@classic-homes/theme-docs 0.0.50 → 0.2.0

package/dist/lib/parser/extensions.js

@@ -2,15 +2,27 @@
  * Marked Extensions for Enhanced Markdown Features
  *
  * Provides support for:
- * - Admonitions/Callouts (note, tip, warning, important, caution)
+ * - Admonitions/Callouts (note, info, tip, warning, important, caution, danger)
  * - Footnotes
  * - Definition Lists
  * - Mermaid diagram placeholders (rendered client-side)
+ * - Component placeholders for allowlisted `<Name prop="…" />` tags (mounted client-side)
  */
+import { escapeHtml } from '../highlighter/index.js';
 /**
  * Admonition types and their corresponding icons/classes
  */
-export const ADMONITION_TYPES = ['note', 'tip', 'warning', 'important', 'caution'];
+export const ADMONITION_TYPES = [
+    'note',
+    'info',
+    'tip',
+    'warning',
+    'important',
+    'caution',
+    'danger',
+];
+/** `:::type`, then an optional `[Title]` or ` Title`, the body, and a closing `:::`. */
+const ADMONITION_PATTERN = new RegExp(`^:::(${ADMONITION_TYPES.join('|')})(?:\\[([^\\]\\n]*)\\]|[ \\t]+([^\\n]*))?[ \\t]*\\n([\\s\\S]*?)\\n:::`);
 /**
  * Admonition extension for marked
  *
@@ -22,6 +34,12 @@ export const ADMONITION_TYPES = ['note', 'tip', 'warning', 'important', 'caution
  * :::warning Title Here
  * This is a warning with a custom title
  * :::
+ *
+ * :::tip[Title Here]
+ * The bracketed title form, as written for Docusaurus (remark-directive)
+ * :::
+ *
+ * Titles are inline markdown, so `code` and *emphasis* render.
  */
 export function admonitionExtension() {
     return {
@@ -33,18 +51,22 @@ export function admonitionExtension() {
                     return src.match(/^:::/)?.index;
                 },
                 tokenizer(src) {
-                    // Match :::type optional-title\ncontent\n:::
-                    const match = src.match(/^:::(note|tip|warning|important|caution)(?:\s+([^\n]*))?\n([\s\S]*?)\n:::/);
+                    // Match :::type[optional title] or :::type optional title, then content, then :::
+                    const match = src.match(ADMONITION_PATTERN);
                     if (match) {
+                        const type = match[1];
+                        const title = (match[2] ?? match[3])?.trim() || type.charAt(0).toUpperCase() + type.slice(1);
                         const token = {
                             type: 'admonition',
                             raw: match[0],
-                            admonitionType: match[1],
-                            title: match[2]?.trim() || match[1].charAt(0).toUpperCase() + match[1].slice(1),
-                            content: match[3].trim(),
+                            admonitionType: type,
+                            title,
+                            titleTokens: [],
+                            content: match[4].trim(),
                             tokens: [],
                         };
-                        // Parse the inner content as markdown
+                        // Parse the title as inline markdown and the inner content as block markdown
+                        this.lexer.inlineTokens(title, token.titleTokens);
                         this.lexer.blockTokens(token.content, token.tokens);
                         return token;
                     }
@@ -52,17 +74,20 @@ export function admonitionExtension() {
                 },
                 renderer(token) {
                     const innerHtml = this.parser.parse(token.tokens ?? []);
+                    const titleHtml = this.parser.parseInline(token.titleTokens ?? []);
                     const iconMap = {
-                        note: `<svg class="admonition-icon" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><circle cx="12" cy="12" r="10"/><line x1="12" y1="16" x2="12" y2="12"/><line x1="12" y1="8" x2="12.01" y2="8"/></svg>`,
-                        tip: `<svg class="admonition-icon" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M9.663 17h4.673M12 3v1m6.364 1.636l-.707.707M21 12h-1M4 12H3m3.343-5.657l-.707-.707m2.828 9.9a5 5 0 117.072 0l-.548.547A3.374 3.374 0 0014 18.469V19a2 2 0 11-4 0v-.531c0-.895-.356-1.754-.988-2.386l-.548-.547z"/></svg>`,
-                        warning: `<svg class="admonition-icon" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M10.29 3.86L1.82 18a2 2 0 001.71 3h16.94a2 2 0 001.71-3L13.71 3.86a2 2 0 00-3.42 0z"/><line x1="12" y1="9" x2="12" y2="13"/><line x1="12" y1="17" x2="12.01" y2="17"/></svg>`,
-                        important: `<svg class="admonition-icon" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M12 22c5.523 0 10-4.477 10-10S17.523 2 12 2 2 6.477 2 12s4.477 10 10 10z"/><path d="M12 8v4"/><path d="M12 16h.01"/></svg>`,
-                        caution: `<svg class="admonition-icon" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M7.86 2h8.28L22 7.86v8.28L16.14 22H7.86L2 16.14V7.86L7.86 2z"/><line x1="12" y1="8" x2="12" y2="12"/><line x1="12" y1="16" x2="12.01" y2="16"/></svg>`,
+                        note: `<svg class="admonition-icon" aria-hidden="true" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><circle cx="12" cy="12" r="10"/><line x1="12" y1="16" x2="12" y2="12"/><line x1="12" y1="8" x2="12.01" y2="8"/></svg>`,
+                        info: `<svg class="admonition-icon" aria-hidden="true" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><circle cx="12" cy="12" r="10"/><path d="M12 16v-4"/><path d="M12 8h.01"/></svg>`,
+                        tip: `<svg class="admonition-icon" aria-hidden="true" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M9.663 17h4.673M12 3v1m6.364 1.636l-.707.707M21 12h-1M4 12H3m3.343-5.657l-.707-.707m2.828 9.9a5 5 0 117.072 0l-.548.547A3.374 3.374 0 0014 18.469V19a2 2 0 11-4 0v-.531c0-.895-.356-1.754-.988-2.386l-.548-.547z"/></svg>`,
+                        warning: `<svg class="admonition-icon" aria-hidden="true" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M10.29 3.86L1.82 18a2 2 0 001.71 3h16.94a2 2 0 001.71-3L13.71 3.86a2 2 0 00-3.42 0z"/><line x1="12" y1="9" x2="12" y2="13"/><line x1="12" y1="17" x2="12.01" y2="17"/></svg>`,
+                        important: `<svg class="admonition-icon" aria-hidden="true" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M12 22c5.523 0 10-4.477 10-10S17.523 2 12 2 2 6.477 2 12s4.477 10 10 10z"/><path d="M12 8v4"/><path d="M12 16h.01"/></svg>`,
+                        caution: `<svg class="admonition-icon" aria-hidden="true" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M7.86 2h8.28L22 7.86v8.28L16.14 22H7.86L2 16.14V7.86L7.86 2z"/><line x1="12" y1="8" x2="12" y2="12"/><line x1="12" y1="16" x2="12.01" y2="16"/></svg>`,
+                        danger: `<svg class="admonition-icon" aria-hidden="true" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M8.5 14.5A2.5 2.5 0 0 0 11 12c0-1.38-.5-2-1-3-1.072-2.143-.224-4.054 2-6 .5 2.5 2 4.9 4 6.5 2 1.6 3 3.5 3 5.5a7 7 0 1 1-14 0c0-1.153.433-2.294 1-3a2.5 2.5 0 0 0 2.5 2.5z"/></svg>`,
                     };
                     return `<div class="admonition admonition-${token.admonitionType}">
   <div class="admonition-heading">
     ${iconMap[token.admonitionType]}
-    <span class="admonition-title">${token.title}</span>
+    <span class="admonition-title">${titleHtml}</span>
   </div>
   <div class="admonition-content">${innerHtml}</div>
 </div>`;
@@ -71,18 +96,19 @@ export function admonitionExtension() {
         ],
     };
 }
-let footnoteStore = {
-    definitions: new Map(),
-    references: new Set(),
-};
+export function createFootnoteStore() {
+    return { definitions: new Map(), references: new Set() };
+}
+/** Store used when an extension is created without one (the pre-0.2 global API). */
+let defaultFootnoteStore = createFootnoteStore();
 /**
- * Reset footnote store (call before parsing a new document)
+ * Reset the default footnote store.
+ *
+ * @deprecated `parseMarkdown` now keeps a store per call. Only needed if you build a
+ * `Marked` instance yourself from `footnoteExtension()` without passing a store.
  */
 export function resetFootnoteStore() {
-    footnoteStore = {
-        definitions: new Map(),
-        references: new Set(),
-    };
+    defaultFootnoteStore = createFootnoteStore();
 }
 /**
  * Footnotes extension for marked
@@ -92,7 +118,8 @@ export function resetFootnoteStore() {
  *
  * [^1]: This is the footnote content.
  */
-export function footnoteExtension() {
+export function footnoteExtension(store) {
+    const footnotes = () => store ?? defaultFootnoteStore;
     return {
         extensions: [
             // Footnote definition: [^id]: content
@@ -116,7 +143,7 @@ export function footnoteExtension() {
                             tokens: [],
                         };
                         this.lexer.inline(content, token.tokens);
-                        footnoteStore.definitions.set(id, { content, tokens: token.tokens });
+                        footnotes().definitions.set(id, { content, tokens: token.tokens });
                         return token;
                     }
                     return undefined;
@@ -137,7 +164,7 @@ export function footnoteExtension() {
                     const match = src.match(/^\[\^([^\]]+)\](?!:)/);
                     if (match) {
                         const id = match[1];
-                        footnoteStore.references.add(id);
+                        footnotes().references.add(id);
                         return {
                             type: 'footnoteRef',
                             raw: match[0],
@@ -147,7 +174,8 @@ export function footnoteExtension() {
                     return undefined;
                 },
                 renderer(token) {
-                    return `<sup class="footnote-ref"><a href="#fn-${token.id}" id="fnref-${token.id}">[${token.id}]</a></sup>`;
+                    const id = escapeHtml(token.id);
+                    return `<sup class="footnote-ref"><a href="#fn-${id}" id="fnref-${id}" aria-label="Footnote ${id}">[${id}]</a></sup>`;
                 },
             },
         ],
@@ -156,38 +184,33 @@ export function footnoteExtension() {
 /**
  * Render collected footnotes as a section
  * Call this after parsing to get the footnotes HTML
+ *
+ * @param store - The store the footnote extension wrote to (default: the shared store)
+ * @param renderInline - Renders a footnote's inline tokens to HTML. Without it the
+ *   footnote text is escaped and shown as written.
  */
-export function renderFootnotes() {
-    if (footnoteStore.definitions.size === 0) {
+export function renderFootnotes(store = defaultFootnoteStore, renderInline) {
+    if (store.definitions.size === 0) {
         return '';
     }
     const items = [];
-    for (const [id, { content }] of footnoteStore.definitions) {
-        if (footnoteStore.references.has(id)) {
+    for (const [rawId, { content, tokens }] of store.definitions) {
+        if (store.references.has(rawId)) {
+            const id = escapeHtml(rawId);
+            const body = renderInline ? renderInline(tokens) : escapeHtml(content);
             items.push(`<li id="fn-${id}" class="footnote-item">
-          <p>${content} <a href="#fnref-${id}" class="footnote-backref">↩</a></p>
+          <p>${body} <a href="#fnref-${id}" class="footnote-backref" aria-label="Back to reference ${id}">↩</a></p>
         </li>`);
         }
     }
     if (items.length === 0) {
         return '';
     }
-    return `<section class="footnotes">
+    return `<section class="footnotes" aria-label="Footnotes">
   <hr class="footnotes-separator" />
   <ol class="footnotes-list">${items.join('')}</ol>
 </section>`;
 }
-/**
- * Definition list extension for marked
- *
- * Syntax:
- * Term 1
- * : Definition for term 1
- *
- * Term 2
- * : Definition for term 2
- * : Another definition for term 2
- */
 export function definitionListExtension() {
     return {
         extensions: [
@@ -229,6 +252,11 @@ export function definitionListExtension() {
                         if (items.length === 0) {
                             return undefined;
                         }
+                        // Terms and definitions are inline markdown, like everywhere else in a page
+                        for (const item of items) {
+                            item.termTokens = this.lexer.inlineTokens(item.term);
+                            item.definitionTokens = item.definitions.map((def) => this.lexer.inlineTokens(def));
+                        }
                         return {
                             type: 'defList',
                             raw,
@@ -240,8 +268,10 @@ export function definitionListExtension() {
                 renderer(token) {
                     const itemsHtml = token.items
                         .map((item) => {
-                        const defsHtml = item.definitions.map((def) => `<dd>${def}</dd>`).join('');
-                        return `<dt>${item.term}</dt>${defsHtml}`;
+                        const defsHtml = item.definitionTokens
+                            .map((tokens) => `<dd>${this.parser.parseInline(tokens)}</dd>`)
+                            .join('');
+                        return `<dt>${this.parser.parseInline(item.termTokens)}</dt>${defsHtml}`;
                     })
                         .join('');
                     return `<dl class="definition-list">${itemsHtml}</dl>`;
@@ -262,6 +292,14 @@ export function definitionListExtension() {
  *   A --> B
  * ```
  */
+export function renderMermaidPlaceholder(code) {
+    // A placeholder div with the mermaid code; the client-side Mermaid library picks it up.
+    // The <pre> shows the source until (or if) mermaid renders it.
+    const escapedCode = escapeHtml(code);
+    return `<div class="mermaid-diagram" data-mermaid="${escapedCode}">
+  <pre class="mermaid">${escapedCode}</pre>
+</div>`;
+}
 export function mermaidExtension() {
     return {
         extensions: [
@@ -269,10 +307,10 @@ export function mermaidExtension() {
                 name: 'mermaidBlock',
                 level: 'block',
                 start(src) {
-                    return src.match(/^```mermaid/)?.index;
+                    return src.match(/^```mermaid[ \t]*\n/)?.index;
                 },
                 tokenizer(src) {
-                    const match = src.match(/^```mermaid\n([\s\S]*?)```/);
+                    const match = src.match(/^```mermaid[ \t]*\n([\s\S]*?)```/);
                     if (match) {
                         return {
                             type: 'mermaidBlock',
@@ -283,16 +321,47 @@ export function mermaidExtension() {
                     return undefined;
                 },
                 renderer(token) {
-                    // Render as a placeholder div with the mermaid code
-                    // The client-side Mermaid library will pick this up
-                    const escapedCode = token.code
-                        .replace(/&/g, '&amp;')
-                        .replace(/</g, '&lt;')
-                        .replace(/>/g, '&gt;')
-                        .replace(/"/g, '&quot;');
-                    return `<div class="mermaid-diagram" data-mermaid="${escapedCode}">
-  <pre class="mermaid">${token.code}</pre>
-</div>`;
+                    return renderMermaidPlaceholder(token.code);
+                },
+            },
+        ],
+    };
+}
+/**
+ * Component placeholder extension for marked
+ *
+ * Syntax (on a line of its own, string props only):
+ * <RequestForm id="ai-use-request" />
+ *
+ * Renders an empty placeholder that `mountComponents` fills with the real component:
+ * <div data-component="RequestForm" data-props="{&quot;id&quot;:&quot;ai-use-request&quot;}"></div>
+ *
+ * Only names in `names` are recognised, so any other tag stays ordinary HTML. This lets
+ * MDX-style pages render without an MDX compiler.
+ */
+export function componentExtension(names) {
+    const allowed = new Set(names);
+    return {
+        extensions: [
+            {
+                name: 'component',
+                level: 'block',
+                start(src) {
+                    return src.match(/^ {0,3}<[A-Z]/m)?.index;
+                },
+                tokenizer(src) {
+                    const match = src.match(/^ {0,3}<([A-Z][A-Za-z0-9]*)((?:\s+[A-Za-z][\w-]*="[^"]*")*)\s*\/>[ \t]*(?:\n+|$)/);
+                    if (!match || !allowed.has(match[1]))
+                        return undefined;
+                    const props = {};
+                    for (const [, key, value] of match[2].matchAll(/([A-Za-z][\w-]*)="([^"]*)"/g)) {
+                        props[key] = value;
+                    }
+                    return { type: 'component', raw: match[0], name: match[1], props };
+                },
+                renderer(token) {
+                    const props = escapeHtml(JSON.stringify(token.props));
+                    return `<div data-component="${token.name}" data-props="${props}"></div>\n`;
                 },
             },
         ],
@@ -300,12 +369,16 @@ export function mermaidExtension() {
 }
 /**
  * Get all markdown extensions
+ *
+ * @param components - Names of components to render as placeholders (see `componentExtension`)
+ * @param footnotes - Store for this document's footnotes (default: the shared store)
  */
-export function getAllExtensions() {
+export function getAllExtensions(components = [], footnotes) {
     return [
         admonitionExtension(),
-        footnoteExtension(),
+        footnoteExtension(footnotes),
         definitionListExtension(),
         mermaidExtension(),
+        ...(components.length > 0 ? [componentExtension(components)] : []),
     ];
 }

package/dist/lib/parser/index.d.ts

@@ -6,7 +6,9 @@ import type { ParsedMarkdown, ParseOptions } from '../types/index.js';
  * applies Shiki syntax highlighting to code blocks, and optionally generates heading IDs.
  *
  * Supported extensions:
- * - Admonitions/Callouts: :::note, :::tip, :::warning, :::important, :::caution
+ * - Admonitions/Callouts: :::note, :::info, :::tip, :::warning, :::important, :::caution, :::danger
+ * - Explicit heading IDs: ## Heading {#custom-id}
+ * - Component placeholders: <RequestForm id="x" /> when "RequestForm" is in options.components
  * - Footnotes: [^1] references and [^1]: definitions
  * - Definition Lists: Term followed by : Definition
  * - Mermaid Diagrams: ```mermaid code blocks (rendered client-side)
@@ -15,7 +17,12 @@ import type { ParsedMarkdown, ParseOptions } from '../types/index.js';
  * @param options - Parsing options
  * @param options.theme - Shiki theme for code highlighting ('github-dark' | 'github-light' | 'one-dark-pro')
  * @param options.generateHeadingIds - Whether to generate IDs for headings (default: true)
- * @returns Parsed markdown with frontmatter data, cleaned markdown, and rendered HTML
+ * @param options.headingIdStyle - 'default', or 'github' for GitHub/Docusaurus-compatible IDs
+ * @param options.headingAnchors - Add a `#` permalink to each heading (default: false)
+ * @param options.components - Tag names to render as component placeholders (see `mountComponents`)
+ * @param options.externalLinks - Open http(s) links in a new tab, announced to screen readers
+ * @param options.langAlias - Map fence names to Shiki languages, e.g. `{ ios: 'text' }`
+ * @returns Parsed markdown with frontmatter data, cleaned markdown, rendered HTML, and TOC
  *
  * @example
  * ```typescript

package/dist/lib/parser/index.js

@@ -1,7 +1,17 @@
-import { Marked, Renderer } from 'marked';
+import { Marked, Parser, Renderer } from 'marked';
 import yaml from 'js-yaml';
 import { getHighlighter, escapeHtml } from '../highlighter/index.js';
-import { getAllExtensions, resetFootnoteStore, renderFootnotes } from './extensions.js';
+import { createFootnoteStore, getAllExtensions, renderFootnotes, renderMermaidPlaceholder, } from './extensions.js';
+import { createSlugger, EXPLICIT_ID_PATTERN } from './slug.js';
+/** Undo the entity escaping marked applies to heading text, so `A & B` slugs as `A & B`. */
+function decodeEntities(text) {
+    return text
+        .replace(/&lt;/g, '<')
+        .replace(/&gt;/g, '>')
+        .replace(/&quot;/g, '"')
+        .replace(/&#0?39;/g, "'")
+        .replace(/&amp;/g, '&');
+}
 /**
  * SECURITY NOTE: This parser renders markdown to HTML without sanitization.
  * Only use with trusted markdown content from your own codebase or CMS.
@@ -34,7 +44,9 @@ function extractFrontmatter(content) {
  * applies Shiki syntax highlighting to code blocks, and optionally generates heading IDs.
  *
  * Supported extensions:
- * - Admonitions/Callouts: :::note, :::tip, :::warning, :::important, :::caution
+ * - Admonitions/Callouts: :::note, :::info, :::tip, :::warning, :::important, :::caution, :::danger
+ * - Explicit heading IDs: ## Heading {#custom-id}
+ * - Component placeholders: <RequestForm id="x" /> when "RequestForm" is in options.components
  * - Footnotes: [^1] references and [^1]: definitions
  * - Definition Lists: Term followed by : Definition
  * - Mermaid Diagrams: ```mermaid code blocks (rendered client-side)
@@ -43,7 +55,12 @@ function extractFrontmatter(content) {
  * @param options - Parsing options
  * @param options.theme - Shiki theme for code highlighting ('github-dark' | 'github-light' | 'one-dark-pro')
  * @param options.generateHeadingIds - Whether to generate IDs for headings (default: true)
- * @returns Parsed markdown with frontmatter data, cleaned markdown, and rendered HTML
+ * @param options.headingIdStyle - 'default', or 'github' for GitHub/Docusaurus-compatible IDs
+ * @param options.headingAnchors - Add a `#` permalink to each heading (default: false)
+ * @param options.components - Tag names to render as component placeholders (see `mountComponents`)
+ * @param options.externalLinks - Open http(s) links in a new tab, announced to screen readers
+ * @param options.langAlias - Map fence names to Shiki languages, e.g. `{ ios: 'text' }`
+ * @returns Parsed markdown with frontmatter data, cleaned markdown, rendered HTML, and TOC
  *
  * @example
  * ```typescript
@@ -61,56 +78,79 @@ function extractFrontmatter(content) {
  * ```
  */
 export async function parseMarkdown(content, options = {}) {
-    const { theme = 'github-dark', generateHeadingIds = true } = options;
+    const { theme: requestedTheme = 'github-dark', generateHeadingIds = true, headingIdStyle = 'default', headingAnchors = false, components = [], externalLinks = false, langAlias = {}, } = options;
     // Extract frontmatter
     const { data: frontmatter, content: markdownContent } = extractFrontmatter(content);
-    // Get Shiki highlighter
+    // Get Shiki highlighter, with this page's theme and code languages loaded
     const highlighter = await getHighlighter();
-    // Reset footnote store for this document
-    resetFootnoteStore();
+    const theme = await ensureTheme(highlighter, requestedTheme);
+    const languageOf = (name) => langAlias[name] ?? name;
+    const highlightable = await ensureLanguages(highlighter, fenceLanguages(markdownContent).map(languageOf));
+    // Footnotes collected for this document only
+    const footnotes = createFootnoteStore();
     // Configure marked with custom code renderer
     const renderer = new Renderer();
     renderer.code = ({ text, lang }) => {
-        const language = lang || 'text';
-        // Skip mermaid blocks - they're handled by the mermaid extension
+        // The info string is the language, then optional meta: ```bash title="install.sh"
+        const [, name = '', meta = ''] = (lang ?? '').trim().match(/^(\S*)\s*(.*)$/) ?? [];
+        const language = languageOf(name) || 'text';
         if (language === 'mermaid') {
-            return '';
-        }
-        try {
-            const highlighted = highlighter.codeToHtml(text, {
-                lang: language,
-                theme: theme,
-            });
-            return highlighted;
-        }
-        catch {
-            // Fallback for unsupported languages
-            return `<pre class="shiki"><code class="language-${language}">${escapeHtml(text)}</code></pre>`;
+            // Normally caught by the mermaid extension; this covers fences it doesn't match
+            return renderMermaidPlaceholder(text);
         }
+        const pre = highlightable.has(language)
+            ? highlighter.codeToHtml(text, { lang: language, theme })
+            : `<pre class="shiki"><code class="language-${escapeHtml(language)}">${escapeHtml(text)}</code></pre>`;
+        const title = meta.match(/\btitle=(?:"([^"]*)"|'([^']*)'|(\S+))/);
+        const titleText = title ? (title[1] ?? title[2] ?? title[3]) : '';
+        return titleText
+            ? `<div class="code-block-wrapper"><div class="code-block-filename">${escapeHtml(titleText)}</div>${pre}</div>`
+            : pre;
     };
     if (generateHeadingIds) {
-        renderer.heading = function ({ tokens, text, depth }) {
-            const id = text
-                .toLowerCase()
-                .replace(/\./g, '-') // Convert periods to hyphens (preserves version numbers like v2.0 → v2-0)
-                .replace(/[^\w\s-]+/g, '') // Remove other special characters
-                .replace(/\s+/g, '-') // Convert spaces to hyphens
-                .replace(/-+/g, '-') // Collapse multiple hyphens
-                .replace(/^-|-$/g, ''); // Remove leading/trailing hyphens
+        const slug = createSlugger(headingIdStyle);
+        renderer.heading = function ({ tokens, depth }) {
+            // Slug the heading's text, not its markdown: `## Use **sudo**` → `use-sudo`
+            const plain = this.parser.parseInline(tokens, this.parser.textRenderer);
+            const explicitId = plain.match(EXPLICIT_ID_PATTERN)?.[1];
+            // Raw inline HTML (`## A <b>&amp;</b> B`) comes through as tags; slug only its text
+            const text = decodeEntities(plain.replace(EXPLICIT_ID_PATTERN, '').replace(/<[^>]*>/g, ''));
+            const id = escapeHtml(slug(text, explicitId));
             // Render inline tokens so markdown inside headings (bold, code, links) works
-            return `<h${depth} id="${id}">${this.parser.parseInline(tokens)}</h${depth}>`;
+            const inner = this.parser.parseInline(tokens).replace(EXPLICIT_ID_PATTERN, '');
+            const anchor = headingAnchors
+                ? `<a class="hash-link" href="#${id}" aria-label="Direct link to ${escapeHtml(text)}">&#8203;</a>`
+                : '';
+            return `<h${depth} id="${id}">${inner}${anchor}</h${depth}>`;
         };
     }
+    if (externalLinks) {
+        const { target = '_blank', rel = 'noopener noreferrer' } = externalLinks === true ? {} : externalLinks;
+        renderer.link = function (token) {
+            const html = Renderer.prototype.link.call(this, token);
+            if (!/^https?:\/\//i.test(token.href))
+                return html;
+            return html
+                .replace(/^<a /, `<a class="external-link" target="${escapeHtml(target)}" rel="${escapeHtml(rel)}" `)
+                .replace(/<\/a>$/, '<span class="external-link-hint"> (opens in new tab)</span></a>');
+        };
+    }
+    // Images below the fold shouldn't hold up the page
+    renderer.image = function (token) {
+        return Renderer.prototype.image
+            .call(this, token)
+            .replace(/^<img /, '<img loading="lazy" decoding="async" ');
+    };
     // Use a per-call Marked instance: the renderer captures per-call state
     // (theme, highlighter), and `marked.use` on the shared global instance
     // accumulates extensions across calls.
     const md = new Marked();
     // Apply all markdown extensions (admonitions, footnotes, definition lists, mermaid)
-    md.use(...getAllExtensions());
+    md.use(...getAllExtensions(components, footnotes));
     md.use({ renderer, gfm: true });
     let html = await md.parse(markdownContent);
     // Append footnotes section if any were referenced
-    const footnotesHtml = renderFootnotes();
+    const footnotesHtml = renderFootnotes(footnotes, (tokens) => Parser.parseInline(tokens, md.defaults));
     if (footnotesHtml) {
         html += footnotesHtml;
     }
@@ -118,8 +158,55 @@ export async function parseMarkdown(content, options = {}) {
         frontmatter,
         markdown: markdownContent,
         html,
+        toc: extractToc(html, 6),
     };
 }
+/** Languages named on code fences (```bash, ~~~yaml), mermaid excluded. */
+function fenceLanguages(markdown) {
+    const names = new Set();
+    for (const [, name] of markdown.matchAll(/^ {0,3}(?:`{3,}|~{3,})[ \t]*([^\s`{]+)/gm)) {
+        if (name !== 'mermaid')
+            names.add(name);
+    }
+    return [...names];
+}
+/** Shiki's built-in plain-text languages, which never need loading. */
+const PLAIN_LANGUAGES = new Set(['text', 'txt', 'plain', 'plaintext', 'ansi']);
+const warnedLanguages = new Set();
+/**
+ * Load every language a page uses before rendering, since marked renders code blocks
+ * synchronously. Returns the names that can be highlighted; the rest render as plain code.
+ */
+async function ensureLanguages(highlighter, names) {
+    const ok = new Set(PLAIN_LANGUAGES);
+    await Promise.all(names.map(async (name) => {
+        if (ok.has(name))
+            return;
+        try {
+            await highlighter.loadLanguage(name);
+            ok.add(name);
+        }
+        catch {
+            if (!warnedLanguages.has(name)) {
+                warnedLanguages.add(name);
+                console.warn(`[docs] No syntax highlighting for "${name}"; rendering as plain text`);
+            }
+        }
+    }));
+    return ok;
+}
+async function ensureTheme(highlighter, theme) {
+    if (highlighter.getLoadedThemes().includes(theme))
+        return theme;
+    try {
+        await highlighter.loadTheme(theme);
+        return theme;
+    }
+    catch {
+        console.warn(`[docs] Unknown theme "${theme}"; using github-dark`);
+        return 'github-dark';
+    }
+}
 /**
  * Extract table of contents entries from rendered HTML content.
  *
@@ -148,8 +235,11 @@ export function extractToc(html, maxDepth = 3) {
         if (level <= maxDepth) {
             toc.push({
                 level,
-                id: match[2],
-                text: match[3].replace(/<[^>]*>/g, ''),
+                id: decodeEntities(match[2]),
+                text: decodeEntities(match[3]
+                    .replace(/<a class="hash-link"[\s\S]*?<\/a>/g, '')
+                    .replace(/<[^>]*>/g, '')
+                    .trim()),
             });
         }
     }

package/dist/lib/parser/slug.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Heading ID generation.
+ *
+ * Two styles:
+ * - `default`: this package's original slugs (periods become hyphens, so `v2.0` → `v2-0`).
+ * - `github`: GitHub's algorithm (github-slugger), which Docusaurus, VitePress and GitHub
+ *   itself use. Pick it when migrating content whose `#anchor` links must keep working.
+ *
+ * Both styles dedupe repeated headings with a `-1`, `-2`… suffix (an explicit ID is never
+ * suffixed), and both honour an explicit `{#custom-id}` at the end of a heading.
+ */
+export type HeadingIdStyle = 'default' | 'github';
+/** Trailing `{#custom-id}` on a heading, as Docusaurus and Pandoc write it. */
+export declare const EXPLICIT_ID_PATTERN: RegExp;
+/**
+ * Create a slugger for one document. IDs are unique within it: the second
+ * `## Setup` becomes `setup-1`, matching github-slugger.
+ */
+export declare function createSlugger(style?: HeadingIdStyle): (text: string, explicitId?: string) => string;