add third party asciidoc extension

[uniqueck]

I mean today there is no way to add third party AsciiDoc extensions to the plugin, so that it will be affected in the preview panel.

I think it would be a good idea to have a general way to add third party extensions.
I'm to familar with the intellij plugin development, but if you give me some hints, i would like to try it.

I think for the issue #237 it would also be nice, to have some kind of possibility.

[ahus1]

There is support for Ruby extensions. It works best as long as there are no additional package dependencies. See here: https://github.com/asciidoctor/asciidoctor-intellij-plugin/wiki/Support-for-Asciidoctor-Extensions

Please comment if this supports your use case, or how your use case is different. It is also possible to pre-bundle extensions, this has been done for spring-rest-docs support.

[uniqueck]

This sounds great, but i need it for java written extension.
My extensions are all in java written, so i would like it if you have a similar way for java.
Here is my extension asciidoctorj-office-extension.

[ahus1]

As it requires POI and other dependencies it needs to be packaged as plugin that extends the intellij plugin. This is not possible yet, but might be possible in the future.

Other plugins (the one for eclipse) allow referencing an Asciidoctor setup outside the IDE. This doesn't work yet for the IntelliJ plugin.

This is where we are today. I'll update the ticket when there are other options. Anyone volunteering: feel free to comment here.

[uniqueck]

let me know if i can help you.

[ahus1]

@uniqueck - thanks for volunteering!

I haven't yet figured out or found documentation on how one plugin can extend another plugin. Apparently there is an extension mechanism using extensionPoints and matching extensions. One example in this plugin is that it provides an extensionPoints for a AsciiDocHtmlPanelProvider, and also its own implementations JeditorHtmlPanelProvider and JavaFxHtmlPanelProvider for it.

I assume that this also works across plugins although I've never tried it, and I am not sure how to set it up. An extension point in this plugin could allow a second plugin to register additional block macros etc. with the Asciidoctor instance that can then participate in the rendering cycle.

The JetBrains SDK documentation
is good to show how to get started with developing plugins. Unfortunately the it doesn't provide much help about plugins extending other plugins, so I assume some digging in the code of the IntelliJ community edition would be necessary.
There is a chat on gitter that might give you short answers to short questions: https://gitter.im/IntelliJ-Plugin-Developers/Lobby

The next step would be to setup your local development environment: There is a CONTRIBUTING.adoc file that guides you through the process to setup a local development environment.

Using the guide, you should be able to do the following: Check out the source of the plugin, open it in IntelliJ and ensure that you can debug the plugin through the IntelliJ's launch configuration. You'll need to use a JDK 8 setup as described in the contributing guide.
Maybe you want to tackle one of the other (potentially smaller) issue as a warm-up.

[Azhrei]

It's only been a couple months, but is there any movement on this?

I have a need to use the tree plugin (which I think is actually MonoTree). It works in AsciiDocFX (a standalone app that works like this plugin — there's an editor window adjacent to a live preview window using JavaFX) but I can't figure out how to add it to this plugin.

Where should I start if I want to hack a solution together? I did find the .asciidoctor/lib directory that contains the various JARs, and the spot in the code that adds a bunch of .rb extensions if they exist, but I'm not sure what else might need tweaking. (And there's very little JavaDoc so I'm having a hard time jumping around between classes and keeping track of what's going on!)

Thanks!

[ahus1]

I've picked up this topic in issue #532 and the latest pre-release supports AsciidoctorJ JAR files in addition to the ruby extensions available previously.

Please have a look at #532 and join the discussion in that ticket.

I assume this enables most scenarios this ticket discussed. It doesn't support plugins for this plugin in the JetBrains marketplace. I would argue that this is out-of-scope for now / less urgent.

Please let me know what you think, and if this ticket can be closed in favor of #532.

[uniqueck]

sounds great for me. I give it a try. so i think this issue can be closed.

[ahus1]

I'm sorry that this ticket was open for so long. I suppose I aimed a bit too high when suggesting plugin for this plugin.

Only after implementing #515 and getting an extra class loader in place implementing I understand how loading AsciidoctorJ extensions was only one step away.

[uniqueck]

So i try it, but we have problems with transitive dependencies. So i think as an third party asciidoctor extension developer we have to create an jar with dependencies, if you need third party frameworks to implement your asciidoctor extension.

You can try it with my office or liquibase asciidoctor extension, to reproduce this error.

[ahus1]

@uniqueck - I've given your Liquibase extension a test run, see here for an example: https://github.com/ahus1/ad-demo-extension-liquibase

I chose to put the essential JAR dependencies alongside the extension in the lib folder. These were the minimal dependencies I used to make the Liquibase extension work (by trial and error, looking which dependencies it was missing).

After confirming the dialog "do you trust...", I get the following preview in my IDE:

[uniqueck]

Yes ok, but i think it is not a prefered way. I think better is we provide an jar with dependencies in our build process, maybe with qualifier intellij-preview-mode or so. What do you think?

[ahus1]

For a broader audience a the custom-built JAR you suggest would be a better solution. It would come at the trade-off that multiple extensions would re-package the same libraries (not a technical problem, just a matter of size). Once different extensions package different versions of the same library it would get messy. That potential mess could only be resolved (if it can be resolved) by JARs that don't include their dependencies.

For a single project that someone is personally involved, it might be ok to have separate libraries. It's probably also ok when the files are put there using a setup or build script.

The AsciiDoc plugin for IntelliJ loads all JARs found in the folder. Both custom-built JARs and separate JARs would work from a technical point of view. From the plugin's perspective I won't make a choice yet what to support or suggest. I first want to see some solution "in the wild".

I'm happy to include for example links to plugin specific instructions on the documentation site, maybe even the documentation how to use the plugin itself. I'm looking forward for pull requests.

[ahus1]

I'm closing this issue as there hasn't been a response for more than two weeks. Please continue to share your experiences as comments in this ticket, and I'll re-open it.

To share things that worked for you with future developers, please consider a pull request to the plugin's documentation.