md-to-lark

中文说明

md-to-lark publishes Markdown (GFM) content to Feishu docs through a repeatable pipeline.

It is not a one-off rendering script. The pipeline covers input preparation, title policy, asset detection and upload, Mermaid rendering, table enhancement, dry-run, and stage-by-stage artifacts for debugging.

Repository And Package Name

• GitHub repository: jacobbubu/md-to-lark
• The npm package metadata is configured as @jacobbubu/md-to-lark
• The dependency @jacobbubu/md-zh-format remains unchanged

Notes:

• The commands in this README are still focused on local development and verification.
• Once the package is actually published to npm, it can be installed as @jacobbubu/md-to-lark.

What It Is Good For

• Publishing a single Markdown file to a Feishu doc
• Recursively publishing multiple .md files from a directory
• Preparing local assets, remote images, and standalone URLs before publish
• Running a full dry-run without writing to Feishu
• Rewriting Markdown before publish with one or more ordered presets

Quick Start

Install dependencies first:

npm install

Then prepare .env:

cp .env.sample .env

At minimum, make sure these values are valid:

LARK_APP_ID="xxx"
LARK_APP_SECRET="xxx"
LARK_TOKEN_TYPE=tenant
LARK_FOLDER_TOKEN="xxx"

If you want the returned documentUrl to use a specific browser domain, set this too:

LARK_DOCUMENT_BASE_URL="https://li.feishu.cn"

Notes:

• 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:

npm run publish:md -- --input ./test-md/comp/comp.md --dry-run

This runs the full pipeline without actually writing to Feishu. After that looks correct, remove --dry-run:

npm run publish:md -- --input ./test-md/comp/comp.md

Successful CLI runs now print a JSON array to stdout. Each item contains:

• documentId
• title
• status
• documentUrl

Progress logs and exceptions are written to stderr.

documentUrl is built from documentId plus a document base URL:

• Prefer --document-base-url
• Otherwise use LARK_DOCUMENT_BASE_URL
• Otherwise fall back to the current compatibility derivation from LARK_BASE_URL

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.

Common Commands

Basic publish:

npm run publish:md -- --input ./test-md/comp/comp.md
npm run publish:md -- --input ./test-md/comp/comp.md --dry-run
npm run publish:md -- --input ./test-md

Target document and title:

npm run publish:md -- --input ./test-md/comp/comp.md --doc <document_id>
npm run publish:md -- --input ./test-md --title "Team Notes"
npm run publish:md -- --input ./test-md/comp/comp.md --no-date-prefix

Presets, Mermaid, and stage artifacts:

npm run publish:md -- --input ./test-md/comp/comp.md --preset medium --dry-run
npm run publish:md -- --input ./test-md/comp/comp.md --preset zh-format --dry-run
npm run publish:md -- --input ./test-md/comp/comp.md --preset zh-format --preset ./my-preset.mjs --dry-run
npm run publish:md -- --input ./paper.md --single-dollar-text-math --dry-run
npm run publish:md -- --input ./tmp/generated/article.md --resource-base-dir ./source-assets --dry-run
npm run publish:md -- --input ./test-md/mermaid.md --mermaid-target board --dry-run
npm run publish:md -- --input ./test-md/comp/comp.md --pipeline-cache-dir ./out/debug-cache --dry-run

Debugging and helper scripts:

npm run dev:playground
npm run example:module
npm run fetch:board-data -- --doc <document_id> --index 1

Testing

Default local verification:

npm run check
npm test

Live Feishu end-to-end tests:

npm run test:e2e
npm run test:e2e:watch

Notes:

• npm test only runs local tests and never writes to Feishu.
• npm run test:e2e runs real Feishu end-to-end tests and requires a local .env-test.
• .env-test is already ignored by Git and can be prepared from .env-test.example.

Release Process

Releases are now driven by semantic-release.

• Only pushes to main can trigger a real release
• Version numbers are calculated from commit messages
• GitHub Releases and npm publishing are both handled automatically
• CHANGELOG.md is maintained by CI

Required repository setup:

• GitHub Actions must be enabled
• The repository must have an NPM_TOKEN secret with publish permission for @jacobbubu/md-to-lark
• Commits merged into main should continue to use Conventional Commit style such as feat: and fix:

Guardrails:

• Non-main branches do not trigger the release workflow
• Non-main branches can still run local checks, tests, and build verification
• npm publishing is expected to happen only through the main branch CI flow

Core Capabilities

• 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
• 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
• 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

README is only the entry point. It does not repeat the full parameter reference or implementation details.

1. docs/README.md
2. overview.md
3. quickstart.md
4. presets.md
5. cli-reference.md
6. architecture-overview.md

If this is your first time using the project, read in this order:

01-getting-started -> 02-guides -> 03-reference -> 04-internals