Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
20 changes: 10 additions & 10 deletions docs/guide/pages-routing/markdown.md
Original file line number Diff line number Diff line change
Expand Up @@ -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, `<kbd>`, `<mark>`, 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.

Expand Down Expand Up @@ -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

Expand Down Expand Up @@ -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'`.

Expand Down
4 changes: 1 addition & 3 deletions packages/md/package.json
Original file line number Diff line number Diff line change
Expand Up @@ -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",
Expand All @@ -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": {
Expand Down
67 changes: 17 additions & 50 deletions packages/md/src/compile.ts
Original file line number Diff line number Diff line change
@@ -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';
Expand Down Expand Up @@ -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<string>;
};
Expand All @@ -63,48 +58,20 @@ async function getCompiler(options?: CompileOptions): Promise<MarkdownExit> {
async function createCompiler(options?: CompileOptions): Promise<MarkdownExit> {
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<Token>, tokenIndex: number) => {
const highlight = await createCodeHighlighter(
options?.themes ?? options?.shiki?.themes ?? { light: 'github-light', dark: 'github-dark' },
);
markdown.renderer.rules.fence = (tokens: ReadonlyArray<Token>, 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);
Expand All @@ -114,7 +81,7 @@ async function createCompiler(options?: CompileOptions): Promise<MarkdownExit> {
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') {
Expand Down
218 changes: 218 additions & 0 deletions packages/md/src/highlight.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,218 @@
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<string, ReadonlyArray<string>> = {
'++': ['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<string> = [
'highlighted',
'diff',
'add',
'remove',
'focused',
'error',
'warning',
];
const PRE_CLASS_ORDER: ReadonlyArray<string> = ['has-diff', 'has-highlighted', 'has-focused'];

async function loadTheme(name: string): Promise<Theme | ThemeFamily> {
if (!/^[a-z0-9-]+$/.test(name)) {
throw new Error(`Invalid code theme name '${name}'.`);
}
try {
const module = (await import(`@pierre/highlights/themes/${name}`)) as {
default: Theme | ThemeFamily;
};
return module.default;
} catch (error) {
throw new Error(`Unknown code theme '${name}'.`, { cause: error });
}
}

function escapeHtml(text: string): string {
return /[&<]/.test(text) ? text.replace(/&/g, '&#x26;').replace(/</g, '&#x3C;') : text;
}

function escapeAttribute(text: string): string {
return escapeHtml(text).replace(/"/g, '&#x22;');
}

/** The 1-based lines of a `{1,3-5}` range in the fence info, if it has one. */
function metaHighlightedLines(meta: string): ReadonlySet<number> | null {
const match = /\{([\d,-]+)\}/.exec(meta);
if (!match) {
return null;
}
const lines = new Set<number>();
for (const part of match[1].split(',')) {
const [from, to] = part.split('-').map((value) => parseInt(value, 10));
if (Number.isNaN(from)) {
continue;
}
const end = to === undefined || Number.isNaN(to) ? from : to;
for (let line = from; line <= end; line++) {
lines.add(line);
}
}
return lines;
}

// The highlighter gives every token of one kind the same style object.
const spanOpeners = new WeakMap<object, string>();

function spanOpener(token: ThemedToken): string {
const style = token.htmlStyle;
if (!style) {
return '<span>';
}
let opener = spanOpeners.get(style);
if (opener === undefined) {
const css = Object.entries(style)
.map(([property, value]) => `${property}:${value}`)
.join(';');
opener = css ? `<span style="${escapeAttribute(css)}">` : '<span>';
spanOpeners.set(style, opener);
}
return opener;
}

function renderLine(tokens: ReadonlyArray<ThemedToken>, classes: string): string {
let html = `<span class="${classes}">`;
for (const token of tokens) {
html += `${spanOpener(token)}${escapeHtml(token.content)}</span>`;
}
return `${html}</span>`;
}

type Notation = Readonly<{ classes: ReadonlyArray<string>; count: number }>;

/**
* Splits the `[!code ...]` notations from the comments of a line.
* A comment that held nothing else is removed with them.
*/
function takeNotations(tokens: ReadonlyArray<ThemedToken>): Readonly<{
tokens: ReadonlyArray<ThemedToken>;
notations: ReadonlyArray<Notation>;
}> {
const notations: Array<Notation> = [];
const kept: Array<ThemedToken> = [];
for (const token of tokens) {
if (token.type !== TOKEN_COMMENT || !token.content.includes('[!code ')) {
kept.push(token);
continue;
}
const content = token.content.replace(
NOTATION_RE,
(_match, name: string, count: string | undefined) => {
notations.push({
classes: NOTATION_CLASSES[name],
count: count ? Math.max(1, parseInt(count, 10)) : 1,
});
return '';
},
);
if (!EMPTY_COMMENT_RE.test(content)) {
kept.push(content === token.content ? token : { ...token, content });
}
}
return { tokens: kept, notations };
}

function isBlank(tokens: ReadonlyArray<ThemedToken>): boolean {
return tokens.every((token) => !/\S/.test(token.content));
}

/**
* Creates the code block highlighter. It renders the block the theme CSS expects:
* one `span.line` per line, light colors inline and dark colors in CSS variables.
*/
export async function createCodeHighlighter(themeNames: CodeThemeNames): Promise<CodeHighlighter> {
const [light, dark] = await Promise.all([
loadTheme(themeNames.light),
loadTheme(themeNames.dark),
]);
const plainText = 'text' as Lang;
const options = {
themes: { light, dark },
defaultColor: 'light',
cssVariablePrefix: CSS_VARIABLE_PREFIX,
} as const;

// The colors of the block depend on the themes alone.
const { bg, fg } = codeToTokens('', { lang: plainText, ...options });
const preClass = `shiki shiki-themes ${themeNames.light} ${themeNames.dark}`;
const preStyle = escapeAttribute(`background-color:${bg};color:${fg}`);

return (code, lang, meta) => {
const result = codeToTokens(code, {
lang: isSupportedLanguage(lang) ? lang : plainText,
...options,
});
const highlighted = metaHighlightedLines(meta);

// Most blocks have neither notations nor a line range.
if (!highlighted && !code.includes('[!code ')) {
const body = result.tokens.map((tokens) => renderLine(tokens, 'line')).join('\n');
return `<pre class="${preClass}" style="${preStyle}" tabindex="0"><code>${body}</code></pre>`;
}

const preClasses = new Set<string>();
const lines: Array<string> = [];
// Notations still to apply. One with a `:N` count stays for the lines that follow.
let running: Array<{ classes: ReadonlyArray<string>; remaining: number }> = [];

result.tokens.forEach((lineTokens, index) => {
const { tokens, notations } = takeNotations(lineTokens);
for (const notation of notations) {
preClasses.add(`has-${notation.classes[0]}`);
running.push({ classes: notation.classes, remaining: notation.count });
}
// A line that held only the comment is dropped, and its notations apply from the next line.
if (notations.length > 0 && isBlank(tokens)) {
return;
}

const classes = new Set<string>();
if (highlighted?.has(index + 1)) {
classes.add('highlighted');
}
for (const entry of running) {
for (const name of entry.classes) {
classes.add(name);
}
entry.remaining--;
}
running = running.filter((entry) => entry.remaining > 0);

const ordered = LINE_CLASS_ORDER.filter((name) => classes.has(name));
lines.push(renderLine(tokens, ['line', ...ordered].join(' ')));
});

const blockClass = [preClass, ...PRE_CLASS_ORDER.filter((name) => preClasses.has(name))].join(
' ',
);
return `<pre class="${blockClass}" style="${preStyle}" tabindex="0"><code>${lines.join('\n')}</code></pre>`;
};
}
Loading