@dogsbay/serialize-core 0.2.0-beta.115 → 0.2.0-beta.117

package/dist/lead.js

@@ -0,0 +1,196 @@
+/**
+ * Inspect the leading nodes of a page tree.
+ *
+ * Defensive against empty trees and missing properties — returns
+ * `false` for both flags when the tree is empty.
+ */
+export function detectLeadingNodes(tree) {
+    if (!tree || tree.length === 0) {
+        return { hasH1: false, hasLede: false };
+    }
+    // H1 detection looks past two things that are not content:
+    //
+    //  - leading raw-HTML CHROME (banners, toolbars — the comparison view
+    //    injects both). Only tree[0] was inspected before, so a page that
+    //    opened with a banner "had no H1" and the layout added a second
+    //    one (external review);
+    //  - a transparent `group` wrapper, which by definition adds no
+    //    semantics — it exists only to carry an attribute for a run of
+    //    blocks (the comparison marks a whole added/removed page with one).
+    //    A wrapper that hid the page's H1 would resurrect the same bug.
+    //
+    // LEDE detection deliberately still keys off tree[0]: a paragraph that
+    // merely follows an HTML block is not the page's lede, and treating it
+    // as one silently suppresses the frontmatter description on any
+    // imported page opening with a <figure>/hero block (code review,
+    // 2026-07-13). Only an H1 introduces a lede.
+    let list = tree;
+    for (;;) {
+        let i = 0;
+        while (i < list.length && list[i]?.type === "html")
+            i++;
+        const first = list[i];
+        if (first?.type === "group" && first.children?.length) {
+            list = first.children;
+            continue;
+        }
+        if (isH1(first)) {
+            return { hasH1: true, hasLede: isParagraph(list[i + 1]) };
+        }
+        return { hasH1: false, hasLede: isParagraph(tree[0]) };
+    }
+}
+function isH1(node) {
+    if (!node || node.type !== "heading")
+        return false;
+    // Some importers (dogsbay-md, mkdocs) attach depth as a top-level
+    // field; others (Starlight via mdx-jsx) use props.level. Both
+    // conventions are valid — check both.
+    const depth = node.depth;
+    if (typeof depth === "number")
+        return depth === 1;
+    const level = node.props?.level;
+    if (typeof level === "number")
+        return level === 1;
+    return false;
+}
+function isParagraph(node) {
+    if (!node)
+        return false;
+    return node.type === "paragraph";
+}
+/**
+ * Derive a `<meta name="description">` from a page body when the
+ * frontmatter doesn't supply one: the first prose paragraph,
+ * whitespace-collapsed and truncated at a word boundary.
+ *
+ * Deliberately Minja-unaware. This only runs at build time, on the
+ * preprocessed (resolved) tree — `{{ var }}` and `{% include %}` are
+ * already gone, so the first paragraph is real prose. (A still-undefined
+ * `{{ var }}` survives `preserve` mode, but that's a content bug equally
+ * visible in the body and already flagged by the `unresolved-directives`
+ * audit — not the description's job to scrub.) The `--no-preprocess` /
+ * `dogsbay convert` paths emit unresolved output by design, where a
+ * slightly-off description is the least of it.
+ *
+ * Scans past a leading H1 / heading / code to the first prose paragraph;
+ * returns `undefined` when the page has no prose. See
+ * plans/auto-meta-description.md.
+ */
+export function deriveDescription(tree, maxLen = 155) {
+    if (!tree || tree.length === 0)
+        return undefined;
+    // Skip a leading H1 (the page title) so the lede is the node after it.
+    let i = isH1(tree[0]) ? 1 : 0;
+    for (; i < tree.length; i++) {
+        const node = tree[i];
+        if (node.type !== "paragraph")
+            continue; // skip headings/code/etc.
+        const text = paragraphText(node).replace(/\s+/g, " ").trim();
+        if (!text)
+            continue;
+        return truncateAtWord(text, maxLen);
+    }
+    return undefined;
+}
+/**
+ * Flatten a paragraph node's text. Tolerant of the three shapes
+ * format-astro already handles: flat `node.inline`, wrapped
+ * `node.children[{ inline }]`, and pre-rendered `node.html`.
+ */
+function paragraphText(node) {
+    const parts = [];
+    const visit = (n) => {
+        if (!n || typeof n !== "object")
+            return;
+        const o = n;
+        if (typeof o.text === "string")
+            parts.push(o.text);
+        if (typeof o.code === "string")
+            parts.push(o.code);
+        if (Array.isArray(o.inline))
+            o.inline.forEach(visit);
+        if (Array.isArray(o.children))
+            o.children.forEach(visit);
+    };
+    if (Array.isArray(node.inline))
+        node.inline.forEach(visit);
+    else if (Array.isArray(node.children))
+        node.children.forEach(visit);
+    else if (typeof node.html === "string") {
+        parts.push(node.html.replace(/<[^>]+>/g, ""));
+    }
+    return parts.join("");
+}
+function truncateAtWord(s, max) {
+    if (s.length <= max)
+        return s;
+    const cut = s.slice(0, max);
+    const lastSpace = cut.lastIndexOf(" ");
+    const base = lastSpace > max * 0.6 ? cut.slice(0, lastSpace) : cut;
+    return base.replace(/[\s.,;:!?-]+$/, "") + "…";
+}
+/**
+ * Extract plain text of the first paragraph in a page tree. Cross-shape
+ * tolerant: handles `node.inline` (dogsbay-md parser) and
+ * `node.children[{type: "prose", inline}]` (Starlight importer).
+ */
+export function extractFirstParagraph(tree) {
+    for (const node of tree) {
+        if (node.type !== "paragraph")
+            continue;
+        const inline = node.inline ?? findProseInline(node.children);
+        if (inline)
+            return inlineToPlainText(inline).trim();
+    }
+    return "";
+}
+function findProseInline(children) {
+    if (!children)
+        return undefined;
+    for (const child of children) {
+        if (child.type === "prose" && child.inline)
+            return child.inline;
+    }
+    return undefined;
+}
+function inlineToPlainText(inline) {
+    let out = "";
+    for (const node of inline) {
+        switch (node.type) {
+            case "text":
+                out += node.text;
+                break;
+            case "code":
+                out += node.text;
+                break;
+            case "link":
+            case "highlight":
+                out += inlineToPlainText(node.children);
+                break;
+            case "kbd":
+                out += node.keys.join("+");
+                break;
+            case "badge":
+                out += node.text;
+                break;
+            case "math":
+                out += node.latex;
+                break;
+            case "image":
+                if (node.alt)
+                    out += node.alt;
+                break;
+            case "break":
+                out += " ";
+                break;
+            case "html-inline":
+            case "footnote-ref":
+            case "icon":
+                // No useful plain text; skip.
+                break;
+        }
+    }
+    return out;
+}
+//# sourceMappingURL=lead.js.map

