Document to Document Cross References

The inline xref macro can also link to IDs in other AsciiDoc documents. This eliminates the need to use direct links between documents that are coupled to a particular converter (e.g., HTML links). It also captures the intent of the author to establish a reference to a section in another document.

Here’s how a cross reference is normally defined in Asciidoctor:

The section <<images>> describes how to insert images into your document.

This cross reference creates a link to the section with the ID images.

Let’s assume the cross reference is defined in the document document-a.adoc. If the target section is in a separate document, document-b.adoc, the author may be tempted to write:

However, this link is coupled to HTML output. What’s worse, if document-b.adoc is included in the same document as document-a.adoc, the link will refer to a document that doesn’t even exist!

These problems can be alleviated by using an inter-document xref:

The ID of the target is now placed behind a hash symbol (#). Preceding the hash is the name of the reference document (the file extension is optional). We’ve also added a label since Asciidoctor cannot (yet) resolve the section title in a separate document.

When Asciidoctor generates the link for this cross reference, it first checks to see if document-b.adoc is included in the same document as document-a.doc. If not, it will generate a link to document-b.html, intelligently substituting the original file extension with the file extension of the output file.

<a href="document-b.html#section-b">Section B</a>

If document-b.adoc is included in the same document as document-a.doc, then the document will be dropped in the link target and look like the output of a normal cross reference:

<a href="#section-b">Section B</a>

Now you can create inter-document cross references without the headache.

In certain environments, such as a source repository or the browser preview extensions, you view the generated HTML through the AsciiDoc source URL. This has consequences for inter-document cross references.

Since the default suffix for relative links in the html5 backend is .html, the inter-document cross references in these environments end up pointing to non-existent HTML files. In this case, you need to change the inter-document cross references to refer to other AsciiDoc source files instead. You can achieve this behavior by setting the outfilesuffix attribute to the value as .adoc, as the example below shows.

= Document Title
ifdef::env-github,env-browser[:outfilesuffix: .adoc]

See the <<README#,README>>.

We could also write the link as link:README{outfilesuffix}[README].

The links in the generated document will now point to README.adoc instead of the default, README.html.

This configuration is no longer necessary on GitHub since GitHub now sets the value of outfilesuffix to match the file extension of the source file. However, it’s still required in GitHub-like environments such as GitLab.
You probably don’t want to set outfilesuffix to .adoc without the ifdef condition as it could result in Asciidoctor overwriting input files when you run it locally (though there’s some protection against this).

While outfilesuffix gives you control over the end of the resolved path for an inter-document cross reference, the relfileprefix attribute gives you control over the beginning of the path. When resolving the path of an inter-document cross reference, if the relfileprefix attribute is set, the value of this attribute gets prepended to the path. Let’s look at an example of when these two attributes are used together.

A common practice in website architecture is to move files into their own folder to make the path format agnostic (called “indexify”). For example, the path filename.html becomes filename (which targets filename/index.html). However, this is problematic for inter-document cross references. Any cross reference that resolves to the path filename.html is now invalid since the file has moved to a subfolder (and thus no longer a sibling of the referencing document).

To solve this problem, you can define the following two attributes:

:relfileprefix: ../
:outfilesuffix: /

Now, the cross reference <<filename#,Label>> will resolve to ../filename instead of filename.html. Since this change is specific to the website architecture described, you want to be sure to only set these attributes in that particular environment (either using an ifdef directive or via the API).