@classic-homes/theme-docs 0.1.0 → 0.3.0

package/dist/lib/parser/index.js

@@ -1,7 +1,7 @@
-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) {
@@ -56,8 +56,11 @@ function extractFrontmatter(content) {
  * @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
@@ -75,32 +78,34 @@ function extractFrontmatter(content) {
  * ```
  */
 export async function parseMarkdown(content, options = {}) {
-    const { theme = 'github-dark', generateHeadingIds = true, headingIdStyle = 'default', components = [], } = 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) {
         const slug = createSlugger(headingIdStyle);
@@ -108,22 +113,44 @@ export async function parseMarkdown(content, options = {}) {
             // 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];
-            const id = slug(decodeEntities(plain.replace(EXPLICIT_ID_PATTERN, '')), explicitId);
+            // 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
             const inner = this.parser.parseInline(tokens).replace(EXPLICIT_ID_PATTERN, '');
-            return `<h${depth} id="${escapeHtml(id)}">${inner}</h${depth}>`;
+            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(components));
+    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;
     }
@@ -131,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.
  *
@@ -161,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/sanitize/index.d.ts

@@ -0,0 +1,11 @@
+export interface SanitizeResult {
+    /** The cleaned HTML */
+    html: string;
+    /**
+     * What was removed, e.g. `<script>`, `p[onclick]`, `a[href=javascript:]`. Report these
+     * from a build so a page that loses markup says so instead of quietly rendering differently.
+     */
+    removed: string[];
+}
+/** Sanitize one page's rendered HTML. */
+export declare function sanitizeDocsHtml(html: string): SanitizeResult;

package/dist/lib/sanitize/index.js

@@ -0,0 +1,122 @@
+/**
+ * `@classic-homes/theme-docs/sanitize` — allowlist sanitizer for HTML from `parseMarkdown`.
+ *
+ * `parseMarkdown` passes raw HTML in markdown straight through. When pages are written by
+ * more than a few trusted people (a git repo with many authors, a browser editor), run its
+ * output through `sanitizeDocsHtml` so markup cannot run script, embed frames or set event
+ * handlers for every reader.
+ *
+ * The allowlist is what the parser itself produces — GFM tables and task lists, footnotes,
+ * definition lists, Shiki highlighting, admonition icons, heading permalinks, mermaid and
+ * component placeholders — plus the safe inline HTML authors commonly write
+ * (details/summary, kbd, sub/sup, br, mark).
+ *
+ * Server/build-time only: it depends on `sanitize-html` (and through it, postcss), which
+ * you don't want in a browser bundle.
+ */
+import sanitizeHtml from 'sanitize-html';
+const SVG = ['svg', 'path', 'circle', 'line', 'polyline', 'polygon', 'rect', 'g'];
+const OPTIONS = {
+    allowedTags: [
+        ...sanitizeHtml.defaults.allowedTags, // p, a, lists, tables, code, pre, headings, blockquote, …
+        'img',
+        'details',
+        'summary',
+        'kbd',
+        'sup',
+        'sub',
+        'del',
+        's',
+        'ins',
+        'mark',
+        'dl',
+        'dt',
+        'dd',
+        'section',
+        'input',
+        'br',
+        'hr',
+        ...SVG,
+    ],
+    allowedAttributes: {
+        '*': ['class', 'id', 'title', 'aria-hidden', 'aria-label', 'role'],
+        a: ['href', 'name', 'target', 'rel'],
+        img: ['src', 'alt', 'width', 'height', 'loading', 'decoding'],
+        pre: ['style', 'tabindex'],
+        span: ['style'],
+        code: ['style'],
+        div: ['data-component', 'data-props', 'data-mermaid'],
+        input: ['type', 'checked', 'disabled'],
+        ol: ['start', 'type'],
+        td: ['align', 'colspan', 'rowspan'],
+        th: ['align', 'colspan', 'rowspan', 'scope'],
+        details: ['open'],
+        svg: [
+            'viewBox',
+            'fill',
+            'stroke',
+            'stroke-width',
+            'stroke-linecap',
+            'stroke-linejoin',
+            'width',
+            'height',
+            'xmlns',
+        ],
+        path: ['d', 'fill', 'stroke'],
+        circle: ['cx', 'cy', 'r', 'fill', 'stroke'],
+        line: ['x1', 'x2', 'y1', 'y2'],
+        polyline: ['points'],
+        polygon: ['points'],
+        rect: ['x', 'y', 'width', 'height', 'rx', 'ry'],
+    },
+    // Shiki colours code by inline style; nothing else may set styles.
+    allowedStyles: {
+        '*': {
+            color: [/^#[0-9a-f]{3,8}$/i, /^var\(--[\w-]+\)$/],
+            'background-color': [/^#[0-9a-f]{3,8}$/i, /^var\(--[\w-]+\)$/],
+            'font-style': [/^italic$/],
+            'font-weight': [/^(bold|\d{3})$/],
+            'text-decoration': [/^(underline|line-through)$/],
+        },
+    },
+    allowedSchemes: ['http', 'https', 'mailto', 'tel'],
+    allowProtocolRelative: false,
+    // Keep the text of a dropped element (e.g. an unknown wrapper) but never of script/style.
+    disallowedTagsMode: 'discard',
+    nonTextTags: ['script', 'style', 'textarea', 'option', 'noscript', 'iframe', 'object', 'embed'],
+    parser: { lowerCaseAttributeNames: false },
+};
+const SVG_TAGS = new Set(SVG);
+const allowedTags = new Set(OPTIONS.allowedTags);
+const allowedAttributes = OPTIONS.allowedAttributes;
+const allowedAttrs = (tag) => [
+    ...allowedAttributes['*'],
+    ...(allowedAttributes[tag] ?? []),
+];
+/** Sanitize one page's rendered HTML. */
+export function sanitizeDocsHtml(html) {
+    const removed = new Set();
+    const clean = sanitizeHtml(html, {
+        ...OPTIONS,
+        transformTags: {
+            '*': (tagName, rawAttribs) => {
+                // HTML attribute names are case-insensitive, and content written as MDX uses JSX
+                // casing (`colSpan`, `rowSpan`). Lowercase them so the allowlist matches; SVG keeps
+                // its case-sensitive names (`viewBox`).
+                const attribs = SVG_TAGS.has(tagName)
+                    ? rawAttribs
+                    : Object.fromEntries(Object.entries(rawAttribs).map(([name, value]) => [name.toLowerCase(), value]));
+                if (!allowedTags.has(tagName))
+                    removed.add(`<${tagName}>`);
+                else
+                    for (const name of Object.keys(attribs))
+                        if (!allowedAttrs(tagName).includes(name))
+                            removed.add(`${tagName}[${name}]`);
+                if (attribs.href && /^\s*(javascript|data|vbscript):/i.test(attribs.href))
+                    removed.add(`${tagName}[href=${attribs.href.split(':')[0].trim()}:]`);
+                return { tagName, attribs };
+            },
+        },
+    });
+    return { html: clean, removed: [...removed] };
+}

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

@@ -0,0 +1,57 @@
+/**
+ * `@classic-homes/theme-docs/search` — full-text search over rendered docs (MiniSearch).
+ *
+ * Build the index at build time with `buildSearchIndex`, ship its JSON, and query it on
+ * the server or in the browser with `createSearch`. A `filter` runs inside MiniSearch,
+ * before results and snippets are built, so access rules can drop hits a reader may not
+ * see without their text ever leaving the index.
+ */
+import { type Options } from 'minisearch';
+import type { RenderedDoc } from '../content/types.js';
+/** Fields stored with each hit, available to `filter` and in results. */
+export interface StoredFields {
+    title: string;
+    description: string;
+    sidebar: string | null;
+}
+/**
+ * Index options. `buildSearchIndex` and `createSearch` must use the same ones, so both
+ * read them from here.
+ */
+export declare const SEARCH_OPTIONS: Options;
+type Indexable = Pick<RenderedDoc, 'route' | 'title' | 'description' | 'sidebar' | 'toc' | 'text'>;
+/** Index every page. Returns MiniSearch's serialized form; write it out as JSON. */
+export declare function buildSearchIndex(pages: Indexable[]): string;
+export interface SearchHit {
+    route: string;
+    title: string;
+    description: string;
+    sidebar: string | null;
+    /** About 160 characters of the page around the first match (or its description) */
+    snippet: string;
+    /** Terms that matched, for highlighting */
+    terms: string[];
+    score: number;
+}
+export interface SearchQueryOptions {
+    /** Keep a hit only when this returns true. Runs before snippets are built. */
+    filter?: (hit: StoredFields & {
+        route: string;
+    }) => boolean;
+    /** Maximum hits. Default: 12 */
+    limit?: number;
+    /** Queries shorter than this return nothing. Default: 2 */
+    minLength?: number;
+}
+/**
+ * Load a serialized index for querying.
+ *
+ * @param indexJson - What `buildSearchIndex` returned (string or parsed object)
+ * @param texts - Page text by route, for snippets. Without it, snippets use descriptions.
+ */
+export declare function createSearch(indexJson: string | object, texts?: Map<string, string> | Record<string, string>): {
+    search(query: string, options?: SearchQueryOptions): SearchHit[];
+};
+/** About 160 characters around the first matched term, cut at word boundaries. */
+export declare function snippet(text: string, terms: string[]): string;
+export {};

package/dist/lib/search/index.js

@@ -0,0 +1,107 @@
+/**
+ * `@classic-homes/theme-docs/search` — full-text search over rendered docs (MiniSearch).
+ *
+ * Build the index at build time with `buildSearchIndex`, ship its JSON, and query it on
+ * the server or in the browser with `createSearch`. A `filter` runs inside MiniSearch,
+ * before results and snippets are built, so access rules can drop hits a reader may not
+ * see without their text ever leaving the index.
+ */
+import MiniSearch from 'minisearch';
+/**
+ * Index options. `buildSearchIndex` and `createSearch` must use the same ones, so both
+ * read them from here.
+ */
+export const SEARCH_OPTIONS = {
+    fields: ['title', 'headings', 'description', 'text'],
+    storeFields: ['title', 'description', 'sidebar'],
+    searchOptions: {
+        boost: { title: 4, headings: 2, description: 1.5 },
+        prefix: true,
+        fuzzy: 0.15,
+        combineWith: 'AND',
+    },
+};
+/** Index every page. Returns MiniSearch's serialized form; write it out as JSON. */
+export function buildSearchIndex(pages) {
+    const index = new MiniSearch(SEARCH_OPTIONS);
+    index.addAll(pages.map((page) => ({
+        id: page.route,
+        title: page.title,
+        description: page.description,
+        sidebar: page.sidebar,
+        headings: page.toc.map((entry) => entry.text).join(' '),
+        text: page.text,
+    })));
+    return JSON.stringify(index);
+}
+/**
+ * Load a serialized index for querying.
+ *
+ * @param indexJson - What `buildSearchIndex` returned (string or parsed object)
+ * @param texts - Page text by route, for snippets. Without it, snippets use descriptions.
+ */
+export function createSearch(indexJson, texts) {
+    const index = MiniSearch.loadJSON(typeof indexJson === 'string' ? indexJson : JSON.stringify(indexJson), SEARCH_OPTIONS);
+    const textOf = (route) => texts instanceof Map ? texts.get(route) : texts?.[route];
+    return {
+        search(query, options = {}) {
+            const { filter, limit = 12, minLength = 2 } = options;
+            const trimmed = query.trim();
+            if (trimmed.length < minLength)
+                return [];
+            const results = index.search(trimmed, {
+                ...(filter && {
+                    filter: (hit) => filter({ ...hit, route: String(hit.id) }),
+                }),
+            });
+            return results.slice(0, limit).map((hit) => {
+                const route = String(hit.id);
+                const stored = hit;
+                return {
+                    route,
+                    title: stored.title,
+                    description: stored.description,
+                    sidebar: stored.sidebar,
+                    snippet: snippet(withoutTitle(textOf(route), stored.title) ?? stored.description ?? '', hit.terms),
+                    terms: hit.terms,
+                    score: hit.score,
+                };
+            });
+        },
+    };
+}
+/**
+ * A page's text minus its leading title: the body's `# Title` heading is the first thing in
+ * the text, and the result already shows the title, so a snippet would repeat it.
+ */
+function withoutTitle(text, title) {
+    if (!text || !title || !text.startsWith(title))
+        return text;
+    return text.slice(title.length).trimStart();
+}
+/** About 160 characters around the first matched term, cut at word boundaries. */
+export function snippet(text, terms) {
+    const lower = text.toLowerCase();
+    const at = Math.min(...terms.map((term) => lower.indexOf(term.toLowerCase())).filter((i) => i >= 0));
+    if (!Number.isFinite(at))
+        return clip(text, 0, 160);
+    return clip(text, Math.max(0, at - 60), Math.max(0, at - 60) + 160, at);
+}
+/** `text[start, end)` widened or narrowed to whole words (never past `keep`), with ellipses. */
+function clip(text, start, end, keep = start) {
+    if (start > 0) {
+        // Start after the space before the cut, so the snippet opens on a whole word.
+        const space = text.indexOf(' ', start);
+        if (space >= 0 && space < keep)
+            start = space + 1;
+    }
+    if (end < text.length) {
+        const space = text.lastIndexOf(' ', end);
+        if (space > keep)
+            end = space;
+    }
+    else {
+        end = text.length;
+    }
+    return `${start > 0 ? '…' : ''}${text.slice(start, end).trim()}${end < text.length ? '…' : ''}`;
+}

package/dist/lib/styles/markdown.css

@@ -272,6 +272,135 @@
   border-top-right-radius: 0;
 }
 
+/* Fence titles (```bash title="install.sh") rendered by parseMarkdown */
+.markdown-content .code-block-filename {
+  padding: 0.5rem 1rem;
+  font-size: 0.875rem;
+  font-family:
+    ui-monospace, SFMono-Regular, 'SF Mono', Menlo, Consolas, 'Liberation Mono', monospace;
+  color: hsl(var(--muted-foreground));
+  background-color: hsl(var(--muted) / 0.5);
+  border: 1px solid hsl(var(--border));
+  border-bottom: 0;
+  border-top-left-radius: 0.5rem;
+  border-top-right-radius: 0.5rem;
+}
+
+/* Copy buttons (enhanceCodeBlocks / DocPage) */
+.code-block-wrapper.has-copy-button {
+  position: relative;
+}
+
+.code-copy-button {
+  position: absolute;
+  top: 0.5rem;
+  right: 0.5rem;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: 2rem;
+  height: 2rem;
+  padding: 0.375rem;
+  border-radius: 0.375rem;
+  border: 1px solid hsl(0 0% 100% / 0.2);
+  background-color: hsl(0 0% 0% / 0.4);
+  color: hsl(0 0% 100% / 0.85);
+  cursor: pointer;
+  opacity: 0;
+  transition: opacity 150ms;
+}
+
+.code-block-filename + .shiki + .code-copy-button {
+  top: calc(0.5rem + 2.3rem);
+}
+
+.code-block-wrapper:hover .code-copy-button,
+.code-copy-button:focus-visible,
+.code-copy-button[data-copied] {
+  opacity: 1;
+}
+
+.code-copy-button:focus-visible {
+  outline: 2px solid hsl(var(--ring));
+  outline-offset: 2px;
+}
+
+.code-copy-button svg {
+  width: 100%;
+  height: 100%;
+}
+
+@media (hover: none) {
+  .code-copy-button {
+    opacity: 1;
+  }
+}
+
+.docs-sr-only {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  margin: -1px;
+  overflow: hidden;
+  clip: rect(0, 0, 0, 0);
+  white-space: nowrap;
+}
+
+/* Search terms carried over from a search result (?highlight=) */
+.markdown-content mark.search-highlight {
+  background-color: hsl(var(--warning) / 0.35);
+  color: inherit;
+  border-radius: 0.125rem;
+  padding: 0 0.0625rem;
+}
+
+/* ==========================================================================
+   Heading permalinks (headingAnchors option)
+   ========================================================================== */
+
+/* Anchor targets clear a fixed header when jumped to (DocPage sets the variable) */
+.markdown-content [id] {
+  scroll-margin-top: var(--docs-header-offset, 5rem);
+}
+
+.markdown-content .hash-link {
+  margin-left: 0.5rem;
+  color: hsl(var(--primary));
+  text-decoration: none;
+  opacity: 0;
+}
+
+.markdown-content .hash-link::before {
+  content: '#';
+}
+
+.markdown-content :is(h1, h2, h3, h4, h5, h6):hover .hash-link,
+.markdown-content .hash-link:focus-visible {
+  opacity: 1;
+}
+
+/* ==========================================================================
+   External links (externalLinks option)
+   ========================================================================== */
+
+.markdown-content .external-link::after {
+  content: '\2197';
+  margin-left: 0.125rem;
+  font-size: 0.75em;
+}
+
+.markdown-content .external-link-hint {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  padding: 0;
+  margin: -1px;
+  overflow: hidden;
+  clip: rect(0, 0, 0, 0);
+  white-space: nowrap;
+  border: 0;
+}
+
 /* ==========================================================================
    Admonitions / Callouts
    ========================================================================== */
@@ -477,6 +606,15 @@
   height: auto;
 }
 
+/* Mermaid writes a diagram's classDef names onto its SVG nodes, so a diagram
+   with `classDef hidden …` gets nodes classed `hidden` — which Tailwind's
+   .hidden utility collapses. Not scoped to .markdown-content: mermaid measures
+   labels in a temporary SVG appended to <body> before placing the diagram. */
+svg g.node.hidden,
+svg g.cluster.hidden {
+  display: inline;
+}
+
 .markdown-content .mermaid-diagram pre.mermaid {
   margin: 0;
   padding: 0;

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

@@ -50,6 +50,12 @@ export interface ParsedMarkdown {
     markdown: string;
     /** Rendered HTML content */
     html: string;
+    /** Every heading with an ID, in document order (all levels; filter by `level` as needed) */
+    toc: {
+        text: string;
+        level: number;
+        id: string;
+    }[];
 }
 /** Parser options */
 export interface ParseOptions {
@@ -67,6 +73,21 @@ export interface ParseOptions {
      * line of its own (`<RequestForm id="x" />`). Mount them with `mountComponents`.
      */
     components?: readonly string[];
+    /** Append a `#` permalink (`a.hash-link`) to each heading, as Docusaurus does. Default: false */
+    headingAnchors?: boolean;
+    /**
+     * Open `http(s)` links in a new tab with a visually hidden "(opens in new tab)" note.
+     * `true` uses `target="_blank" rel="noopener noreferrer"`. Default: false
+     */
+    externalLinks?: boolean | {
+        target?: string;
+        rel?: string;
+    };
+    /**
+     * Map code fence names to Shiki languages, e.g. `{ ios: 'text', caddyfile: 'nginx' }`.
+     * Languages Shiki doesn't know render as plain code.
+     */
+    langAlias?: Record<string, string>;
 }
 /** MarkdownPage component props */
 export interface MarkdownPageProps {