How to link to a relative AsciiDoc document

A syntax for creating links to relative documents that work both in GitHub previews and in the published documentation (HTML, PDF, etc) is currently being discussed in Asciidoctor issue #417. Until that issue is resolved, this page outlines strategies that can be used with the existing syntax.

Solution #1: Extension in attribute

In the header, you define an attribute for the extension of relative documents, guarded by the environment in which the document is being viewed. While this is ideal, it will only work once GitHub is upgraded to Asciidoctor 0.1.3 (currently on Asciidoctor 0.1.0).

:ext-relative: {outfilesuffix}

Important

If you are using the GitHub wiki to write documentation, then ext-relative should be set to an empty value.

Note	The attribute outfilesuffix is set automatically based on the backend in use.

Then you create your relative links like:

* link:index{ext-relative}[]
* link:Creating-a-Source-Module{ext-relative}[]

Other possible solution is to set the extension explicitly in the header of the document:

:ext-relative: adoc

That will make relative links work on GitHub in any version of Asciidoctor. Then, you explicitly set the relative extension when you invoke Asciidoctor as part of your build, or when calling it directly:

$> asciidoctor -a relative-ext=.html sample.adoc

or

$> asciidoctor -a relative-ext=.xml -b docbook sample.adoc

If you have ideas about how the link macro should work to accommodate linking to relative AsciiDoc document, we welcome your feedback on Asciidoctor issue #417.