officeparser 7.7.0 → 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
 
 ---
@@ -783,6 +783,7 @@ idempotent and `.md → AST → HTML → AST → .md` survives unchanged.
 | 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. |
 
@@ -988,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) |

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

@@ -527,8 +527,11 @@ class HtmlGenerator extends BaseGenerator_js_1.BaseGenerator {
                 // 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
@@ -1145,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
@@ -1157,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

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.

package/dist/generators/MarkdownGenerator.js

@@ -160,10 +160,19 @@ class MarkdownGenerator extends BaseGenerator_js_1.BaseGenerator {
     collectedAbbreviations = new Map();
     resolvedDialect;
     resolvedFallbackToHtml;
+    resolvedEmbeds;
     constructor(ast, config) {
         super('md', ast, config);
         this.resolvedDialect = resolveDialect(this.config.mdConfig.dialect);
         this.resolvedFallbackToHtml = resolveFallbackToHtml(this.config.mdConfig.fallbackToHtml);
+        // `dialect.embeds` is the authority for embed form. It lives in a different config object
+        // than the deprecated `fallbackToHtml.embeds` boolean, and an explicit boolean `false` must
+        // still win over the preset default, so it is resolved here rather than in `resolveDialect`:
+        // an embeds value set on the dialect OBJECT wins; otherwise the boolean maps (`true`/unset ->
+        // `'html'`, `false` -> `'link'`); otherwise the default `'html'`.
+        const dialectCfg = this.config.mdConfig.dialect;
+        const explicitEmbeds = (dialectCfg && typeof dialectCfg === 'object') ? dialectCfg.embeds : undefined;
+        this.resolvedEmbeds = explicitEmbeds ?? (this.resolvedFallbackToHtml.embeds ? 'html' : 'link');
     }
     /**
      * Renders anchor tags if HTML fallback is allowed.
@@ -603,32 +612,67 @@ class MarkdownGenerator extends BaseGenerator_js_1.BaseGenerator {
                     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.
+                    // Markdown has no native embed syntax. `this.resolvedEmbeds` (from
+                    // `dialect.embeds`, honoring the deprecated `fallbackToHtml.embeds` boolean)
+                    // selects the form: 'html' (the single-line block this library has always
+                    // emitted and re-recognises), 'directive' (a remark-directive leaf), 'link'
+                    // (a plain link), 'thumbnail' (YouTube-only clickable preview).
                     const meta = node.metadata;
+                    const mode = this.resolvedEmbeds;
+                    // A directive label sits inside `::name[...]`; strip the `[]`/newline chars that
+                    // would break out of it. An attribute value sits inside `{...}`; percent-encode
+                    // the space/brace chars that would break out (widths/aligns/ids never contain
+                    // them, but a src can).
+                    const dirLabel = (meta?.label || '').replace(/[[\]\r\n]+/g, ' ').trim();
+                    const dirUrl = (u) => (0, sanitize_js_1.sanitizeMarkdownUrl)(u).replace(/[{}\s]/g, c => '%' + c.charCodeAt(0).toString(16).toUpperCase().padStart(2, '0'));
+                    const attrList = (pairs) => {
+                        const kv = pairs.filter(([, v]) => v !== undefined && v !== '').map(([k, v]) => `${k}=${v}`);
+                        return kv.length ? `{${kv.join(' ')}}` : '';
+                    };
                     if (meta?.embedType === 'iframe') {
-                        // sanitizeUrl scheme-checks and HTML-escapes the src (hostile schemes drop
-                        // the node). The single-line <iframe> is what MarkdownParser recognises on
-                        // reimport, gated there on preserveIframes.
-                        const safe = (0, sanitize_js_1.sanitizeUrl)(meta?.url || '');
-                        if (!safe)
-                            return '';
-                        if (this.resolvedFallbackToHtml.embeds) {
+                        const rawUrl = meta?.url || '';
+                        if (mode === 'directive') {
+                            const src = dirUrl(rawUrl);
+                            if (!src)
+                                return '';
+                            const lbl = dirLabel ? `[${dirLabel}]` : '';
+                            return `::embed${lbl}${attrList([['src', src], ['width', meta?.width], ['height', meta?.height], ['align', meta?.align]])}\n\n`;
+                        }
+                        if (mode === 'html') {
+                            // sanitizeUrl scheme-checks and HTML-escapes the src (hostile schemes drop
+                            // the node). The single-line <iframe> is what MarkdownParser recognises on
+                            // reimport, gated there on preserveIframes.
+                            const safe = (0, sanitize_js_1.sanitizeUrl)(rawUrl);
+                            if (!safe)
+                                return '';
                             const w = meta?.width ? ` width="${(0, sanitize_js_1.escapeHtml)(meta.width)}"` : '';
                             const h = meta?.height ? ` height="${(0, sanitize_js_1.escapeHtml)(meta.height)}"` : '';
                             return `\n<iframe src="${safe}"${w}${h}></iframe>\n\n`;
                         }
-                        return `[Embed](${(0, sanitize_js_1.sanitizeMarkdownUrl)(meta?.url || '')})\n\n`;
+                        // 'link' and 'thumbnail' (thumbnail is YouTube-only, so a generic iframe
+                        // degrades to a link) both emit a plain link.
+                        const safe = (0, sanitize_js_1.sanitizeMarkdownUrl)(rawUrl);
+                        return safe ? `[${meta?.label || 'Embed'}](${safe})\n\n` : '';
                     }
                     const id = meta?.videoId || '';
-                    if (this.resolvedFallbackToHtml.embeds) {
+                    if (mode === 'directive') {
+                        const lbl = dirLabel ? `[${dirLabel}]` : '';
+                        return `::youtube${lbl}${attrList([['id', id], ['width', meta?.width], ['align', meta?.align]])}\n\n`;
+                    }
+                    if (mode === 'html') {
                         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 lbl = meta?.label ? ` data-embed-label="${(0, sanitize_js_1.escapeHtml)(meta.label)}"` : '';
+                        return `\n<div data-youtube-video="${(0, sanitize_js_1.escapeHtml)(id)}"${width}${align}${lbl}></div>\n\n`;
+                    }
+                    if (mode === 'thumbnail' && id) {
+                        const watch = (0, sanitize_js_1.sanitizeMarkdownUrl)(`https://www.youtube.com/watch?v=${id}`);
+                        const thumb = (0, sanitize_js_1.sanitizeMarkdownUrl)(`https://img.youtube.com/vi/${id}/hqdefault.jpg`);
+                        return `[![${meta?.label || 'YouTube'}](${thumb})](${watch})\n\n`;
                     }
+                    // 'link' (and 'thumbnail' with no id): a plain link.
                     const url = meta?.url || (id ? `https://youtu.be/${id}` : '');
-                    return url ? `[YouTube](${(0, sanitize_js_1.sanitizeMarkdownUrl)(url)})\n\n` : '';
+                    return url ? `[${meta?.label || 'YouTube'}](${(0, sanitize_js_1.sanitizeMarkdownUrl)(url)})\n\n` : '';
                 }
                 case 'admonition': {
                     const meta = node.metadata;

package/dist/officeparser.browser.d.ts

@@ -415,6 +415,18 @@ export interface HtmlParserConfig {
 	 * Defaults to false.
 	 */
 	preserveIframes?: boolean | string[];
+	/**
+	 * Import ambiguous "folk" embed forms in Markdown as embeds: a standalone Obsidian-style image
+	 * whose URL is a YouTube link (`![](https://youtube.com/watch?v=ID)`), and the clickable
+	 * thumbnail-link (`[![alt](https://img.youtube.com/vi/ID/…)](watch-url)`). Both become a
+	 * `embedType: 'youtube'` embed (rendered from the validated id, so it is safe). Off by default:
+	 * auto-upgrading an image/link to an embed is a heuristic that could mangle a genuinely-intended
+	 * image link, so a consumer opts in. The unambiguous forms (`<div data-youtube-video>`, a bare
+	 * YouTube `<iframe>`, the `::youtube` directive) are always recognized, independent of this flag.
+	 *
+	 * Defaults to false.
+	 */
+	embedFolkForms?: boolean;
 }
 /**
  * Maps an input format string to its corresponding format-specific parser configuration, mirroring
@@ -883,6 +895,15 @@ export interface HtmlGeneratorConfig {
 	 * `HtmlParser` reads every shape this emits, so output stays self-round-trippable.
 	 */
 	sourceAttributes?: boolean;
+	/**
+	 * Emit a generic (non-YouTube) iframe embed as a gated placeholder,
+	 * `<div data-embed-gated data-embed-src="…" …>`, instead of a live `<iframe>`. The gated shape
+	 * never auto-loads its src: an editor renders a click-to-load placeholder from it, and
+	 * `HtmlParser` reads it back to the same `embed` node. The src is scheme-checked (`sanitizeUrl`)
+	 * on emit. Off by default; the default output (a live `<iframe>`) is unchanged. YouTube embeds
+	 * are unaffected (they already render from a validated id).
+	 */
+	gatedEmbeds?: boolean;
 }
 /**
  * Configuration options for PDF generation.
@@ -1056,6 +1077,20 @@ export type CitationSyntax = "at" | "none";
 export type WikilinkSyntax = "double-bracket" | "none";
 /** `{width=50%}` attribute lists (`'brace'`), or `'none'`. */
 export type AttributeListSyntax = "brace" | "none";
