#398: Update asciidoc-writers-guide.adoc #655
Conversation
Added tip to include relative link to a file in a sub directory using xref inline macro.
hemanik
changed the title
| @@ -366,6 +366,8 @@ include::{includedir}/xref.adoc[] | |||
|
|
|||
| include::{includedir}/xref-relative.adoc[] | |||
|
|
|||
| TIP: The xref inline macro by default resolves the link to HTML, to create a relative link to an asciidoc file in another subdirectory include `ifdef::env-github[:outfilesuffix: .adoc]` below the document header and drop the ".adoc" extension after the filename. | |||
There was a problem hiding this comment.
Is there a method which is more neutral (support any output or source format). I canimagine there are more edit environents than GitHub?
There was a problem hiding this comment.
@ecki, Thanks for pointing out, it shouldn't indeed be limited to just GitHub.
I am not aware of any generic way, will explore and update the PR.
There was a problem hiding this comment.
It's important to note that the xref macro only links to another file if the target ends in a hash suffix (e.g., # or #anchor-name). The # is how Asciidoctor distinguishes between an internal xref and an external xref.
Is there a method which is more neutral (support any output or source format).
The env-* attributes are set by the integrations. For example, the code that runs on GitHub (and GitLab) sets the env-github attribute. You should expect that each integration has a similar attribute. For example, Awestruct sets env-site. We've tried to introduce generic attributes where possible, but in some cases like GitHub, the environment is so unique that it really only applies to that specific integration.
Btw, the browser previews also need the outfilesuffix to be .adoc. Both the Chrome and Firefox plugin set this value by default now. You can also use env-browser in those environments.
There was a problem hiding this comment.
Eventually, we'll want to document all these environment attributes in the user manual. At the time of this writing, they are still evolving.
There was a problem hiding this comment.
I'd like to see outfilesuffix set to .adoc by default on GitHub. There's an issue tracking that change. See github/markup#519
|
I incorporated this into 731a287. This is now the default behavior on GitHub. |
Added tip to include relative link to a file in a sub directory using xref inline macro.
issue:#398