@jacobbubu/md-to-lark 1.6.0 → 1.7.1

package/README.md

@@ -56,8 +56,8 @@ LARK_DOCUMENT_BASE_URL="https://li.feishu.cn"
 
 Notes:
 
-- `--dry-run` still validates Feishu configuration first. It is not a zero-config mode.
-- As long as `--doc` is not provided, `LARK_FOLDER_TOKEN` is required for single-file, directory, dry-run, and real publish modes.
+- Pure local `--dry-run` does not require Feishu credentials, `--folder`, or `--doc`.
+- Real publishing requires either `--doc` or `LARK_FOLDER_TOKEN`/`--folder`, plus valid Feishu credentials.
 
 The first run should use a built-in sample:
 
@@ -175,13 +175,16 @@ Guardrails:
 - Title derivation, title prefix, and single-H1 promotion
 - Local attachment and image detection with real upload
 - Programmatic image display width control through `imageSizeResolver`
+- Versioned `article-render/v1` contracts with inheritance, capability negotiation, strict pre-publish validation, and render reports
+- Semantic figures, tables, equations, callouts, and GFM footnotes rendered to native Lark block structures
+- Automatic `assets/manifest.yml` image sizing in renderer-contract mode
 - 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
 - Table width heuristics and numeric-column right alignment
 - Chinese Markdown formatting preset (`zh-format`)
 - Ordered preset composition from CLI and programmatic usage
-- Stage cache output from `00-source` to `05-publish`
+- Legacy stage cache output from `00-source` to `05-publish`; protocol mode adds contract and semantic stages through `07-publish`
 - Programmatic access through `publishMdToLark`
 
 ## Where To Read Next

package/dist/commands/publish-md/args.js

