@jacobbubu/md-to-lark 1.7.0 → 1.8.0

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:
 
@@ -88,6 +88,18 @@ Progress logs and exceptions are written to stderr.
 
 Relative local assets such as `./img-001.png` still resolve against the Markdown file directory by default. If your caller generates a temporary Markdown file elsewhere, use `--resource-base-dir` to keep local asset resolution pinned to the original content directory.
 
+## Markdown Syntax Notes
+
+Inline `<mark>text</mark>` is supported as a controlled HTML shorthand for Feishu yellow text background highlight.
+
+Example:
+
+```md
+This is <mark>important text</mark>.
+```
+
+Nested Markdown marks inside `<mark>...</mark>`, such as `**bold**` and links, are preserved. This does not enable arbitrary raw HTML rendering; unsupported HTML keeps the existing parser behavior.
+
 ## Common Commands
 
 Basic publish:
@@ -182,6 +194,7 @@ Guardrails:
 - 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
+- Inline `<mark>text</mark>` mapped to Feishu yellow text background
 - Chinese Markdown formatting preset (`zh-format`)
 - Ordered preset composition from CLI and programmatic usage
 - Legacy stage cache output from `00-source` to `05-publish`; protocol mode adds contract and semantic stages through `07-publish`

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

@@ -39,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.',
         '',
@@ -285,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);

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

@@ -71,7 +71,7 @@ export async function publishMdToLark(options, env = process.env) {
         folderToken: options.folderToken?.trim() || env.LARK_FOLDER_TOKEN?.trim() || '',
         dryRun: options.dryRun ?? false,
     };
-    if (!publishOptions.documentId && !publishOptions.folderToken) {
+    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);

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

