MkDocs | 超简单的文档生成器

phyger

2022-03-13 / 0 评论 / 0 点赞 / 3,050 阅读 / 1,125 字 / 正在检测是否收录...

03/13

前言

最近啊，我比较迷恋文档和静态站点生成，今天我们再分享一个基于 Python 和 Markdown 的文档生成器。它就是 MkDocs。

关于 MkDocs

MkDocs 是一个快速、简单、完全华丽的静态站点生成器，用于构建项目文档。文档源文件以 Markdown 格式编写，并使用单个 YAML 配置文件进行配置。

呆猫

安装 MkDocs

pip install mkdocs

创建 MkDocs 项目

PS C:\> mkdocs.exe new my-demo
INFO     -  Creating project directory: my-demo
INFO     -  Writing config file: my-demo\mkdocs.yml
INFO     -  Writing initial docs: my-demo\docs\index.md
PS C:\> cd .\my-demo\
PS C:\my-demo> ls


    目录: C:\my-demo


Mode                 LastWriteTime         Length Name
----                 -------------         ------ ----
d-----          22-2-9  下午 09:00                docs
-a----          22-2-9  下午 09:00             20 mkdocs.yml


PS C:\my-demo>

启动项目

命令：mkdocs.exe serve

启动过程

文档首页预览效果

如上，我们可以发现两个亮点。第一 MkDocs 生成的文档自带 ico；第二 MkDocs 默认支持搜索。

打造我们自己的在线文档

MkDocs 不同于 Pelican 等站点生成器，其类似 Docsify+Pelican，即可以在访问过程中动态渲染，也可以编译为静态资源。我们只需要维护自己的 docs 目录即可。

创建自己的文档

我们在 docs 目录下创建我们自己的文档mydemo.md，内容太长，就不做展示了。

然后我们访问http://localhost:8000/，就可以看到我们的站点已经发生了变化。没错，MkDocs 是支持热加载的。

新效果

我自己的文档

下拉菜单

我们需要在mkdocs.yml中进行 nav 配置，假设我们想把我们的文章 Mydemo 放到一个 Blog 下拉菜单中，起名为 Pelican 入门。

site_name: My Docs
nav:
    - Home: '../'
    - 'Blog':
      - 'Pelican入门': 'mydemo.md'

再次查看http://localhost:8000/

下拉菜单效果

不得不说，秒啊。

编译文档

mkdos.exe build

编译结果

我们进入 site 目录，用 python 的 http.server 模块启动我们能的静态站点。

启动站点

页面效果

为了方便展示，我们直接使用 python 的 http.server 工具启动了我们的站点，实际生产中建议你选择 nginx 之类的 web 服务器来托管你的静态站点。

更多内容详见：https://www.mkdocs.org/

目录CONTENT