+/**
+ * How an `embed` node is written to Markdown:
+ * - `'html'` (default): the single-line `<div data-youtube-video="ID">` / `<iframe src=...>` block
+ *   this library has always emitted. Round-trips through officeParser, but renders as an invisible
+ *   empty box on GitHub.
+ * - `'directive'`: a remark-directive leaf, `::youtube[Label]{id=... width=... align=...}` /
+ *   `::embed[Label]{src=... width=... height=... align=...}`. Round-trips within an editor that
+ *   understands it; renders verbatim (not just the label) on GitHub, so it is an editor format, not
+ *   a GitHub-interop one.
+ * - `'link'`: a plain `[YouTube](url)` / `[Embed](url)`.
+ * - `'thumbnail'`: a YouTube-only clickable thumbnail `[![Label](.../vi/ID/hqdefault.jpg)](watch)`,
+ *   the best GitHub degrade; a non-YouTube embed falls back to `'link'`.
+ */
+export type EmbedSyntax = "html" | "directive" | "link" | "thumbnail";
 /**
  * @deprecated Legacy flavor names for `MarkdownDialectConfig.admonitions`. Use the syntax names
  * instead: `'github'` -> `'blockquote'`, `'gitlab'` -> `'fence'`, `'pandoc'` -> `'fence-attribute'`.
@@ -1142,6 +1177,13 @@ export interface MarkdownDialectConfig {
 	/** Table syntax: native GFM pipe tables, or forced HTML `<table>` (required for strict
 	 *  CommonMark, which has no table syntax of its own). */
 	tables?: "native" | "html";
