diff --git a/docs/guide/pages-routing/markdown.md b/docs/guide/pages-routing/markdown.md index de78078bc..4957130da 100644 --- a/docs/guide/pages-routing/markdown.md +++ b/docs/guide/pages-routing/markdown.md @@ -289,7 +289,7 @@ Wrap your markdown content in a `.void-md` element to scope the styles: The theme covers: - **Prose:** headings, paragraphs, lists, blockquotes, tables, inline code, links, horizontal rules, task lists, ``, ``, definition lists, and footnotes. Dark mode works through `prefers-color-scheme` and the `data-theme` attribute. -- **Code blocks:** Shiki dual-theme highlighting with CSS-driven switching and zero JS. +- **Code blocks:** dual-theme syntax highlighting with CSS-driven switching and zero JS. - **Containers:** styles for `:::tip`, `:::warning`, `:::danger`, `:::info`, and `:::details`. - **GitHub alerts:** support for `> [!NOTE]`, `> [!TIP]`, `> [!WARNING]`, and similar syntax. @@ -371,7 +371,7 @@ Custom titles work too: `::: tip Pro Tip`. ### Syntax Highlighting -Code blocks use [Shiki](https://shiki.style) with `github-light` and `github-dark` themes by default. +Code blocks are highlighted with the `github-light` and `github-dark` themes by default. A code block in a language that is not supported renders as plain text. ### Line Highlighting @@ -452,19 +452,19 @@ Headings include permalink anchors. Use `[[toc]]` for a table of contents. Image import { voidMarkdown } from '@void/md/plugin'; voidMarkdown({ - shiki: { - themes: { light: 'github-light', dark: 'github-dark' }, - }, + themes: { light: 'github-light', dark: 'github-dark' }, copyLabel: 'Copy Code', }); ``` -| Option | Type | Default | Description | -| -------------- | -------------------------------- | ------------------------------------------------ | ----------------------------------------------------- | -| `shiki.themes` | `{ light: string; dark: string}` | `{ light: "github-light", dark: "github-dark" }` | Shiki color themes | -| `copyLabel` | `string` | `"Copy Code"` | Tooltip and accessible label for the code copy button | +| Option | Type | Default | Description | +| ----------- | -------------------------------- | ------------------------------------------------ | ----------------------------------------------------------------- | +| `themes` | `{ light: string; dark: string}` | `{ light: "github-light", dark: "github-dark" }` | Code block color themes, such as `pierre-light` and `pierre-dark` | +| `copyLabel` | `string` | `"Copy Code"` | Tooltip and accessible label for the code copy button | -Code block languages load on demand from Shiki's bundled languages. +Code block languages need no configuration. An unknown theme name stops the build with an error. + +The `shiki.themes` option is deprecated. Use `themes`. For a translated site, set `copyLabel` to the label in your site's language, such as `'Copier le code'`. diff --git a/packages/md/package.json b/packages/md/package.json index 332c028d4..7ea849354 100644 --- a/packages/md/package.json +++ b/packages/md/package.json @@ -41,8 +41,7 @@ "typecheck": "tsc --noEmit --rootDir ../.." }, "dependencies": { - "@shikijs/engine-javascript": "catalog:", - "@shikijs/transformers": "catalog:", + "@pierre/highlights": "^0.5.1", "gray-matter": "^4.0.3", "markdown-exit": "catalog:", "markdown-it": "^15.0.3", @@ -52,7 +51,6 @@ "markdown-it-emoji": "^3.1.0", "markdown-it-footnote": "^4.0.0", "pathslash": "catalog:", - "shiki": "catalog:", "tinyglobby": "^0.2.17" }, "devDependencies": { diff --git a/packages/md/src/compile.ts b/packages/md/src/compile.ts index 48653d0c7..f0718f315 100644 --- a/packages/md/src/compile.ts +++ b/packages/md/src/compile.ts @@ -1,17 +1,9 @@ -import { createJavaScriptRegexEngine } from '@shikijs/engine-javascript'; -import { - transformerMetaHighlight, - transformerNotationDiff, - transformerNotationHighlight, - transformerNotationFocus, - transformerNotationErrorLevel, -} from '@shikijs/transformers'; import MarkdownExit from 'markdown-exit'; import type { RuleCore, Token } from 'markdown-exit'; import attrs from 'markdown-it-attrs'; import { full as emoji } from 'markdown-it-emoji'; import footnote from 'markdown-it-footnote'; -import { createHighlighter, bundledLanguages, isSpecialLang, type BundledLanguage } from 'shiki'; +import { createCodeHighlighter } from './highlight.ts'; import { extractHeadings, parseFrontmatter } from './metadata.ts'; import { containerPlugin } from './plugins/containers.ts'; import { gitHubAlertsPlugin } from './plugins/github-alerts.ts'; @@ -39,12 +31,15 @@ export type CompileResult = Readonly<{ export type CompileOptions = Readonly<{ /** Title of the code block copy button. Defaults to `Copy Code`. */ copyLabel?: string; + /** Code block color themes. Defaults to `github-light` and `github-dark`. */ + themes?: { light: string; dark: string }; + /** @deprecated Use `themes`. Removed in the next major version. */ shiki?: { + /** @deprecated Use the top-level `themes` option. Removed in the next major version. */ themes?: { light: string; dark: string }; /** - * @deprecated Has no effect. Code block languages load on demand from - * Shiki's bundled languages. Remove this option. Removed in the next major - * version. + * @deprecated Has no effect. Every supported code block language is + * built in. Remove this option. Removed in the next major version. */ langs?: ReadonlyArray; }; @@ -63,48 +58,20 @@ async function getCompiler(options?: CompileOptions): Promise { async function createCompiler(options?: CompileOptions): Promise { const markdown = new MarkdownExit({ html: true, linkify: true }); - // Shiki highlighting with JS RegExp engine (no WASM) + lazy language loading - const themes = options?.shiki?.themes ?? { - light: 'github-light', - dark: 'github-dark', - }; - const highlighter = await createHighlighter({ - engine: createJavaScriptRegexEngine(), - themes: [themes.light, themes.dark], - langs: [], - }); - const shikiTransformers = [ - transformerMetaHighlight(), - transformerNotationDiff(), - transformerNotationHighlight(), - transformerNotationFocus(), - transformerNotationErrorLevel(), - ]; - markdown.renderer.rules.fence = async (tokens: ReadonlyArray, tokenIndex: number) => { + const highlight = await createCodeHighlighter( + options?.themes ?? options?.shiki?.themes ?? { light: 'github-light', dark: 'github-dark' }, + ); + markdown.renderer.rules.fence = (tokens: ReadonlyArray, tokenIndex: number) => { const token = tokens[tokenIndex]; - const code = token.content; - let lang = token.info ? token.info.split(/\s+/g)[0] : 'text'; - if (!isSpecialLang(lang) && !highlighter.getLoadedLanguages().includes(lang)) { - if (lang in bundledLanguages) { - await highlighter.loadLanguage(lang as BundledLanguage); - } else { - lang = 'text'; - } - } + const lang = token.info ? token.info.split(/\s+/g)[0] : 'text'; // `markdown-it-attrs` strips `{1,3-5}` line-highlight ranges from - // `token.info`; `stash_fence_info` keeps the original so - // `transformerMetaHighlight` still sees them. + // `token.info`; `stash_fence_info` keeps the original so the highlighter + // still sees them. const rawInfo = (token.meta as { rawInfo?: string } | null)?.rawInfo ?? token.info; - return highlighter.codeToHtml(code, { - lang, - themes, - defaultColor: 'light', - transformers: shikiTransformers, - meta: { __raw: rawInfo }, - }); + return highlight(token.content, lang, rawInfo); }; - // Code block wrapping (must come after shiki, before line-numbers) + // Code block wrapping (must come after the fence rule, before line-numbers) markdown.use(preWrapperPlugin, { copyLabel: options?.copyLabel }); markdown.use(containerPlugin); @@ -114,7 +81,7 @@ async function createCompiler(options?: CompileOptions): Promise { markdown.use(gitHubAlertsPlugin); // Save the raw fence info (e.g. `ts {1,3-5}`) before `markdown-it-attrs` strips the - // `{…}`, so `transformerMetaHighlight` still gets the line ranges via `meta.__raw`. + // `{…}`, so the highlighter still gets the line ranges. const stashFenceInfo: RuleCore = (state) => { for (const token of state.tokens) { if (token.type === 'fence') { diff --git a/packages/md/src/highlight.ts b/packages/md/src/highlight.ts new file mode 100644 index 000000000..7aef4a46d --- /dev/null +++ b/packages/md/src/highlight.ts @@ -0,0 +1,246 @@ +import { codeToTokens, isSupportedLanguage } from '@pierre/highlights'; +import type { Lang, Theme, ThemeFamily, ThemedToken } from '@pierre/highlights'; + +export type CodeThemeNames = Readonly<{ light: string; dark: string }>; + +/** Renders a code block. `meta` is the fence info, which may hold a `{1,3-5}` line range. */ +export type CodeHighlighter = (code: string, lang: string, meta: string) => string; + +// The theme CSS and the code-copy script select on these names. +const CSS_VARIABLE_PREFIX = '--shiki-'; + +const NOTATION_RE = /\s*\[!code (\+\+|--|highlight|hl|focus|error|warning)(?::(\d+))?\]/g; +// What is left of a comment once its notations are removed: only delimiters. +const EMPTY_COMMENT_RE = /^\s*(?:\/\/|\/\*|\*\/||--|[#;%"'*]|\s)*\s*$/; +const TOKEN_COMMENT = 1; + +// The classes a notation gives its line. The block gets `has-` and the first one. +const NOTATION_CLASSES: Record> = { + '++': ['diff', 'add'], + '--': ['diff', 'remove'], + highlight: ['highlighted'], + hl: ['highlighted'], + focus: ['focused'], + error: ['highlighted', 'error'], + warning: ['highlighted', 'warning'], +}; + +// Line and block classes come out in this order whatever order the notations appear in. +const LINE_CLASS_ORDER: ReadonlyArray = [ + 'highlighted', + 'diff', + 'add', + 'remove', + 'focused', + 'error', + 'warning', +]; +const PRE_CLASS_ORDER: ReadonlyArray = ['has-diff', 'has-highlighted', 'has-focused']; + +async function loadTheme(name: string): Promise { + if (!/^[a-z0-9-]+$/.test(name)) { + throw new Error(`Invalid code theme name '${name}'.`); + } + let module: { default?: unknown }; + try { + module = (await import(`@pierre/highlights/themes/${name}`)) as { default?: unknown }; + } catch (error) { + // Only a missing module means the name is wrong. Anything else is a broken install. + if ((error as NodeJS.ErrnoException).code !== 'ERR_MODULE_NOT_FOUND') { + throw error; + } + throw new Error(`Unknown code theme '${name}'.`, { cause: error }); + } + // The themes directory also holds modules that are not themes. + const theme = module.default; + if (typeof theme !== 'object' || theme === null || !('style' in theme || 'themes' in theme)) { + throw new Error(`Unknown code theme '${name}'.`); + } + return theme as Theme | ThemeFamily; +} + +function escapeHtml(text: string): string { + return /[&<]/.test(text) ? text.replace(/&/g, '&').replace(/; + +/** The 1-based line ranges of a `{1,3-5}` list in the fence info, if it has one. */ +function metaHighlightedRanges(meta: string): ReadonlyArray | null { + const match = /\{([\d,-]+)\}/.exec(meta); + if (!match) { + return null; + } + const ranges: Array = []; + for (const part of match[1].split(',')) { + const [from, to] = part.split('-').map((value) => parseInt(value, 10)); + if (!Number.isNaN(from)) { + ranges.push({ from, to: to === undefined || Number.isNaN(to) ? from : to }); + } + } + return ranges; +} + +// The highlighter gives every token of one kind the same style object. +const spanOpeners = new WeakMap(); + +function spanOpener(token: ThemedToken): string { + const style = token.htmlStyle; + if (!style) { + return ''; + } + let opener = spanOpeners.get(style); + if (opener === undefined) { + const css = Object.entries(style) + .map(([property, value]) => `${property}:${value}`) + .join(';'); + opener = css ? `` : ''; + spanOpeners.set(style, opener); + } + return opener; +} + +function renderLine(tokens: ReadonlyArray, classes: string): string { + let html = ``; + for (const token of tokens) { + html += `${spanOpener(token)}${escapeHtml(token.content)}`; + } + return `${html}`; +} + +type Notation = Readonly<{ classes: ReadonlyArray; count: number }>; + +// Markdown examples show code fences as text, so only their HTML comments carry notations. +const MARKDOWN_LANGS: ReadonlySet = new Set(['md', 'markdown', 'mdx']); + +/** + * Splits the `[!code ...]` notations from the comments of a line. + * A comment that held nothing else is removed with them. + */ +function takeNotations( + tokens: ReadonlyArray, + lang: string, +): Readonly<{ + tokens: ReadonlyArray; + notations: ReadonlyArray; +}> { + const notations: Array = []; + const kept: Array = []; + const htmlCommentsOnly = MARKDOWN_LANGS.has(lang); + const jsx = lang === 'jsx' || lang === 'tsx'; + for (let index = 0; index < tokens.length; index++) { + const token = tokens[index]; + if ( + token.type !== TOKEN_COMMENT || + !token.content.includes('[!code ') || + (htmlCommentsOnly && !token.content.trimStart().startsWith('\n', 'html'); + expect(renderedLines(markup)[0]).toEqual({ classes: 'line diff add', text: '

