You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
26 lines
1.7 KiB
26 lines
1.7 KiB
4 years ago
|
////
|
||
|
|
Provide custom templates using the API
|
||
|
|
This file is included in the user-manual document
|
||
|
|
////
|
||
|
|
|
||
|
|
Asciidoctor allows you to override the converter methods used to convert almost any individual AsciiDoc element.
|
||
|
|
If you provide a directory of {uri-tilt}[Tilt]-compatible templates, named in such a way that Asciidoctor can figure out which template goes with which element, Asciidoctor will use the templates in this directory instead of its built-in templates for any elements for which it finds a matching template.
|
||
|
|
It will fallback to its default templates for everything else.
|
||
|
|
|
||
|
|
[source,ruby]
|
||
|
|
----
|
||
|
|
puts Asciidoctor.convert '*This* is Asciidoctor.', :header_footer => true,
|
||
|
|
:template_dir => 'templates'
|
||
|
|
----
|
||
|
|
|
||
|
|
The Document and Section templates should begin with `document` and `section`, respectively.
|
||
|
|
The file extension is used by Tilt to determine which view framework it will use to use to interpret the template.
|
||
|
|
For instance, if you want to write the template in ERB, you'd name these two templates `document.html.erb` and `section.html.erb`.
|
||
|
|
The first file extension, `.html`, maps to the converter and the second, `.erb` maps to the template engine.
|
||
|
|
To use Haml as the template engine, you'd name the templates `document.html.haml` and `section.html.haml`.
|
||
|
|
|
||
|
|
Templates for block elements, like a paragraph or sidebar, are named after the block they handle.
|
||
|
|
For instance, to override the default paragraph template with an ERB template, put a file named `paragraph.html.erb` in the template directory you pass to the `Document` constructor using the `:template_dir` option.
|
||
|
|
|
||
|
|
For more usage examples, see the {backend-git}[asciidoctor-backends], the O'Reilly {uri-asciidoctor-htmlbook}[htmlbook] project and the (massive) {tests}[test suite].
|