2018-10-16 18:53:37 +02:00
|
|
|
---
|
|
|
|
|
author:
|
|
|
|
|
- Mauro Bieg
|
|
|
|
|
- John MacFarlane
|
|
|
|
|
title: Customizing Pandoc
|
|
|
|
|
---
|
|
|
|
|
|
2018-10-16 18:10:34 +02:00
|
|
|
This document provides a quick overview over the various ways to
|
2018-10-16 18:53:37 +02:00
|
|
|
customize pandoc's output, with links to fuller documentation
|
|
|
|
|
and some examples.
|
|
|
|
|
|
|
|
|
|
## Templates
|
|
|
|
|
|
|
|
|
|
When the `-s`/`--standalone` option is used, pandoc will
|
|
|
|
|
generate a standalone document rather than a fragment.
|
|
|
|
|
For example, in HTML output this will include the
|
|
|
|
|
`<head>` element; in LaTeX output, it will include the
|
|
|
|
|
preamble.
|
|
|
|
|
|
|
|
|
|
Pandoc comes with a default template for (almost) every output
|
|
|
|
|
format. A template is a plain text file containing variables
|
|
|
|
|
that are replaced by text generated by pandoc. For example,
|
|
|
|
|
the variable `$body$` will be replaced by the document body,
|
2018-11-17 14:39:26 +01:00
|
|
|
and `$title$` by the title from metadata.
|
2018-10-16 18:53:37 +02:00
|
|
|
|
|
|
|
|
To look at the default template for an output format, you can do
|
|
|
|
|
`pandoc -D FORMAT`, where `FORMAT` is replaced by the name of
|
2018-11-17 14:39:26 +01:00
|
|
|
the format. For example `pandoc -D latex`. You can also use your
|
|
|
|
|
own template instead, either by using the `--template` option
|
2018-10-16 18:53:37 +02:00
|
|
|
or by putting the custom template in your user data directory
|
|
|
|
|
(on linux and macOS, `~/.pandoc/templates/`).
|
|
|
|
|
|
2018-10-16 19:42:48 +02:00
|
|
|
Note that in many cases you can avoid the need for a custom
|
2018-11-17 14:23:49 +01:00
|
|
|
template by including a file with the `--include-in-header`,
|
|
|
|
|
`--include-before-body`, or `--include-after-body` option.
|
|
|
|
|
Or you can set the corresponding template variable directly.
|
|
|
|
|
|
|
|
|
|
### Template variables
|
|
|
|
|
|
|
|
|
|
There are several ways to set template variables:
|
|
|
|
|
|
|
|
|
|
| | [`--variable`] | [`--metadata`] | [YAML metadata] and [`--metadata-file`] |
|
|
|
|
|
|:---------------|:------------------|:------------------|:----------------------------|
|
|
|
|
|
| values can be… | strings and bools | strings and bools | also YAML objects and lists |
|
|
|
|
|
| strings are… | inserted verbatim | escaped | interpreted as markdown |
|
|
|
|
|
| accessible by filters: | no | yes | yes |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
[`--variable`]: http://pandoc.org/MANUAL.html#option--variable
|
|
|
|
|
[`--metadata`]: http://pandoc.org/MANUAL.html#option--metadata
|
|
|
|
|
[YAML metadata]: http://pandoc.org/MANUAL.html#extension-yaml_metadata_block
|
|
|
|
|
[`--metadata-file`]: http://pandoc.org/MANUAL.html#option--metadata-file
|
|
|
|
|
|
|
|
|
|
|
2018-10-16 19:42:48 +02:00
|
|
|
|
2018-10-16 18:53:37 +02:00
|
|
|
For more information, see [Templates](/MANUAL.html#templates) in
|
|
|
|
|
the pandoc manual.
|
|
|
|
|
|
|
|
|
|
### Example: adding structured author data to HTML
|
|
|
|
|
|
|
|
|
|
TODO
|
|
|
|
|
|
|
|
|
|
### Example: generating documents from YAML metadata
|
|
|
|
|
|
|
|
|
|
TODO <!-- Example of generating a structured document,
|
|
|
|
|
say, a table, from structured YAML metadata using
|
|
|
|
|
just the control structures in pandoc's template
|
|
|
|
|
language. -->
|
|
|
|
|
|
|
|
|
|
## Reference docx/pptx/odt
|
|
|
|
|
|
|
|
|
|
For `docx`, `pptx` or `odt` documents, things are a bit more
|
|
|
|
|
complicated. Instead of a single template file, you need to
|
|
|
|
|
provide a customized `reference.docx/pptx/odt`.
|
|
|
|
|
See the manual for the
|
|
|
|
|
[`--reference-doc`](/MANUAL.html#option--reference-doc) option.
|
|
|
|
|
|
|
|
|
|
### Example: changing the font and line spacing in a Word docx
|
|
|
|
|
|
|
|
|
|
TODO
|
|
|
|
|
|
|
|
|
|
## Filters
|
|
|
|
|
|
|
|
|
|
Templates are very powerful, but they are only a sort of scaffold to
|
|
|
|
|
place your document's body text in. You cannot directly change the
|
|
|
|
|
body text using the template.
|
|
|
|
|
|
|
|
|
|
If you need to affect the output of the actual body text, you
|
|
|
|
|
can use a pandoc filter. A filter is a small program that
|
|
|
|
|
transforms the document, between the parsing and the writing phase,
|
|
|
|
|
while it is still in pandoc's native format. For example,
|
|
|
|
|
a filter might find all the Header elements of a document
|
|
|
|
|
and capitalize their text.
|
|
|
|
|
|
|
|
|
|
Pandoc's native representation of a document is an
|
|
|
|
|
abstract syntax tree (AST), not unlike the HTML DOM. It is
|
|
|
|
|
documented
|
|
|
|
|
[here](https://hackage.haskell.org/package/pandoc-types/docs/Text-Pandoc-Definition.html). A `Pandoc` document is a chunk of
|
|
|
|
|
metadata (`Meta`) and a list of `Block`s. The `Block`s, in
|
|
|
|
|
turn, are composed of other `Block`s and `Inline` elements.
|
|
|
|
|
(`Block` elements are things like paragraphs, lists, headers,
|
|
|
|
|
and code blocks. `Inline` elements are individual words,
|
|
|
|
|
links, emphasis, and so on.) Filters operate on these
|
2018-10-16 18:57:10 +02:00
|
|
|
elements. You can use `pandoc -t native` to learn about the
|
|
|
|
|
AST's structure.
|
2018-10-16 18:53:37 +02:00
|
|
|
|
|
|
|
|
There are two kinds of filters: JSON filters (which transform a
|
|
|
|
|
JSON serialization of the pandoc AST, and may be written in any
|
|
|
|
|
language that can parse and emit JSON), and Lua filters (which
|
|
|
|
|
use an interface built directly into pandoc, and must be written
|
|
|
|
|
in the Lua language). If you are writing your own filters, it
|
|
|
|
|
is best to use Lua filters, which are more portable (they
|
|
|
|
|
require only pandoc itself) and more efficient. See [Lua
|
|
|
|
|
filters](lua-filters.html) for documentation and examples. If
|
|
|
|
|
you would prefer to write your filter in another language, see
|
|
|
|
|
[Filters](filters.html) for a gentle introduction to JSON
|
|
|
|
|
filters.
|
|
|
|
|
|
|
|
|
|
There's a repository of lua filters at
|
|
|
|
|
[pandoc/lua-filters](https://github.com/pandoc/lua-filters)
|
|
|
|
|
on GitHub. A number of pandoc filters, written in
|
|
|
|
|
Haskell, are available on
|
|
|
|
|
[Hackage](https://hackage.haskell.org/packages/search?terms=pandoc+filter)
|
|
|
|
|
and can be installed using the `stack` or `cabal` tools.
|
|
|
|
|
The wiki also lists [third party
|
|
|
|
|
filters](https://github.com/jgm/pandoc/wiki/Pandoc-Filters).
|
|
|
|
|
|
|
|
|
|
### Example: capitalizing headers
|
|
|
|
|
|
|
|
|
|
TODO
|
|
|
|
|
|
|
|
|
|
### Example: code extractor
|
|
|
|
|
|
|
|
|
|
TODO
|
|
|
|
|
|
|
|
|
|
## Generic Divs and Spans
|
|
|
|
|
|
|
|
|
|
TODO
|
|
|
|
|
[Divs and Spans](/MANUAL.html#divs-and-spans): generic blocks
|
|
|
|
|
that can be transformed with filters
|
|
|
|
|
|
|
|
|
|
### Example: colored text
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
### Example: custom styles in docx
|
|
|
|
|
|
|
|
|
|
[Custom Styles in Docx](/MANUAL.html#custom-styles-in-docx)
|
|
|
|
|
|
|
|
|
|
## Raw attributes
|
|
|
|
|
|
|
|
|
|
TODO
|
|
|
|
|
[Generic raw attributes](/MANUAL.html#generic-raw-attribute):
|
|
|
|
|
to include raw snippets
|
|
|
|
|
|
|
|
|
|
## Custom writers
|
|
|
|
|
|
|
|
|
|
TODO
|
|
|
|
|
[Custom writers](/MANUAL.html#custom-writers)
|
|
|
|
|
|
|
|
|
|
## Custom syntax highlighting
|
|
|
|
|
|
|
|
|
|
TODO
|
|
|
|
|
[Custom syntax highlighting](/MANUAL.html#syntax-highlighting),
|
|
|
|
|
provided by the [skylighting
|
|
|
|
|
library](https://github.com/jgm/skylighting)
|
|
|
|
|
|
|
|
|
|
including highlighting styles
|
|
|
|
|
|
