mkdocs

安装¶

环境配置¶

Note

环境为CentOS7

mkdocs安装需要python3的环境，CentOS7默认为python2，这里使用miniconda3配置python3的环境。

$ mkdir -p ~/miniconda3
$ wget https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh -O ~/miniconda3/miniconda.sh
$ bash ~/miniconda3/miniconda.sh -b -u -p ~/miniconda3
$ rm -rf ~/miniconda3/miniconda.sh

# 初始化
$ ~/miniconda3/bin/conda init bash
$ source ~/.bashrc

安装¶

安装mkdocs及mkdocs-material主题

$ pip install mkdocs mkdocs-material

项目创建¶

创建mkdocs项目，mkdocs站点的所有文档、生成的静态文件均在此目录内。

生成的mkdocs.yml为项目配置文件，docs目录存放需要编写的markdown文档。

$ mkdocs new mydocs
INFO    -  Creating project directory: mydocs
INFO    -  Writing config file: mydocs/mkdocs.yml
INFO    -  Writing initial docs: mydocs/docs/index.md

启动本地服务器浏览生成的mkdocs站点

$ cd mydocs
$ mkdocs serve -a 0.0.0.0:8000
INFO    -  Building documentation...
INFO    -  Cleaning site directory
INFO    -  Documentation built in 0.05 seconds
INFO    -  [18:12:36] Watching paths for changes: 'docs', 'mkdocs.yml'
INFO    -  [18:12:36] Serving on http://0.0.0.0:8000/

在浏览器中打开 http://ip:8000

更换主题¶

编辑 mkdocs.yml 文件以更换主题。

初始配置文件内容。

site_name: My Docs

更换为 material 主题。

site_name: My Docs
theme:
  name: 'material'

配置静态站点¶

将md文件生成HTML文件进行部署，使用静态文件安全性和速度更有保障。

生成的静态文件在 ~/mydocs/site 内，然后使用apache或Nginx进行配置部署。

$ cd mydocs
$ mkdocs build
INFO    -  Cleaning site directory
INFO    -  Building documentation to directory: ~/mydocs/site
INFO    -  Documentation built in 0.07 seconds

这里以apache为例。

<VirtualHost *:80>
        ServerName  docs.domain.cn
        DocumentRoot "/home/docks/mydocs/site"
        ErrorLog /home/git/log
        <Directory "/home/docks/mydocs/site">
                Options Indexes FollowSymLinks
                AllowOverride all
                Require all granted
        </Directory>
</VirtualHost>

内容编写¶

一般通过目录对文档内容进行分类，如catalog01、catalog02、catalog03。

$ cd mydocs
$ mkdir docs/{catalog01,catalog02,catalog03}

# 编写对应的markdown文档
$ vim docs/catalog01/pyhton.md
## python安装
测试
## python基本语法
测试

$ vim docs/catalog02/perl.md
## perl安装
测试
## perl基本语法
测试

$ vim docs/catalog02/R.md
## R安装
测试
## R基本语法
测试

然后在mkdocs.yml配置文件内添加上面编写的markdown文档。

site_name: My Docs
theme:
  name: 'material'

nav:
    - 文档首页: 'index.md'
    - 'python':
        - python基础 : 'catalog01/pyhton.md'
    - 'perl':
        - perl基础 : 'catalog02/perl.md'
    - 'python':
        - R基础 : 'catalog03/R.md'

最后转成静态文件发布

$ mkdocs build

Note

为方便文档编写，可以使用vscode连接远程服务器编写markdown文档。

配置¶

语法¶

升级¶

Warning

由于跨大版本升级，有许多地方需要更改，因此升级之前需要先认真阅读官方升级文档。

8.x to 9.x¶

由于mkdocs的搜索功能一直有点问题无法使用 (正在初始化搜索引擎, Initializing search engine)，比较影响用户体验。查了诸多资料之后发现可能某种原因触发了软件bug导致的，官方开发人员在 github issue 上回复9.x版中修复了该bug，因此进行了此次升级。

罪魁祸首：chrome F12中的js报错

