MkDocs 和文档格式化怎么用：文档站选型、Docker 运行和 Markdown 格式化

文档站工具很多，MkDocs、Docsify、VuePress、Docusaurus、DokuWiki、Hexo 都能做知识库。选择时不必追求最全，先看内容类型、部署方式和维护成本。

文档站工具怎么选

常见选择：

• MkDocs：Markdown 驱动，适合技术文档和个人知识库。
• Docsify：无需构建，适合轻量文档。
• VuePress：适合 Vue 生态和组件化文档。
• Docusaurus：适合产品文档、版本文档和团队维护。
• DokuWiki：传统 Wiki，适合多人编辑。
• Hexo：更偏博客。

如果目标是“写 Markdown 并快速部署”，MkDocs Material 是一个很稳的选择。

Docker 运行 MkDocs

用 Docker 可以避免本地 Python 环境混乱。新建项目：

docker run -it --rm \
  -v /path/to/mkdocs:/docs \
  squidfunk/mkdocs-material new demo-docs

本地运行：

docker run -it --rm \
  -v /path/to/mkdocs:/docs \
  -p 8000:8000 \
  --workdir /docs/demo-docs \
  squidfunk/mkdocs-material serve -a 0.0.0.0:8000

然后访问本地 8000 端口预览。

Python 环境运行

如果不用 Docker，可以按项目环境安装：

pipenv install
pipenv shell
pipenv install -r requirements.txt
mkdocs new testdocs
mkdocs serve

正式项目更推荐用 uv 或固定虚拟环境，避免全局 Python 污染。

Markdown 格式化

文档多了以后，格式化很重要。可以考虑：

mdfmt -w .
prettier --write "*.md"
prettier --write "*/*.md"
prettier --write "*/*/*.md"

注意中文 Markdown 不一定适合强制长段落换行。团队要统一规则，避免每次格式化都产生巨大 diff。

文档站维护建议

1. 首页只放导航和关键入口。
2. 每篇文档只解决一个主题。
3. 旧文档要标注状态。
4. 链接失效要定期检查。
5. 图片和附件要有固定目录。
6. 部署命令写进 README。

文档站不是把所有 Markdown 复制进去，而是给读者一条可走的路径。

实用结论

MkDocs 适合用 Markdown 快速搭建文档站。Docker 跑起来最省环境成本，格式化工具负责保持一致。真正决定文档站质量的，不是主题多漂亮，而是目录清楚、链接可用、内容不过期。