跳转至

MkDocs

Introduction

MkDocs

MkDocs is a fast, simple and downright gorgeous static site generator that’s geared towards building project documentation. Documentation source files are written in Markdown, and configured with a single YAML configuration file.

MkDocs是基于Markdown文档和YAML格式配置文件的快速静态站点生成器，主要用于构建项目文档，可以将Markdown文档转化为静态网站

MkDocs采用Python编写，使用Python-Markdown解析Markdown文件，使用Pygments语法高亮代码，使用Jinja模板引擎渲染Markdown文件

MkDocs-Material

Material for MkDocs is a powerful documentation framework on top of MkDocs, a static site generator for project documentation.

MkDocs-Material是一个基于MkDocs的主题框架，它提供了一个简洁、现代的界面，支持多种语言，支持多种配置，并集成了一系列实用插件 👍

MkDocs-Material的设计理念
  • It's just Markdown: 你只需要了解Markdown语法和专注于你的内容，而无需关注其它的复杂事，让MkDocs-Material帮你完成HTML && CSS && JavaScript的工作
  • Works on all devices: 项目结构和文档在不同设备上自动调整，并完美适配各种类型和尺寸的显示屏
  • Made to measure: 优良的可扩展性，提供丰富的配置选择和行为表现
  • Fast and lightweight: 上层的性能表现，绝佳的用户反馈
  • Accessible: 各种设备都可以使用
  • Open Source: 开源，MIT协议

Installation

MkDocs由Python编写，因此使用Python包作为安装单元

官方建议

推荐使用虚拟环境进行包管理

通过pip进行安装

1
2
pip install mkdocs
pip install mkdocs-material # Themes

使用如下命令查看是否安装完成：

1
mkdocs --version

显示版本号则安装成功，否则可以使用如下命令：

1
python3 -m mkdocs --version

将Python目录下的Scripts加入到环境变量PATH中即可实现上一条

Linux下支持的安装方式
1
sudo apt install mkdocs

Usage

创建站点

创建站点
1
mkdocs new <dir_name>

MkDocs 在目标目录下创建项目文件夹

项目结构
1
2
3
4
.
├── docs # 文档文件夹
│   └── index.md # 首页
└── mkdocs.yml # 配置文件

本地渲染

1
mkdocs serve

打开浏览器，输入http://127.0.0.1:8000即可本地访问站点

在运行站点的同时，也可以修改站点信息，都可以实时在浏览器显示更改

构建站点

经过构建之后就可以看到渲染

1
mkdocs build

构建完成后会出现一个新的目录site/

使用建议

对于远程部署来说，最好只上传原始的Markdown文档到服务器，然后在服务器端进行构建生成站点，因为MkDocs的版本变化可能导致本地构建的站点上传至服务器时无法正常显示 

1
site/

远程部署

为了能在远程看到站点渲染，需要进行远程部署

GitHub

通常来说，使用GitHub Pages构建是最为常见的

项目站点
1
mkdocs gh-deploy

执行上述命令后MkDocs会

  1. 创建远程分支gh-pages
  2. 执行mkdocs build命令
  3. 将当前目录下的site/中的内容推送到远程分支

使用建议

可以在主分支上上传项目源文档，利用gh-pages分支上传构建后的站点文档

用户站点
1
2
3
4
5
6
7
# 假设项目结构如下
.
├── Project
│   ├── docs
│   │   └── index.md
│   └── mkdocs.yml
└── User.github.io

则配置用户站点的方法：

1
2
cd User.github.io
mkdocs gh-deploy --config-file ../Project/mkdocs.yml --remote-branch master

这里需要显式指出配置文件的位置和推送分支

注意

如果不指明推送分支，默认推送分支为master

Configuration

进入mkdocs.yml进行站点配置

注意

以下配置仅对主题MkDocs-Material有效，不同主题支持的配置不同，详见官方文档

站点信息

站点名是唯一的硬性配置要求

mkdocs.yml
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
# 项目信息
site_name: <site_name> # 唯一配置要求
site_url: https://example.com
site_description: >-
    an example website
site_author: Author_Name
site_dir: site # 文档存放位置
site_favicon: images/favicon.ico

# 代码仓库信息
repo_name: Your_Repo_Name
repo_url: Your_Repo_URL

# [版权信息](MkDocs.md#5.1.8%20底栏)
copyright: Copyright Info

导航栏

使用导航栏（Navigator）显示所有添加的页面

支持添加多级页面

所有的文档位置都采用与docs/的相对位置

mkdocs.yml
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
nav:
  - HOME: index.md
  - ABOUT: about.md
  - PAGES:
    - Page1: pages/page1.md
    - Page2:
      - Page2-1: pages/page2/page2-1.md
      - Page2-2: pages/page2/page2-2.md
    - Page3: pages/page3.md
  - License: License.md
  - Release Notes: notes.md
  - Blog:
      - blog.index.md

注意

添加的.md文档不应该以.开头，否则会被MkDocs忽略导致添加失败，如.foo.md

首页

通常根据习惯，浏览器都会把首页返回为一个index文件，所以MkDocs也采用index.md作为首页

