@classic-homes/theme-docs 0.1.0 → 0.2.0

package/dist/lib/content/types.d.ts

@@ -0,0 +1,90 @@
+/**
+ * Shapes of the docs content model built by `loadDocs` and `renderDocs`.
+ * Plain data: safe to serialize into a bundle and to import from client code.
+ */
+import type { FrontmatterData } from '../types/frontmatter.js';
+import type { TocEntry } from '../types/docs.js';
+/** One sidebar entry. A category's `route` is its linked doc or generated-index page. */
+export type NavItem = {
+    type: 'page';
+    title: string;
+    route: string;
+} | {
+    type: 'category';
+    label: string;
+    route?: string;
+    /** From `_category_.json`. Undefined means the site's default. */
+    collapsible?: boolean;
+    collapsed?: boolean;
+    items: NavItem[];
+};
+/** A markdown file, with its links rewritten to site routes. */
+export interface DocSource {
+    /** Site route, e.g. `/docs/it/network/vpn` (`index.md` maps to its folder) */
+    route: string;
+    /** Path under the docs directory, posix separators, e.g. `it/network/vpn/index.md` */
+    file: string;
+    /** ID of the sidebar the page belongs to, or null when it sits outside every sidebar root */
+    sidebar: string | null;
+    /** `title` front matter, else the first `# heading`, else the file name */
+    title: string;
+    /** `sidebar_label` front matter: the page's name in navigation (Docusaurus parity) */
+    sidebarLabel?: string;
+    description: string;
+    tags: string[];
+    /** `sidebar_position` front matter */
+    position?: number;
+    /** The page's full front matter, including fields this package doesn't know */
+    frontmatter: FrontmatterData;
+    /** Markdown body (no front matter), links resolved */
+    markdown: string;
+}
+/** A sidebar autogenerated from one directory, as Docusaurus `{type: 'autogenerated', dirName}` does. */
+export interface Sidebar {
+    /** The directory it was generated from (relative to the docs dir), or `default` for the root */
+    id: string;
+    /** The directory, relative to the docs dir ('' for the root) */
+    dir: string;
+    /** `_category_.json` label of the directory, else its name */
+    label: string;
+    /** `_category_.json` position of the directory */
+    position?: number;
+    /** Route of the directory itself */
+    route: string;
+    /** The directory's index page if it has one, else its shallowest, lowest-positioned page */
+    landingRoute: string;
+    items: NavItem[];
+}
+/** A generated-index page (`_category_.json` `link: { type: 'generated-index' }`). */
+export interface CategoryPage {
+    route: string;
+    sidebar: string;
+    title: string;
+    description: string;
+    /** The category's items, in sidebar order */
+    items: NavItem[];
+}
+export interface Tag {
+    id: string;
+    label: string;
+    description: string;
+}
+export interface DocsContent {
+    pages: DocSource[];
+    sidebars: Sidebar[];
+    categories: CategoryPage[];
+    /** The tag vocabulary when one was given, else every tag used, in first-use order */
+    tags: Tag[];
+    /** Non-fatal problems, e.g. broken links when `onBrokenLinks` is `'warn'` */
+    warnings: string[];
+}
+/** A page after `renderDocs`: HTML instead of markdown, plus what layouts and search need. */
+export interface RenderedDoc extends Omit<DocSource, 'markdown'> {
+    html: string;
+    /** Headings with IDs, all levels */
+    toc: TocEntry[];
+    /** Whether the body has its own `<h1>`. When it doesn't, the layout shows `title`. */
+    hasH1: boolean;
+    /** Searchable plain text: the page without markup, code blocks or diagrams */
+    text: string;
+}

package/dist/lib/content/types.js

@@ -0,0 +1,5 @@
+/**
+ * Shapes of the docs content model built by `loadDocs` and `renderDocs`.
+ * Plain data: safe to serialize into a bundle and to import from client code.
+ */
+export {};

