Asciidoctor filenames with at signs (@).
It seems that it is not possible to include an Asciidoctor file, whose filename starts with @
, in the navigation.
I'm documenting a GraphQL API with that defines custom directives, and one of those directives is @index
. I don't want to use the filename index.adoc
, as I've already got one at that level of the module's file tree. So, I named the file @index.adoc
.
Antora transforms this file to HTML with no problem.
However, I'd like the file to be included in the navigation. In my nav.adoc
, I would define the entry like so:
** xref:GraphQL/directives/@index.adoc[`@index.adoc`]
But the entry is unresolved in the HTML:
<li class="nav-item" data-depth="4">
<a class="nav-link" href="#">GraphQL/directives/@index.adoc</a>
</li>
Thinking that the @
sign was being interpreted as the version delimiter, I changed my xref to be fully qualified:
** xref:current@component:API:GraphQL/directives/@index.adoc[`@index.adoc`]
That also remains unresolved. Escaping the page's @
with a backslash doesn't help.
So, I won't use @
in the filenames. If this is not considered to be a bug, an update to the documentation describing limitations in a page's filename should be included.