API docs for what is available in templates

[matklad]

It would be cool to have some kind of API docs for which keys are allowed in module.export of template.js, and which methods are available on node. My understanding is that this API is mechanically generated from a ruby API, but I am having a hard time finding Ruby API docs as well :-)

Specifically, the problem I am trying to solve is that of syntax highlighting: I don't really like the results of hljs, and would prefer to do roll my own syntax highlighting instead. I understand how I can do that hljs way: add a JS snippet to the generated HTML which traverses all the <code> blocks and does the thing. However, I would prefer to do that at document-generation time, but I am not quite sure which node type I should add to the template to achieve that.

[ggrossetie]

I agree. As far as I know we don't have yet a comprehensive guide to write custom templates. You can read my blog post though: https://blog.yuzutech.fr/blog/1.0/custom-converter/index.html

You will find the complete list of node type. What you are looking for is a listing block.

I'm also referring a lot to the built-in HTML5 converter in Asciidoctor Ruby. You can search the file named html5.rb. Each function has the name of a node.

You can also search on GitHub Asciidoctor compile/build/conversion time syntax Highlighting. I know a few people (including myself) that did some experiments.

[ggrossetie]

Spoiler alert the most difficult task will be to support callout 😉

[ggrossetie]

Somehow related to https://github.com/Mogztter/asciidoctor-pdf.js/issues/43 I wholeheartedly agree, we need to write good documentation and provide examples where we demonstrate how to use the API.

[butcherpete]

I am not sure that I understand where to place my custom.css file. Docs indicate that I can "provide a custom stylesheet using the stylesheet attribute. A custom stylesheet does completely replace the default stylesheet."

I've tried putting this file in many different places, but I always get a "ENOENT: no such file or directory". Is it in the root of the asciidoctor-pdf directory, the asciidoctor-pdf/css directory, the directory containing the ADOC file. Does it make a difference if I have asciidoctor-pdf installed globally?

[ggrossetie]

We resolve the path relative to the Asciidoctor base directory so you can put your stylesheet next to your AsciiDoc document. You can also use an absolute path. Could you please share the command your are executing?

Is it in the root of the asciidoctor-pdf directory, the asciidoctor-pdf/css directory, the directory containing the ADOC file.

The asciidoctor-pdf directory is in your node_modules right? You should not put additional files in this directory.

Does it make a difference if I have asciidoctor-pdf installed globally?

No it should not.

[butcherpete]

Sorry, I should have made it clear that I thought this was a documentation issue. Perhaps, I shoiuld have opened a distinct issue. I appreciate your patience.

I assumed that the css would be placed in the directory aside the ADOC file I am converting to PDF. When that didn't work, I thought maybe the CSS file should be placed elsewhere perhaps with the asciidoctor-pdf in the node_modules. (But that obviously did not work.)

More testing and I can report.

These do not work:

$ asciidoctor-pdf elements-book.adoc -a title-page stylesheet="custom.css"|
$ asciidoctor-pdf elements-book.adoc -a  stylesheet="custom.css" title-page

So the -a needs to specified for each parameter.

This does work:

$ asciidoctor-pdf elements-book.adoc -a stylesheet="custom.css"

This does not:

$ asciidoctor-pdf elements-book.adoc -a stylesheet="custom.css" -a title-page|
$ asciidoctor-pdf elements-book.adoc -a title-page -a stylesheet="custom.css" 

Neither command generates a separate title page in my experience.

Thanks BTW for doing this. Really nice.