Inter-document cross referencing not working as expected

[himanshu-setia]

Hi,

I am using the asciidoctor gradle plugin and the inter-document cross referencing does not seem to be working as expected. Really appreciate any help on this. Thanks!

The cross reference to help.asciidoc defined below in analysis.asciidoc (both files in same directory)

xref:help.asciidoc[help] 

The html output generated for this reference in analysis.html is

<a href="#help.asciidoc">help</a></p>

While the expectation is it should be something like this

<a href="help.html">help</a></p>

My build.gradle is

buildscript {
    repositories {
        mavenCentral()
        jcenter()
    }
    dependencies {
        classpath 'org.ajoberstar:grgit:1.7.2'
        classpath 'org.asciidoctor:asciidoctor-gradle-plugin:1.5.6'
    }
}

apply plugin: 'org.asciidoctor.convert'

[mojavelinux]

When using the xref macro, it's necessary to use the .adoc file extension, which is the only official file extension for AsciiDoc files being proposed in the specification.

[himanshu-setia]

Thanks much @mojavelinux for your quick response. I switched the files to adoc extension but the cross reference still doesn't seem to work (see worklog below). Is there any documentation covering an example for using inter-document cross-referencing using the plugin? If yes, that could be very helpful

Html output

<a href="#help.adoc">help</a></p>

Expected output

<a href="help.html">help</a></p>

[mojavelinux]

org.asciidoctor:asciidoctor-gradle-plugin:1.5.6

In that case, you problem is here. That's a very outdated version of this plugin and, as I understand it, no longer actively supported. You can find the documentation for the current version here: https://asciidoctor.github.io/asciidoctor-gradle-plugin/development-3.x/user-guide/

[himanshu-setia]

Thanks @mojavelinux . I replaced it with 2.4.0 but that didn't seem to work either. Let me try the 3.x ones.

Adding some background, I am trying to utilize the gradle build system for building the documentation spread across multiple repos. In build tools (which uses asciidoctor plugin), I pull down docs from multiple repos using a gradle plugin and then let asciidoctor process those docs to produce html output. Asciidoctor plugin looks promising so far but I am not sure if it is able to handle all my requirements. I would really appreciate if you could please help with below queries

1. Does the 3.x version support html output chunking?
2. Does it support incremental builds (building on differential set of documents over the last build)?
3. Is there a way to validate cross-document links generated in output automatically using gradle?
4. Is there a way to validating html rendering is correct on the output?
5. Fundamentally is there any difference between .asciidoc and .adoc extensions?

I will get back on how switching to 3.x played out. Thanks again for your help!

[mojavelinux]

I am trying to utilize the gradle build system for building the documentation spread across multiple repos.

Given this requirement, Antora may be more suited for your needs. See https://docs.antora.org. It was designed for this very use case and it's what we use for the Asciidoctor docs. That's not to say you couldn't accomplish the same thing using the Gradle plugin. But you should at least evaluate both.

Fundamentally is there any difference between .asciidoc and .adoc extensions?

The .asciidoc extension is deprecated and is not on a standards track.

[himanshu-setia]

Thanks for the suggestion @mojavelinux. I gave Antora a quick read. Looks like it is based on the asciidoctor engine, knows the git language and can pull docs from multiple repos using configurable playbooks. I'll definitely give it a shot.

Also 3.2.0 version worked well for cross-referencing :)

However, I am still struggling to find if the html chunking is supported in 3.2.0 version of the plugin. I couldn't find it in the user-guide. Doing a bit of digging I found that chunking was added in asciidoctor version 2.0.11 and the asciidoctor-gradle-plugin 3.2.0 version (which I am using now) uses org.asciidoctor:asciidoctorj:2.2.0 as dependency, so if asciidoctorj 2.2.0 is on top of asciidoctor 2.2.0 version, it should be available if the plugin has also onboarded to support it. Is this correct? If yes, could you please point me to an example on how to use?

[mojavelinux]

Chunking has not been added to Asciidoctor core. However, as you discovered, it is available as a custom converter. Since that library is only available only as a RubyGem, you need to follow this section to add it to your Gradle build: https://asciidoctor.github.io/asciidoctor-gradle-plugin/development-3.x/user-guide/#asciidoctorj-gems-plugin

As for Antora, the approach to chunking is to do it at the source level. In other words, you pre-chunk the content. Antora will then provide a way to reassemble those chunks into longer pages (either using includes or the in progress single page exporter).

[himanshu-setia]

Thanks @mojavelinux. Most of our documentation is currently written assuming chunk support, so I am a bit hesitant switching that over to Antora. Out of curiosity, is there any good reason to not support chunking at build time in Antora? Is it considered as a bad documentation strategy compared to pre-chunking i.e. doing at source level?

On a different note, I included the RubyGem for asciidoctor-multipage which currently fails task execution with below error. I will continue exploring more in this direction.

Exception in thread "main" org.jruby.exceptions.LoadError: (LoadError) no such file to load -- asciidoctor-multipage
        at org.jruby.RubyKernel.require(org/jruby/RubyKernel.java:978)
        at RUBY.require(uri:classloader:/META-INF/jruby.home/lib/ruby/stdlib/rubygems/core_ext/kernel_require.rb:54)
        at RUBY.<main>(<script>:1)

Really appreciate your guidance.

[mojavelinux]

is there any good reason to not support chunking at build time in Antora?

Philosophically, I don't think it should be up to the computer to decide where to split content. In my experience, I produces poor reading experiences (for example, a page with a single paragraph and more links). I think this is something the author should be able to control. So far, this has proven tremendously effective and more engaging for authors.

[himanshu-setia]

Closing the issue here. Really appreciate all support on this Dan!