代码块¶

代码块和示例是技术项目文档的重要组成部分。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 语法高亮器时不适用。

查看其他配置选项：

• Highlight
• InlineHilite
• SuperFences
• Snippets

代码复制按钮¶

9.0.0

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

theme:
  features:
    - content.code.copy

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

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

代码选择按钮¶

9.7.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 }
# 代码块内容
```

自定义选择器¶

9.7.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="<custom 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]
```

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 使用 # ... 等。¹:

``` yaml
theme:
  features:
    - content.code.annotate # (1)
```

1.  :man_raising_hand: 我是一个代码注释！我可以包含 `code`、__格式化文本__、图像，... 基本上可以写入 Markdown 的任何内容。

theme:
  features:
    - content.code.annotate # (1)

去除注释¶

8.5.0

如果您希望去除代码注释周围的注释字符，只需在代码注释的闭合括号后添加 !：

``` yaml
# (1)!
```

1.  看，妈，少了行噪声！

# (1)!

请注意，这只允许每个注释渲染一个代码注释。如果您想添加多个代码注释，由于技术原因，注释不能被去除。

添加行号¶

可以通过在短代码后直接使用 linenums="<start>" 选项来为代码块添加行号，其中 <start> 表示起始行号。代码块可以从行号 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 开始，无论指定的起始行号是什么：

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

高亮行内代码块¶

当启用 InlineHilite 时，可以通过在行内代码块前加上 shebang，即 #!，直接后跟相应的 语言短代码 来应用语法高亮。

`#!python range()` 函数用于生成数字序列。

嵌入外部文件¶

当启用 Snippets 时，可以通过在代码块中直接使用 --8<-- 语法 嵌入来自其他文件（包括源文件）的内容：

``` title=".browserslistrc"
--8<-- ".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

如果您想调整特定类型的字符串，例如 `backticks`，可以在 语法主题定义 中查找特定的 CSS 类名，并在您的 附加样式表 中覆盖它：

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

extra_css:
  - stylesheets/extra.css

注释工具提示宽度¶

如果您的代码注释中包含大量内容，增加工具提示的宽度可能是个好主意，可以将以下内容作为 附加样式表 的一部分添加：

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

extra_css:
  - stylesheets/extra.css

这将使注释呈现更大的宽度：

# (1)!