然而有些展示仓库的网站会对README文件有特殊的展示（如GitHub），因此在MkDocs中如果把首页命名为README.md也会被其识别，但是在经过远程部署之后会被转化成index.html使得浏览器能够正确识别

注意

如果index.md和README.md同时存在，则README.md会被忽略

TOC

标题链接

让每个标题带上链接

默认为permalink=false，即不显示

启用为true后显示，也可以改成其它字符如#

1
2
3
markdown_extensions:
  - toc:
      permalink: true

基准标题

默认情况下基准标题为1

更改配置使得基准标题变化

1
2
3
4
markdown_extensions:
  - toc:
      baselevel: 2
      toc_depth: 3

分词符

分词符为使用了标题链接后显示的ID中的分隔符

默认情况下分词符为-

1
2
3
markdown_extensions:
  - toc:
      seperator: '_'

提示块

提示块扩展(Admonition, Call-out)非常好用

mkdocs.yml
1
2
3
4
markdown_extensions:
    - admonition
    - pymdownx.details # 提示块可折叠
    - pymdownx.superfences # 提示块可嵌套

用法

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
<!-- 基本用法 -->
!!! AdmonitionType
    Your Text Here

<!-- 添加标题 -->
!!! AdmonitionType "YourTitleHere"
    Your Text Here

<!-- 去除标题 -->
!!! AdmonitionType ""
    Your Text Here

<!-- 可折叠块：默认折叠 -->
??? AdmonitionType
    Your Text Here

<!-- 可折叠块：默认打开 -->
???+ AdmonitionType
    Your Text Here

<!-- 行内提示块：左侧 -->
!!! AdmonitionType inline "YourTitleHere"
    Your Text Here

<!-- 行内提示块：右侧 -->
!!! AdmonitionType inline end "YourTitleHere"
    Your Text Here

支持类型

Note

Abstract

Info

Tip

Success

Question

Warning

Failure

Danger

Bug

Example

Quote

代码块

配置

mkdocs.yml
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
markdown_extensions:
    - pymdownx.highlight:
        # 行号
        linenums: true
        # 每行行号生成锚点链接
        anchor_linenums: true
        line_spans: __span
    - pymdownx.inlinehilite
    - pymdownx.snippets # 从其它文件嵌入页面
    - pymdownx.superfences # 代码块嵌套
theme:
    name: material
    features:
        - content.code.copy # 代码块复制按键

用法

1
2
3
4
5
6
7
<!-- Code Block -->
``` Language CodeBlockAttributes
Your code here
```

<!-- Inline Code -->
`#!Language YourCodeHere`
用法 属性
添加标题 title="YourTitle"
起始行号 linenums="Num"
高亮特定行 hl_lines="line1 line2 ..."
hl_lines="line1-lineN"

列表

注意

多级列表需要4个空格才能识别

mkdocs.yml
1
2
3
4
5
6
markdown_extensions:
    # 定义列表
    - def_list
    # 任务列表
    - pymdownx.tasklist:
        custom_checkbox: true
定义列表样例

用于下定义 

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
`Lorem ipsum dolor sit amet`

:   Sed sagittis eleifend rutrum. Donec vitae suscipit est. Nullam tempus
    tellus non sem sollicitudin, quis rutrum leo facilisis.

`Cras arcu libero`

:   Aliquam metus eros, pretium sed nulla venenatis, faucibus auctor ex. Proin
    ut eros sed sapien ullamcorper consequat. Nunc ligula ante.

    Duis mollis est eget nibh volutpat, fermentum aliquet dui mollis.
    Nam vulputate tincidunt fringilla.
    Nullam dignissim ultrices urna non auctor.

任务列表样例 

1
2
3
4
5
6
- [x] Lorem ipsum dolor sit amet, consectetur adipiscing elit
- [ ] Vestibulum convallis sit amet nisi a tincidunt
    * [x] In hac habitasse platea dictumst
    * [x] In scelerisque nibh non dolor mollis congue sed et metus
    * [ ] Praesent sed risus massa
- [ ] Aenean pretium efficitur erat, donec pharetra, ligula non scelerisque
效果如下： - [x] Lorem ipsum dolor sit amet, consectetur adipiscing elit - [ ] Vestibulum convallis sit amet nisi a tincidunt * [x] In hac habitasse platea dictumst * [x] In scelerisque nibh non dolor mollis congue sed et metus * [ ] Praesent sed risus massa - [ ] Aenean pretium efficitur erat, donec pharetra, ligula non scelerisque

Tabs

配置

mkdocs.yml
1
2
3
4
5
6
7
8
markdown_extension:
    - pymdownx.superfences
    - pymdownx.tabbed:
        alternate_style: true
        # 生成tab链接
        slugify: !!python/object/apply:pymdownx.slugs.slugify
            kwds:
                case: lower

用法

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
=== "YourTitleHere"
    Your Text Here

<!-- 样例 -->
=== "C"

    ``` c
    #include <stdio.h>

    int main(void) {
      printf("Hello world!\n");
      return 0;
    }
    ```

=== "C++"

    ``` c++
    #include <iostream>

    int main(void) {
      std::cout << "Hello world!" << std::endl;
      return 0;
    }
    ```