package/dist/lead.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lead.js","sourceRoot":"","sources":["../src/lead.ts"],"names":[],"mappings":"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"}

package/dist/text.d.ts

@@ -35,21 +35,108 @@ export declare function normalizeTrailingWhitespace(content: string): string;
  * use for HTML they cannot represent. Callers should record the degradation.
  */
 export declare function stripHtml(html: string): string;
-/**
- * Convert common INLINE HTML back to markdown.
- *
- * Importers frequently hand serializers pre-rendered HTML for prose
- * (`<code>x</code>`, `<strong>y</strong>`). Passing it through works in
- * MDX-ish targets but produces source no human wants to maintain — and the
- * point of a migration is clean, editable markdown.
- *
- * Deliberately conservative: only unambiguous inline tags, non-greedy, and
- * block-level markup is left completely alone (a regex cannot restructure
- * tables or lists safely). Anything not listed here survives as raw HTML.
- */
-export declare function inlineHtmlToMarkdown(html: string): string;
+export declare function inlineHtmlToMarkdown(html: string, options?: {
+    /** The caller strips the remaining tags (`stripHtml`), so ALL text
+     *  becomes Markdown and is escaped, block HTML or not. */
+    flatten?: boolean;
+}): string;
 /** Serialize a value as YAML frontmatter scalar, quoting when required. */
 export declare function yamlScalar(value: string): string;
 /** Build a YAML frontmatter block from ordered entries. Empty → "". */
 export declare function frontmatterBlock(entries: Array<[string, string | number | boolean | undefined]>): string;
