Support `example$` for Antora symlinks

[gastaldi]

What is this issue about?

• [ ] Bug report
• [x] Feature request
• [ ] Question

Description Antora defines a special example$ directory for symlinks (see https://docs.antora.org/antora/latest/symlinks/ for the full explanation) and that does not work with the Asciidoctor maven plugin (see https://github.com/quarkiverse/quarkus-neo4j/pull/83)

[ERROR] asciidoctor: ERROR: index.adoc: line 60: include file not found: /Users/ggastald/workspace/quarkiverse/quarkus-neo4j/docs/modules/ROOT/pages/example$Fruit.java
[ERROR] asciidoctor: ERROR: index.adoc: line 186: include file not found: /Users/ggastald/workspace/quarkiverse/quarkus-neo4j/docs/modules/ROOT/pages/example$Fruit.java
[ERROR] asciidoctor: ERROR: index.adoc: line 196: include file not found: /Users/ggastald/workspace/quarkiverse/quarkus-neo4j/docs/modules/ROOT/pages/example$FruitResource.java

Environment information

• asciidoctor-maven-plugin version: 2.2.2
• asciidoctorj version: ___
• Maven, Java and OS version:

  Apache Maven 3.8.6 (84538c9988a25aec085021c365c560670ad80f63)
  Maven home: /Users/ggastald/.sdkman/candidates/maven/current
  Java version: 17.0.4, vendor: GraalVM Community, runtime: /Users/ggastald/.sdkman/candidates/java/22.2.r17-grl
  Default locale: en_BR, platform encoding: UTF-8
  OS name: "mac os x", version: "12.5", arch: "aarch64", family: "mac"

[abelsromero]

Antora adds this and many other features that are not part of asciidoctor, hence the plugin does not understand them. For instance, the example$ is also dependant on the Antora's module definition, and it's not the goal of the plugin to extends beyond what asciidoctor does.

On a personal note, I think Antora is a very capable CLI tool and I don't feel adding an additional layer on top of it is worth the effort. If you are interested in building via Maven though, you can work arround with frontend-maven-plugin to run node https://abelsromero.github.io/blog/2020/antora-with-maven.html.

[mojavelinux]

I was about to post something very similar to what Abel wrote. There's one thing I liked to add.

We could consider the possibility of supporting an Antora "mode" if antora.yml is detected in much the way the IntelliJ plugin exists. What that mode would do is activate an xref resolve extension that can make sense of xrefs that use the Antora coordinate system. If the extension is maintained separately, then all the plugin would need to do is add it automatically. Or, the end user could do so instead.

[abelsromero]

What that mode would do is activate an xref resolve extension that can make sense of xrefs that use the Antora coordinate system.

It's a worthy option but I fail to see the end goal here. We could resolve the references in the same module, but at the end you don't want to build the docs via "pure asciidoctor" if it's an Antora project right? The only case I can imagine is if the docs are re-used somehow in 2 builds like I suggested in https://github.com/quarkiverse/quarkus-neo4j/pull/83#issuecomment-1204356313.

[mojavelinux]

Yep. I'm certainly not disagreeing with you. Just sharing some possible ideas for how to think about it.

[abelsromero]

Ok, from the other story, it seems the idea is getting a preview, it's reasonable to explore it.