lunr.ja.min.js:1 Uncaught (in promise) TypeError: t.toLowerCase is not a function
    at lunr.ja.min.js:1:862
    at Array.map (<anonymous>)
    at e.ja.tokenizer (lunr.ja.min.js:1:823)
    at t.Builder.add (lunr.js:2479:23)
    at t.Builder.<anonymous> (index.ts:217:14)
    at t (lunr.js:53:10)
    at new U (index.ts:177:18)
    at index.ts:146:15
    at Generator.next (<anonymous>)
    at s (search.16e2a7d4.min.js:1:953)

changelog:

升级后搜索功能恢复正常
代码高亮出现了bug，单行代码超过代码框的部分未被高亮
mkdocs build 编译时间从18s增加到了25s

# 查看版本升级前的版本
$ pip show mkdocs-material
Name: mkdocs-material
Version: 8.5.10
Summary: Documentation that simply works
Home-page: None
Author: None
Author-email: Martin Donath <martin.donath@squidfunk.com>
License: None
Location: /home/mkdocs/software/miniconda3/lib/python3.9/site-packages
Requires: requests, pymdown-extensions, jinja2, mkdocs-material-extensions, pygments, markdown, mkdocs
Required-by: mkdocs-print-site-plugin

# 升级
$ pip install --upgrade --force-reinstall mkdocs-material

# 查看升级后的版本
$ pip show mkdocs-material
Name: mkdocs-material
Version: 9.5.13
Summary: Documentation that simply works
Home-page: None
Author: None
Author-email: Martin Donath <martin.donath@squidfunk.com>
License: None
Location: /home/mkdocs/software/miniconda3/lib/python3.9/site-packages
Requires: mkdocs-material-extensions, requests, markdown, paginate, babel, jinja2, pymdown-extensions, mkdocs, regex, colorama, pygments
Required-by: mkdocs-print-site-plugin

# 配置文件备份，以防后面修改配置文件过程中出错
$ cp mkdocs.yml mkdocs_240314.yml

升级后运行 mkdocs serve，查看是否能正常运行，并根据该命令运行的日志内容对配置文件mkdocs.yml内容进行修改。

配置文件中的部分改动

material.emoji.twemoji 改为 material.extensions.emoji.twemoji

prebuild_index 特性不再支持需要删除

更改material软件包中的文件，以启用访问计数功能。

lib/python3.9/site-packages/material/partials/content.html