@@ -511,6 +511,9 @@ function parseInlineNodes(ctx, nodes, marks = createDefaultMarks()) {
         if (node.tagName === 'u') {
             nextMarks.underline = true;
         }
+        if (node.tagName === 'mark') {
+            nextMarks.backgroundColor = 'light_yellow';
+        }
         if (node.tagName === 'a' || node.tagName === 'm2l-footnote-reference') {
             const href = getStringProp(node, 'href');
             nextMarks.link = href ? { url: href } : null;

package/dist/pipeline/markdown/md-to-hast.js

@@ -4,12 +4,14 @@ import remarkGfm from 'remark-gfm';
 import remarkMath from 'remark-math';
 import remarkRehype from 'remark-rehype';
 import { normalizeMarkdownBeforeParse } from './normalize-markdown.js';
+import { remarkMarkToHast } from './remark-mark.js';
 export async function markdownToHast(markdown, options = {}) {
     const content = normalizeMarkdownBeforeParse(markdown);
     const processor = unified()
         .use(remarkParse)
         .use(remarkGfm)
         .use(remarkMath, { singleDollarTextMath: options.singleDollarTextMath ?? false })
+        .use(remarkMarkToHast)
         .use(remarkRehype, { allowDangerousHtml: false });
     const mdast = processor.parse(content);
     const hast = await processor.run(mdast);

package/dist/pipeline/markdown/md-to-semantic-hast.js

@@ -9,9 +9,11 @@ import { normalizeChineseBoldClosingPunctuation } from './normalize-markdown.js'
 const SUPPORTED_CONTAINER_DIRECTIVES = new Set(['figure', 'table', 'equation', 'callout', 'footnote']);
 const SUPPORTED_LEAF_DIRECTIVES = new Set(['caption', 'note', 'source']);
 const FORBIDDEN_MATH_COMMAND_RE = /\\(?:includegraphics|include|input|cite|documentclass|usepackage|begin\{document\}|end\{document\})\b/;
-const CURRENCY_MATH_RE = /^\s*(?:[$€£¥]\s*)?\d[\d,.]*(?:[KMBT])?(?:\s*-\s*[$€£¥]?\s*\d[\d,.]*(?:[KMBT])?)?\s*$/i;
 const INLINE_CODE_PIPE_PLACEHOLDER = '\uE000';
 const INLINE_MATH_PIPE_PLACEHOLDER = '\uE001';
+const CURRENCY_DOLLAR_PLACEHOLDER = '\uE002';
+const CURRENCY_TOKEN_RE = /(?<![\\$])\$(?:\d{1,3}(?:,\d{3})+|\d+)(?:\.\d+)?(?:[KMBT])?(?:\/(?:year|yr))?(?=$|[\s)\]}>.,;:!?"'%…—–-])/gi;
+const CURRENCY_MATH_RE = /^\s*(?:[$€£¥]\s*)?\d[\d,.]*(?:[KMBT])?(?:\s*-\s*[$€£¥]?\s*\d[\d,.]*(?:[KMBT])?)?\s*$/i;
 function normalizeDirectiveTree(node) {
     if (node.type === 'footnoteReference') {
         const id = node.identifier ?? node.label ?? '';
@@ -71,9 +73,7 @@ function collectProtectedMdastRanges(tree) {
 function protectCurrencyDollars(markdown) {
     const tree = unified().use(remarkParse).parse(markdown);
     const ranges = collectProtectedMdastRanges(tree);
-    const protectSegment = (segment) => segment
-        .replace(/(?<!\\)\$(\d[\d,.]*(?:[KMBT])?)\s*[-–]\s*\$(\d[\d,.]*(?:[KMBT])?)/gi, (_all, left, right) => `\\$${left}-\\$${right}`)
-        .replace(/(?<!\\)\$(\d[\d,.]*(?:[KMBT])?)\$/gi, (_all, amount) => `\\$${amount}\\$`);
+    const protectSegment = (segment) => segment.replace(CURRENCY_TOKEN_RE, (token) => CURRENCY_DOLLAR_PLACEHOLDER + token.slice(1));
     let output = '';
     let cursor = 0;
     for (const range of ranges) {
@@ -84,6 +84,70 @@ function protectCurrencyDollars(markdown) {
     output += protectSegment(markdown.slice(cursor));
     return output;
 }
+function restoreCurrencyPlaceholders(hast) {
+    const restore = (value) => value.replaceAll(CURRENCY_DOLLAR_PLACEHOLDER, '$');
+    const visit = (node) => {
+        if (node.type === 'text') {
+            node.value = restore(node.value);
+            return;
+        }
+        if (!isElement(node))
+            return;
+        for (const [key, value] of Object.entries(node.properties ?? {})) {
+            if (typeof value === 'string')
+                node.properties[key] = restore(value);
+            else if (Array.isArray(value)) {
+                node.properties[key] = value.map((item) => (typeof item === 'string' ? restore(item) : item));
+            }
+        }
+        for (const child of node.children)
+            visit(child);
+    };
+    for (const child of hast.children)
+        visit(child);
+}
+function isHtmlCommentOnly(value) {
+    let remaining = value.trim();
+    while (remaining.startsWith('<!--')) {
+        const end = remaining.indexOf('-->');
+        if (end < 0)
+            return false;
+        remaining = remaining.slice(end + 3).trim();
+    }
+    return remaining.length === 0;
+}
+function analyzeRawHtmlMdast(tree, options) {
+    const diagnostics = [];
+    const referencedFootnoteIds = new Set();
+    const visit = (node) => {
+        if (node.type === 'html' && typeof node.value === 'string') {
+            if (isHtmlCommentOnly(node.value))
+                return;
+            for (const match of node.value.matchAll(/\[\^([^\]\s]+)\]/g)) {
+                if (match[1])
+                    referencedFootnoteIds.add(match[1].toLowerCase());
+            }
+            const tag = /<\s*\/?\s*([A-Za-z][\w:-]*)/.exec(node.value)?.[1]?.toLowerCase() ?? 'html';
+            diagnostics.push({
+                severity: options.strict ? 'error' : 'warning',
+                code: 'unsupported-raw-html',
+                message: tag === 'table'
+                    ? 'Raw HTML <table> would be discarded in Lark protocol mode. Convert it to a GFM table before publication.'
+                    : 'Raw HTML <' +
+                        tag +
+                        '> would be discarded in Lark protocol mode. Convert it to Markdown before publication.',
+                ...(options.inputPath ? { sourcePath: options.inputPath } : {}),
+                ...(typeof node.position?.start?.line === 'number' ? { line: node.position.start.line } : {}),
+                ...(typeof node.position?.start?.column === 'number' ? { column: node.position.start.column } : {}),
+            });
+            return;
+        }
+        for (const child of node.children ?? [])
+            visit(child);
+    };
+    visit(tree);
+    return { diagnostics, referencedFootnoteIds };
+}
 function protectTableInlinePipes(markdown) {
     const lines = markdown.match(/[^\n]*\n|[^\n]+/g) ?? [''];
     let fenceMarker = '';
@@ -402,6 +466,7 @@ function analyzeSemanticHast(hast, options) {
                 code: 'unreferenced-footnote',
                 message: `Footnote definition is not referenced: ${id}.`,
                 ...(options.inputPath ? { sourcePath: options.inputPath } : {}),
+                semanticId: id,
             });
     }
     if (footnoteReferences.size > 0) {
@@ -568,14 +633,23 @@ export async function markdownToSemanticHast(markdown, options = {}) {
         .use(semanticDirectivePlugin)
         .use(remarkRehype, { allowDangerousHtml: false });
     const mdast = processor.parse(content);
+    const rawHtml = analyzeRawHtmlMdast(mdast, options);
     const unparsedFootnoteReferences = collectUnparsedFootnoteReferences(mdast);
     const hast = (await processor.run(mdast));
     restoreTableInlinePipes(hast);
-    if (options.target?.math?.currency_policy !== 'parse')
+    if (options.target?.math?.currency_policy !== 'parse') {
+        restoreCurrencyPlaceholders(hast);
         restoreCurrencyMath(hast, content);
+    }
     assignAutomaticEquationNumbers(hast);
     normalizeMathHast(hast, options.target?.math);
     const semantic = analyzeSemanticHast(hast, options);
+    if (rawHtml.referencedFootnoteIds.size > 0) {
+        semantic.diagnostics = semantic.diagnostics.filter((diagnostic) => diagnostic.code !== 'unreferenced-footnote' ||
+            !diagnostic.semanticId ||
+            !rawHtml.referencedFootnoteIds.has(diagnostic.semanticId.toLowerCase()));
+    }
+    semantic.diagnostics.unshift(...rawHtml.diagnostics);
     for (const id of unparsedFootnoteReferences) {
         semantic.counts.footnoteReferences += 1;
         if (!semantic.diagnostics.some((diagnostic) => diagnostic.code === 'missing-footnote-definition' && diagnostic.message.includes(id))) {

package/dist/pipeline/markdown/remark-mark.js

@@ -0,0 +1,83 @@
+const MARK_OPEN_RE = /^<mark(?:\s[^>]*)?>$/i;
+const MARK_CLOSE_RE = /^<\/mark\s*>$/i;
+function isHtmlNode(node) {
+    return node?.type === 'html' && typeof node.value === 'string';
+}
+function isMarkOpen(node) {
+    return isHtmlNode(node) && MARK_OPEN_RE.test(node.value.trim());
+}
+function isMarkClose(node) {
+    return isHtmlNode(node) && MARK_CLOSE_RE.test(node.value.trim());
+}
+function toMarkNode(open, close, children) {
+    const markNode = {
+        type: 'mark',
+        children,
+        data: {
+            hName: 'mark',
+        },
+    };
+    if (open.position?.start && close.position?.end) {
+        markNode.position = {
+            start: open.position.start,
+            end: close.position.end,
+        };
+    }
+    return markNode;
+}
+function rewriteMarkPairs(children) {
+    const rewritten = [];
+    let cursor = 0;
+    while (cursor < children.length) {
+        const node = children[cursor];
+        if (!node) {
+            cursor += 1;
+            continue;
+        }
+        if (!isMarkOpen(node)) {
+            rewritten.push(node);
+            cursor += 1;
+            continue;
+        }
+        const markChildren = [];
+        let depth = 1;
+        let closeIndex = -1;
+        for (let index = cursor + 1; index < children.length; index += 1) {
+            const child = children[index];
+            if (!child)
+                continue;
+            if (isMarkOpen(child)) {
+                depth += 1;
+            }
+            if (isMarkClose(child)) {
+                depth -= 1;
+                if (depth === 0) {
+                    closeIndex = index;
+                    break;
+                }
+            }
+            markChildren.push(child);
+        }
+        if (closeIndex === -1) {
+            rewritten.push(node);
+            cursor += 1;
+            continue;
+        }
+        rewritten.push(toMarkNode(node, children[closeIndex], rewriteMarkPairs(markChildren)));
+        cursor = closeIndex + 1;
+    }
+    return rewritten;
+}
+function visit(node) {
+    if (!Array.isArray(node.children))
+        return;
+    for (const child of node.children) {
+        visit(child);
+    }
+    node.children = rewriteMarkPairs(node.children);
+}
+export const remarkMarkToHast = function remarkMarkToHast() {
+    return (tree) => {
+        visit(tree);
+    };
+};

package/dist/publish/runtime.js

@@ -53,8 +53,18 @@ function normalizeOptionalPath(value) {
     }
     return trimmed;
 }
+function withDryRunLarkDefaults(env) {
+    const tokenType = env.LARK_TOKEN_TYPE?.trim();
+    return {
+        ...env,
+        LARK_APP_ID: env.LARK_APP_ID?.trim() || 'dry-run',
+        LARK_APP_SECRET: env.LARK_APP_SECRET?.trim() || 'dry-run',
+        LARK_TOKEN_TYPE: tokenType === 'tenant' || tokenType === 'user' ? tokenType : 'tenant',
+        LARK_USER_ACCESS_TOKEN: env.LARK_USER_ACCESS_TOKEN?.trim() || 'dry-run',
+    };
+}
 export function buildPublishRuntime(options, env, markdownPresets) {
-    const config = createLarkClientConfigFromEnv(env);
+    const config = createLarkClientConfigFromEnv(options.dryRun ? withDryRunLarkDefaults(env) : env);
     const sdkClient = new lark.Client({
         appId: config.appId,
         appSecret: config.appSecret,

package/package.json

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