CODEWITHSUNDEEP
githubrestructuredtextasciidoc
Phil Kang
Phil Kang

Reputation: 1018

How to generate anchor IDs for definition (labeled) lists in AsciiDoc or reStructuredText?

I'm writing documentation on GitHub, and would like to make hashtag links to individual terms in my definition lists (AKA labeled lists, description lists). Example: https://github.com/username/projectname/wiki/SomeArticle#my-term

Kramdown provides a neat feature that generates element IDs for all terms in a definition list. However, Kramdown cannot be used as the renderer in GitHub wikis.

Is there a similar feature for AsciiDoc or reStructuredText? For what I know:

Short of moving away from GitHub wiki (which is a poor option for me), what can I do?

Upvotes: 2

Views: 645

Answers (1)

eskwayrd
eskwayrd

Reputation: 4521

For Asciidoctor, you can add an identifier to each term in a definition list:

[[apple]]Apple::
  A red fruit

[[banana]]Banana::
  A yellow fruit

Then you can link to them with the in-page cross reference syntax:

See <<apple>> for more details.

As you can see, the markup is fairly simple. If you don't want to manually add the identifier, you could write a script to add them. For example, if you have a document like:

= Document

Apple::
  A red fruit.

Banana::
  A yellow fruit.

You can do this:

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

which prints:

= Document

[[apple]]Apple::
  A red fruit.

[[banana]]Banana::
  A yellow fruit.

If you need to save the result, do this:

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

Note: If your definition list contains terms with spaces, you would need to do more work to convert the spaces to hyphens, or other HTML-safe identifier characters.

Upvotes: 1

Related Questions