MkDocs Markdown 项目文档工具部署&优化主题

背景: 
    之前写笔记基本使用了私有的wiz为知笔记,有些笔记可能需要大纲一样展示出来,碰巧那天看到一个博主的Ansible博客,感觉还挺不错,就试了下,很简约,可以渲染 Markdown 成静态HTML,很符合我的需求
MkDocs Markdown 项目文档工具部署&优化主题
  
环境: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/
效果:
MkDocs Markdown 项目文档工具部署&优化主题

第四步:优化主题

mkdocs 官方提供了  默认主题 和 ReadTheDocs 主题,其他主题可以去github 上查找【https://github.com/mkdocs/mkdocs/wiki/MkDocs-Themes】
还是有很多模板可供选择的
MkDocs Markdown 项目文档工具部署&优化主题
我这里选择了 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: fxkjnj.com
repo_url: https://fxkjnj.com

site_name: doc.fxkjnj.com
site_description: doc.fxkjnj.com
site_author: fxkjnj.com
site_url: https://doc.fxkjnj.com
copyright: Copyright © 2022 <a href="https://fxkjnj.com">Powered by fxkjnj.com 版权所有</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
MkDocs Markdown 项目文档工具部署&优化主题

第五步:编程成静态网页

  • 切换到项目路径下,编译
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;
        }

}
  • 访问
MkDocs Markdown 项目文档工具部署&优化主题

本文版权归 飞翔沫沫情 作者所有,欢迎转载,但未经作者同意必须保留此段声明,且在文章页面明显位置给出 原文链接 如有问题, 可发送邮件咨询,转贴请注明出处:https://www.fxkjnj.com/3650/

(1)
打赏 WeChat WeChat Alipay Alipay
上一篇 2022年3月7日 上午10:01
下一篇 2022年3月20日 下午11:18

相关推荐

发表评论

登录后才能评论
分享本页
返回顶部