Markdown 一键生成文档站

2026-09-10

DocMD 是一个生产级文档生成命令行工具，一条命令可将 Markdown 文档生成美观的静态文档网站。

前置条件：只需要 npx

npx 跟着 Node.js 一起装。如果电脑里已经有 Node.js，终端跑一下：

node -v
npx -v

两个命令都有输出，就能继续。

如果还没装，去 Node.js 官网下载安装包即可：https://nodejs.org/zh-cn 。装完重开终端，再跑一遍上面的两个命令。

怎么启动

实测方式：在桌面上创建一个 test 文件夹，里面创建 docs 子目录，丢进去 5 篇 Markdown 文件。题材很杂：AI 观点、工具教程、行业分析都有。

目录类似：

test/
├── docs/
│   ├── index.md
│   ├── ai_detection_report.md
│   └── guides/
│       └── setup.md

然后在终端执行：

cd C:\Users\admin\Desktop\test
npx @docmd/core dev

DocMD 就会自己干活：

扫描 docs/ 下面的 Markdown
按文件和文件夹层级生成导航
在本地开一个可预览的站点

这一步最适合拿来验证一件事：手里的这批 Markdown，到底值不值得单独做个站。

浏览器打开终端输出的地址，本地站点直接起来了。左边有导航，右边是正文，搜索和亮暗切换也都有。整个过程比预想得简单很多。

这类工具真正有价值的地方就是一件事：先把站跑起来。 先看到东西，再决定要不要折腾配置。

什么时候用 build

dev 是自己在本地看。要给别人访问、要上线、要部署，就跑：

npx @docmd/core build

跑完之后，目录里会多出一个 site/ 文件夹。这个文件夹就是构建产物，也就是真正要上传的东西。

建议构建后做 4 个检查：

打开 site/index.html
点左侧菜单，确认页面跳转正常
刷新子页面，看会不会 404
检查图片、CSS、JS 有没有丢

都没问题，site/ 就能部署。

这里最容易犯的错很典型：上传的是 docs/，真正该上传的是 site/。

配置这件事，别把自己吓跑

很多人一看到 docmd.config.js 就开始退，其实没必要。DocMD 最顺手的用法是两段式：第一段，先零配置跑起来；第二段，哪里不满意，再补哪里。

比如站点标题想改、域名想补、导航想调，这时候再创建 docmd.config.js。

不过有个实际坑要先说清楚。如果要在配置文件里写：

const { defineConfig } = require('@docmd/core');

那得先本地安装一次：

cd C:\Users\admin\Desktop\test
npm init -y
npm install @docmd/core

原因很简单：npx 负责临时运行，require() 需要本地能找到这个包。

装完之后，最小配置其实就两项：

const { defineConfig } = require('@docmd/core');

module.exports = defineConfig({
  title: '你的站点名称',
  url: 'https://your-domain.com',
});

很多人的需求到这里就结束了。

自定义最省事的办法：让 AI 直接看你的文件夹

这一段值得直接记住。

不要被”自定义”这两个字吓跑。 现在最省事的做法，往往不是自己去翻配置文档，而是让大模型直接看你的项目文件夹，然后替你改。

项目文件夹里通常有：docs/ 里的 Markdown、docmd.config.js、assets/css/custom.css、assets/js/custom.js。这时候完全可以把这个文件夹交给 AI，让它直接看结构，再下指令。

比如可以直接说：

帮我把侧边栏按”AI 观点 / 开发者工具 / 行业与商业”分组
帮我加一个顶部导航栏，右上角放 GitHub 链接
帮我把主题改成更有质感的样式
帮我加一个页脚，放简介和联系方式
帮我写一份 custom.css，把标题字号、间距、卡片样式调得更舒服

这种方式比自己一点点翻文档快得多。因为 AI 看到的是真实文件，不是一个抽象需求。它知道现在有哪些文章、目录怎么排、配置文件已经写到哪一步，改出来的东西会更贴近当前这个站。

说白了，现在做自定义，最省事的路子就是：先让站跑起来，再让 AI 按你的文件结构帮你改。

还能自定义哪些东西

DocMD 常见的自定义点，基本就这几类：

主题切换：默认 sky，也可以换成 ruby、retro 这些风格
侧边栏分组：把文章按主题整理成更清楚的结构
顶部导航栏：适合放首页、分类入口、外链
页脚：适合放简介、品牌信息、联系方式
自定义 CSS / JS：适合微调样式和补一点交互

不用一次全做完。先改最影响阅读体验的那一项，通常是导航，其次是样式。

它和别的方案差在哪

DocMD 官方给的数据，初始 JS 负载大约是 18KB。对比一下：

工具	初始负载	需要写配置	生态依赖
DocMD	~18KB	不需要	无
MkDocs	~40KB	需要	Python
VitePress	~50KB	需要	Vue
Docusaurus	~250KB	需要	React

这张表的重点不只是轻量。更关键的是，它适合一种很现实的需求：手里已经有一堆 Markdown，只是想尽快把它们变成一个能访问的站。 如果目标就是这个，DocMD 的路径确实更短。