August 12, 2014

Awesome Asciidoctor: Links Without URI Scheme

Since Asciidoctor 1.5.0 we can use the document attribute hide-uri-scheme to turn URLs into links, where the link text is displayed without the URI scheme. This can save typing when we simply want to add a URL without any special description.

In the next Asciidoc syntax we first define URLs without the hide-uri-scheme attribute, followed by URLs after the attribute is set:

Reference to http://www.mrhaki.com is 
turned into link +
`+<a href="http://www.mrhaki.com">http://www.mrhaki.com</a>+`.

To loose URI scheme we could write the link
as http://www.mrhaki.com[www.mrhaki.com]. Or we 
can use the new attribute `hide-uri-scheme` which is
added to Asciidoctor 1.5.0.


After applying the `hide-uri-scheme` attribute
the URI scheme is removed from the text in links.
So a reference to http://www.mrhaki.com is
turned into the link +
`+<a href="http://www.mrhaki.com">www.mrhaki.com</a>+`

This also works for other URI schemes like `file`.
For example 
file:///Users/mrhaki/file.txt is translated to +
`+<a href="file:///Users/mrhaki/file.txt">/Users/mrhaki/file.txt</a>+`.

When we generate output using the HTML backend we see the following output:

Written with Asciidoctor 1.5.0.