> ## Documentation Index
> Fetch the complete documentation index at: https://fundocker.topfde.net/llms.txt
> Use this file to discover all available pages before exploring further.

# Docmd installation guide

# DocMD 安装指南

本文介绍开源项目 [`docmd-io/docmd`](https://github.com/docmd-io/docmd) 的安装与启动方式。DocMD（命令行和 npm 包名为 `docmd` / `@docmd/core`）可将 Markdown 文档构建为静态文档站点。

## 环境要求

* **Node.js 20 或更高版本**，用于本地或全局安装。
* npm 随 Node.js 一同提供；也可以使用 pnpm、Yarn 或 Bun。
* 使用 Docker 方式时，需要已安装并启动 Docker。

检查 Node.js 和 npm 是否可用：

```bash theme={null}
node --version
npm --version
```

## 安装方式

### 方式一：快速运行

适合先体验 DocMD，或在已有 Markdown 文档的目录中启动预览。进入包含 Markdown 文件的项目目录后运行：

```bash theme={null}
npx @docmd/core dev
```

然后打开终端显示的本地地址，默认是 [http://localhost:3000](http://localhost:3000)。此方式无需先将 DocMD 添加到项目依赖。

### 方式二：安装到项目（推荐）

适合长期维护文档站点，并希望将工具版本随项目一同管理的场景。在项目根目录运行：

```bash theme={null}
npm install -D @docmd/core
npx docmd init
```

初始化后，启动本地预览：

```bash theme={null}
npx docmd dev
```

构建静态站点：

```bash theme={null}
npx docmd build
```

默认构建产物输出到 `site/` 目录，可部署到 GitHub Pages、Vercel、Netlify 等静态托管服务。

使用其他包管理器时，可选择对应命令：

```bash theme={null}
# pnpm
pnpm add -D @docmd/core
pnpm dlx docmd init

# Yarn
yarn add -D @docmd/core
yarn dlx docmd init

# Bun
bun add -D @docmd/core
bunx docmd init
```

### 方式三：全局安装

如果希望在多个目录中直接使用 `docmd` 命令，可全局安装：

```bash theme={null}
npm install -g @docmd/core
```

安装后，在文档项目目录中运行：

```bash theme={null}
docmd dev
docmd build
```

也可以使用 `pnpm add -g @docmd/core`、`yarn global add @docmd/core` 或 `bun add -g @docmd/core`。

### 方式四：使用 Docker 构建

不想在本机安装 Node.js 时，可以使用官方 Docker 镜像。以下命令适用于 macOS/Linux 常见 shell；它将当前目录的 `docs/` 挂载为容器内的文档源目录，并将构建结果写入当前目录的 `site/`：

```bash theme={null}
docker pull ghcr.io/docmd-io/docmd:latest

docker run --rm \
  -v "$(pwd)/docs:/docs" \
  -v "$(pwd)/site:/site" \
  ghcr.io/docmd-io/docmd:latest build
```

生产环境建议将 `latest` 替换为固定版本标签，以便构建结果可复现。Windows 用户请按所用终端的 Docker 卷挂载路径格式调整路径。

## 常见问题

### Node.js 版本过低

运行 `node --version` 检查版本；如果低于 20，请升级 Node.js 后重试。

### 全局安装遇到权限错误（`EACCES`）

macOS/Linux 上不建议通过 `sudo` 安装 npm 全局包。可使用 nvm 或 fnm 管理 Node.js 版本，再重新安装。

### 默认端口已被占用

DocMD 开发服务器会尝试使用下一个可用端口。请查看启动命令的终端输出，并打开其中显示的地址。

## 官方资料

* [DocMD 项目主页与快速开始](https://github.com/docmd-io/docmd)
* [官方安装指南（中文）](https://github.com/docmd-io/docs/blob/main/docmd-main/v09/zh/getting-started/installation.md)
* [官方快速开始（中文）](https://github.com/docmd-io/docs/blob/main/docmd-main/v09/zh/getting-started/quick-start.md)

***

本文中由 FunDocker 项目维护者 Jeff Wang 创作的原创内容，采用 [知识共享署名 4.0 国际许可协议（CC BY 4.0）](https://creativecommons.org/licenses/by/4.0/) 授权，可用于商业用途。转载或改编时，请注明作者“FunDocker 项目维护者”、本文标题和来源链接，并说明是否做过修改；不得暗示作者为使用者或其使用方式背书。

本许可仅适用于上述原创内容，不涵盖 DocMD 项目及其他第三方的名称、商标、文字、代码、图片或资料；这些内容仍按各自权利人适用的许可和权利说明处理。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.