链接到 asciidoc 中同一页面的部分

Question

我正在写一些文本，这些文本将被转换为 HTML，作为一个很长的单页。

无法弄清楚如何使用 #some-id 链接到 HTML 中的部分，以便用户在单击它时会在网页上向上或向下移动到

<h2 id="some-id">Section A</h2>
<p>Lot's of lines</p>
<a href="#some-id">Go to section</a>

Answer 1

您指的是“内部交叉引用”。

内部交叉引用的标记是：

<<id,caption>>

其中 id 是页面上具有标识符的元素，通常是标题，caption 是可选文本，应出现在 link.

您可以 link 到具有 auto-generated ID 的标题，但 ID 的构成可能因属性 idprefix 和（对于 Asciidoctor） idseparator 而异.默认设置是将标题文本设为小写，使用下划线作为前缀，并将空格和其他标点符号替换为下划线。标题“让我们做一个游戏吧！”的 ID将是 _lets_make_a_game.

您通常最好指定自己的 ID，即使您编辑标题的文本也能保持稳定。您可以这样做：

[[id,label]]

其中 id 是您要指定的标识符，label 是可选的默认标签，可用于交叉引用（如果交叉引用本身未指定caption).

如果您的交叉引用指向的元素是标题，您可以省略标题和标签，link 将使用标题的文本作为它自己的文本。

对于 Asciidoc，请参阅：http://asciidoc.org/userguide.html#_internal_cross_references

对于 Asciidoctor，请参阅：https://asciidoctor.org/docs/user-manual/#internal-cross-references

用法示例：

这是我们分配 ID 的方式：

== Debug Running Pods [[debug_running_pods]]

引用一个ID：

<<debug_running_pods>>

Answer 2

另一种选择是使用 link: 宏。这是我的 Asciidoctor 文档中的一个示例：

link:#_explore_the_public_directory[17.4. Explore the `public` directory]

相关信息在 https://asciidoctor.org/docs/user-manual/#url 中。以下是相关部分的摘录：

When a URL does not start with one of the common schemes, or the URL is not surrounded by word boundaries, you must use the link macro.

链接到 asciidoc 中同一页面的部分

Links to sections of same page in asciidoc

asciidoc

asciidoctor