跳转至

01-Mkdocs文档服务器

参考博文

https://blog.csdn.net/weixin_34341117/article/details/92097716
https://cyent.github.io/markdown-with-mkdocs-material/

mkdocs-material介绍

符合google material ui规范的静态文档网站生成器，使用markdown进行文档书写

MkDocs 可以同时编译多个markdown文件，形成书籍一样的文件。有多种主题供你选择，很适合项目使用。

MkDocs 是快速，简单和华丽的静态网站生成器，可以构建项目文档。文档源文件在 Markdown 编写，使用单个 YAML 配置文件配置。

mkdocs

  1. python编写的markdown解释器、编译器，带有本地cli工具
  2. 自带基于Tornado的小型http服务，用于本地调试
  3. 内置一键式发布至GitHub Pages
  4. 内置mkdocs风格、readthedocs风格的主题，并支持自定义主题
  5. 支持调用python模块实现语法及渲染的扩展

mkdocs-material

  1. python模块，符合google material ui规范的mkdocs自定义主题
  2. 针对特定语法、功能做了渲染优化
  3. 根据客户端浏览器页面尺寸自动缩放，对PC、移动设备都友好
  4. 丰富的页面配色，多达19种主体配色和16种悬停链接文字配色
  5. 支持中文搜索
  6. 支持统计功能，如百度统计，谷歌统计

mkdocs安装

配置国内pip源

 mkdir -p /root/.pip/
 vim .pip/pip.conf
 [global]
index-url = http://pypi.douban.com/simple
trusted-host = pypi.douban.com

mkdir -p ~/.pip/
cat > ~/.pip/pip.conf<<EOF
[global]
index-url = https://pypi.tuna.tsinghua.edu.cn/simple

[install]
trusted-host=pypi.tuna.tsinghua.edu.cn
EOF

安装mkdocks

yum -y install python36 python36-pip
pip3.6 install mkdocs mkdocs-material

mkdocs配置

初始化项目

mkdocs new my-project

会生成my-project目录，进入该目录里，可以看到默认放置了一些文件，包括mkdocs.yml，这是主配置文件

修改主题

mkdocs.yml里添加:

cat >>my-project/mkdocs.yml<<EOF
theme:
  name: material
EOF

运行mkdocs

在my-project目录里执行

cd /root/my-project/
mkdocs serve -a 192.168.1.3:8000

访问mkdocs

通过浏览器访问本地ip的8000端口（比如http://192.168.1.3:8000/） 查看效果，如图所示

image-20230110162553294

发布到个人HTTP Server

通过mkdocs build编译出html并手动同步至http server的根目录

生成站点文件

在git目录下执行命令

mkdocs build

命令执行完毕后可以看到site目录

发布至http server

将site目录里的所有东西拷贝到http server的根目录下

mkdocs.yml注意事项

由于是yaml格式，因此首先要符合yaml的语法要求

docs下需要一个index.md，作为站点首页

文档层次结构虽然可以很多层，但最佳实践是控制在2层内，最多不要超过3层，否则展示会不够友好

添加页面

在my-project/docs/里放置.md文件，可以自行组织目录结构

然后在mkdocs.yml里添加，比如这样:

nav:
  - 介绍: index.md
  - 安装:
      - 本地环境搭建: install/local.md
      - 发布至GitHub Pages: install/github-pages.md
      - 发布至自己的HTTP Server: install/http-server.md
  - 语法:
      - 语法总览: syntax/main.md
      - 标题: syntax/headline.md
      - 段落: syntax/paragraph.md
  • 上面的index.md就是放置在my-project/docs/index.md
  • 上面的local.md就是放置在my-project/docs/install/local.md

添加常用扩展

只有添加了扩展，才能完美使用mkdocs-material官方支持的所有markdown语法

mkdocs.yml里添加:

markdown_extensions:
  - admonition
  - codehilite:
      guess_lang: false
      linenums: false
  - toc:
      permalink: true
  - footnotes
  - meta
  - def_list
  - pymdownx.arithmatex
  - pymdownx.betterem:
      smart_enable: all
  - pymdownx.caret
  - pymdownx.critic
  - pymdownx.details
  - pymdownx.emoji:
      emoji_generator: !!python/name:pymdownx.emoji.to_png
  - pymdownx.inlinehilite
  - pymdownx.magiclink
  - pymdownx.mark
  - pymdownx.smartsymbols
  - pymdownx.superfences
  - pymdownx.tasklist
  - pymdownx.tilde

Mkdocs扩展

添加百度统计

先在百度统计里创建添加站点，以本站为例:

确定后会看到javascript代码，复制代码

在docs目录下新建js目录，并在docs/js目录里放置baidu-tongji.js，将复制的代码粘贴进来，以本站为例:·

var _hmt = _hmt || [];
(function() {
  var hm = document.createElement("script");
  hm.src = "https://hm.baidu.com/hm.js?51fafb2ac8f80ecf43b05bb4cc281020";
  var s = document.getElementsByTagName("script")[0];
  s.parentNode.insertBefore(hm, s);
})();

最后在mkdocs.yml里新增如下配置:

extra_javascript:
    - 'js/baidu-tongji.js'

效果: js会自动加在前，以本站为例:

mkdocs层级关系

一个.md里只能有一个#（h1），下面是多个##

如果有多个#（h1），则是不标准的目录结构，不会自动生产目录

如果.md没有用#（h1），则mkdocs会自动将该文件在mkdocs.yml里对应的page名用h1效果展示在第一行

支持中文搜索

虽然search功能(lunr.js)暂不直接支持中文，但测试发现设置为日语后，中文和英文搜索都可以使用

extra:
  search:
    language: 'jp'

测试发现，当站点文字比较多的时候，有的时候第一次搜索加载查询的时间比较久，会引起浏览器假死，多等一会就行了。比如本站点内容比较多，搜索就比较卡

为什么上面说的是有的时候，因为我的另一个站点文字数量比本站还要多，但搜索确很快，等以后熟悉了lunr.js后再来解决这个问题

另外，搜索对话框的显示文字，默认为英文，可以设置为中文。例如"search"改为中文后就叫"搜索"

theme:
  language: 'zh'

参考资料

MkDocs 支持中文搜索

https://github.com/bxiaopeng/mkdocs

个人配置参考

site_name: Chrisjing的运维知识体系
#repo_url: https://github.com/linuxchrisking
repo_url: https://gitee.com/chriscentos
theme:
  name: material
  language: 'zh'
  features:
# 开启文档标题侧边栏
#    - toc.integrate

extra_css:
  - stylesheets/extra.css
extra:
  search:
    language: 'jp'
  palette:
    primary: 'Blue Grey'
    accent: 'Pink'
  social: 
    - icon: fontawesome/brands/twitter
      link: https://twitter.com/squidfunk
extra_javascript:
    - 'js/baidu-tongji.js'

markdown_extensions:
  - admonition
  - codehilite:
      guess_lang: false
      linenums: true
  - toc:
      permalink: true
  - footnotes
  - meta
  - def_list
  - pymdownx.arithmatex
  - pymdownx.betterem:
      smart_enable: all
  - pymdownx.caret
  - pymdownx.critic
  - pymdownx.details
  - pymdownx.emoji:
      emoji_generator: !!python/name:pymdownx.emoji.to_png
  - pymdownx.inlinehilite
  - pymdownx.magiclink
  - pymdownx.mark
  - pymdownx.smartsymbols
  - pymdownx.superfences
  - pymdownx.tasklist
  - pymdownx.tilde