Markdown的自定义块

Customblocks是Python-Markdown （Python-Markdown）的一个扩展，用于设置一个用于可自定义和可嵌套组件的通用标记，其输出可以通过简单的Python函数进行重新定义。

提供了许多现成的组件，如div容器、警告、图、链接卡片、地图等，以及来自常见网站（维基百科、YouTube、Vimeo、PeerTube、Mastodon、Twitter、Facebook、Instagram、Goteo、Verkami等）的一些嵌入式小工具。

还包括方便的工具来简化组件定义：超脚本HTML生成、缓存页面获取和元数据页面提取。

安装和设置

要安装

$ pip install markdown-customblocks

然后像其他Markdown扩展一样激活它。

从命令行

$ markdown -x customblocks ...

在Python代码中

import markdown
md = markdown.Markdown(extensions=["customblocks"])
md.convert(markdowncontent)

在Pelican配置文件中

MARKDOWN = {
    'extensions': [
        'customblocks',
    ],
}

对于MkDocs，将以下内容添加到mkdocs.yml

markdown_extensions:
  - customblocks

如果您需要为扩展指定附加参数，请参阅您的生成器文档。

基本用法

Customblocks扩展解析如下标记结构

::: mytype "value 1" param2=value2
    Indented **content**

默认情况下，它生成如下HTML

<div class="mytype value-1" param2="value2">
   <p>Indented <b>content</b></p>
</div>

这是默认生成器的输出：container。但我们可以将mytype绑定到如下所示的Python自定义函数

def mygenerator(ctx, param1, param2):
    return f"""<div attrib1="{param1}" attrib2="{param2}">{ctx.content}</div>"""

然后，之前的Markdown将生成其他HTML

<div attrib1="value 1" attrib2="value2">Indented **content**</div>

请注意，这个函数没有转义任何接收到的值，也没有将内容中的任何内容转换为Markdown。幸运的是，customblocks提供了一些有用的工具：超脚本生成器和Markdown子解析器

from customblocks.utils import E, Markdown

def mygenerator(ctx, param1, param2):
    return E('', attrib1=param1, attrib2=param2,
        Markdown(ctx.content, ctx.parser)
    )

您可以在相关文档中了解更多关于它们的信息。

内置生成器

为了方便，customblocks还提供了以下预定义生成器

• container：具有任意类、属性和内容的div元素。如果没有匹配的类型，则这是默认值。
• admonition：警告、注释、警告等框（与标准额外扩展相当相似）。它与类型note、info、error、warning等绑定。
• figure：具有标题、灯箱等完整功能的图像。
• map：来自OpenStreetMaps.org的地图。
• linkcard：外部链接卡片（类似于Facebook和Twitter在您发布链接时的行为）。
• wikipedia：根据词元（和语言）生成的维基百科文章卡片。
• youtube：来自youtube的嵌入视频。
• vimeo：来自vimeo的嵌入视频。
• peertube：来自peertube的嵌入视频。
• mastodon：来自mastodon的嵌入帖子。
• twitter：嵌入推文。
• facebook：来自facebook的嵌入帖子。
• instagram：来自instagram的嵌入帖子。
• verkami：[Verkami]中的筹款项目小部件。
• goteo：[Goteo]中的筹款项目小部件。

通用标记语法

这是一个更完整的标记示例

::: mytype param1 key1=value1 "other param" key2='value2 with words' flag1 noflag2
    Indented **content**

    The block ends whenever the indentation stops
This unindented line is not considered part of the block

标题： 以:::开头的行是标题。它首先指定了块类型（mytype），然后是一组将被传递给生成器作为参数的值。

块类型： 类型用于选择生成器函数。如果没有与类型绑定的生成器，则默认使用div-container生成器。

引号： 可以使用单引号或双引号传递多词值。如果您的值是单词，则可以省略引号。

显式关键字： 一些值也可能通过具有键的显式参数来目标。这如下所示：从可用的块参数中，首先设置具有键的值，然后通过位置填充剩余未设置的参数。

标志（布尔值）： 可以通过仅添加具有标志名称的值来设置布尔参数（标志），例如示例中的flag1。并且可以通过添加具有no前缀的名称来取消设置，例如示例中的noflag2。

内容： 在标题之后，可能跟随几行缩进的内容。内容以回到之前缩进的第一个非空行结束。

缩进从内容中移除以供生成器处理。块类型可以选择将此内容解释为Markdown。因此，您可以通过添加额外的缩进来具有嵌套块。例如

::: recipe
    # Sweet water
    ::: ingredients "4 persons"
        - two spons of suggar
        - a glass of tap water
    ::: mealphoto sweetwater.jpg
        Looks gorgeus!
    Drop the suggar into the glass. Stir.

::: note 结束标签:::是可选的。在大多数情况下，缩进应该足够，从视觉和功能上讲。但是，很少需要这样做。例如下面的例子中，mealphoto内容将与后面的代码块混合

    ::: mealphoto sweetwater.jpg
            Looks gorgeus!
    :::
            This is a code block by indentation

进一步阅读

• 完整文档
• 代码
• 发布历史
• 路线图
• 动机和设计选择
• 灵感和致谢