{#-
  This file was automatically generated - do not edit
-#}
{% if "tags" in config.plugins %}
  {% include "partials/tags.html" %}
{% endif %}
{% include "partials/actions.html" %}
{% if not "\x3ch1" in page.content %}
  <h1>{{ page.title | d(config.site_name, true)}}</h1>
{% endif %}
{{ page.content }}
<font size="2" color="grey">本文阅读量&nbsp;<span id="busuanzi_value_page_pv"></span>&nbsp;次</font>
<br>
<font size="2" color="grey">本站总访问量&nbsp;<span id="busuanzi_value_site_pv"></span>&nbsp;次</font>
{% include "partials/source-file.html" %}
{% include "partials/feedback.html" %}
{% include "partials/comments.html" %}

site_name: 作重计算平台用户手册

copyright: 'Copyright &copy; 2023 <a href="http://croplab.hzau.edu.cn" target="_blank">华中农业大学作物遗传改良全国重点实验室</a>'

theme:
  name: material
  custom_dir: overrides
  language: 'zh'  # 配置语言
  features:
    - content.code.annotate # 代码注释
    - navigation.top # 长页面点击快速回到页面顶部
  palette: # 白天黑夜切换
    - media: "(prefers-color-scheme: light)"
      scheme: default
      toggle:
        icon: material//weather-sunny
        name: Switch to dark mode
    - media: "(prefers-color-scheme: dark)"
      primary: teal
      scheme: slate
      toggle:
        icon: material/weather-night
        name: Switch to light mode


extra_javascript:
    - http://busuanzi.ibruce.info/busuanzi/2.3/busuanzi.pure.mini.js # 访问统计
    - 'js/baidu-tongji.js' # 百度统计
    - 'js/tablesort.js' # 表格排序

markdown_extensions:
  - pymdownx.snippets: # 往文档中嵌入其它文档的内容
      check_paths: true
  - pymdownx.arithmatex
  - pymdownx.superfences
  - pymdownx.details # 提示块可折叠
  - pymdownx.magiclink
  - pymdownx.tilde # 删除线下标
  - pymdownx.caret # 下划线上标
  - pymdownx.emoji
  - pymdownx.mark # 文本高亮
  - pymdownx.smartsymbols # 符号转换
  - pymdownx.critic # 增加删除修改高亮注释，可修饰行内或段落
  - pymdownx.tabbed: # tab块
      alternate_style: true
  - pymdownx.snippets:
      base_path: ./codes/
  - pymdownx.inlinehilite # 行内代码高亮
  - pymdownx.magiclink  # 自动识别超链接
  - pymdownx.superfences  # 代码嵌套在列表里
  - pymdownx.highlight: # 代码高亮，显示行号
      linenums: true
      linenums_style: pymdownx-inline
  - pymdownx.emoji: # 表情
      emoji_index: !!python/name:materialx.emoji.twemoji
      emoji_generator: !!python/name:materialx.emoji.to_svg
  - toc: # 锚点
      permalink: true
      slugify: !!python/object/apply:pymdownx.slugs.slugify {kwds: {case: lower}} # 自定义页面锚点，如 ## Custom Heading {#custom-anchor}
  - admonition # 提示块
  - footnotes  # 脚注
  - meta  # 定义元数据，通过文章上下文控制，如disqus
  - pymdownx.betterem:  # 对加粗和斜体更好的检测
      smart_enable: all
  - pymdownx.tasklist:  # 复选框checklist
      custom_checkbox: true
  - attr_list #增加css-html样式，例如按钮，比如图片定义大小，caption，设置新窗口中打开链接
  - md_in_html
  - pymdownx.arithmatex  # 数学公式



plugins:
  - glightbox: # 图片点击放大 https://github.com/blueswen/mkdocs-glightbox
  - search: # 下面的设置以便中文搜索
      separator: '[\s\u200b\-]'
      lang: ja
  - git-revision-date-localized: # 配合git，以显示每个页面的创建和修改时间
      type: date
      enable_creation_date: true
      fallback_to_build_date: true
  - tags:
      tags_file: tags.md
  - exclude: # 编译静态页面时排除的文件和目录
      glob:
        - "tmp/*"
        - "*.tmp"
        - "*.pdf"
        - "*.gz"
      regex:
        - '.*\.(tmp|bin|tar)$'
  - print-site: # 将所有页面都在一个页面内生成
      # 防止生产静态页面时报错，需添加以下两个选项
      enumerate_headings: false  
      add_table_of_contents: false  

nav:
  - 介绍: index.md
  - 集群相关: 
    - 常见问题(FAQ) : cluster/062-FAQ.md
    - 集群硬件资源: cluster/015-cluster-hardware.md 
    - 用户资源限制: cluster/012-user-resource-limit.md
    - 集群登录: cluster/073-login-outside.md
    - LSF基本使用: cluster/016-LSF.md
    - 集群账号申请: cluster/033-cluster-account-application.md
    - 账号密码修改: cluster/008-change-password.md
    - 作业队列划分: cluster/031-cluster-lsf-queue.md
    - 备份存储使用: cluster/022-backup-storage.md
    - 账户注销: cluster/037-cluster-account-deletion.md
    - 集群考试内容: cluster/036-examination-syllabus.md
    - 集群收费标准: cluster/027-cluster-fee.md
    - 论文致谢: cluster/057-acknowlege.md
    - 数据使用规范: cluster/058-data-manage.md
    - 数据共享: cluster/061-data-share.md
    - GPU节点使用: cluster/068-GPU-node.md
    - 文件扫描: cluster/070-file-scan.md
    - 文件完整性检查: linux/077-file-check.md
    - 使用本地存储: cluster/114-local-storage.md
    - 数据下载: cluster/080-download-data.md
  - 应用软件: 
    - 介绍: app/index.md
    - 软件安装: app/066-software-installation.md
    - 生信数据库: app/025-bioinformatics-database.md
    - 短序列比对输出bam: app/054-sam-to-bam.md
    - fq比对建议: app/071-fq2bam.md
    - 多语言gzip文件读写: app/056-api_read_write_gzip.md
    - 常用生信数据处理操作: app/096-biodata-manipulate.md
    - 运行32位软件: app/101-run-32bit-software.md
    - gcc: app/034-gcc.md
    - glibc: app/095-glibc.md
    - module: app/004-Module.md
    - singularity: app/007-singularity.md
    - perl: app/005-perl.md
    - R: app/006-R.md
    - RStudio: app/105-rstudio.md
    - MySQL: app/014-mysql-database.md
    - python: app/029-python.md
    - mamba: app/099-mamba.md
    - nextflow: app/035-nextflow.md

  - linux: 
    - linux 基础: linux/065-Linux-basics.md
    - linux 练习: linux/116-linux-exercise.md
    - linux 学习环境: linux/093-linux-exercise-env.md
    - linux 远程登录工具: linux/094-login-tools.md
    - linux tricks: linux/068-Linux-tricks.md
    - linux 中文支持: linux/003-Linux-Chinese-support.md
    - linux 无root编译安装软件: linux/039-Linux-software-installation.md
    - 使用SSH密钥登录服务器: linux/009-RSA-key-login.md
    - 在 Fish 环境中使用 module: linux/132-fish-shell-module.md
  - OnePage: print_page/

插件¶

mkdocs-print-site-plugin¶

可以将所有mkdocs页面生成一个页面，方便打印成pdf。

文档：https://timvink.github.io/mkdocs-print-site-plugin/

安装：

pip3 install mkdocs-print-site-plugin

配置：

在mkdocs.yml 中添加print-site及相关选项。

使用默认选项时，生产静态页面会出现报错 The page 介绍 (app/index.md) does not start with a level 1 heading.This is required for print page Table of Contents and/or enumeration of headings。因此需要将 enumerate_headings add_table_of_contents 置为 false

mkdocs.yml

plugins:
  - print-site:
      enumerate_headings: false
      add_table_of_contents: false

使用：

打开页面 url/print_page/ 即可

访问统计¶

https://blog.csdn.net/arnolan/article/details/105026738

https://ohevan.com/vercount-website-counter-busuanzi-alternative.html

其他实用插件¶

https://github.com/mkdocs/catalog 探索优秀的mkdocs项目和插件

mkdocs-charts-plugin 在mkdocs中创建图表

mkdocs-blogging-plugin 博客插件，支持 Tag

mkdocs-jupyter 在mkdocs中使用jupyter

markdown-exec 在mkdown代码块中执行代码，支持bash python mkdown 等

Termynal 动画终端窗口

mkdocs-categories-plugin

mkdocs-alias-plugin build时自定义标题

mkdocs-live-edit-plugin 在线写mkdocs文档

其它¶

中文技术文档的写作规范¶

https://github.com/ruanyf/document-style-guide

在新网页中打开链接¶

[pymdown拓展语法](https://facelessuser.github.io/pymdown-extensions/extensions/arithmatex/){target="_blank"}

搜索功能¶

mkdocs 官方准备重头开发文档搜索模块以代替 Lunr.js，进展见 Towards better documentation search #6307。

搜索功能有时候会抽风，如果发现搜索功能异常，在浏览器中查看 http://url/search/search_index.json 的内容是否正常。

mkdocs build --dirty 时只会索引更改过的页面，导致搜索功能异常，因此少量修改时可以使用原来的索引，操作如下：

cp site/search/search_index.json . && mkdocs build --dirty && cp search_index.json site/search/

文档具有较大幅度改动时使用 mkdocs build --clean 生成完整的索引。

中文搜索支持：

https://cloud.tencent.com/developer/article/2303134

https://zhuanlan.zhihu.com/p/411854801

Note

在 9.x 版中已经支持了中文搜索。

自定义锚点¶

在写文档过程中经常有中文标题或中英文混杂的各级标题，URL引用或页面交叉引用时风格不一，如中文标题的锚点会变为 #_1，而英文或中英文混杂的直接为英文。在标题后面添加 {#custom-anchor} 即可自定义锚点。

如标题 ## 载入python {#load-python}，网页链接引用时的URL为 http://hpc.ncpgr.cn/app/029-python/#load-python，其它站内文档交叉引用的链接为 [python使用](../app/029-python/#load-python)。

中文锚点自动转拼音¶

使用 pymdownx.slugs.slugify 功能可以保留中文锚点不被转成类似 #_1 的形式，但 pymdownx.slugs.slugify 对中文做处理的时候会对中文进行 utf-8 编码，导致URL复制后出现类似乱码的情况，如 中文标题 会复制粘贴后显示为 %E4%B8%AD%E6%96%87%E6%A0%87%E9%A2%98。

python有个包 python-slugify 用于将字符串转成URL友好的格式，如可以将 中文标题 转成 zhong-wen-biao-ti 这样的汉语对应的拼音ASCII字符串。

from slugify import slugify
title = "中文标题"
slug = slugify(title)
print(slug)  # 输出: "zhong-wen-biao-ti"

利用这个包可以对 pymdownx.slugs.slugify 模块进行改写，首先安装这个包 pip install python-slugify，改写 slugs.py 文件（添加下面高亮的2行代码）。

lib/python3.9/site-packages/pymdownx/slugs.py

import re
import unicodedata
import functools
from urllib.parse import quote
from . import util
from slugify import slugify as slugifyx # 引入slugify中的slugify函数，并重命名为slugifyx，以免与代码中原有的slugify冲突


RE_TAGS = re.compile(r'</?[^>]*>', re.UNICODE)
RE_INVALID_SLUG_CHAR = re.compile(r'[^\w\- ]', re.UNICODE)
RE_SEP = re.compile(r' ', re.UNICODE)
RE_ASCII_LETTERS = re.compile(r'[A-Z]', re.UNICODE)


def _uslugify(text, sep, case="none", percent_encode=False, normalize='NFC'):
    """Unicode slugify (`utf-8`)."""

    # Normalize, Strip html tags, strip leading and trailing whitespace, and lower
    slug = RE_TAGS.sub('', unicodedata.normalize(normalize, text)).strip()

    if case == 'lower':
        slug = slug.lower()
    elif case == 'lower-ascii':
        def lower(m):
            """Lowercase character."""
            return m.group(0).lower()

        slug = RE_ASCII_LETTERS.sub(lower, slug)
    elif case == 'fold':
        slug = slug.casefold()

    # Remove non word characters, non spaces, and non dashes, and convert spaces to dashes.
    slug = RE_SEP.sub(sep, RE_INVALID_SLUG_CHAR.sub('', slug))

    # 使用slugifyx函数对字符串进行处理
    slug = slugifyx(slug)

    return quote(slug.encode('utf-8')) if percent_encode else slug

在toc中启用 pymdownx.slugs.slugify

markdown_extensions:
  - toc: 
      permalink: true 
      slugify: !!python/object/apply:pymdownx.slugs.slugify {kwds: {case: lower}}

标题 ## 载入python，网页链接引用时的URL自动变为 http://hpc.ncpgr.cn/app/029-python/#zai-ru-python，其它站内文档交叉引用的链接为 [python使用](../app/0029-python/#zai-ru-python)。

这里有个小bug，中英文混排时英文与后面的中文之间如果没有空格，会将该英文单词与该汉字的拼音转成一个字符串，如 安装python模块 会转成 an-zhuang-pythonmo-kuai，安装python 模块则正常转换 an-zhuang-python-mo-kuai。

build 策略¶

mkdocs build 默认使用了 --clean 选项，即会在build之前删掉所有之前build时创建的静态文件，如果文档数量较多，整个过程速度会比较慢，如本站build的时间约为25秒，build期间网站不可使用。如果修改比较频繁，则比较影响使用体验。

因此对大型文档网站，只对部分页面进行了修改，可以使用mkdocs build --dirty，只build修改了页面，速度会快很多，如本站使用mkdocs build --dirty后build的时间缩短为不到2秒。

mkdocs build --dirty 对文档搜索和OnePage插件使用有影响，应慎重使用。

官方解释

For large sites the build time required to create the pages can become problematic, thus a "dirty" build mode was created. This mode simply compares the modified time of the generated HTML and source markdown. If the markdown has changed since the HTML then the page is re-constructed. Otherwise, the page remains as is. It is important to note that this method for building the pages is for development of content only, since the navigation and other links do not get updated on other pages.

为避免大型文档在 build 期间不可访问，可将 build 输出到临时目录，然后替换静态站点，具体操作如下。每次 build 时执行这个脚本即可。

build.sh

# 每次修改之后将文档推送到gitee私人仓库备份
git add -A
git commit -m "$(date)"    
git push -u origin master

# build 输出到临时目录，然后再替换正式目录
mkdir site-tmp
mkdocs build --clean -d site-tmp
mv site tmp
mv site-tmp site
rm -rf tmp/site

参考文档¶

使用 MkDocs 和 Material 主题搭建技术博客

本文阅读量次
本站总访问量次