officeparser 7.2.3 → 7.4.0

package/dist/generators/MarkdownGenerator.js

@@ -1,7 +1,87 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.MarkdownGenerator = void 0;
+const sanitize_js_1 = require("../utils/sanitize.js");
 const BaseGenerator_js_1 = require("./BaseGenerator.js");
+const errorUtils_js_1 = require("../utils/errorUtils.js");
+/**
+ * Values accepted for an attribute-list `align=`. Matches what `MarkdownParser`'s own
+ * `parseAttributeList` allowlists on import (plus `justify`, which HTML sources can supply),
+ * so this is lossless for anything the parser produced.
+ */
+const MD_ALIGN_VALUES = new Set(['left', 'center', 'right', 'justify']);
+/** A CSS length or percentage - the only shape `width=` legitimately carries. */
+const MD_LENGTH_PATTERN = /^\d+(?:\.\d+)?(?:px|%|em|rem|pt|pc|in|cm|mm|ex|ch|vw|vh)?$/;
+/** Admonition kinds, mirroring the union declared on `AdmonitionMetadata` in types.ts. */
+const MD_ADMONITION_TYPES = new Set(['note', 'tip', 'important', 'warning', 'caution']);
+/**
+ * Folds line breaks to spaces.
+ *
+ * Used on values that sit inside a single-line construct (an abbreviation definition, an
+ * admonition's bold title). A raw newline there does not merely look wrong: it terminates the
+ * construct and exposes whatever follows as document-level Markdown.
+ */
+const foldLines = (value) => String(value ?? '').replace(/[\r\n]+/g, ' ');
+/**
+ * Named Markdown dialect presets. `extended` reproduces this library's historical output
+ * exactly (every feature on, GitHub-style admonitions) - the backward-compatibility anchor.
+ */
+const MARKDOWN_DIALECT_PRESETS = {
+    extended: { admonitions: 'github', definitionLists: true, footnotes: true, citations: true, wikilinks: true, math: 'dollar', attributeLists: true, strikethrough: true, bulletListMarker: '-', orderedListMarker: '.', emphasisMarker: 'asterisk', tables: 'native' },
+    github: { admonitions: 'github', definitionLists: false, footnotes: true, citations: false, wikilinks: false, math: 'dollar', attributeLists: false, strikethrough: true, bulletListMarker: '-', orderedListMarker: '.', emphasisMarker: 'asterisk', tables: 'native' },
+    gitlab: { admonitions: 'gitlab', definitionLists: false, footnotes: true, citations: false, wikilinks: false, math: 'dollar', attributeLists: false, strikethrough: true, bulletListMarker: '-', orderedListMarker: '.', emphasisMarker: 'asterisk', tables: 'native' },
+    obsidian: { admonitions: 'github', definitionLists: false, footnotes: true, citations: false, wikilinks: true, math: 'dollar', attributeLists: false, strikethrough: true, bulletListMarker: '-', orderedListMarker: '.', emphasisMarker: 'asterisk', tables: 'native' },
+    pandoc: { admonitions: 'pandoc', definitionLists: true, footnotes: true, citations: true, wikilinks: false, math: 'dollar', attributeLists: true, strikethrough: true, bulletListMarker: '-', orderedListMarker: '.', emphasisMarker: 'asterisk', tables: 'native' },
+    commonmark: { admonitions: 'none', definitionLists: false, footnotes: false, citations: false, wikilinks: false, math: 'none', attributeLists: false, strikethrough: false, bulletListMarker: '-', orderedListMarker: '.', emphasisMarker: 'asterisk', tables: 'html' },
+};
+/**
+ * Normalizes `MdGeneratorConfig.dialect` into a fully-resolved preset. A string names a preset
+ * directly; an object's `extends` field (default `'extended'`) names the base preset that any
+ * omitted field falls back to - NOT "whatever preset was ambient before", since config merging
+ * replaces the whole `dialect` field rather than layering an object on top of a prior string.
+ */
+function resolveDialect(dialect) {
+    if (dialect === undefined)
+        return MARKDOWN_DIALECT_PRESETS.extended;
+    if (typeof dialect === 'string')
+        return MARKDOWN_DIALECT_PRESETS[dialect] ?? MARKDOWN_DIALECT_PRESETS.extended;
+    const base = MARKDOWN_DIALECT_PRESETS[dialect.extends ?? 'extended'] ?? MARKDOWN_DIALECT_PRESETS.extended;
+    return {
+        admonitions: dialect.admonitions ?? base.admonitions,
+        definitionLists: dialect.definitionLists ?? base.definitionLists,
+        footnotes: dialect.footnotes ?? base.footnotes,
+        citations: dialect.citations ?? base.citations,
+        wikilinks: dialect.wikilinks ?? base.wikilinks,
+        math: dialect.math ?? base.math,
+        attributeLists: dialect.attributeLists ?? base.attributeLists,
+        strikethrough: dialect.strikethrough ?? base.strikethrough,
+        bulletListMarker: dialect.bulletListMarker ?? base.bulletListMarker,
+        orderedListMarker: dialect.orderedListMarker ?? base.orderedListMarker,
+        emphasisMarker: dialect.emphasisMarker ?? base.emphasisMarker,
+        tables: dialect.tables ?? base.tables,
+    };
+}
+/**
+ * Normalizes `MdGeneratorConfig.fallbackToHtml` into a fully resolved object, mirroring
+ * `HtmlGenerator`'s `resolveStandalone()` pattern: `true`/undefined turns every part on; `false`
+ * turns every part off; an object's omitted fields default to on.
+ */
+function resolveFallbackToHtml(fallbackToHtml) {
+    const uniform = (on) => ({
+        textFormatting: on, alignment: on, anchors: on, tables: on, embeds: on, cellLineBreaks: on,
+    });
+    if (fallbackToHtml === undefined || typeof fallbackToHtml === 'boolean')
+        return uniform(fallbackToHtml ?? true);
+    const on = uniform(true);
+    return {
+        textFormatting: fallbackToHtml.textFormatting ?? on.textFormatting,
+        alignment: fallbackToHtml.alignment ?? on.alignment,
+        anchors: fallbackToHtml.anchors ?? on.anchors,
+        tables: fallbackToHtml.tables ?? on.tables,
+        embeds: fallbackToHtml.embeds ?? on.embeds,
+        cellLineBreaks: fallbackToHtml.cellLineBreaks ?? on.cellLineBreaks,
+    };
+}
 /**
  * Generates Markdown from an AST.
  *
@@ -11,11 +91,11 @@ const BaseGenerator_js_1 = require("./BaseGenerator.js");
  *    be used for these features.
  *
  * 2. **Fidelity vs. Purity (The `fallbackToHtml` Principle)**:
- *    - When `fallbackToHtml` is TRUE: The generator prioritizes high-fidelity document
- *      conversion. It will use HTML tags for features that Markdown cannot natively
- *      represent (e.g., `<u>` for underline, `<div>` for alignment, `<table>` for
- *      nested structures or merged cells).
- *    - When `fallbackToHtml` is FALSE: The generator prioritizes "pure" Markdown.
+ *    - When a given `fallbackToHtml` part is TRUE: The generator prioritizes high-fidelity
+ *      document conversion for that part. It will use HTML tags for features that Markdown
+ *      cannot natively represent (e.g., `<u>` for underline, `<div>` for alignment, `<table>`
+ *      for nested structures or merged cells).
+ *    - When FALSE: The generator prioritizes "pure" Markdown for that part.
  *      Unsupported features are either:
  *      - **Skipped**: Non-essential formatting like underline, subscript, superscript,
  *        or text alignment is omitted.
@@ -25,22 +105,82 @@ const BaseGenerator_js_1 = require("./BaseGenerator.js");
  *
  * 3. **Consistency**: All similar structural or formatting ideological problems must be
  *    resolved using these same rules to ensure predictable output.
+ *
+ * 4. **Dialect (`MdGeneratorConfig.dialect`)**: A second, independent axis from `fallbackToHtml` -
+ *    which *native* Markdown syntax to emit for constructs with more than one real-world
+ *    convention (admonitions, definition lists, footnotes, citations, wikilinks, math, list/
+ *    emphasis markers, tables). See `resolveDialect()` and `MARKDOWN_DIALECT_PRESETS` above.
  */
 class MarkdownGenerator extends BaseGenerator_js_1.BaseGenerator {
     isInsideTable = false;
     hoistedContent = [];
+    collectedAbbreviations = new Map();
+    resolvedDialect;
+    resolvedFallbackToHtml;
     constructor(ast, config) {
         super('md', ast, config);
+        this.resolvedDialect = resolveDialect(this.config.mdConfig.dialect);
+        this.resolvedFallbackToHtml = resolveFallbackToHtml(this.config.mdConfig.fallbackToHtml);
     }
     /**
      * Renders anchor tags if HTML fallback is allowed.
      */
     renderAnchors(metadata) {
-        if (!this.config.mdConfig.fallbackToHtml || this.config.ignoreInternalLinks)
+        if (!this.resolvedFallbackToHtml.anchors || this.config.ignoreInternalLinks)
             return '';
         const ids = metadata?.anchorIds || [];
         return ids.map((aid) => `<a id="${this.slugify(aid)}"></a>`).join('');
     }
+    /**
+     * Serializes a frontmatter array as a YAML flow sequence (e.g. `[a, b]`), matching
+     * MarkdownParser's frontmatter array handling. Plain strings are left bare; anything
+     * that would break flow-array syntax (or isn't a string) falls back to JSON encoding.
+     */
+    serializeFrontmatterArray(arr) {
+        const items = arr.map(item => (typeof item === 'string' && item.trim() === item && !/[,[\]]/.test(item))
+            ? item
+            : JSON.stringify(item));
+        return `[${items.join(', ')}]`;
+    }
+    /**
+     * Renders a Pandoc-style attribute list (e.g. `{width=50% align=left}`) from
+     * ImageMetadata/TableMetadata's width/align fields - the canonical form is always
+     * `key=value`, matching MarkdownParser's own vocabulary (MARKDOWN_DIALECT.md §15).
+     */
+    renderAttributeList(meta) {
+        if (!this.resolvedDialect.attributeLists)
+            return '';
+        if (!meta?.width && !meta?.align)
+            return '';
+        const parts = [];
+        // Allowlist, not escape. These land in `metadata.width`/`align` on reparse, which the
+        // parser does NOT entity-decode, so encoding here would not round-trip - and stripping
+        // alone is not enough: the previous `[{}\s]+` guard removed whitespace, which stops
+        // `<img src=x onerror=…>` but not the slash-separated `<img/src=x/onerror=…>`.
+        // Both values have a small, fully-known shape, so matching that shape is both safer and
+        // lossless for anything a parser can produce.
+        //
+        // (`isValidContainerWidth` in utils/configUtils.ts is a near-identical regex, but it is a
+        // config validator that also accepts 'auto' and numbers; importing configUtils here for
+        // one pattern would be a worse coupling than this local constant.)
+        if (meta.width && MD_LENGTH_PATTERN.test(String(meta.width).trim())) {
+            parts.push(`width=${String(meta.width).trim()}`);
+        }
+        if (meta.align && MD_ALIGN_VALUES.has(String(meta.align).trim().toLowerCase())) {
+            parts.push(`align=${String(meta.align).trim().toLowerCase()}`);
+        }
+        if (parts.length === 0)
+            return '';
+        return `{${parts.join(' ')}}`;
+    }
+    /** Converts a document-supplied date to an ISO string, or '' if invalid
+     *  (a malformed date would otherwise throw a RangeError and abort generation). */
+    toIsoDate(value) {
+        if (value === undefined || value === null || value === '')
+            return '';
+        const d = new Date(value);
+        return isNaN(d.getTime()) ? '' : d.toISOString();
+    }
     /**
      * Generates Markdown string from the provided AST.
      *
@@ -49,21 +189,34 @@ class MarkdownGenerator extends BaseGenerator_js_1.BaseGenerator {
     async generate() {
         let output = '';
         // Add Metadata (YAML Front Matter)
-        if (this.ast.metadata) {
+        const meta = this.effectiveMetadata;
+        if (meta) {
             output += '---\n';
-            if (this.ast.metadata.title)
-                output += `title: "${this.ast.metadata.title}"\n`;
-            if (this.ast.metadata.author)
-                output += `author: "${this.ast.metadata.author}"\n`;
-            if (this.ast.metadata.created)
-                output += `created: ${new Date(this.ast.metadata.created).toISOString()}\n`;
-            if (this.ast.metadata.modified)
-                output += `modified: ${new Date(this.ast.metadata.modified).toISOString()}\n`;
-            if (this.ast.metadata.description)
-                output += `description: "${this.ast.metadata.description}"\n`;
-            if (this.ast.metadata.customProperties) {
-                for (const [key, val] of Object.entries(this.ast.metadata.customProperties)) {
-                    output += `${key}: ${JSON.stringify(val)}\n`;
+            // JSON-encode scalar values so a title/author/description containing a
+            // quote or newline can't break out of the YAML string and inject
+            // arbitrary front-matter keys. (JSON.stringify of a benign value yields
+            // the same `"..."` form as before, so normal output is unchanged.)
+            if (meta.title)
+                output += `title: ${JSON.stringify(meta.title)}\n`;
+            if (meta.author)
+                output += `author: ${JSON.stringify(meta.author)}\n`;
+            const createdIso = this.toIsoDate(meta.created);
+            if (createdIso)
+                output += `created: ${createdIso}\n`;
+            const modifiedIso = this.toIsoDate(meta.modified);
+            if (modifiedIso)
+                output += `modified: ${modifiedIso}\n`;
+            if (meta.description)
+                output += `description: ${JSON.stringify(meta.description)}\n`;
+            if (meta.subject)
+                output += `subject: ${JSON.stringify(meta.subject)}\n`;
+            if (meta.keywords)
+                output += `keywords: ${JSON.stringify(meta.keywords)}\n`;
+            if (meta.customProperties) {
+                for (const [key, val] of Object.entries(meta.customProperties)) {
+                    // Strip newlines/colons from the key so it can't inject a new mapping.
+                    const safeKey = String(key).replace(/[\r\n:]+/g, ' ').trim();
+                    output += `${safeKey}: ${Array.isArray(val) ? this.serializeFrontmatterArray(val) : JSON.stringify(val)}\n`;
                 }
             }
             output += '---\n\n';
@@ -87,16 +240,19 @@ class MarkdownGenerator extends BaseGenerator_js_1.BaseGenerator {
             }
             switch (node.type) {
                 case 'text': {
-                    let text = node.text || '';
+                    // Entity-encode angle brackets so document text can't inject a raw
+                    // HTML tag (e.g. <script>) when the Markdown is rendered to HTML.
+                    let text = (0, sanitize_js_1.markdownEscapeText)(node.text || '');
                     if (this.config.includeFormatting && node.formatting) {
+                        const emphasisAsterisk = this.resolvedDialect.emphasisMarker === 'asterisk';
                         if (node.formatting.bold)
-                            text = `**${text}**`;
+                            text = emphasisAsterisk ? `**${text}**` : `__${text}__`;
                         if (node.formatting.italic)
-                            text = `*${text}*`;
-                        if (node.formatting.strikethrough)
+                            text = emphasisAsterisk ? `*${text}*` : `_${text}_`;
+                        if (node.formatting.strikethrough && this.resolvedDialect.strikethrough)
                             text = `~~${text}~~`;
                         // Use HTML tags for formatting not natively supported by standard Markdown
-                        if (this.config.mdConfig.fallbackToHtml) {
+                        if (this.resolvedFallbackToHtml.textFormatting) {
                             if (node.formatting.underline)
                                 text = `<u>${text}</u>`;
                             if (node.formatting.subscript)
@@ -106,18 +262,52 @@ class MarkdownGenerator extends BaseGenerator_js_1.BaseGenerator {
                         }
                     }
                     const meta = node.metadata;
-                    if (meta?.link) {
+                    if (meta?.wikilink && this.resolvedDialect.wikilinks) {
+                        // Obsidian syntax: bare page name, or page|alias when the display
+                        // text differs from the page name. Strip the `[]|`/newline chars
+                        // that would break out of the `[[...]]` wrapper.
+                        // The alias must be built from the ESCAPED text, not from raw node.text.
+                        // Rebuilding from the raw value here discarded the markdownEscapeText()
+                        // applied above, so a wikilink was the one place document text reached
+                        // the output unescaped. Escaping is lossless for the alias specifically,
+                        // because it lands back in a text node, which the parser entity-decodes.
+                        const alias = (0, sanitize_js_1.markdownEscapeText)(node.text || '').replace(/[[\]|\r\n]+/g, '');
+                        // `page` lands in metadata.link, which is NOT entity-decoded on reparse,
+                        // so it gets `<` dropped rather than encoded - a page name is an
+                        // identifier, and `<` carries no meaning in one.
+                        const page = (meta.link || '').replace(/[[\]|<\r\n]+/g, '');
+                        text = (node.text && node.text !== (meta.link || '')) ? `[[${page}|${alias}]]` : `[[${page}]]`;
+                    }
+                    else if (meta?.link) {
                         const isInternal = meta.linkType !== 'external';
                         if (!this.config.ignoreInternalLinks || !isInternal) {
                             let link = meta.link;
                             // Slugify internal link targets to match heading IDs if generating IDs
-                            if (isInternal && link.startsWith('#') && (this.config.generateIds || this.config.mdConfig.fallbackToHtml)) {
+                            if (isInternal && link.startsWith('#') && (this.config.generateIds || this.resolvedFallbackToHtml.anchors)) {
                                 const target = link.substring(1);
                                 link = '#' + this.slugify(target);
                             }
-                            text = `[${text}](${link})`;
+                            // Reject javascript:/data: schemes and encode `()`/whitespace so the
+                            // URL can't break out of `](...)` or inject a script link.
+                            text = `[${text}](${(0, sanitize_js_1.sanitizeMarkdownUrl)(link)})`;
                         }
                     }
+                    if (meta?.abbreviationTitle) {
+                        // Markdown Extra's abbreviation syntax has no inline marker - the bare
+                        // word round-trips as-is, with its expansion collected at the document
+                        // end via `*[abbr]: title`.
+                        this.collectedAbbreviations.set(node.text || '', meta.abbreviationTitle);
+                    }
+                    if (meta?.citationKey) {
+                        // Allowlist to exactly the character class MarkdownParser's own citation
+                        // recognizer accepts, so this is provably lossless for anything it
+                        // produced - while fully neutralizing a key arriving from HtmlParser's
+                        // `data-citation-key`, which accepts any string. Like the wikilink above,
+                        // this branch also replaces `text` wholesale, so a strip that left `<`
+                        // behind discarded the escaping applied earlier.
+                        const key = String(meta.citationKey).replace(/[^a-zA-Z0-9_:.-]/g, '');
+                        text = this.resolvedDialect.citations ? `[@${key}]` : `[${key}]`;
+                    }
                     return text;
                 }
                 case 'heading': {
@@ -136,14 +326,14 @@ class MarkdownGenerator extends BaseGenerator_js_1.BaseGenerator {
                     else if (this.config.generateIds) {
                         id = ` {#${this.slugify(this.getNodeText(node))}}`;
                     }
-                    const anchors = this.config.mdConfig.fallbackToHtml
-                        ? remainingAnchors.map(aid => `<a name="${aid}"></a>`).join('')
+                    const anchors = this.resolvedFallbackToHtml.anchors
+                        ? remainingAnchors.map(aid => `<a name="${this.slugify(aid)}"></a>`).join('')
                         : '';
                     let content = `${prefix}${childrenOutput}${id}`;
                     // Alignment fallback via HTML div/p
-                    if (this.config.mdConfig.fallbackToHtml && meta?.alignment && meta.alignment !== 'left') {
+                    if (this.resolvedFallbackToHtml.alignment && meta?.alignment && meta.alignment !== 'left') {
                         // Use extra newlines to ensure Markdown inside the div is parsed
-                        content = `<div style="text-align: ${meta.alignment}">\n\n${content}\n\n</div>`;
+                        content = `<div style="text-align: ${(0, sanitize_js_1.sanitizeCssValue)(meta.alignment)}">\n\n${content}\n\n</div>`;
                     }
                     return `${anchors}${anchors ? '\n' : ''}${content}\n\n`;
                 }
@@ -152,8 +342,8 @@ class MarkdownGenerator extends BaseGenerator_js_1.BaseGenerator {
                     const anchors = this.renderAnchors(meta);
                     let content = childrenOutput;
                     // Alignment fallback via HTML div/p
-                    if (this.config.mdConfig.fallbackToHtml && meta?.alignment && meta.alignment !== 'left') {
-                        content = `<div style="text-align: ${meta.alignment}">${content}</div>`;
+                    if (this.resolvedFallbackToHtml.alignment && meta?.alignment && meta.alignment !== 'left') {
+                        content = `<div style="text-align: ${(0, sanitize_js_1.sanitizeCssValue)(meta.alignment)}">${content}</div>`;
                     }
                     return childrenOutput ? `${anchors}${content}\n\n` : '';
                 }
@@ -161,7 +351,10 @@ class MarkdownGenerator extends BaseGenerator_js_1.BaseGenerator {
                     const meta = node.metadata;
                     const indentSpaces = ' '.repeat(4);
                     const indent = indentSpaces.repeat(meta?.indentation || 0);
-                    const marker = meta?.listType === 'ordered' ? `${(meta.itemIndex ?? 0) + 1}. ` : '- ';
+                    const bullet = `${this.resolvedDialect.bulletListMarker} `;
+                    const marker = meta?.isTask
+                        ? (meta.checked ? `${bullet}[x] ` : `${bullet}[ ] `)
+                        : (meta?.listType === 'ordered' ? `${(meta.itemIndex ?? 0) + 1}${this.resolvedDialect.orderedListMarker} ` : bullet);
                     const anchors = this.renderAnchors(meta);
                     return `${indent}${marker}${anchors}${childrenOutput}\n`;
                 }
@@ -179,11 +372,25 @@ class MarkdownGenerator extends BaseGenerator_js_1.BaseGenerator {
                         }
                     }
                     const anchors = this.renderAnchors(meta);
-                    return `${anchors}${anchors ? '\n' : ''}![${alt}](${src})`;
+                    // Strip `[]` from alt (would close the `![...]`) and neutralize the URL scheme.
+                    const safeAlt = (0, sanitize_js_1.markdownEscapeText)(alt).replace(/[[\]]/g, '');
+                    const safeSrc = (0, sanitize_js_1.sanitizeMarkdownUrl)(src, { allowDataImage: true });
+                    return `${anchors}${anchors ? '\n' : ''}![${safeAlt}](${safeSrc})${this.renderAttributeList(meta)}`;
                 }
                 case 'table': {
                     const anchors = this.renderAnchors(node.metadata);
                     const tableOutput = await this.renderMarkdownTable(node, processor);
+                    // The HTML-fallback path (merged cells/nested tables, or a dialect that forces
+                    // HTML tables outright) already carries data-align on the <table> tag directly -
+                    // only the plain pipe-table form needs the attribute-list syntax for alignment.
+                    const usedHtmlFallback = this.resolvedDialect.tables === 'html' ||
+                        (this.resolvedFallbackToHtml.tables && (this.hasNestedTable(node) || this.hasColspanOrRowspan(node)));
+                    const attrList = usedHtmlFallback ? '' : this.renderAttributeList(node.metadata);
+                    if (attrList) {
+                        // Must glue directly below the last row with no blank line, or
+                        // MarkdownParser's block splitter won't see it as part of the same block.
+                        return `${anchors}${anchors ? '\n' : ''}${tableOutput.replace(/\n+$/, '\n')}${attrList}\n`;
+                    }
                     return `${anchors}${anchors ? '\n' : ''}${tableOutput}`;
                 }
                 case 'row':
@@ -192,17 +399,60 @@ class MarkdownGenerator extends BaseGenerator_js_1.BaseGenerator {
                     return childrenOutput;
                 }
                 case 'break': {
+                    // A hard line break (CommonMark: two trailing spaces before the
+                    // newline) round-trips back to a distinct 'break' node on reparse;
+                    // every other breakType (including 'page', used for a thematic-break
+                    // HR) keeps emitting a bare newline, unchanged.
+                    const meta = node.metadata;
+                    if (meta?.breakType === 'carriageReturn')
+                        return '  \n';
                     return '\n';
                 }
                 case 'code': {
                     const meta = node.metadata;
-                    const lang = meta?.language || '';
-                    // Block code if it contains newlines, else inline
-                    if (node.text && node.text.includes('\n')) {
-                        return `\n\`\`\`${lang}\n${node.text}\n\`\`\`\n\n`;
+                    // Math content reached the output completely raw, which mattered most under
+                    // `math: 'none'` (the commonmark preset), where there is no `$` wrapper at
+                    // all and the text lands directly in the document body.
+                    //
+                    // Encode rather than drop: `$a < b$` is ordinary LaTeX, and dropping `<`
+                    // would silently corrupt real formulae. markdownEscapeText only touches `<`
+                    // followed by a letter/`/`/`!`/`?`, which is not idiomatic math, and it is
+                    // idempotent - so output is stable across repeated round-trips even though
+                    // the first cycle shifts an anomalous `<img` to `&lt;img`. (Fully lossless
+                    // would mean teaching MarkdownParser.decodeHtmlEntities to cover math `code`
+                    // nodes; that is a parser behaviour change with its own baseline
+                    // consequences and must not gate a security fix.)
+                    if (meta?.math === 'block') {
+                        // A content line of exactly `$$` would close the block early.
+                        const mathBlock = (0, sanitize_js_1.markdownEscapeText)(node.text || '')
+                            .split('\n').map(l => (l.trim() === '$$' ? ` ${l}` : l)).join('\n');
+                        return this.resolvedDialect.math === 'dollar' ? `\n$$\n${mathBlock}\n$$\n\n` : `\n${mathBlock}\n\n`;
+                    }
+                    if (meta?.math === 'inline') {
+                        // Dropping `$` and newlines is lossless here: the parser's own inline-math
+                        // recognizer is `\$(?!\s)([^$\n]+?)(?<!\s)\$`, which can never capture either.
+                        const mathInline = (0, sanitize_js_1.markdownEscapeText)(node.text || '').replace(/[$\r\n]+/g, '');
+                        return this.resolvedDialect.math === 'dollar' ? `$${mathInline}$` : mathInline;
+                    }
+                    const lang = (meta?.language || '').replace(/[\r\n`]+/g, '');
+                    // Block code if it contains a line break, else inline. Testing only for `\n`
+                    // routed a CR-only string to the inline branch, where a renderer that
+                    // normalizes `\r` to a line ending sees a blank line, the span dies, and the
+                    // remainder is exposed as raw Markdown. The fence sizing below is correct and
+                    // needs no change; code content itself is not an HTML context.
+                    if (node.text && /[\r\n]/.test(node.text)) {
+                        // Fence with one more backtick than the longest run inside the content
+                        // so an embedded ``` can't close the block early and inject markup.
+                        const longestRun = Math.max(0, ...(node.text.match(/`+/g) || []).map(s => s.length));
+                        const fence = '`'.repeat(Math.max(3, longestRun + 1));
+                        return `\n${fence}${lang}\n${node.text}\n${fence}\n\n`;
                     }
                     else {
-                        return `\`${node.text || ''}\` `;
+                        const t = node.text || '';
+                        const longestRun = Math.max(0, ...(t.match(/`+/g) || []).map(s => s.length));
+                        const fence = '`'.repeat(Math.max(1, longestRun + 1));
+                        const pad = (t.startsWith('`') || t.endsWith('`')) ? ' ' : '';
+                        return `${fence}${pad}${t}${pad}${fence} `;
                     }
                 }
                 case 'sheet': {
@@ -220,9 +470,80 @@ class MarkdownGenerator extends BaseGenerator_js_1.BaseGenerator {
                 }
                 case 'note': {
                     const meta = node.metadata;
-                    const typeLabel = meta?.noteType === 'footnote' ? 'Footnote' : (meta?.noteType === 'endnote' ? 'Endnote' : 'Note');
-                    return `> **${typeLabel}:** ${childrenOutput.trim()}\n\n`;
+                    if (meta?.noteType === 'footnote' || meta?.noteType === 'endnote') {
+                        if (!this.resolvedDialect.footnotes) {
+                            // Dialect has no footnote syntax - the caller inlines this bare body
+                            // as a parenthetical at the reference point instead of collecting it
+                            // into an end-of-document "### Notes" section under a [^id] marker.
+                            return childrenOutput.trim();
+                        }
+                        return `[^${this.getFootnoteKey(node)}]: ${childrenOutput.trim()}\n\n`;
+                    }
+                    return `> **Note:** ${childrenOutput.trim()}\n\n`;
                 }
+                case 'embed': {
+                    // Markdown has no native embed syntax. When fallbackToHtml.embeds is on (our
+                    // save default), emit the exact single-line div MarkdownParser recognises on
+                    // reimport; otherwise degrade to a plain link.
+                    const meta = node.metadata;
+                    const id = meta?.videoId || '';
+                    if (this.resolvedFallbackToHtml.embeds) {
+                        const width = meta?.width ? ` data-width="${(0, sanitize_js_1.escapeHtml)(meta.width)}"` : '';
+                        const align = meta?.align ? ` data-align="${(0, sanitize_js_1.escapeHtml)(meta.align)}"` : '';
+                        return `\n<div data-youtube-video="${(0, sanitize_js_1.escapeHtml)(id)}"${width}${align}></div>\n\n`;
+                    }
+                    const url = meta?.url || (id ? `https://youtu.be/${id}` : '');
+                    return url ? `[YouTube](${(0, sanitize_js_1.sanitizeMarkdownUrl)(url)})\n\n` : '';
+                }
+                case 'admonition': {
+                    const meta = node.metadata;
+                    // `admonitionType` is a closed union in types.ts and both parsers already
+                    // allowlist on import, so enforcing it here is a no-op for any conforming
+                    // AST - it closes the gap for a programmatically-built one, where the type is
+                    // interpolated straight into `:::TYPE` / `::: {.TYPE}` / `[!TYPE]`.
+                    const rawType = String(meta?.admonitionType || 'note').toLowerCase();
+                    const type = MD_ADMONITION_TYPES.has(rawType) ? rawType : 'note';
+                    const label = type.toUpperCase();
+                    // A newline in the title would close the `**...**` and, in the fenced-div
+                    // branches, could emit a stray `:::` line. `title` is never parser-set, so
+                    // there is no round-trip to preserve and escaping is free.
+                    const title = meta?.title ? (0, sanitize_js_1.markdownEscapeText)(foldLines(meta.title)) : '';
+                    const body = childrenOutput.trim();
+                    switch (this.resolvedDialect.admonitions) {
+                        case 'gitlab':
+                            // GLFM fenced-div: no dedicated title syntax, so a custom title (if
+                            // any) is folded into the body as a bold first line.
+                            return `:::${type}\n${title ? `**${title}**\n\n` : ''}${body}\n:::\n\n`;
+                        case 'pandoc':
+                            // Pandoc's own fenced-div-with-class syntax; same title handling as gitlab.
+                            return `::: {.${type}}\n${title ? `**${title}**\n\n` : ''}${body}\n:::\n\n`;
+                        case 'none': {
+                            // Degrade to a plain bold-labeled blockquote, no special marker.
+                            const quotedLines = body.split('\n').map(l => l.length > 0 ? `> ${l}` : '>').join('\n');
+                            const heading = title || label.charAt(0) + label.slice(1).toLowerCase();
+                            return `> **${heading}:**\n${quotedLines}\n\n`;
+                        }
+                        case 'github':
+                        default: {
+                            // Canonical GitHub blockquote form. No dedicated title syntax either
+                            // (matches this library's historical output).
+                            const quotedLines = body.split('\n').map(l => l.length > 0 ? `> ${l}` : '>').join('\n');
+                            return `> [!${label}]\n${quotedLines}\n\n`;
+                        }
+                    }
+                }
+                case 'definitionList':
+                    if (!this.resolvedDialect.definitionLists)
+                        return `${childrenOutput}\n`;
+                    return `${childrenOutput}\n`;
+                case 'definitionTerm':
+                    if (!this.resolvedDialect.definitionLists)
+                        return `**${childrenOutput}**\n\n`;
+                    return `${childrenOutput}\n`;
+                case 'definitionDescription':
+                    if (!this.resolvedDialect.definitionLists)
+                        return `${childrenOutput}\n\n`;
+                    return `: ${childrenOutput}\n`;
                 default:
                     return childrenOutput;
             }
@@ -253,8 +574,24 @@ class MarkdownGenerator extends BaseGenerator_js_1.BaseGenerator {
             }
             output += notesMd;
         }
+        if (this.collectedAbbreviations.size > 0) {
+            output += '\n\n';
+            for (const [abbr, title] of this.collectedAbbreviations) {
+                output += `*[${(0, sanitize_js_1.markdownEscapeText)(String(abbr).replace(/[[\]\r\n]+/g, ''))}]: ${(0, sanitize_js_1.markdownEscapeText)(foldLines(title))}\n`;
+            }
+        }
+        // Only a run of literal "\n" at either end is ever a generator artifact here: block
+        // separators, the notes/abbreviations sections, the unconditional '\n\n' before
+        // hoistedContent (added even when hoistedContent is empty), and renderMarkdownTable's
+        // HTML-fallback branches, which unconditionally wrap in a leading+trailing '\n' as
+        // separators from whatever precedes/follows (in practice this rarely surfaces at the very
+        // start of `output` today since frontmatter's own "---" almost always precedes real
+        // content first - see the type doc on `ast.metadata` - but the strip is correct regardless
+        // of what precedes it). Nothing else at either end is a generator artifact: not leading
+        // whitespace, and not any other kind of trailing whitespace, both of which would be real
+        // document content. See the identical reasoning in TextGenerator.generate().
         return {
-            value: (output + '\n\n' + this.hoistedContent.join('\n\n')).trim(),
+            value: (output + '\n\n' + this.hoistedContent.join('\n\n')).replace(/^\n+|\n+$/g, ''),
             messages: this.messages
         };
     }
@@ -263,6 +600,10 @@ class MarkdownGenerator extends BaseGenerator_js_1.BaseGenerator {
      * Overridden to provide AST optimization (merging adjacent text nodes).
      */
     async processNodeRecursive(node, processor) {
+        // Mirrors the check in BaseGenerator.processNodeRecursive. This override replaces that
+        // method entirely, so without repeating the check here the signal would be silently
+        // inert for this generator - which is exactly how it was missed.
+        (0, errorUtils_js_1.checkAbortSignal)(this.config.abortSignal);
         // Allow user to completely override rendering or skip via onNode
         const override = await this.handleOnNode(node);
         if (override === false) {
@@ -279,9 +620,16 @@ class MarkdownGenerator extends BaseGenerator_js_1.BaseGenerator {
                 childrenOutput += await this.processNodeRecursive(child, processor);
             }
         }
+        // When the dialect has no footnote syntax, a footnote/endnote is inlined right at its
+        // reference point instead (see below) - so it must not also be collected into the
+        // end-of-document "### Notes" section, or its content would be duplicated.
+        const isInlinedFootnote = (note) => {
+            const meta = note.metadata;
+            return (meta?.noteType === 'footnote' || meta?.noteType === 'endnote') && !this.resolvedDialect.footnotes;
+        };
         if (node.notes && node.notes.length > 0) {
             if (node.type !== 'slide') {
-                this.collectedNotes.push(...node.notes);
+                this.collectedNotes.push(...node.notes.filter(note => !isInlinedFootnote(note)));
             }
         }
         let result = await processor(node, childrenOutput);
@@ -290,6 +638,27 @@ class MarkdownGenerator extends BaseGenerator_js_1.BaseGenerator {
                 result += await this.processNodeRecursive(note, processor);
             }
         }
+        else if (node.notes && node.notes.length > 0) {
+            for (const note of node.notes) {
+                const meta = note.metadata;
+                if (meta?.noteType !== 'footnote' && meta?.noteType !== 'endnote')
+                    continue;
+                if (isInlinedFootnote(note)) {
+                    // Markdown-specific degrade (not RTF/plain-text's "drop the marker, just
+                    // append at the end" convention): inline the note's rendered body as a
+                    // parenthetical right where it's referenced, since Markdown readers benefit
+                    // from an inline association those simpler formats don't need in the same way.
+                    const body = await this.processNodeRecursive(note, processor);
+                    result += ` (Note: ${body})`;
+                }
+                else {
+                    // Emit the [^id] reference marker at the point of reference. Without this,
+                    // a footnote/endnote would only ever show up in the collected ### Notes
+                    // section at the end, with no indication of where it was originally cited.
+                    result += `[^${this.getFootnoteKey(note)}]`;
+                }
+            }
+        }
         return result;
     }
     /**
@@ -337,13 +706,19 @@ class MarkdownGenerator extends BaseGenerator_js_1.BaseGenerator {
     async renderMarkdownTable(node, processor) {
         if (!node.children || node.children.length === 0)
             return '';
+        // A dialect that has no native table syntax at all (e.g. strict CommonMark) always
+        // renders as HTML, regardless of complexity - this is a separate axis from the
+        // nested/merged-cell HTML fallback below, which only applies to otherwise-native tables.
+        if (this.resolvedDialect.tables === 'html') {
+            return '\n' + await this.renderTableAsHtml(node) + '\n';
+        }
         // If table is complex, nested, or uses merges, fallback to HTML for high fidelity if allowed
         const isComplex = this.hasNestedTable(node) || this.hasColspanOrRowspan(node);
-        if (this.config.mdConfig.fallbackToHtml && isComplex) {
+        if (this.resolvedFallbackToHtml.tables && isComplex) {
             return '\n' + await this.renderTableAsHtml(node) + '\n';
         }
         // Handle nested tables in pure Markdown by hoisting them out
-        if (this.isInsideTable && !this.config.mdConfig.fallbackToHtml) {
+        if (this.isInsideTable && !this.resolvedFallbackToHtml.tables) {
             const wasInside = this.isInsideTable;
             this.isInsideTable = false; // Reset to allow rendering the hoisted table correctly
             const hoistedId = this.hoistedContent.length + 1;
@@ -384,7 +759,7 @@ class MarkdownGenerator extends BaseGenerator_js_1.BaseGenerator {
                     // Process cell content
                     let cellContent = await this.processNodeRecursive(cellNode, processor);
                     // Use <br> fallback only if allowed, otherwise space
-                    const br = this.config.mdConfig.fallbackToHtml ? '<br>' : ' ';
+                    const br = this.resolvedFallbackToHtml.cellLineBreaks ? '<br>' : ' ';
                     cellContent = cellContent.trim().replace(/\n+/g, br).replace(/\|/g, '\\|');
                     rowCells.push(cellContent);
                     // Handle colspan by adding empty cells
@@ -460,7 +835,11 @@ class MarkdownGenerator extends BaseGenerator_js_1.BaseGenerator {
                     rows += await this.renderTableAsHtml(row, await this.handleOnNode(row));
                 }
             }
-            return `<table>\n${rows}</table>\n`;
+            // Carry table-layout alignment through the HTML fallback so it isn't lost
+            // just because the table also needed HTML for merged cells.
+            const tableMeta = node.metadata;
+            const alignAttr = tableMeta?.align ? ` data-align="${(0, sanitize_js_1.escapeHtml)(tableMeta.align)}"` : '';
+            return `<table${alignAttr}>\n${rows}</table>\n`;
         }
         else if (node.type === 'row') {
             let cells = '';
@@ -482,7 +861,9 @@ class MarkdownGenerator extends BaseGenerator_js_1.BaseGenerator {
                     content += await this.processNodeRecursive(child, async (n, co) => {
                         switch (n.type) {
                             case 'text': {
-                                let text = n.text || '';
+                                // Inside HTML table cells, entity-encode angle brackets so cell
+                                // text can't inject a raw tag (e.g. </td><script>).
+                                let text = (0, sanitize_js_1.markdownEscapeText)(n.text || '');
                                 if (n.formatting?.bold)
                                     text = `<b>${text}</b>`;
                                 if (n.formatting?.italic)
@@ -497,7 +878,7 @@ class MarkdownGenerator extends BaseGenerator_js_1.BaseGenerator {
                             }
                             case 'paragraph': return `<p>${co}</p>`;
                             case 'heading': {
-                                const level = n.metadata?.level || 1;
+                                const level = Math.min(Math.max(Number(n.metadata?.level) || 1, 1), 6);
                                 return `<h${level}>${co}</h${level}>`;
                             }
                             case 'table': return await this.renderTableAsHtml(n);