Skip to content

Enable Asciidoctor section anchors

Problem to solve

Section titles does not have an anchor when the document is written in AsciiDoc. Here's the same document in Markdown and AsciiDoc:

Markdown AsciiDoc
section-anchor no-section-anchor

Asciidoctor has a built-in feature to generate section anchors: https://asciidoctor.org/docs/user-manual/#anchors It's even possible to configure the auto-generated section id: https://asciidoctor.org/docs/user-manual/#sections-summary

Intended users

Everyone that writes or reads AsciiDoc document on GitLab.

Proposal

I think we should add the following attributes:

  • sectanchors: add an anchor in front of the section title when the mouse cursor hovers over it.
  • idprefix=user-content: prepend user-content to generated section ID to avoid conflicts.
  • idseparator=-: use - character between words in generated section ID.

Relax the sanitization, otherwise the link will be removed.

Links / references