docmd：零配置 Markdown 文档生成器

写过技术文档的人大多经历过这样的场景：手里有一堆 Markdown 文件，只想把它们变成一个能搜索、能被搜索引擎收录、能部署到任意静态托管平台的文档站，却不得不先花半天时间配置 Docusaurus 的 docusaurus.config.js、VitePress 的 config.mts 或者 MkDocs 的 mkdocs.yml。docmd 的目标就是消除这道门槛——它把"Markdown 文件夹"到"生产级文档站"的距离压缩到一条命令。

项目托管在 GitHub（docmd-io/docmd），采用 MIT 许可证，完全开源免费。它的核心主张只有三句话：零配置、AI 原生、为开发者构建。

docmd 解决什么问题

当前主流的文档生成器大体分两类：一类是基于框架的（Docusaurus 基于 React、VitePress 基于 Vue、Starlight 基于 Astro），一类是轻量的（MkDocs Material、Hugo 等）。前者能力强大但客户端 JavaScript 负载沉重——Docusaurus 在 50 页文档站上初始 JS 载荷约 250KB；后者虽然轻，但配置项和插件系统仍有学习成本。

docmd 选择了一条中间路线：不绑定任何前端框架，输出纯静态 HTML，客户端 JS 仅约 18KB，同时把现代文档站需要的搜索、SEO、多语言、版本控制、AI 上下文生成等功能做成开箱即用的内置能力。

官方给出的对比数据（50 页文档站）：

注：数据来源 docmd 官方对比页。

对于读者端，每 100KB JavaScript 在中端手机上约增加 50ms 解析时间。docmd 的 18KB 意味着即使在 3G 网络下文档也能瞬时打开，而 Docusaurus 为相同内容发送的 JS 是其 16 倍。

核心特性

零配置启动

在任意包含 Markdown 文件的目录下执行：

npx @docmd/core dev

docmd 会自动扫描 docs/ 目录的文件结构，生成嵌套导航侧边栏，并启动开发服务器（默认 http://localhost:3000）。不需要 docmd.config.js、不需要 frontmatter、不需要学习框架概念。

对于永久性项目，建议本地安装并初始化配置以锁定版本：

npm install @docmd/core
npx docmd init
npx docmd dev

生产构建与部署

npx @docmd/core build

build 命令输出高度优化的静态站点（默认输出到 site/ 目录），可直接部署到 Vercel、Cloudflare Pages、Netlify、GitHub Pages 或任何静态托管平台。构建产物包含：

• 纯静态 HTML（无框架运行时、无 hydration gap）

• 自动生成的 sitemap.xml、canonical URL、robots.txt、.nojekyll

• Open Graph 元数据

• 内置离线全文搜索（基于 MiniSearch，无需 Algolia 等云服务）

• PWA 支持（可安装到主屏幕、离线访问）

• 自动生成的 llms.txt 和 llms-full.txt

AI 原生能力

这是 docmd 区别于传统文档生成器的关键设计。它把"让 AI 能读你的文档"作为一等公民特性：

• llms.txt / llms-full.txt：构建时自动生成，为 LLM 提供完整的文档上下文文件

• MCP Server：执行 docmd mcp 启动基于 stdio 的 MCP 服务，Claude Desktop、Cursor、VS Code 里的 AI 智能体可以直接搜索、读取、校验你的文档内容

• Agent Skills：docmd init 会在项目中创建 SKILL.md 指令文件，供编码智能体使用

• Copy Markdown / Copy Context 按钮：文档页面内置浏览器按钮，为 AI 聊天优化

原生版本控制与多语言

版本控制和 i18n 是文档站的硬需求，docmd 把它们做成零配置的原生能力：

const { defineConfig } = require('@docmd/core');
module.exports = defineConfig({
  versions: {
    current: 'v2',
    all: [
      { id: 'v2', dir: 'docs' },
      { id: 'v1', dir: 'docs-v1' }
    ]
  },
  i18n: {
    default: 'en',
    locales: [
      { id: 'en', label: 'English' },
      { id: 'zh', label: '中文' }
    ]
  }
});

内置支持英语、印地语、中文、西班牙语、德语、日语、法语，其他语言可轻松扩展。

i18n 的实现细节值得一说：当读者切换到某个未翻译的语言时，docmd 在构建时处理回退——不可用的语言环境显示"N/A"徽章，未翻译的页面静默回退并带有本地化的警告标注。这避免了 VitePress 和 Docusaurus 在那里的常见 404 问题。

多项目支持

对于在一个域名下维护多个子项目文档的团队，docmd 支持原生多项目：

module.exports = defineConfig({
  projects: [
    { prefix: '/', src: 'main-docs' },
    { prefix: '/sdk', src: 'sdk-docs' }
  ]
});

