使用MkDocs撰写文档¶
初始化文档¶
在 安装MkDocs 之后，就可以开始撰写文档。第一个步骤是初始化文档结构:
mkdocs new 创建 works 项目目录结构¶
mkdocs new works
cd works
文档布局¶
在MkDocs中，文档就是常规的Markdown文件，存放在 docs_dir 配置对应的目录(默认是 docs 目录):
mkdocs.yml
docs/
index.md
如何合理布局¶
其实我也是依样画葫芦，在网上能够找到大量的采用 MkDocs 撰写的文档库，可以直接clone下来参考构建自己的文档。例如，我参考 Argo CD 官方文档 的 Argo CD 手册案例 ，构建文档索引:
mkdocs.yml¶
site_name: My Works
theme: 'material'
plugins:
- search:
lang:
- en
- ja
nav:
- Home: index.md
- '技术':
- Overview: tech/index.md
- '容灾':
- 'DNS域名解析容灾': tech/disaster_recovery/gslb.md
- '项目':
- Overview: project/index.md
- 'xyz项目':
- Overview: project/xyz/index.md
- '可行性分析': 'alipay/project/xyz/feasibility_analysis.md'
- About: about.md
备注
我发现 Mkdocs 配置和使用 写得非常清晰，值得学习参考。珠玉在前，我就不再重复了。后续我可能会根据实践再补充本文，不过目前我还是简单使用，主要用于工作文档记录，就暂且这样吧。