package/dist/lib/index.d.ts

@@ -5,11 +5,15 @@
  * with syntax highlighting, frontmatter support, and rich markdown extensions.
  *
  * Supported Markdown Extensions:
- * - Admonitions/Callouts: :::note, :::tip, :::warning, :::important, :::caution
+ * - Admonitions/Callouts: :::note, :::info, :::tip, :::warning, :::important, :::caution, :::danger
  * - Footnotes: [^1] references and [^1]: definitions
  * - Definition Lists: Term followed by : Definition
  * - Mermaid Diagrams: ```mermaid code blocks (rendered client-side)
  *
+ * Node/server code (build scripts, loaders) should import the pipeline from
+ * `@classic-homes/theme-docs/parser`, which has no Svelte imports, and sanitize
+ * rendered HTML with `@classic-homes/theme-docs/sanitize`.
+ *
  * @packageDocumentation
  */
 export { default as MarkdownPage } from './components/MarkdownPage.svelte';
@@ -20,12 +24,20 @@ export { default as TableOfContents } from './components/TableOfContents.svelte'
 export { default as TocPanel } from './components/TocPanel.svelte';
 export { default as MermaidDiagram } from './components/MermaidDiagram.svelte';
 export { default as MermaidInit } from './components/MermaidInit.svelte';
+export { default as DocPage } from './components/DocPage.svelte';
+export { default as CategoryIndex } from './components/CategoryIndex.svelte';
+export { default as Breadcrumbs } from './components/Breadcrumbs.svelte';
+export { default as DocPager } from './components/DocPager.svelte';
+export { default as TagList } from './components/TagList.svelte';
+export { default as TagIndex } from './components/TagIndex.svelte';
 export { mountComponents } from './components/mount.js';
+export { enhanceCodeBlocks, highlightTerms, labelDiagram } from './components/enhance.js';
+export { toSidebarNav, revealActive, type ToSidebarNavOptions } from './components/sidebar.js';
 export type { AuthorInfo, FrontmatterData, ParsedMarkdown, ParseOptions, MarkdownPageProps, } from './types/frontmatter.js';
 export type { DocsItem, DocsSection, DocsHubConfig, DocsHubProps, DocsCardProps, TocEntry, TableOfContentsProps, } from './types/docs.js';
 export { parseMarkdown, extractToc } from './parser/index.js';
 export { createSlugger, type HeadingIdStyle } from './parser/slug.js';
 export { highlightCode, getHighlighter, escapeHtml } from './highlighter/index.js';
 export { cn } from './utils.js';
-export { ADMONITION_TYPES, type AdmonitionType, admonitionExtension, footnoteExtension, definitionListExtension, mermaidExtension, getAllExtensions, resetFootnoteStore, renderFootnotes, } from './parser/extensions.js';
+export { ADMONITION_TYPES, type AdmonitionType, admonitionExtension, footnoteExtension, definitionListExtension, mermaidExtension, componentExtension, getAllExtensions, createFootnoteStore, type FootnoteStore, resetFootnoteStore, renderFootnotes, renderMermaidPlaceholder, } from './parser/extensions.js';
 export { tv, type VariantProps } from 'tailwind-variants';

package/dist/lib/index.js

@@ -5,11 +5,15 @@
  * with syntax highlighting, frontmatter support, and rich markdown extensions.
  *
  * Supported Markdown Extensions:
- * - Admonitions/Callouts: :::note, :::tip, :::warning, :::important, :::caution
+ * - Admonitions/Callouts: :::note, :::info, :::tip, :::warning, :::important, :::caution, :::danger
  * - Footnotes: [^1] references and [^1]: definitions
  * - Definition Lists: Term followed by : Definition
  * - Mermaid Diagrams: ```mermaid code blocks (rendered client-side)
  *
