git.iko.soy/typeable/pandoc
on 2.4 help sign in
typeable/pandoc/doc/customizing-pandoc.md
157 lines 5.3 kB history raw
1---
2author:
3- Mauro Bieg
4- John MacFarlane
5title: Customizing Pandoc
6---
8This document provides a quick overview over the various ways to
9customize pandoc's output, with links to fuller documentation
10and some examples.
12## Templates
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
18preamble.
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. Variables will
25be automatically populated by the contents of like-named
26metadata fields (with proper escaping). (See
27[YAML metadata blocks](/MANUAL.html#extension-yaml_metadata_block)
28for documentation on setting metafields in pandoc markdown
29documents; the command line option
30[`--metadata`](/MANUAL.html#option--metadata) can also be
31used.) Values for variables can also be specified directly
32from the command line using `--variable` (which does no escaping).
34To look at the default template for an output format, you can do
35`pandoc -D FORMAT`, where `FORMAT` is replaced by the name of
36the format. You can also replace the defaults with your
37own custom templates, either by using the `--template` option
38or by putting the custom template in your user data directory
39(on linux and macOS, `~/.pandoc/templates/`).
41Note that in many cases you can avoid the need for a custom
42template by making use of the `--include-in-header`,
43`--include-before-body`, and `--include-after-body` options.
45For more information, see [Templates](/MANUAL.html#templates) in
46the pandoc manual.
48### Example: adding structured author data to HTML
50TODO
52### Example: generating documents from YAML metadata
54TODO <!-- Example of generating a structured document,
55say, a table, from structured YAML metadata using
56just the control structures in pandoc's template
57language. -->
59## Reference docx/pptx/odt
61For `docx`, `pptx` or `odt` documents, things are a bit more
62complicated. Instead of a single template file, you need to
63provide a customized `reference.docx/pptx/odt`.
64See the manual for the
65[`--reference-doc`](/MANUAL.html#option--reference-doc) option.
67### Example: changing the font and line spacing in a Word docx
69TODO
71## Filters
73Templates are very powerful, but they are only a sort of scaffold to
74place your document's body text in. You cannot directly change the
75body text using the template.
77If you need to affect the output of the actual body text, you
78can use a pandoc filter. A filter is a small program that
79transforms the document, between the parsing and the writing phase,
80while it is still in pandoc's native format. For example,
81a filter might find all the Header elements of a document
82and capitalize their text.
84Pandoc's native representation of a document is an
85abstract syntax tree (AST), not unlike the HTML DOM. It is
86documented
87[here](https://hackage.haskell.org/package/pandoc-types/docs/Text-Pandoc-Definition.html). A `Pandoc` document is a chunk of
88metadata (`Meta`) and a list of `Block`s. The `Block`s, in
89turn, are composed of other `Block`s and `Inline` elements.
90(`Block` elements are things like paragraphs, lists, headers,
91and code blocks. `Inline` elements are individual words,
92links, emphasis, and so on.) Filters operate on these
93elements. You can use `pandoc -t native` to learn about the
94AST's structure.
96There are two kinds of filters: JSON filters (which transform a
97JSON serialization of the pandoc AST, and may be written in any
98language that can parse and emit JSON), and Lua filters (which
99use an interface built directly into pandoc, and must be written
100in the Lua language). If you are writing your own filters, it
101is best to use Lua filters, which are more portable (they
102require only pandoc itself) and more efficient. See [Lua
103filters](lua-filters.html) for documentation and examples. If
104you would prefer to write your filter in another language, see
105[Filters](filters.html) for a gentle introduction to JSON
106filters.
108There's a repository of lua filters at
109[pandoc/lua-filters](https://github.com/pandoc/lua-filters)
110on GitHub. A number of pandoc filters, written in
111Haskell, are available on
112[Hackage](https://hackage.haskell.org/packages/search?terms=pandoc+filter)
113and can be installed using the `stack` or `cabal` tools.
114The wiki also lists [third party
115filters](https://github.com/jgm/pandoc/wiki/Pandoc-Filters).
117### Example: capitalizing headers
119TODO
121### Example: code extractor
123TODO
125## Generic Divs and Spans
127TODO
128[Divs and Spans](/MANUAL.html#divs-and-spans): generic blocks
129that can be transformed with filters
131### Example: colored text
134### Example: custom styles in docx
136[Custom Styles in Docx](/MANUAL.html#custom-styles-in-docx)
138## Raw attributes
140TODO
141[Generic raw attributes](/MANUAL.html#generic-raw-attribute):
142to include raw snippets
144## Custom writers
146TODO
147[Custom writers](/MANUAL.html#custom-writers)
149## Custom syntax highlighting
151TODO
152[Custom syntax highlighting](/MANUAL.html#syntax-highlighting),
153provided by the [skylighting
154library](https://github.com/jgm/skylighting)
156including highlighting styles