officeparser 7.6.2 → 7.8.0

package/README.md

@@ -758,7 +758,7 @@ Definition List Node (type: 'definitionList')
 ```
 
 - `admonition` round-trips through both Markdown (`> [!NOTE]` / `:::note ... :::`) and HTML (`<div class="admonition admonition-note" data-type="note">`)
-- `embed` currently models YouTube videos; HTML round-trips via `<div data-youtube-video="ID">`, Markdown falls back to a raw HTML block or a plain link
+- `embed` models YouTube videos and generic iframes. Markdown form is selected by `mdConfig.dialect.embeds`: `'html'` (default; the `<div data-youtube-video>` / `<iframe>` block), `'directive'` (a `::youtube[…]{…}` / `::embed[…]{…}` leaf directive), `'link'`, or `'thumbnail'` (YouTube-only clickable preview). A generic iframe is captured only under `htmlParserConfig.preserveIframes` (the trust input) and can be emitted as an inert click-to-load placeholder via `htmlConfig.gatedEmbeds`. The `'directive'` form is an editor round-trip format, not GitHub-rendered
 - Abbreviations (`*[HTML]: Hypertext Markup Language`) are stored as `TextMetadata.abbreviationTitle` on the abbreviated text node rather than as a separate node type
 
 ---
@@ -780,7 +780,10 @@ idempotent and `.md → AST → HTML → AST → .md` survives unchanged.
 | Attribute lists | `![alt](img.png){width=50% .centered}` | `ImageMetadata.width` / `.align`, `TableMetadata.align` |
 | Citations | `[@smith2024]` | `TextMetadata.citationKey` |
 | Wikilinks | `[[Page]]` / `[[Page\|Alias]]` | `TextMetadata.wikilink`, `.link`, `.linkType` |
+| Highlight | `==text==` | `TextMetadata.backgroundColor` |
+| Link/image titles | `[text](url "Title")` / `![alt](img.png "Title")` | `TextMetadata.title` / `ImageMetadata.title` |
 | Inline/block math | `$E=mc^2$` / `` $$...$$ `` | `type: 'code'`, `CodeMetadata.math` (`'inline' \| 'block'`) |
+| Embeds | `::youtube[Label]{id=… width=… align=…}` / `::embed[Label]{src=… …}` (leaf directive; see `mdConfig.dialect.embeds`) | `type: 'embed'`, `EmbedMetadata` |
 | Frontmatter arrays | `tags: [a, b]` or `tags: ["a","b"]` | Real array in `metadata.customProperties`/`nativeProperties` |
 | MDX components (import-only) | `<Component prop="x">...</Component>` | Stripped; inner Markdown is kept. Never generated back. |
 
@@ -795,7 +798,8 @@ save→reload cycle:
 | HTML attribute | AST field | Notes |
 |---|---|---|
 | `data-width` / `data-align` / inline `style="width:…"` on `<img>` | `ImageMetadata.width` / `.align` | |
-| `data-align` on `<table>` | `TableMetadata.align` | |
+| `data-align` on `<table>` | `TableMetadata.align` | Emitted/parsed as per-column GFM markers (`:---`, `:---:`, `---:`); alignment rides `CellMetadata.align` |
+| `title` on `<a>` / `<img>` | `TextMetadata.title` / `ImageMetadata.title` | Survives both directions (`[text](url "Title")` in Markdown) |
 | `colspan` / `rowspan` on `<td>`/`<th>` | `CellMetadata.colSpan` / `.rowSpan` | Previously dropped on HTML import — merged cells now survive a save→reload cycle |
 | `<div data-youtube-video="ID">` / `<iframe src="...youtube.com...">` | `type: 'embed'` | |
 | `<ul data-type="taskList">` / `<li data-checked>` | `ListMetadata.isTask` / `.checked` | |
@@ -985,7 +989,7 @@ Pass as the second argument to `parseOffice(file, config)`.
 | `fileType` | `SupportedFileType \| null` | `null` | **Required for text-based binary data** (`'md'`, `'html'`, `'csv'`) as these lack magic bytes. |
 | `csvDelimiter` | `string` | `','` | Input delimiter when parsing CSV files |
 | `decompressionLimits` | `DecompressionLimits` | `{ maxUncompressedBytes: 512MB, maxZipEntries: 10000, maxTableCells: 1000000 }` | **New**: Limits applied during ZIP extraction (and ODF cell expansion) to protect against excessive memory and resource usage |
-| `htmlParserConfig` | `HtmlParserConfig` | `{}` | HTML/XHTML/EPUB parsing options. `preserveAttributes` (`boolean`, default `false`): keep generic source attributes no typed field consumed on `node.htmlAttributes`. `preserveIframes` (`boolean \| string[]`, default `false`): preserve non-YouTube `<iframe>` embeds (otherwise dropped) as `embed` nodes — `true` for any, or a hostname allowlist; the src is scheme-checked on generation |
+| `htmlParserConfig` | `HtmlParserConfig` | `{}` | HTML/XHTML/EPUB parsing options. `preserveAttributes` (`boolean`, default `false`): keep generic source attributes no typed field consumed on `node.htmlAttributes`. `preserveIframes` (`boolean \| string[]`, default `false`): preserve non-YouTube `<iframe>` embeds (otherwise dropped) as `embed` nodes — `true` for any, or a hostname allowlist; the src is scheme-checked on generation. `embedFolkForms` (`boolean`, default `false`): opt in to importing ambiguous folk embed forms (Obsidian `![](youtube-url)`, thumbnail-link) as YouTube embeds |
 | `pdfWorkerSrc` | `string` | CDN (jsDelivr) | Path/URL to `pdf.worker.min.mjs` (required in browser) |
 | `onWarning` | `(issue: OfficeIssue) => void` | — | Callback for non-fatal parsing issues |
 | `abortSignal` | `AbortSignal \| null` | `null` | Optional signal to cancel parsing (rejects with AbortError) |
@@ -1146,7 +1150,8 @@ Pass as `mdConfig` inside `GeneratorConfig`.
 
 | Option | Type | Default | Description |
 |--------|------|---------|-------------|
-| `fallbackToHtml` | `boolean \| FallbackToHtmlConfig` | `true` | Use HTML tags for features Markdown cannot represent (underlines, merged table cells, embeds, etc.). Pass an object for per-feature control. `inlineFormatting` (default `false`, opt-in even when the boolean is `true`) additionally round-trips inline color/highlight/font-size as `<span style="...">` runs. |
+| `fallbackToHtml` | `boolean \| FallbackToHtmlConfig` | `true` | Use HTML tags for features Markdown cannot represent (underlines, merged table cells, embeds, etc.). Pass an object for per-feature control. `cellLineBreaks`/`itemLineBreaks` (default on) join multi-line table-cell / multi-paragraph list-item content with `<br>` instead of a space. `inlineFormatting` (default `false`, opt-in even when the boolean is `true`) additionally round-trips inline color/highlight/font-size as `<span style="...">` runs. |
+| `dialect` | `MarkdownDialectPreset \| MarkdownDialectConfig` | `'extended'` | Which native syntax to emit for constructs that differ across targets (GitHub/GitLab/Obsidian/Pandoc/CommonMark). Each capability is typed by the syntax it selects (e.g. `strikethrough: 'tilde'`, `highlight: 'equals'`, `admonitions: 'blockquote'`), with `'none'` to turn it off. See [Markdown Dialect Support](#markdown-dialect-support). The old `boolean` toggles and admonition flavour names (`'github'`/`'gitlab'`/`'pandoc'`) still work but are deprecated. |
 
 ### PdfGeneratorConfig
 

package/dist/defaults.js

@@ -41,6 +41,7 @@ const DEFAULT_OCR_CONFIG = {
 const DEFAULT_HTML_PARSER_CONFIG = {
     preserveAttributes: false,
     preserveIframes: false,
+    embedFolkForms: false,
 };
 /**
  * Default configuration for the OfficeParser.
@@ -89,6 +90,7 @@ const DEFAULT_HTML_GENERATOR_CONFIG = {
         bodyEnd: '',
     },
     sourceAttributes: false,
+    gatedEmbeds: false,
 };
 /**
  * Default configuration for PDF generation.

package/dist/generators/HtmlGenerator.js

@@ -446,7 +446,11 @@ class HtmlGenerator extends BaseGenerator_js_1.BaseGenerator {
      */
     async processNodeArray(nodes) {
         let html = '';
-        // Stack to track active lists: { indentation, type, isTask }
+        // Stack to track active lists. `liClose` is the currently-open item's deferred closing
+        // suffix (`</li>`, or `</div></li>` for a task item): a list item is rendered WITHOUT its
+        // close so a deeper list can land inside it (spec-valid `<li>a<ul>...</ul></li>` rather
+        // than the invalid `<li>a</li><ul>...</ul>` sibling shape). The close is emitted when a
+        // same-level sibling arrives, when the level is popped, or at the end.
         const listStack = [];
         const openListTag = (type, isTask) => {
             if (isTask)
@@ -457,7 +461,7 @@ class HtmlGenerator extends BaseGenerator_js_1.BaseGenerator {
         const closeListsToLevel = (level) => {
             while (listStack.length > 0 && listStack[listStack.length - 1].indentation > level) {
                 const list = listStack.pop();
-                html += closeListTag(list.type) + '\n\n';
+                html += list.liClose + closeListTag(list.type) + '\n\n';
             }
         };
         for (const node of nodes) {
@@ -492,27 +496,42 @@ class HtmlGenerator extends BaseGenerator_js_1.BaseGenerator {
                 closeListsToLevel(indentation);
                 // Handle current level
                 if (listStack.length > 0 && listStack[listStack.length - 1].indentation === indentation) {
-                    if (listStack[listStack.length - 1].type !== type || listStack[listStack.length - 1].isTask !== isTask) {
-                        // Type changed at same level
+                    const top = listStack[listStack.length - 1];
+                    if (top.type !== type || top.isTask !== isTask) {
+                        // Kind changed at the same level: close the open item and the old list,
+                        // then open the replacement list.
                         const last = listStack.pop();
-                        html += closeListTag(last.type) + '\n';
+                        html += last.liClose + closeListTag(last.type) + '\n';
                         html += openListTag(type, isTask) + '\n';
-                        listStack.push({ indentation, type, isTask });
+                        listStack.push({ indentation, type, isTask, liClose: '' });
+                    }
+                    else {
+                        // Sibling at the same level: close the previous item before this one opens.
+                        html += top.liClose;
                     }
                 }
                 else {
-                    // Start a new nested list
+                    // Deeper level (or the first list): open a nested list INSIDE the currently
+                    // open item, leaving the parent <li>'s close pending on its stack frame.
                     html += openListTag(type, isTask) + '\n';
-                    listStack.push({ indentation, type, isTask });
+                    listStack.push({ indentation, type, isTask, liClose: '' });
                 }
                 html += await this.processNodeRecursive(node, this.nodeProcessor.bind(this), override);
+                // Defer this item's close so a nested list can land inside it. A string override is
+                // a complete replacement item that already carries its own close, so add none.
+                listStack[listStack.length - 1].liClose = (typeof override === 'string')
+                    ? ''
+                    : (isTask ? '</div></li>' : '</li>');
             }
             else {
                 // Non-list node closes all active lists
                 closeListsToLevel(-1);
                 let result = await this.processNodeRecursive(node, this.nodeProcessor.bind(this), override);
-                // Add newlines for readability of the HTML source
-                if (!result.endsWith('\n\n')) {
+                // Add a blank line after BLOCK nodes for readable HTML source. Inline nodes (a
+                // paragraph's text/link runs) must concatenate with no separator: adding `\n\n`
+                // around an inline <a> put a blank line inside the <p>, which reparsed as a stray
+                // space before the following punctuation (`[video](url) .`).
+                if (node.type !== 'text' && !result.endsWith('\n\n')) {
                     if (result.endsWith('\n'))
                         result += '\n';
                     else
@@ -712,7 +731,8 @@ class HtmlGenerator extends BaseGenerator_js_1.BaseGenerator {
                     imgStyleParts.push('display: block', `margin-left: ${ml}`, `margin-right: ${mr}`);
                 }
                 const imgStyleAttr = imgStyleParts.length > 0 ? ` style="${imgStyleParts.join('; ')}"` : '';
-                const img = `<img src="${(0, sanitize_js_1.sanitizeImageUrl)(src)}" alt="${this.escape(node.text || meta?.altText || '')}"${className}${mappedAttrs}${imgDataAttrs}${imgStyleAttr}>`;
+                const imgTitle = meta?.title ? ` title="${this.escape(meta.title)}"` : '';
+                const img = `<img src="${(0, sanitize_js_1.sanitizeImageUrl)(src)}" alt="${this.escape(node.text || meta?.altText || '')}"${imgTitle}${className}${mappedAttrs}${imgDataAttrs}${imgStyleAttr}>`;
                 const content = this.config.includeFormatting ? `<div class="image-container">${img}<div class="caption">${this.escape(attachmentName || '')}</div></div>` : img;
                 return `${extraAnchors}<div${idAttr}>${content}</div>`;
             }
@@ -831,7 +851,12 @@ class HtmlGenerator extends BaseGenerator_js_1.BaseGenerator {
                 }
                 const lang = meta?.language ? ` class="language-${this.escape(meta.language)}"` : '';
                 const codeHtml = `<code${lang}>${this.escape(node.text || '')}</code>`;
-                if (node.text && node.text.includes('\n')) {
+                // A `code` node is always block-level (inline code is a monospace text run, emitted
+                // as <code> by formatText). Wrap in <pre> whenever it carries a language or spans
+                // multiple lines; only a bare single-line, language-less code node stays a <span>.
+                // Previously a single-line block (e.g. a one-line ```js) emitted <span><code>, which
+                // re-imports as inline code and which strict CodeBlock parsers (only <pre><code>) miss.
+                if (meta?.language || (node.text && node.text.includes('\n'))) {
                     return `${extraAnchors}<pre${idAttr}${className}${mappedAttrs}${styleAttr}>${codeHtml}</pre>`;
                 }
                 else {
@@ -839,16 +864,19 @@ class HtmlGenerator extends BaseGenerator_js_1.BaseGenerator {
                 }
             }
             case 'list': {
+                // The closing suffix (`</div></li>` for a task item, `</li>` otherwise) is emitted
+                // by processNodeArray's list stack, not here, so a nested list can be placed inside
+                // this item before it closes. See `listStack`/`liClose` there.
                 const meta = node.metadata;
                 if (meta?.isTask) {
                     const checkedAttr = ` data-checked="${meta.checked ? 'true' : 'false'}"`;
                     const checkedBool = meta.checked ? ' checked' : '';
-                    return `${extraAnchors}<li${checkedAttr}${idAttr}${className}${mappedAttrs}${styleAttr}><label><input type="checkbox"${checkedBool}><span></span></label><div>${childrenOutput}</div></li>`;
+                    return `${extraAnchors}<li${checkedAttr}${idAttr}${className}${mappedAttrs}${styleAttr}><label><input type="checkbox"${checkedBool}><span></span></label><div>${childrenOutput}`;
                 }
                 const value = (meta?.listType === 'ordered' && typeof meta.itemIndex === 'number')
                     ? ` value="${meta.itemIndex + 1}"`
                     : '';
-                return `${extraAnchors}<li${value}${idAttr}${className}${mappedAttrs}${styleAttr}>${childrenOutput}</li>`;
+                return `${extraAnchors}<li${value}${idAttr}${className}${mappedAttrs}${styleAttr}>${childrenOutput}`;
             }
             case 'table': {
                 // Smart Table Header Detection
@@ -1120,6 +1148,15 @@ class HtmlGenerator extends BaseGenerator_js_1.BaseGenerator {
                         return '';
                     const w = meta?.width ? ` width="${this.escape(meta.width)}"` : '';
                     const h = meta?.height ? ` height="${this.escape(meta.height)}"` : '';
+                    if (this.config.htmlConfig.gatedEmbeds) {
+                        // Inert, never-auto-loading placeholder: the editor renders click-to-load from
+                        // it, and HtmlParser reads it back to the same embed node. src already sanitized.
+                        const a = meta?.align ? ` data-embed-align="${this.escape(meta.align)}"` : '';
+                        const l = meta?.label ? ` data-embed-label="${this.escape(meta.label)}"` : '';
+                        const dw = meta?.width ? ` data-embed-width="${this.escape(meta.width)}"` : '';
+                        const dh = meta?.height ? ` data-embed-height="${this.escape(meta.height)}"` : '';
+                        return `${extraAnchors}<div data-embed-gated data-embed-src="${src}"${dw}${dh}${a}${l}${idAttr}${mappedAttrs}${styleAttr}></div>`;
+                    }
                     return `${extraAnchors}<iframe src="${src}"${w}${h}${idAttr}${mappedAttrs}${styleAttr}></iframe>`;
                 }
                 // Match the attribute-driven Youtube wrapper shape so a loaded embed re-hydrates
@@ -1132,7 +1169,11 @@ class HtmlGenerator extends BaseGenerator_js_1.BaseGenerator {
                 const iframe = id
                     ? `<iframe src="https://www.youtube.com/embed/${this.escape(id)}" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowfullscreen></iframe>`
                     : '';
-                return `${extraAnchors}<div data-youtube-video="${this.escape(id)}" data-width="${this.escape(width)}" data-align="${this.escape(align)}" class="youtube-embed"${idAttr}${mappedAttrs} style="width: ${(0, sanitize_js_1.sanitizeCssValue)(width)}; margin-left: ${ml}; margin-right: ${mr};">${iframe}</div>`;
+                // Carry the human label so it survives AST -> editor-HTML -> AST, at parity with the
+                // generic gated path's data-embed-label. Only emitted when a label exists (from a
+                // `::youtube[Label]` directive), so unlabeled youtube embeds are byte-identical.
+                const ytLabel = meta?.label ? ` data-embed-label="${this.escape(meta.label)}"` : '';
+                return `${extraAnchors}<div data-youtube-video="${this.escape(id)}" data-width="${this.escape(width)}" data-align="${this.escape(align)}"${ytLabel} class="youtube-embed"${idAttr}${mappedAttrs} style="width: ${(0, sanitize_js_1.sanitizeCssValue)(width)}; margin-left: ${ml}; margin-right: ${mr};">${iframe}</div>`;
             }
             case 'admonition': {
                 // Match the attribute-driven admonition wrapper so a loaded admonition
@@ -1166,6 +1207,11 @@ class HtmlGenerator extends BaseGenerator_js_1.BaseGenerator {
         let result = this.escape(text);
         const f = node.formatting;
         if (this.config.includeFormatting && f) {
+            // Inline code: a monospace run becomes `<code>`, not a `font-family: monospace` span, so
+            // an editor keying on <code> sees it and it re-imports as inline code (HtmlParser maps
+            // <code> back to a monospace run). Innermost, so bold/italic wrap it (`<b><code>…`).
+            if (f.font === 'monospace')
+                result = `<code>${result}</code>`;
             // Inside an `<hN>`, the heading's own styling is authoritative. A run that also carries
             // bold and a font size - the normal case for ODF, where a heading's paragraph style is
             // inherited by its runs - would wrap the text in `<b>` the heading already implies and,
@@ -1220,7 +1266,8 @@ class HtmlGenerator extends BaseGenerator_js_1.BaseGenerator {
         else if (meta?.link) {
             const isInternal = meta.linkType !== 'external';
             if (!this.config.ignoreInternalLinks || !isInternal) {
-                result = `<a href="${(0, sanitize_js_1.sanitizeUrl)(meta.link)}"${meta.linkType === 'external' ? ' target="_blank"' : ''}>${result}</a>`;
+                const linkTitle = meta.title ? ` title="${this.escape(meta.title)}"` : '';
+                result = `<a href="${(0, sanitize_js_1.sanitizeUrl)(meta.link)}"${linkTitle}${meta.linkType === 'external' ? ' target="_blank"' : ''}>${result}</a>`;
             }
         }
         if (meta?.abbreviationTitle) {
@@ -1250,6 +1297,12 @@ class HtmlGenerator extends BaseGenerator_js_1.BaseGenerator {
             const meta = node.metadata;
             if (meta.alignment)
                 pushSafe('text-align', meta.alignment);
+            // A table cell's column alignment (GFM `:---`/`:---:`/`---:`) lives on
+            // `CellMetadata.align`, not `alignment`. Emit it as `text-align` on the `<th>`/`<td>`
+            // so `HtmlParser` reads it back and the pipe-table markers survive AST -> HTML -> AST.
+            // An unaligned cell (no `align`) adds nothing, keeping its HTML byte-identical.
+            if (node.type === 'cell' && meta.align)
+                pushSafe('text-align', meta.align);
             if (meta.backgroundColor)
                 pushSafe('background-color', meta.backgroundColor);
             if (meta.verticalAlign)
@@ -1274,7 +1327,9 @@ class HtmlGenerator extends BaseGenerator_js_1.BaseGenerator {
                 pushSafe('background-color', f.backgroundColor);
             if (f.size && !options.skipFontSize)
                 pushSafe('font-size', f.size);
-            if (f.font) {
+            // A monospace run is emitted as <code> by formatText, so it must not also become a
+            // font-family style here (that was the old, non-semantic inline-code shape).
+            if (f.font && f.font !== 'monospace') {
                 const safeFont = (0, sanitize_js_1.sanitizeCssValue)(f.font);
                 if (safeFont)
                     styles.push(`font-family: ${safeFont}, sans-serif`);

package/dist/generators/MarkdownGenerator.d.ts

@@ -47,6 +47,7 @@ export declare class MarkdownGenerator extends BaseGenerator<'md'> {
     private collectedAbbreviations;
     private resolvedDialect;
     private resolvedFallbackToHtml;
+    private resolvedEmbeds;
     constructor(ast: OfficeParserAST, config?: GeneratorConfig<'md'>);
     /**
      * Renders anchor tags if HTML fallback is allowed.