# Pamphlet

> 把一份 Markdown 编译成一个能双击打开的 HTML 文件

## 开始

- [快速开始](https://lazygophers.github.io/pamphlet/start/quickstart.md): 跟着敲完这一页，你会得到一个能双击打开、断网也能看的 HTML 文件。 全程不需要安装任何东西。
- [简介](https://lazygophers.github.io/pamphlet/start/what-is-it.md): Pamphlet 把一份 Markdown 编译成一个能双击打开的 HTML 文件。 产物里没有 <link>、没有 <script src>、没有 CDN 引用。图表在编译时就画成静态 SVG 内联进去了，字体是子集化后的 data URI，图片是 base64。断网、file://、U 盘拷来拷去，行为完全一样。
- [安装](https://lazygophers.github.io/pamphlet/start/install.md): 不用装也能跑。 npx 是 npm 自带的一条命令，意思是「下载这个包、跑一次、不留在我电脑里」。第一次会花十几秒下载（实测 86 个依赖、15 秒），之后 npx 自己有缓存。

## 写作

- [写作总览](https://lazygophers.github.io/pamphlet/write/index.md): 这一页列全了 Pamphlet 认识的每一条语法。 左边的菜单和这张表是一一对应的：菜单上有的，这里就有；这里没有的，就是不支持。 源文档是标准的 .md，直接丢上 GitHub 仍然能读。
- [标题](https://lazygophers.github.io/pamphlet/write/text/headings.md)
- [段落与换行](https://lazygophers.github.io/pamphlet/write/text/paragraphs.md)
- [强调](https://lazygophers.github.io/pamphlet/write/text/emphasis.md)
- [行内代码](https://lazygophers.github.io/pamphlet/write/text/inline-code.md)
- [转义](https://lazygophers.github.io/pamphlet/write/text/escaping.md)
- [引用块](https://lazygophers.github.io/pamphlet/write/blocks/quote.md)
- [列表](https://lazygophers.github.io/pamphlet/write/blocks/lists.md)
- [代码块](https://lazygophers.github.io/pamphlet/write/blocks/code.md)
- [表格](https://lazygophers.github.io/pamphlet/write/blocks/table.md)
- [分隔线](https://lazygophers.github.io/pamphlet/write/blocks/rule.md)
- [指令怎么写](https://lazygophers.github.io/pamphlet/write/components/index.md): 五种能点、能跳出正文的东西，统称容器指令。它们是 Pamphlet 在标准 Markdown 之上加的部分。
- [提示块](https://lazygophers.github.io/pamphlet/write/components/callout.md)
- [标签页（Tab）](https://lazygophers.github.io/pamphlet/write/components/tabs.md)
- [折叠块](https://lazygophers.github.io/pamphlet/write/components/collapse.md)
- [步骤](https://lazygophers.github.io/pamphlet/write/components/steps.md)
- [滚动入场](https://lazygophers.github.io/pamphlet/write/components/reveal.md)
- [流程图](https://lazygophers.github.io/pamphlet/write/diagrams/flowchart.md)
- [时序图](https://lazygophers.github.io/pamphlet/write/diagrams/sequence.md)
- [状态图](https://lazygophers.github.io/pamphlet/write/diagrams/state.md)
- [类图](https://lazygophers.github.io/pamphlet/write/diagrams/class.md)
- [实体关系图](https://lazygophers.github.io/pamphlet/write/diagrams/er.md)
- [甘特图](https://lazygophers.github.io/pamphlet/write/diagrams/gantt.md)
- [饼图](https://lazygophers.github.io/pamphlet/write/diagrams/pie.md)
- [架构图](https://lazygophers.github.io/pamphlet/write/diagrams/architecture.md)
- [系统上下文图（C4）](https://lazygophers.github.io/pamphlet/write/diagrams/c4.md)
- [数据流图](https://lazygophers.github.io/pamphlet/write/diagrams/dataflow.md)
- [思维导图](https://lazygophers.github.io/pamphlet/write/diagrams/mindmap.md)
- [git 分支图](https://lazygophers.github.io/pamphlet/write/diagrams/gitgraph.md)
- [块图](https://lazygophers.github.io/pamphlet/write/diagrams/block.md)
- [泳道图](https://lazygophers.github.io/pamphlet/write/diagrams/swimlane.md)
- [网络拓扑图](https://lazygophers.github.io/pamphlet/write/diagrams/topology.md)
- [数据图表](https://lazygophers.github.io/pamphlet/write/diagrams/chart.md)
- [组织架构图](https://lazygophers.github.io/pamphlet/write/diagrams/orgchart.md)
- [Mermaid（画图的引擎）](https://lazygophers.github.io/pamphlet/write/diagrams/mermaid/index.md)
- [流程图（Mermaid 围栏）](https://lazygophers.github.io/pamphlet/write/diagrams/mermaid/flowchart.md)
- [时序图（Mermaid 围栏）](https://lazygophers.github.io/pamphlet/write/diagrams/mermaid/sequence.md)
- [状态图（Mermaid 围栏）](https://lazygophers.github.io/pamphlet/write/diagrams/mermaid/state.md)
- [类图（Mermaid 围栏）](https://lazygophers.github.io/pamphlet/write/diagrams/mermaid/class.md)
- [实体关系图（Mermaid 围栏）](https://lazygophers.github.io/pamphlet/write/diagrams/mermaid/er.md)
- [甘特图（Mermaid 围栏）](https://lazygophers.github.io/pamphlet/write/diagrams/mermaid/gantt.md)
- [饼图（Mermaid 围栏）](https://lazygophers.github.io/pamphlet/write/diagrams/mermaid/pie.md)
- [架构图（Mermaid 围栏）](https://lazygophers.github.io/pamphlet/write/diagrams/mermaid/architecture.md)
- [系统上下文图（Mermaid 围栏）](https://lazygophers.github.io/pamphlet/write/diagrams/mermaid/c4.md)
- [数据流图（Mermaid 围栏）](https://lazygophers.github.io/pamphlet/write/diagrams/mermaid/dataflow.md)
- [思维导图（Mermaid 围栏）](https://lazygophers.github.io/pamphlet/write/diagrams/mermaid/mindmap.md)
- [git 分支图（Mermaid 围栏）](https://lazygophers.github.io/pamphlet/write/diagrams/mermaid/gitgraph.md)
- [块图（Mermaid 围栏）](https://lazygophers.github.io/pamphlet/write/diagrams/mermaid/block.md)
- [其余七个引擎](https://lazygophers.github.io/pamphlet/write/diagrams/others.md): Mermaid 内置在 Pamphlet 里，其余七个各自是一个包，用到哪个装哪个。不装的人一个字节都不多——七个全装约 340MB，其中 d2 一个就 91.4MB。 每一种一页，点上表第一列进去：那一页写清它是什么、能画哪些图、围栏里怎么写、有什么坑。 没装就用那种围栏会得到 DIAG-301 并且整次编译失败（不是留个占位框），提示里就是上表第三列那条命令。pamphlet doctor 一次列全七个装了没有。
- [d2](https://lazygophers.github.io/pamphlet/write/diagrams/d2/index.md)
- [Graphviz](https://lazygophers.github.io/pamphlet/write/diagrams/dot/index.md)
- [MathJax](https://lazygophers.github.io/pamphlet/write/diagrams/math/index.md)
- [Vega-Lite](https://lazygophers.github.io/pamphlet/write/diagrams/vega-lite/index.md)
- [WaveDrom](https://lazygophers.github.io/pamphlet/write/diagrams/wavedrom/index.md)
- [bytefield-svg](https://lazygophers.github.io/pamphlet/write/diagrams/bytefield/index.md)
- [PlantUML](https://lazygophers.github.io/pamphlet/write/diagrams/plantuml/index.md)
- [图片与资源](https://lazygophers.github.io/pamphlet/write/diagrams/images.md): 图片、字体全部内嵌进产物 —— 图片编码成 base64，字体子集化后写成 data URI。所以产物拷到哪里都完整。
- [裸 HTML](https://lazygophers.github.io/pamphlet/write/html.md)

## 指南

- [在 CI 里检查文档](https://lazygophers.github.io/pamphlet/howto/ci.md): 目标：有人改坏了源文档，在合并之前就发现，而不是等到编译的时候。 用 pamphlet lint —— 它只检查语法、报诊断，不产出任何文件。 退出码非 0 就是有问题，CI 直接据此判断，不必解析输出。
- [换一套主题色](https://lazygophers.github.io/pamphlet/howto/theme.md): 先看够不够用：内置主题按文档类型分，各有独立的配色和版式，一行就能换。 这一页讲的是内置主题不够用时怎么微调 —— 往源文档里写一段 <style> 覆盖 CSS 变量。两条路可以叠加：先选一套主题，再盖掉其中一两个值。
- [让 AI 帮你写 Pamphlet 文档](https://lazygophers.github.io/pamphlet/howto/ai-skills.md): 仓库里有三份写给 AI 看的说明书（skill）。装上之后，AI 助手写 Pamphlet 文档时会自己把它们读进去——不用你每次粘一遍语法。 这条命令会列出三份让你挑，装到当前项目的 .claude/skills/。装到全局（所有项目都能用）加 -g。
- [接一个自定义图表引擎](https://lazygophers.github.io/pamphlet/howto/custom-engine.md)

## 参考

- [命令行](https://lazygophers.github.io/pamphlet/reference/cli/index.md): 没装的话前面加 npx @nekoleapuki/pamphlet-cli，例如 npx @nekoleapuki/pamphlet-cli build 方案.md。
- [build](https://lazygophers.github.io/pamphlet/reference/cli/build.md): 编译成单文件 HTML。 产物默认写在源文档旁边：方案.md → 方案.html。
- [serve](https://lazygophers.github.io/pamphlet/reference/cli/serve.md): 本地预览，源文档改了就自动重新编译并刷新页面。 刷新走 SSE（Server-Sent Events，服务器主动往浏览器推消息的一种标准做法），不需要你手动按刷新。
- [lint](https://lazygophers.github.io/pamphlet/reference/cli/lint.md): 只检查语法、报诊断，不产出任何文件。
- [ast](https://lazygophers.github.io/pamphlet/reference/cli/ast.md): 打印这份文档解析出来的语法树。 输出 { path, frontmatter, ast, diagnostics } 的 JSON 到标准输出。 一次只接一个文件，匹配到多个会报错退出 2。
- [extract](https://lazygophers.github.io/pamphlet/reference/cli/extract.md): 从产物里把源文档原样吐回来。 源文档默认内嵌在产物的 HTML 注释里，所以产物即备份 —— 只剩一个 HTML 文件也能把 .md 拿回来。
- [doctor](https://lazygophers.github.io/pamphlet/reference/cli/doctor.md): 逐个图表引擎打印装了没有、怎么装。 装好了： 没装： 缺任何一个引擎退出码是 3（环境缺失），不是 1。分开是为了让 CI 能区分「文档写错了」和「机器上没装东西」。
- [frontmatter 参考](https://lazygophers.github.io/pamphlet/reference/frontmatter.md): 没有配置文件。 全部配置都写在源文档开头的 frontmatter 里 —— 那两行 --- 中间的部分。 这么定的理由是：一份源文档 = 一个产物，配置跟着文档走，拷贝文档就等于拷贝配置。多一个配置文件就多一处「文档在这、设置在那」的脱节。
- [内置主题](https://lazygophers.github.io/pamphlet/reference/themes.md): 内置主题按文档类型分，不按审美分。每套都是独立的配色和版式 —— 正文宽度、标题体系、提示块形态、Tab 形态、表格线各不相同。 或者写进源文档，让它跟着文档走： --theme 压过 frontmatter。 命令行是「这一次编译」的意图，frontmatter 是「这份文档一贯的样子」—— 一次性的意图应该能盖过长期设定。 名字写错报 DOC-106，退回 default 继续编译：主题错了只影响长相，内容是对的。
- [主题 token 清单](https://lazygophers.github.io/pamphlet/reference/theme-tokens.md): 三层结构见 ADR-0020：语义层是根，元素层默认从语义层派生，作者只写想改的。 怎么改见换一套主题色。
- [诊断码表](https://lazygophers.github.io/pamphlet/reference/diagnostics.md): 每条诊断都带位置、原因和修复建议，底下那行链接就指向本页对应的锚点。

## 设计

- [产物是什么样的](https://lazygophers.github.io/pamphlet/design/output.md): 一本 pamphlet 是一个 HTML 文件，里面有五段东西：骨架、样式、正文 HTML、内联的图表 SVG、一小段运行时 JavaScript。外加一段把源文档原样存起来的 HTML 注释。 跑 pamphlet build --verbose 能看到各段占多少字节。
- [方案对比](https://lazygophers.github.io/pamphlet/design/compare.md): 只比两个真正接近的：Pandoc 和 Typora / Obsidian 的导出 HTML。 不比 VitePress、mdBook、Docusaurus 这类 —— 它们产出的是一个网站（几百个文件，要有服务器或 GitHub Pages 才能看），Pamphlet 产出的是一个文件（双击就开）。这不是同一类东西，比较没有意义。

## 常见问题

- [常见问题](https://lazygophers.github.io/pamphlet/faq.md)

## Others

- [Domain Docs](https://lazygophers.github.io/pamphlet/agents/domain.md): How the engineering skills should consume this repo's domain documentation when exploring the codebase. This repo is single-context: one CONTEXT.md and one docs/adr/ at the repo root, shared across all packages. Even though packages/* is a pnpm workspace, the packages share one glossary and one decision log.
- [Issue tracker：本地 markdown](https://lazygophers.github.io/pamphlet/agents/issue-tracker.md): 票是 markdown 文件，存在 .scratch/issues/ 下，按开着还是做完了分两个目录： 一张票一个文件，文件名 NN-<短标题>.md。 2026-09-14 从 GitHub Issues 换回来的（此前 2026-09-11 从本地换去过 GitHub）。 换回来时把 GitHub 上那 48 张票连同全部评论导出到了 done/ 和 open/， GitHub 上的原票没有删，还在 https://github.com/lazygophers/pamphlet/issues。