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.
50 lines
2.8 KiB
50 lines
2.8 KiB
4 years ago
|
////
|
||
|
|
Included in:
|
||
|
|
|
||
|
|
- user-manual: Inter-document cross references
|
||
|
|
- faq
|
||
|
|
////
|
||
|
|
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.
|
||
|
|
|
||
|
|
[source]
|
||
|
|
----
|
||
|
|
= 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 [.path]_README.adoc_ instead of the default, [.path]_README.html_.
|
||
|
|
|
||
|
|
TIP: 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.
|
||
|
|
|
||
|
|
CAUTION: 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 [.path]_filename.html_ becomes [.path]_filename/_ (which targets [.path]_filename/index.html_).
|
||
|
|
However, this is problematic for inter-document cross references.
|
||
|
|
Any cross reference that resolves to the path [.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:
|
||
|
|
|
||
|
|
[source]
|
||
|
|
----
|
||
|
|
:relfileprefix: ../
|
||
|
|
:outfilesuffix: /
|
||
|
|
----
|
||
|
|
|
||
|
|
Now, the cross reference `+<<filename#,Label>>+` will resolve to [.path]_../filename/_ instead of [.path]_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).
|