使用mkdocs撰写技术文档并部署上线

Posted 2021-02-28 paulwhw

安装mkdocs模块

pip3 install mkdocs

安装完后查看一下版本：

mkdocs --version
‘‘‘
mkdocs, version 1.0.4 from /Library/Frameworks/Python.framework/Versions/3.6/lib/python3.6/site-packages/mkdocs (Python 3.6)
‘‘‘

在本地创建一个项目

# 这里项目名是pythonGuide
mkdocs new pythonGuide

执行完上面命令后我们会看到在当前目录下自动生成了一个pythonGuide项目目录，我们看看里面的东西：

ls pythonGuide
‘‘‘
docs        mkdocs.yml
‘‘‘

pythonGuide这个项目目录有一个docs目录，主要存放我们文档的源文件以及图片的资源；mkdocs.yml是配置文件，文档页面的目录结构以及主题等等都是在这里配置的。

本地调试

进入pythonGuide项目目录，在与mkdocs.yml同级的目录下执行命令 mkdocs serve即可：

cd pythonGuide

mkdocs serve

默认在本地8000端口可以看到文档的在线呈现的内容。

项目的本地配置

这里我把项目的目录结构配置成了下面这样：

.
├── docs
│   ├── imgs
│   │   └── egg.jpeg
│   ├── index.md
│   └── python基础
│       └── python基础1.md
└── mkdocs.yml

截图如下：

注意：里面的index.md文件不可以删除！我们可以在index.md中配置一下主页展示的内容。

mkdocs.yml中的内容

 

index.md中的内容

 

 

 

 

123

123

mkdocs的文档

https://mkdocs.zimoapps.com/

https://www.mkdocs.org/