Write documentation that explains how to customize the converter output using templates

[mojavelinux]

Write documentation that explains how to create a custom backend. Information to be covered includes:

• What template languages can be used (answer: anything supported by Tilt)
• The names of each template and how the file is named
• What objects are available to the template
• Brief documenation about the structure of an Asciidoctor document object model
• Commonly used instance variables and methods in the template

Some starting material can be found here:

asciidoctor/asciidoctor-backends#12 (comment)

[obilodeau]

Until the back-end documentation gets written I think this advice by @mojavelinux should be highlighted here:

p.s. To see which attributes are available, you can print them using:

- puts @document.attributes.inspect
- puts @attributes.inspect

http://discuss.asciidoctor.org/How-can-we-pass-parameters-to-HAML-HTML5-backend-template-td1036.html#a1076

Works with haml and slim templates.

[obilodeau]

- puts instance_variables
- puts local_variables
- puts @document.methods
...

is also verify useful to understand what is available to the back-end writer

edit: added other interesting things to look at to understand what you have access to

[mojavelinux]

You might find pp to produce better output (and in some cases not).

- require 'pp'
- pp @document.attributes

[mojavelinux]

Questions to answer:

• What can I accomplish using templates? What is the purpose of templates?
• What is a template? How does it fit into the Asciidoctor processor?
• What libraries do I need to make templates? (prerequisites)
• How do I make a template? What does a template look like?
• What information is available to a template (APIs, context)?
• How many templates do I need to make?
• Where do I put the templates?
• How do I use templates? What are the parameters I need to specify?
• How do I use templates with a build tool like Maven or Gradle?

[mojavelinux]

Additional raw material: http://discuss.asciidoctor.org/Add-new-attribute-to-the-html-p-tag-td3976.html

[jaredmorgs]

When this ticket is resolved, be sure to close off asciidoctor/asciidoctor.org#452 so user-guide.adoc contributors know they no longer need to discuss the section.

[kastork]

just tossing a +1 on this

[mojavelinux]

Here's some excellent material about why and how to use Pry to debug templates, contributed by @obilodeau. Definitely a key addition to this guide.

http://discuss.asciidoctor.org/Interactively-debugging-a-template-with-a-REPL-td4498.html#a4502

[jcayouette]

+100 on this topic, I think it extremely valuable. I would love to contribute here, however, my other projects do not allow me the time currently. :( If my status changes perhaps Ill spend a hackweek on it 👍

[ggrossetie]

Additional raw materials:

• https://blog.yuzutech.fr/blog/1.0/custom-converter/index.html
• Resolves #85, Explain how to create and register a custom converter asciidoctor.js#620

[settermjd]

This looks like something I could sink my teeth into, allowing for available time.

[tomschr]

It seems quite a while that this issue is open. Would be really helpful to see templates being described in the documentation. At the moment, it's hard to find all the necessary bits and pieces and put them together. It's annoying and time consuming.

Please also consider, not everybody is familiar with Ruby. 😉 Some expressions and notations should be explained. Thanks!

[mojavelinux]

I'm quite aware this documentation is sorely needed. If there were more hours in the day, I could get to it. But I'm already giving everything I've got (and then way more). (And the same is probably true for majority of the other maintainers in Asciidoctor).

While the documentation will certainly cover some basic concepts of Ruby, the templates are a programming construct and it's not the appropriate place to teach those concepts. We will be sensitive with the use of terms, but will likely link out to tutorials that you can read.

[mojavelinux]

At long last, a draft is ready! See #4180.

[mojavelinux]

I still have a bit of work to do to before merging to integrate the information from the linked resources.

[mojavelinux]

The documentation is now ready for review. I'll leave the PR up for a day or two to see if I get any feedback.

[mojavelinux]

Backport this change to v2.0.x.

[mojavelinux]

I'm pleased to announce that the documentation for converter templates is now available!

https://docs.asciidoctor.org/asciidoctor/latest/convert/templates/

Thanks to @tomschr for reviewing the content and proposing revisions.