////
Included in:

- user-manual: Inter-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:

[source]
----
include::ex-xref.adoc[tag=base]
----

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

Let's assume the cross reference is defined in the document [.path]_document-a.adoc_.
If the target section is in a separate document, [.path]_document-b.adoc_, the author may be tempted to write:

[source]
----
include::ex-xref.adoc[tag=bad]
----

However, this link is coupled to HTML output.
What's worse, if [.path]_document-b.adoc_ is included in the same document as [.path]_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:

[source]
----
include::ex-xref.adoc[tag=base-inter]
----

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 [.path]_document-b.adoc_ is included in the same document as [.path]_document-a.doc_.
If not, it will generate a link to [.path]_document-b.html_, intelligently substituting the original file extension with the file extension of the output file.

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

If [.path]_document-b.adoc_ is included in the same document as [.path]_document-a.doc_, then the document will be dropped in the link target and look like the output of a normal cross reference:

[source,html]
----
<a href="#section-b">Section B</a>
----

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

==== Navigating Between Source Files

include::xref-source-to-source.adoc[]