Skip to main content

​
DocMD 安装指南

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

​
环境要求

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

​
安装方式

​
方式一：快速运行

适合先体验 DocMD，或在已有 Markdown 文档的目录中启动预览。进入包含 Markdown 文件的项目目录后运行：
然后打开终端显示的本地地址，默认是 http://localhost:3000。此方式无需先将 DocMD 添加到项目依赖。

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

适合长期维护文档站点，并希望将工具版本随项目一同管理的场景。在项目根目录运行：
初始化后，启动本地预览：
构建静态站点：
默认构建产物输出到 site/ 目录，可部署到 GitHub Pages、Vercel、Netlify 等静态托管服务。 使用其他包管理器时，可选择对应命令：

​
方式三：全局安装

如果希望在多个目录中直接使用 docmd 命令，可全局安装：
安装后，在文档项目目录中运行：
也可以使用 pnpm add -g @docmd/core、yarn global add @docmd/core 或 bun add -g @docmd/core。

​
方式四：使用 Docker 构建

不想在本机安装 Node.js 时，可以使用官方 Docker 镜像。以下命令适用于 macOS/Linux 常见 shell；它将当前目录的 docs/ 挂载为容器内的文档源目录，并将构建结果写入当前目录的 site/：
生产环境建议将 latest 替换为固定版本标签，以便构建结果可复现。Windows 用户请按所用终端的 Docker 卷挂载路径格式调整路径。

​
常见问题

​
Node.js 版本过低

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

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

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

​
默认端口已被占用

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

​
官方资料

本文中由 FunDocker 项目维护者 Jeff Wang 创作的原创内容，采用 知识共享署名 4.0 国际许可协议（CC BY 4.0） 授权，可用于商业用途。转载或改编时，请注明作者“FunDocker 项目维护者”、本文标题和来源链接，并说明是否做过修改；不得暗示作者为使用者或其使用方式背书。 本许可仅适用于上述原创内容，不涵盖 DocMD 项目及其他第三方的名称、商标、文字、代码、图片或资料；这些内容仍按各自权利人适用的许可和权利说明处理。