5title: Customizing Pandoc
8This document provides a quick overview over the various ways to
9customize pandoc's output, with links to fuller documentation
14When the `-s`/`--standalone` option is used, pandoc will
15generate a standalone document rather than a fragment.
16For example, in HTML output this will include the
17`<head>` element; in LaTeX output, it will include the
20Pandoc comes with a default template for (almost) every output
21format. A template is a plain text file containing variables
22that are replaced by text generated by pandoc. For example,
23the variable `$body$` will be replaced by the document body,
24and `$title$` by the title from metadata.
26To look at the default template for an output format, you can do
27`pandoc -D FORMAT`, where `FORMAT` is replaced by the name of
28the format. For example `pandoc -D latex`. You can also use your
29own template instead, either by using the `--template` option
30or by putting the custom template in your user data directory
31(on Linux and macOS, `~/.pandoc/templates/`).
33Note that in many cases you can avoid the need for a custom
34template by including a file with the `--include-in-header`,
35`--include-before-body`, or `--include-after-body` option.
36Or you can set the corresponding template variable directly.
40There are several ways to set template variables:
42| | [`--variable`] | [`--metadata`] | [YAML metadata] and [`--metadata-file`] |
43|:---------------|:------------------|:------------------|:----------------------------|
44| values can be… | strings and bools | strings and bools | also YAML objects and lists |
45| strings are… | inserted verbatim | escaped | interpreted as markdown |
46| accessible by filters: | no | yes | yes |
49[`--variable`]: https://pandoc.org/MANUAL.html#option--variable
50[`--metadata`]: https://pandoc.org/MANUAL.html#option--metadata
51[YAML metadata]: https://pandoc.org/MANUAL.html#extension-yaml_metadata_block
52[`--metadata-file`]: https://pandoc.org/MANUAL.html#option--metadata-file
56For more information, see [Templates](https://pandoc.org/MANUAL.html#templates) in
59### Example: adding structured author data to HTML
63### Example: generating documents from YAML metadata
65TODO <!-- Example of generating a structured document,
66say, a table, from structured YAML metadata using
67just the control structures in pandoc's template
70## Reference docx/pptx/odt
72For `docx`, `pptx` or `odt` documents, things are a bit more
73complicated. Instead of a single template file, you need to
74provide a customized `reference.docx/pptx/odt`.
76[`--reference-doc`](https://pandoc.org/MANUAL.html#option--reference-doc) option.
78### Example: changing the font and line spacing in a Word docx
84Templates are very powerful, but they are only a sort of scaffold to
85place your document's body text in. You cannot directly change the
86body text using the template.
88If you need to affect the output of the actual body text, you
89can use a pandoc filter. A filter is a small program that
90transforms the document, between the parsing and the writing phase,
91while it is still in pandoc's native format. For example,
92a filter might find all the Header elements of a document
93and capitalize their text.
95Pandoc's native representation of a document is an
96abstract syntax tree (AST), not unlike the HTML DOM. It is
98[here](https://hackage.haskell.org/package/pandoc-types/docs/Text-Pandoc-Definition.html). A `Pandoc` document is a chunk of
99metadata (`Meta`) and a list of `Block`s. The `Block`s, in
100turn, are composed of other `Block`s and `Inline` elements.
101(`Block` elements are things like paragraphs, lists, headers,
102and code blocks. `Inline` elements are individual words,
103links, emphasis, and so on.) Filters operate on these
104elements. You can use `pandoc -t native` to learn about the
107There are two kinds of filters: JSON filters (which transform a
108JSON serialization of the pandoc AST, and may be written in any
109language that can parse and emit JSON), and Lua filters (which
110use an interface built directly into pandoc, and must be written
111in the Lua language). If you are writing your own filters, it
112is best to use Lua filters, which are more portable (they
113require only pandoc itself) and more efficient. See [Lua
114filters](https://pandoc.org/lua-filters.html) for documentation and examples. If
115you would prefer to write your filter in another language, see
116[Filters](https://pandoc.org/filters.html) for a gentle introduction to JSON
119There's a repository of lua filters at
120[pandoc/lua-filters](https://github.com/pandoc/lua-filters)
121on GitHub. A number of pandoc filters, written in
122Haskell, are available on
123[Hackage](https://hackage.haskell.org/packages/search?terms=pandoc+filter)
124and can be installed using the `stack` or `cabal` tools.
125The wiki also lists [third party
126filters](https://github.com/jgm/pandoc/wiki/Pandoc-Filters).
128### Example: capitalizing headers
132### Example: code extractor
136## Generic Divs and Spans
139[Divs and Spans](https://pandoc.org/MANUAL.html#divs-and-spans): generic blocks
140that can be transformed with filters
142### Example: colored text
145### Example: custom styles in docx
147[Custom Styles in Docx](https://pandoc.org/MANUAL.html#custom-styles-in-docx)
152[Generic raw attributes](https://pandoc.org/MANUAL.html#generic-raw-attribute):
153to include raw snippets
158[Custom writers](https://pandoc.org/MANUAL.html#custom-writers)
160## Custom syntax highlighting
163[Custom syntax highlighting](https://pandoc.org/MANUAL.html#syntax-highlighting),
164provided by the [skylighting
165library](https://github.com/jgm/skylighting)
167including highlighting styles
keysesc to close
- j k
- move down, up
- enter
- open
- esc
- back, or up a level
- 1 2 3 4
- readme, files, commits, refs
- /
- filter
- y
- copy the clone command
- c
- compare the chosen commit with another (or shift-click both)
- ?
- show or hide this list