x

' }); + + const block = render('a { } /* [!code focus] */\n', 'css'); + expect(renderedLines(block)[0]).toEqual({ classes: 'line focused', text: 'a { } ' }); + }); + + it('removes a comment that held only a notation, whatever its delimiter', () => { + const cases: ReadonlyArray<[string, string, string]> = [ + ['lisp', '(a) ; [!code ++]\n', '(a) '], + ['latex', 'x % [!code ++]\n', 'x '], + ['sql', 'select 1 -- [!code ++]\n', 'select 1 '], + ['vim', 'let a=1 " [!code ++]\n', 'let a=1 '], + ]; + for (const [lang, code, text] of cases) { + expect(renderedLines(render(code, lang))[0]).toEqual({ classes: 'line diff add', text }); + } + }); + + it('applies a notation with a count to the following lines', () => { + const html = render('a(); // [!code ++:2]\nb();\nc();\n'); + expect(lineClasses(html)).toEqual(['line diff add', 'line diff add', 'line', 'line']); + }); + + it('applies a notation on its own line to the next line', () => { + const html = render('a();\n// [!code focus]\nb();\n'); + expect(renderedLines(html)).toEqual([ + { classes: 'line', text: 'a();' }, + { classes: 'line focused', text: 'b();' }, + { classes: 'line', text: '' }, + ]); + }); + + it('applies a counted notation on its own line to the lines after it', () => { + const html = render('// [!code ++:2]\na();\nb();\nc();\n'); + expect(lineClasses(html)).toEqual(['line diff add', 'line diff add', 'line', 'line']); + }); + + it('drops a JSX comment that held only a notation, with its braces', () => { + const html = render(' {/* [!code highlight:2] */}\n\n\n\n', 'tsx'); + expect(renderedLines(html)).toEqual([ + { classes: 'line highlighted', text: '' }, + { classes: 'line highlighted', text: '' }, + { classes: 'line', text: '' }, + { classes: 'line', text: '' }, + ]); + }); + + it('removes the braces of a JSX annotation at the end of a line', () => { + const html = render(' {/* [!code ++] */}\n', 'tsx'); + expect(renderedLines(html)[0]).toEqual({ classes: 'line diff add', text: ' ' }); + }); + + it('reads only HTML comments in a Markdown block, so code fences in it stay as written', () => { + const fence = render('```ts\na(); // [!code ++]\n```\n', 'md'); + expect(preClasses(fence)).not.toContain('has-diff'); + expect(renderedLines(fence)[1]).toEqual({ classes: 'line', text: 'a(); // [!code ++]' }); + + const comment = render('\ntext\n', 'md'); + expect(renderedLines(comment)[0]).toEqual({ classes: 'line focused', text: 'text' }); + }); + + it('accepts a line range far past the end of the block', () => { + const html = render('a();\nb();\n', 'ts', 'ts {2-1000000000}'); + expect(lineClasses(html)).toEqual(['line', 'line highlighted', 'line highlighted']); + }); + + describe.each(['jsx', 'tsx'])('%s comment expressions', (lang) => { + it('removes standalone annotation braces and applies the count to following lines', () => { + const html = render( + '
\n { /* [!code --:2] */ }\n \n \n \n
\n', + lang, + ); + expect(renderedLines(html)).toEqual([ + { classes: 'line', text: '
' }, + { classes: 'line diff remove', text: ' ' }, + { classes: 'line diff remove', text: ' ' }, + { classes: 'line', text: ' ' }, + { classes: 'line', text: '
' }, + { classes: 'line', text: '' }, + ]); + }); + + it('removes inline annotation braces without removing the surrounding JSX', () => { + const html = render('
{/* [!code ++] */}
\n', lang); + expect(renderedLines(html)[0]).toEqual({ + classes: 'line diff add', + text: '
', + }); + }); + + it('keeps braces around a comment with remaining text', () => { + const html = render('
{/* keep this [!code focus] */}
\n', lang); + expect(renderedLines(html)[0]).toEqual({ + classes: 'line focused', + text: '
{/* keep this */}
', + }); + }); + + it('keeps function body braces around an annotation', () => { + const html = render('function f() {/* [!code focus] */}\n', lang); + expect(renderedLines(html)[0]).toEqual({ + classes: 'line focused', + text: 'function f() {}', + }); + }); + }); + + it('leaves a notation outside a comment alone', () => { + const html = render('const s = "// [!code ++]";\n'); + expect(preClasses(html)).not.toContain('has-diff'); + expect(renderedLines(html)[0]).toEqual({ + classes: 'line', + text: 'const s = "// [!code ++]";', + }); + }); + + it('combines a line range from the fence info with a notation', () => { + const html = render('a(); // [!code ++]\nb();\nc();\n', 'ts', 'ts {1,3}'); + expect(lineClasses(html)).toEqual([ + 'line highlighted diff add', + 'line', + 'line highlighted', + 'line', + ]); + }); + + it('uses the named themes', async () => { + const other = await createCodeHighlighter({ light: 'vitesse-light', dark: 'vitesse-dark' }); + const html = other('const a = 1;\n', 'ts', 'ts'); + expect(preClasses(html)).toBe('shiki shiki-themes vitesse-light vitesse-dark'); + }); + + it('rejects a module in the themes directory that is not a theme', async () => { + await expect(createCodeHighlighter({ light: 'loader', dark: 'github-dark' })).rejects.toThrow( + "Unknown code theme 'loader'.", + ); + }); + + it('rejects a theme that does not exist', async () => { + await expect( + createCodeHighlighter({ light: 'no-such-theme', dark: 'github-dark' }), + ).rejects.toThrow("Unknown code theme 'no-such-theme'."); + }); +}); diff --git a/packages/md/test/unit/plugins.test.ts b/packages/md/test/unit/plugins.test.ts index 3acaad78a..8be7c0d04 100644 --- a/packages/md/test/unit/plugins.test.ts +++ b/packages/md/test/unit/plugins.test.ts @@ -61,7 +61,7 @@ describe('plugins', () => { expect(prose.html).not.toContain(' { + it('copy script drops the empty last line of the code block', () => { const copied: Array = []; clickCopy(['const x = 1;', '', 'const y = 2;', ''], (text) => { copied.push(text); diff --git a/playground/markdown-blog/pages/posts/code-examples.md b/playground/markdown-blog/pages/posts/code-examples.md index e32f7521d..e32c6d145 100644 --- a/playground/markdown-blog/pages/posts/code-examples.md +++ b/playground/markdown-blog/pages/posts/code-examples.md @@ -1,6 +1,6 @@ --- title: Code Examples -description: Shiki syntax highlighting demos +description: Syntax highlighting demos --- Void supports syntax highlighting with dual themes (light/dark). @@ -33,6 +33,15 @@ export default defineConfig({ }); ``` +```tsx +
+ {/* [!code --] */} + + {/* [!code ++] */} + +
+``` + ## Line Highlighting ```ts {2,4-5} diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index cc9c2ab6a..4ff299691 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -255,12 +255,6 @@ catalogs: '@react-router/dev': specifier: ^8.5.1 version: 8.5.1 - '@shikijs/engine-javascript': - specifier: ^4.6.0 - version: 4.6.0 - '@shikijs/transformers': - specifier: ^4.6.0 - version: 4.6.0 '@stylexjs/stylex': specifier: 0.19.1 version: 0.19.1 @@ -592,12 +586,9 @@ importers: packages/md: dependencies: - '@shikijs/engine-javascript': - specifier: 'catalog:' - version: 4.6.0 - '@shikijs/transformers': - specifier: 'catalog:' - version: 4.6.0 + '@pierre/highlights': + specifier: ^0.5.1 + version: 0.5.1 gray-matter: specifier: ^4.0.3 version: 4.0.3 @@ -625,9 +616,6 @@ importers: pathslash: specifier: 'catalog:' version: 0.1.0 - shiki: - specifier: 'catalog:' - version: 4.6.0 tinyglobby: specifier: ^0.2.17 version: 0.2.17 @@ -4689,6 +4677,9 @@ packages: resolution: {integrity: sha512-7FNeNl8NCE7aINx7WXiKQrPYZWC/hvrTsmk6zmxbI7LTXE7hVek/n8AfVgpe2y82zl3w0HvCHN0bVKMBoJcC0w==} engines: {node: '>= 10.0.0'} + '@pierre/highlights@0.5.1': + resolution: {integrity: sha512-c2WF6sgwgKdxXU6FpWDLWUYHRca/cJy+3QJkWAqYqEAFxqlPf8eSH0ehHcFFjKBmT+9KBl9H7q6z7HMRU7+m6g==} + '@polka/url@1.0.0-next.29': resolution: {integrity: sha512-wwQAWhWSuHaag8c4q/KN/vCoeOJYshAIvMQwD4GpSb3OiZklFfvAgmj0VCBBImRpuF/aFgIRzllXlVX93Jevww==} @@ -13048,6 +13039,8 @@ snapshots: '@parcel/watcher-win32-arm64': 2.6.0 '@parcel/watcher-win32-x64': 2.6.0 + '@pierre/highlights@0.5.1': {} + '@polka/url@1.0.0-next.29': {} '@poppinss/colors@4.1.6': diff --git a/pnpm-workspace.yaml b/pnpm-workspace.yaml index f92b77f1b..58644e6c2 100644 --- a/pnpm-workspace.yaml +++ b/pnpm-workspace.yaml @@ -101,8 +101,6 @@ catalog: tslib: ^2.9.1 vite-plugin-solid: ^2.11.16 '@hono/node-server': ^2.1.6 - '@shikijs/engine-javascript': ^4.6.0 - '@shikijs/transformers': ^4.6.0 markdown-exit: ^2.1.3 markdown-it-anchor: ^10.1.0 minimatch: ^11.0.7