Python-Markdown扩展

MkDocs pages must be authored in Markdown.

MkDocs uses the Python-Markdown library to render Markdown documents to HTML.

markdown_extensions#

MkDocs includes support for extending the Markdown syntax with Python-Markdown extensions. See the MkDocs' markdown_extensions configuration setting for details on how to enable extensions.

MkDocs includes some extensions by default, which are highlighted below.

Internal links: toc
Meta-Data: meta
Tables: tables
Fenced code blocks: fenced_code
- 貌似默认主题已带代码高亮，参考 Choosing your Theme - mkdocs。

建议启用以下扩展：

nl2br
sane_lists
footnotes
codehilite: 需要安装 Pygments

More extensions#

User Guide - Configuration

Formatting options | markdown_extensions

The Python-Markdown documentation provides a list of extensions which are available out-of-the-box. For a list of configuration options available for a given extension, see the documentation for that extension.

You may also install and use various third party extensions (Python-Markdown wiki, MkDocs project catalog). Consult the documentation provided by those extensions for installation instructions and available configuration options.

checklist#

checklist: Adds GitHub-style task lists with checkboxes

执行 pip install markdown-checklist 安装扩展插件，然后在 mkdocs.yml 中引入：

markdown_extensions:

   - markdown_checklist.extension

undo1
undo2
done1
done2

YAML Style Meta-Data#

YAML style meta-data consists of YAML key/value pairs wrapped in YAML style delimiters to mark the start and/or end of the meta-data. The first line of a document must be ---. The meta-data ends at the first line containing an end deliminator (either --- or ...). The content between the delimiters is parsed as YAML.

---
title: My Document
summary: A brief description of my document.
authors:
    - Waylan Limberg
    - Tom Christie
date: 2018-07-10
some_url: https://example.com
---
This is the first paragraph of the document.

YAML is able to detect data types. Therefore, in the above example, the values of title, summary and some_url are strings, the value of authors is a list of strings and the value of date is a datetime.date object. Note that the YAML keys are case sensitive and MkDocs expects keys to be all lowercase. The top level of the YAML must be a collection of key/value pairs, which results in a Python dict being returned. If any other type is returned or the YAML parser encounters an error, then MkDocs does not recognize the section as meta-data, the page's meta attribute will be empty, and the section is not removed from the document.

关于 metadata 的扩展使用案例，参考：

material extensions#

Material for MkDocs - Python Markdown Extensions

Material for MkDocs - Reference

tasklist#

Lists。

不用再安装 markdown-checklist，采用 pymdownx.tasklist 平替，效果区别如下：

前面没有无序列表的 bullet 点号；
custom_checkbox 自定义绿色圆形勾选图标。

markdown_extensions:
  - def_list
  - pymdownx.tasklist:
      custom_checkbox: true

Content Tabs#

Content tabs

Sometimes, it's desirable to group alternative content under different tabs, e.g. when describing how to access an API from different languages or environments. Material for MkDocs allows for beautiful and functional tabs, grouping code blocks and other content.

这里涉及到设定代码块标题：title="Content Tabs"。
注意缩进。

Content Tabs

=== "Unordered list"

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

=== "Ordered list"

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

Unordered listOrdered list

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

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

Formatting#

Formatting

markdown_extensions:
  - pymdownx.critic
  - pymdownx.caret
  - pymdownx.mark
  - pymdownx.tilde
  - pymdownx.keys

Critic Markup#

The Critic extension allows for the usage of Critic Markup to highlight added, deleted or updated sections in a document, i.e. for tracking changes in Markdown syntax.

Critic DemoCritic Code

Text can be ~~deleted~~ and replacement text added. This can also be
combined into ~~one~~a single operation. Highlighting is also
possible and comments can be added inline.

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.

Critic-Markup-Demo

Highlighting#

The Caret, Mark & Tilde extensions add the ability to highlight text and define sub- and superscript using a simple syntax.

Highlighting DemoHighlighting Code

This was marked
This was inserted
~~This was deleted~~

- ==This was marked==
- ^^This was inserted^^
- ~~This was deleted~~

Sub & Sup#

When Caret & Tilde are enabled, text can be sub- and superscripted with a simple syntax, which is more convenient than directly using the corresponding sub and sup HTML tags:

sub-sup Demosub-sup Code

6CO₂ + 6H₂O -> C₆H₁₂O₆[(CH₂O)_n] + 6O₂
A^TA

