docs: make Chinese README the default

2026-07-13 10:21:16 +00:00
parent 09b67d3f14
commit c0f6dae9db
1 changed files with 118 additions and 112 deletions
@@ -1,6 +1,12 @@
+<!-- WEHUB_ZH_README -->
+> [!NOTE]
+> 本文档由 WeHub 基于上游 README 翻译整理，属于社区翻译，非官方中文文档。  
+> [English](./README.en.md) · [原始项目](https://github.com/docmd-io/docmd) · [上游 README](https://github.com/docmd-io/docmd/blob/HEAD/README.md)  
+> 原作者、版权与许可证归属以原始项目及本仓库 LICENSE 文件为准。
+
 <div align="right">
  <sup>
-    <b>EN</b> &nbsp;|&nbsp; <a href="./README.es.md">ES</a> &nbsp;|&nbsp; <a href="./README.de.md">DE</a> &nbsp;|&nbsp; <a href="./README.ja.md">日本語</a> &nbsp;|&nbsp; <a href="./README.fr.md">FR</a> &nbsp;|&nbsp; <a href="./README.zh.md">中文</a>
+    <a href="./README.md">EN</a> &nbsp;|&nbsp; <a href="./README.es.md">ES</a> &nbsp;|&nbsp; <a href="./README.de.md">DE</a> &nbsp;|&nbsp; <a href="./README.ja.md">日本語</a> &nbsp;|&nbsp; <a href="./README.fr.md">FR</a> &nbsp;|&nbsp; <b>中文</b>
  </sup>
 </div>

@@ -16,46 +22,46 @@

  <br/>

-  <p><b>Production-ready documentation from Markdown, in seconds.</b><br/>Zero config. AI-native. Built for developers.</p>
+  <p><b>几秒内从 Markdown 生成生产可用的文档站点。</b><br/>零配置。AI 原生。为开发者打造。</p>

  <p>
    <a href="https://www.npmjs.com/package/@docmd/core"><img src="https://img.shields.io/npm/v/@docmd/core.svg?style=flat-square&color=CB3837" alt="npm version"></a>
-    <a href="https://www.npmjs.com/package/@docmd/core?activeTab=versions"><img src="https://img.shields.io/npm/dm/@docmd/core.svg?style=flat-square&color=38bd24" alt="monthly downloads"></a>
+    <a href="https://www.npmjs.com/package/@docmd/core?activeTab=versions"><img src="https://img.shields.io/npm/dm/@docmd/core.svg?style=flat-square&color=38bd24" alt="每月下载"></a>
    <a href="https://github.com/docmd-io/docmd"><img src="https://img.shields.io/github/stars/docmd-io/docmd?style=flat-square&logo=github" alt="GitHub stars"></a>
    <a href="https://github.com/docmd-io/docmd/blob/main/LICENSE"><img src="https://img.shields.io/github/license/docmd-io/docmd.svg?style=flat-square&color=A31F34" alt="license"></a>
  </p>

  <h4>
-    <a href="https://docmd.io">Website</a> &nbsp;·&nbsp;
-    <a href="https://docs.docmd.io">Documentation</a> &nbsp;·&nbsp;
-    <a href="https://live.docmd.io">Live Editor</a> &nbsp;·&nbsp;
+    <a href="https://docmd.io">官网</a> &nbsp;·&nbsp;
+    <a href="https://docs.docmd.io">文档</a> &nbsp;·&nbsp;
+    <a href="https://live.docmd.io">在线编辑器</a> &nbsp;·&nbsp;
    <a href="https://github.com/docmd-io/docmd-skills">Agent Skills</a> &nbsp;·&nbsp;
-    <a href="https://github.com/docmd-io/docmd/issues">Report a Bug</a>
+    <a href="https://github.com/docmd-io/docmd/issues">反馈 Bug</a>
  </h4>

  <br/>

  <a href="https://docs.docmd.io">
-    <img width="820" alt="docmd default theme — light and dark mode preview" src="https://raw.githubusercontent.com/docmd-io/docmd/refs/heads/main/assets/docmd-cover.webp" />
+    <img width="820" alt="docmd 默认主题 — 浅色与深色模式预览" src="https://raw.githubusercontent.com/docmd-io/docmd/refs/heads/main/assets/docmd-cover.webp" />
  </a>

  <br/><br/>

 </div>

-## Quick Start
+## 快速开始

-Run docmd in any folder with Markdown files — no install needed:
+在任何包含 Markdown 文件的目录下直接运行 docmd —— 无需安装：

 ```bash
 npx @docmd/core dev
 ```

 <details>
-  <summary><b>Opens at <code>http://localhost:3000</code></b></summary><br>
+  <summary><b>在 <code>http://localhost:3000</code> 打开</b></summary><br>

 ```bash
-    _                 _ 
+    _                 _
  _| |___ ___ _____ _| |
 | . | . |  _|     | . |
 |___|___|___|_|_|_|___|
@@ -96,169 +102,169 @@ npx @docmd/core dev
 </details>

 <p align="center">
-  <img alt="docmd dev server preview" width="820" src="https://docmd.io/assets/images/dev-preview.gif">
+  <img alt="docmd dev 服务器预览" width="820" src="https://docmd.io/assets/images/dev-preview.gif">
 </p>

-Navigation is generated from your file structure. No config file, no frontmatter required, no framework to learn.
+导航由你的目录结构自动生成。无需配置文件、不强制 frontmatter、不必学习框架。

-**When you're ready to ship:**
+**当准备发布时：**

 ```bash
 npx @docmd/core build
 ```

-This outputs a highly optimized static site (SPA) ready for deployment to Vercel, Cloudflare Pages, Netlify, GitHub Pages, or any static host.
+这会输出一个高度优化的静态站点（SPA），可直接部署到 Vercel、Cloudflare Pages、Netlify、GitHub Pages 或任何静态主机。

-**Requirements:** Node.js 18+
+**环境要求：** Node.js 18+

 <details>
-  <summary><b>Or install globally / via Docker</b></summary><br/>
+  <summary><b>或全局安装 / 通过 Docker</b></summary><br/>

 ```bash
-# Install globally via npm
+# 通过 npm 全局安装
 npm install -g @docmd/core

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

-# Run it
-docmd dev    # start dev server
-docmd build  # build for deployment
+# 运行
+docmd dev    # 启动开发服务器
+docmd build  # 构建用于部署
 ```

-Or run via Docker:
+或通过 Docker 运行：

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

-> Pin a version for reproducible builds.
+> 固定一个版本以获得可复现的构建。

 </details>

-## Why docmd?
+## 为什么选择 docmd？

-| Feature | docmd | Docusaurus | MkDocs | VitePress | Mintlify |
+| 特性 | docmd | Docusaurus | MkDocs | VitePress | Mintlify |
 | :--- | :---: | :---: | :---: | :---: | :---: |
-| **Config required** | **None** | `docusaurus.config.js` | `mkdocs.yml` | `config.mts` | `docs.json` |
-| **JS payload** | **~18 kb** | ~250 kb | ~40 kb | ~50 kb | ~120 kb |
-| **Navigation** | **Instant SPA** | React SPA | Full reload | Vue SPA | Hosted SPA |
-| **Versioning** | **Native** | Native (complex) | mike plugin | Manual | Native |
-| **i18n** | **Native** | Native (complex) | Plugin-based | Native | Native |
-| **Multi-project** | **Native** | Plugin | Plugin | - | - |
-| **Search** | **Built-in** | Algolia (cloud) | Built-in | MiniSearch | Cloud |
-| **AI context (`llms.txt`)** | **Built-in** | - | - | - | Built-in |
-| **MCP server** | **Built-in** | - | - | - | Built-in |
-| **Agent skills** | **Built-in** | - | - | - | - |
-| **Docker image** | **Official** | - | Official | - | - |
-| **Self-hosted** | **Yes** | Yes | Yes | Yes | - |
-| **Cost** | **Free (OSS)** | Free (OSS) | Free (OSS) | Free (OSS) | Freemium |
+| **需要配置** | **无需** | `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 |

-## Features
+## 功能特性

-### Zero config, instant start
-Point docmd at any Markdown folder and it runs. Navigation is built automatically from your file structure. You can write your first doc and have it live in under a minute — no boilerplate, no build pipeline to configure, no decisions to make upfront.
+### 零配置，即时启动
+把 docmd 指向任意 Markdown 目录，它就会运行。导航会根据你的目录结构自动生成。你可以在不到一分钟的时间内写好第一篇文档并上线 —— 没有模板代码，没有需要配置的构建流程，也不需要提前做技术决策。

-### Tiny by default, fast everywhere
-The default JavaScript payload is ~18 kb. Pages navigate as an instant SPA. The output is static HTML — SEO-optimised, with sitemap, canonical URLs, and Open Graph metadata included. Offline full-text search is built in, no cloud service required.
+### 默认轻量，处处高速
+默认的 JavaScript 体积约 18 kb，页面以即时 SPA 的方式切换。输出为静态 HTML —— 已做好 SEO 优化，包含 sitemap、canonical URL 与 Open Graph 元数据。内置离线全文搜索，无需任何云服务。

-### AI-native
-docmd is built for the way documentation is read and used today:
- **MCP Server** — `docmd mcp` exposes your docs to AI agents over stdio, letting them search, read, and validate content directly.
- **Context (`llms.txt` / `llms-full.txt`)** — complete documentation context generated at build time, ready for any LLM.
- **Agent Skills** — modular instruction sets for LLMs and IDE agents ([docmd-skills](https://github.com/docmd-io/docmd-skills)).
- **Copy as Markdown / Copy Context** — one-click buttons in the browser, optimised for pasting into AI chat.
+### 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 对话中做了优化。

-### Built to scale
- Internationalisation with multi-locale builds (per-locale search index, llms, okf, hreflang)
- Versioning for multiple doc releases (with auto-detection of the current version)
- Workspaces for monorepos and multi-project setups
- Plugin system for extending core behaviour (per-hook return-type validation, async-friendly)
- Full theming support, built-in templates, custom CSS/JS, light/dark mode
+### 为规模化而生
+- 通过多语言构建实现国际化
+- 支持多个文档版本的版本管理
+- 面向 monorepo 与多项目场景的 Workspaces
+- 用于扩展核心行为的插件体系
+- 完整的 Theming 支持、内置模板、自定义 CSS/JS，以及浅色 / 深色模式

 ## CLI

 ```bash
-docmd dev            # local development server
-docmd build          # build for deployment
-docmd live           # browser-based Live Editor
-docmd init           # scaffold a new docmd.config.json in the current folder
-docmd stop           # stop any running `docmd dev` / `docmd live` servers
-docmd doctor         # pre-flight check: config + plugin install status
-docmd migrate        # migrate to docmd from Docusaurus, VitePress, MkDocs, or Starlight
-docmd deploy         # generate config for Docker, NGINX, Caddy, Vercel, Netlify
-docmd validate       # check all internal links
-docmd mcp            # run as an MCP server over stdio
-docmd add <name>     # install a plugin or template
+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>     # 安装插件或模板
 ```

-## Plugins
+## 插件

-Core functionality is powered by a robust plugin system. The essentials are included by default, while optional plugins can be added for specific needs.
+核心功能由一套稳健的插件系统驱动。基础能力默认已包含，特定需求可加装可选插件。

-| Plugin | Status | Description |
+| 插件 | 状态 | 描述 |
 | :--- | :---: | :--- |
-| `search` | Core | Offline full-text search (keyword + optional semantic via `docmd-search`) |
-| `seo` | Core | SEO tags and Open Graph metadata |
-| `sitemap` | Core | Generates `sitemap.xml` |
-| `git` | Core | Git commit history and last-updated dates |
-| `analytics` | Core | Lightweight analytics integration |
-| `llms` | Core | AI context generation (`llms.txt` / `llms-full.txt`) |
-| `okf` | Core | Open Knowledge Format bundles for AI agents (per-locale) |
-| `mermaid` | Core | Mermaid diagram support |
-| `openapi` | Core | Build-time OpenAPI 3.x spec renderer |
-| `pwa` | Optional | Progressive Web App — offline navigation |
-| `threads` | Optional | Inline discussion threads *(by @svallory)* |
-| `math` | Optional | KaTeX / LaTeX math rendering |
+| `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 数学公式渲染 |

-Install optional plugins:
+安装可选插件：

 ```bash
 docmd add <plugin-name>
 ```

-Build your own: [Plugin Development Guide](https://docs.docmd.io/development/building-plugins/)
+开发你自己的插件：[插件开发指南](https://docs.docmd.io/development/building-plugins/)

-## Configuration
+## 配置

-No configuration is required to get started. Add a `docmd.config.json` (or `.ts` / `.js`) in your project root only when you need more control:
+上手无需任何配置。仅在需要更多控制时，在项目根目录添加 `docmd.config.json`（或 `.ts` / `.js`）：

 ```json
 {
-  "title": "My Project",
+  "title": "我的项目",
  "url": "https://docs.myproject.com",
  "src": "./docs",
  "out": "./dist"
 }
 ```

-TypeScript and JavaScript config files are supported for dynamic values.
+TypeScript 与 JavaScript 格式的配置文件支持动态值。

-Full reference: [Configuration Overview](https://docs.docmd.io/configuration/overview)
+完整参考：[配置概览](https://docs.docmd.io/configuration/overview)

-## Project Structure
+## 项目结构

 ```text
 my-docs/
-├── docs/                ← Your markdown files
-├── assets/              ← Images and static files
-├── docmd.config.json    ← Optional configuration
+├── docs/                ← 你的 Markdown 文件
+├── assets/              ← 图片与静态资源
+├── docmd.config.json    ← 可选配置
 └── package.json
 ```

-## Live Editor
+## 在线编辑器

-A browser-based editor for writing and previewing docs — no local setup required.
+基于浏览器的编辑器，所见即所得地撰写并预览文档 —— 无需任何本地配置。

 <p>
-  <img alt="docmd live editor preview" width="820" src="https://docs.docmd.io/assets/previews/live-editor-preview.webp">
+  <img alt="docmd 在线编辑器预览" width="820" src="https://docs.docmd.io/assets/previews/live-editor-preview.webp">
 </p>

-**Try it at [live.docmd.io](https://live.docmd.io)**
+**前往 [live.docmd.io](https://live.docmd.io) 体验**

-## Programmatic API
+## 编程式 API

-Use docmd in Node.js scripts, CI pipelines, or custom build steps. (Supports both CommonJS and ESM).
+在 Node.js 脚本、CI 流水线或自定义构建步骤中使用 docmd。（同时支持 CommonJS 与 ESM。）

 ```javascript
 import { build } from '@docmd/core';
@@ -266,21 +272,21 @@ import { build } from '@docmd/core';
 await build('./docmd.config.json', { isDev: false });
 ```

-Full reference: [Node API](https://docs.docmd.io/development/node-api-reference/)
+完整参考：[Node API](https://docs.docmd.io/development/node-api-reference/)

-## Community
+## 社区

- **Bugs & issues** → [GitHub Issues](https://github.com/docmd-io/docmd/issues)
- **Questions & ideas** → [Discussions](https://github.com/orgs/docmd-io/discussions)
- **Contributing** → [CONTRIBUTING.md](.github/CONTRIBUTING.md)
- **Roadmap** → [GitHub Discussions](https://github.com/orgs/docmd-io/discussions/2)
+- **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)

-## Support
+## 支持我们

- Getting the word out is the most direct way to support docmd's development. [Share it on X](https://twitter.com/intent/tweet?url=https://github.com/docmd-io/docmd&text=docmd%20-%20Production-ready%20docs%20from%20Markdown%20in%20seconds.) with friends or give it a star.
- If docmd saves you time, a [GitHub sponsorship](https://github.com/sponsors/mgks) goes a long way.
- Got ideas or bugs? Open an issue or PR, feel free to contribute your own plugins.
+- 让更多人知道 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，欢迎贡献你自己的插件。

-## License
+## 许可

-MIT License. See `LICENSE` for details.
+MIT —— 详见 [`LICENSE`](./LICENSE)。