表格

mkdocs.yml
1
2
markdown_extension:
    - tables

Mermaid

mkdocs.yml
1
2
3
4
5
6
markdown_extensions:
  - pymdownx.superfences:
      custom_fences:
        - name: mermaid
          class: mermaid
          format: !!python/name:pymdownx.superfences.fence_code_format

支持的类型

Diagrams - Material for MkDocs

脚注

mkdocs.yml
1
2
markdown_extensions:
    - footnotes

数学公式

完整信息

Math - Material for MkDocs

通常来说使用KaTex就足够站点使用

首先创建文件docs/javascripts/katex.js

docs/javascripts/katex.js
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
document$.subscribe(({ body }) => { 
  renderMathInElement(body, {
    delimiters: [
      { left: "$$",  right: "$$",  display: true },
      { left: "$",   right: "$",   display: false },
      { left: "\\(", right: "\\)", display: false },
      { left: "\\[", right: "\\]", display: true }
    ],
  })
})

然后在配置文件中添加

mkdocs.yml
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
markdown_extensions:
    - pymdownx.arithmatex:
        generic: true

extra_javascript:
    - javascripts/katex.js
    - https://unpkg.com/katex@0/dist/katex.min.js
    - https://unpkg.com/katex@0/dist/contrib/auto-render.min.js

extra_css:
    - https://unpkg.com/katex@0/dist/katex.min.css

格式化

格式化支持文本的高亮、删除线、替换、上下标等

mkdocs.yml
1
2
3
4
5
6
markdown_extensions:
  - pymdownx.critic
  - pymdownx.caret
  - pymdownx.keys
  - pymdownx.mark
  - pymdownx.tilde

格式化样例

```Markdown Text can be deleted and replacement text added. This can also be

combined into onea single operation. Highlighting is also possible and comments can be added inline.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18


Formatting can also be applied to blocks by putting the opening and closing tags on separate lines and adding new lines between the tags and the content.



<!-- 高亮文本 -->
- ==This was marked (highlight)==
- ^^This was inserted (underline)^^
- ~~This was deleted (strikethrough)~~
a
<!-- 上下标 -->
- H~2~O
- A^T^A

<!-- 键盘 -->
++ctrl+alt+del++
```

Emoji

mkdocs.yml
1
2
3
4
5
markdown_extensions:
  - attr_list
  - pymdownx.emoji:
      emoji_index: !!python/name:material.extensions.emoji.twemoji
      emoji_generator: !!python/name:material.extensions.emoji.to_svg

小提示

可以给文本添加小提示，如缩略语等

完整信息

Tooltips - Material for MkDocs

站内跳转

使用Markdown的链接格式进行站内跳转

