@jacobbubu/md-to-lark 1.5.0 → 1.6.0

package/README.md

@@ -174,6 +174,7 @@ Guardrails:
 - Single-file and recursive directory publish
 - Title derivation, title prefix, and single-H1 promotion
 - Local attachment and image detection with real upload
+- Programmatic image display width control through `imageSizeResolver`
 - Remote image download and standalone URL preparation
 - Mermaid `text-drawing` and `board` output paths
 - Opt-in single-dollar inline math parsing for LaTeX-heavy papers

package/dist/pipeline/hast-to-last.js

@@ -11,11 +11,14 @@ const BLOCK_CONTAINER_TAGS = new Set([
     'footer',
 ]);
 const DEFAULT_ALIGN = 'left';
-function createContext() {
+function createContext(options = {}) {
     return {
         blocks: {},
         blockCounter: 1,
         inlineCounter: 1,
+        imageSizeContext: options.imageSizeContext ?? {},
+        warnedImageSizeKeys: new Set(),
+        ...(options.imageSizeResolver ? { imageSizeResolver: options.imageSizeResolver } : {}),
     };
 }
 function nextBlockId(ctx) {
@@ -145,9 +148,74 @@ function createDividerBlock(ctx, parentId) {
     });
     return blockId;
 }
-function createImageBlock(ctx, parentId, sourceUrl) {
+function warnInvalidImageDisplaySize(ctx, key, message) {
+    if (ctx.warnedImageSizeKeys.has(key))
+        return;
+    ctx.warnedImageSizeKeys.add(key);
+    console.warn(`[md-to-lark] ${message}`);
+}
+function buildImageSizeResolverContext(ctx, image) {
+    const context = {};
+    if (ctx.imageSizeContext.inputPath) {
+        context.inputPath = ctx.imageSizeContext.inputPath;
+    }
+    if (ctx.imageSizeContext.resourceBaseDir) {
+        context.resourceBaseDir = ctx.imageSizeContext.resourceBaseDir;
+    }
+    if (image.alt) {
+        context.alt = image.alt;
+    }
+    if (image.title) {
+        context.title = image.title;
+    }
+    return context;
+}
+function toPositiveRoundedWidth(value) {
+    if (!Number.isFinite(value) || value <= 0)
+        return undefined;
+    return Math.max(1, Math.round(value));
+}
+function applyImageDisplaySize(ctx, image, block) {
+    if (!ctx.imageSizeResolver || !image.sourceUrl) {
+        return;
+    }
+    const size = ctx.imageSizeResolver(image.sourceUrl, buildImageSizeResolverContext(ctx, image));
+    if (!size) {
+        return;
+    }
+    const hasWidthRatio = typeof size.widthRatio === 'number';
+    if (hasWidthRatio) {
+        const ratio = size.widthRatio;
+        if (Number.isFinite(ratio) && ratio > 0 && ratio <= 1) {
+            const baseWidth = block.payload.width ??
+                createDefaultImagePayload(block.parentId ? ctx.blocks[block.parentId]?.type : undefined).width ??
+                0;
+            const width = toPositiveRoundedWidth(baseWidth * ratio);
+            if (width !== undefined) {
+                block.payload.width = width;
+            }
+            return;
+        }
+        warnInvalidImageDisplaySize(ctx, `widthRatio:${image.sourceUrl}:${String(size.widthRatio)}`, `Ignoring invalid image widthRatio for ${image.sourceUrl}: ${String(size.widthRatio)}. Expected 0 < widthRatio <= 1.`);
+    }
+    if (typeof size.widthPx === 'number') {
+        const width = toPositiveRoundedWidth(size.widthPx);
+        if (width !== undefined) {
+            block.payload.width = width;
+            return;
+        }
+        warnInvalidImageDisplaySize(ctx, `widthPx:${image.sourceUrl}:${String(size.widthPx)}`, `Ignoring invalid image widthPx for ${image.sourceUrl}: ${String(size.widthPx)}. Expected widthPx > 0.`);
+    }
+}
+function createImageBlock(ctx, parentId, sourceUrl, alt = null, title = null, linkHref = null) {
     const blockId = nextBlockId(ctx);
     const parentBlock = ctx.blocks[parentId];
+    const image = {
+        sourceUrl,
+        alt,
+        title,
+        linkHref,
+    };
     const blockBase = {
         id: blockId,
         type: 'image',
@@ -155,9 +223,23 @@ function createImageBlock(ctx, parentId, sourceUrl) {
         children: [],
         payload: createDefaultImagePayload(parentBlock?.type),
     };
+    const selectorAttrs = {};
     if (sourceUrl) {
-        blockBase.selector = { attrs: { sourceUrl } };
+        selectorAttrs.sourceUrl = sourceUrl;
+    }
+    if (alt) {
+        selectorAttrs.alt = alt;
+    }
+    if (title) {
+        selectorAttrs.title = title;
     }
+    if (linkHref) {
+        selectorAttrs.linkHref = linkHref;
+    }
+    if (Object.keys(selectorAttrs).length > 0) {
+        blockBase.selector = { attrs: selectorAttrs };
+    }
+    applyImageDisplaySize(ctx, image, blockBase);
     addBlock(ctx, blockBase);
     return blockId;
 }
@@ -358,14 +440,35 @@ function isWhitespaceTextNode(node) {
 function getMeaningfulChildren(nodes) {
     return nodes.filter((child) => !isWhitespaceTextNode(child));
 }
-function findStandaloneImageSrcInParagraph(paragraph) {
+function extractImageSourceFromElement(element) {
+    if (element.tagName === 'img') {
+        return {
+            sourceUrl: getStringProp(element, 'src'),
+            alt: getStringProp(element, 'alt'),
+            title: getStringProp(element, 'title'),
+            linkHref: null,
+        };
+    }
+    if (element.tagName !== 'a')
+        return null;
+    const href = getStringProp(element, 'href');
+    const meaningfulChildren = getMeaningfulChildren(getChildren(element));
+    if (meaningfulChildren.length !== 1)
+        return null;
+    const only = meaningfulChildren[0];
+    if (!only || !isElement(only))
+        return null;
+    const imageSource = extractImageSourceFromElement(only);
+    return imageSource ? { ...imageSource, linkHref: href } : null;
+}
+function findStandaloneImageInParagraph(paragraph) {
     const meaningfulChildren = getMeaningfulChildren(getChildren(paragraph));
     if (meaningfulChildren.length !== 1)
         return null;
     const only = meaningfulChildren[0];
-    if (!only || !isElement(only) || only.tagName !== 'img')
+    if (!only || !isElement(only))
         return null;
-    return getStringProp(only, 'src');
+    return extractImageSourceFromElement(only);
 }
 function parseHttpUrl(url) {
     try {
@@ -472,10 +575,11 @@ function findStandaloneRichItemInTableCell(cell) {
     }
     if (!only || !isElement(only))
         return null;
-    if (only.tagName === 'img') {
+    const imageSource = extractImageSourceFromElement(only);
+    if (imageSource) {
         return {
             kind: 'image',
-            sourceUrl: getStringProp(only, 'src'),
+            ...imageSource,
         };
     }
     if (only.tagName !== 'a')
@@ -667,7 +771,7 @@ function convertTable(ctx, table, parentId) {
             const cellBlock = ctx.blocks[cellId];
             const richItem = cell ? findStandaloneRichItemInTableCell(cell) : null;
             if (cellBlock?.type === 'table_cell' && richItem?.kind === 'image') {
-                const imageId = createImageBlock(ctx, cellId, richItem.sourceUrl);
+                const imageId = createImageBlock(ctx, cellId, richItem.sourceUrl, richItem.alt, richItem.title, richItem.linkHref);
                 cellBlock.children = [imageId];
                 cells.push(cellId);
                 continue;
@@ -733,6 +837,46 @@ function convertUnknownElement(ctx, element, parentId) {
         ]),
     ];
 }
+function hasNonWhitespaceInline(inlines) {
+    return inlines.some((inline) => toSearchText(inline).text.trim().length > 0);
+}
+function convertParagraph(ctx, paragraph, parentId) {
+    const standaloneImage = findStandaloneImageInParagraph(paragraph);
+    if (standaloneImage?.sourceUrl) {
+        return [
+            createImageBlock(ctx, parentId, standaloneImage.sourceUrl, standaloneImage.alt, standaloneImage.title, standaloneImage.linkHref),
+        ];
+    }
+    const standaloneIframe = findStandaloneIframePayloadInParagraph(paragraph);
+    if (standaloneIframe) {
+        return [createIframeBlock(ctx, parentId, standaloneIframe.url, standaloneIframe.iframeType)];
+    }
+    const ids = [];
+    let pendingInlineNodes = [];
+    const flushText = () => {
+        if (pendingInlineNodes.length === 0)
+            return;
+        const inlines = parseInlineNodes(ctx, pendingInlineNodes);
+        pendingInlineNodes = [];
+        if (!hasNonWhitespaceInline(inlines))
+            return;
+        ids.push(createTextualBlock(ctx, 'text', parentId, inlines));
+    };
+    for (const child of getChildren(paragraph)) {
+        const image = isElement(child) ? extractImageSourceFromElement(child) : null;
+        if (image?.sourceUrl) {
+            flushText();
+            ids.push(createImageBlock(ctx, parentId, image.sourceUrl, image.alt, image.title, image.linkHref));
+            continue;
+        }
+        pendingInlineNodes.push(child);
+    }
+    flushText();
+    if (ids.length > 0) {
+        return ids;
+    }
+    return [createTextualBlock(ctx, 'text', parentId, parseInlineNodes(ctx, getChildren(paragraph)))];
+}
 function convertBlock(ctx, node, parentId) {
     if (isWhitespaceTextNode(node)) {
         return [];
@@ -753,17 +897,8 @@ function convertBlock(ctx, node, parentId) {
         return [];
     }
     switch (node.tagName) {
-        case 'p': {
-            const standaloneImageSrc = findStandaloneImageSrcInParagraph(node);
-            if (standaloneImageSrc) {
-                return [createImageBlock(ctx, parentId, standaloneImageSrc)];
-            }
-            const standaloneIframe = findStandaloneIframePayloadInParagraph(node);
-            if (standaloneIframe) {
-                return [createIframeBlock(ctx, parentId, standaloneIframe.url, standaloneIframe.iframeType)];
-            }
-            return [createTextualBlock(ctx, 'text', parentId, parseInlineNodes(ctx, getChildren(node)))];
-        }
+        case 'p':
+            return convertParagraph(ctx, node, parentId);
         case 'h1':
         case 'h2':
         case 'h3':
@@ -789,7 +924,9 @@ function convertBlock(ctx, node, parentId) {
         case 'table':
             return convertTable(ctx, node, parentId);
         case 'img':
-            return [createImageBlock(ctx, parentId, getStringProp(node, 'src'))];
+            return [
+                createImageBlock(ctx, parentId, getStringProp(node, 'src'), getStringProp(node, 'alt'), getStringProp(node, 'title')),
+            ];
         case 'br':
             return [
                 createTextualBlock(ctx, 'text', parentId, [
@@ -902,7 +1039,7 @@ function deepCloneBlock(value) {
     return JSON.parse(JSON.stringify(value));
 }
 export function hastToLAST(hast, options) {
-    const ctx = createContext();
+    const ctx = createContext(options);
     const mode = options?.mode ?? 'fragment';
     const rootId = createTextualBlock(ctx, 'page', null, []);
     const root = ctx.blocks[rootId];

package/dist/publish/process-file.js

@@ -105,6 +105,15 @@ export async function processSingleMarkdownFile(params) {
     const last = hastToLAST(hast, {
         documentId: documentKey,
         mode: 'fragment',
+        ...(runtime.imageSizeResolver
+            ? {
+                imageSizeResolver: runtime.imageSizeResolver,
+                imageSizeContext: {
+                    inputPath: markdownPath,
+                    resourceBaseDir,
+                },
+            }
+            : {}),
     });
     await writeLastStage(stagePaths, last);
     ensureLastBlockBttIds(last);

package/dist/publish/runtime.js

@@ -122,6 +122,7 @@ export function buildPublishRuntime(options, env, markdownPresets) {
         ...(ytDlpPath ? { ytDlpPath } : {}),
         mermaidRenderConfig,
         markdownParseConfig,
+        ...(options.imageSizeResolver ? { imageSizeResolver: options.imageSizeResolver } : {}),
         prepareConfig: {
             enabled: downloadRemoteImages,
             timeoutMs: prepareTimeoutMs,
@@ -145,6 +146,9 @@ export function logPublishRuntimeSummary(runtime, inputCount, inputMode) {
     if (runtime.markdownParseConfig.singleDollarTextMath) {
         console.error('Markdown parse: single_dollar_text_math=true');
     }
+    if (runtime.imageSizeResolver) {
+        console.error('Image display size resolver: enabled');
+    }
     console.error(`Document URL base: ${runtime.documentBaseUrl}`);
     if (runtime.resourceBaseDir) {
         console.error(`Local asset base override: ${runtime.resourceBaseDir}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jacobbubu/md-to-lark",
-  "version": "1.5.0",
+  "version": "1.6.0",
   "description": "Publish Markdown to Feishu docs with a stable pipeline.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",