markdown-formatter (mdf)

面向中文写作场景的格式化工具。它把中英文之间加上空格、按语境把半角标点转成全角、统一技术术语的大小写、统一 Markdown 标记风格——让中英夹杂的文档排版整齐、风格一致。

支持五种输入：Markdown、Jupyter Notebook (.ipynb)、纯文本、HTML (.html/.htm)、Vue 单文件组件 (.vue，仅 <template>)。

设计原则

这是一个保守的工具：宁可漏改，不可错改。格式化工具一旦错改一次，用户就会永久关掉它，所以在灰色地带 mdf 选择保持原样。同时保证幂等 (format(format(x)) === format(x))，并且永不触碰内容字节——代码块、公式、URL、frontmatter 只被排版，不被改写。

主要功能

• 中英文空格：中文与字母 / 数字之间自动补空格 (含 C++、C#、%、° 等符号词的护栏)
• 标点全角化：中文语境下半角标点按语境转全角，并有一整套护栏——缩写 (vs./e.g.)、时间 (16:32)、URL、HTML 实体、品牌叹号 (Yahoo!)、占位符 (%s/$1/\d) 不误伤；也支持反向 half-width 归一
• 引号风格：中文直引号统一为 “” 或 「」 (可关)
• 省略号 / 破折号：... → ……,-- → —— (中文语境)
• 术语大小写统一：按内置词典归一常见技术术语 (如 github → GitHub)，词典宁缺毋滥、可扩展 / 禁用
• Markdown 标记统一：列表符号、加粗 / 斜体标记、分隔线、缩进等序列化风格统一
• 逃生舱：<!-- mdf disabled --> / <!-- mdf-ignore --> 让用户对本工具有最终否决权
• 可选高级功能：用 Prettier 格式化代码块 (code.format,opt-in，异步)

安装

包管理器是 pnpm，需要 Node ≥ 18.17。

pnpm add -D markdown-formatter
# 或全局安装 CLI
pnpm add -g markdown-formatter

命令行用法

mdf <files|globs...>       # 格式化并写回文件
mdf --check <files...>     # 检查模式:不写回,存在未格式化文件时退出码为 1
mdf --diff <files...>      # 预览改动(彩色 unified diff,不写回)
mdf --stdin [--type md]    # 从标准输入读取,结果输出到标准输出
mdf init                   # 交互式生成 mdf.config.json

常用选项：

| 选项 | 说明 | | - | - | | --check | 只检查不写回 | | --diff | 预览改动 (隐含 --check 语义) | | --stdin | 从标准输入读取 | | --type <t> | stdin 输入类型：md | ipynb | text | html | vue (默认 md) | | --config <path> | 指定配置文件 | | --no-ignore | 不读取 .gitignore 与配置 ignore | | --no-lint | 不输出 lint 只读告警 | | -h, --help / -v, --version | 帮助 / 版本 |

默认遵循 cwd 下的 .gitignore;额外忽略可在配置文件的 ignore 字段 (gitignore 语法) 追加。

支持的文件类型：.md .markdown、.ipynb、.txt、.html .htm、.vue。

配置

在项目根放一个 mdf.config.json (也支持 .mdfrc.json 或 package.json 的 "mdf" 字段)。仓库内的 schema.json 提供编辑器自动补全。

{
  "$schema": "./node_modules/markdown-formatter/schema.json",
  "spacing": true,
  "punctuation": "full-width",
  "quotes": "“”",
  "ellipsis": true,
  "dash": true,
  "terminology": true,
  "markdown": {
    "bullet": "-",
    "emphasis": "*",
    "strong": "*",
    "math": true
  }
}

主要配置项：

• spacing：中英文 / 数字之间加空格 (默认 true)
• punctuation："full-width" (默认)/ "half-width" / false
• quotes："“”" (默认)/ "「」" / false
• ellipsis / dash：... → …… / -- → —— (默认 true)
• terminology：术语大小写归一，可传对象 { extend, disable } 扩展 / 禁用词条
• markdown.*:Markdown 标记风格与专属开关 (math / html / tableAlign)
• code.format:opt-in，用 Prettier 格式化代码块 (需异步 API + 可选依赖 Prettier)

完整字段见 schema.json。

编程接口

import { format, check, formatAsync, remarkMdf } from 'markdown-formatter'

// 同步(默认主路,零额外依赖)
const out = format(src, 'markdown', options)
const ok = check(src, 'markdown', options) // === format(...) === src

// 异步旁路,仅在启用 code.format 时需要
const out2 = await formatAsync(src, 'markdown', { code: { format: true } })

// 作为 remark 插件嵌入外部 unified 管道(VitePress / Docusaurus)
// unified().use(remarkParse).use(remarkMdf).use(remarkStringify)

type 取值：'markdown' | 'notebook' | 'text' | 'html' | 'vue'。

开发

pnpm test          # 跑全部测试(vitest)
pnpm typecheck     # tsc --noEmit
pnpm build         # tsup 产出 dist/
pnpm check         # 发布前全套门禁
pnpm demo          # 启动在线 playground(Vue)
pnpm docs:dev      # 启动文档站(VitePress)

判例法与设计信条见 docs/rules.md 与 docs/principles.md;贡献规则前请先阅读。

License

ISC