每个项目可以独立版本化、独立 i18n、共享资源，输出到单一站点目录，无需反向代理。

项目结构

docmd 保持仓库整洁：

my-docs/
├── docs/              # Markdown 文件
├── assets/            # 图片和自定义 JS/CSS
├── docmd.config.js    # 配置文件（可选）
└── package.json

内容放在 docs/，配置放在 docmd.config.js。没有任何强制的模板文件或脚手架。

使用方式

方式一：npx 直接运行（推荐尝鲜）

npx @docmd/core dev

方式二：全局安装

npm install -g @docmd/core
docmd dev      # 启动开发服务器
docmd build    # 构建生产站点

方式三：Docker

docker run -p 3000:3000 ghcr.io/docmd-io/docmd:latest docmd dev

也可固定版本以保证可复现构建：

docker run -p 3000:3000 ghcr.io/docmd-io/docmd:0.8.7

方式四：项目依赖

npm install @docmd/core --save-dev

在 package.json 中添加脚本：

{
  "scripts": {
    "docs:dev": "docmd dev",
    "docs:build": "docmd build"
  }
}

常用命令一览

可选插件

核心功能无需插件即可工作，需要扩展时可通过插件系统添加：

安装可选插件：

docmd add search
docmd add mcp

适用场景

docmd 适合以下几类需求：

• 个人项目或开源项目文档：不想折腾配置，追求快速上线

• SDK / API 文档多项目管理：一个仓库管理多个产品的文档，各自独立版本控制

• 多语言文档站：需要真正可用的 i18n，而不是会 404 的半成品

• AI 智能体需要读取的文档：希望通过 MCP 或 llms.txt 让 AI 直接访问文档内容

• 对性能敏感的文档站：客户端 JS 极小，3G 网络下也能秒开

不适用场景

客观地看，docmd 并不是万能的：

• 需要复杂交互组件：docmd 严格执行标准 Markdown + HTML，不支持 MDX，无法在 Markdown 里直接导入 React 组件。如果需要复杂的交互式文档，Docusaurus 仍是更好的选择

• 深度主题定制：内置主题（default、sky、ruby、retro）和自定义 CSS 能满足大多数需求，但如果要大幅改变布局（例如把侧边栏移到右侧），需要手写 CSS 覆盖

• 庞大插件生态：docmd 项目相对年轻，插件生态远不如 Docusaurus 或 MkDocs Material 丰富。不过搜索、SEO、Mermaid、PWA、OpenAPI 等常用功能已内置

• 非 Node.js 工具链：docmd 依赖 Node.js 18+，对纯 Python 或非 JS 工具链的团队会引入额外的环境依赖

• 项目成熟度：docmd 仍在快速迭代，版本间 API 可能有变动，长期维护的稳定性尚未经过足够长时间的验证

与其他工具的对比

官方给出的完整功能矩阵（部分）：

注：数据来源 docmd 官方对比页。

对于一个包含版本控制、多语言、搜索和站点地图的完整文档站，所需配置行数对比：

• docmd：~15 行（1 个文件）

• MkDocs Material：~50 行（1 个文件 + 插件）

• VitePress：~80 行（1 个文件 + 主题目录）

• Docusaurus：~120 行（3+ 个配置文件）

迁移支持

如果你已经在用其他文档工具，docmd 提供了迁移命令：

docmd migrate

支持从 Docusaurus、VitePress、MkDocs 一键迁移。这对于想从重型框架切换到轻量方案的团队是一个实际的退出通道。

部署

docmd 输出纯静态 HTML，可部署到任何静态托管平台。它还提供部署配置生成器：

docmd deploy --docker    # 生成 Dockerfile
docmd deploy --nginx     # 生成 Nginx 配置
docmd deploy --caddy     # 生成 Caddy 配置

GitHub Pages 用户可以使用官方提供的模板仓库，一键创建包含自动化 GitHub Actions 的预配置文档仓库。

写在最后

docmd 在 2026 年的文档生成器市场中找到了一个清晰的定位：为那些"只想要一个快速、轻量、能被 AI 读取的文档站"的开发者服务。它不试图取代 Docusaurus 在企业级复杂场景中的地位，也不试图在主题定制上与 VitePress 全面竞争。它的价值主张非常聚焦——把 Markdown 变成生产级文档站的过程压缩到一条命令，并且默认输出对搜索引擎友好、对 AI 智能体友好。

如果你手上有一堆 Markdown 文件，想给开源项目、SDK、内部工具搭一个文档站，又不想陷入框架配置的泥潭，docmd 值得作为首选评估对象。一条 npx @docmd/core dev 就能看到结果，不合适随时放弃，成本几乎为零。

项目地址：github.com/docmd-io/docmd

官网：docmd.io

文档：docs.docmd.io

许可证：MIT