@pterodoc/core 0.2.0

package/lib/render/index.js

@@ -0,0 +1,1336 @@
+import matter from 'gray-matter';
+import { unified } from 'unified';
+import remarkParse from 'remark-parse';
+import remarkGfm from 'remark-gfm';
+import remarkDirective from 'remark-directive';
+import remarkFrontmatter from 'remark-frontmatter';
+import remarkMdx from 'remark-mdx';
+import { visit } from 'unist-util-visit';
+import path from 'node:path';
+import { toHast } from 'mdast-util-to-hast';
+import { toHtml } from 'hast-util-to-html';
+import GithubSlugger from 'github-slugger';
+import { toString } from 'mdast-util-to-string';
+import { I as IssueCollector } from '../chunks/issues-DBsPh6ek.js';
+import fs from 'node:fs';
+
+/**
+ * Gutenberg block serialisation.
+ *
+ * WordPress stores post content as HTML annotated with block comments, and the
+ * editor re-parses that markup and compares it with what the block's own save
+ * function would produce. Everything here therefore follows core's output
+ * closely: the attribute encoding, the class names and the whitespace.
+ */
+/**
+ * Encode block attributes the way WordPress encodes them, so the editor sees
+ * markup it would have written itself.
+ */
+function serializeAttrs(attributes) {
+    return JSON.stringify(attributes)
+        .replace(/--/g, '\\u002d\\u002d')
+        .replace(/</g, '\\u003c')
+        .replace(/>/g, '\\u003e')
+        .replace(/&/g, '\\u0026')
+        .replace(/\\"/g, '\\u0022');
+}
+/**
+ * Wrap inner markup in a block comment pair.
+ *
+ * @param name Block name without the `core/` prefix.
+ * @param attributes Omitted from the output when empty.
+ * @param inner The block's stored markup.
+ */
+function serializeBlock(name, attributes, inner) {
+    const attrs = attributes && Object.keys(attributes).length > 0 ? ` ${serializeAttrs(attributes)}` : '';
+    return `<!-- wp:${name}${attrs} -->\n${inner}\n<!-- /wp:${name} -->`;
+}
+/**
+ * A dynamic block: it renders on the server and stores no inner markup.
+ */
+function serializeVoidBlock(name, attributes) {
+    const attrs = attributes && Object.keys(attributes).length > 0 ? ` ${serializeAttrs(attributes)}` : '';
+    return `<!-- wp:${name}${attrs} /-->`;
+}
+/** Join sibling blocks the way WordPress does. */
+function joinBlocks(blocks) {
+    return blocks.filter((block) => typeof block === 'string' && block !== '').join('\n\n');
+}
+/**
+ * Escape text destined for a `<code>` element.
+ *
+ * `[` becomes an entity because WordPress expands shortcodes inside code as
+ * happily as anywhere else, and documentation is full of bracketed samples.
+ */
+function escapeCode(text) {
+    return text
+        .replace(/&/g, '&amp;')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+        .replace(/\[/g, '&#91;');
+}
+/** Escape text for use in an HTML text node or attribute value. */
+function escapeText(text) {
+    return String(text)
+        .replace(/&/g, '&amp;')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+        .replace(/"/g, '&quot;')
+        .replace(/\[/g, '&#91;');
+}
+
+/** Summaries used for excerpts, SEO descriptions and index listings. */
+/**
+ * Shorten text to at most `max` characters, breaking on a word.
+ *
+ * @param text The full text.
+ * @param max Longest result, before the ellipsis.
+ */
+function excerptFrom(text, max = 160) {
+    const clean = String(text ?? '').replace(/\s+/g, ' ').trim();
+    if (clean.length <= max)
+        return clean;
+    const cut = clean.slice(0, max);
+    const lastSpace = cut.lastIndexOf(' ');
+    const kept = lastSpace > max * 0.6 ? cut.slice(0, lastSpace) : cut;
+    return `${kept.replace(/[\s,;:.]+$/, '')}…`;
+}
+
+/**
+ * Page composition: the navigation and layout wrapped around a rendered body.
+ *
+ * This module deliberately describes the page tree structurally rather than
+ * importing it, so the renderer stays independent of where the model came from
+ * and of where the page is going.
+ */
+/** The layout used when a site configures none. */
+const DEFAULT_LAYOUT = {
+    kind: 'two-column',
+    navWidth: '25%',
+    mainWidth: '75%',
+    align: '',
+    nav: 'page-list',
+    breadcrumb: true,
+    pagination: true,
+    childIndex: 'auto',
+};
+/** A short summary of a page, for an index listing. */
+function summaryOf(node, theme) {
+    if (node.description)
+        return excerptFrom(node.description, 140);
+    const count = node.children.length;
+    if (count === 1)
+        return theme.text('pageCountOne');
+    if (count > 1)
+        return theme.text('pageCount', { count });
+    return '';
+}
+/** The trail of links back to the root. */
+function renderBreadcrumb(input) {
+    const trail = [];
+    for (let current = input.node.parent; current; current = current.parent)
+        trail.unshift(current);
+    if (trail.length === 0)
+        return '';
+    const links = trail.map((ancestor) => `<a href="${input.href(ancestor.path)}">${escapeText(ancestor.title)}</a>`);
+    links.push(escapeText(input.node.title));
+    const className = input.theme.cls('docs-breadcrumb');
+    // Marked up, the plugin can swap the separator for a configured one exactly
+    // rather than by guessing which run of text between two links is one. Left
+    // bare, it is the same characters it has always been.
+    const separator = escapeText(input.theme.strings.breadcrumbSeparator);
+    const joined = input.theme.blocks === 'plugin'
+        ? links.join(`<span class="${input.theme.cls('breadcrumb-separator')}">${separator}</span>`)
+        : links.join(separator);
+    return serializeBlock('group', { className }, `<div class="wp-block-group ${className}">${serializeBlock('paragraph', undefined, `<p>${joined}</p>`)}</div>`);
+}
+/** Previous and next links, following the site's own order. */
+function renderPagination(input) {
+    const previous = input.node.previousPath === undefined ? undefined : input.lookup(input.node.previousPath);
+    const next = input.node.nextPath === undefined ? undefined : input.lookup(input.node.nextPath);
+    if (!previous && !next)
+        return '';
+    const parts = [];
+    if (previous) {
+        const className = input.theme.cls('docs-pagination-prev');
+        parts.push(serializeBlock('paragraph', { className }, `<p class="${className}"><a href="${input.href(previous.path)}">${escapeText(input.theme.text('previous', { title: previous.title }))}</a></p>`));
+    }
+    if (next) {
+        const className = input.theme.cls('docs-pagination-next');
+        parts.push(serializeBlock('paragraph', { className }, `<p class="${className}"><a href="${input.href(next.path)}">${escapeText(input.theme.text('next', { title: next.title }))}</a></p>`));
+    }
+    const className = input.theme.cls('docs-pagination');
+    return serializeBlock('group', { className }, `<div class="wp-block-group ${className}">${joinBlocks(parts)}</div>`);
+}
+/** A list of the pages below this one, grouped as the sidebar grouped them. */
+function renderChildIndex(input, heading) {
+    const { node, theme } = input;
+    if (node.children.length === 0)
+        return '';
+    const parts = [];
+    if (heading) {
+        const className = theme.cls('docs-index-heading');
+        parts.push(serializeBlock('heading', { className }, `<h2 class="wp-block-heading ${className}" id="in-this-section">${escapeText(heading)}</h2>`));
+    }
+    for (const section of node.sections.length > 0 ? node.sections : [{ label: undefined, children: node.children }]) {
+        if (section.label) {
+            parts.push(serializeBlock('heading', { level: 3 }, `<h3 class="wp-block-heading">${escapeText(section.label)}</h3>`));
+        }
+        const items = section.children
+            .map((child) => {
+            const summary = summaryOf(child, theme);
+            const link = `<a href="${input.href(child.path)}">${escapeText(child.title)}</a>`;
+            return serializeBlock('list-item', undefined, `<li>${link}${summary ? ` — ${escapeText(summary)}` : ''}</li>`);
+        })
+            .join('\n\n');
+        const className = theme.cls('docs-index');
+        parts.push(serializeBlock('list', { className }, `<ul class="wp-block-list ${className}">${items}</ul>`));
+    }
+    return joinBlocks(parts);
+}
+/** The navigation column's contents. */
+function renderNavigation(input) {
+    if (input.layout.nav === 'none')
+        return '';
+    return serializeVoidBlock('page-list', { parentPageID: input.navRootId ?? 0 });
+}
+/** Compose the stored content of one page. */
+function composePage(input) {
+    const { node, theme, layout } = input;
+    let index = '';
+    if (node.children.length > 0 && layout.childIndex !== 'never') {
+        // A page that already links all of its children does not need a generated
+        // list; one that links none of them does.
+        const linksAllChildren = node.children.every((child) => input.links.has(child.path));
+        if (layout.childIndex === 'always' || !linksAllChildren) {
+            index = renderChildIndex(input, input.body ? theme.text('indexHeading') : '');
+        }
+    }
+    const main = joinBlocks([
+        input.banner ?? '',
+        layout.breadcrumb ? renderBreadcrumb(input) : '',
+        input.body,
+        index,
+        layout.pagination ? renderPagination(input) : '',
+    ]);
+    if (layout.kind === 'single' || layout.nav === 'none')
+        return main;
+    const navClass = theme.cls('docs-nav');
+    const mainClass = theme.cls('docs-main');
+    const navColumn = serializeBlock('column', { width: layout.navWidth, className: navClass }, `<div class="wp-block-column ${navClass}" style="flex-basis:${layout.navWidth}">${renderNavigation(input)}</div>`);
+    const mainColumn = serializeBlock('column', { width: layout.mainWidth, className: mainClass }, `<div class="wp-block-column ${mainClass}" style="flex-basis:${layout.mainWidth}">${main}</div>`);
+    const columnsClass = theme.cls('docs');
+    const attributes = { className: columnsClass };
+    if (layout.align)
+        attributes['align'] = layout.align;
+    const alignClass = layout.align ? ` align${layout.align}` : '';
+    return serializeBlock('columns', attributes, `<div class="wp-block-columns${alignClass} ${columnsClass}">${navColumn}\n\n${mainColumn}</div>`);
+}
+/** Body for a path segment that exists only so the documentation has a parent. */
+function renderNavigationStub(selfId) {
+    return serializeVoidBlock('page-list', { parentPageID: selfId });
+}
+/** A notice shown on every page of a version that is not the current one. */
+function renderVersionBanner(theme, label, kind) {
+    const className = `${theme.cls('version-banner')} ${theme.cls(`version-banner-${kind}`)}`;
+    return serializeBlock('group', { className }, `<div class="wp-block-group ${className}">${serializeBlock('paragraph', undefined, `<p>${escapeText(theme.text('versionBanner', { label }))}</p>`)}</div>`);
+}
+
+/**
+ * Every class name and every human-readable string the renderer emits.
+ *
+ * Kept in one place so a site can restyle the output without patching the
+ * renderer, and so a non-English site can translate it.
+ */
+/** The strings used when a site configures none. */
+const DEFAULT_STRINGS = {
+    indexHeading: 'In this section',
+    breadcrumbSeparator: ' › ',
+    previous: '← {title}',
+    next: '{title} →',
+    documentation: 'Documentation',
+    pageCount: '{count} pages',
+    pageCountOne: '1 page',
+    versionBanner: 'This is documentation for {label}.',
+    unsupportedNotice: 'Content omitted: {what}',
+};
+/**
+ * Build a theme.
+ *
+ * @param options Class prefix and any string overrides.
+ */
+function createTheme(options = {}) {
+    const classPrefix = options.classPrefix ?? 'pterodoc';
+    const strings = { ...DEFAULT_STRINGS, ...options.strings };
+    return {
+        classPrefix,
+        blocks: options.blocks ?? 'core',
+        strings,
+        cls(name) {
+            return `${classPrefix}-${name}`;
+        },
+        text(key, values = {}) {
+            return strings[key].replace(/\{(\w+)\}/g, (match, name) => name in values ? String(values[name]) : match);
+        },
+    };
+}
+
+/**
+ * Markdown and MDX parsing.
+ *
+ * Two processors, built once and reused: Docusaurus decides per document
+ * whether a file is plain markdown or MDX, and the model carries that decision
+ * so it is never guessed here.
+ */
+/** Extensions Docusaurus treats as plain markdown when `format: 'detect'`. */
+const PLAIN_EXTENSIONS = new Set([
+    '.md',
+    '.markdown',
+    '.mdown',
+    '.mkdn',
+    '.mkd',
+    '.mdwn',
+    '.mkdown',
+    '.ron',
+]);
+/**
+ * Resolve `format: 'detect'` the way Docusaurus does: by extension.
+ *
+ * @param filePath Path of the source file.
+ */
+function detectFormat(filePath) {
+    const dot = filePath.lastIndexOf('.');
+    const extension = dot === -1 ? '' : filePath.slice(dot).toLowerCase();
+    return PLAIN_EXTENSIONS.has(extension) ? 'md' : 'mdx';
+}
+const base = () => unified()
+    .use(remarkParse)
+    .use(remarkFrontmatter, ['yaml'])
+    .use(remarkGfm)
+    .use(remarkDirective);
+const markdownProcessor = base();
+const mdxProcessor = base().use(remarkMdx);
+/**
+ * Parse a document body.
+ *
+ * Only the parser runs: no transformers, no compiler. The tree is what the
+ * rest of the renderer works on.
+ *
+ * @param markdown The body, with front matter already removed.
+ * @param format Which flavour to parse as.
+ */
+function parseMarkdown(markdown, format = 'md') {
+    const processor = format === 'mdx' ? mdxProcessor : markdownProcessor;
+    return processor.parse(markdown);
+}
+
+/**
+ * Reference-style links and images.
+ *
+ * `[text][ref]` with a `[ref]: ./target.md` definition elsewhere only works if
+ * something joins the two. Doing it here, as a pre-pass over the whole
+ * document, means the rest of the renderer never sees a reference node and the
+ * definitions never reach the page as visible text.
+ */
+/**
+ * Turn resolvable references into ordinary links and images, and remove the
+ * definitions that backed them.
+ *
+ * An unresolvable reference is left alone: CommonMark says it renders as the
+ * literal text that was typed, which is what the HTML conversion then does.
+ *
+ * @param root The document, modified in place.
+ */
+function resolveReferences(root) {
+    const definitions = new Map();
+    visit(root, 'definition', (node) => {
+        if (!definitions.has(node.identifier))
+            definitions.set(node.identifier, node);
+    });
+    visit(root, (node, index, parent) => {
+        if (!parent || index === undefined)
+            return;
+        if (node.type !== 'linkReference' && node.type !== 'imageReference')
+            return;
+        // A reference with no definition never reaches here: CommonMark says it is
+        // not a link at all, so the parser has already turned it into plain text.
+        const definition = definitions.get(node.identifier);
+        if (!definition)
+            return;
+        const replacement = node.type === 'linkReference'
+            ? {
+                type: 'link',
+                url: definition.url,
+                ...(definition.title != null ? { title: definition.title } : {}),
+                children: node.children,
+                ...(node.position ? { position: node.position } : {}),
+            }
+            : {
+                type: 'image',
+                url: definition.url,
+                ...(definition.title != null ? { title: definition.title } : {}),
+                alt: node.alt ?? '',
+                ...(node.position ? { position: node.position } : {}),
+            };
+        parent.children[index] = replacement;
+    });
+    // Definitions carry no visible content; leaving them in would print them.
+    removeDefinitions(root);
+}
+/** Drop every definition node, at any depth. */
+function removeDefinitions(root) {
+    const prune = (node) => {
+        if (!Array.isArray(node.children))
+            return;
+        node.children = node.children.filter((child) => child.type !== 'definition');
+        for (const child of node.children)
+            prune(child);
+    };
+    prune(root);
+}
+
+/**
+ * Lowering MDX into something a Gutenberg page can hold.
+ *
+ * MDX is JavaScript, and a WordPress page is not. What can be translated is
+ * translated by the component table; the rest is reported with its position
+ * rather than dropped, because a page that quietly loses a third of its
+ * content is worse than one that tells you it did.
+ */
+/** Elements that are plain HTML and can be carried through as written. */
+const HTML_ELEMENTS = new Set([
+    'a', 'abbr', 'b', 'br', 'code', 'div', 'em', 'figcaption', 'figure', 'h1', 'h2', 'h3',
+    'h4', 'h5', 'h6', 'hr', 'i', 'img', 'kbd', 'li', 'mark', 'ol', 'p', 'pre', 's', 'samp',
+    'small', 'span', 'strong', 'sub', 'sup', 'table', 'tbody', 'td', 'th', 'thead', 'tr',
+    'u', 'ul', 'var',
+]);
+/** Components the renderer knows how to turn into blocks. */
+const KNOWN_COMPONENTS = new Set([
+    'Tabs',
+    'TabItem',
+    'Details',
+    'details',
+    'summary',
+    'CodeBlock',
+    'Admonition',
+]);
+/** The original text a node was parsed from. */
+function sourceOf(node, source) {
+    const start = node.position?.start.offset;
+    const end = node.position?.end.offset;
+    return start !== undefined && end !== undefined ? source.slice(start, end) : '';
+}
+/** Read the import specifiers out of an ESM block, without evaluating it. */
+function readImports(value, into) {
+    const pattern = /import\s+([A-Za-z_$][\w$]*)\s+from\s+['"]([^'"]+)['"]/g;
+    for (const match of value.matchAll(pattern))
+        into.set(match[1], match[2]);
+}
+/** True for an expression that holds nothing but a comment. */
+function isCommentOnly(node) {
+    const estree = node.data?.estree;
+    if (estree)
+        return (estree.body?.length ?? 0) === 0 && (estree.comments?.length ?? 0) > 0;
+    return /^\s*\/[/*]/.test(node.value ?? '');
+}
+/**
+ * Replace MDX-only nodes so nothing downstream has to know about them.
+ *
+ * @param root The document, modified in place.
+ * @param ctx Where to report, and what to do about the untranslatable.
+ */
+function lowerMdx(root, ctx) {
+    const imports = new Map();
+    const severity = ctx.onUnknown === 'error' ? 'error' : 'warning';
+    const report = (node, message, code) => {
+        ctx.issues.add({
+            code,
+            severity,
+            message,
+            file: ctx.file,
+            line: node.position?.start.line,
+            column: node.position?.start.column,
+        });
+        if (ctx.onUnknown !== 'placeholder')
+            return undefined;
+        return { type: 'html', value: `<!-- pterodoc: ${message} -->` };
+    };
+    const replacements = [];
+    visit(root, (node, index, parent) => {
+        if (!parent || index === undefined)
+            return;
+        const typed = node;
+        switch (typed.type) {
+            case 'mdxjsEsm': {
+                readImports(node.value ?? '', imports);
+                replacements.push({ parent: parent, index, with: undefined });
+                return;
+            }
+            case 'mdxFlowExpression':
+            case 'mdxTextExpression': {
+                const expression = node;
+                if (isCommentOnly(expression)) {
+                    replacements.push({ parent: parent, index, with: undefined });
+                    return;
+                }
+                replacements.push({
+                    parent: parent,
+                    index,
+                    with: report(typed, `An MDX expression ({${(expression.value ?? '').trim().slice(0, 40)}}) has no fixed value outside the site, so it was left out.`, 'mdx-expression'),
+                });
+                return;
+            }
+            case 'mdxJsxTextElement': {
+                const element = node;
+                const name = element.name ?? '';
+                if (name && HTML_ELEMENTS.has(name)) {
+                    // Plain HTML: keep exactly what the author wrote.
+                    replacements.push({
+                        parent: parent,
+                        index,
+                        with: { type: 'html', value: sourceOf(typed, ctx.source) },
+                    });
+                    return;
+                }
+                if (name === '') {
+                    // A fragment: keep the children, drop the wrapper.
+                    return;
+                }
+                replacements.push({
+                    parent: parent,
+                    index,
+                    with: report(typed, `<${name}> is a React component, which a page cannot run, so it was left out.`, 'mdx-unknown-component'),
+                });
+                return;
+            }
+            default:
+                return;
+        }
+    });
+    // Applied afterwards so the walk is not disturbed by its own edits.
+    for (const replacement of replacements.reverse()) {
+        if (replacement.with)
+            replacement.parent.children.splice(replacement.index, 1, replacement.with);
+        else
+            replacement.parent.children.splice(replacement.index, 1);
+    }
+    return { imports };
+}
+/** True for an element name pterodoc can translate into blocks. */
+function isTranslatable(name) {
+    return KNOWN_COMPONENTS.has(name) || HTML_ELEMENTS.has(name);
+}
+
+/**
+ * Link rewriting.
+ *
+ * A documentation link can be relative to the source file, absolute against
+ * the site's base URL, or an anchor. Whichever it is, it has to end up
+ * pointing at the right page on the target — or, when the target has no such
+ * page, somewhere honest.
+ */
+/** True for a URL that already names its own scheme or host. */
+function isAbsoluteUrl(href) {
+    return /^[a-zA-Z][a-zA-Z0-9+.-]*:/.test(href) || href.startsWith('//');
+}
+/**
+ * Resolve a documentation link to the URL path it refers to.
+ *
+ * Relative targets are resolved against the linking document's own permalink,
+ * which is what makes this work regardless of where the docs are mounted.
+ *
+ * @param href The link as written.
+ * @param fromPermalink Permalink of the document containing the link.
+ * @returns The URL path and fragment, or undefined when the link is not internal.
+ */
+function toInternalPath(href, fromPermalink) {
+    if (!href || href.startsWith('#') || isAbsoluteUrl(href))
+        return undefined;
+    const hashIndex = href.indexOf('#');
+    const hash = hashIndex === -1 ? '' : href.slice(hashIndex);
+    const target = hashIndex === -1 ? href : href.slice(0, hashIndex);
+    const withoutExtension = target.replace(/\.mdx?$/, '');
+    const base = fromPermalink.endsWith('/') ? fromPermalink : `${fromPermalink}/`;
+    const urlPath = withoutExtension.startsWith('/')
+        ? path.posix.normalize(withoutExtension)
+        : path.posix.normalize(path.posix.join(base, '..', withoutExtension));
+    return { urlPath, hash };
+}
+/**
+ * Rewrite every link in a document.
+ *
+ * @param root The document, modified in place.
+ * @param fromPermalink Permalink of the document.
+ * @param resolve Where each link should point.
+ * @returns Tree paths of the pages this document links to.
+ */
+function rewriteLinks(root, fromPermalink, resolve, _issues) {
+    const linked = new Set();
+    visit(root, 'link', (node, index, parent) => {
+        const resolved = resolve(node.url, fromPermalink);
+        if (resolved.path !== undefined)
+            linked.add(resolved.path);
+        if (resolved.href === null) {
+            // The target is not published, so keep the words and drop the link.
+            if (parent && index !== undefined) {
+                parent.children.splice(index, 1, ...node.children);
+                return index;
+            }
+            return;
+        }
+        node.url = resolved.href;
+        return;
+    });
+    return linked;
+}
+
+/**
+ * Phrasing content to HTML.
+ *
+ * The whole run of nodes is converted in one pass, so `mdast-util-to-hast`
+ * keeps whatever state it needs, and the conversion happens inside a synthetic
+ * paragraph so it does not separate the children with newlines the way it does
+ * for a root.
+ */
+/**
+ * Escape shortcode brackets inside text, leaving tags and attributes alone.
+ *
+ * Done on the tree rather than on the serialised string: a `>` inside an
+ * attribute value would fool any regex that tries to find tag boundaries.
+ * A `raw` node carries the entity through serialisation unescaped.
+ */
+function escapeShortcodesInHast(nodes) {
+    const out = [];
+    for (const node of nodes) {
+        if (node.type === 'text' && node.value.includes('[')) {
+            const parts = node.value.split('[');
+            parts.forEach((part, index) => {
+                if (index > 0)
+                    out.push({ type: 'raw', value: '&#91;' });
+                if (part !== '')
+                    out.push({ type: 'text', value: part });
+            });
+            continue;
+        }
+        if ('children' in node && Array.isArray(node.children)) {
+            node.children = escapeShortcodesInHast(node.children);
+        }
+        out.push(node);
+    }
+    return out;
+}
+/** Convert phrasing content to the hast nodes that back it. */
+function toInlineHast(nodes) {
+    const paragraph = toHast({ type: 'paragraph', children: nodes }, { allowDangerousHtml: true });
+    const children = (paragraph?.children ?? []);
+    return escapeShortcodesInHast(children);
+}
+/** Serialise hast nodes to HTML. */
+function hastToHtml(nodes) {
+    const tree = Array.isArray(nodes) ? { type: 'root', children: nodes } : nodes;
+    return toHtml(tree, { allowDangerousHtml: true });
+}
+/** Render phrasing content to HTML. */
+function renderInline(nodes) {
+    return hastToHtml(toInlineHast(nodes));
+}
+
+/**
+ * Heading identifiers.
+ *
+ * The anchors have to match the ones Docusaurus generated, or every in-page
+ * link that survived the move would break. That is why `github-slugger` is
+ * pinned to the major Docusaurus itself depends on.
+ */
+/** Start a fresh slugger for a document. */
+function createSlugger() {
+    return new GithubSlugger();
+}
+/**
+ * Work out a heading's identifier.
+ *
+ * Docusaurus lets an explicit `{#id}` override the generated slug. Both paths
+ * feed the same slugger so that a later duplicate is still disambiguated.
+ *
+ * @param heading The heading node.
+ * @param slugger The document's slugger.
+ * @param maintainCase Whether Docusaurus is configured to keep heading case.
+ */
+function headingIdFor(heading, slugger, maintainCase = false) {
+    const children = heading.children.map((child) => ({ ...child }));
+    const last = children[children.length - 1];
+    let explicit = '';
+    if (last && last.type === 'text') {
+        const text = last;
+        const match = /\s*\{#([^}]+)\}\s*$/.exec(text.value);
+        if (match) {
+            explicit = match[1].trim();
+            text.value = text.value.slice(0, match.index).replace(/\s+$/, '');
+            if (text.value === '')
+                children.pop();
+        }
+    }
+    const text = toString({ type: 'root', children });
+    if (explicit) {
+        // Register it so a later generated slug cannot collide with it.
+        slugger.slug(explicit, true);
+        return { id: explicit, children, text };
+    }
+    return { id: slugger.slug(text, maintainCase), children, text };
+}
+
+/**
+ * Code blocks.
+ *
+ * Docusaurus carries extra instructions in the fence's metastring — a title,
+ * highlighted line ranges, line numbers. WordPress core's code block has
+ * nowhere to put them, so the title becomes a visible caption, line numbers
+ * become a class a theme can act on, and anything left over is reported rather
+ * than dropped in silence.
+ */
+/**
+ * Read a fence's metastring.
+ *
+ * @param meta The text after the language on the opening fence.
+ */
+function parseCodeMeta(meta) {
+    const source = meta ?? '';
+    const title = /(?:^|\s)title=(?:"([^"]*)"|'([^']*)'|([^\s]+))/.exec(source);
+    const highlight = /\{([\d,\s-]+)\}/.exec(source);
+    return {
+        ...(title ? { title: title[1] ?? title[2] ?? title[3] ?? '' } : {}),
+        showLineNumbers: /(?:^|\s)showLineNumbers(?:\s|=|$)/.test(source),
+        ...(highlight ? { highlight: highlight[1].trim() } : {}),
+    };
+}
+/**
+ * Render a fenced code block.
+ *
+ * @param node The code node.
+ * @param theme Class names and strings.
+ * @param issues Where unrepresentable instructions are reported.
+ * @param file Source file, for the issue's position.
+ */
+function renderCode(node, theme, issues, file) {
+    const lang = (node.lang ?? '').toLowerCase();
+    const meta = parseCodeMeta(node.meta);
+    if (lang === 'mermaid') {
+        // Entities are decoded again when mermaid reads the element's text, so
+        // escaping keeps `A[Start]` away from the shortcode parser without
+        // changing the diagram.
+        return serializeBlock('html', undefined, `<pre class="mermaid">${escapeCode(node.value)}</pre>`);
+    }
+    const classes = [];
+    if (lang)
+        classes.push(`language-${lang}`);
+    if (meta.showLineNumbers)
+        classes.push(theme.cls('line-numbers'));
+    const className = classes.join(' ');
+    const preClasses = className ? `wp-block-code ${className}` : 'wp-block-code';
+    // Highlighted lines have no core equivalent, so with core blocks alone they
+    // can only be reported. The plugin can render them, and reads the range from
+    // the block comment — never from the markup, which stays exactly what core's
+    // own save function would have written.
+    const carried = theme.blocks === 'plugin' && meta.highlight !== undefined;
+    const attributes = {};
+    if (className)
+        attributes['className'] = className;
+    if (carried)
+        attributes['pterodocHighlight'] = meta.highlight;
+    const code = serializeBlock('code', Object.keys(attributes).length > 0 ? attributes : undefined, `<pre class="${preClasses}"><code>${escapeCode(node.value)}</code></pre>`);
+    if (meta.highlight && !carried) {
+        issues?.add({
+            code: 'code-highlight-dropped',
+            severity: 'info',
+            message: `Highlighted lines {${meta.highlight}} have no WordPress equivalent and were not carried over. Install the pterodoc WordPress plugin and set render.blocks to 'plugin' to keep them.`,
+            file,
+            line: node.position?.start.line,
+        });
+    }
+    if (!meta.title)
+        return code;
+    const caption = serializeBlock('paragraph', { className: theme.cls('code-title') }, `<p class="${theme.cls('code-title')}">${escapeCode(meta.title)}</p>`);
+    const groupClass = theme.cls('code-group');
+    return serializeBlock('group', { className: groupClass }, `<div class="wp-block-group ${groupClass}">${joinBlocks([caption, code])}</div>`);
+}
+
+/**
+ * Docusaurus admonitions.
+ *
+ * `:::note` and its siblings are container directives. WordPress has no
+ * equivalent block, so each becomes a group with stable classes a theme can
+ * style, opened by a bold label the way Docusaurus renders one.
+ */
+/**
+ * The keywords Docusaurus recognises when a site configures none.
+ *
+ * Taken from the docs plugin's own defaults rather than guessed: a site that
+ * writes `:::success` gets an admonition on Docusaurus and must get one here.
+ */
+const DEFAULT_ADMONITION_KEYWORDS = [
+    'secondary',
+    'info',
+    'success',
+    'danger',
+    'note',
+    'tip',
+    'warning',
+    'important',
+    'caution',
+];
+/**
+ * Render an admonition.
+ *
+ * @param node The container directive.
+ * @param theme Class names and strings.
+ * @param renderChild How to render each block inside the admonition.
+ */
+function renderAdmonition(node, theme, renderChild) {
+    const type = String(node.name ?? '').toLowerCase();
+    const children = [...node.children];
+    let label = type.charAt(0).toUpperCase() + type.slice(1);
+    const first = children[0];
+    if (first?.data?.directiveLabel) {
+        label = toString(children[0]);
+        children.shift();
+    }
+    const base = theme.cls('admonition');
+    const className = `${base} ${base}-${type}`;
+    const titleClass = theme.cls('admonition-title');
+    const inner = joinBlocks([
+        serializeBlock('paragraph', { className: titleClass }, `<p class="${titleClass}"><strong>${renderInline([{ type: 'text', value: label }])}</strong></p>`),
+        ...children.map(renderChild),
+    ]);
+    return serializeBlock('group', { className }, `<div class="wp-block-group ${className}">${inner}</div>`);
+}
+
+/**
+ * The MDX component table.
+ *
+ * Docusaurus ships a small set of components that documentation actually uses.
+ * Each one here has a WordPress block that carries the same meaning; anything
+ * else is reported by the lowering pass rather than guessed at.
+ */
+/** Read a string attribute, ignoring expression values we cannot evaluate. */
+function attribute(element, name) {
+    for (const attr of element.attributes ?? []) {
+        if (attr.type !== 'mdxJsxAttribute' || attr.name !== name)
+            continue;
+        if (typeof attr.value === 'string')
+            return attr.value;
+        const value = attr.value;
+        if (value && typeof value.value === 'string')
+            return value.value;
+        return undefined;
+    }
+    return undefined;
+}
+/** A details block, which is what a collapsible section becomes. */
+function detailsBlock(summary, inner) {
+    return serializeBlock('details', undefined, `<details class="wp-block-details"><summary>${escapeText(summary)}</summary>${inner}</details>`);
+}
+/** Render `<TabItem>` as one collapsible section. */
+function renderTabItem(element, ctx) {
+    const label = attribute(element, 'label') ?? attribute(element, 'value') ?? 'Tab';
+    const inner = joinBlocks((element.children ?? []).map(ctx.renderChild));
+    return detailsBlock(label, inner);
+}
+/**
+ * Render `<Tabs>`.
+ *
+ * Tabs need JavaScript that a published page does not have, so each tab
+ * becomes a collapsible section instead. All of the content survives, and it
+ * stays readable without any script at all.
+ */
+function renderTabs(element, ctx) {
+    const items = (element.children ?? []).filter((child) => child.name === 'TabItem');
+    const rendered = items.map((item) => renderTabItem(item, ctx));
+    const className = ctx.theme.cls('tabs');
+    return serializeBlock('group', { className }, `<div class="wp-block-group ${className}">${joinBlocks(rendered)}</div>`);
+}
+/** Render `<Details>` or a raw `<details>` element. */
+function renderDetails(element, ctx) {
+    const children = [...(element.children ?? [])];
+    let summary = attribute(element, 'summary') ?? '';
+    const summaryIndex = children.findIndex((child) => child.name === 'summary');
+    if (summaryIndex !== -1) {
+        const node = children[summaryIndex];
+        summary = plainText$1(node, ctx.source);
+        children.splice(summaryIndex, 1);
+    }
+    return detailsBlock(summary || 'Details', joinBlocks(children.map(ctx.renderChild)));
+}
+/** Render `<CodeBlock language="ts" title="x">`. */
+function renderCodeBlock(element, ctx) {
+    const language = attribute(element, 'language') ?? '';
+    const title = attribute(element, 'title');
+    // The children parse as ordinary markdown, so the code arrives as text
+    // inside paragraphs rather than as one raw string.
+    const value = textContent(element.children ?? []);
+    const classes = language ? `wp-block-code language-${language}` : 'wp-block-code';
+    const code = serializeBlock('code', language ? { className: `language-${language}` } : undefined, `<pre class="${classes}"><code>${escapeCode(value)}</code></pre>`);
+    if (!title)
+        return code;
+    const groupClass = ctx.theme.cls('code-group');
+    const titleClass = ctx.theme.cls('code-title');
+    return serializeBlock('group', { className: groupClass }, `<div class="wp-block-group ${groupClass}">${joinBlocks([
+        serializeBlock('paragraph', { className: titleClass }, `<p class="${titleClass}">${escapeText(title)}</p>`),
+        code,
+    ])}</div>`);
+}
+/** Render `<Admonition type="tip" title="…">`. */
+function renderAdmonitionElement(element, ctx) {
+    const type = (attribute(element, 'type') ?? 'note').toLowerCase();
+    const label = attribute(element, 'title') ?? type.charAt(0).toUpperCase() + type.slice(1);
+    const base = ctx.theme.cls('admonition');
+    const className = `${base} ${base}-${type}`;
+    const titleClass = ctx.theme.cls('admonition-title');
+    const inner = joinBlocks([
+        serializeBlock('paragraph', { className: titleClass }, `<p class="${titleClass}"><strong>${escapeText(label)}</strong></p>`),
+        ...(element.children ?? []).map(ctx.renderChild),
+    ]);
+    return serializeBlock('group', { className }, `<div class="wp-block-group ${className}">${inner}</div>`);
+}
+/**
+ * The text a run of nodes carries.
+ *
+ * Block-level children are separated by a blank line, which is what keeps the
+ * lines of a code block apart once MDX has parsed them into paragraphs.
+ */
+function textContent(nodes) {
+    const blocks = [];
+    for (const node of nodes) {
+        const parts = [];
+        const walk = (child) => {
+            if (typeof child.value === 'string' && child.type !== 'html')
+                parts.push(child.value);
+            for (const grandChild of (child.children ?? []))
+                walk(grandChild);
+        };
+        walk(node);
+        const text = parts.join('');
+        if (text !== '')
+            blocks.push(text);
+    }
+    return blocks.join('\n\n');
+}
+/** The text inside an element, for a summary. */
+function plainText$1(element, source) {
+    const parts = [];
+    const walk = (node) => {
+        if (typeof node.value === 'string' && node.type === 'text')
+            parts.push(node.value);
+        for (const child of (node.children ?? []))
+            walk(child);
+    };
+    walk(element);
+    const text = parts.join('').trim();
+    if (text)
+        return text;
+    const start = element.position?.start.offset;
+    const end = element.position?.end.offset;
+    return start !== undefined && end !== undefined
+        ? source.slice(start, end).replace(/<[^>]*>/g, '').trim()
+        : '';
+}
+/**
+ * Render a block-level JSX element.
+ *
+ * @returns The block markup, or undefined when nothing here can render it.
+ */
+function renderJsxBlock(element, ctx) {
+    const name = element.name ?? '';
+    switch (name) {
+        case 'Tabs':
+            return renderTabs(element, ctx);
+        case 'TabItem':
+            return renderTabItem(element, ctx);
+        case 'Details':
+        case 'details':
+            return renderDetails(element, ctx);
+        case 'CodeBlock':
+            return renderCodeBlock(element, ctx);
+        case 'Admonition':
+            return renderAdmonitionElement(element, ctx);
+    }
+    if (name === '') {
+        // A fragment contributes nothing of its own.
+        return joinBlocks((element.children ?? []).map(ctx.renderChild));
+    }
+    if (HTML_ELEMENTS.has(name)) {
+        const start = element.position?.start.offset;
+        const end = element.position?.end.offset;
+        if (start !== undefined && end !== undefined) {
+            return serializeBlock('html', undefined, ctx.source.slice(start, end));
+        }
+    }
+    return undefined;
+}
+
+/**
+ * Markdown block nodes to Gutenberg blocks.
+ *
+ * One function per node type, dispatched from `renderBlock`. Everything that
+ * cannot be represented is reported as an issue; nothing is dropped quietly.
+ */
+/** A context with the defaults a caller usually wants. */
+function createRenderContext(init) {
+    return {
+        maintainCase: false,
+        admonitionKeywords: new Set(DEFAULT_ADMONITION_KEYWORDS),
+        source: '',
+        ...init,
+    };
+}
+/** True when a list only holds shapes core's list block can carry. */
+function listIsSimple(list) {
+    return list.children.every((item) => item.type === 'listItem' &&
+        item.children.every((child, index) => (child.type === 'paragraph' && index === 0) || child.type === 'list'));
+}
+function renderListItem(item, ctx) {
+    const parts = [];
+    for (const child of item.children) {
+        if (child.type === 'paragraph')
+            parts.push(renderInline(child.children));
+        else if (child.type === 'list')
+            parts.push(renderList(child));
+    }
+    const marker = item.checked === true ? '☑ ' : item.checked === false ? '☐ ' : '';
+    return serializeBlock('list-item', undefined, `<li>${marker}${parts.join('')}</li>`);
+}
+function renderList(node, ctx) {
+    const tag = node.ordered ? 'ol' : 'ul';
+    const attributes = {};
+    if (node.ordered)
+        attributes['ordered'] = true;
+    const start = node.ordered && typeof node.start === 'number' && node.start !== 1 ? node.start : null;
+    if (start !== null)
+        attributes['start'] = start;
+    const items = node.children.map((item) => renderListItem(item)).join('\n\n');
+    const open = `<${tag}${start !== null ? ` start="${start}"` : ''} class="wp-block-list">`;
+    return serializeBlock('list', attributes, `${open}${items}</${tag}>`);
+}
+function renderTable(node) {
+    const align = node.align ?? [];
+    const cell = (content, index, header) => {
+        const tag = header ? 'th' : 'td';
+        const alignment = align[index];
+        const attrs = alignment ? ` class="has-text-align-${alignment}" data-align="${alignment}"` : '';
+        return `<${tag}${attrs}>${renderInline(content.children ?? [])}</${tag}>`;
+    };
+    const [head, ...body] = node.children;
+    const thead = head
+        ? `<thead><tr>${head.children.map((c, i) => cell(c, i, true)).join('')}</tr></thead>`
+        : '';
+    const tbody = body.length
+        ? `<tbody>${body
+            .map((row) => `<tr>${row.children.map((c, i) => cell(c, i, false)).join('')}</tr>`)
+            .join('')}</tbody>`
+        : '';
+    return serializeBlock('table', { hasFixedLayout: false }, `<figure class="wp-block-table"><table>${thead}${tbody}</table></figure>`);
+}
+/** A paragraph holding nothing but one image becomes an image block. */
+function loneImage(node) {
+    const meaningful = node.children.filter((child) => !(child.type === 'text' && child.value.trim() === ''));
+    return meaningful.length === 1 && meaningful[0].type === 'image'
+        ? meaningful[0]
+        : undefined;
+}
+function renderImageBlock(node, ctx) {
+    const uploaded = ctx.media?.get(node.url);
+    const src = uploaded?.url ?? node.url;
+    const attributes = { sizeSlug: 'large', linkDestination: 'none' };
+    if (uploaded)
+        attributes['id'] = uploaded.id;
+    const classes = `wp-block-image size-large`;
+    const imgClass = uploaded ? ` class="wp-image-${uploaded.id}"` : '';
+    const caption = node.title
+        ? `<figcaption class="wp-element-caption">${escapeText(node.title)}</figcaption>`
+        : '';
+    return serializeBlock('image', attributes, `<figure class="${classes}"><img src="${escapeText(src)}" alt="${escapeText(node.alt ?? '')}"${imgClass}/>${caption}</figure>`);
+}
+/**
+ * Render one top-level markdown node.
+ *
+ * @param node The node.
+ * @param ctx Theme, slugger and issue collector.
+ */
+function renderBlock(node, ctx) {
+    switch (node.type) {
+        case 'paragraph': {
+            const image = loneImage(node);
+            if (image)
+                return renderImageBlock(image, ctx);
+            const html = renderInline(node.children);
+            if (html.trim() === '')
+                return '';
+            return serializeBlock('paragraph', undefined, `<p>${html}</p>`);
+        }
+        case 'heading': {
+            const heading = node;
+            const { id, children } = headingIdFor(heading, ctx.slugger, ctx.maintainCase);
+            const level = heading.depth;
+            const attributes = level === 2 ? undefined : { level };
+            return serializeBlock('heading', attributes, `<h${level} class="wp-block-heading" id="${id}">${renderInline(children)}</h${level}>`);
+        }
+        case 'list': {
+            const list = node;
+            if (listIsSimple(list))
+                return renderList(list);
+            ctx.issues.add({
+                code: 'list-not-representable',
+                severity: 'info',
+                message: 'A list item holds blocks the WordPress list block cannot carry; kept as HTML.',
+                file: ctx.file,
+                line: node.position?.start.line,
+            });
+            const hast = toHast(list, { allowDangerousHtml: true });
+            const escaped = hast ? escapeShortcodesInHast([hast]) : [];
+            return serializeBlock('html', undefined, hastToHtml(escaped));
+        }
+        case 'code':
+            return renderCode(node, ctx.theme, ctx.issues, ctx.file);
+        case 'blockquote': {
+            const inner = joinBlocks(node.children.map((child) => renderBlock(child, ctx)));
+            return serializeBlock('quote', undefined, `<blockquote class="wp-block-quote">${inner}</blockquote>`);
+        }
+        case 'table':
+            return renderTable(node);
+        case 'thematicBreak':
+            return serializeBlock('separator', undefined, '<hr class="wp-block-separator has-alpha-channel-opacity"/>');
+        case 'containerDirective': {
+            const directive = node;
+            const name = String(directive.name ?? '').toLowerCase();
+            if (ctx.admonitionKeywords.has(name)) {
+                return renderAdmonition(directive, ctx.theme, (child) => renderBlock(child, ctx));
+            }
+            ctx.issues.add({
+                code: 'directive-unknown',
+                severity: 'warning',
+                message: `":::${directive.name}" is not an admonition on this site; its content was kept without the wrapper.`,
+                file: ctx.file,
+                line: node.position?.start.line,
+            });
+            return joinBlocks(directive.children.map((child) => renderBlock(child, ctx)));
+        }
+        case 'mdxJsxFlowElement': {
+            const element = node;
+            const rendered = renderJsxBlock(element, {
+                theme: ctx.theme,
+                issues: ctx.issues,
+                source: ctx.source,
+                file: ctx.file,
+                renderChild: (child) => renderBlock(child, ctx),
+            });
+            if (rendered !== undefined)
+                return rendered;
+            ctx.issues.add({
+                code: 'mdx-unknown-component',
+                severity: ctx.onUnknownJsx === 'error' ? 'error' : 'warning',
+                message: `<${element.name ?? 'fragment'}> is a React component, which a page cannot run, so it was left out.`,
+                file: ctx.file,
+                line: node.position?.start.line,
+                column: node.position?.start.column,
+            });
+            return ctx.onUnknownJsx === 'placeholder'
+                ? serializeBlock('html', undefined, `<!-- pterodoc: <${element.name ?? 'fragment'}> omitted -->`)
+                : '';
+        }
+        case 'html': {
+            const value = node.value;
+            // Comments carry no content; Docusaurus hides them too.
+            if (/^\s*<!--[\s\S]*-->\s*$/.test(value))
+                return '';
+            return serializeBlock('html', undefined, value);
+        }
+        case 'image':
+            return renderImageBlock(node, ctx);
+        case 'definition':
+        case 'yaml':
+        case 'footnoteDefinition':
+            return '';
+        default: {
+            const position = node.position;
+            if (position && ctx.source) {
+                const raw = ctx.source.slice(position.start.offset ?? 0, position.end.offset ?? 0);
+                ctx.issues.add({
+                    code: 'node-unhandled',
+                    severity: 'warning',
+                    message: `A "${node.type}" node has no WordPress equivalent; its source was kept verbatim.`,
+                    file: ctx.file,
+                    line: position.start.line,
+                });
+                return serializeBlock('paragraph', undefined, `<p>${escapeText(raw)}</p>`);
+            }
+            ctx.issues.add({
+                code: 'node-unhandled',
+                severity: 'warning',
+                message: `A "${node.type}" node has no WordPress equivalent and was skipped.`,
+                file: ctx.file,
+            });
+            return '';
+        }
+    }
+}
+/**
+ * Render a document body.
+ *
+ * @param root The parsed document.
+ * @param ctx Theme, slugger and issue collector.
+ * @param options `dedupeTitle` drops a leading H1 that repeats the page title.
+ */
+function renderBody(root, ctx, options = {}) {
+    const children = [...root.children];
+    if (options.dedupeTitle !== false) {
+        // The theme prints the page title, so a body that opens with the same
+        // heading would show it twice. Skipping anything that renders to nothing
+        // first means a comment or a stripped import cannot hide the heading.
+        const firstVisible = children.findIndex((child) => !(child.type === 'html' && /^\s*<!--[\s\S]*-->\s*$/.test(child.value)) &&
+            child.type !== 'yaml' &&
+            child.type !== 'definition');
+        const candidate = firstVisible === -1 ? undefined : children[firstVisible];
+        if (candidate && candidate.type === 'heading' && candidate.depth === 1) {
+            children.splice(firstVisible, 1);
+        }
+    }
+    const firstParagraph = children.find((child) => child.type === 'paragraph');
+    const body = joinBlocks(children.map((child) => renderBlock(child, ctx)));
+    return {
+        body,
+        firstParagraph: firstParagraph ? plainText(firstParagraph) : '',
+    };
+}
+/** Plain text of a node, for excerpts. */
+function plainText(node) {
+    const parts = [];
+    const walk = (child) => {
+        if (typeof child.value === 'string' && (child.type === 'text' || child.type === 'inlineCode')) {
+            parts.push(child.value);
+        }
+        if (Array.isArray(child.children)) {
+            for (const grandChild of child.children)
+                walk(grandChild);
+        }
+    };
+    walk(node);
+    return parts.join('');
+}
+
+/**
+ * Finding and resolving the files a document references.
+ *
+ * Images are found wherever they sit — in a paragraph, behind a reference,
+ * inside raw HTML — because the one place they never sit is at the top level
+ * of a document, which is where an earlier version of this code looked.
+ */
+/** Every image a document references, including ones behind a reference definition. */
+function collectImages(markdown, format = 'md') {
+    const root = parseMarkdown(markdown, format);
+    // Reference-style images become ordinary ones first, so they are not missed.
+    resolveReferences(root);
+    const found = [];
+    const seen = new Set();
+    visit(root, 'image', (node) => {
+        if (seen.has(node.url))
+            return;
+        seen.add(node.url);
+        found.push({
+            url: node.url,
+            alt: node.alt ?? '',
+            ...(node.title != null ? { title: node.title } : {}),
+        });
+    });
+    return found;
+}
+/**
+ * Work out which file an image URL points at.
+ *
+ * The order matches how Docusaurus itself resolves them: an absolute URL is
+ * left alone, `@site/` is site-relative, a leading slash is served from a
+ * static directory, and anything else is relative to the document — preferring
+ * the localised copy when there is one.
+ */
+function resolveImage(url, ctx) {
+    const exists = ctx.exists ?? ((file) => fs.existsSync(file));
+    if (!url || url.startsWith('data:') || isAbsoluteUrl(url))
+        return { kind: 'external', url };
+    if (url.startsWith('@site/')) {
+        const file = path.resolve(ctx.siteDir, url.slice('@site/'.length));
+        return exists(file) ? { kind: 'file', url, file } : { kind: 'missing', url };
+    }
+    if (url.startsWith('/')) {
+        const base = ctx.baseUrl.replace(/\/+$/, '');
+        const withoutBase = base && url.startsWith(`${base}/`) ? url.slice(base.length) : url;
+        for (const dir of ctx.staticDirs) {
+            for (const candidate of [path.join(dir, url), path.join(dir, withoutBase)]) {
+                if (exists(candidate))
+                    return { kind: 'file', url, file: candidate };
+            }
+        }
+        return { kind: 'missing', url };
+    }
+    const sourceDir = path.dirname(ctx.sourceAbsolutePath);
+    const direct = path.resolve(sourceDir, url);
+    if (exists(direct))
+        return { kind: 'file', url, file: direct };
+    // The document may be the unlocalised original while its assets sit beside
+    // the translated copy, or the other way round.
+    if (ctx.contentPath && ctx.contentPathLocalized && ctx.contentPath !== ctx.contentPathLocalized) {
+        const relative = path.relative(ctx.contentPath, direct);
+        const twin = path.resolve(ctx.contentPathLocalized, relative);
+        if (!relative.startsWith('..') && exists(twin))
+            return { kind: 'file', url, file: twin };
+    }
+    return { kind: 'missing', url };
+}
+
+/**
+ * Rendering a document: parse, resolve, and serialise to blocks.
+ *
+ * This layer is pure. It never reaches the network, never loads Docusaurus and
+ * knows nothing about the target beyond the URLs a resolver hands back.
+ */
+/**
+ * Render one document to Gutenberg block markup.
+ */
+function renderDoc(input) {
+    const issues = input.issues ?? new IssueCollector();
+    const parsed = matter(input.markdown);
+    const source = parsed.content.replace(/\r\n/g, '\n').replace(/^\n+/, '');
+    const format = input.format ?? (input.file ? detectFormat(input.file) : 'md');
+    const root = parseMarkdown(source, format);
+    if (format === 'mdx') {
+        lowerMdx(root, {
+            source,
+            file: input.file,
+            issues,
+            onUnknown: input.onUnknownJsx ?? 'report',
+        });
+    }
+    resolveReferences(root);
+    const links = input.resolveLink
+        ? rewriteLinks(root, input.permalink, input.resolveLink)
+        : new Set();
+    const ctx = createRenderContext({
+        theme: input.theme,
+        slugger: createSlugger(),
+        issues,
+        maintainCase: input.maintainCase ?? false,
+        admonitionKeywords: new Set(input.admonitionKeywords ?? DEFAULT_ADMONITION_KEYWORDS),
+        file: input.file,
+        source,
+        media: input.media,
+        onUnknownJsx: input.onUnknownJsx ?? 'report',
+    });
+    const { body, firstParagraph } = renderBody(root, ctx, {
+        dedupeTitle: input.dedupeTitle ?? true,
+    });
+    return { body, links, firstParagraph, issues };
+}
+/** Build an excerpt from a description, falling back to the opening paragraph. */
+function excerptFor(description, firstParagraph, max = 160) {
+    return excerptFrom(description || firstParagraph || '', max);
+}
+
+export { DEFAULT_ADMONITION_KEYWORDS, DEFAULT_LAYOUT, DEFAULT_STRINGS, KNOWN_COMPONENTS, attribute, collectImages, composePage, createRenderContext, createSlugger, createTheme, detectFormat, escapeCode, escapeText, excerptFor, excerptFrom, headingIdFor, isAbsoluteUrl, isTranslatable, joinBlocks, lowerMdx, parseMarkdown, renderBlock, renderBody, renderDoc, renderInline, renderJsxBlock, renderNavigationStub, renderVersionBanner, resolveImage, resolveReferences, rewriteLinks, serializeAttrs, serializeBlock, serializeVoidBlock, toInternalPath };
+//# sourceMappingURL=index.js.map