+/**
+ * Text → CommonMark (or MDX) that reads back as the same text.
+ *
+ * A TreeNode `text` is LITERAL: an importer that met `&lt;script&gt;`, `\*`
+ * or `\[x\](…)` in its source stored `<script>`, `*`, `[x](…)`. Written into
+ * Markdown unescaped, those become a live element, emphasis and a link —
+ * the Docusaurus `.md` export put a spec's `<script>` and a
+ * `[x](javascript:…)` link into the site that way.
+ *
+ * - `<`, `{` and `}` become ENTITIES (`&lt;`, `&#123;`, `&#125;`), which read
+ *   the same in CommonMark and MDX and which no later MDX pass re-reads. A
+ *   backslash form did not survive Docusaurus' `sanitizeForMdx`: the text
+ *   `\{` became `\\{`, a literal backslash and a live expression.
+ * - `&` before an entity name becomes `&amp;`.
+ * - Backslash, `` ` ``, `*`, `[`, `]`, `~~` and a run of `_` at a word edge
+ *   are backslash-escaped. Both brackets: an unbalanced `\]` let
+ *   `[@dependabot[bot]](url)` link the wrong text. A task marker (`[ ]`,
+ *   `[x]`) starting the text is kept: GFM and Obsidian draw it as a
+ *   checkbox, and the parser keeps it as text.
+ * - A URL written as text keeps its `_` and `\` (GFM autolinks it, and an
+ *   escape would end up in the href); its brackets and backticks are still
+ *   escaped.
+ *
+ * `mdx: true` also escapes a `<` before any non-space character (`<3` is a
+ * syntax error in MDX), not only a tag-shaped one, and braces. Without it
+ * braces stay, as CommonMark reads them as text.
+ */
+export declare function escapeMarkdownText(text: string, options?: {
+    mdx?: boolean;
+    /**
+     * How `<`, `{` and `}` are escaped. `"entity"` (default) reads the same
+     * everywhere and survives a later MDX pass (Docusaurus). `"backslash"`
+     * (`\<`, `\{`) is easier to read in a file people edit (an Obsidian
+     * vault) and is what a target that does not decode entities needs
+     * (OpenKnowledge).
+     */
+    style?: "entity" | "backslash";
+}): string;
+/**
+ * May this URL be written as a link or image destination? Not a
+ * `javascript:`, `vbscript:` or `data:` URL (a `data:image/` source is
+ * allowed for images), however it is cased or padded with control
+ * characters and whitespace — browsers strip those before reading the
+ * scheme. markdown-it refuses these when it PARSES Markdown; a link node an
+ * importer built directly never passed that check.
+ */
+export declare function isSafeHref(href: string, kind?: "link" | "image"): boolean;
+/**
+ * Markdown from a string we did not write (an OpenAPI description, which
+ * the spec defines as CommonMark) made inert where it could run: raw HTML
+ * (`<` before a tag name becomes `&lt;`, which still reads `<`) and link or
+ * definition destinations with a `javascript:`/`vbscript:`/`data:` scheme
+ * (their `](` is escaped, so the text stays and the link goes). The rest of
+ * the Markdown is kept.
+ */
+export declare function neutralizeMarkdown(md: string): string;
+/**
+ * Apply `fn` to the parts of `md` outside inline code spans, leaving the
+ * spans as written. Spans are found as CommonMark finds them — a run of N
+ * backticks closed by the next run of exactly N, a backslash-escaped
+ * backtick opening nothing — in one pass over the runs (a backtracking
+ * RegExp took 7.6 s on 50,000 backticks).
+ */
+export declare function mapOutsideCodeSpans(md: string, fn: (prose: string) => string): string;
+/**
+ * A URL as a Markdown link or image destination that the reader resolves
+ * back to the same URL, and that nothing in it can end: `&` becomes `&amp;`
+ * (so `javascript&#58;` stays those characters rather than decoding to a
+ * scheme), a backslash is escaped, and space, `(`, `)`, `<`, `>` and control
+ * characters are percent-encoded (a `)` ended the destination and the rest
+ * became live Markdown).
+ */
+export declare function markdownDestination(url: string): string;
+/** A link or image title: one line, its quotes and backslashes escaped. */
+export declare function markdownTitle(title: string | undefined): string;
+/**
+ * LaTeX for `$…$` / `$$…$$` math read by arithmatex (MkDocs) or Obsidian:
+ * an unescaped `$` would close the span early, so it becomes `\$`.
+ */
+export declare function markdownLatex(latex: string): string;
+/**
+ * Math for remark-math / micromark (Docusaurus, MDX targets), which reads
+ * `$` like code: a run of N dollars is closed by a run of N, and `\$` does
+ * NOT escape. The delimiter is sized past any run in the LaTeX instead.
+ */
+export declare function remarkMath(latex: string, display: boolean): string;
+/**
+ * A footnote label every reader accepts, written the same way for the
+ * reference and its definition. Injective: other characters are
+ * hex-encoded (`note.1` → `note_x2e_1`), not deleted, so `*` and `†` do
+ * not collide with footnote 1.
+ */
+export declare function footnoteLabel(label: string): string;
+/** An id for `{#id}` or `id="…"`: characters that cannot end either. */
+export declare function safeAnchorId(id: string): string;
 //# sourceMappingURL=text.d.ts.map

