## 快速开始
在任何包含 Markdown 文件的目录下直接运行 docmd —— 无需安装：
```bash
npx @docmd/core dev
```
在 http://localhost:3000 打开
```bash
_ _
_| |___ ___ _____ _| |
| . | . | _| | . |
|___|___|___|_|_|_|___|
v1.x.x
┌─ Build
│ Engine JS
│ Source docs/
│ Output site/
│ Versions 2 (06, 05)
│ Locales 7 (en, hi, zh, es, de, ja, fr)
└──────────────────────────────────────────────────────────
┌─ Data Indexing
│ [ DONE ] Syncing git metadata
│ [ DONE ] Building semantic search index (multi-version)
└──────────────────────────────────────────────────────────
┌─ Publishing
│ [ DONE ] Generated robots.txt
│ [ DONE ] Generated .nojekyll (disables Jekyll on GitHub Pages)
│ [ DONE ] Generated sitemap
│ [ DONE ] Generating LLMs context files
└──────────────────────────────────────────────────────────
⬢ Initial build completed in 1.2s.
┌─ Watching
│ Source ./docs
│ Config ./docmd.config.json
│ Assets ./assets
└──────────────────────────────────────────────────────────
┌─ Development Server Running
│ Local Access http://127.0.0.1:3000
│ Network Access http://192.168.1.6:3000
│ Serving from ./site
└──────────────────────────────────────────────────────────
```
导航由你的目录结构自动生成。无需配置文件、不强制 frontmatter、不必学习框架。
**当准备发布时：**
```bash
npx @docmd/core build
```
这会输出一个高度优化的静态站点（SPA），可直接部署到 Vercel、Cloudflare Pages、Netlify、GitHub Pages 或任何静态主机。
**环境要求：** Node.js 18+
或全局安装 / 通过 Docker
```bash
# 通过 npm 全局安装
npm install -g @docmd/core
# 或通过 pnpm
pnpm add -g @docmd/core
# 运行
docmd dev # 启动开发服务器
docmd build # 构建用于部署
```
或通过 Docker 运行：
```bash
docker run -p 3000:3000 ghcr.io/docmd-io/docmd:0.8.7
```
> 固定一个版本以获得可复现的构建。
## 为什么选择 docmd？
| 特性 | docmd | Docusaurus | MkDocs | VitePress | Mintlify |
| :--- | :---: | :---: | :---: | :---: | :---: |
| **需要配置** | **无需** | `docusaurus.config.js` | `mkdocs.yml` | `config.mts` | `docs.json` |
| **JS 体积** | **~18 kb** | ~250 kb | ~40 kb | ~50 kb | ~120 kb |
| **导航** | **即时 SPA** | React SPA | 全量重载 | Vue SPA | 托管 SPA |
| **版本管理** | **原生** | 原生（复杂） | mike 插件 | 手动 | 原生 |
| **i18n** | **原生** | 原生（复杂） | 插件方式 | 原生 | 原生 |
| **多项目** | **原生** | 插件 | 插件 | - | - |
| **搜索** | **内置** | Algolia（云） | 内置 | MiniSearch | 云 |
| **AI 上下文 (`llms.txt`)** | **内置** | - | - | - | 内置 |
| **MCP 服务器** | **内置** | - | - | - | 内置 |
| **Agent Skills** | **内置** | - | - | - | - |
| **Docker 镜像** | **官方** | - | 官方 | - | - |
| **自托管** | **可** | 可 | 可 | 可 | - |
| **费用** | **免费 (OSS)** | 免费 (OSS) | 免费 (OSS) | 免费 (OSS) | Freemium |
## 功能特性
### 零配置，即时启动
把 docmd 指向任意 Markdown 目录，它就会运行。导航会根据你的目录结构自动生成。你可以在不到一分钟的时间内写好第一篇文档并上线 —— 没有模板代码，没有需要配置的构建流程，也不需要提前做技术决策。
### 默认轻量，处处高速
默认的 JavaScript 体积约 18 kb，页面以即时 SPA 的方式切换。输出为静态 HTML —— 已做好 SEO 优化，包含 sitemap、canonical URL 与 Open Graph 元数据。内置离线全文搜索，无需任何云服务。
### AI 原生
docmd 的设计贴合文档在当今被阅读与使用的方式：
- **MCP 服务器** — `docmd mcp` 通过 stdio 把你的文档暴露给 AI Agent，让它们可以直接搜索、阅读并校验内容。
- **上下文 (`llms.txt` / `llms-full.txt`)** — 在构建时生成完整的文档上下文，可被任何 LLM 立即消费。
- **Agent Skills** — 面向 LLM 与 IDE Agent 的模块化指令集合（[docmd-skills](https://github.com/docmd-io/docmd-skills)）。
- **复制为 Markdown / 复制上下文** — 浏览器内一键按钮，专门为粘贴到 AI 对话中做了优化。
### 为规模化而生
- 通过多语言构建实现国际化
- 支持多个文档版本的版本管理
- 面向 monorepo 与多项目场景的 Workspaces
- 用于扩展核心行为的插件体系
- 完整的 Theming 支持、内置模板、自定义 CSS/JS，以及浅色 / 深色模式
## CLI
```bash
docmd dev # 本地开发服务器
docmd build # 构建用于部署
docmd live # 浏览器端在线编辑器
docmd migrate # 从 Docusaurus / VitePress / MkDocs / Starlight 导入
docmd deploy # 生成 Docker / NGINX / Caddy / Vercel / Netlify 配置
docmd validate # 检查全部内部链接
docmd mcp # 以 MCP 服务器方式在 stdio 上运行
docmd add # 安装插件或模板
```
## 插件
核心功能由一套稳健的插件系统驱动。基础能力默认已包含，特定需求可加装可选插件。
| 插件 | 状态 | 描述 |
| :--- | :---: | :--- |
| `search` | ✅ 核心 | 带模糊匹配的离线全文搜索 |
| `seo` | ✅ 核心 | SEO 标签与 Open Graph 元数据 |
| `sitemap` | ✅ 核心 | 生成 `sitemap.xml` |
| `git` | ✅ 核心 | Git 提交历史与最后更新时间 |
| `analytics` | ✅ 核心 | 轻量级分析集成 |
| `llms` | ✅ 核心 | AI 上下文生成（`llms.txt` / `llms-full.txt`） |
| `mermaid` | ✅ 核心 | Mermaid 图表支持 |
| `openapi` | ✅ 核心 | 构建期 OpenAPI 3.x 规范渲染器 |
| `pwa` | ➕ 可选 | Progressive Web App —— 离线导航 |
| `threads` | ➕ 可选 | 内联讨论串 *(by @svallory)* |
| `math` | ➕ 可选 | KaTeX / LaTeX 数学公式渲染 |
安装可选插件：
```bash
docmd add
```
开发你自己的插件：[插件开发指南](https://docs.docmd.io/development/building-plugins/)
## 配置
上手无需任何配置。仅在需要更多控制时，在项目根目录添加 `docmd.config.json`（或 `.ts` / `.js`）：
```json
{
"title": "我的项目",
"url": "https://docs.myproject.com",
"src": "./docs",
"out": "./dist"
}
```
TypeScript 与 JavaScript 格式的配置文件支持动态值。
完整参考：[配置概览](https://docs.docmd.io/configuration/overview)
## 项目结构
```text
my-docs/
├── docs/ ← 你的 Markdown 文件
├── assets/ ← 图片与静态资源
├── docmd.config.json ← 可选配置
└── package.json
```
## 在线编辑器
基于浏览器的编辑器，所见即所得地撰写并预览文档 —— 无需任何本地配置。
**前往 [live.docmd.io](https://live.docmd.io) 体验**
## 编程式 API
在 Node.js 脚本、CI 流水线或自定义构建步骤中使用 docmd。（同时支持 CommonJS 与 ESM。）
```javascript
import { build } from '@docmd/core';
await build('./docmd.config.json', { isDev: false });
```
完整参考：[Node API](https://docs.docmd.io/development/node-api-reference/)
## 社区
- **Bug 与问题** → [GitHub Issues](https://github.com/docmd-io/docmd/issues)
- **问题与想法** → [Discussions](https://github.com/orgs/docmd-io/discussions)
- **参与贡献** → [CONTRIBUTING.md](.github/CONTRIBUTING.md)
- **路线图** → [GitHub Discussions](https://github.com/orgs/docmd-io/discussions/2)
## 支持我们
- 让更多人知道 docmd 是支持其开发最直接的方式 —— 在 X 上 [分享给你的朋友](https://twitter.com/intent/tweet?url=https://github.com/docmd-io/docmd&text=docmd%20-%20几秒内从%20Markdown%20生成生产可用的文档站点。)，或点个 Star。
- 如果 docmd 节省了你的时间，[GitHub Sponsorship](https://github.com/sponsors/mgks) 是巨大的鼓励。
- 有想法或发现 Bug？欢迎提 Issue 或 PR，欢迎贡献你自己的插件。
## 许可
MIT —— 详见 [`LICENSE`](./LICENSE)。 