+ * Node/server code (build scripts, loaders) should import the pipeline from
+ * `@classic-homes/theme-docs/parser`, which has no Svelte imports, and sanitize
+ * rendered HTML with `@classic-homes/theme-docs/sanitize`.
+ *
  * @packageDocumentation
  */
 // Components
@@ -21,13 +25,21 @@ export { default as TableOfContents } from './components/TableOfContents.svelte'
 export { default as TocPanel } from './components/TocPanel.svelte';
 export { default as MermaidDiagram } from './components/MermaidDiagram.svelte';
 export { default as MermaidInit } from './components/MermaidInit.svelte';
+export { default as DocPage } from './components/DocPage.svelte';
+export { default as CategoryIndex } from './components/CategoryIndex.svelte';
+export { default as Breadcrumbs } from './components/Breadcrumbs.svelte';
+export { default as DocPager } from './components/DocPager.svelte';
+export { default as TagList } from './components/TagList.svelte';
+export { default as TagIndex } from './components/TagIndex.svelte';
 export { mountComponents } from './components/mount.js';
+export { enhanceCodeBlocks, highlightTerms, labelDiagram } from './components/enhance.js';
+export { toSidebarNav, revealActive } from './components/sidebar.js';
 // Utilities
 export { parseMarkdown, extractToc } from './parser/index.js';
 export { createSlugger } from './parser/slug.js';
 export { highlightCode, getHighlighter, escapeHtml } from './highlighter/index.js';
 export { cn } from './utils.js';
 // Markdown Extensions
-export { ADMONITION_TYPES, admonitionExtension, footnoteExtension, definitionListExtension, mermaidExtension, getAllExtensions, resetFootnoteStore, renderFootnotes, } from './parser/extensions.js';
+export { ADMONITION_TYPES, admonitionExtension, footnoteExtension, definitionListExtension, mermaidExtension, componentExtension, getAllExtensions, createFootnoteStore, resetFootnoteStore, renderFootnotes, renderMermaidPlaceholder, } from './parser/extensions.js';
 // Re-export tailwind-variants types for consumer convenience
 export { tv } from 'tailwind-variants';

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

@@ -0,0 +1,12 @@
+/**
+ * `@classic-homes/theme-docs/parser` — the markdown pipeline without any Svelte imports.
+ *
+ * Safe to load in Node (build scripts, server loaders, workers) and in non-Svelte bundles
+ * such as a CMS preview. The package root re-exports all of this alongside the components.
+ */
+export { parseMarkdown, extractToc } from './index.js';
+export { createSlugger, type HeadingIdStyle } from './slug.js';
+export { ADMONITION_TYPES, type AdmonitionType, admonitionExtension, footnoteExtension, definitionListExtension, mermaidExtension, componentExtension, getAllExtensions, createFootnoteStore, type FootnoteStore, resetFootnoteStore, renderFootnotes, renderMermaidPlaceholder, } from './extensions.js';
+export { highlightCode, getHighlighter, escapeHtml } from '../highlighter/index.js';
+export type { AuthorInfo, FrontmatterData, ParsedMarkdown, ParseOptions, } from '../types/frontmatter.js';
+export type { TocEntry } from '../types/docs.js';

package/dist/lib/parser/api.js

@@ -0,0 +1,10 @@
+/**
+ * `@classic-homes/theme-docs/parser` — the markdown pipeline without any Svelte imports.
+ *
+ * Safe to load in Node (build scripts, server loaders, workers) and in non-Svelte bundles
+ * such as a CMS preview. The package root re-exports all of this alongside the components.
+ */
+export { parseMarkdown, extractToc } from './index.js';
+export { createSlugger } from './slug.js';
+export { ADMONITION_TYPES, admonitionExtension, footnoteExtension, definitionListExtension, mermaidExtension, componentExtension, getAllExtensions, createFootnoteStore, resetFootnoteStore, renderFootnotes, renderMermaidPlaceholder, } from './extensions.js';
+export { highlightCode, getHighlighter, escapeHtml } from '../highlighter/index.js';

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

