mkdocs

部署

mkdocs 官方入门，mcdocs usage：mkdocs --help。

官方内置主题: mkdocs 和 readthedocs。目前最好的第三方主题 Material 持续稳定更新。

主题设置

在 mkdocs.yml 中设置主题。

警告或标注

markdown_extensions:
  - admonition                # 警告或标注
  - pymdownx.details          # 细节折叠
  - pymdownx.superfences      # 超级围栏

!!! 开头后接关键字。下一行缩进 4 个空格。

!!! note
    Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
    nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
    massa, nec semper lorem quam in massa.

Note

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor massa, nec semper lorem quam in massa.

双引号内为标题。

!!! success "Phasellus posuere in sem ut cursus"

Phasellus posuere in sem ut cursus

以 ??? 开头为细节折叠。多加号为展开。

???+ info
    reject common sense to make the impossible possible

Quote

reject common sense to make the impossible possible

侧边栏使用 inline 放在左侧，inline+end 放在右侧。

左对齐右对齐

Info

left side

!!! info inline
    left side

Tip

right side

!!! tip inline end
    right side

abstract, summary, tip 摘要，总结, 提示
info, todo 信息，待办
success, check, done 成功，检查，完成
question, help, faq 问题，帮助，常见问题解答
warning, caution, attention 警告，小心，注意
failure, fail, missing 失败，错过
danger, error 危险，错误
bug 漏洞
quote 引用，提及

自定义警告类型需要颜色和 *.svg 图标。

extra_css:
  - stylesheets/extra.css

:root {
  --md-admonition-icon--pied-piper: url('data:image/svg+xml;charset=utf-8,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 576 512"><path d="M244 246c-3.2-2-6.3-2.9-10.1-2.9-6.6 0-12.6 3.2-19.3 3.7l1.7 4.9zm135.9 197.9c-19 0-64.1 9.5-79.9 19.8l6.9 45.1c35.7 6.1 70.1 3.6 106-9.8-4.8-10-23.5-55.1-33-55.1zM340.8 177c6.6 2.8 11.5 9.2 22.7 22.1 2-1.4 7.5-5.2 7.5-8.6 0-4.9-11.8-13.2-13.2-23 11.2-5.7 25.2-6 37.6-8.9 68.1-16.4 116.3-52.9 146.8-116.7C548.3 29.3 554 16.1 554.6 2l-2 2.6c-28.4 50-33 63.2-81.3 100-31.9 24.4-69.2 40.2-106.6 54.6l-6.3-.3v-21.8c-19.6 1.6-19.7-14.6-31.6-23-18.7 20.6-31.6 40.8-58.9 51.1-12.7 4.8-19.6 10-25.9 21.8 34.9-16.4 91.2-13.5 98.8-10zM555.5 0l-.6 1.1-.3.9.6-.6zm-59.2 382.1c-33.9-56.9-75.3-118.4-150-115.5l-.3-6c-1.1-13.5 32.8 3.2 35.1-31l-14.4 7.2c-19.8-45.7-8.6-54.3-65.5-54.3-14.7 0-26.7 1.7-41.4 4.6 2.9 18.6 2.2 36.7-10.9 50.3l19.5 5.5c-1.7 3.2-2.9 6.3-2.9 9.8 0 21 42.8 2.9 42.8 33.6 0 18.4-36.8 60.1-54.9 60.1-8 0-53.7-50-53.4-60.1l.3-4.6 52.3-11.5c13-2.6 12.3-22.7-2.9-22.7-3.7 0-43.1 9.2-49.4 10.6-2-5.2-7.5-14.1-13.8-14.1-3.2 0-6.3 3.2-9.5 4-9.2 2.6-31 2.9-21.5 20.1L15.9 298.5c-5.5 1.1-8.9 6.3-8.9 11.8 0 6 5.5 10.9 11.5 10.9 8 0 131.3-28.4 147.4-32.2 2.6 3.2 4.6 6.3 7.8 8.6 20.1 14.4 59.8 85.9 76.4 85.9 24.1 0 58-22.4 71.3-41.9 3.2-4.3 6.9-7.5 12.4-6.9.6 13.8-31.6 34.2-33 43.7-1.4 10.2-1 35.2-.3 41.1 26.7 8.1 52-3.6 77.9-2.9 4.3-21 10.6-41.9 9.8-63.5l-.3-9.5c-1.4-34.2-10.9-38.5-34.8-58.6-1.1-1.1-2.6-2.6-3.7-4 2.2-1.4 1.1-1 4.6-1.7 88.5 0 56.3 183.6 111.5 229.9 33.1-15 72.5-27.9 103.5-47.2-29-25.6-52.6-45.7-72.7-79.9zm-196.2 46.1v27.2l11.8-3.4-2.9-23.8zm-68.7-150.4l24.1 61.2 21-13.8-31.3-50.9zm84.4 154.9l2 12.4c9-1.5 58.4-6.6 58.4-14.1 0-1.4-.6-3.2-.9-4.6-26.8 0-36.9 3.8-59.5 6.3z"/></svg>')
}
.md-typeset .admonition.pied-piper,
.md-typeset details.pied-piper {
  border-color: rgb(43, 155, 70);
}
.md-typeset .pied-piper > .admonition-title,
.md-typeset .pied-piper > summary {
  background-color: rgba(43, 155, 70, 0.1);
  border-color: rgb(43, 155, 70);
}
.md-typeset .pied-piper > .admonition-title::before,
.md-typeset .pied-piper > summary::before {
  background-color: rgb(43, 155, 70);
  -webkit-mask-image: var(--md-admonition-icon--pied-piper);
          mask-image: var(--md-admonition-icon--pied-piper);
}

