Snippets

概述

Snippets 是将 Markdown 或 HTML 片段插入到另一个 Markdown 文件的扩展。
Snippets 非常适合需要将内容插入多个文档的情况。 例如，此文档将其所有超链接保存在一个单独的文件中，然后通过Snippets将这些超链接包含在文档的底部。 如果一个链接需要更新，它可以在一个位置更新，而不是在多个文件中更新。

Snippets是作为预处理器运行的，所以如果在一个隔离的代码块中找到一个片段，它仍然会被处理。

如果处理了代码段声明，并且找不到指定的文件，则将删除标记。

代码片段可以处理递归文件包含。 如果Snippets在当前堆栈中遇到相同的文件，它将避免重新处理它，以避免无限循环(或在达到最大递归深度时崩溃)。

这意味着简单的文件包含，它不打算从复杂的模板系统实现功能。 如果需要更复杂的东西，可以考虑在通过Python Markdown提供文件 之前 使用模板环境来处理文件。 如果您正在使用文档生成系统，则可能通过该文档系统的插件来执行此操作(假设有可用的插件环境)。

Snippets扩展可以通过以下方式包含在Python Markdown中:

import markdown
md = markdown.Markdown(extensions=['pymdownx.snippets'])

片段符号

有两种插入代码片段的模式:单行和块。 单行模式接受单个文件名，块模式接受多个文件。 Snippets不需要特定的扩展名，只要指定了有效的文件名，它就会尝试处理它。

代码片段路径相对于基本位置，默认情况下是当前工作目录。 您可以通过设置base_path来指定新的基本位置。 您甚至可以允许从外部位置下载片段。 要了解更多信息，请查看“指定代码片段位置”和“URL Snippet”。

单行格式

单行格式通过为单行表示法放置以下标记来完成:

--8<-- "filename.ext"

如您所见，符号是ASCII剪刀剪下一行，后面跟着文件名。 在单行变体的情况下，文件名直接跟在剪刀后面并加引号。 在块格式的情况下，文件名在单独的行后面，然后添加一个额外的剪刀来表示块的结束。

破折号可以只有2(--8<--)或更长如果需要(---8<---------);不管你喜欢什么。 重要的是，符号必须单独驻留在一行中，并且在单行符号的情况下，路径必须加引号。 如果文件名缩进，则内容也将缩进到该级别。

您可以通过在文件名前放置;来暂时禁用该代码片段:

--8<-- "; skip.md"

块格式

第二种方法被称为块格式。块格式允许您插入多个文件。

--8<--
filename.md
filename.log
--8<--

块格式与单一格式的不同之处在于，它要求内容被分隔在两个 --8<-- 之间。 开始和结束 --8<-- 必须单独在一条线上。

当使用块格式时，块内也保留空行。考虑下面的例子。

--8<--
fileA.md

fileB.md
--8<--

This would yield:

Content of file A.

Content of file B.

如果有一个文件想要暂时忽略，可以在行首加上;，将其注释掉。

--8<--
include.md
; skip.md
--8<--

段行

在指定代码片段时，可以指定希望包含的代码片段文件的哪些行。 要指定行号，只需将开始和/或结束附加到文件名的末尾，每个数字用:分隔。

• 要指定从特定行号开始提取内容，只需使用 file.md:3.
• 要提取到特定行的所有内容，使用file.md::3。这将提取第1-3行。
• 要提取从特定行开始到另一行的所有内容，使用file.md:4:6。这将提取第4-6行。

--8<-- "file.md:4:6"

--8<--
include.md::3
--8<--

段落

指定代码片段行可能并不总是理想的。 源可以通过移动、添加和/或删除线来改变。 解决这个问题的一种方法是将代码片段划分为命名的部分，然后针对要包含的特定部分而不是特定的行号。

可以通过在文本块周围加上--8<-- [start:name]和--8<-- [end:name]来指定 Snippet 段落。 然后，文件可以简单地使用名称而不是行号指定代码段。

--8<-- "include.md:name"

--8<--
include.md:name
--8<--

与其他代码段语法不同，部分开始和结束语法不必单独在一行中。 这允许您根据文件类型将它们嵌入到注释中。 当包含一个节时，包含开始和结束的行总是被省略。

如果我们想要包含一个来自Python源代码的函数，我们可以像下面这样指定代码片段:

# --8<-- [start:func]
def my_function(var):
    pass
# --8<-- [end:func]

然后将它包含在我们的文档中:

--8<-- "example.py:func"

转义片段表示法

如果需要演示代码段语法，则需要使用转义方法。 如果需要转义代码段，只需在--8<--之前加一个;。 这将适用于单行和块格式。 转义后的代码片段表示法将通过Markdown解析器传递，第一个;将被删除。

```
;--8<-- "escaped.md"
;;--8<-- "escaped.md"
```

--8<-- "escaped.md"
;--8<-- "escaped.md"

指定代码段位置

所有代码段都是相对于base_path选项中指定的基本路径指定的。 base_path是一个路径列表(但出于遗留目的，它将使用单个字符串)。

在计算路径时，将按照指定的顺序执行。 将根据每个基路径对指定的代码段进行求值，并返回产生有效代码段的第一个基路径。

如果基本路径是一个文件，则将指定的代码片段与该文件的基本名称进行比较。 例如，如果我们指定了一个代码片段test.md，并且我们有一个base_path为py3 ["some/location/test.md"]，这将匹配。 指定的location/test.md代码段将不匹配。 如果您在基本目录之外有一个一次性文件，但是您希望直接包含它，那么这非常好。

URL片段

如果启用了url_download， URLs也可以用作代码片段。 而不是使用文件，只需在其位置指定一个URL。 默认情况下，内容的最大大小通过url_max_size指定，默认超时通过url_timeout指定。 如果其中任何一个设置为零，则忽略限制。

使用url_request_headers在每个HTTP请求中传递任意HTTP头。

Auto-Append片段

Snippets被设计为一种通用的方法，用于定位文件并将其注入到给定的Markdown文件中，但有时，特别是当通过像MkDocs这样的库构建文档时，提供一种方法将给定文件附加到每个Markdown文档中，而不必在每个页面中通过Snippet语法手动包含它们，这可能是有意义的。 这对于在每个页面上包含一页参考链接或缩写尤其有用。

Snippets提供了一个auto_append选项，允许用户指定一个文件列表，这些文件将自动添加到每个Markdown内容。 相对于“base_path”条目搜索列表中的每个条目。

选项