Add ability to use custom templates to render asciidoc to HTML

[wesruv]

Need

We're looking into recommending this extension for our (small army of) technical documentation authors at Red Hat; they'd really like to be able to see what their doc would look like on the site early and often. This extension seems like a great FOSS solution.

Only thing we're missing (I think) is a way to apply our templates for the Adoc to HTML transformation. This is a feature we'd be glad to help work on and submit as a PR, and if our authors are into using this for previewing their work, we'd love to help with the project.

A little more info in the first comment.

Possible Solution?

Thinking this could be a setting for the extension, a simple text field that defines a path where the templates live on the host machine. If it's blank it defaults to current behavior, if it's filled out it passes the templates to the HTML AsciiDoctorJS.

[wesruv]

If anyone in the know has a few to help point us in the right direction to help us get a proof of concept going, we'd be very grateful.

A few of us have poked around a little bit and hacked in some CSS, I tried finding templates or something that's currently transforming adoc to HTML but nothing jumped out at me yet.

I'm looking for what it's using to turn this:

.After landing the cloaked Klingon bird of prey in Golden Gate park:
[quote, Captain James T. Kirk, Star Trek IV: The Voyage Home]
Everybody remember where we parked.

Into this (this is just example HTML, not necessarily what the extension creates):

<div class="quoteblock">
<div class="title">After landing the cloaked Klingon bird of prey in Golden Gate park:</div>
<blockquote>
Everybody remember where we parked.
</blockquote>
<div class="attribution">
— Captain James T. Kirk<br>
<cite>Star Trek IV: The Voyage Home</cite>
</div>
</div>

We have been using Ruby AsciiDoctor and have HAML templates for HTML5 presentation, but looking to switch to AsciiDoctorJS. I'm not a fan of HAML, and would love to find some templates that work well (by default is even better) with AsciiDoctor JS that we could modify to get the HTML we prefer.

[ggrossetie]

Asciidoctor.js supports the following template engines:

• EJS
• Handlebars
• Nunjucks
• Pug
• Plain JavaScript templates

Please note that the dependencies are optional, so you will need to install them explicitly. For instance, if you want to use Nunjucks, you will need to install the nunjucks package:

npm i nunjucks

Since we are using a custom converter we will probably need to add the backend trait support_templates in the constructor: https://github.com/asciidoctor/asciidoctor-vscode/blob/master/src/asciidoctorWebViewConverter.ts

See:

• https://github.com/asciidoctor/asciidoctor.js/blob/99ba4c561ab373c72298c305ff37b712242667e8/packages/core/spec/node/asciidoctor.spec.js#L2369-L2375
• https://github.com/asciidoctor/asciidoctor.js/blob/99ba4c561ab373c72298c305ff37b712242667e8/packages/core/spec/node/asciidoctor.spec.js#L2341-L2345

We will also need a way to configure the template_dirs option. I think we should introduce a new setting.

https://github.com/asciidoctor/asciidoctor-vscode/blob/9934f0c08f979a78fb60b09c109e9e8c1f5c7e95/src/asciidocParser.ts#L180-L188

https://docs.asciidoctor.org/asciidoctor.js/latest/extend/converter/template-converter/#templates-directory

[wesruv]

Oh man, that makes sense, and is trickier than expected. Thanks for the reply! We're currently tinkering, we'll share anything we come up with :D

[xdavidson]

@Mogztter,

Thank you for your pointers. I made some code changes. Can you show me how to do local testing?

Thanks,

[ggrossetie]

Hello Lisa,

The contributing guide has been recently revised so you should be able to test your local changes if you follow this guide: https://github.com/asciidoctor/asciidoctor-vscode/blob/master/CONTRIBUTING.adoc

Let me know if you encounter any issues. We can discuss on https://chat.asciidoctor.org if needed.