Activating custom extensions (.asciidoctor dir)

[mlasevich]

We have a custom ruby based extension in .asciidoctor directory, it seems to work with many asciidoctor tools, but it does not look like AsciidocFX recognizes it - any way to activate it?

[rahmanusta]

Hi, unfortunately, AsciidocFX doesn’t use asciidoctor-ruby

[mlasevich]

:-( I thought it had at least of of its own ruby based plugins. I mean, how do these work (or do they?)? https://github.com/asciidocfx/AsciidocFX/tree/master/asciidoctor-extension

[rahmanusta]

You may write in JavaScript :) https://github.com/asciidocfx/AsciidocFX/tree/master/conf/public/js

[mlasevich]

I hate the idea of having two parallel versions of same plugin, one for Asciidoctor and all related tools, and one for AsciidocFX - it seems like a recipe for trouble (although to be fair, this is a very simplistic plugin, just a wildcard inlclude processor, honestly I am surprised it is not part of the standard Asciidoc) - so the question is - will AsciidocFX read the plugins from .asciidoctor or some other similar directory within the source dir? Or does it need to be installed for each system?

[rahmanusta]

Hi, the feature is available in version 1.8.4. You can test it here https://github.com/asciidocfx/AsciidocFX/releases/tag/v1.8.4 . Java and Ruby extensions will automatically be activated from the working directory. Please let me know if you notice any issue.

[verhas]

I tried this feature with the release 1.8.4 but to no luck. I suspect the main reason is the lack of documentation and my understanding of how it works.

The release does not mention the .asciidoctor directory. It mentions the .asciidoctorconfig "feature", which I could figure out from the source code is a text file that can contain configuration parameters in the working directory. These get added to the global configuration options.

I could not find any information on how to configure an extension with AsccidoFX. I created the .asciidoctor/lib directory in the working directory, whereas the *.adoc file was in the installation directory. I even tried to copy the *.jar files into the installation directory of AsciidocFX (btw: many dependencies are not the latest versions and collided with my extension). The application does not start my preprocessor.

The preprocessor extension I tried to use with AsccidocFX is Jamal from

https://github.com/verhas/jamal

which works seamlessly with the IntelliJ Asciidoctor plugin.

[rahmanusta]

Seems Jamal plugin is too IntelliJ Idea centric, I'm not sure if it will work with AsciidocFX seamlessly. AsciidocFX should register Asciidoctor plugins as they are written. You can see two examples below

https://github.com/rahmanusta/java-extension-demo

https://github.com/asciidocfx/ruby-extension-demo

[verhas]

I had a look at those examples and it is exactly how Jamal is built up:

public class JamalPreprocessor extends Preprocessor implements ExtensionRegistry {

...

    @Override
    public void register(Asciidoctor asciidoctor) {
        JavaExtensionRegistry javaExtensionRegistry = asciidoctor.javaExtensionRegistry();
        javaExtensionRegistry.preprocessor(JamalPreprocessor.class);
    }

still it is not started for some reason by AsciidocFX. I see no difference between IntelliJ and AsciidocFX except that it, for some inexplicable reason, does not work in the case of AsciidoFX and does for the IntelliJ Asciidoctor plugin.

As a matter of fact, I do not really understand why it does not work since the AsciidocFX and IntelliJ integrate the same Ruby-written Asciidoctor, which indeed handles the extensions. So, essentially, I am facing the same SPI. However, you say that Jamalis too IntelliJ "centric", so there may be some difference that I cannot see. If there is, I am happy to support and create the code that is needed to integrate Jamal into AsciidocFx.

P.S.: I am on vacation this week, usually I react faster and I appreciate your support.

[rahmanusta]

Hi,

The issue is, AsciidocFX does convert Asciidoc from String instead of File. That's why the logic https://github.com/verhas/jamal/blob/master/jamal-asciidoc/src/main/java/javax0/jamal/asciidoc/JamalPreprocessor.java#L77 is not activated. I applied a fix for this, but this way on each text change we must trigger to save the file to disk. That's something that I refrain to do.

Alternatively, I set docfile attribute in this commit https://github.com/asciidocfx/AsciidocFX/commit/6b9d748d7bc5138af72d96f9b7f055b44939a30a#diff-8199957b8393271dfef5baeb0c3955e9fd750662bdd22557cc4def26b0c52f7c . And, there is a pull request for jamal https://github.com/verhas/jamal/pull/35

I tested it with the latest AsciidocFX master and seems jamal is working.

[verhas]

I may be clumsy with something, but I needed help getting Jamal working with your patch using AsciidocFx 1.8.4 and opening a .adoc.jam file, and changing the Doctype in the menu to Asciidoc. It renders the document, but the macros are unprocessed as they are in the source file.

Jamal looks at the file name, but it works from the String in memory and does not read the file unless the very first line of the document contains the fromFile option, presumably as a comment macro, which is a particular case.

I had no luck compiling and starting up the latest version from GitHub. I could compile it without executing the tests, but then I could not start the generated jar file as an application.

[rahmanusta]

You can try with https://github.com/asciidocfx/AsciidocFX/releases/tag/v1.8.5 , it should work imho

[verhas]

Your link leads to a 404 page. There is no 1.8.5 currently.

[rahmanusta]

Sorry, I needed to revert it. It is available now https://github.com/asciidocfx/AsciidocFX/releases/tag/v1.8.5

[verhas]

I had some time today to try version 1.8.5. It works by copying all the JAR files into ~/Applications/AsciidocFX/lib. After starting AsciidocFX, it warned me about multiple versions of the same libraries, which is a brilliant thing to do. It also recommends deleting the old versions of the libraries, and after doing so it seems to be working.

I used it to edit the documentation of how to install Jamal for Asciidoctor in IntelliJ to cover installation with AsciidocFX.

There is one caveat: The snakeyaml library versions are 1.3 and 2.0. There is a good reason the version is a major upgrade. Version 2.0 is not compatible with the 1.x releases, and it was a PITA converting the Yaml module of Jamal to use version 2.0. There is a good reason to upgrade, however: security is better, and functionality was also enhanced.

I recommend upgrading the library versions to the newest versions. To keep dependencies up-to-date, you can have a look at

https://github.com/verhas/jamal/blob/master/versions.adoc

to see how I do it for Jamal. It is a Jamal preprocessed Asciidoc file that checks the latest versions on the fly and reports the outdated libraries.

Thanks a lot for including .jam as an Asciidoc extension.