How to distribute themes?

[fwilhe]

Hello,

we're evaluating to use asciidoctor-pdf for documentation. We have created a theme for our ci. The only option I see for using this theme is to copy it for each repository. This is a problem, because it makes it very hard to change the theme.

Is there a suggested way to handle this?

[mojavelinux]

I haven't really thought that far ahead yet. There are various ways you could prepare the theme for the build.

One way is to put the theme files into a shared directory and reference that directory from the build by setting the pdf-stylesdir attribute to that location.

Another way is to put the theme files into a git repository and clone the repository at the start of the build, putting it either in a shared location or to a location inside the project. Using git is probably the best strategy.

[fwilhe]

Thanks for your answer, @mojavelinux

In the long term, I think it would be great to establish a mechanism similar to extensions for firefox and chrome. I think of zipping the files (with metadata added) and providing a "gallery"/"store" where the user can browse and get themes.

In the short term, it might be an option to clone the repository containing the theme to a defined location and adjust the paths. Maybe a gradle plugin can automate this process (at least for my use case).

[mojavelinux]

👍 to your short term solution. That's what I would do.

For the long-term, I think we can leverage an existing package manager (bower, npm, gem or even bintray) to distribute the themes. As for as Asciidoctor PDF is concerned, I think it just needs to assume that the theme was already fetched and put into place. It's best to follow the Unix philosophy and make sure each tool is doing one thing (and doing it well).

[fwilhe]

I've built a (very very hacky) plugin for getting a theme from a remote git repository.

Here it is: https://github.com/fwilhe/asciidoctor-pdf-theme-gradle-plugin

There is no release yet, so it needs to be installed locally to use it. I intend to develop this further.

This is a demo document to try the plugin: https://github.com/fwilhe/asciidoctor-pdf-theme-gradle-plugin-example

[mojavelinux]

Cool! Thanks for sharing!

[fwilhe]

Thinking about if this functionality should go into the asciidoctor-gradle plugin. But I guess this has to be discussed in an issue in that project.

[mojavelinux]

In addition to the other solution proposed, it's now possible to load themes from a jar file. See the bottom of https://github.com/asciidoctor/asciidoctor-pdf/blob/master/docs/theming-guide.adoc#applying-your-theme. Themes can also be distributed as a gem as demonstrated by https://github.com/chloerei/asciidoctor-pdf-cjk-kai_gen_gothic.