如何在 AsciiDoc 或 reStructuredText 中为定义(标记)列表生成锚点 ID?

Question

我正在GitHub上编写文档，并希望为我的定义列表(AKA标记列表，描述列表(中的单个术语提供主题标签链接。示例：https://github.com/username/projectname/wiki/SomeArticle#my-term

Kramdown提供了一个简洁的功能，可以为定义列表中的所有术语生成元素ID。但是，Kramdown不能用作GitHub wiki中的渲染器。

AsciiDoc 或 reStructuredText 是否有类似的功能？据我所知：

• AsciiDoc 允许定义自定义锚点。但是如果可能的话，我不想手动添加锚点。
• (sphinx-powered(reStructuredText支持创建和链接到自定义标签，但它似乎不适用于GitHub。
• reStructuredText 允许您使用:term:角色链接到词汇表中的任何术语。但是，GitHub 也不支持.. glossary::指令。

除了离开GitHub wiki(这对我来说是一个糟糕的选择(，我能做什么？

Answer 1

对于 Asciidoctor，您可以为定义列表中的每个术语添加标识符：

[[apple]]Apple::
A red fruit
[[banana]]Banana::
A yellow fruit

然后，您可以使用页内交叉引用语法链接到它们：

See <<apple>> for more details.

如您所见，标记相当简单。如果不想手动添加标识符，可以编写脚本来添加它们。例如，如果您有如下文档：

= Document
Apple::
A red fruit.
Banana::
A yellow fruit.

您可以这样做：

cat file.adoc | perl -ne 's/^([^:[]+)::$/[[L$1E]]$1::/; print $_'

其中打印：

= Document
[[apple]]Apple::
A red fruit.
[[banana]]Banana::
A yellow fruit.

如果需要保存结果，请执行以下操作：

cat file.adoc | perl -ne 's/^([^:[]+)::$/[[L$1E]]$1::/; print $_' > file_with_id.adoc

注意：如果定义列表包含带空格的术语，则需要执行更多工作才能将空格转换为连字符或其他 HTML 安全标识符字符。