目 录CONTENT

文章目录

MkDocs | 超简单的文档生成器

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

前言

最近啊,我比较迷恋文档和静态站点生成,今天我们再分享一个基于 PythonMarkdown 的文档生成器。它就是 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 目录,用 pythonhttp.server 模块启动我们能的静态站点。

启动站点

页面效果

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

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

0
广告 广告

评论区