缩写与片段

markdown_extensions:
  - abbr                      # 缩写或名词
  - pymdownx.snippets         # 片段，将任意文件或部分内容嵌入到文档中

snippets 内容前加 --8<-- 嵌入。

"includes/abbr.md"
*[HTML]: Hyper Text Markup Language
*[W3C]: World Wide Web Consortium

The HTML specification is maintained by the W3C.

定义和属性列表

markdown_extensions:
  - def_list                
  - attr_list

定义列表枚举任意键值对的列表。

`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.

属性列表允许为所有内联和块级元素添加属性，将任何链接变成按钮。

[Subscribe to our newsletter](#){ .md-button .md-button--primary }
[Send :fontawesome-solid-paper-plane:](#){ .md-button }

Subscribe to our newsletter Send

元数据 meta

添加文档 meta 信息。

---
title: Mkdocs 使用
description: 介绍 Mkdos 部署和 Material 主题设置
icon: material/emoticon-happy 
tags:
  - tools
  - mkdocs
---

自定义和隐藏导航或侧边栏：

---
template: custom.html
hide:
  - navigation
  - toc
---

HTML 中的 Markdown md_in_html

默认情况下，Markdown 会忽略原始 HTML 块级元素中的任何内容。启用扩展 md_in_html，原始 HTML 块级元素的内容可以通过 markdown 在开始标记上包含属性来解析为 Markdown。该 markdown 属性将从输出中删除，而所有其他属性将被保留。

表格 tables

|  Method  |             Description              |
| :------ | ----------------------------------: |
|  `GET`   | :material-check:     Fetch resource  |
|  `PUT`   | :material-check-all: Update resource |
| `DELETE` | :material-close:     Delete resource |

Method	Description
`GET`	Fetch resource
`PUT`	Update resource
`DELETE`	Delete resource

数学公式

markdown_extensions:
  - pymdownx.arithmatex:
      generic: true

extra_javascript:
  - javascripts/mathjax.js
  - https://polyfill.io/v3/polyfill.min.js?features=es6
  - https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js

\[\mathbb{E}[\mathbf{z}]=\int_0^\infty z_t\mathrm{d}t\]

格式化

  - pymdownx.caret            # 角标 (`^`)
  - pymdownx.mark             # 双等 (`==`)
  - pymdownx.tilde            # 波浪 (`~`)
  - pymdownx.critic:          # 评论家
      mode: reject            # 如何解析标记

- ==This was marked==
- ^^This was inserted^^
- ~~This was deleted~~
- H~2~0
- A^T^A

This was marked
This was inserted
~~This was deleted~~
H₂0
A^TA

Emoji

:smile: 
:fontawesome-regular-face-laugh-wink:

代码块

  - pymdownx.highlight:       # 代码高亮
      anchor_linenums: false  # 代码块行号锚链接
      use_pygments: true      # 使用 Pygments 或在浏览器中使用 JavaScript 语法高亮器高亮
      auto_title: false
#      linenums: false
      linenums_style: pymdownx-inline
  - pymdownx.inlinehilite     # 行内高亮

bubble_sort.py

def bubble_sort(items):
    for i in range(len(items)):
        for j in range(len(items) - 1 - i):
            if items[j] > items[j + 1]:
                items[j], items[j + 1] = items[j + 1], items[j]

内容选项

CC++

#include <stdio.h>

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

#include <iostream>

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

Example

Unordered ListOrdered List

List, unordered

* Sed sagittis eleifend rutrum
* Donec vitae suscipit est
* Nulla tempor lobortis orci

List, ordered

1. Sed sagittis eleifend rutrum
2. Donec vitae suscipit est
3. Nulla tempor lobortis orci

任务列表 pymdownx.tasklist

- [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

Lorem ipsum dolor sit amet, consectetur adipiscing elit
Vestibulum convallis sit amet nisi a tincidunt
- In hac habitasse platea dictumst
- In scelerisque nibh non dolor mollis congue sed et metus
- Praesent sed risus massa
Aenean pretium efficitur erat, donec pharetra, ligula non scelerisque

图表 mermaid

流程图

graph LR
  A[Start] --> B{Error?};
  B -->|Yes| C[Hmm...];
  C --> D[Debug];
  D --> B;
  B ---->|No| E[Yay!];

序列图

sequenceDiagram
  Alice->>John: Hello John, how are you?
  loop Healthcheck
      John->>John: Fight against hypochondria
  end
  Note right of John: Rational thoughts!
  John-->>Alice: Great!
  John->>Bob: How about you?
  Bob-->>John: Jolly good!

状态图

stateDiagram-v2
  state fork_state <<fork>>
    [*] --> fork_state
    fork_state --> State2
    fork_state --> State3

    state join_state <<join>>
    State2 --> join_state
    State3 --> join_state
    join_state --> State4
    State4 --> [*]

类图

classDiagram
  Person <|-- Student
  Person <|-- Professor
  Person : +String name
  Person : +String phoneNumber
  Person : +String emailAddress
  Person: +purchaseParkingPass()
  Address "1" <-- "0..1" Person:lives at
  class Student{
    +int studentNumber
    +int averageMark
    +isEligibleToEnrol()
    +getSeminarsTaken()
  }
  class Professor{
    +int salary
  }
  class Address{
    +String street
    +String city
    +String state
    +int postalCode
    +String country
    -validate()
    +outputAsLabel()  
  }

实体关系图

erDiagram
  CUSTOMER ||--o{ ORDER : places
  ORDER ||--|{ LINE-ITEM : contains
  CUSTOMER }|..|{ DELIVERY-ADDRESS : uses

图片

markdown_extensions:
  - attr_list      
  - md_in_html                # 在 HTML 中使用 Markdown

图片居左图片居右

Image, aligned to left

![Image title](https://dummyimage.com/600x400/eee/aaa){ align=left }

Image title

Image, aligned to right

![Image title](https://dummyimage.com/600x400/eee/aaa){ align=right }

Image title

<figure markdown>
  ![Image title](https://dummyimage.com/600x400/){ width="300" }
  <figcaption>Image caption</figcaption>
</figure>

脚注 footnotes

短脚注可写在一行内，长脚注需要缩进 4 个空格。

Lorem ipsum[^1] dolor sit amet, consectetur adipiscing elit.[^2]

[^1]: Lorem ipsum dolor sit amet, consectetur adipiscing elit.

[^2]:
    Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
    nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
    massa, nec semper lorem quam in massa.

Lorem ipsum¹ dolor sit amet, consectetur adipiscing elit.²

Lorem ipsum dolor sit amet, consectetur adipiscing elit. ↩
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor massa, nec semper lorem quam in massa. ↩