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

package/theme/rf-basic/README.md

@@ -1,6 +1,6 @@
 # rf-basic Theme
 
-`rf-basic` is the default color preset for `@peaceroad/markdown-it-renderer-fence`.
+`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
@@ -25,10 +25,12 @@ highlight.js markup mode uses the same base plus highlight.js class rules:
 
 ## Custom Highlight API mode
 
-Shiki API mode uses the provider helper and `::highlight(hl-shiki-role-*)` CSS:
+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 { createRfBasicShikiCustomHighlightOptions } from '@peaceroad/markdown-it-renderer-fence/theme/rf-basic'
+import { createRfBasicShikiRoleCustomHighlightOptions } from '@peaceroad/markdown-it-renderer-fence/theme/rf-basic'
+
+const customHighlight = createRfBasicShikiRoleCustomHighlightOptions({ highlighter })
 ```
 
 ```css
@@ -36,6 +38,8 @@ import { createRfBasicShikiCustomHighlightOptions } from '@peaceroad/markdown-it
 @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
@@ -55,7 +59,27 @@ For demos or pages that intentionally compare providers, the complete color pres
 @import "@peaceroad/markdown-it-renderer-fence/theme/rf-basic.css";
 ```
 
-It imports base layout, Shiki API scopes, highlight.js API scopes, and highlight.js markup classes.
+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
 
@@ -76,7 +100,7 @@ The theme favors practical readability and cross-provider consistency over exact
 ## 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.
+- `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.
@@ -85,6 +109,8 @@ The theme favors practical readability and cross-provider consistency over exact
 
 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
 

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

@@ -1,4 +1,4 @@
-/*! rf-basic Shiki API scopes | MIT License */
+/*! rf-basic Shiki role-mode API scopes | MIT License */
 
 ::highlight(hl-shiki-role-text) {
   color: var(--rf-code-fg);

package/theme/rf-basic/base.css

@@ -1,3 +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.js

@@ -126,6 +126,14 @@ const createRfBasicShikiCustomHighlightOptions = ({
   includeScopeStyles,
 })
 
+const createRfBasicShikiRoleCustomHighlightOptions = (options = {}) => {
+  return createRfBasicShikiCustomHighlightOptions({
+    ...options,
+    shikiScopeMode: 'role',
+    includeScopeStyles: false,
+  })
+}
+
 const createRfBasicHighlightjsCustomHighlightOptions = ({
   hljs,
   hljsHighlight,
@@ -144,6 +152,7 @@ const rfBasicShikiThemeScopeGroups = rendererFenceShikiThemeScopeGroups
 export {
   createRfBasicHighlightjsCustomHighlightOptions,
   createRfBasicShikiCustomHighlightOptions,
+  createRfBasicShikiRoleCustomHighlightOptions,
   createRfBasicShikiRoleScopeColorVars,
   createRfBasicShikiTheme,
   rfBasicShikiRoleScopeColorVars,

package/theme/rf-monochrome/README.md

@@ -39,32 +39,45 @@ import { rfMonochromeShikiTheme } from '@peaceroad/markdown-it-renderer-fence/th
 
 - 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 and meta-like regions use italic by default.
-- Doc tags and method-like titles stay normal weight so they do not compete with structural keywords.
+- 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. CJK comments may be easier to read without italics:
+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
-pre code,
-pre samp,
-.hljs {
+/* Global or scoped to the container that owns rendered Markdown. */
+.docs-theme {
   --rf-monochrome-comment-font-style: normal;
 }
 ```
 
