Document Processors
Choosing a Document Processor
By default, PureBuilder Simply uses Pandoc
as its document processor.
Pandoc is an extremely powerful tool and allows you to take full
advantage of what PureBuilder Simply can offer.
However, PureBuilder Simply does not depend solely on
Pandoc—you can also choose other document processors.
The processor to use is specified in .pbsimply.yaml
with the pbsimply_processor value.
| Processor | pbsimply_processor |
|---|---|
| RDoc | rdoc |
| RDoc/Markdown | rdoc_markdown |
| Kramdown | kramdown |
| Redcarpet | redcarpet |
| CommonMarker (cmark-gfm) | cmark |
| Docutils (experimental) | docutils |
That said, Pandoc remains the most powerful option, and choosing a processor other than Pandoc may result in functional limitations.
When initializing with pbsimply-init, in version
3.x the Kramdown theme will be used if no theme
is specified.
This is because installing Pandoc can be somewhat heavy for
users, whereas installing Kramdown is relatively easy as long as
a Ruby environment is already available to run PureBuilder
Simply.
Overview of Document Processors
RDoc
Summary
It uses RDoc, the standard documentation system of Ruby.
Source files are treated as RDoc, and the target is limited to
*.rdoc files.
Templates are handled as eRuby templates.
Dependency
- rdoc library
Disabled configurations
csstocpandoc_additional_optionspost_eruby
RDoc/Markdown
Summary
Use the Markdown processor of RDoc, Ruby’s standard document
system. Treat source files as if they were Markdown, limited to
*.md files.
Templates are handled as eRuby templates.
Dependency
- rdoc library
Disabled configurations
csstocpandoc_additional_optionspost_eruby
Kramdown
Summary
It is generated using Kramdown, Ruby’s Markdown library.
Treat source files as if they were Markdown, limited to
*.md files.
Templates are handled as eRuby templates.
Dependency
- kramdown library
Disabled configurations
csstocpandoc_additional_optionspost_eruby
Additional configurations
| Key | Type | Description |
|---|---|---|
kramdown_features |
Hash | An associative array passed as the second argument to
Kramdown::Document.new. See the API documentation for details |
Redcarpet
Summary
It is generated using Redcarpet, Ruby’s Markdown library.
Treat source files as if they were Markdown, limited to
*.md files.
Templates are handled as eRuby templates.
Dependency
- redcarpet library
Disabled configurations
csstocpandoc_additional_optionspost_eruby
Additional configurations
| Key | Type | Description |
|---|---|---|
redcarpet_extensions |
Hash | An associative array showing the extensions to Redcarpet. See the Redcarpet page for details. |
Redcarpet
Summary
Generated using CommonMarker, a Ruby wrapper for
libcmark-gfm. Source files are treated as Markdown,
and the target is limited to *.md files.
The table and strikethrough
extensions are enabled.
Templates are handled as eRuby templates.
Dependency
- libcmark-gfm
- commonmarker library
Disabled configurations
csstocpandoc_additional_optionspost_eruby
Additional configurations
| Key | Type | Description |
|---|---|---|
commonmarker_options |
Array | render_doc options. |
Docutils
Summary
Generated using Docutils ReSTructured Text processor written
by Python. Source files are treated as ReSTructured Text, and
the target is limited to *.rst files.
Dependency
- Docutils (
rst2html5)
Disabled configurations
tocpandoc_additional_options
Additional configurations
| Key | Type | Description |
|---|---|---|
docutils_options |
Array | Command-line option arguments for rst2html5
command. |