1
2
[AltText](RelativePath/To/ThisFile)
[AltText](RelativePath/To/ThisFile#Section)

图片与媒体

把所有图片放到docs/img/下，并在你的文档中使用相对于docs/的路径使用图片链接格式即可

完整信息

Images - Material for MkDocs

Themes

默认配置

MkDocs默认主题：mkdocs和readthedoc

第三方主题库

MkDocs Themes · mkdocs/mkdocs Wiki

MkDocs-Material

配色

主题配色

MkDocs-Material支持2种颜色主题

属性值 内容
default 亮色主题
slate 暗色主题
mkdocs.yml
1
2
3
4
theme:
    name: material
    palette:
        scheme: default
内容配色
  • 基础配色(Primary Color)用于在文档头、侧边栏、文本链接等显示
  • 口音配色(Accent Color)用于在链接、按钮、滚动条等显示
mkdocs.yml
1
2
3
4
5
theme:
    name: material
    palette:
        primary: indigo
        accent: pink
支持的颜色 
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
red
pink
purple
deep purple
indigo -> 默认值
blue
light blue
cyan
teal
green
light green
lime
yellow
amber
orange
deep orange
brown -> 仅限primary
grey -> 仅限primary
blue grey -> 仅限primary
black -> 仅限primary
white -> 仅限primary
配色切换

可以让用户决定主题配色切换

mkdocs.yml
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
theme:
    name: material
    palette:
        # 亮色主题
        - scheme: default
          primary: pink
          accent: blue
          toggle:
            icon: material/brightness-7
            name: Switch to dark mode
        # 暗色主题
        - scheme: slate
          primary: red
          accent: indigo
          toggle:
            icon: material/brightness-4
            name: Switch to light mode

其中，icon必须指向有效的图标路径

常用icon

1
2
3
4
5
material/brightness-7  + material/brightness-4
material/toggle-switch + material/toggle-switch-off-outline
material/weather-night + material/weather-sunny
material/eye           + material/eye-outline
material/lightbulb     + material/lightbulb-outline
跟随系统

与系统配色保持一致的配色风格

只需要在scheme属性添加media属性

mkdocs.yml
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
theme:
    name: material
    palette:
        # 亮色主题
        - media: "(prefers-color-scheme: light)"
          scheme: default
          primary: green
          accent: yellow
          toggle:
            icon: material/brightness-7
            name: Switch to dark mode
        # 暗色主题
        - media: "(prefers-color-scheme: dark)"
          scheme: slate
          primary: pink
          accent: blue
          toggle:
            icon: material/brightness-4
            name: Switch to light mode
自动切换

一些新的操作系统允许在白天和夜晚自动切换配色

mkdocs.yml
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
theme:
    name: material
    palette:
        # 自动模式
        - media: "(prefers-color-scheme)"
          toggle:
            icon: material/brightness-auto
            name: Switch to light mode
        # 亮色主题
        - media: "(prefers-color-scheme: light)"
          scheme: default
          toggle:
            icon: material/brightness-7
            name: Switch to dark mode
        # 暗色主题
        - media: "(prefers-color-scheme: dark)"
          scheme: slate
          toggle:
            icon: material/brightness-4
            name: Switch to system preference
自定义配色

完整内容

自定义配色

字体

通常来说字体不用调

mkdocs.yml
1
2
3
4
5
theme:
    name: material
    font:
        text: Roboto
        code: Roboto Mono

完整信息

字体

语言

在配置文件中进行修改

mkdocs.yml
1
2
3
theme:
    name: material
    language: en

常用的语言

1
2
3
4
zh
zh-TW
zh-Hant
en

完整信息

支持的语言和语言切换器

图标

logo显示在侧边栏上

mkdocs.yml
1
2
3
theme:
    name: material
    logo: PathToYourLogoFile
站点图标

站点图标显示在浏览器标签页上

mkdocs.yml
1
2
3
theme:
    name: material
    favicon: PathToYourIconFile
MkDocs原生图标支持

MkDocs原生主题默认使用MkDocs favicon图标，如果使用自定义图标，在docs/下创建子目录img，并将图标文件.ico放入其中即可，无需修改任何配置

其它图标
mkdocs.yml
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
theme:
    name: material
    icon:
        logo: ... # 同[logo](MkDocs.md#logo)
        menu: ...
        alternate: ...
        search: ...
        share: ...
        close: ...
        top: ...
        edit: ... # 编辑此页图标
        view: ... # 查看页面源码图标
        repo: ... # 仓库图标
        admonition: ... # 提示块图标
        tag: ...
        previous: ... # 上一页
        next: ... # 下一页

图标实例

仓库图标

完整信息

Material-RepoIcon
1
2
3
4
5
6
fontawesome/brands/git
fontawesome/brands/git-alt
fontawesome/brands/github
fontawesome/brands/github-alt
fontawesome/brands/gitlab
fontawesome/brands/trash

代码图标
Material-CodeAction
1
2
material/pencil
material/eye

1
2
??? info "提示块图标"
    [Admonition Icons](https://squidfunk.github.io/mkdocs-material/reference/admonitions/#admonition-icons)
自定义图标

自定义

数据隐私

完整信息

数据隐私

导航栏

加载项
mkdocs.yml
1
2
3
4
5
6
theme:
    name: material
    features:
        - navigation.instant # 即时加载
        - navigation.instant.prefetch # 预加载
        - navigation.instant.progress # 显示进度条

提示

使用即时加载的相关项时必须使用site_url属性

说明

参考[工欲善其事，必先利其器] - 搭建技术博客/个人主页 - 使用MkDocs和Material - 知乎 (zhihu.com)，即时加载最好去掉，因为在多语言切换中这个加载项会导致切回首页

锚点

实现导航栏跟踪

mkdocs.yml
1
2
3
4
theme:
    name: material
    features:
        - navigation.tracking
菜单栏

实现页面顶部菜单栏功能

mkdocs.yml
1
2
3
4
5
theme:
    name: material
    features:
        - navigation.tabs
        - navigation.tabs.sticky # 是否始终显示
章节显示

显示每个页面的每个章节

mkdocs.yml
1
2
3
4
5
theme:
    name: material
    features:
        - navigation.sections # 是否显示章节
        - navigation.expand # 是否压缩显示
路径

内测版专属

mkdocs.yml
1
2
3
4
theme:
    name: material
    features:
        - navigation.path
项目优化

构建只可见的页面，可以优化导航栏

mkdocs.yml
1
2
3
4
theme:
    name: material
    features:
        - navigation.prune
首页信息

是否单独显示首页

为了能链接至某章节的某个页，在这个章节中添加这个章节的首页

mkdocs.yml
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
nav:
    - SectionName:
        - SectionFolder/index.md
        - Page 1: section/page-1.md
        - Page 2: section/page-2.md
        ...
theme:
    name: material
    features:
        - navigation.indexes
TOC

TOC在这里指页面右侧的小目录

mkdocs.yml
1
2
3
4
5
theme:
    name: material
    features:
        - toc.follow # 右侧边栏的目录跟踪
        - toc.integrate # 目录跟踪集成到左侧边栏目录中
回到顶部
mkdocs.yml
1
2
3
4
theme:
    name: material
    features:
        - navigation.top
隐藏

可以在某些页面中隐藏导航栏和/或TOC，只需要在页面的元数据YAML中添加即可

page.md
1
2
3
4
5
6
7
8
9
---
hide:
    - navigation
    - toc
---

# Page title

...

顶栏

顶栏可以添加公告、防止仓库地址、搜索栏等等

mkdocs.yml
1
2
3
4
5
theme:
    name: material
    feature:
        - header.autohide # 自动隐藏顶栏
        - announce.dismiss # 可以叉掉公告

底栏

底栏可以放置网站链接、社交频道、版权信息等等

mkdocs.yml
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
theme:
    name: material
    features:
        - navigation.footer
        ...
extra:
    # 社交链接
    social:
        - icon: IconFile1
          link: YourSocialLink1
        - icon: IconFile2
          link: YourSocialLink2
        ...
        - icon: IconFileN # 邮箱
          link: mailto:<YourEmailAddress>
    # 有关MkDocs-Material的生成器
    generator: false
# 版权信息
copyright: >-
    Copyright &copy; 2024 YourName

社交链接图标

注意

社交链接图标必须是与主题绑定的图标

Material-SocialIcons
1
2
3
4
5
6
7
8
9
fontawesome/brands/github
fontawesome/brands/gitlab
fontawesome/brands/x-twitter
fontawesome/brands/docker
fontawesome/brands/facebook
fontawesome/brands/instagram
fontawesome/brands/linkedin
fontawesome/brands/slack
fontawesome/brands/discord
icon-完整信息

技巧

可以在Copyright中添加HTML链接

如果要在某页中隐藏底栏，在页顶的YAML中设置

page.md
1
2
3
4
5
6
---
hide:
    - footer
---

...

评论区

完整信息

评论系统

页面源码

mkdocs.yml
1
2
3
4
5
theme:
    name: material
    features:
        - content.action.view # 显示页面文档源码
        - content.action.edit # 编辑此页

Plugins

这里介绍一些实用的插件，仅限MkDocs-Material主题

所有插件

(Built-in plugins - Material for MkDocs)

用于全站搜索信息使用

MkDocs-Material的搜索功能非常完善，不需要借助任何第三方工具，甚至可以离线工作

mkdocs.yml
1
2
3
4
5
6
7
8
9
plugins:
    - search # 配置搜索插件
    ...
theme:
    name: material
    features:
        - search.suggest # 搜索建议
        - search.highlight # 搜索高亮
        - search.share # 搜索分享

逐出搜索范围

如果想要某些页面不被搜索到，可以在页面头的YAML中配置：

page.md
1
2
3
4
5
6
7
---
search:
    exclude: true
---

# Page title
...

Blog

Blogs are a great way to engage with your audience. Software developers can use a blog to announce new features, demonstrate their usage and provide background information.

Blog主要以时间线为线索，类似于日记

完成配置后Blogs根据创建时间顺序倒序排列显示

配置

在配置文件中应用blog插件

mkdocs.yml
1
2
plugins:
    - blog

使用

完成配置后，运行mkdocs serve以创建Blog

创建Blog后的文件结构
1
2
3
4
5
6
7
.
├── docs
│   ├── blog # Blog文件夹
│   │   ├── index.md # Blog首页
│   │   └── posts # 存放Blog的文件夹
│   └── index.md
└── mkdocs.yml

之后将所有的blogs都放在docs/blog/posts下

Blog首页会包含所有的Blog及其摘要

元数据

创建的Blog必须有一个页头，将Blog的元数据（如创建日期）写在Markdown文件头部的Yaml中

必需条件

元数据中的创建日期created是唯一的Blog条件，必需写入

Blogs.md
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
---
date:
    created: 2024-07-23 <!-- 创建日期，必需 -->
    updated: 2024-07-24 <!-- 更新日期 -->
readtime: 20 <!-- 阅读时间，不添加会自动生成 -->
pin: true <!-- 是否置顶 -->
draft: true <!-- 是否存入草稿而不发布 -->
categories: <!-- 日记类别 -->
    - CategoryName
links: <!-- 链接 -->
    - HomePage: index.md
    - Blog Index: blog/index.md
    - External links: <!-- 外部链接 -->
        - YourLinkName: https://example.com
---

# My Blog

...

<!-- more --> <!-- 摘要分栏 -->

...
  • 作为草稿的Blog在构建站点时不会被构建，在本地渲染时可以看到一个draft标签
  • Blog可以进行分类，使用categories属性标记类别
  • 在Yaml部分到<!-- more -->之间的内容会作为Blog的摘要显示在首页和归档中，而后续内容则不会显示

导航栏配置

完成Blog配置后搭配导航栏以显示blogs

mkdocs.yml
1
2
3
4
nav:
    ...
    - Blog:
        - blog/index.md

使用建议

为了避免Blog首页重复显示，可以在配置文件中这样修改

mkdocs.yml
1
2
3
4
theme:
    name: material
    features:
        - navigation.indexes

归档

Blogs默认情况下按照年份进行归档整理

也可以自定义设置归档格式

mkdocs.yml
1
2
3
plugins:
    - blog:
        archive_date_format: MMMM yyyy # y年M月d日

分类

在元数据中提到使用分类(Categories)的方法对Blogs进行分类

可以在配置文件中修改允许显示的类别

mkdocs.yml
1
2
3
4
5
6
plugins:
    - blog:
        categories_allowed:
            - Categories 0
            - Categories 1
            ...

作者

创建文件docs/blog/.authors.yml来标明Blogs的作者

.authors.yml
1
2
3
4
5
6
7
authors:
    Author1: # 作者ID
        name: YourName # 作者名
        description: YourDescription # 作者描述
        avatar: YourURL # 作者图标
    Author2:
        ...

添加完作者配置文件后在Blogs头部的元数据中添加作者

Blog.md
1
2
3
4
5
6
7
8
9
---
date:
    created: ...
authors:
    - Author1
    ...
---

...

即可在Blogs中查看作者的信息

添加作者个人主页

MkDocs-Material内测版允许你在你的站点添加作者个人主页，完成赞助以启用这个功能

分页

Blogs数量过多时可以使用分页(Pagination)功能

默认情况下的Blog分页为10Blogs每页

mkdocs.yml
1
2
3
4
5
6
plugins:
    - blog:
        ...
        pagination_per_page: 10
        archive_pagination_per_page: 5
        categories_pagination_per_page: 5

目录

当Blogs数量过多，可以启用Blogs目录完成信息分拣

mkdocs.yml
1
2
3
plugins:
    - blog:
        blog_toc: true

标签

标签也可以用来对文章分类

mkdocs.yml
1
2
plugins:
    - tags

添加标签

在每页的头部YAML中加入tag

page.md
1
2
3
4
5
6
7
8
---
tags:
    - YourTag1
    - YourTag2
    ...
---

...

隐藏标签

只需要在头部YAML中设置

page.md
1
2
3
4
5
6
---
hide:
    - tags
---

...

标签图标

在配置文件中设置标签的标识符和图标

mkdocs.yml
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
theme:
    name: material
    icon:
        tags:
            YourTagIdentifier1: YourTagIconFile1
            YourTagIdentifier2: YourTagIconFile2
            ...
extra:
    tags:
        YourTag1: YourTagIdentifier1
        YourTag2: YourTagIdentifier2
        ...

Material主题提供的标签

Tag-Icon

标签索引页

可以专门做一个标签索引页来记录所有的标签及其对应的页面

注意

记得把这个标签索引页加入导航栏中

然后在索引页中添加

tags.md
1
2
3
4
5
6
7
# Tags

...

###### This_Is_Tech/Tools/Sites/MkDocs.md:23445-23467/name { #This_Is_Tech/Tools/Sites/MkDocs.md:23445-23467/slug }

...

标签插件会在!-- material/tags -->位置插入标签索引页的内容

然后在配置文件中修改配置为

mkdocs.yml
1
2
3
plugins:
    - tags:
        tags_file: tags.md

注意

添加的文件路径为相对于docs/

社交卡片

完整信息

社交卡片

说明

参考[工欲善其事，必先利其器] - 搭建技术博客/个人主页 - 使用MkDocs和Material - 知乎 (zhihu.com)，社交卡片有一些bug，会导致报错

RSS

完整信息

RSS

Extra

站点分析工具

完整信息

Analytics

版本工具

有时候一个产品或站点有不同的版本，因此使用版本工具可以查看不同版本对应的站点内容

完整信息

Versioning

状态

可以设置文章的状态

Material主题预定义的状态

  • 文章是最新添加的 new
  • 文章是过时弃用的 deprecated

先在配置文件中设置

mkdocs.yml
1
2
3
extra:
    status:
        <identifier>: <description>

然后在对应页面的头部YAML中描述

page.md
1
2
3
4
5
---
status: <identifier>
---

...

References

参考配置

参考知乎文章中的一份比较完整和实用的配置文件：

mkdocs.yml
  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
# 项目信息
site_name: Eureka! # 项目名称
site_url: https://localhost:8000/ # 我在nginx中使用的是8000端口，如果你使用的是80端口，可以直接写成https://localhost/。
site_author: Shuaiwen Cui # 作者
site_description: >- # 项目描述
  Welcome to Shaun's rabbit hole. This site serves as a personal knowledge base for me to record my thoughts and ideas. It is also a place for me to share my knowledge and experience with the world. I hope you find something useful here. 

# 代码仓库信息
repo_name: Shuaiwen-Cui/Infinity # 仓库名称
repo_url: https://github.com/Shuaiwen-Cui/Infinity.git/ # 仓库地址

# 版权信息
copyright: Copyright &copy; 2023 ~ now |   Shuaiwen Cui (Shaun)

# 配置
theme:
  custom_dir: material/overrides # 自定义文件夹，对于个别页面，如果你不想使用主题的默认样式，可以在这里进行修改，使用里面的文件覆盖主题的默认文件。具体可以参考material官方文档。
  name: material # 主题名称，Material已经是最优秀的选择了，相信我。
  logo: static/images/logo.png # logo 图片
  language: en # 默认语言
  features: # 功能  
    - announce.dismiss # 可以叉掉公告的功能
    - content.action.edit # 编辑按钮，似乎没啥用
    - content.action.view # 查看按钮，似乎没啥用
    - content.code.annotate # 代码注释，具体不清楚
    - content.code.copy # 复制代码按钮
    # - content.code.select # 选择代码按钮
    # - content.tabs.link # 链接标签
    - content.tooltips # 不太清楚呢这个
    # - header.autohide # 自动隐藏header
    - navigation.expand # 默认展开导航栏
    - navigation.footer # 底部导航栏
    - navigation.indexes # 索引按钮可以直接触发文件，而不是只能点击其下属选项浏览，这个功能可以给对应的section提供很好的预览和导航功能
    # - navigation.instant # 瞬间加载 最好注释掉，多语言切换这个会导致跳回首页
    - navigation.instant.prefetch # 预加载
    - navigation.instant.progress # 进度条
    - navigation.path # 导航路径， 目前好像没啥用
    # - navigation.prune # 只构建可见的页面
    - navigation.sections # 导航栏的section
    - navigation.tabs # 顶级索引被作为tab
    - navigation.tabs.sticky # tab始终可见
    - navigation.top # 开启顶部导航栏
    - navigation.tracking # 导航栏跟踪
    - search.highlight # 搜索高亮
    - search.share # 搜索分享
    - search.suggest # 搜索建议
    - toc.follow # 目录跟踪-页面右侧的小目录
    # - toc.integrate # 目录跟踪集成到左侧大目录中
  palette:
    - media: "(prefers-color-scheme)" # 主题颜色
      scheme: slate
      primary: black
      accent: indigo
      toggle:
        icon: material/link
        name: Switch to light mode
    - media: "(prefers-color-scheme: light)" # 浅色
      scheme: default
      primary: indigo
      accent: indigo
      toggle:
        icon: material/toggle-switch
        name: Switch to dark mode
    - media: "(prefers-color-scheme: dark)" # 深色
      scheme: slate
      primary: black
      accent: indigo
      toggle:
        icon: material/toggle-switch-off
        name: Switch to system preference
  font: # 字体，大概率不需要换
    text: Roboto
    code: Roboto Mono
  favicon: assets/favicon.png # 网站图标 似乎不需要管
  icon: # 一些用到的icon
    logo: logo
    previous: fontawesome/solid/angle-left
    next: fontawesome/solid/angle-right
    tag:
      default-tag: fontawesome/solid/tag
      hardware-tag: fontawesome/solid/microchip
      software-tag: fontawesome/solid/laptop-code

# Plugins
plugins:
  - tags # 标签功能插件
  - blog # 博客功能插件
  - rss: # rss订阅插件 - 不太懂是干嘛的目前
      match_path: blog/posts/.* 
      date_from_meta:
        as_creation: date
      categories:
        - categories
        - tags 
  # - social # 目前我开启会报错，还没研究透 
  - search: # 搜索插件
      separator: '[\s\u200b\-_,:!=\[\]()"`/]+|\.(?!\d)|&[lg]t;|(?!\b)(?=[A-Z][a-z])' # 分隔符
  - minify: # 压缩插件
      minify_html: true
  # - privacy # 隐私插件
  - i18n: # 多语言插件
      docs_structure: suffix # 抄来的，不太懂
      fallback_to_default: true # 抄来的，不太懂
      reconfigure_material: true # 抄来的，不太懂
      reconfigure_search: true # 抄来的，不太懂
      languages: # 多语言配置 - 需要小心一点
        - locale: en
          default: true # 默认语言
          name: English
          build: true # 是否构建
          # site_name: Infinity
        - locale: zh
          name: 简体中文
          build: true
          nav_translations: # 导航栏翻译，不可以有缩进
            HOME: 首页
            ABOUT: 关于
            SPONSORSHIP: 赞助
            CS: 计算机
            CODING: 编程
            EMBEDDED-SYS: 嵌入式系统
            DSP: 数字信号处理
            PERCEPTION: 感知
            ACTUATION: 执行
            IOT: 物联网
            CLOUD: 云
            CLOUD-TECH: 云技术
            HANDS-ON: 上手实践
            Have A Server: 拥有一台服务器
            Server Configuration: 服务器配置
            Get A Domain Name: 获得一个域名
            AI: 人工智能
            RESEARCH: 研究
            PROJECT: 项目
# Hooks - 讲真，这个东西我还没搞懂
# hooks:
#   - material/overrides/hooks/shortcodes.py
#   - material/overrides/hooks/translations.py

# 额外配置项
extra:
  generator: false # 是否显示生成器
  status: # 不是很懂有什么用
    new: Recently added
    deprecated: Deprecated
  analytics: # 分析工具， 我反正没用到
    provider: google
    property: !ENV GOOGLE_ANALYTICS_KEY
    feedback: # feedback form
      title: Was this page helpful?
      ratings:
        - icon: material/thumb-up-outline
          name: This page was helpful
          data: 1
          note: >-
            Thanks for your feedback!
        - icon: material/thumb-down-outline
          name: This page could be improved
          data: 0
          note: >- 
            Thanks for your feedback! Help us improve this page by
            using our <a href="..." target="_blank" rel="noopener">feedback form</a>.
  # alternate: # 由上面那个i18n插件提供的多语言功能，这个似乎就不需要了。 这个是官方文档的例子，但是官方没有提供很详细的例子，所以我也不知道怎么用。
  #   - name: English
  #     link: /en/ 
  #     lang: en
  #   - name: Chinese
  #     link: /zh/
  #     lang: zh
  social: # 社交媒体
    - icon: fontawesome/solid/house
      link: http://www.cuishuaiwen.com/
    - icon: fontawesome/brands/github
      link: https://github.com/Shuaiwen-Cui
    - icon: fontawesome/brands/linkedin
      link: https://www.linkedin.com/in/shaun-shuaiwen-cui/
    - icon: fontawesome/brands/researchgate
      link: https://www.researchgate.net/profile/Shuaiwen-Cui
    - icon: fontawesome/brands/orcid
      link: https://orcid.org/0000-0003-4447-6687
    - icon: fontawesome/brands/twitter
      link: https://twitter.com/ShuaiwenC
  tags: # 自定义标签
    Default: default-tag
    Hardware: hardware-tag
    Software: software-tag
  # consent: # 征求同意 Cookie
  #   title: Cookie consent
  #   description: >- 
  #     We use cookies to recognize your repeated visits and preferences, as well
  #     as to measure the effectiveness of our documentation and whether users
  #     find what they're searching for. With your consent, you're helping us to
  #     make our documentation better.

# 扩展
markdown_extensions: # markdown extensions
  - abbr
  - admonition
  - attr_list
  - def_list
  - footnotes
  - md_in_html
  - toc:
      permalink: true
  - pymdownx.arithmatex:
      generic: true
  - pymdownx.betterem:
      smart_enable: all
  - pymdownx.caret
  - pymdownx.details
  - pymdownx.emoji:
      emoji_generator: !!python/name:material.extensions.emoji.to_svg
      emoji_index: !!python/name:material.extensions.emoji.twemoji
  - pymdownx.highlight:
      anchor_linenums: true
      line_spans: __span
      pygments_lang_class: true
  - pymdownx.inlinehilite
  - pymdownx.keys
  - pymdownx.magiclink:
      normalize_issue_symbols: true
      repo_url_shorthand: true
      user: squidfunk
      repo: mkdocs-material
  - pymdownx.mark
  - pymdownx.smartsymbols
  - pymdownx.snippets:
      auto_append:
        - includes/mkdocs.md
  - pymdownx.superfences:
      custom_fences:
        - name: mermaid
          class: mermaid
          format: !!python/name:pymdownx.superfences.fence_code_format
  - pymdownx.tabbed:
      alternate_style: true
      combine_header_slug: true
      slugify: !!python/object/apply:pymdownx.slugs.slugify
        kwds:
          case: lower
  - pymdownx.tasklist:
      custom_checkbox: true
  - pymdownx.tilde

# 导航树 - 请按照我的做法来做，否则可能无法正常工作。引号可以省略。开头的点和斜杠也可以省略 ("./HOME/about.md" 或 Home/about.md) 。注意，导航树这里的文件名是 filename.md 这样的，但在文件夹中，它实际上被命名为 filename.en.md 和 filename.zh.md。我猜测默认是英文，所以, index.en.md 和 index.md 是一样的。i18n插件会自动识别文件名，然后根据文件名的后缀来切换语言。所以，如果你想添加一个新页面，你需要添加两个文件，一个是 filename.en.md，另一个是 filename.zh.md。其中，filename.en.md 也可以被命名为 filename.md，但是 filename.zh.md 不能被命名为 filename.md，否则会导致无法识别。
nav: 
  - HOME: 
      - "index.md"
      - ABOUT: "./HOME/about.md"
      - SPONSORSHIP: "./HOME/sponsorship.md"
  - CS: 
      - "./CS/CS.md"
  - CODING: 
      - "./CODING/coding.md"
  - EMBEDDED-SYS: 
      - "./EMBEDDED-SYS/embedded-sys.md"
  - DSP: 
      - "./DSP/dsp.md"
  - PERCEPTION: 
      - "./PERCEPTION/perception.md"
  - ACTUATION: 
      - "./ACTUATION/actuation.md"
      - ROS: "./ACTUATION/ROS/ros.md"
  - IOT: 
      - "./IOT/iot.md"
  - CLOUD: 
      - "./CLOUD/cloud.md"
      - CLOUD-TECH: "./CLOUD/CLOUD-TECH/cloud-tech.md"
      - HANDS-ON:
          - Have A Server: "./CLOUD/HANDS-ON/001-HAVE-A-SERVER/have-a-server.md"
          - Server Configuration: "./CLOUD/HANDS-ON/002-SERVER-CONFIG/server-config.md"
          - Get A Domain Name: "./CLOUD/HANDS-ON/003-DOMAIN-NAME/domain-name.md"
  - AI: 
      - "./AI/ai.md"
  - RESEARCH: 
      - "./RESEARCH/research.md"
  - PROJECT: 
      - "./PROJECT/project.md"
      - TECH-BLOG: "./PROJECT/TECH-BLOG/mkdocs_and_material.md"

简洁的配置教程

so easy！从头教你用mkdocs构建个人博客系统~_mkdocs教程-CSDN博客