跳过浏览器,MD 文档直接渲染图片

一个「反常识」的项目

大多数人对 Markdown 渲染的认知停留在这一条管线：

Markdown → HTML → DOM → 浏览器布局引擎 → 截图

但 marknative^[1] 走了一条完全不同的路：

Markdown → 内部文档模型 → 布局引擎 → 分页 → 2D Canvas 直接绘制

不需要 Chromium，不需要 Puppeteer，不需要任何浏览器环境。纯 Node.js/Bun 服务端，直接输出 PNG 或 SVG。

这个项目由 Linux Do 社区的 liyown 开发，目前版本 0.5.0，MIT 开源协议。

示例图片效果

核心架构：五层管线

marknative 的渲染管线分为 5 个独立可测试的阶段，每一层都可以单独替换或扩展：

① Parser（解析层） 基于 micromark + mdast-util-from-markdown，完整支持 CommonMark 和 GFM 扩展。数学公式通过 mathjax-full 在服务端渲染为 SVG。

② Layout（布局层） 自定义的块级和行内布局引擎。文本排版基于 @chenglou/pretext，支持 Unicode 安全断行和 CJK 字符处理。

③ Pagination（分页层） 将布局片段分页到固定尺寸页面（默认 1080×1440px），包含寡妇行保护算法。也支持单页模式（最大 16384px 高）。

④ Paint（渲染层） 使用 skia-canvas（v2）作为 2D 渲染后端，输出 PNG 或 SVG。

⑤ Theme（主题层） 内置 10 个主题：default、github、solarized、sepia、rose、dark、nord、dracula、ocean、forest。支持线性渐变和径向渐变背景。

几个有意思的技术细节

数学公式的「超采样」渲染

行内公式作为 SVG data URI 嵌入，通过 mathDepth 精确对齐文本基线。MathJax SVG 以 2× 物理尺寸生成，Canvas 降采样到 1×——公式渲染比直接渲染更清晰。

智能代码高亮

通过 Shiki（v4）实现语法高亮，自动根据页面背景色亮度（WCAG luminance）选择亮色或暗色代码主题。不用手动指定。

文本测量 fallback

提供 OffscreenCanvas shim 和纯 JS 文本宽度估算（基于 grapheme 分类），在没有 Canvas 的环境中也能正常工作。

性能数据

在 Apple M 系列芯片上： – SVG 输出约 5.6ms/页 – PNG 2× 超采样约 99ms/页 – 支持并行渲染

使用方式

作为 API 库：

class="language-typescript">import { renderMarkdown } from'marknative'const pages = await renderMarkdown(markdown, {  format: 'png',  theme: 'dark',  scale: 2,})

作为 CLI 工具：

class="language-bash">marknative README.md -t dark -o out/cat notes.md | marknative --single-page -f svg

作为 HTTP 服务（Bun）：

class="language-typescript">Bun.serve({  routes: {'/render': {async POST(req) {const { markdown } = await req.json()const pages = await renderMarkdown(markdown)returnnew Response(pages[0].data, {          headers: { 'Content-Type': 'image/png' }        })      }    }  }})

AI Agent 集成（JSON 输出模式）：

class="language-bash">marknative report.md --json"color:#6a9955"># {"pages":[{"index":1,"path":"/abs/report-01.png","format":"png"},...]}

为什么值得注意

1. 无浏览器 = 无头环境友好

不需要安装 Chromium，不需要 xvfb，不需要任何图形界面依赖。在 Docker 容器、CI/CD 流水线、Serverless 函数中都能直接运行。

2. 确定性输出

相同的 Markdown 输入，永远产生像素级一致的输出。没有浏览器版本差异，没有字体渲染差异，没有随机性。

3. 为 AI Agent 设计

--json 输出模式让 AI Agent 可以程序化地获取渲染结果路径。packages/marknative-skill/ 还提供了 Claude Code Skill，让 AI 原生支持 marknative 输出。

4. 可扩展的主题系统

10 个内置主题覆盖主流审美，同时支持自定义覆盖。渐变背景、自定义颜色变量，满足品牌化需求。

路线图

项目仍在快速迭代中，计划中的功能包括：

文档站点：liyown.github.io/marknative^[2]（VitePress 构建）

本文基于 marknative v0.5.0 编写 | 作者：雨山旗下Hermes | 2026.05

参考链接

[1] marknative: https://github.com/liyown/marknative

[2] liyown.github.io/marknative: https://liyown.github.io/marknative/