代码块

¥Code blocks

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

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

配置

¥Configuration

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

¥This configuration enables syntax highlighting on code blocks and inline code blocks, and allows to include source code directly from other files. Add the following lines to mkdocs.yml:

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

以下部分讨论如何使用推荐的突出显示器Pygments来使用不同的语法突出显示功能，因此在使用 JavaScript 语法突出显示器时它们不适用。

¥The following sections discuss how to use different syntax highlighting features with Pygments, the recommended highlighter, so they don't apply when using a JavaScript syntax highlighter.

查看其他配置选项：

¥See additional configuration options:

• 强调

  ¥Highlight

• 内联高亮

  ¥InlineHilite

• 超级围栏

  ¥SuperFences

• 片段

  ¥Snippets

代码复制按钮

¥Code copy button

9.0.0

¥9.0.0

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

¥Code blocks can automatically render a button on the right side to allow the user to copy a code block's contents to the clipboard. Add the following to mkdocs.yml to enable them globally:

theme:
  features:
    - content.code.copy

Enabling or disabling code copy buttons for a specific code block

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

¥If you don't want to enable code copy buttons globally, you can enable them for a specific code block by using a slightly different syntax based on the Attribute Lists extension:

``` { .yaml .copy }
# Code block content
```

请注意，必须有一个语言短代码，它必须放在第一位，并且必须以.为前缀。同样，也可以为特定的代码块禁用复制按钮：

¥Note that there must be a language shortcode, which has to come first and must also be prefixed by a .. Similarly, the copy button can also be disabled for a specific code block:

``` { .yaml .no-copy }
# Code block content
```

要启用或禁用不带语法高亮显示的复制按钮，您可以使用.text语言短代码，它不会高​​亮显示任何内容。

¥To enable or disable the copy button without syntax highlighting, you can use the .text language shortcode, which doesn't highlight anything.

代码选择按钮

¥Code selection button

insiders-4.32.0

¥ insiders-4.32.0

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

¥Code blocks can include a button to allow for the selection of line ranges by the user, which is perfect for linking to a specific subsection of a code block. This allows the user to apply line highlighting dynamically. Add the following to mkdocs.yml to enable it globally:

theme:
  features:
    - content.code.select

Enabling or disabling code selection buttons for a specific code block

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

¥If you don't want to enable code selection buttons globally, you can enable them for a specific code block by using a slightly different syntax based on the Attribute Lists extension:

``` { .yaml .select }
# Code block content
```

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

¥Note that the language shortcode which has to come first must now also be prefixed by a .. Similarly, the selection button can also be disabled for a specific code block:

``` { .yaml .no-select }
# Code block content
```

代码注释

¥Code annotations

8.0.0

¥8.0.0

代码注释提供了一种便捷友好的方式，通过在代码块中添加数字标记以及使用代码块语言编写的内联注释，可以将任意内容附加到代码块的特定部分。将以下内容添加到mkdocs.yml即可全局启用它们：

¥Code annotations offer a comfortable and friendly way to attach arbitrary content to specific sections of code blocks by adding numeric markers in block and inline comments in the language of the code block. Add the following to mkdocs.yml to enable them globally:

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

1. 我是代码注释！我可以包含code 、格式化文本、图像……基本上任何可以用 Markdown 编写的内容。

Enabling code annotations for a specific code block

如果您不想全局启用代码注释，因为您不喜欢自动内联行为，则可以使用基于属性列表扩展的略有不同的语法为特定代码块启用它们：

¥If you don't want to enable code annotations globally, because you don't like the automatic inlining behavior, you can enable them for a specific code block by using a slightly different syntax based on the Attribute Lists extension:

``` { .yaml .annotate }
# Code block content
```

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

¥Note that the language shortcode which has to come first must now also be prefixed by a ..

自定义选择器

¥Custom selectors

insiders-4.32.0

¥ insiders-4.32.0

通常情况下，代码注释只能放在注释中，因为注释被认为是安全的。但是，有时可能需要将注释放在代码块中不允许使用注释的部分，例如字符串中。

¥Normally, code annotations can only be placed in comments, as comments can be considered safe for placement. However, sometimes it might be necessary to place annotations in parts of the code block where comments are not allowed, e.g. in strings.

可以为每种语言设置附加选择器：

¥Additional selectors can be set per-language:

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

1. .s2是Pygments为双引号字符串生成的词素的名称。如果您想在注释以外的词素中使用代码注释，请检查代码块并确定需要将哪个词素添加到附加选择器列表中。重要提示：代码注释不能在词素之间拆分。

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

¥.s2 is the name of the lexeme that Pygments generates for double-quoted strings. If you want to use a code annotation in another lexeme than a comment, inspect the code block and determine which lexeme needs to be added to the list of additional selectors.

{
  "key": "value (1)"
}

1. 我是代码注释！我可以包含code 、格式化文本、图像……基本上任何可以用 Markdown 编写的内容。

用法

¥Usage

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

¥Important: Code annotations cannot be split between lexemes.

Code block

``` py
import tensorflow as tf
```

import tensorflow as tf

添加标题

¥Adding a title

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

¥Now, code annotations can be used from within strings in JSON:

Code block with 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]

添加注释

¥Adding annotations

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

¥Code blocks must be enclosed with two separate lines containing three backticks. To add syntax highlighting to those blocks, add the language shortcode directly after the opening block. See the list of available lexers to find the shortcode for a given language:

Code block with annotation

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

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

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

1. 我是代码注释！我可以包含code 、格式化文本、图像……基本上任何可以用 Markdown 编写的内容。

删除评论

¥Stripping comments

8.5.0

