Search code examples
quotingasciidoctor

Quoting square brackets in an Asciidoctor link description

I am writing a release guide in Asciidoctor for a project I am contributing.

The document contains a link and the intended link description should contain placeholes like [variable]. As Asciidoctor alsi uses square brackets to enclose the link description I quoted my square brackets. But the result is not the indended one.

Here is an simplified example of my attempt:

Here comes the problem!

https://dist.apache.org/[https://dist.apache.org/repos/\[version\]\[project\]^].

Asciidoctor (version 1.5.6.1) renders the link as https://dist.apache.org/repos/dist/dev/incubator/tamaya/\[version]/\[project]. But I expected https://dist.apache.org/repos/dist/dev/incubator/tamaya/[version]/\[project]as result.

What did I miss?

Solution

  • In my experience, using the decimal HTML Entity code is the solution. This should work for both HTML and PDF. For your case:

    I would write:

    Here comes the problem!

https://dist.apache.org/[https://dist.apache.org/repos/[version][project]^].

    If you use the entities a lot, you can use variables:

    :left_sb: [
:rigth_sb: ]

Here comes the problem!

https://dist.apache.org/[https://dist.apache.org/repos/{left_sb}version{rigth_sb}{left_sb}project{rigth_sb}^].