Links to sections of same page in asciidoc

Question

I'm writing some text that will be converted to HTML, as a long single page.

Can't figure out how to make links to sections as in HTML using #some-id, so that a user when clicking it will go up or down the web page to

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

Answer 1

What you're referring to is called an "internal cross reference".

The markup for an internal cross reference is:

<<id,caption>>

where id is an element on the page that has an identifier, typically a title, and caption is optional text that should appear in the link.

You can link to titles that have auto-generated ids, but the formation of the ids could vary based on the attributes idprefix and (for Asciidoctor) idseparator. The default is to make the title text lowercase, prefix with an underscore, and replace spaces and other punctuation with underscores. The id for the title "Let's make a game!" would be _lets_make_a_game.

It is often better for you to specify your own id that will remain stable even if you edit the text of a title. You can do so with:

[[id,label]]

where id is the identifier you want to specify, and label is the optional, default label that may be used for the cross reference (if the cross reference itself doesn't specify a caption).

If the element that your cross reference points to is a title, you can omit the caption and the label, and the link will use the title's text as its own text.

For Asciidoc, see: http://asciidoc.org/userguide.html#_internal_cross_references

For Asciidoctor, see: https://asciidoctor.org/docs/user-manual/#internal-cross-references

Usage Example:

This is how we assign an ID:

== Debug Running Pods [[debug_running_pods]]

Refer to an ID:

<<debug_running_pods>>

Answer 2

Another option is to use the link: macro. Here's an example from one of my Asciidoctor docs:

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

Info about this is in https://asciidoctor.org/docs/user-manual/#url. Here's an excerpt from the relevant part:

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.