Skip to content

代码块

代码块和示例是技术项目文档的重要组成部分。Material for MkDocs 提供了不同的方法来设置代码块的语法高亮，可以在构建时使用Pygments或在运行时使用 JavaScript 语法高亮器。

配置

此配置可以在代码块和内联代码块上启用语法高亮，并允许直接从其他文件中包含源代码。将以下行添加到mkdocs.yml文件中：

markdown_extensions:
  - pymdownx.highlight:
      anchor_linenums: true
      line_spans: __span
      pygments_lang_class: true
  - pymdownx.inlinehilite
  - pymdownx.snippets
  - pymdownx.superfences

下面的部分将讨论如何使用Pygments的不同语法高亮功能，因此当使用 JavaScript 语法高亮器时，这些功能不适用。

查看额外的配置选项：

代码复制按钮

9.0.0 · 功能标志

代码块可以自动在右侧渲染一个按钮，允许用户将代码块的内容复制到剪贴板中。将以下内容添加到mkdocs.yml以在全局启用它们：

theme:
  features:
    - content.code.copy
为特定代码块启用或禁用代码复制按钮

如果您不想在全局启用代码复制按钮，可以通过使用稍微不同的语法为特定代码块启用它们，基于属性列表扩展：

``` { .yaml .copy }
# 代码块内容
```

请注意，必须首先出现的语言简码现在也必须以.为前缀。类似地，可以为特定代码块禁用复制按钮：

``` { .yaml .no-copy }
# 代码块内容
```

代码选择按钮

仅限赞助商 · insiders-4.32.0 · 实验性

代码块可以包含一个按钮，允许用户选择行范围，这对于链接到代码块的特定子部分非常有用。这允许用户动态应用行高亮。将以下内容添加到mkdocs.yml以在全局启用它：

theme:
  features:
    - content.code.select
为特定代码块启用或禁用代码选择按钮

如果您不想在全局启用代码选择按钮，可以通过使用稍微不同的语法为特定代码块启用它，基于属性列表扩展：

``` { .yaml .select }
# 代码块内容
```

请注意，必须首先出现的语言简码现在也必须以.为前缀。类似地，可以为特定代码块禁用选择按钮：

``` { .yaml .no-select }
# 代码块内容
```

代码注解

8.0.0 · 功能标志

代码注解提供了一种舒适友好的方式，可以通过在代码块的块注释和内联注释中添加数字标记来将任意内容附加到代码块的特定部分。将以下内容添加到mkdocs.yml以在全局启用它们：

theme:
  features:
    - content.code.annotate # (1)!
  1. 🙋‍♂️ 我是一个代码注解！我可以包含code、格式化文本、图像等等，基本上可以用 Markdown 表达的任何内容。
为特定代码块启用代码注解

如果您不想在全局启用代码注解，因为您不喜欢自动内联行为，可以通过使用稍微不同的语法为特定代码块启用它，基于属性列表扩展：

``` { .yaml .annotate }
# 代码块内容
```

请注意，必须首先出现的语言简码现在也必须以.为前缀。

自定义选择器

仅限赞助商 · insiders-4.32.0 · 实验性

通常，代码注解只能放置在注释中，因为注释可以被认为是安全的。然而，有时候需要在不允许注释的代码块的部分中放置注解，例如在字符串中。

可以为每种语言设置其他选择器：

extra:
  annotate:
    json: [.s2] # (1)!

  1. .s2是Pygments为双引号字符串生成的词法单元的名称。如果要在注解中使用不同于注释的词法单元，请检查代码块并确定要将哪个词法单元添加到其他选择器列表中。

    重要信息：代码注解不能在词法单元之间分割。

现在，可以在 JSON 字符串中的字符串中使用代码注解：

{
  "key": "value (1)"
}
  1. 🙋‍♂️ 我是一个代码注解！我可以包含code、格式化文本、图像等等，基本上可以用 Markdown 表达的任何内容。

使用方法

代码块必须用包含三个反引号的两行分隔。要对这些块添加语法高亮，直接在开头块后面添加语言简码。请参阅可用词法分析器列表以找到给定语言的简码：

代码块
```py
import tensorflow as tf
```

import tensorflow as tf

添加标题

为了提供额外的上下文，可以通过在简码之后直接使用title="<自定义标题>"选项为代码块添加自定义标题，例如显示文件的名称：

带有标题的代码块
```py title="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]
```
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]

添加注解

代码注解可以放置在代码块中的任何位置，只要该位置可以放置代码块语言的注释，例如 JavaScript 中的// ...和/* ... */，YAML 中的# ...等1：

带注解的代码块
```yaml
theme:
  features:
    - content.code.annotate # (1)
```

1.  :man_raising_hand: 我是一个代码注解！我可以包含`code`、**格式化文本**、图像等等，基本上可以用 Markdown 表达的任何内容。