@@ -1,6 +1,6 @@
 function usage() {
     return [
-        'Usage: npm run publish:md -- --input <file.md|dir> [--title <doc_title_or_prefix>] [--date-prefix|--no-date-prefix] [--preset <preset_name_or_module_path>]... [--document-base-url <base_url>] [--resource-base-dir <dir>] [--folder <folder_token>] [--doc <document_id>] [--download-remote-images|--no-download-remote-images] [--yt-dlp-path <path>] [--yt-dlp-cookies-path <path>] [--pipeline-cache-dir <dir>] [--single-dollar-text-math] [--mermaid-target <text-drawing|board>] [--mermaid-board-syntax-type <int>] [--mermaid-board-style-type <int>] [--mermaid-board-diagram-type <int>] [--dry-run] [--help|-h]',
+        'Usage: npm run publish:md -- --input <file.md|dir> [--renderer lark] [--renderer-contract <path>] [--strict] [--render-report <path>] [--image-size-manifest <path>] [other options]',
         '',
         'Options:',
         '  --input   Markdown file path, or directory path (publish all *.md recursively).',
@@ -10,6 +10,12 @@ function usage() {
         '  --preset  Optional preset module path (js/mjs/cjs/ts) or built-in name (e.g. medium). Repeatable; presets run in the given order before publish pipeline.',
         '  --document-base-url Base URL used to build documentUrl results (for example https://li.feishu.cn).',
         '  --resource-base-dir Base directory used to resolve relative local image/file paths. Default: the current markdown file directory.',
+        '  --renderer Target renderer. Default: lark.',
+        '  --renderer-contract Explicit article-render/v1 contract path.',
+        '  --renderer-default-contract Fallback renderer contract path when no article contract is found.',
+        '  --strict Require a valid renderer contract and fail before publish on semantic errors.',
+        '  --render-report Write the article-render/v1 JSON report to this path.',
+        '  --image-size-manifest Explicit assets/manifest.yml path for image display sizing.',
         '  --folder  Feishu folder token. Default: LARK_FOLDER_TOKEN from .env',
         '  --doc     Existing Feishu document id (single-file only). If set, publish directly into this doc (and clear content first).',
         '  --download-remote-images    Enable prepare-stage remote image pre-download + link rewrite.',
@@ -33,7 +39,7 @@ function usage() {
         '  5) If markdown has exactly one h1 and --title is not provided, that h1 becomes doc title, then removed from content, and remaining headings are promoted by one level.',
         '  6) Stage cache layout per markdown: 00-source, 01-prepare, 02-hast, 03-last, 04-btt, 05-publish.',
         '  7) Prepare stage can pre-download remote markdown images and optional yt-dlp URL lines.',
-        '  8) Leading YAML/TOML frontmatter is rewritten as fenced code block (yaml/toml), so it stays visible and will not be parsed as headings.',
+        '  8) In article-render/v1 protocol mode, leading YAML frontmatter is parsed for article_render configuration and removed from visible output. In legacy mode, unrecognized frontmatter follows the legacy preparation policy.',
         '  9) Missing local asset files are skipped/degraded to text fallback; publish will not fail only because a referenced local path is absent.',
         '  10) Relative local asset paths resolve against the markdown file directory by default; use --resource-base-dir to override that base.',
         '',
@@ -58,6 +64,12 @@ export function parsePublishMdArgs(argv, env = process.env) {
     const presetPaths = [];
     let documentBaseUrl = '';
     let resourceBaseDir = '';
+    let renderer = '';
+    let rendererContractPath = '';
+    let rendererDefaultContractPath = '';
+    let strict;
+    let renderReportPath = '';
+    let imageSizeManifestPath = '';
     let folderToken = (env.LARK_FOLDER_TOKEN ?? '').trim();
     let documentId;
     let downloadRemoteImages;
@@ -137,6 +149,50 @@ export function parsePublishMdArgs(argv, env = process.env) {
             i += 1;
             continue;
         }
+        if (arg === '--renderer') {
+            const value = argv[i + 1];
+            if (!value)
+                throw new Error('Missing value for --renderer.');
+            renderer = value;
+            i += 1;
+            continue;
+        }
+        if (arg === '--renderer-contract') {
+            const value = argv[i + 1];
+            if (!value)
+                throw new Error('Missing value for --renderer-contract.');
+            rendererContractPath = value;
+            i += 1;
+            continue;
+        }
+        if (arg === '--renderer-default-contract') {
+            const value = argv[i + 1];
+            if (!value)
+                throw new Error('Missing value for --renderer-default-contract.');
+            rendererDefaultContractPath = value;
+            i += 1;
+            continue;
+        }
+        if (arg === '--strict') {
+            strict = true;
+            continue;
+        }
+        if (arg === '--render-report') {
+            const value = argv[i + 1];
+            if (!value)
+                throw new Error('Missing value for --render-report.');
+            renderReportPath = value;
+            i += 1;
+            continue;
+        }
+        if (arg === '--image-size-manifest') {
+            const value = argv[i + 1];
+            if (!value)
+                throw new Error('Missing value for --image-size-manifest.');
+            imageSizeManifestPath = value;
+            i += 1;
+            continue;
+        }
         if (arg === '--doc') {
             const value = argv[i + 1];
             if (!value)
@@ -229,7 +285,7 @@ export function parsePublishMdArgs(argv, env = process.env) {
     if (!inputPath.trim()) {
         throw new Error('Input path is required. Use --input <file.md|dir>.');
     }
-    if (!documentId && !folderToken) {
+    if (!dryRun && !documentId && !folderToken) {
         throw new Error('Folder token is required when --doc is not provided. Use --folder or set LARK_FOLDER_TOKEN.');
     }
     const normalizedPresetPaths = presetPaths.map((presetPath) => presetPath.trim()).filter(Boolean);
@@ -245,6 +301,12 @@ export function parsePublishMdArgs(argv, env = process.env) {
             : {}),
         ...(documentBaseUrl.trim() ? { documentBaseUrl: documentBaseUrl.trim() } : {}),
         ...(resourceBaseDir.trim() ? { resourceBaseDir: resourceBaseDir.trim() } : {}),
+        ...(renderer.trim() ? { renderer: renderer.trim() } : {}),
+        ...(rendererContractPath.trim() ? { rendererContractPath: rendererContractPath.trim() } : {}),
+        ...(rendererDefaultContractPath.trim() ? { rendererDefaultContractPath: rendererDefaultContractPath.trim() } : {}),
+        ...(strict === undefined ? {} : { strict }),
+        ...(renderReportPath.trim() ? { renderReportPath: renderReportPath.trim() } : {}),
+        ...(imageSizeManifestPath.trim() ? { imageSizeManifestPath: imageSizeManifestPath.trim() } : {}),
         folderToken,
         ...(documentId ? { documentId: documentId.trim() } : {}),
         ...(downloadRemoteImages === undefined ? {} : { downloadRemoteImages }),

package/dist/commands/publish-md/command.js

@@ -1,10 +1,11 @@
-import { getPublishMdUsage, hasPublishMdHelpFlag, parsePublishMdArgs } from './args.js';
+import { getPublishMdUsage, hasPublishMdHelpFlag, parsePublishMdArgs, } from './args.js';
 import { resolvePublishInputSet } from './input-resolver.js';
 import { loadMarkdownPresets } from './preset-loader.js';
 import { createDocument, listFolderChildren, normalizeDocumentId } from '../../lark/docx/ops.js';
 import { processSingleMarkdownFile } from '../../publish/process-file.js';
 import { buildPublishRuntime, logPublishRuntimeSummary } from '../../publish/runtime.js';
 import { sleep } from '../../shared/rate-limiter.js';
+import { getRendererCapabilities, validateRendererContract } from '../../protocol/index.js';
 export { getPublishMdUsage, parsePublishMdArgs };
 function resolveMarkdownPresetRefs(options) {
     if (options.presetPaths && options.presetPaths.length > 0) {
@@ -65,19 +66,29 @@ function createFolderDocumentResolver(runtime, options) {
     };
 }
 export async function publishMdToLark(options, env = process.env) {
-    const inputSet = await resolvePublishInputSet(options.inputPath);
-    const markdownPresets = await loadMarkdownPresets(resolveMarkdownPresetRefs(options));
-    if (options.documentId && inputSet.markdownFiles.length !== 1) {
+    const publishOptions = {
+        ...options,
+        folderToken: options.folderToken?.trim() || env.LARK_FOLDER_TOKEN?.trim() || '',
+        dryRun: options.dryRun ?? false,
+    };
+    if (!publishOptions.dryRun && !publishOptions.documentId && !publishOptions.folderToken) {
+        throw new Error('Folder token is required when documentId is not provided.');
+    }
+    const inputSet = await resolvePublishInputSet(publishOptions.inputPath);
+    const markdownPresets = await loadMarkdownPresets(resolveMarkdownPresetRefs(publishOptions));
+    if (publishOptions.documentId && inputSet.markdownFiles.length !== 1) {
         throw new Error('--doc only supports single markdown input file.');
     }
-    const runtime = buildPublishRuntime(options, env, markdownPresets);
+    const runtime = buildPublishRuntime(publishOptions, env, markdownPresets);
     logPublishRuntimeSummary(runtime, inputSet.markdownFiles.length, inputSet.mode);
-    const normalizedDocumentId = options.documentId ? normalizeDocumentId(options.documentId) : undefined;
-    const resolveTargetDocumentId = options.dryRun || normalizedDocumentId ? undefined : createFolderDocumentResolver(runtime, options);
+    const normalizedDocumentId = publishOptions.documentId ? normalizeDocumentId(publishOptions.documentId) : undefined;
+    const resolveTargetDocumentId = publishOptions.dryRun || normalizedDocumentId ? undefined : createFolderDocumentResolver(runtime, publishOptions);
     const results = [];
     for (let index = 0; index < inputSet.markdownFiles.length; index += 1) {
         const markdownPath = inputSet.markdownFiles[index];
-        const perFileOptions = normalizedDocumentId ? { ...options, documentId: normalizedDocumentId } : options;
+        const perFileOptions = normalizedDocumentId
+            ? { ...publishOptions, documentId: normalizedDocumentId }
+            : publishOptions;
         const result = await processSingleMarkdownFile({
             runtime,
             inputSet,
@@ -92,7 +103,7 @@ export async function publishMdToLark(options, env = process.env) {
             status: result.status,
             documentUrl: result.documentUrl,
         });
-        if (!options.dryRun && index < inputSet.markdownFiles.length - 1 && runtime.publishCooldownMs > 0) {
+        if (!publishOptions.dryRun && index < inputSet.markdownFiles.length - 1 && runtime.publishCooldownMs > 0) {
             console.error(`[${index + 1}/${inputSet.markdownFiles.length}] Cooldown ${runtime.publishCooldownMs}ms before next markdown...`);
             await sleep(runtime.publishCooldownMs);
         }
@@ -104,6 +115,21 @@ export async function runPublishMdToLarkCli(argv, env = process.env) {
         console.log(getPublishMdUsage());
         return;
     }
+    if (argv.includes('--print-capabilities')) {
+        const rendererIndex = argv.indexOf('--renderer');
+        const renderer = rendererIndex >= 0 ? argv[rendererIndex + 1] : undefined;
+        console.log(JSON.stringify(getRendererCapabilities(renderer), null, 2));
+        return;
+    }
+    const validateIndex = argv.indexOf('--validate-contract');
+    if (validateIndex >= 0) {
+        const contractPath = argv[validateIndex + 1];
+        if (!contractPath)
+            throw new Error('Missing value for --validate-contract.');
+        const resolved = await validateRendererContract(contractPath);
+        console.log(JSON.stringify(resolved, null, 2));
+        return;
+    }
     const options = parsePublishMdArgs(argv, env);
     const results = await publishMdToLark(options, env);
     process.stdout.write(`${JSON.stringify(results, null, 2)}\n`);

package/dist/index.js

@@ -1 +1,2 @@
 export { publishMdToLark } from './commands/publish-md/index.js';
+export { getRendererCapabilities, parseArticleFrontmatter, resolveRendererContract, validateRendererContract, } from './protocol/index.js';

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

@@ -1,6 +1,7 @@
 import { toString } from 'hast-util-to-string';
 import { createDefaultImagePayload } from '../last/image-defaults.js';
 import { LAST_TEXTUAL_BLOCK_TYPE_SET } from '../last/textual-block-types.js';
+import { parseDirectiveWidth } from './markdown/md-to-semantic-hast.js';
 const BLOCK_CONTAINER_TAGS = new Set([
     'article',
     'section',
@@ -18,6 +19,7 @@ function createContext(options = {}) {
         inlineCounter: 1,
         imageSizeContext: options.imageSizeContext ?? {},
         warnedImageSizeKeys: new Set(),
+        semanticTarget: options.semanticTarget ?? {},
         ...(options.imageSizeResolver ? { imageSizeResolver: options.imageSizeResolver } : {}),
     };
 }
@@ -170,19 +172,27 @@ function buildImageSizeResolverContext(ctx, image) {
     }
     return context;
 }
-function toPositiveRoundedWidth(value) {
+function toPositiveRoundedWidth(value, maximum = 1000) {
     if (!Number.isFinite(value) || value <= 0)
         return undefined;
-    return Math.max(1, Math.round(value));
+    return Math.min(maximum, Math.max(1, Math.round(value)));
 }
 function applyImageDisplaySize(ctx, image, block) {
     if (!ctx.imageSizeResolver || !image.sourceUrl) {
-        return;
+        return false;
     }
     const size = ctx.imageSizeResolver(image.sourceUrl, buildImageSizeResolverContext(ctx, image));
     if (!size) {
-        return;
+        return false;
     }
+    const applyAspectRatio = () => {
+        if (typeof size.aspectRatio === 'number' &&
+            Number.isFinite(size.aspectRatio) &&
+            size.aspectRatio > 0 &&
+            typeof block.payload.width === 'number') {
+            block.payload.height = Math.max(1, Math.round(block.payload.width / size.aspectRatio));
+        }
+    };
     const hasWidthRatio = typeof size.widthRatio === 'number';
     if (hasWidthRatio) {
         const ratio = size.widthRatio;
@@ -193,21 +203,25 @@ function applyImageDisplaySize(ctx, image, block) {
             const width = toPositiveRoundedWidth(baseWidth * ratio);
             if (width !== undefined) {
                 block.payload.width = width;
+                applyAspectRatio();
             }
-            return;
+            return true;
         }
         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);
+        const maximum = createDefaultImagePayload(block.parentId ? ctx.blocks[block.parentId]?.type : undefined).width ?? 1000;
+        const width = toPositiveRoundedWidth(size.widthPx, maximum);
         if (width !== undefined) {
             block.payload.width = width;
-            return;
+            applyAspectRatio();
+            return true;
         }
         warnInvalidImageDisplaySize(ctx, `widthPx:${image.sourceUrl}:${String(size.widthPx)}`, `Ignoring invalid image widthPx for ${image.sourceUrl}: ${String(size.widthPx)}. Expected widthPx > 0.`);
     }
+    return false;
 }
-function createImageBlock(ctx, parentId, sourceUrl, alt = null, title = null, linkHref = null) {
+function createImageBlock(ctx, parentId, sourceUrl, alt = null, title = null, linkHref = null, displayOverride) {
     const blockId = nextBlockId(ctx);
     const parentBlock = ctx.blocks[parentId];
     const image = {
@@ -239,10 +253,81 @@ function createImageBlock(ctx, parentId, sourceUrl, alt = null, title = null, li
     if (Object.keys(selectorAttrs).length > 0) {
         blockBase.selector = { attrs: selectorAttrs };
     }
-    applyImageDisplaySize(ctx, image, blockBase);
+    const resolverMatched = applyImageDisplaySize(ctx, image, blockBase);
+    const shouldApplyOverride = Boolean(displayOverride && (!displayOverride.fallback || !resolverMatched));
+    if (shouldApplyOverride && displayOverride?.widthRatio !== undefined) {
+        const ratio = displayOverride.widthRatio;
+        if (Number.isFinite(ratio) && ratio > 0 && ratio <= 1) {
+            const baseWidth = createDefaultImagePayload(parentBlock?.type).width ?? blockBase.payload.width ?? 0;
+            blockBase.payload.width = Math.max(1, Math.round(baseWidth * ratio));
+        }
+    }
+    else if (shouldApplyOverride && displayOverride?.widthPx !== undefined && displayOverride.widthPx > 0) {
+        const maximum = createDefaultImagePayload(parentBlock?.type).width ?? 1000;
+        blockBase.payload.width = Math.min(maximum, Math.max(1, Math.round(displayOverride.widthPx)));
+    }
+    if (shouldApplyOverride && displayOverride?.aspectRatio && blockBase.payload.width) {
+        blockBase.payload.height = Math.max(1, Math.round(blockBase.payload.width / displayOverride.aspectRatio));
+    }
+    if (displayOverride?.align)
+        blockBase.payload.align = displayOverride.align;
     addBlock(ctx, blockBase);
     return blockId;
 }
+function attachSemanticMeta(ctx, blockId, role, semanticId) {
+    const block = ctx.blocks[blockId];
+    if (!block)
+        return;
+    block.selector = {
+        ...(block.selector ?? {}),
+        labels: [...(block.selector?.labels ?? []), role],
+        attrs: {
+            ...(block.selector?.attrs ?? {}),
+            semanticRole: role,
+            ...(semanticId ? { semanticId } : {}),
+        },
+    };
+}
+function normalizeCalloutColor(value) {
+    return value?.trim().toLowerCase().replaceAll('-', '_') || undefined;
+}
+function calloutStyleForElement(element, footnote) {
+    const target = footnote ? undefined : getStringProp(element, 'type');
+    const defaults = {
+        note: { backgroundColor: 'light_gray', borderColor: 'gray' },
+        info: { backgroundColor: 'light_blue', borderColor: 'blue' },
+        tip: { backgroundColor: 'light_green', borderColor: 'green' },
+        warning: { backgroundColor: 'light_yellow', borderColor: 'yellow' },
+        danger: { backgroundColor: 'light_red', borderColor: 'red' },
+        important: { backgroundColor: 'light_purple', borderColor: 'purple' },
+    };
+    const style = defaults[target ?? 'note'] ?? defaults.note;
+    return {
+        backgroundColor: style.backgroundColor,
+        borderColor: style.borderColor,
+    };
+}
+function createCalloutBlock(ctx, parentId, element, footnote) {
+    const blockId = nextBlockId(ctx);
+    const base = calloutStyleForElement(element, footnote);
+    const footnoteTarget = ctx.semanticTarget.footnotes;
+    const backgroundColor = footnote ? normalizeCalloutColor(footnoteTarget?.background_color ?? null) : undefined;
+    const borderColor = footnote ? normalizeCalloutColor(footnoteTarget?.border_color ?? null) : undefined;
+    addBlock(ctx, {
+        id: blockId,
+        type: 'callout',
+        parentId,
+        children: [],
+        payload: {
+            ...base,
+            ...(backgroundColor ? { backgroundColor: backgroundColor } : {}),
+            ...(borderColor ? { borderColor: borderColor } : {}),
+            ...(footnoteTarget?.icon ? { emojiId: footnoteTarget.icon } : {}),
+        },
+    });
+    attachSemanticMeta(ctx, blockId, footnote ? 'footnote' : 'callout', getStringProp(element, 'semanticId') ?? undefined);
+    return blockId;
+}
 function createIframeBlock(ctx, parentId, url, iframeType) {
     const blockId = nextBlockId(ctx);
     addBlock(ctx, {
@@ -426,7 +511,7 @@ function parseInlineNodes(ctx, nodes, marks = createDefaultMarks()) {
         if (node.tagName === 'u') {
             nextMarks.underline = true;
         }
-        if (node.tagName === 'a') {
+        if (node.tagName === 'a' || node.tagName === 'm2l-footnote-reference') {
             const href = getStringProp(node, 'href');
             nextMarks.link = href ? { url: href } : null;
         }
@@ -877,6 +962,189 @@ function convertParagraph(ctx, paragraph, parentId) {
     }
     return [createTextualBlock(ctx, 'text', parentId, parseInlineNodes(ctx, getChildren(paragraph)))];
 }
+function collectSemanticImages(element) {
+    const images = [];
+    const visit = (node) => {
+        if (!isElement(node))
+            return;
+        const image = extractImageSourceFromElement(node);
+        if (image?.sourceUrl) {
+            images.push(image);
+            return;
+        }
+        for (const child of getChildren(node))
+            visit(child);
+    };
+    for (const child of getChildren(element))
+        visit(child);
+    return images;
+}
+function findDirectSemanticChild(element, tagName) {
+    return getChildren(element).find((child) => isElement(child) && child.tagName === tagName);
+}
+function createSemanticTextBlock(ctx, element, parentId, role, semanticId) {
+    const blockId = createTextualBlock(ctx, 'text', parentId, parseInlineNodes(ctx, getChildren(element)));
+    attachSemanticMeta(ctx, blockId, role, semanticId);
+    return blockId;
+}
+function parseSemanticAlign(element) {
+    return parseAlignValue(getStringProp(element, 'align'));
+}
+function semanticAnnotationIds(ctx, wrapper, parentId, semanticId) {
+    const result = {};
+    for (const role of ['caption', 'note', 'source']) {
+        const element = findDirectSemanticChild(wrapper, `m2l-${role}`);
+        if (element)
+            result[role] = createSemanticTextBlock(ctx, element, parentId, role, semanticId);
+    }
+    return result;
+}
+function convertSemanticFigure(ctx, figure, parentId) {
+    const semanticId = getStringProp(figure, 'semanticId') ?? undefined;
+    const display = parseDirectiveWidth(getStringProp(figure, 'width') ?? '');
+    const fallbackRatio = ctx.semanticTarget.figures?.default_width_ratio;
+    const effectiveDisplay = display ??
+        (typeof fallbackRatio === 'number' && fallbackRatio > 0 && fallbackRatio <= 1
+            ? { widthRatio: fallbackRatio, fallback: true }
+            : undefined);
+    const align = parseSemanticAlign(figure);
+    const imageIds = collectSemanticImages(figure).map((image) => {
+        const imageId = createImageBlock(ctx, parentId, image.sourceUrl, image.alt, image.title, image.linkHref, {
+            ...(effectiveDisplay ?? {}),
+            ...(align ? { align } : {}),
+        });
+        attachSemanticMeta(ctx, imageId, 'figure-image', semanticId);
+        return imageId;
+    });
+    const annotations = semanticAnnotationIds(ctx, figure, parentId, semanticId);
+    const target = ctx.semanticTarget.figures;
+    const ids = [];
+    if (target?.caption_position === 'above' && annotations.caption)
+        ids.push(annotations.caption);
+    if (target?.source_position === 'above' && annotations.source)
+        ids.push(annotations.source);
+    if (target?.note_position === 'above' && annotations.note)
+        ids.push(annotations.note);
+    ids.push(...imageIds);
+    if (target?.caption_position !== 'above' && annotations.caption)
+        ids.push(annotations.caption);
+    if (target?.source_position === 'below-caption' && annotations.source)
+        ids.push(annotations.source);
+    if (target?.note_position !== 'above' && annotations.note)
+        ids.push(annotations.note);
+    if (target?.source_position !== 'above' && target?.source_position !== 'below-caption' && annotations.source) {
+        ids.push(annotations.source);
+    }
+    return ids;
+}
+function convertSemanticTable(ctx, wrapper, parentId) {
+    const semanticId = getStringProp(wrapper, 'semanticId') ?? undefined;
+    const table = getChildren(wrapper).find((child) => isElement(child) && child.tagName === 'table');
+    const annotations = semanticAnnotationIds(ctx, wrapper, parentId, semanticId);
+    const tableIds = table ? convertTable(ctx, table, parentId) : [];
+    for (const tableId of tableIds)
+        attachSemanticMeta(ctx, tableId, 'semantic-table', semanticId);
+    const target = ctx.semanticTarget.tables;
+    const ids = [];
+    if (target?.caption_position !== 'below' && annotations.caption)
+        ids.push(annotations.caption);
+    if (target?.source_position === 'above' && annotations.source)
+        ids.push(annotations.source);
+    ids.push(...tableIds);
+    if (target?.caption_position === 'below' && annotations.caption)
+        ids.push(annotations.caption);
+    if (annotations.note)
+        ids.push(annotations.note);
+    if (target?.source_position !== 'above' && annotations.source)
+        ids.push(annotations.source);
+    return ids;
+}
+function convertSemanticEquation(ctx, wrapper, parentId) {
+    const semanticId = getStringProp(wrapper, 'semanticId') ?? undefined;
+    const ids = [];
+    const equationNumber = getStringProp(wrapper, 'equationNumber');
+    let numberAttached = false;
+    for (const child of getChildren(wrapper)) {
+        if (isElement(child) && ['m2l-caption', 'm2l-note', 'm2l-source'].includes(child.tagName))
+            continue;
+        for (const blockId of convertBlock(ctx, child, parentId)) {
+            attachSemanticMeta(ctx, blockId, 'equation', semanticId);
+            const block = ctx.blocks[blockId];
+            if (equationNumber && !numberAttached && block && isTextualBlockNode(block)) {
+                block.payload.inlines.push({
+                    id: nextInlineId(ctx),
+                    kind: 'text_run',
+                    marks: createDefaultMarks(),
+                    text: ` (${equationNumber})`,
+                });
+                numberAttached = true;
+            }
+            ids.push(blockId);
+        }
+    }
+    const annotations = semanticAnnotationIds(ctx, wrapper, parentId, semanticId);
+    if (annotations.caption)
+        ids.push(annotations.caption);
+    if (annotations.note)
+        ids.push(annotations.note);
+    if (annotations.source)
+        ids.push(annotations.source);
+    return ids;
+}
+function prependFootnoteLabel(ctx, blockId, label) {
+    const block = ctx.blocks[blockId];
+    if (!block || !isTextualBlockNode(block))
+        return;
+    block.payload.inlines.unshift({
+        id: nextInlineId(ctx),
+        kind: 'text_run',
+        marks: { ...createDefaultMarks(), bold: true },
+        text: `[${label}] `,
+    });
+}
+function convertSemanticCallout(ctx, element, parentId, footnote) {
+    const output = [];
+    let calloutId = createCalloutBlock(ctx, parentId, element, footnote);
+    output.push(calloutId);
+    let firstText = true;
+    const appendConverted = (blockId) => {
+        const block = ctx.blocks[blockId];
+        if (!block)
+            return;
+        if (block.type === 'image' || block.type === 'table' || block.type === 'file' || block.type === 'board') {
+            block.parentId = parentId;
+            attachSemanticMeta(ctx, blockId, footnote ? 'footnote-media-sibling' : 'callout-media-sibling', getStringProp(element, 'semanticId') ?? undefined);
+            output.push(blockId);
+            calloutId = createCalloutBlock(ctx, parentId, element, footnote);
+            output.push(calloutId);
+            return;
+        }
+        const callout = ctx.blocks[calloutId];
+        if (!callout || callout.type !== 'callout')
+            return;
+        block.parentId = calloutId;
+        appendChild(callout, blockId);
+        if (footnote && firstText && isTextualBlockNode(block)) {
+            prependFootnoteLabel(ctx, blockId, getStringProp(element, 'semanticId') ?? '?');
+            firstText = false;
+        }
+    };
+    for (const child of getChildren(element)) {
+        const current = ctx.blocks[calloutId];
+        if (!current || current.type !== 'callout')
+            continue;
+        for (const blockId of convertBlock(ctx, child, calloutId))
+            appendConverted(blockId);
+    }
+    for (const blockId of [...output]) {
+        const block = ctx.blocks[blockId];
+        if (block?.type === 'callout' && block.children.length === 0) {
+            delete ctx.blocks[blockId];
+            output.splice(output.indexOf(blockId), 1);
+        }
+    }
+    return output;
+}
 function convertBlock(ctx, node, parentId) {
     if (isWhitespaceTextNode(node)) {
         return [];
@@ -923,6 +1191,21 @@ function convertBlock(ctx, node, parentId) {
             return [createDividerBlock(ctx, parentId)];
         case 'table':
             return convertTable(ctx, node, parentId);
+        case 'm2l-figure':
+            return convertSemanticFigure(ctx, node, parentId);
+        case 'm2l-table':
+            return convertSemanticTable(ctx, node, parentId);
+        case 'm2l-equation':
+            return convertSemanticEquation(ctx, node, parentId);
+        case 'm2l-callout':
+            return convertSemanticCallout(ctx, node, parentId, false);
+        case 'm2l-footnote':
+            return convertSemanticCallout(ctx, node, parentId, true);
+        case 'm2l-unknown-directive':
+        case 'm2l-caption':
+        case 'm2l-note':
+        case 'm2l-source':
+            return convertUnknownElement(ctx, node, parentId);
         case 'img':
             return [
                 createImageBlock(ctx, parentId, getStringProp(node, 'src'), getStringProp(node, 'alt'), getStringProp(node, 'title')),

package/dist/pipeline/index.js

@@ -1,3 +1,4 @@
 export { markdownToHast } from './markdown/md-to-hast.js';
+export { markdownToSemanticHast, parseDirectiveWidth } from './markdown/md-to-semantic-hast.js';
 export { prepareMarkdownBeforePublish } from './markdown/prepare-markdown.js';
 export { hastToLAST } from './hast-to-last.js';