-For Shiki markup output, create the theme with `createRfMonochromeShikiTheme({ commentFontStyle: '' })`.
+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.
+- `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
 

package/theme/rf-monochrome/base.css

@@ -1,3 +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.js

@@ -9,8 +9,6 @@ const createTokenFontStyle = (scope, foreground, fontStyle) => ({
 })
 
 const rfMonochromeNormalScopeOverrides = Object.freeze([
-  'meta.method.declaration.js storage.type.js',
-  'meta.method.declaration.ts storage.type.ts',
   'keyword.operator.or.regexp',
   'keyword.operator.quantifier.regexp',
 ])
@@ -35,6 +33,7 @@ const createRfMonochromeShikiTheme = ({
   foreground = 'currentColor',
   background = 'transparent',
   commentFontStyle = 'italic',
+  structuralFontStyle = 'bold',
 } = {}) => ({
   name,
   type: 'light',
@@ -45,9 +44,9 @@ const createRfMonochromeShikiTheme = ({
   tokenColors: [
     { settings: { foreground, background } },
     createTokenFontStyle(rendererFenceShikiThemeScopeGroups.comment, foreground, commentFontStyle),
-    createTokenFontStyle(rendererFenceShikiThemeScopeGroups.keyword, foreground, 'bold'),
-    createTokenFontStyle(rendererFenceShikiThemeScopeGroups.type, foreground, 'bold'),
-    createTokenFontStyle(rendererFenceShikiThemeScopeGroups.tag, foreground, 'bold'),
+    createTokenFontStyle(rendererFenceShikiThemeScopeGroups.keyword, foreground, structuralFontStyle),
+    createTokenFontStyle(rendererFenceShikiThemeScopeGroups.type, foreground, structuralFontStyle),
+    createTokenFontStyle(rendererFenceShikiThemeScopeGroups.tag, foreground, structuralFontStyle),
     createTokenFontStyle(rendererFenceShikiThemeScopeGroups.title, foreground, ''),
     createTokenFontStyle(rendererFenceShikiThemeScopeGroups.string, foreground, ''),
     createTokenFontStyle(rendererFenceShikiThemeScopeGroups.number, foreground, ''),

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

@@ -1,5 +1,14 @@
 /*! rf-monochrome highlightjs markup theme | MIT License */
 
+:root {
+  --rf-monochrome-strong-font-weight: 700;
+  --rf-monochrome-normal-font-weight: 400;
+  --rf-monochrome-comment-font-style: italic;
+  --rf-monochrome-meta-font-style: normal;
+  --rf-monochrome-meta-font-weight: var(--rf-monochrome-normal-font-weight);
+  --rf-monochrome-doctag-font-weight: var(--rf-monochrome-normal-font-weight);
+}
+
 pre {
   --rf-monochrome-fg: var(--rf-code-fg);
   --rf-monochrome-bg: var(--rf-code-bg);
@@ -12,10 +21,6 @@ pre samp,
 .hljs {
   color: var(--rf-monochrome-fg, var(--rf-code-fg));
   background: transparent;
-  --rf-monochrome-comment-font-style: italic;
-  --rf-monochrome-meta-font-style: italic;
-  --rf-monochrome-meta-font-weight: 400;
-  --rf-monochrome-doctag-font-weight: 400;
 }
 
 /*
@@ -39,7 +44,7 @@ pre:has(> samp) {
 .hljs-type,
 .hljs-strong {
   color: var(--rf-monochrome-fg, var(--rf-code-fg));
-  font-weight: 700;
+  font-weight: var(--rf-monochrome-strong-font-weight, 700);
 }
 
 .hljs-title,
@@ -48,7 +53,7 @@ pre:has(> samp) {
 .hljs-function,
 .hljs-class {
   color: var(--rf-monochrome-fg, var(--rf-code-fg));
-  font-weight: 400;
+  font-weight: var(--rf-monochrome-normal-font-weight, 400);
 }
 
 .hljs-comment,
@@ -63,10 +68,21 @@ pre:has(> samp) {
   font-style: var(--rf-monochrome-comment-font-style, italic);
 }
 
+/*
+ * CJK fonts rarely provide a true italic face. Let the inherited document or
+ * container language disable synthetic italics for comments automatically.
+ * `:lang(ja)` also matches language tags such as `ja-JP`.
+ */
+.hljs-comment:lang(ja),
+.hljs-comment:lang(zh),
+.hljs-comment:lang(ko) {
+  --rf-monochrome-comment-font-style: normal;
+}
+
 .hljs-meta,
 .hljs-doctag {
   color: var(--rf-monochrome-fg, var(--rf-code-fg));
-  font-style: var(--rf-monochrome-meta-font-style, italic);
+  font-style: var(--rf-monochrome-meta-font-style, normal);
   font-weight: var(--rf-monochrome-meta-font-weight, 400);
 }
 
@@ -78,7 +94,7 @@ pre:has(> samp) {
 .hljs-comment .hljs-type,
 .hljs-comment .hljs-variable {
   font-style: inherit;
-  font-weight: 400;
+  font-weight: var(--rf-monochrome-normal-font-weight, 400);
 }
 
 /*
@@ -114,7 +130,7 @@ pre:has(> samp) .hljs-meta.prompt_ {
 .hljs-deletion {
   color: var(--rf-monochrome-fg, var(--rf-code-fg));
   font-style: normal;
-  font-weight: 400;
+  font-weight: var(--rf-monochrome-normal-font-weight, 400);
 }
 
 .hljs-addition,
@@ -130,5 +146,5 @@ pre:has(> samp) .hljs-meta.prompt_ {
 pre:has(> samp) [class^="hljs-"],
 pre:has(> samp) [class*=" hljs-"] {
   font-style: normal;
-  font-weight: 400;
+  font-weight: var(--rf-monochrome-normal-font-weight, 400);
 }

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

@@ -23,5 +23,16 @@ pre:has(> samp).rf-monochrome {
  */
 pre:has(> samp).rf-monochrome span[style] {
   font-style: normal !important;
-  font-weight: 400 !important;
+  font-weight: var(--rf-monochrome-normal-font-weight, 400) !important;
+}
+
+/*
+ * The rf-monochrome Shiki theme emits italic only for comment scopes by
+ * default. Normalize those inline styles when the inherited language is CJK;
+ * `!important` is required because Shiki writes font-style inline.
+ */
+pre.rf-monochrome span[style*="font-style"][style*="italic"]:lang(ja),
+pre.rf-monochrome span[style*="font-style"][style*="italic"]:lang(zh),
+pre.rf-monochrome span[style*="font-style"][style*="italic"]:lang(ko) {
+  font-style: normal !important;
 }