@peaceroad/markdown-it-renderer-fence 0.7.0 → 0.9.0

package/theme/line-number.css

@@ -0,0 +1,64 @@
+/*! Renderer Fence line-number layout | MIT License */
+
+:root {
+  --line-number-width: 2em;
+  --line-number-gap: 0.5em;
+  --line-number-rule-gap: 0.25em;
+  --line-number-color: var(--rf-line-number-fg, #666);
+  --line-number-rule-color: var(--rf-line-number-rule, #ccc);
+}
+
+pre :is(code, samp)[data-pre-start] .pre-line {
+  display: block;
+  position: relative;
+  padding-inline-start: calc(var(--line-number-width) + var(--line-number-rule-gap) + var(--line-number-gap));
+  background-image: linear-gradient(var(--line-number-rule-color), var(--line-number-rule-color));
+  background-repeat: no-repeat;
+  background-size: 1px 100%;
+  background-position: calc(var(--line-number-width) + var(--line-number-rule-gap)) 0;
+}
+
+pre :is(code, samp)[data-pre-start] {
+  white-space: normal;
+}
+
+pre:not([data-pre-wrap]) :is(code, samp)[data-pre-start] .pre-line {
+  white-space: pre;
+}
+
+pre[data-pre-wrap] :is(code, samp)[data-pre-start] .pre-line {
+  white-space: break-spaces;
+  overflow-wrap: anywhere;
+}
+
+pre :is(code, samp)[data-pre-start] .pre-line::before {
+  content: counter(pre-line-number);
+  position: absolute;
+  inset-inline-start: 0;
+  top: 0;
+  width: var(--line-number-width);
+  padding-inline-end: var(--line-number-rule-gap);
+  color: var(--line-number-color);
+  text-align: right;
+}
+
+pre :is(code, samp)[data-pre-start] .pre-line[data-pre-line-label]::before {
+  content: attr(data-pre-line-label);
+}
+
+pre :is(code, samp)[data-pre-start] .pre-line[data-pre-line-label-bold]::before {
+  font-weight: bold;
+}
+
+pre :is(code, samp)[data-pre-start] .pre-line::after {
+  content: "";
+  counter-increment: pre-line-number;
+}
+
+pre :is(code, samp)[data-pre-start] .pre-line.pre-line-no-number::before {
+  content: "";
+}
+
+pre :is(code, samp)[data-pre-start] .pre-line.pre-line-no-number::after {
+  counter-increment: none;
+}

package/theme/rf-basic/README.md

@@ -0,0 +1,117 @@
+# rf-basic Theme
+
+`rf-basic` is the optional first-party color preset for `@peaceroad/markdown-it-renderer-fence`.
+It is a mode/provider-aware theme package: import only the CSS and JavaScript helper that matches the renderer mode you actually run.
+
+## Markup mode
+
+Shiki markup mode uses the JavaScript Shiki theme object plus the shared block styling:
+
+```js
+import { rfBasicShikiTheme } from '@peaceroad/markdown-it-renderer-fence/theme/rf-basic'
+```
+
+```css
+@import "@peaceroad/markdown-it-renderer-fence/theme/rf-basic/base.css";
+@import "@peaceroad/markdown-it-renderer-fence/theme/rf-basic/markup/shiki.css";
+```
+
+highlight.js markup mode uses the same base plus highlight.js class rules:
+
+```css
+@import "@peaceroad/markdown-it-renderer-fence/theme/rf-basic/base.css";
+@import "@peaceroad/markdown-it-renderer-fence/theme/rf-basic/markup/highlightjs.css";
+```
+
+## Custom Highlight API mode
+
+Shiki API mode has two distinct profiles. The recommended CSS-managed role profile uses the dedicated helper and `::highlight(hl-shiki-role-*)` CSS:
+
+```js
+import { createRfBasicShikiRoleCustomHighlightOptions } from '@peaceroad/markdown-it-renderer-fence/theme/rf-basic'
+
+const customHighlight = createRfBasicShikiRoleCustomHighlightOptions({ highlighter })
+```
+
+```css
+@import "@peaceroad/markdown-it-renderer-fence/theme/rf-basic/base.css";
+@import "@peaceroad/markdown-it-renderer-fence/theme/rf-basic/api/shiki.css";
+```
+
+The generic `createRfBasicShikiCustomHighlightOptions()` helper keeps its `semantic` + embedded `scopeStyles` defaults for callers that want provider-owned payload styles. That profile needs `base.css` to define the `--rf-*` variables, but it does not depend on the role-only `api/shiki.css` selectors.
+
+highlight.js API mode uses the highlight.js provider helper and API scope CSS:
+
+```js
+import { createRfBasicHighlightjsCustomHighlightOptions } from '@peaceroad/markdown-it-renderer-fence/theme/rf-basic'
+```
+
+```css
+@import "@peaceroad/markdown-it-renderer-fence/theme/rf-basic/base.css";
+@import "@peaceroad/markdown-it-renderer-fence/theme/rf-basic/api/highlightjs.css";
+```
+
+## Complete preset
+
+For demos or pages that intentionally compare providers, the complete color preset is available:
+
+```css
+@import "@peaceroad/markdown-it-renderer-fence/theme/rf-basic.css";
+```
+
+It imports base layout, line-number/line-notes layout, Shiki role-mode API scopes, highlight.js API scopes, Shiki markup correction, and highlight.js markup classes.
+
+The base palette follows `prefers-color-scheme`, but applies the CSS `color-scheme` hint only to each `pre` surface. Importing the theme does not change UA colors for the whole document. Sites with an explicit theme can override `--rf-code-color-scheme` and `--rf-samp-color-scheme` together with the palette variables.
+
+## Line feature customization
+
+The renderer owns line-number markup, counter values, skip/set behavior, and line wrappers. The structural CSS owns presentation, so an application theme can change the layout without changing renderer options:
+
+```css
+@import "@peaceroad/markdown-it-renderer-fence/theme/rf-basic.css";
+
+.docs-theme {
+  --line-number-width: 3ch;
+  --line-number-gap: 0.75ch;
+  --line-number-rule-gap: 0.5ch;
+  --line-number-color: oklch(48% 0.03 250);
+  --line-number-rule-color: oklch(82% 0.02 250);
+}
+```
+
+The variables are inherited, so they can be set globally or on a container that owns the rendered Markdown. The preset gives `samp` an inverted terminal palette on `pre:has(> samp)`; override the same variables on that `pre` selector as well when terminal line numbers need a different application-specific treatment.
+
+## Color design
+
+The palette is neutral-first: code backgrounds stay close to monochrome, syntax roles keep high contrast, and `samp` blocks invert the code palette so terminal output remains visually distinct in both light and dark color schemes.
+
+Role directions:
+
+- keyword: red/coral
+- string: blue
+- number/literal: blue-violet
+- title/type: purple/magenta
+- variable: amber/brown
+- tag: green/teal
+- punctuation/meta: neutral
+
+The theme favors practical readability and cross-provider consistency over exact parity with any one editor theme.
+
+## File roles
+
+- `index.css`: complete color preset for demos and mixed-provider pages.
+- `base.css`: public base import; it loads shared renderer-fence block/layout CSS plus package-owned line-number and line-notes layout.
+- `markup/shiki.css`: Shiki markup correction for `samp` terminal surfaces.
+- `markup/highlightjs.css`: highlight.js markup class rules.
+- `api/highlightjs.css`: Custom Highlight API rules for highlight.js provider ranges.
+- `api/shiki.css`: Custom Highlight API rules for Shiki role-mode ranges.
+- `index.js`: Shiki theme object and provider option helpers.
+
+The private `theme/_shared/rf-core.css` file is an internal source file used to avoid
+duplicating block/layout CSS across themes. Import this theme's public `base.css` instead.
+The theme-neutral structural files are also public as `theme/line-number.css` and `theme/line-notes.css` for consumers that do not want a preset palette.
+The below-block line-note label can be localized without changing renderer HTML by overriding `--line-note-label-prefix` and `--line-note-label-suffix`.
+
+## License
+
+MIT, same as the package.

package/theme/rf-basic/api/highlightjs.css

@@ -0,0 +1,71 @@
+/*! rf-basic highlightjs API scopes | MIT License */
+
+::highlight(hl-hljs-language-javascript),
+::highlight(hl-hljs-subst) {
+  color: var(--rf-code-fg);
+}
+
+::highlight(hl-hljs-keyword),
+::highlight(hl-hljs-built-in),
+::highlight(hl-hljs-built_in) {
+  color: var(--rf-syntax-keyword);
+}
+
+::highlight(hl-hljs-string) {
+  color: var(--rf-syntax-string);
+}
+
+::highlight(hl-hljs-number) {
+  color: var(--rf-syntax-number);
+}
+
+::highlight(hl-hljs-comment) {
+  color: var(--rf-syntax-comment);
+}
+
+::highlight(hl-hljs-literal) {
+  color: var(--rf-syntax-literal);
+}
+
+::highlight(hl-hljs-type) {
+  color: var(--rf-syntax-type);
+}
+
+::highlight(hl-hljs-title),
+::highlight(hl-hljs-title-function),
+::highlight(hl-hljs-title-class),
+::highlight(hl-hljs-title-function-invoke),
+::highlight(hl-hljs-function),
+::highlight(hl-hljs-class) {
+  color: var(--rf-syntax-title);
+}
+
+::highlight(hl-hljs-variable),
+::highlight(hl-hljs-variable-constant),
+::highlight(hl-hljs-variable-language),
+::highlight(hl-hljs-params),
+::highlight(hl-hljs-property) {
+  color: var(--rf-syntax-variable);
+}
+
+::highlight(hl-hljs-tag),
+::highlight(hl-hljs-name),
+::highlight(hl-hljs-selector-pseudo) {
+  color: var(--rf-syntax-tag);
+}
+
+::highlight(hl-hljs-attr),
+::highlight(hl-hljs-attribute),
+::highlight(hl-hljs-selector-class) {
+  color: var(--rf-syntax-attribute);
+}
+
+::highlight(hl-hljs-punctuation),
+::highlight(hl-hljs-meta),
+::highlight(hl-hljs-operator) {
+  color: var(--rf-syntax-punctuation);
+}
+
+::highlight(hl-hljs-symbol) {
+  color: var(--rf-syntax-literal);
+}

package/theme/rf-basic/api/shiki.css

@@ -0,0 +1,67 @@
+/*! rf-basic Shiki role-mode API scopes | MIT License */
+
+::highlight(hl-shiki-role-text) {
+  color: var(--rf-code-fg);
+}
+
+::highlight(hl-shiki-role-keyword),
+::highlight(hl-shiki-role-type-primitive) {
+  color: var(--rf-syntax-keyword);
+}
+
+::highlight(hl-shiki-role-string),
+::highlight(hl-shiki-role-string-unquoted) {
+  color: var(--rf-syntax-string);
+}
+
+::highlight(hl-shiki-role-number) {
+  color: var(--rf-syntax-number);
+}
+
+::highlight(hl-shiki-role-comment),
+::highlight(hl-shiki-role-meta-shebang) {
+  color: var(--rf-syntax-comment);
+}
+
+::highlight(hl-shiki-role-literal),
+::highlight(hl-shiki-role-variable-this) {
+  color: var(--rf-syntax-literal);
+}
+
+::highlight(hl-shiki-role-type),
+::highlight(hl-shiki-role-type-name),
+::highlight(hl-shiki-role-title-class),
+::highlight(hl-shiki-role-namespace) {
+  color: var(--rf-syntax-type);
+}
+
+::highlight(hl-shiki-role-title-function),
+::highlight(hl-shiki-role-title-function-builtin) {
+  color: var(--rf-syntax-title);
+}
+
+::highlight(hl-shiki-role-variable),
+::highlight(hl-shiki-role-variable-const),
+::highlight(hl-shiki-role-variable-member),
+::highlight(hl-shiki-role-variable-plain),
+::highlight(hl-shiki-role-variable-property),
+::highlight(hl-shiki-role-variable-parameter) {
+  color: var(--rf-syntax-variable);
+}
+
+::highlight(hl-shiki-role-tag) {
+  color: var(--rf-syntax-tag);
+}
+
+::highlight(hl-shiki-role-attribute) {
+  color: var(--rf-syntax-attribute);
+}
+
+::highlight(hl-shiki-role-punctuation),
+::highlight(hl-shiki-role-tag-delimiter) {
+  color: var(--rf-syntax-punctuation);
+}
+
+::highlight(hl-shiki-role-meta) {
+  color: var(--rf-code-fg);
+}

package/theme/rf-basic/base.css

@@ -0,0 +1,5 @@
+/*! rf-basic base | MIT License */
+
+@import "../_shared/rf-core.css";
+@import "../line-number.css";
+@import "../line-notes.css";

package/theme/rf-basic/index.css

@@ -0,0 +1,7 @@
+/*! rf-basic theme | MIT License */
+
+@import "./base.css";
+@import "./api/shiki.css";
+@import "./api/highlightjs.css";
+@import "./markup/shiki.css";
+@import "./markup/highlightjs.css";

package/theme/rf-basic/index.js

@@ -0,0 +1,164 @@
+import { rendererFenceShikiThemeScopeGroups } from '../../src/custom-highlight/shiki-theme-role.js'
+
+const rfBasicThemeName = 'rf-basic'
+const rfBasicShikiThemeName = rfBasicThemeName
+
+const rfBasicSyntaxCssVars = Object.freeze({
+  background: 'var(--rf-code-bg)',
+  text: 'var(--rf-code-fg)',
+  keyword: 'var(--rf-syntax-keyword)',
+  string: 'var(--rf-syntax-string)',
+  number: 'var(--rf-syntax-number)',
+  comment: 'var(--rf-syntax-comment)',
+  type: 'var(--rf-syntax-type)',
+  title: 'var(--rf-syntax-title)',
+  variable: 'var(--rf-syntax-variable)',
+  literal: 'var(--rf-syntax-literal)',
+  tag: 'var(--rf-syntax-tag)',
+  attribute: 'var(--rf-syntax-attribute)',
+  punctuation: 'var(--rf-syntax-punctuation)',
+  meta: 'var(--rf-syntax-meta)',
+
+  // Backward-friendly role aliases for highlighter APIs that use these names.
+  constant: 'var(--rf-syntax-literal)',
+  builtIn: 'var(--rf-syntax-variable)',
+})
+
+const mergePalette = (palette) => palette
+  ? Object.assign({}, rfBasicSyntaxCssVars, palette)
+  : rfBasicSyntaxCssVars
+
+const createTokenColor = (scope, foreground) => ({
+  scope: Array.isArray(scope) ? scope.slice() : scope,
+  settings: { foreground },
+})
+
+const createRfBasicShikiTheme = ({
+  name = rfBasicShikiThemeName,
+  palette = null,
+} = {}) => {
+  const p = mergePalette(palette)
+  return {
+    name,
+    type: 'light',
+    colors: {
+      'editor.foreground': p.text,
+      'editor.background': p.background,
+    },
+    tokenColors: [
+      { settings: { foreground: p.text } },
+      createTokenColor(rendererFenceShikiThemeScopeGroups.comment, p.comment),
+      createTokenColor(rendererFenceShikiThemeScopeGroups.string, p.string),
+      createTokenColor(rendererFenceShikiThemeScopeGroups.number, p.number),
+      createTokenColor(rendererFenceShikiThemeScopeGroups.literal, p.literal),
+      createTokenColor(rendererFenceShikiThemeScopeGroups.keyword, p.keyword),
+      createTokenColor(rendererFenceShikiThemeScopeGroups.punctuation, p.punctuation),
+      createTokenColor(rendererFenceShikiThemeScopeGroups.title, p.title),
+      createTokenColor(rendererFenceShikiThemeScopeGroups.type, p.type),
+      createTokenColor(rendererFenceShikiThemeScopeGroups.variable, p.variable),
+      createTokenColor(rendererFenceShikiThemeScopeGroups.tag, p.tag),
+      createTokenColor(rendererFenceShikiThemeScopeGroups.attribute, p.attribute),
+    ],
+  }
+}
+
+const rfBasicShikiTheme = createRfBasicShikiTheme()
+
+const createRfBasicShikiRoleScopeColorVars = (palette = null) => {
+  const p = mergePalette(palette)
+  return {
+    'hl-shiki-role-keyword': p.keyword,
+    'hl-shiki-role-type-primitive': p.keyword,
+    'hl-shiki-role-number': p.number,
+    'hl-shiki-role-string': p.string,
+    'hl-shiki-role-string-unquoted': p.string,
+    'hl-shiki-role-variable': p.variable,
+    'hl-shiki-role-variable-this': p.literal,
+    'hl-shiki-role-variable-const': p.variable,
+    'hl-shiki-role-variable-member': p.variable,
+    'hl-shiki-role-variable-plain': p.variable,
+    'hl-shiki-role-variable-property': p.variable,
+    'hl-shiki-role-variable-parameter': p.variable,
+    'hl-shiki-role-title-function': p.title,
+    'hl-shiki-role-title-function-builtin': p.title,
+    'hl-shiki-role-title-class': p.type,
+    'hl-shiki-role-namespace': p.type,
+    'hl-shiki-role-literal': p.literal,
+    'hl-shiki-role-comment': p.comment,
+    'hl-shiki-role-meta-shebang': p.comment,
+    'hl-shiki-role-punctuation': p.punctuation,
+    'hl-shiki-role-meta': p.text,
+    'hl-shiki-role-type': p.type,
+    'hl-shiki-role-type-name': p.type,
+    'hl-shiki-role-tag': p.tag,
+    'hl-shiki-role-tag-delimiter': p.punctuation,
+    'hl-shiki-role-attribute': p.attribute,
+    'hl-shiki-role-text': p.text,
+  }
+}
+
+const rfBasicShikiRoleScopeColorVars = Object.freeze(
+  createRfBasicShikiRoleScopeColorVars(),
+)
+
+const createHighlightjsHighlightFn = (hljs) => {
+  if (!hljs || typeof hljs.highlight !== 'function') return null
+  return (code, lang) => {
+    const target = (lang && typeof hljs.getLanguage === 'function' && hljs.getLanguage(lang))
+      ? lang
+      : 'plaintext'
+    return hljs.highlight(code, { language: target })
+  }
+}
+
+const createRfBasicShikiCustomHighlightOptions = ({
+  highlighter,
+  theme = rfBasicShikiThemeName,
+  shikiScopeMode = 'semantic',
+  includeScopeStyles = shikiScopeMode === 'role' ? false : true,
+  ...overrides
+} = {}) => ({
+  ...overrides,
+  provider: 'shiki',
+  highlighter,
+  theme,
+  shikiScopeMode,
+  includeScopeStyles,
+})
+
+const createRfBasicShikiRoleCustomHighlightOptions = (options = {}) => {
+  return createRfBasicShikiCustomHighlightOptions({
+    ...options,
+    shikiScopeMode: 'role',
+    includeScopeStyles: false,
+  })
+}
+
+const createRfBasicHighlightjsCustomHighlightOptions = ({
+  hljs,
+  hljsHighlight,
+  highlight,
+  includeScopeStyles = false,
+  ...overrides
+} = {}) => ({
+  ...overrides,
+  provider: 'hljs',
+  includeScopeStyles,
+  hljsHighlight: hljsHighlight || highlight || createHighlightjsHighlightFn(hljs),
+})
+
+const rfBasicShikiThemeScopeGroups = rendererFenceShikiThemeScopeGroups
+
+export {
+  createRfBasicHighlightjsCustomHighlightOptions,
+  createRfBasicShikiCustomHighlightOptions,
+  createRfBasicShikiRoleCustomHighlightOptions,
+  createRfBasicShikiRoleScopeColorVars,
+  createRfBasicShikiTheme,
+  rfBasicShikiRoleScopeColorVars,
+  rfBasicShikiTheme,
+  rfBasicShikiThemeName,
+  rfBasicShikiThemeScopeGroups,
+  rfBasicSyntaxCssVars,
+  rfBasicThemeName,
+}

package/theme/rf-basic/markup/highlightjs.css

@@ -0,0 +1,77 @@
+/*! rf-basic highlight.js markup scopes | MIT License */
+
+.hljs-keyword,
+.hljs-built_in {
+  color: var(--rf-syntax-keyword);
+}
+
+.hljs-string {
+  color: var(--rf-syntax-string);
+}
+
+.hljs-number {
+  color: var(--rf-syntax-number);
+}
+
+.hljs-comment {
+  color: var(--rf-syntax-comment);
+}
+
+.hljs-literal,
+.hljs-symbol {
+  color: var(--rf-syntax-literal);
+}
+
+.hljs-type {
+  color: var(--rf-syntax-type);
+}
+
+.hljs-title,
+.hljs-title.function_,
+.hljs-title.class_,
+.hljs-function,
+.hljs-class {
+  color: var(--rf-syntax-title);
+}
+
+.hljs-variable,
+.hljs-variable.constant_,
+.hljs-params,
+.hljs-property {
+  color: var(--rf-syntax-variable);
+}
+
+.hljs-tag,
+.hljs-name {
+  color: var(--rf-syntax-tag);
+}
+
+.hljs-attr,
+.hljs-attribute,
+.hljs-selector-class {
+  color: var(--rf-syntax-attribute);
+}
+
+.hljs-punctuation,
+.hljs-meta,
+.hljs-operator {
+  color: var(--rf-syntax-punctuation);
+}
+
+.hljs-meta.prompt_ {
+  color: var(--rf-code-muted);
+}
+
+.hljs-subst,
+.language-javascript {
+  color: var(--rf-code-fg);
+}
+
+pre:has(> samp) .hljs-meta.prompt_ {
+  color: var(--rf-samp-prompt);
+}
+
+pre:has(> samp) .hljs-subst,
+pre:has(> samp) .language-javascript {
+  color: var(--rf-samp-fg);
+}

package/theme/rf-basic/markup/shiki.css

@@ -0,0 +1,11 @@
+/*! rf-basic Shiki markup scopes | MIT License */
+
+/*
+ * Shiki writes background/color as inline styles on `<pre>`. When renderer-fence
+ * outputs a Shiki-highlighted `<samp>`, re-apply the rf-basic terminal surface
+ * so the samp syntax variables are not rendered on the normal code background.
+ */
+pre.shiki:has(> samp) {
+  color: var(--rf-samp-fg) !important;
+  background-color: var(--rf-samp-bg) !important;
+}

package/theme/rf-monochrome/README.md

@@ -0,0 +1,84 @@
+# rf-monochrome Theme
+
+`rf-monochrome` is a one-color markup-mode preset for `@peaceroad/markdown-it-renderer-fence`.
+It uses the shared renderer-fence code surface plus bold/italic cues instead of syntax colors. It is intended for print, photocopy-safe output, or documents that must keep code in a single text color.
+
+## Scope
+
+This is intentionally a markup-mode theme. Browser Custom Highlight API rules cannot reliably apply `font-weight` or `font-style`, so API-mode monochrome would mostly be `color: currentColor` and would not provide the intended structure cues.
+
+## highlight.js markup
+
+```css
+@import "@peaceroad/markdown-it-renderer-fence/theme/rf-monochrome.css";
+```
+
+or, if you want split imports:
+
+```css
+@import "@peaceroad/markdown-it-renderer-fence/theme/rf-monochrome/base.css";
+@import "@peaceroad/markdown-it-renderer-fence/theme/rf-monochrome/markup/highlightjs.css";
+```
+
+## Shiki markup
+
+Use the Shiki theme object plus base CSS:
+
+```js
+import { rfMonochromeShikiTheme } from '@peaceroad/markdown-it-renderer-fence/theme/rf-monochrome'
+```
+
+```css
+@import "@peaceroad/markdown-it-renderer-fence/theme/rf-monochrome/base.css";
+@import "@peaceroad/markdown-it-renderer-fence/theme/rf-monochrome/markup/shiki.css";
+```
+
+`markup/shiki.css` maps Shiki's inline `currentColor` / transparent surface back to the shared code and `samp` surfaces; the main Shiki token styling comes from `rfMonochromeShikiTheme`.
+
+## Design notes
+
+- No underline by default; underline makes code harder to scan and can look like links.
+- Keywords, type/class/tag-like structural tokens use bold.
+- Comments use italic by default; metadata stays normal so it does not become visually indistinguishable from prose comments.
+- Doc tags and ordinary function/method titles stay normal weight so they do not compete with structural keywords. Shiki may classify constructor-like tokens as `storage.type`; keeping those bold avoids a broader override that would also neutralize `const` / `let` / `var` declarations inside method bodies.
+- Terminal-like `<samp>` blocks suppress token-level bold/italic so prompts, commands, and output do not look inconsistently emphasized.
+
+Italic comments are only a default. When the rendered code inherits `lang="ja"`, `lang="zh"`, or `lang="ko"` from the document or a nearer container, the preset automatically renders comment tokens upright. CSS `:lang()` matching also covers subtags such as `ja-JP`.
+
+You can still disable comment italics explicitly for another language or a specific container:
+
+```css
+/* Global or scoped to the container that owns rendered Markdown. */
+.docs-theme {
+  --rf-monochrome-comment-font-style: normal;
+}
+```
+
+For Shiki markup output, the preset CSS overrides the default inline italic style for inherited CJK languages. Create the theme with `createRfMonochromeShikiTheme({ commentFontStyle: '' })` when comments should remain upright regardless of language.
+
+Typography defaults live on `:root` and inherit into code blocks, so an application can override them globally or on a Markdown container. Structural emphasis can be tuned without rewriting the theme. highlight.js consumers can override `--rf-monochrome-strong-font-weight` (default `700`) and `--rf-monochrome-normal-font-weight` (default `400`). Shiki accepts `createRfMonochromeShikiTheme({ structuralFontStyle: '' })` when an application wants a completely regular-weight one-color rendering. Shiki's TextMate `fontStyle` supports semantic `bold` rather than an arbitrary numeric weight, so exact `600`/`650` parity remains CSS/highlight.js-specific.
+
+Metadata is normal by default. Sites that prefer italic preprocessor or metadata tokens can opt in:
+
+```css
+.docs-theme {
+  --rf-monochrome-meta-font-style: italic;
+}
+```
+
+## File roles
+
+- `index.css`: complete monochrome markup preset.
+- `base.css`: public base import; it loads shared renderer-fence block/layout CSS plus package-owned line-number and line-notes layout.
+- `markup/highlightjs.css`: highlight.js monochrome class rules.
+- `markup/shiki.css`: Shiki markup `samp` override.
+- `index.js`: Shiki monochrome theme object and factory.
+
+The private `theme/_shared/rf-core.css` file is an internal source file used to avoid
+duplicating block/layout CSS across themes. Import this theme's public `base.css` instead.
+The structural layouts are also available without a palette as `theme/line-number.css` and `theme/line-notes.css`.
+The below-block line-note label is customizable through `--line-note-label-prefix` and `--line-note-label-suffix`.
+
+## License
+
+MIT, same as the package.

package/theme/rf-monochrome/base.css

@@ -0,0 +1,5 @@
+/*! rf-monochrome base | MIT License */
+
+@import "../_shared/rf-core.css";
+@import "../line-number.css";
+@import "../line-notes.css";

package/theme/rf-monochrome/index.css

@@ -0,0 +1,5 @@
+/*! rf-monochrome theme | MIT License */
+
+@import "./base.css";
+@import "./markup/highlightjs.css";
+@import "./markup/shiki.css";