You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
62 lines
2.2 KiB
62 lines
2.2 KiB
4 years ago
|
////
|
||
|
|
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[]
|