Skip to content
Merged
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
Loading