代码块¶

代码块和示例是技术项目的重要组成部分 文档。MkDocs的材料提供了不同的语法设置方法 在构建时使用[Pygges]或 在运行时使用JavaScript语法高亮显示。

配置¶

此配置允许在代码块和内联代码上突出显示语法 块，并允许直接包含来自其他文件的源代码。添加 将以下行转换为mkdocs.yml：

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

以下部分讨论了如何使用不同的语法突出显示功能 使用[Pygges]，推荐的高亮显示，因此在使用时不适用 JavaScript语法高亮显示。

请参阅其他配置选项：

• Highlight
• InlineHilite
• SuperFences
• Snippets

代码复制按钮¶

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

theme:
  features:
    - content.code.copy

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

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

代码选择按钮¶

代码块可以包括一个按钮，允许通过以下方式选择行范围 用户，这非常适合链接到代码块的特定子部分。这允许用户动态应用[行突出显示]。添加以下内容 要全局启用mkdocs.yml：

theme:
  features:
    - content.code.select

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

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

代码注释¶

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

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

1. :man_raising_hand：我是一个代码注释！我可以包含__格式的“代码” text__、图像、。..基本上任何可以用Markdown写的东西。

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

定制选择器¶

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

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

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

1. .s2是[Pygges]为双引号生成的词素名称 串。如果你想在另一个词位中使用代码注释，而不是 注释、检查代码块并确定需要添加哪个词素 添加到附加选择器列表中。

   重要：代码注释不能在词法之间拆分。

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

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

1. :man_raising_hand：我是一个代码注释！我可以包含__格式的“代码” text__、图像、。..基本上任何可以用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的“#！js//。..以及 #！js/*。..*/，用于`#！yaml#。..等¹：

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

1.  :man_raising_hand：我是一个代码注释！我可以包含__格式的“代码”
    text__、图像、。..基本上任何可以用Markdown写的东西。

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

删除评论¶

如果你想去掉代码注释周围的注释字符， 只需添加一个！在代码注释的右括号之后：

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

1.  Look ma, less line noise!

# (1)!

请注意，这只允许按以下方式呈现单个代码注释 评论。如果要添加多个代码注释，则不能添加注释 由于技术原因被剥离。

添加行号¶

可以使用linenums=“<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”处，无论作为部分指定的起始行号如何 [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]

突出显示内联代码块¶

启用InlineHilite后，可以对内联应用语法高亮显示 通过在代码块前加上shebang（即“#！`，紧接着 相应的[语言简码][可用词法分析器列表]。

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

嵌入外部文件¶

启用Snippets时，来自其他文件（包括源文件）的内容 可以直接使用[--8<--符号][Snippets符号]嵌入 在代码块内：

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

last 4 years

自定义¶

自定义语法主题¶

如果使用[Pyggments]，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

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

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

假设您想更改“#”的颜色！js“字符串”`。虽然有 有几种[类型的字符串标记]，它们使用相同的颜色。您可以分配 使用[附加样式表]添加新颜色：

: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)!