墨线 · Markdown 排版

命令行的 Markdown 排版引擎,一条命令出成品。

已上线 效率工具 macOS / Linux / Windows 版本 0.9.4 更新于 2026-09-06

写作工具分两类:一类让你在写作时调格式,一类让你写完再排版。 混在一起的结果是,写到一半开始纠结行距,正事反而被搁置。

墨线只做后一半:输入 Markdown,输出排好版的成品。 模板、字体、页边距、代码高亮、中英文混排间距都在配置里定死, 写作时只管内容,出稿时一条命令。

为什么不用 Word 或在线文档?因为它们把“写”与“排”绑在一起, 而且产物不可控:换一台机器打开,字体、分页、行距都可能变。 Markdown + 一套固定的排版规则,产物每次一模一样,还能进 Git 看改动。 代价是你得接受“先写完再排版”这个顺序——而这正是它想让你做的事。

安装部署

前置要求:Node.js ≥ 18(自带 npm)。导出 PDF 时依赖本机中文字体,字体缺失会退回默认字体。

方式一 · npm 全局安装(推荐)

npm install -g moxian
moxian --version

装完在任意目录可用。全局安装的好处是终端里随处能调,适合当作日常工具。

方式二 · npx 免安装试一次

不想污染全局环境时,用 npx 临时拉起来跑一次。

npx moxian build ./docs

每次执行都会检查版本,第一次会慢一些。适合验证效果,不适合长期使用。

方式三 · 源码构建(要改模板时用)

git clone https://github.com/limaosou/moxian.git
cd moxian
npm install
npm run build
npm link        # 把本地版本挂到全局命令

npm link 之后改源码、重新 build 即生效,适合调模板与排版规则。

方式四 · 装进项目,随 CI 跑

npm install -D moxian
# package.json
"scripts": { "docs": "moxian build docs", "lint:md": "moxian build docs --lint" }

锁在项目里可以固定版本,团队与 CI 产出完全一致。

装好之后先自检

装完别急着用,先跑一遍这 6 项。任何一项不对,说明环境或权限还没到位。

  • moxian --version 能打出版本号。
  • 对任意一个含中文的 Markdown 文件跑一次 build,输出的 HTML 里中英文之间有间距。
  • 加 --lint 跑一次,能对不合规的标点或缩进报出问题。
  • 导出 PDF 后检查字体不是宋体默认值(说明字体配置生效)。
  • 打开产出的 HTML,样式是内联的——把它单独拷到另一个目录,排版不变。
  • 故意在源文件里删掉一级标题再跑一次,--lint 能报出标题层级异常。

前台使用

三条主要命令

moxian build <目录或文件>     # 构建,输出 HTML / PDF
moxian build <路径> --lint        # 只检查排版,不产出文件
moxian build <路径> --pdf         # 额外导出 PDF

参数可以叠加,例如 moxian build docs --pdf --lint。

输出物长什么样

默认在源目录旁生成 dist/:每个 Markdown 对应一个 HTML,样式内联,不依赖外部 CSS,单文件可直接发给别人。加 --pdf 时同名 PDF 一起产出。

中文排版默认值

中英文之间自动留四分之一空隙、标点避头尾、段落首行不缩进、标题层级按中文习惯收敛字号。这些默认值就是它存在的理由——不用每次重新调。

为什么是四分之一字:比一个空格窄,比粘死宽,接近纸书里中英混排的视觉节奏。直接打空格会变成一个全角宽度,中英混排时出现一段一段的空洞;不处理则汉字与拉丁字母贴在一起,辨识成本变高。

标点避头尾:行首不出现逗号句号、行尾不出现左引号左括号。浏览器默认不处理这件事,中文长文里很容易出现孤零零的标点开行,看着像排版事故。

目录与锚点

模板会按标题层级自动生成目录,每个标题带稳定锚点,可以直接把链接发给别人定位到某一节。

目录深度默认到二级,层次太深(到五级)会让目录比正文还长。标题里尽量别用括号与特殊符号——它们会进锚点,粘贴出去的链接容易在聊天工具里被截断。

图片与表格

图片按相对路径引用,构建时原样拷贝到输出目录,不压缩也不转格式。好处是不失真,代价是图片大的话产物也大,发布前自己压一轮。

表格默认按内容宽度自适应,列多时会横向滚动。列宽想固定就在表格前的段落里加说明,或者干脆拆成两张表——中文表格一列超过四五个字就开始挤。

后台与设置

配置文件

项目根目录放一个 moxian.config.json,就近生效;没有配置文件时用内置默认值。常用字段:

  • output:输出目录,默认 dist。
  • spacing:中英文间距、标点挤压开关。
  • typography:正文字体、字号、行高、页宽。
  • code:代码高亮主题与行号。
  • pdf:纸张大小、页边距、页眉页脚。

模板

模板决定 HTML 骨架。内置一套干净的文档模板;要换版式时把模板目录复制出来改,再用配置指过去。模板里能用到的变量包括标题、目录、正文、生成时间。

在 CI 里当守门员

把 moxian build docs --lint 放进 CI 的检查步骤,标点用错、中英文混排没空格、标题跳级都会让构建失败。规则可以在配置里降级成警告,避免一上来拦住所有提交。

