@jacobbubu/md-to-lark 1.5.1 → 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, alt = null) {
+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',
@@ -162,9 +230,16 @@ function createImageBlock(ctx, parentId, sourceUrl, alt = null) {
     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;
 }
@@ -370,17 +445,21 @@ function extractImageSourceFromElement(element) {
         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;
-    return extractImageSourceFromElement(only);
+    const imageSource = extractImageSourceFromElement(only);
+    return imageSource ? { ...imageSource, linkHref: href } : null;
 }
 function findStandaloneImageInParagraph(paragraph) {
     const meaningfulChildren = getMeaningfulChildren(getChildren(paragraph));
@@ -692,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, richItem.alt);
+                const imageId = createImageBlock(ctx, cellId, richItem.sourceUrl, richItem.alt, richItem.title, richItem.linkHref);
                 cellBlock.children = [imageId];
                 cells.push(cellId);
                 continue;
@@ -764,7 +843,9 @@ function hasNonWhitespaceInline(inlines) {
 function convertParagraph(ctx, paragraph, parentId) {
     const standaloneImage = findStandaloneImageInParagraph(paragraph);
     if (standaloneImage?.sourceUrl) {
-        return [createImageBlock(ctx, parentId, standaloneImage.sourceUrl, standaloneImage.alt)];
+        return [
+            createImageBlock(ctx, parentId, standaloneImage.sourceUrl, standaloneImage.alt, standaloneImage.title, standaloneImage.linkHref),
+        ];
     }
     const standaloneIframe = findStandaloneIframePayloadInParagraph(paragraph);
     if (standaloneIframe) {
@@ -785,7 +866,7 @@ function convertParagraph(ctx, paragraph, parentId) {
         const image = isElement(child) ? extractImageSourceFromElement(child) : null;
         if (image?.sourceUrl) {
             flushText();
-            ids.push(createImageBlock(ctx, parentId, image.sourceUrl, image.alt));
+            ids.push(createImageBlock(ctx, parentId, image.sourceUrl, image.alt, image.title, image.linkHref));
             continue;
         }
         pendingInlineNodes.push(child);
@@ -843,7 +924,9 @@ function convertBlock(ctx, node, parentId) {
         case 'table':
             return convertTable(ctx, node, parentId);
         case 'img':
-            return [createImageBlock(ctx, parentId, getStringProp(node, 'src'), getStringProp(node, 'alt'))];
+            return [
+                createImageBlock(ctx, parentId, getStringProp(node, 'src'), getStringProp(node, 'alt'), getStringProp(node, 'title')),
+            ];
         case 'br':
             return [
                 createTextualBlock(ctx, 'text', parentId, [
@@ -956,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.1",
+  "version": "1.6.0",
   "description": "Publish Markdown to Feishu docs with a stable pipeline.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",