package/dist/text.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"text.d.ts","sourceRoot":"","sources":["../src/text.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,EAAE,SAAS,GAAE,GAAG,GAAG,GAAS,GAAG,MAAM,CAOjF;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAM1D;AAED,uEAAuE;AACvE,wBAAgB,MAAM,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAM9D;AAED,+EAA+E;AAC/E,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAKnE;AAED,+EAA+E;AAC/E,wBAAgB,2BAA2B,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAMnE;AAED;;;GAGG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAkC9C;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAwBzD;AAkBD,2EAA2E;AAC3E,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CA8BhD;AAED,uEAAuE;AACvE,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,KAAK,CAAC,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,SAAS,CAAC,CAAC,GAC9D,MAAM,CAQR"}
+{"version":3,"file":"text.d.ts","sourceRoot":"","sources":["../src/text.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,EAAE,SAAS,GAAE,GAAG,GAAG,GAAS,GAAG,MAAM,CAOjF;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAM1D;AAED,uEAAuE;AACvE,wBAAgB,MAAM,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAM9D;AAED,+EAA+E;AAC/E,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAKnE;AAED,+EAA+E;AAC/E,wBAAgB,2BAA2B,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAMnE;AAED;;;GAGG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAkC9C;AAoBD,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,MAAM,EACZ,OAAO,GAAE;IACP;8DAC0D;IAC1D,OAAO,CAAC,EAAE,OAAO,CAAC;CACd,GACL,MAAM,CAkDR;AA6BD,2EAA2E;AAC3E,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CA8BhD;AAED,uEAAuE;AACvE,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,KAAK,CAAC,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,SAAS,CAAC,CAAC,GAC9D,MAAM,CAQR;AAMD;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,kBAAkB,CAChC,IAAI,EAAE,MAAM,EACZ,OAAO,GAAE;IACP,GAAG,CAAC,EAAE,OAAO,CAAC;IACd;;;;;;OAMG;IACH,KAAK,CAAC,EAAE,QAAQ,GAAG,WAAW,CAAC;CAC3B,GACL,MAAM,CA+BR;AAED;;;;;;;GAOG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,GAAE,MAAM,GAAG,OAAgB,GAAG,OAAO,CAKjF;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAyBrD;AA8BD;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,GAAG,MAAM,CAwCrF;AAQD;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAMvD;AAED,2EAA2E;AAC3E,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAE/D;AAYD;;;GAGG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAEnD;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,MAAM,CAUlE;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAGnD;AAED,wEAAwE;AACxE,wBAAgB,YAAY,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAE/C"}

package/dist/text.js

@@ -114,7 +114,12 @@ export function stripHtml(html) {
  * block-level markup is left completely alone (a regex cannot restructure
  * tables or lists safely). Anything not listed here survives as raw HTML.
  */
-export function inlineHtmlToMarkdown(html) {
+/** Block-level HTML: its text is not inline Markdown. */
+/** HTML that STARTS an HTML block (CommonMark start condition 6): its text
+ *  is not read as Markdown. A block tag later in the line is inline HTML,
+ *  and the text around it is Markdown. */
+const HTML_BLOCK = /^\s*<\/?(?:table|thead|tbody|tr|td|th|pre|div|ul|ol|li|dl|dt|dd|blockquote|h[1-6]|section|details|summary|figure)\b/i;
+export function inlineHtmlToMarkdown(html, options = {}) {
     // Code spans are converted FIRST and then masked, so the emphasis/link rules
     // below cannot rewrite markup that is meant to be shown literally
     // (`<code><b>x</b></code>` must stay `<b>x</b>`, not become `**x**`).
@@ -123,6 +128,24 @@ export function inlineHtmlToMarkdown(html) {
         masked.push(codeSpanText(inner));
         return `\u0000CODE${masked.length - 1}\u0000`;
     });
+    // Text between tags is literal: `[x](javascript:…)` or `*x*` written there
+    // must not become a link or emphasis in the Markdown. Only when the
+    // result stays inline: inside an HTML BLOCK (a table, a <pre>, a <div>)
+    // CommonMark processes no escapes, so they would show as backslashes, and
+    // no Markdown is read there either. (Text is HTML here: `&lt;` already
+    // means `<`, so `&` and `<` are left alone.)
+    if (options.flatten || !HTML_BLOCK.test(out)) {
+        out = out.replace(/(^|>)([^<>]+)(?=<|$)/g, (_m, lead, text) => lead +
+            text
+                .replace(/\\/g, "\\\\")
+                .replace(/[*[\]]/g, "\\$&")
+                // A backtick as an entity: an escaped `\`` is still taken for a
+                // code-span delimiter by the MDX passes that mask code, and the
+                // braces between two of them were left live.
+                .replace(/`/g, "&#96;")
+                .replace(/~~/g, "\\~\\~")
+                .replace(/_+/g, (run, at, all) => /[A-Za-z0-9]/.test(all[at - 1] ?? "") && /[A-Za-z0-9]/.test(all[at + run.length] ?? "") ? run : run.replace(/_/g, "\\_")));
+    }
     out = out
         .replace(/<(?:strong|b)>([\s\S]*?)<\/(?:strong|b)>/gi, "**$1**")
         .replace(/<(?:em|i)>([\s\S]*?)<\/(?:em|i)>/gi, "*$1*")
@@ -131,10 +154,25 @@ export function inlineHtmlToMarkdown(html) {
         .replace(
     // `[^>]*` would stop at a `>` inside another attribute value
     // (`<a href="x" title="a > b">`), so skip quoted runs explicitly.
-    /<a\s+href="([^"]*)"(?:[^>"']|"[^"]*"|'[^']*')*>([\s\S]*?)<\/a>/gi, (_m, href, text) => `[${text}](${href})`)
+    /<a\s+href="([^"]*)"(?:[^>"']|"[^"]*"|'[^']*')*>([\s\S]*?)<\/a>/gi, 
+    // An unsafe scheme keeps the text and loses the link.
+    (_m, href, text) => {
+        const url = decodeAttr(href);
+        return isSafeHref(url) ? `[${text}](${markdownDestination(url)})` : text;
+    })
         .replace(/<br\s*\/?>/gi, "  \n");
     return out.replace(/\u0000CODE(\d+)\u0000/g, (_m, i) => masked[Number(i)]);
 }
+/** An HTML attribute value as the browser reads it (entities decoded). */
+function decodeAttr(v) {
+    return v
+        .replace(/&#x([0-9a-f]+);?/gi, (_m, h) => String.fromCodePoint(parseInt(h, 16)))
+        .replace(/&#(\d+);?/g, (_m, d) => String.fromCodePoint(Number(d)))
+        .replace(/&colon;/gi, ":")
+        .replace(/&tab;/gi, "\t")
+        .replace(/&newline;/gi, "\n")
+        .replace(/&amp;/gi, "&");
+}
 /** CommonMark code span (see serialize-core `codeSpan`; duplicated here to keep
  *  text.ts free of an inline.ts import cycle). */
 function codeSpanText(text) {
@@ -188,4 +226,262 @@ export function frontmatterBlock(entries) {
         return "";
     return `---\n${lines.join("\n")}\n---`;
 }
+/** A URL written as text: GFM autolinks it, so a backslash or `_` escape
+ *  inside it would land in the href. */
+const URL_TEXT = /\b(?:https?:\/\/|www\.)[^\s<>]+/g;
+/**
+ * Text → CommonMark (or MDX) that reads back as the same text.
+ *
+ * A TreeNode `text` is LITERAL: an importer that met `&lt;script&gt;`, `\*`
+ * or `\[x\](…)` in its source stored `<script>`, `*`, `[x](…)`. Written into
+ * Markdown unescaped, those become a live element, emphasis and a link —
+ * the Docusaurus `.md` export put a spec's `<script>` and a
+ * `[x](javascript:…)` link into the site that way.
+ *
+ * - `<`, `{` and `}` become ENTITIES (`&lt;`, `&#123;`, `&#125;`), which read
+ *   the same in CommonMark and MDX and which no later MDX pass re-reads. A
+ *   backslash form did not survive Docusaurus' `sanitizeForMdx`: the text
+ *   `\{` became `\\{`, a literal backslash and a live expression.
+ * - `&` before an entity name becomes `&amp;`.
+ * - Backslash, `` ` ``, `*`, `[`, `]`, `~~` and a run of `_` at a word edge
+ *   are backslash-escaped. Both brackets: an unbalanced `\]` let
+ *   `[@dependabot[bot]](url)` link the wrong text. A task marker (`[ ]`,
+ *   `[x]`) starting the text is kept: GFM and Obsidian draw it as a
+ *   checkbox, and the parser keeps it as text.
+ * - A URL written as text keeps its `_` and `\` (GFM autolinks it, and an
+ *   escape would end up in the href); its brackets and backticks are still
+ *   escaped.
+ *
+ * `mdx: true` also escapes a `<` before any non-space character (`<3` is a
+ * syntax error in MDX), not only a tag-shaped one, and braces. Without it
+ * braces stay, as CommonMark reads them as text.
+ */
+export function escapeMarkdownText(text, options = {}) {
+    const bs = options.style === "backslash";
+    const task = /^\s*\[[ xX]\](?=\s|$)/.exec(text);
+    const head = task ? task[0] : "";
+    const body = text.slice(head.length);
+    const common = (s) => s
+        .replace(/&(?=#?[A-Za-z0-9]+;)/g, "&amp;")
+        .replace(options.mdx ? /<(?=\S|$)/g : /<(?=[A-Za-z/!?])/g, bs ? "\\<" : "&lt;")
+        .replace(options.mdx ? /[{}]/g : /(?!)/g, (b) => (bs ? `\\${b}` : b === "{" ? "&#123;" : "&#125;"))
+        .replace(/[[\]]/g, "\\$&")
+        .replace(/`/g, bs ? "\\`" : "&#96;")
+        // A `$` in text is a dollar, not math: remark-math and MDX passes
+        // that mask `$…$` must not see a span (its braces stayed live).
+        .replace(/\$/g, bs ? "\\$" : "&#36;");
+    const prose = (s) => common(s.replace(/\\/g, "\\\\"))
+        .replace(/\*/g, "\\*")
+        .replace(/~~/g, "\\~\\~")
+        .replace(/_+/g, (run, at, all) => {
+        const before = all[at - 1] ?? "";
+        const after = all[at + run.length] ?? "";
+        return /[A-Za-z0-9]/.test(before) && /[A-Za-z0-9]/.test(after) ? run : run.replace(/_/g, "\\_");
+    });
+    let out = "";
+    let last = 0;
+    for (const m of body.matchAll(URL_TEXT)) {
+        out += prose(body.slice(last, m.index)) + common(m[0]);
+        last = m.index + m[0].length;
+    }
+    return head + out + prose(body.slice(last));
+}
+/**
+ * May this URL be written as a link or image destination? Not a
+ * `javascript:`, `vbscript:` or `data:` URL (a `data:image/` source is
+ * allowed for images), however it is cased or padded with control
+ * characters and whitespace — browsers strip those before reading the
+ * scheme. markdown-it refuses these when it PARSES Markdown; a link node an
+ * importer built directly never passed that check.
+ */
+export function isSafeHref(href, kind = "link") {
+    const scheme = href.replace(/[\u0000-\u0020\u007f]+/g, "").toLowerCase();
+    if (/^(?:javascript|vbscript):/.test(scheme))
+        return false;
+    if (/^data:/.test(scheme))
+        return kind === "image" && /^data:image\/(?:gif|png|jpeg|webp);/.test(scheme);
+    return true;
+}
+/**
+ * Markdown from a string we did not write (an OpenAPI description, which
+ * the spec defines as CommonMark) made inert where it could run: raw HTML
+ * (`<` before a tag name becomes `&lt;`, which still reads `<`) and link or
+ * definition destinations with a `javascript:`/`vbscript:`/`data:` scheme
+ * (their `](` is escaped, so the text stays and the link goes). The rest of
+ * the Markdown is kept.
+ */
+export function neutralizeMarkdown(md) {
+    // Code is shown, not read: a `<token>` in a code span or fence stays.
+    const masked = [];
+    const mask = (m) => `\u0000M${masked.push(m) - 1}\u0000`;
+    let out = maskFencedCode(md, mask);
+    out = mapOutsideCodeSpans(out, (prose) => prose
+        // A safe angle-bracket destination is rewritten plain (percent-
+        // encoded), so every `<` left can be escaped without exception.
+        .replace(/\]\(\s*<([^<>\n]*)>/g, (m, url) => isSafeHref(markdownUrl(url)) ? `](${markdownDestination(markdownUrl(url))}` : `\\](${url}`)
+        // A destination whose scheme could run, however it is spelled:
+        // entities and backslash escapes decoded first, as the reader does.
+        // Escaping the `]` keeps the text and drops the link.
+        // (Not one the angle-bracket pass above already escaped: `\](`.)
+        .replace(/(?<!\\)\](\(\s*)([^\s)<>]*)/g, (m, open, dest) => isSafeHref(markdownUrl(dest)) ? m : `\\]${open}${dest}`)
+        .replace(/^(\s{0,3}\[[^\]\n]*)\](:\s*<?)(\S*)/gm, (m, label, sep, dest) => isSafeHref(markdownUrl(dest)) ? m : `${label}\\]${sep}${dest}`)
+        .replace(/<(?=[A-Za-z/!?])/g, "&lt;"));
+    return out.replace(/\u0000M(\d+)\u0000/g, (_m, n) => masked[Number(n)]);
+}
+/**
+ * Replace each fenced code block (opening line to its closing fence, or to
+ * the end) with `mask(block)`. Line by line: a RegExp backtracked
+ * quadratically on one long line of backticks.
+ */
+function maskFencedCode(md, mask) {
+    const lines = md.split("\n");
+    const out = [];
+    for (let i = 0; i < lines.length; i++) {
+        const open = /^ {0,3}(`{3,}|~{3,})/.exec(lines[i]);
+        // A backtick fence's info string may not contain a backtick.
+        if (!open || (open[1][0] === "`" && lines[i].slice(open[0].length).includes("`"))) {
+            out.push(lines[i]);
+            continue;
+        }
+        const fence = open[1];
+        let j = i + 1;
+        while (j < lines.length) {
+            const close = /^ {0,3}(`+|~+)[ \t]*$/.exec(lines[j]);
+            if (close && close[1][0] === fence[0] && close[1].length >= fence.length)
+                break;
+            j++;
+        }
+        out.push(mask(lines.slice(i, Math.min(j, lines.length - 1) + 1).join("\n")));
+        i = j;
+    }
+    return out.join("\n");
+}
+/**
+ * Apply `fn` to the parts of `md` outside inline code spans, leaving the
+ * spans as written. Spans are found as CommonMark finds them — a run of N
+ * backticks closed by the next run of exactly N, a backslash-escaped
+ * backtick opening nothing — in one pass over the runs (a backtracking
+ * RegExp took 7.6 s on 50,000 backticks).
+ */
+export function mapOutsideCodeSpans(md, fn) {
+    const runs = [];
+    for (let i = 0; i < md.length;) {
+        if (md[i] !== "`") {
+            i++;
+            continue;
+        }
+        let j = i;
+        while (md[j] === "`")
+            j++;
+        let bs = 0;
+        for (let k = i - 1; k >= 0 && md[k] === "\\"; k--)
+            bs++;
+        // An escaped first backtick is literal; the rest of the run still counts.
+        if (bs % 2) {
+            if (j - i > 1)
+                runs.push({ at: i + 1, len: j - i - 1 });
+        }
+        else
+            runs.push({ at: i, len: j - i });
+        i = j;
+    }
+    const byLen = new Map();
+    runs.forEach((r, n) => {
+        const list = byLen.get(r.len);
+        if (list)
+            list.push(n);
+        else
+            byLen.set(r.len, [n]);
+    });
+    const next = new Map(); // len → index into byLen list
+    let out = "";
+    let from = 0;
+    for (let n = 0; n < runs.length; n++) {
+        const r = runs[n];
+        if (r.at < from)
+            continue;
+        const list = byLen.get(r.len);
+        let k = next.get(r.len) ?? 0;
+        while (k < list.length && list[k] <= n)
+            k++;
+        next.set(r.len, k);
+        if (k >= list.length)
+            continue; // no closer: literal backticks
+        const close = runs[list[k]];
+        out += fn(md.slice(from, r.at)) + md.slice(r.at, close.at + close.len);
+        from = close.at + close.len;
+        n = list[k];
+    }
+    return out + fn(md.slice(from));
+}
+/** A Markdown destination as the reader resolves it: backslash escapes
+ *  and character references decoded. */
+function markdownUrl(dest) {
+    return decodeAttr(dest.replace(/\\([!-/:-@[-`{-~])/g, "$1"));
+}
+/**
+ * A URL as a Markdown link or image destination that the reader resolves
+ * back to the same URL, and that nothing in it can end: `&` becomes `&amp;`
+ * (so `javascript&#58;` stays those characters rather than decoding to a
+ * scheme), a backslash is escaped, and space, `(`, `)`, `<`, `>` and control
+ * characters are percent-encoded (a `)` ended the destination and the rest
+ * became live Markdown).
+ */
+export function markdownDestination(url) {
+    return url
+        // Only an `&` the reader would decode (`&#58;`, `&amp;`): `Q&A.md` stays.
+        .replace(/&(?=#?[A-Za-z0-9]+;)/g, "&amp;")
+        .replace(/\\/g, "\\\\")
+        .replace(/[\u0000-\u0020\u007f()<>]/g, (c) => "%" + c.charCodeAt(0).toString(16).toUpperCase().padStart(2, "0"));
+}
+/** A link or image title: one line, its quotes and backslashes escaped. */
+export function markdownTitle(title) {
+    return title ? ` "${title.replace(/\s*[\r\n]+\s*/g, " ").replace(/["\\]/g, "\\$&")}"` : "";
+}
+/**
+ * A tag-shaped `<` in LaTeX becomes `< ` (with a space): inert as HTML,
+ * and the same to KaTeX/MathJax in math mode. Where no math plugin is
+ * configured the span is plain Markdown, and a `<script>` in the LaTeX was
+ * live. (`\lt` broke `\text{a<b}`.)
+ */
+function inertLatex(latex) {
+    return latex.replace(/<(?=[A-Za-z/!?])/g, "< ");
+}
+/**
+ * LaTeX for `$…$` / `$$…$$` math read by arithmatex (MkDocs) or Obsidian:
+ * an unescaped `$` would close the span early, so it becomes `\$`.
+ */
+export function markdownLatex(latex) {
+    return inertLatex(latex).replace(/(\\*)\$/g, (m, bs) => (bs.length % 2 ? m : `${bs}\\$`));
+}
+/**
+ * Math for remark-math / micromark (Docusaurus, MDX targets), which reads
+ * `$` like code: a run of N dollars is closed by a run of N, and `\$` does
+ * NOT escape. The delimiter is sized past any run in the LaTeX instead.
+ */
+export function remarkMath(latex, display) {
+    const tex = inertLatex(latex);
+    const longest = Math.max(0, ...[...tex.matchAll(/\$+/g)].map((m) => m[0].length));
+    if (display) {
+        const fence = "$".repeat(Math.max(2, longest + 1));
+        return `${fence}\n${tex}\n${fence}`;
+    }
+    const fence = "$".repeat(longest + 1);
+    const pad = /^\$|\$$/.test(tex) ? " " : "";
+    return `${fence}${pad}${tex}${pad}${fence}`;
+}
+/**
+ * A footnote label every reader accepts, written the same way for the
+ * reference and its definition. Injective: other characters are
+ * hex-encoded (`note.1` → `note_x2e_1`), not deleted, so `*` and `†` do
+ * not collide with footnote 1.
+ */
+export function footnoteLabel(label) {
+    const out = String(label).replace(/[^A-Za-z0-9-]|_/g, (c) => `_x${c.codePointAt(0).toString(16)}_`);
+    return out || "1";
+}
+/** An id for `{#id}` or `id="…"`: characters that cannot end either. */
+export function safeAnchorId(id) {
+    return id.replace(/[^\w.:-]/g, "-");
+}
 //# sourceMappingURL=text.js.map