背景：

之前写笔记基本使用了私有的wiz为知笔记，有些笔记可能需要大纲一样展示出来，碰巧那天看到一个博主的Ansible博客，感觉还挺不错，就试了下，很简约，可以渲染 Markdown 成静态HTML，很符合我的需求

img

环境：python3

第一步：安装 MkDocs

官网地址：https://www.mkdocs.org/

直接使用pip工具安装：

[root@sre ~]# pip install mkdocs -i https://pypi.douban.com/simple

安装完成后，查看下版本验证是否安装成功

[root@sre ~]# mkdocs --version
mkdocs, version 1.2.3 from /usr/local/lib/python3.6/site-packages/mkdocs (Python 3.6)

第二步：初始化 MkDocs

找一个用于存放mkdocs 项目文件的目录，并执行以下命令：

[root@sre ~]# mkdir -p /home/application
 
[root@sre ~]# cd /home/application/

#mkdocs new (项目名称)
[root@sre application]# mkdocs new mkdocs
# INFO    -  Creating project directory: helpdocs
# INFO    -  Writing config file: helpdocs\mkdocs.yml
# INFO    -  Writing initial docs: helpdocs\docs\index.md

[root@sre application]# ls  mkdocs/
总用量 8
drwxr-xr-x 3 root root   68 3月  20 13:15 docs
-rwxr-xr-x 1 root root 1843 3月  20 13:29 mkdocs.yml


#新建的项目默认有 mkdocs.yml 文件和 docs 目录
mkdocs.yml 文件是项目的配置文件。站点的相关设置，和页面的添加,主题的配置，图标配置等等
docs 目录用于存放所有的文档文件的 Markdown 源码和图片相关文件

第三步：启动 MkDocs

刚刚我们已经初始化好了mkdocs,进入到项目目录下，执行以下命令即可运行

#-a 可以指定监听ip:端口
mkdocs serve -a 0.0.0.0:5000
[root@sre mkdocs]# bash run-test.sh 
INFO     -  Building documentation...
INFO     -  Documentation built in 0.30 seconds
INFO     -  [14:44:07] Serving on http://0.0.0.0:5000/

效果：

img

第四步：优化主题

mkdocs 官方提供了 默认主题 和 ReadTheDocs 主题，其他主题可以去github 上查找【https://github.com/mkdocs/mkdocs/wiki/MkDocs-Themes】

还是有很多模板可供选择的

img

我这里选择了 Material for MkDocs 【https://github.com/squidfunk/mkdocs-material】

  • 安装主题：
[root@sre ~]# pip install mkdocs-material -i https://pypi.douban.com/simple
  • 设置主题：
theme:
  name: material

  • 配置mkdocs.yml 配置文件

    【可根据官方的 配置进行修改，https://github.com/squidfunk/mkdocs-material/blob/master/mkdocs.yml】

[root@sre mkdocs]# cat mkdocs.yml 
theme:
  name: material

repo_name: srebro.cn
repo_url: https://srebro.cn


site_name: doc.srebro.cn
site_description: doc.srebro.cn
site_author: srebro.cn
site_url: https://doc.srebro.cn
copyright: Copyright © 2022 <a href="https://srebro.cn">Powered by srebro.cn 版权所有</a>


extra:
  analytics:
    provider: google
    property: !ENV GOOGLE_ANALYTICS_KEY
  social:
    - icon: fontawesome/brands/github
      link: https://github.com/squidfunk
    - icon: fontawesome/brands/gitter
      link: https://gitter.im/squidfunk/mkdocs-material
    - icon: fontawesome/brands/docker
      link: https://hub.docker.com/r/squidfunk/mkdocs-material/
    - icon: fontawesome/brands/python
      link: https://pypi.org/project/mkdocs-material/
    - icon: fontawesome/brands/twitter
      link: https://twitter.com/squidfunk

nav:
  - Home: index.md
  - Ansible 入门:
    - 1. Ansible 介绍: test.md
    - 2. 安装 Ansible: test.md
    - 3. 快速开始: test.md
    - 4. 认识主机清单: test.md
    - 5. Patterns 匹配: test.md
    - 6. 使用 ad-hoc 命令: test.md
    - 7. 熟悉 ansible 命令: test.md
    - 8. 使用 Playbook: test.md
    - 9. 包含和角色: test.md
    - 10. 使用变量: test.md
    - 11. Facts 数据: test.md
    - 12. Jinja2 模板语法: test.md
    - 13. 条件判断与循环: test.md
    - 14. Blocks: test.md
    - 15. Playbook 高级特性: test.md 
    - 扩展阅读(深入必读):
      - 1. YAML 语法: test.md
      - 2. Vaults 加密数据: test.md
      - 3. 关键字使用: test.md
      - 4. 模块索引: test.md
      - 5. Ansible 配置: test.md
  - Ansible 进阶: test.md
  - Ansible 开发: test.md
  - Ansible 认证: test.md
  - Ansible 其他:
    - test1: test.md
    - test2: test.md
  - About: about.md
  • 在docs 目录下创建 Markdown 文件
[root@sre mkdocs]# ll docs
总用量 12
-rwxr-xr-x 1 root root  6 3月  20 12:40 about.md
-rwxr-xr-x 1 root root  6 3月  20 12:38 index.md
-rwxr-xr-x 1 root root 15 3月  20 14:58 test.md
  • 启动 mkdocs
mkdocs serve -a 0.0.0.0:5000

img

第五步：编程成静态网页

  • 切换到项目路径下，编译
cd /home/application/mkdocs

[root@sre mkdocs]# mkdocs build
INFO     -  Cleaning site directory
INFO     -  Building documentation to directory: /home/application/mkdocs/
INFO     -  Documentation built in 0.29 seconds


#编译后的静态网页文件
[root@sre mkdocs]# ll site
总用量 56
-rw-r--r-- 1 root root 23382 3月  20 15:06 404.html
drwxr-xr-x 2 root root    24 3月  20 15:06 about
drwxr-xr-x 5 root root    58 3月  20 15:06 assets
-rw-r--r-- 1 root root 24342 3月  20 15:06 index.html
drwxr-xr-x 2 root root    31 3月  20 15:06 search
-rw-r--r-- 1 root root   552 3月  20 15:06 sitemap.xml
-rw-r--r-- 1 root root   219 3月  20 15:06 sitemap.xml.gz
drwxr-xr-x 2 root root    24 3月  20 15:06 test
  • 配置nginx，访问静态网页
[root@sre conf.d]# vim mkdocs.conf 
server {
        listen          8080;
  
        location / {
	        root    /home/application/mkdocs/site;
        }

}
  • 访问

img