theme:
  features:
    - content.code.annotate # (1)
  1. 🙋‍♂️ 我是一个代码注解！我可以包含code、格式化文本、图像等等，基本上可以用 Markdown 表达的任何内容。

去除注释

8.5.0 · 实验性

如果希望去除代码注解周围的注释字符，只需在代码注解的右括号后面添加一个!：

带注解的代码块，去除注释
```yaml
# (1)!
```

1.  看吧，少了一些行噪音！

# (1)!
  1. 看吧，少了一些行噪音！

请注意，这仅允许在每个注释中呈现一个代码注解。如果要添加多个代码注解，由于技术原因，无法删除注释。

添加行号

可以通过在简码之后使用linenums="<起始行号>"选项将行号添加到代码块，其中<起始行号>表示起始行号。代码块可以从不是1的行号开始，这允许将大型代码块拆分为可读性更高的部分：

带有行号的代码块
```py linenums="1"
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]
```

1
2
3
4
5
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]

高亮特定行

可以通过将行号传递给hl_lines参数来突出显示特定行，该参数直接放在语言简码之后。请注意，行号从1开始计数，而不管作为linenums的一部分指定的起始行号是什么：

带有突出显示行的代码块
``` py 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]:
                items[j], items[j + 1] = items[j + 1], items[j]
```

1
2
3
4
5
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]
带有突出显示行范围的代码块
``` py hl_lines="3-5"
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]
```

1
2
3
4
5
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]

高亮内联代码块

当启用内联高亮时，可以通过在内联代码块之前添加一个 shebang，即#!，后面直接跟上相应的语言简码，将语法高亮应用于内联代码块。

内联代码块
`#!python range()` 函数用于生成一系列数字。

range() 函数用于生成一系列数字。

嵌入外部文件

当启用片段时，可以使用--8<--标记直接从代码块中嵌入其他文件（包括源文件）的内容：

带有外部内容的代码块
```title=".browserslistrc"
```
.browserslistrc
last 4 years

自定义

自定义语法主题

如果使用了Pygments，Material for MkDocs 提供了代码块的样式，它们使用自定义和平衡的调色板构建，对于颜色方案都能很好地工作：

  • --md-code-hl-number-color
  • --md-code-hl-special-color
  • --md-code-hl-function-color
  • --md-code-hl-constant-color
  • --md-code-hl-keyword-color
  • --md-code-hl-string-color
  • --md-code-hl-name-color
  • --md-code-hl-operator-color
  • --md-code-hl-punctuation-color
  • --md-code-hl-comment-color
  • --md-code-hl-generic-color
  • --md-code-hl-variable-color

代码块的前景、背景和行高亮颜色通过以下方式定义：

  • --md-code-fg-color
  • --md-code-bg-color
  • --md-code-hl-color

假设您想要更改"strings"的颜色。虽然有几种字符串标记类型，但它们使用相同的颜色。您可以通过使用附加样式表来分配新的颜色：

:root > * {
  --md-code-hl-string-color: #0FF1CE;
}

extra_css:
  - stylesheets/extra.css

如果要微调特定类型的字符串，例如#!js `backticks`，您可以在语法主题定义中查找特定的 CSS 类名，并将其作为附加样式表的一部分进行覆盖：

.highlight .sb {
  color: #0FF1CE;
}

extra_css:
  - stylesheets/extra.css

注解工具提示宽度

如果在代码注解中托管了大量内容，增加工具提示的宽度可能是一个好主意，可以通过将以下内容作为附加样式表的一部分添加来实现：

:root {
  --md-tooltip-width: 600px;
}

extra_css:
  - stylesheets/extra.css

这将以更大的宽度呈现注解：

# (1)!
  1. Muuuuuuuuuuuuuuuch more space for content

带有数字的注解

在 8.1.0之前，代码注解以显示作者使用的原始数字的标记呈现。然而，由于技术原因，代码注解数字在每个代码块中重新开始，这可能会引起困惑。因此，代码注解现在呈现为+符号，如果它们是打开的，则会旋转，以表示再次点击它们将关闭它们。

如果您希望恢复到先前的行为并显示代码注解数字，可以添加一个附加样式表，并复制粘贴以下 CSS：

.md-typeset .md-annotation__index > ::before {
  content: attr(data-md-annotation-id);
}
.md-typeset :focus-within > .md-annotation__index > ::before {
  transform: none;
}

extra_css:
  - stylesheets/extra.css

  1. 代码注解需要使用Pygments进行语法高亮-它们当前与 JavaScript 语法高亮器不兼容，或者与其语法中没有注释的语言不兼容。然而，我们正在积极努力支持定义代码注解的替代方法，允许始终将代码注解放置在行末。 ↩