@@ -8,7 +8,7 @@
  * - Mermaid diagram placeholders (rendered client-side)
  * - Component placeholders for allowlisted `<Name prop="…" />` tags (mounted client-side)
  */
-import type { MarkedExtension } from 'marked';
+import type { MarkedExtension, Tokens } from 'marked';
 /**
  * Admonition types and their corresponding icons/classes
  */
@@ -34,7 +34,24 @@ export type AdmonitionType = (typeof ADMONITION_TYPES)[number];
  */
 export declare function admonitionExtension(): MarkedExtension;
 /**
- * Reset footnote store (call before parsing a new document)
+ * Footnotes collected while parsing one document.
+ *
+ * Each `parseMarkdown` call creates its own store, so concurrent parses (e.g. a server
+ * rendering many pages at once) never mix up each other's footnotes.
+ */
+export interface FootnoteStore {
+    definitions: Map<string, {
+        content: string;
+        tokens: Tokens.Generic[];
+    }>;
+    references: Set<string>;
+}
+export declare function createFootnoteStore(): FootnoteStore;
+/**
+ * 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 declare function resetFootnoteStore(): void;
 /**
@@ -45,23 +62,16 @@ export declare function resetFootnoteStore(): void;
  *
  * [^1]: This is the footnote content.
  */
-export declare function footnoteExtension(): MarkedExtension;
+export declare function footnoteExtension(store?: FootnoteStore): MarkedExtension;
 /**
  * Render collected footnotes as a section
  * Call this after parsing to get the footnotes HTML
- */
-export declare function renderFootnotes(): string;
-/**
- * Definition list extension for marked
- *
- * Syntax:
- * Term 1
- * : Definition for term 1
  *
- * Term 2
- * : Definition for term 2
- * : Another definition for term 2
+ * @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 declare function renderFootnotes(store?: FootnoteStore, renderInline?: (tokens: Tokens.Generic[]) => string): string;
 export declare function definitionListExtension(): MarkedExtension;
 /**
  * Mermaid code block extension for marked
@@ -75,6 +85,7 @@ export declare function definitionListExtension(): MarkedExtension;
  *   A --> B
  * ```
  */
+export declare function renderMermaidPlaceholder(code: string): string;
 export declare function mermaidExtension(): MarkedExtension;
 /**
  * Component placeholder extension for marked
@@ -93,5 +104,6 @@ export declare function componentExtension(names: readonly string[]): MarkedExte
  * 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 declare function getAllExtensions(components?: readonly string[]): MarkedExtension[];
+export declare function getAllExtensions(components?: readonly string[], footnotes?: FootnoteStore): MarkedExtension[];

package/dist/lib/parser/extensions.js

@@ -76,13 +76,13 @@ export function admonitionExtension() {
                     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>`,
-                        info: `<svg class="admonition-icon" 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" 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>`,
-                        danger: `<svg class="admonition-icon" 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>`,
+                        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">
@@ -96,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
@@ -117,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
@@ -141,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;
@@ -162,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],
@@ -172,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>`;
                 },
             },
         ],
@@ -181,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: [
@@ -254,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,
@@ -265,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>`;
@@ -287,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: [
@@ -294,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',
@@ -308,16 +321,7 @@ 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);
                 },
             },
         ],
@@ -367,11 +371,12 @@ export function componentExtension(names) {
  * 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(components = []) {
+export function getAllExtensions(components = [], footnotes) {
     return [
         admonitionExtension(),
-        footnoteExtension(),
+        footnoteExtension(footnotes),
         definitionListExtension(),
         mermaidExtension(),
         ...(components.length > 0 ? [componentExtension(components)] : []),

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

@@ -18,8 +18,11 @@ import type { ParsedMarkdown, ParseOptions } from '../types/index.js';
  * @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)
  * @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`)
- * @returns Parsed markdown with frontmatter data, cleaned markdown, and rendered HTML
+ * @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