6CO~2~ + 6H~2~O -> C~6~H~12~O~6~[(CH~2~O)~n~] + 6O~2~
A^T^A

Keys#

The Keys extension adds a simple syntax to allow for the rendering of keyboard keys and combinations, e.g. Ctrl+Alt+Del.

Keys DemoKeys Code

Ctrl+Alt+Del
⌃⌥ ⌫

++ctrl+alt+del++
<kbd>⌃</kbd><kbd>⌥</kbd><kbd> ⌫ </kbd>

Code Blocks#

Code blocks and examples are an essential part of technical project documentation. Material for MkDocs provides different ways to set up syntax highlighting for code blocks, either during build time using Pygments or during runtime using a JavaScript syntax highlighter.

关于 GitHub 配置 Fenced Code Block 语法高亮所使用的 YAML 标记，可参考初探YAML、YAML学习、YAML学习总结、YAML--想要爱你很容易。

语言类型标记参考 linguist/languages.yml 和 Languages — Pygments。以 Shell Script 为例，语言类型标记可以为 shell 或 bash。

linguistPygments

Shell:
  type: programming
  color: "#89e051"
  aliases:
  - sh
  - shell-script
  - bash
  - zsh

Name	Extension(s)	Short name(s)
Bash	.sh, .ksh, .bash, .ebuild, .eclass, .exheres-0, .exlib, .zsh, .bashrc, bashrc, .bash, bash, zshrc, .zshrc, .kshrc, kshrc, PKGBUILD	bash, sh, ksh, zsh, shell, openrc

markdown_extensions 中引入 pymdownx 四大扩展：

Highlight
InlineHilite
SuperFences
Snippets

markdown_extensions:
  - pymdownx.superfences # Supersede fenced_code
  - pymdownx.highlight: # Supersede fenced_codecodehilite
      anchor_linenums: true
      line_spans: __span
      pygments_lang_class: true
  - pymdownx.inlinehilite
  - pymdownx.snippets  # embed external files

在 theme.features 中添加代码复制、行选择和折叠注释功能支持。

theme:
  name: material
  features:
    # Code Blocks
    - content.code.copy # Code Blocks 代码复制按钮
    - content.code.select # Code Block 行选择按钮
    - content.code.annotate # 折叠注释(隐藏/展开)

以下示例综合演示了代码块的功能支持：

Adding a title
Show line numbers
Highlighting specific lines
Adding annotations

Code Blocks DemoCode Blocks Code

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]: # (1)
                items[j], items[j + 1] = items[j + 1], items[j]

I'm a code annotation! I can contain code, formatted
text, images, ... basically anything that can be written in Markdown.

```py title="bubble_sort.py" linenums="1" hl_lines="2 3"
def bubble_sort(items):
for i in range(len(items)):
for j in range(len(items) - 1 - i):
if items[j] > items[j + 1]: # (1)
items[j], items[j + 1] = items[j + 1], items[j]
```

1.  :man_raising_hand: I'm a code annotation! I can contain `code`, __formatted
    text__, images, ... basically anything that can be written in Markdown.

MathJax#

MathJax and KaTeX are two popular libraries for displaying mathematical content in browsers. Although both libraries offer similar functionality, they use different syntaxes and have different configuration options. This documentation site provides information on how to integrate them with Material for MkDocs easily.

加入以下配置，支持渲染数学公式，参考 Markdown-Formula。

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

注意：要将脚本拷贝到本地 docs/javascripts/mathjax.js。

Admonitions#

Admonitions, also known as call-outs, are an excellent choice for including side content without significantly interrupting the document flow. Material for MkDocs provides several different types of admonitions and allows for the inclusion and nesting of arbitrary content.

markdown_extensions:
  - admonition
  - pymdownx.details
  - pymdownx.superfences

Admonition Box#

以下是 Admonition note 示例，默认标题是 Note。

可以在 note 后指定自定义标题: !!! note "Pay Attention"
也可以指定标题为空，即移除标题：!!! note ""

Admonition DemoAdmonition Code

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.

Admonition

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

Collapsible blocks#

When Details is enabled and an admonition block is started with ??? instead of !!!, the admonition is rendered as a collapsible block with a small toggle on the right side.

将 !!! 替换为 ???，则支持可折叠块，点击展开。

在 ??? 后加一个 +，则默认展开。

Collapsible blocks DemoCollapsible blocks Code

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.

Collapsible blocks

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

Inline blocks#

Admonitions can also be rendered as inline blocks (e.g., for sidebars), placing them to the right using the inline + end modifiers, or to the left using only the inline modifier:

排版挺难控制。

Lorem ipsum

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.

!!! info inline end "Lorem ipsum"

    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.
    inline end padding; inline end padding;
    inline end padding; inline end padding;

Supported types#

Admonitions 除了支持 note 提示，还支持以下提示类型：

abstract: 总结
info：信息
tip：提示
success：成功
question：疑问
warning：警告
failure：失败
danger：危险
bug：问题
example：示例
quote：引用

Grids#

Card grids wrap each grid item with a beautiful hover card that levitates on hover. They come in two slightly different syntaxes: list and block syntax, adding support for distinct use cases.

The list syntax is essentially a shortcut for card grids, and consists of an unordered (or ordered) list wrapped by a div with both, the grid and cards classes:

Card grid

<div class="grid cards" markdown>

- :fontawesome-brands-html5: __HTML__ for content and structure
- :fontawesome-brands-js: __JavaScript__ for interactivity
- :fontawesome-brands-css3: __CSS__ for text running out of boxes
- :fontawesome-brands-internet-explorer: __Internet Explorer__ ... huh?

</div>

HTML for content and structure
JavaScript for interactivity
CSS for text running out of boxes
Internet Explorer ... huh?

Card grid, complex example

<div class="grid cards" markdown>

-   :material-clock-fast:{ .lg .middle } __Set up in 5 minutes__

    ---

    Install [`mkdocs-material`](#) with [`pip`](#) and get up
    and running in minutes

    [:octicons-arrow-right-24: Getting started](#)

-   :fontawesome-brands-markdown:{ .lg .middle } __It's just Markdown__

    ---

    Focus on your content and generate a responsive and searchable static site

    [:octicons-arrow-right-24: Reference](#)

-   :material-format-font:{ .lg .middle } __Made to measure__

    ---

    Change the colors, fonts, language, icons, logo and more with a few lines

    [:octicons-arrow-right-24: Customization](#)

-   :material-scale-balance:{ .lg .middle } __Open Source, MIT__

    ---

    Material for MkDocs is licensed under MIT and available on [GitHub]

    [:octicons-arrow-right-24: License](#)

</div>

Set up in 5 minutes

Install mkdocs-material with pip and get up
and running in minutes

Getting started
It's just Markdown

Focus on your content and generate a responsive and searchable static site

Reference
Made to measure

Change the colors, fonts, language, icons, logo and more with a few lines

Customization
Open Source, MIT

Material for MkDocs is licensed under MIT and available on [GitHub]

License

The block syntax allows for arranging cards in grids together with other elements, as explained in the section on generic grids. Just add the card class to any block element inside a grid:

Card grid, blocks

<div class="grid" markdown>

:fontawesome-brands-html5: __HTML__ for content and structure
{ .card }

:fontawesome-brands-js: __JavaScript__ for interactivity
{ .card }

:fontawesome-brands-css3: __CSS__ for text running out of boxes
{ .card }

> :fontawesome-brands-internet-explorer: __Internet Explorer__ ... huh?

</div>

HTML for content and structure

JavaScript for interactivity

CSS for text running out of boxes

Internet Explorer ... huh?

Generic grids allow for arranging arbitrary block elements in a grid, including admonitions, code blocks, content tabs and more. Just wrap a set of blocks by using a div with the grid class:

Generic grid

<div class="grid" markdown>

=== "Unordered list"

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

=== "Ordered list"

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

\`\`\` title="Content tabs"
=== "Unordered list"

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

=== "Ordered list"

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

</div>

Unordered listOrdered list

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

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

Content tabs

=== "Unordered list"

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

=== "Ordered list"

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

embed-pdf#

前端预览PDF总结：iframe、embed、PDFObject、PDF.js
这将是你看到过最全的pdf预览解决方案
 前端实现 PDF 预览的常见方案

在配置文件 mkdocs.yml 的 extra_javascript: 部分导入 javascripts/embed-pdf.js，然后在 markdown 文件中内嵌 iframe 标签：

<iframe src="./test.pdf" height="900px;" width="100%"></iframe>

Python-Markdown扩展

markdown_extensions#

More extensions#

checklist#

YAML Style Meta-Data#

material extensions#

tasklist#

Content Tabs#

Formatting#

Critic Markup#

Highlighting#

Sub & Sup#

Keys#

Code Blocks#

MathJax#

Admonitions#

Admonition Box#

Collapsible blocks#

Inline blocks#

Supported types#

Grids#

embed-pdf#

Comments