Problem
The AsciiDoc documentation advises the use of xref macros instead of link or http macros for linking to other AsciiDoc files:
https://docs.asciidoctor.org/asciidoc/latest/macros/link-macro/#link-to-a-relative-file
If you want to link to a non-AsciiDoc file that is relative to the current document, use the link macro in front of the file name.
Tip: To link to a relative AsciiDoc file, use the xref macro instead.
Unfortunately if we try that in the context of this plugin, you get a link to the wrong place.
Example
Given _src/index.adoc content like this:
= Home page
Link to xref:page1.adoc[page 1]
And _src/page1.adoc:
= Page 1
content here
Link back to xref:index.adoc[home page]
Then the resulting link in _site/index.html will be to page1.html. It should be to page1/index.html.
The link in _site/page1/index.html will be to index.html. It should be to ../index.html or perhaps /index.html.
Workaround
The obvious workaround is to ignore the advice and use link macros. But possibly this could be fixed simply? Is there a configuration which adjusts this behaviour? This would allow AsciiDoc files which follow the advice to be imported for use in Eleventy without needing adjustment.
Problem
The AsciiDoc documentation advises the use of
xrefmacros instead oflinkorhttpmacros for linking to other AsciiDoc files:https://docs.asciidoctor.org/asciidoc/latest/macros/link-macro/#link-to-a-relative-file
Unfortunately if we try that in the context of this plugin, you get a link to the wrong place.
Example
Given
_src/index.adoccontent like this:And
_src/page1.adoc:Then the resulting link in
_site/index.htmlwill be topage1.html. It should be topage1/index.html.The link in
_site/page1/index.htmlwill be toindex.html. It should be to../index.htmlor perhaps/index.html.Workaround
The obvious workaround is to ignore the advice and use
linkmacros. But possibly this could be fixed simply? Is there a configuration which adjusts this behaviour? This would allow AsciiDoc files which follow the advice to be imported for use in Eleventy without needing adjustment.