diff --git a/README.md b/README.md index 3c1eb4a..fdb854d 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,12 @@ + +> [!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 文件为准。 +
- EN  |  ES  |  DE  |  日本語  |  FR  |  中文 + EN  |  ES  |  DE  |  日本語  |  FR  |  中文
@@ -16,46 +22,46 @@
-

Production-ready documentation from Markdown, in seconds.
Zero config. AI-native. Built for developers.

+

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

npm version - monthly downloads + 每月下载 GitHub stars license

- Website  ·  - Documentation  ·  - Live Editor  ·  + 官网  ·  + 文档  ·  + 在线编辑器  ·  Agent Skills  ·  - Report a Bug + 反馈 Bug


- docmd default theme — light and dark mode preview + docmd 默认主题 — 浅色与深色模式预览

-## Quick Start +## 快速开始 -Run docmd in any folder with Markdown files — no install needed: +在任何包含 Markdown 文件的目录下直接运行 docmd —— 无需安装： ```bash npx @docmd/core dev ```
- Opens at http://localhost:3000
+ 在 http://localhost:3000 打开
```bash - _ _ + _ _ _| |___ ___ _____ _| | | . | . | _| | . | |___|___|___|_|_|_|___| @@ -96,169 +102,169 @@ npx @docmd/core dev

- docmd dev server preview + docmd dev 服务器预览

-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+
- Or install globally / via Docker
+ 或全局安装 / 通过 Docker
```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. +> 固定一个版本以获得可复现的构建。
-## 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 # 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 # 安装插件或模板 ``` -## 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 ``` -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. +基于浏览器的编辑器，所见即所得地撰写并预览文档 —— 无需任何本地配置。

- docmd live editor preview + docmd 在线编辑器预览

-**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. \ No newline at end of file +MIT —— 详见 [`LICENSE`](./LICENSE)。 \ No newline at end of file