+	/**
+	 * How an `embed` node is written to Markdown (`'html'` | `'directive'` | `'link'` |
+	 * `'thumbnail'`; see `EmbedSyntax`). This is the authority for embed form. When omitted, the
+	 * deprecated `fallbackToHtml.embeds` boolean is honored (`true`/unset maps to `'html'`, `false`
+	 * to `'link'`), then the default `'html'`.
+	 */
+	embeds?: EmbedSyntax;
 }
 /**
  * Granular control over when the Markdown generator falls back to raw HTML tags for features
@@ -1158,7 +1200,12 @@ export interface FallbackToHtmlConfig {
 	anchors?: boolean;
 	/** Nested-table and merged-cell (colspan/rowspan) HTML `<table>` fallback. */
 	tables?: boolean;
-	/** YouTube embed `<div data-youtube-video>` vs. a plain link. */
+	/**
+	 * YouTube embed `<div data-youtube-video>` vs. a plain link.
+	 * @deprecated Use `mdConfig.dialect.embeds` (`EmbedSyntax`) instead, which also selects the
+	 * `'directive'` and `'thumbnail'` forms. When `dialect.embeds` is unset this boolean is still
+	 * honored (`true` maps to `'html'`, `false` to `'link'`); it will be removed in the next major.
+	 */
 	embeds?: boolean;
 	/** Multi-line table cell content joined with `<br>` instead of a space. */
 	cellLineBreaks?: boolean;
@@ -1778,10 +1825,13 @@ export interface EmbedMetadata {
 	url?: string;
 	/** Display width, as a CSS length or percentage. */
 	width?: string;
-	/** Display height, as a CSS length or percentage (generic iframes). */
+	/** Display height, as a CSS length or percentage. */
 	height?: string;
 	/** Layout alignment of the embed. */
 	align?: "left" | "center" | "right";
+	/** Human-readable label for the embed (e.g. the `[Label]` of a `::youtube[Label]{...}` leaf
+	 *  directive, or a gated embed's caption). Purely descriptive; never a trust or render input. */
+	label?: string;
 }
 /**
  * Metadata for an admonition/alert node (e.g. GitHub's `> [!NOTE]` or GLFM's `:::note`).