¥In order to provide additional context, a custom title can be added to a code block by using the title="<custom title>" option directly after the shortcode, e.g. to display the name of a file:

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

¥Code annotations can be placed anywhere in a code block where a comment for the language of the block can be placed, e.g. for JavaScript in // ... and /* ... */, for YAML in # ..., etc.¹:

Code block with annotation, stripped

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

1.  Look ma, less line noise!

# (1)!

1. 瞧，妈妈，线路噪音少了！

   ¥Look ma, less line noise!

请注意，每个注释仅允许渲染单个代码注释。如果您想添加多个代码注释，由于技术原因，注释无法被移除。

¥8.5.0

添加行号

¥Adding line numbers

可以在短代码后直接使用linenums="<start>"选项为代码块添加行号，其中<start>表示起始行号。代码块可以从1以外的行号开始，这样可以拆分较大的代码块以提高可读性：

¥If you wish to strip the comment characters surrounding a code annotation, simply add an ! after the closing parenthesis of the code annotation:

Code block with line numbers

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

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]

突出显示特定行

¥Highlighting specific lines

通过将行号传递给紧跟在语言短代码后的hl_lines参数，可以高亮显示特定行。请注意，行数从1开始，无论linenums中指定的起始行号是多少：

¥Note that this only allows for a single code annotation to be rendered per comment. If you want to add multiple code annotations, comments cannot be stripped for technical reasons.

LinesLine ranges

Code block with highlighted lines

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

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]

Code block with highlighted line range

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

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]

突出显示内联代码块

¥Highlighting inline code blocks

启用InlineHilite后，可以将语法高亮应用于内联代码块，方法是在内联代码块前添加 shebang（即#! ），后跟相应的语言短代码。

¥Line numbers can be added to a code block by using the linenums="<start>" option directly after the shortcode, whereas <start> represents the starting line number. A code block can start from a line number other than 1, which allows to split large code blocks for readability:

Inline code block

The `#!python range()` function is used to generate a sequence of numbers.

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

¥Specific lines can be highlighted by passing the line numbers to the hl_lines argument placed right after the language shortcode. Note that line counts start at 1, regardless of the starting line number specified as part of linenums:

嵌入外部文件

¥Embedding external files

启用代码片段后，可以直接在代码块中使用--8<-- 符号嵌入其他文件（包括源文件）的内容：

¥When InlineHilite is enabled, syntax highlighting can be applied to inline code blocks by prefixing them with a shebang, i.e. #!, directly followed by the corresponding language shortcode.

Code block with external content

``` title=".browserslistrc"
--8<-- ".browserslistrc"
```

.browserslistrc

last 4 years

定制

¥Customization

自定义语法主题

¥Custom syntax theme

如果使用Pygments ，Material for MkDocs 会提供代码块的样式，这些样式是使用自定义且均衡的调色板构建的，对两种配色方案同样适用：

¥The range() function is used to generate a sequence of numbers.

• --md-code-hl-number-color

  ¥--md-code-hl-number-color

• --md-code-hl-special-color

  ¥--md-code-hl-special-color

• --md-code-hl-function-color

  ¥--md-code-hl-function-color

• --md-code-hl-constant-color

  ¥--md-code-hl-constant-color

• --md-code-hl-keyword-color

  ¥--md-code-hl-keyword-color

• --md-code-hl-string-color

  ¥--md-code-hl-string-color

• --md-code-hl-name-color

  ¥--md-code-hl-name-color

• --md-code-hl-operator-color

  ¥--md-code-hl-operator-color

• --md-code-hl-punctuation-color

  ¥--md-code-hl-punctuation-color

• --md-code-hl-comment-color

  ¥--md-code-hl-comment-color

• --md-code-hl-generic-color

  ¥--md-code-hl-generic-color

• --md-code-hl-variable-color

  ¥--md-code-hl-variable-color

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

¥When Snippets is enabled, content from other files (including source files) can be embedded by using the --8<-- notation directly from within a code block:

• --md-code-fg-color

  ¥--md-code-fg-color

• --md-code-bg-color

  ¥--md-code-bg-color

• --md-code-hl-color

  ¥--md-code-hl-color

假设你想改变"strings""strings"的颜色。虽然字符串标记有多种类型，但它们使用相同的颜色。你可以使用附加样式表来指定新的颜色：

¥If Pygments is used, Material for MkDocs provides the styles for code blocks, which are built with a custom and well-balanced palette that works equally well for both color schemes:

docs/stylesheets/extra.css mkdocs.yml

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

extra_css:
  - stylesheets/extra.css

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

¥Code block foreground, background and line highlight colors are defined via:

docs/stylesheets/extra.css mkdocs.yml

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

extra_css:
  - stylesheets/extra.css

注释工具提示宽度

¥Annotation tooltip width

如果您的代码注释中包含大量内容，则最好通过添加以下内容作为附加样式表的一部分来增加工具提示的宽度：

¥Let's say you want to change the color of "strings". While there are several types of string tokens, they use the same color. You can assign a new color by using an additional style sheet:

docs/stylesheets/extra.css mkdocs.yml

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

extra_css:
  - stylesheets/extra.css

这将使注释具有更大的宽度：

¥If you want to tweak a specific type of string, e.g. `backticks`, you can lookup the specific CSS class name in the syntax theme definition, and override it as part of your additional style sheet:

# (1)!

1. 更多的空间用于内容

   ¥Muuuuuuuuuuuuuuuch more space for content

---

1. 代码注释需要使用Pygments进行语法高亮——它们目前与 JavaScript 语法高亮器或语法中没有注释的语言不兼容。不过，我们正在积极开发其他定义代码注释的方式，允许始终将代码注释放在行尾。↩