刚接入时建议先把规则全设为警告,跑一周看哪些是真问题,再逐条改成错误。一股脑全开,第一个 PR 就会被拦,团队很快就把它关掉了。

字体管理

HTML 输出用系统字体栈,PDF 输出必须能找到真实字体文件。两边的差异是 PDF 出问题最常见的原因。

  • 本机导出:先确认系统里装了配置中写的字族,名字要完全一致(中文包常见“思源宋体”与“Source Han Serif”两种叫法)。
  • 服务器导出:Docker 镜像里默认没有中文字体,需要单独装一次并刷新字体缓存。
  • 字体子集:中文全字库动轧十几 MB,PDF 会内嵌字体,体积大是正常的。

使用帮助

只当排版检查器用

已有自己的构建流程时,用 --lint 就够了:它只检查不产出,把问题打到终端,退出码非 0 可用于 CI 判断。

交付报告怎么出 PDF

报告类文档建议单独建一个目录并配一份 moxian.config.json:纸张 A4、页边距 20mm、加页脚页码。跑 moxian build report --pdf 一步到位。

字体不对怎么办

PDF 走的不是浏览器渲染,字体必须在系统里存在。Linux 服务器上先装中文字体(如 Noto Sans CJK),再把配置里的字体族改成已安装的那个名字。

装完字体记得刷新缓存,否则程序仍说找不到;容器环境里字体要写在镜像里,不能靠手动装。

批量迁移已有文档

手上一堆散落的 Markdown 时,直接对目录跑一次构建,看哪些文件报错——报错的就是格式不规范、值得逐个修的那几份。

  1. 把文档收进一个目录,保持原文件名。
  2. 先跑 --lint 拿到问题清单,不急着改。
  3. 按问题类型批量修(标题层级、空格、标点),一次只处理一类。
  4. 最后跑一次完整构建,检查目录与交叉链接是否正常。

写长文档时的目录拆分

一份几万字的手册不要塞进单个文件。按章节拆成多个 Markdown,父目录一份入口文件做索引,构建时以目录为单位输出。

好处是改动范围小、Git 历史干净,多人同时写也不会互相冲突。拆完记得检查交叉链接——文件改名是链接失效的第一大原因。

几个真实用法

场景怎么做
技术文档仓库里的 Markdown 直接出成风格统一的文档站,不用维护模板。
交付报告客户要 PDF 时一条命令导出,字体与版式一致。

常见问题

必须写配置文件吗?

不必。零配置即可构建,需要定制时再逐步添加 moxian.config.js。

问题解决

先按下面的顺序自查一遍,九成问题能在三步内定位,再往下才是具体现象的对照表。

  1. 确定范围:只有这一台设备/这一个页面出问题,还是全部都这样。只在一处出现,基本是环境或权限;全都这样,先怀疑版本与配置。
  2. 看最先报错的地方:前台报错的原文、浏览器控制台的第一行红字、后台日志里最早的那一条,比最后一条有用。
  3. 退回默认:关掉自己加的配置或与其他插件/脚本的冲突项,用默认设置复现一次。默认能用,问题就在改动里。
现象原因处理
中文与英文之间的间距不对模板里未启用中英混排规则,或源文件里混入了全角空格。检查模板的中英混排开关;源文件统一用半角空格与半角标点。
导出后字体变成默认字体模板指定的字体在本机未安装。安装对应字体,或把模板字体改为本机已有的字族。
命令找不到 moxian全局安装后 PATH 未刷新,或用了 nvm 但切换了 Node 版本。重开终端;nvm 用户在当前版本下重新 npm i -g,或改用 npx。
构建成功但输出目录是空的传入的路径不是 Markdown 目录,或输出目录被配置写到了别处。先对单个 .md 文件跑一次;再看配置里的 output 实际指到哪里。
PDF 里中文变方块系统或容器里没有中文字体,或字体族名写错。装 Noto Sans CJK 等中文字体并刷新字体缓存;配置里用系统的真实字族名。
--lint 报了一堆历史问题旧文档没有按规则写,第一次接入必然全红。先把规则降为警告,按目录分批清理;清完一个目录再把它设为错误。
同一份源文件,两台机器输出不一样版本不一致,或字体环境不同。把版本锁进 package.json,用 npm ci 装依赖;PDF 场景还要统一字体。
生成的 HTML 样式丢了模板改坏,或把产物里的内联样式手动抽成了外部文件。恢复默认模板重建一次;要外链样式需同时修改模板中的引用路径。

以上之外的问题,带上产品名、版本号、报错原文、操作步骤反馈到 hi@qinghuali.com,四项齐了基本一次能定位。

能力边界

这一节比功能列表更值得先看——它决定了你会不会在错误的场景里浪费时间。

  • 不做所见即所得编辑,不提供图形界面。
  • 不托管内容,输出文件在你本地,没有云端同步。
  • 复杂版式(多栏、图文绕排)需要改模板,纯 Markdown 语法表达不了。
  • PDF 的字体依赖本机或容器内已安装的字体,找不到就回退默认字体,不会自动下载。
  • 只做排版与检查,不校对内容:错别字、事实错误、逻辑不通都不在它的职责范围。
  • 不提供在线预览服务,预览靠浏览器打开产出的 HTML。

版本记录

版本日期变更
0.9.42026-09-06支持自定义字体子集,导出 PDF 体积下降约 40%。