使用MKDocs构建Markdown格式API文档(macOS)

最新推荐文章于 2025-06-01 09:17:21 发布

WSYW126

最新推荐文章于 2025-06-01 09:17:21 发布

阅读量4.4k

点赞数 1

CC 4.0 BY-SA版权

分类专栏： GitBook&MkDocs 文章标签： markdown mkdocs

本文链接：https://blog.youkuaiyun.com/WSYW126/article/details/51997395

2 篇文章

订阅专栏

MkDocs是一款用于快速生成静态文档站点的工具，支持Markdown编写，配置灵活。本文介绍了在macOS上安装MkDocs，创建项目，配置及预览文档的步骤，并提供了样式示例和相关资源链接。

摘要生成于 C知道，由 DeepSeek-R1 满血版支持，前往体验 >

MkDocs是什么?

MKDocs就是一个能快速，简单，优雅的生成静态文档站点的项目。文档用Markdown书写，目录用YAML配置，弄好之后你可以把它放到Github的Pages 上，或者自己服务器上就可以了。并且也有好几套UI供你选择MkDocs UI，特别适合那些做开源项目的童鞋，生成说明文档使用。总的来说，就是省时省力，效果还不错
安装

我的机子装了brew，所以可以直接命令行安装软件。
1. 安装Python
  
  在终端输入下面指令：brew install python
  
  查看版本：
```
python --version
Python 2.7.10
```
2. 安装mkdocs
  
  在终端输入下面指令：pip install mkdocs
  
  查看版本：
```
mkdocs --version
mkdocs, version 0.15.3
```
实战一下
1. 在终端输入下面指令：mkdocs new project。创建一个名为project的mkdocs的项目。
2. 运行项目：
```
cd project
mkdocs serve
```
3. 显示如下：
```
Running at: http://127.0.0.1:8000/
```
4. 在浏览器中访问上面的链接即可。
解释一下
1. 在project文件下，会有一个doc目录和一个mkdocs.yml文件，.yml就是配置文件。修改里面的内容就可以修改样式以及需要添加的展示内容。
2. 给出几个样式：
```
theme: readthedocs
theme: bootstrap
theme: amelia
theme: cosmo
theme: slate
theme: yeti
theme: united
theme: journal
```

其他指令

$mkdocs build /*生成网站的site目录，里面有一些静态资源*/
$mkdocs build --clean
$mkdocs --help

参考资料：
MKDocs官网文档
备注：
转载请注明出处：http://blog.youkuaiyun.com/wsyw126/article/details/51997395
作者：WSYW126