Execute a custom asciidoctor converter for generateHTML

[davbader]

Background and description
I am looking to start using docToolchain for our docs.
Our documentation often includes mathematical expressions.
I use STEM blocks to write using latex syntax:

:stem: latexmath

Inline math stem:[\alpha + \beta] followed by a block equation:

[stem]
++++
\alpha + \beta = \gamma
++++

When generating HTML and publish to confluence, asciidoctor will generate code with the default mathjax deliiters, \[, \], \(, \).

However our Confluence MathJax plugin does not support the delimiters above. Thus, I followed this tutorial to write a custom converter that changes the delimiters.

Asciidoctor::Converter.for 'html5'
# => Asciidoctor::Converter::Html5Converter

class MyHtml5Converter < (Asciidoctor::Converter.for 'html5')
    register_for 'html5'

    def convert_stem node
        style = node.style.to_sym
        Asciidoctor::BLOCK_MATH_DELIMITERS[style] = ['(mathjax-block(', ')mathjax-block)']
        Asciidoctor::INLINE_MATH_DELIMITERS[style] = ['(mathjax-inline(', ')mathjax-inline)']
        super
    end
end

I can now generate the HTML site using asciidoctor with:

asciidoctor -r ./my-html5-converter.rb doc.adoc

Delimiters are changed and everything renders correctly.

However, I do not know how to execute the converter using the doctoolchain.

My preferred Solution(s)

1. The converter is not needed and there is an easy way to change the delimiter for the generatedHTML and publishToConfluence task
2. I use the converter above and somheow configure doctoolchain to execute my-html5-converter.rb while running generatedHTML

[rdmueller]

interesting problem. I am not sure if this is the solution, but you can configure doctoolchain to use ruby plugins:

https://github.com/docToolchain/docToolchain/blob/ng/scripts/AsciiDocBasics.gradle#L240

https://github.com/docToolchain/docToolchain/blob/ng/template_config/Config.groovy#L169

Does this help?

[davbader]

Thank you for the reply and the suggestions.This does look promising.

I am using the default docToolchainConfig.groovy which was generated automatically.
I have added the extension at top level:

rubyExtensions = ['my-html5-converter.rb']

Now when I run ./dtcw generateHTML, I see that the ruby extension is added, but failes to run:

> Task :generateHTML FAILED

FAILURE: Build failed with an exception.

* What went wrong:
Execution failed for task ':generateHTML'.
> (NoMethodError) undefined method `for' for Asciidoctor::Converter:Module
  Did you mean?  fork

Any idea? I am not experienced in ruby at all, sorry.

[rdmueller]

I am also not very experienced in ruby. I would take a look at other ruby plugins and see what is different. Unfortunately, there will be no time for me to do so the next two weeks. After that, I could have a look

[davbader]

I made some progress using the raw asciidoctor-gradle-plugin.

First of all I modified my converter, which now also works with inline equations:

Asciidoctor::Converter.for 'html5'
# => Asciidoctor::Converter::Html5Converter

class MyHtml5Converter < (Asciidoctor::Converter.for 'html5')
    register_for 'html5'

    def initialize backend, opts = {}
        Asciidoctor::BLOCK_MATH_DELIMITERS[:latexmath] = ['(mathjax-block(', ')mathjax-block)']
        Asciidoctor::INLINE_MATH_DELIMITERS[:latexmath] = ['(mathjax-inline(', ')mathjax-inline)']
        QUOTE_TAGS[:latexmath] = ['(mathjax-inline(', ')mathjax-inline)']
        super(backend, opts)
    end
end

Now I can successfully build and generate hmtl using the following build.gradle

plugins {
    id "org.asciidoctor.jvm.convert" version "3.3.2"
}

repositories {
    mavenCentral()
}

asciidoctor {
  sourceDir  file('docs')
  sources {
    include 'index.adoc'
  }
  outputDir  file('build/docs')

  asciidoctorj {
    modules {
        diagram.use() 
        diagram.version '2.2.11'
    }
    requires './my-html5-converter.rb'
  }

}

I needed to add my custom converter to the requires option in asciidoctorj.

Adding rubyExtensions = ['my-html5-converter.rb'] at top level procudes the error above. But I can add it to mircosite (as documented in the default docToolchainConfig.groovy and the my-html5-converter.rb is called!

However, I am still lost on how to include this in the docToolchain generateHMTL task.

[davbader]

Again some progress has been made...

I had tested everything with docToolchain-2.2.1. Once I changed to latest build I got the error:

FAILURE: Build failed with an exception.

* Where:
Script '/home/dbader/.doctoolchain/docToolchain-latest/scripts/AsciiDocBasics.gradle' line: 247

* What went wrong:
A problem occurred evaluating script.
> Cannot set the value of read-only property 'requires' for task ':asciidoctor' of type org.asciidoctor.gradle.jvm.AsciidoctorTask.

which I had seen previously when adding the required flag to asciidoctor instead of asciidoctorj.

I mentioned above that the custom converter had to be added to asciidoctorj options. I noticed, that in AsciiDocBasic it was added to any AbstractAsciidoctorTask. Thus, I change it to:

// good to see what the build is doing...
    logDocuments = true

    //TODO: write docs
    asciidoctorj {
        if (config.rubyExtensions) {
            config.rubyExtensions.each { extension ->
                def root= new File(projectDir.canonicalPath)
                def full= new File(new File(docDir,extension).canonicalPath)
                def relPath = root.toPath().relativize( full.toPath() ).toFile()
                requires += ["./$relPath"]
                logger.info ("added required ruby extension '$full'")
            }
        }
    }
    // fix for #1150

This produces the expected results.
Do you think this is the correct fix, or will this have other negative side effects?

[rdmueller]

looks good. Great Work!
I guess it will have no side effects. I only know of one other project which uses the ruby extensions. I will have to give it a try to see if it still works with 3.0.1

[PacoVK]

Thanks for your investigation! I try to find time in the next two weeks to figure out how we can incorporate a fix.

[cgoguyer]

Hello,
is there some news for this issue?

[PacoVK]

@cgoguyer thanks for the valuable hints, that made the fix easy for me to implement ❤️