自定义 ID

CustomIDs 是一个预处理器，它允许在使用 MkDocs 或其他提供 HTML 输出的后端构建的项目中使用 Pandoc 样式语法为 Markdown 源代码中的标题定义自定义标识符 (ID)。这些 ID 可用于指向页面特定部分的超链接。

安装

$ pip install foliantcontrib.customids

用法

要启用预处理器，请添加customids到preprocessors项目配置中的部分：

preprocessors:
    - customids

预处理器支持以下选项：

    - customids:
        stylesheet_path: !path customids.css
        targets:
            - pre
            - mkdocs
            - site
            - ghp

stylesheet_path : CSS 样式表文件的路径。此样式表应定义.custom_id_anchor_container、.custom_id_anchor_container_level_N、.custom_id_anchor和.custom_id_anchor_level_N类的规则。这N是标题级别（1到6）。默认路径是customids.css. 如果样式表文件不存在，将使用默认的内置样式表。

targets ：预处理器的允许目标。如果未指定（默认情况下），预处理器将应用于所有目标。

自定义 ID 可以在同一行的标题内容之后指定。Markdown 语法示例：

# First Heading {#custom_id_for_first_heading}

A paragraph.

## Second Heading {#custom_id_for_second_heading}

Some another paragraph.

这个 Markdown 源代码最终会转化为 HTML 代码：

<div class="custom_id_anchor_container custom_id_anchor_container_level_1"><div id="custom_id_for_first_heading" class="custom_id_anchor custom_id_anchor_level_1"></div></div>

<h1>First Heading</h1>

<p>A paragraph.</p>

<div class="custom_id_anchor_container custom_id_anchor_container_level_2"><div id="custom_id_for_second_heading" class="custom_id_anchor custom_id_anchor_level_2"></div></div>

<h2>Second Heading</h2>

<p>Some another paragraph.</p>

（请注意，CustomIDs 预处理器不会将 Markdown 语法转换为 HTML；它只会将 HTML 标签<div class="custom_id_anchor_container">...</div>插入到 Markdown 代码中。）

自定义 ID 不得包含空格和非 ASCII 字符。

引用自定义 ID 的超链接示例：

[Link to Heading 1](#custom_id_for_first_heading)

[Link to Heading 2 in some document at the current site](/some/page/#custom_id_for_second_heading)

[Link to some heading with custom ID at an external site](https://some.site/path/to/the/page/#some_custom_id)