docmd-io--docmd/README.md at main

wehub/docmd-io--docmd

Fork 0

Files

T

wehub-resource-sync c0f6dae9db

docmd CI verification / verify (push) Waiting to run

Details

docs: make Chinese README the default

2026-07-13 10:21:16 +00:00

12 KiB

Raw Permalink Blame History

Note

本文档由 WeHub 基于上游 README 翻译整理，属于社区翻译，非官方中文文档。
English · 原始项目 · 上游 README
原作者、版权与许可证归属以原始项目及本仓库 LICENSE 文件为准。

^{EN | ES | DE | 日本語 | FR | 中文}

几秒内从 Markdown 生成生产可用的文档站点。
零配置。AI 原生。为开发者打造。

官网 · 文档 · 在线编辑器 · Agent Skills · 反馈 Bug

快速开始

在任何包含 Markdown 文件的目录下直接运行 docmd —— 无需安装：

npx @docmd/core dev

在 http://localhost:3000 打开

    _                 _
  _| |___ ___ _____ _| |
 | . | . |  _|     | . |
 |___|___|___|_|_|_|___|

 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、不必学习框架。

当准备发布时：

npx @docmd/core build

这会输出一个高度优化的静态站点（SPA），可直接部署到 Vercel、Cloudflare Pages、Netlify、GitHub Pages 或任何静态主机。

环境要求： Node.js 18+

或全局安装 / 通过 Docker

# 通过 npm 全局安装
npm install -g @docmd/core

# 或通过 pnpm
pnpm add -g @docmd/core

# 运行
docmd dev    # 启动开发服务器
docmd build  # 构建用于部署

或通过 Docker 运行：

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）。
复制为 Markdown / 复制上下文 — 浏览器内一键按钮，专门为粘贴到 AI 对话中做了优化。

为规模化而生

通过多语言构建实现国际化
支持多个文档版本的版本管理
面向 monorepo 与多项目场景的 Workspaces
用于扩展核心行为的插件体系
完整的 Theming 支持、内置模板、自定义 CSS/JS，以及浅色 / 深色模式

CLI

docmd dev            # 本地开发服务器
docmd build          # 构建用于部署
docmd live           # 浏览器端在线编辑器
docmd init           # 在当前目录生成新的 docmd.config.json
docmd stop           # 停止正在运行的 `docmd dev` / `docmd live` 服务器
docmd doctor         # 预检查: 配置 + 插件安装状态
docmd migrate        # 从 Docusaurus / VitePress / MkDocs / Starlight 导入
docmd deploy         # 生成 Docker / NGINX / Caddy / Vercel / Netlify 配置
docmd validate       # 检查全部内部链接
docmd mcp            # 以 MCP 服务器方式在 stdio 上运行
docmd add <name>     # 安装插件或模板

插件

核心功能由一套稳健的插件系统驱动。基础能力默认已包含，特定需求可加装可选插件。

插件	状态	描述
`search`	核心	带模糊匹配的离线全文搜索
`seo`	核心	SEO 标签与 Open Graph 元数据
`sitemap`	核心	生成 `sitemap.xml`
`git`	核心	Git 提交历史与最后更新时间
`analytics`	核心	轻量级分析集成
`llms`	核心	AI 上下文生成（`llms.txt` / `llms-full.txt`）
`mermaid`	核心	Mermaid 图表支持
`openapi`	核心	构建期 OpenAPI 3.x 规范渲染器
`okf`	Core	面向 AI 代理的 Open Knowledge Format 包 (按 locale)
`pwa`	可选	Progressive Web App —— 离线导航
`threads`	可选	内联讨论串 (by @svallory)
`math`	可选	KaTeX / LaTeX 数学公式渲染

安装可选插件：

docmd add <plugin-name>

开发你自己的插件：插件开发指南

配置

上手无需任何配置。仅在需要更多控制时，在项目根目录添加 docmd.config.json（或 .ts / .js）：

{
  "title": "我的项目",
  "url": "https://docs.myproject.com",
  "src": "./docs",
  "out": "./dist"
}

TypeScript 与 JavaScript 格式的配置文件支持动态值。

完整参考：配置概览

项目结构

my-docs/
├── docs/                ← 你的 Markdown 文件
├── assets/              ← 图片与静态资源
├── docmd.config.json    ← 可选配置
└── package.json

在线编辑器

基于浏览器的编辑器，所见即所得地撰写并预览文档 —— 无需任何本地配置。

前往 live.docmd.io 体验

编程式 API

在 Node.js 脚本、CI 流水线或自定义构建步骤中使用 docmd。（同时支持 CommonJS 与 ESM。）

import { build } from '@docmd/core';

await build('./docmd.config.json', { isDev: false });

完整参考：Node API

社区

Bug 与问题 → GitHub Issues
问题与想法 → Discussions
参与贡献 → CONTRIBUTING.md
路线图 → GitHub Discussions

支持我们

让更多人知道 docmd 是支持其开发最直接的方式 —— 在 X 上分享给你的朋友，或点个 Star。
如果 docmd 节省了你的时间，GitHub Sponsorship 是巨大的鼓励。
有想法或发现 Bug？欢迎提 Issue 或 PR，欢迎贡献你自己的插件。

许可

MIT —— 详见 LICENSE。

12 KiB Raw Permalink Blame History Unescape Escape