@@ -1,64 +1,152 @@
1+---
2+author:
3+- Mauro Bieg
4+- John MacFarlane
5+title: Customizing Pandoc
6+---
7+
18This document provides a quick overview over the various ways to
2−customize pandoc's output. Follow the links to learn how to use each
3−approach.
4−
5−[Templates](/MANUAL.html#templates)
6−
7−: Pandoc comes with a template for (almost) every output format. A
8− template is a plain text file, that contains for example the line
9− `$body$`. That variable is replaced by the document's body text on
10− output.
11−
12− There are many other variables, like `title`, `header-includes`,
13− etc. that are either set automatically, or that you can set using
14− [YAML metadata blocks](/MANUAL.html#extension-yaml_metadata_block),
15− [`--metadata`](/MANUAL.html#option--metadata) (which properly escape
16− things), or `--variable` (which does no escaping). You can also
17− generate your own template (e.g. `pandoc -D html > myletter.html`)
18− and customize that file, for example by introducing new variables.
19−
20−[reference.docx/pptx/odt](/MANUAL.html#option--reference-doc)
21−
22−: To output a `docx`, `pptx` or `odt` document, which is a ZIP of
23− several files, things are a bit more complicated. Instead of a
24− single template file, you need to provide a customized
25− `reference.docx/pptx/odt`.
26−
27−[Lua filters](lua-filters.html) and [filters](filters.html)
28−
29−: Templates are very powerful, but they are only a sort of scaffold to
30− place your document's body text in. You cannot directly change the
31− body text using the template (beyond e.g. adding CSS for HTML
32− output, or `\renewcommand` for LaTeX output).
33−
34− If you need to affect the output of the actual body text, you
35− probably need a pandoc filter. A filter is a small program, that
36− transforms the document, between the parsing and the writing phase,
37− while it is still in pandoc's native format -- an abstract syntax
38− tree (AST), not unlike the HTML DOM. As can be seen in the [AST
39− definition](https://hackage.haskell.org/package/pandoc-types/docs/Text-Pandoc-Definition.html)
40− `Pandoc Meta [Block]`, a pandoc document is a chunk of metadata and
41− a list of `Block`s.
42−
43− - There's a [list of third party filters on the
44− wiki](https://github.com/jgm/pandoc/wiki/Pandoc-Filters).
45− - Unless you have a good reason not to, it's best to write your
46− own filter in the Lua scripting language. Since pandoc ships
47− with a Lua interpreter, Lua filters are very portable and
48− efficient. See [Lua filters](lua-filters.html).
49− - For a gentle introduction into filters and writing them in any
50− programming language, see [filters](filters.html).
51−
52−Furthecustomizations
53−
54−: - [Custom Styles in Docx](/MANUAL.html#custom-styles-in-docx)
55− - If you're converting from Markdown, see
56− - [Generic raw attributes](/MANUAL.html#generic-raw-attribute):
57− to include raw snippets
58− - [Divs and Spans](/MANUAL.html#divs-and-spans): generic blocks
59− that can be transformed with filters
60− - [Custom syntax highlighting](/MANUAL.html#syntax-highlighting),
61− provided by the [skylighting
62− library](https://github.com/jgm/skylighting)
63− - [Custom writers](/MANUAL.html#custom-writers)
64− - [Pandoc Extras wiki page](https://github.com/jgm/pandoc/wiki/Pandoc-Extras)
9+customize pandoc's output, with links to fuller documentation
10+and some examples.
11+
12+## Templates
13+
14+When the `-s`/`--standalone` option is used, pandoc will
15+generate a standalone document rather than a fragment.
16+For example, in HTML output this will include the
17+`<head>` element; in LaTeX output, it will include the
18+preamble.
19+
20+Pandoc comes with a default template for (almost) every output
21+format. A template is a plain text file containing variables
22+that are replaced by text generated by pandoc. For example,
23+the variable `$body$` will be replaced by the document body,
24+and `$title$` by the title from metadata. Variables will
25+be automatically populated by the contents of like-named
26+metadata fields (with proper escaping). (See
27+[YAML metadata blocks](/MANUAL.html#extension-yaml_metadata_block)
28+for documentation on setting metafields in pandoc markdown
29+documents; the command line option
30+[`--metadata`](/MANUAL.html#option--metadata) can also be
31+used.) Values for variables can also be specified directly
32+from the command line using `--variable` (which does no escaping).
33+
34+To look at the default template for an output format, you can do
35+`pandoc -D FORMAT`, where `FORMAT` is replaced by the name of
36+the format. You can also replace the defaults with your
37+own custom templates, either by using the `--template` option
38+or by putting the custom template in your user data directory
39+(on linux and macOS, `~/.pandoc/templates/`).
40+
41+For more information, see [Templates](/MANUAL.html#templates) in
42+the pandoc manual.
43+
44+### Example: adding structured author data to HTML
45+
46+TODO
47+
48+### Example: generating documents from YAML metadata
49+
50+TODO <!-- Example of generating a structured document,
51+say, a table, from structured YAML metadata using
52+just the control structures in pandoc's template
53+language. -->
54+
55+## Reference docx/pptx/odt
56+
57+For `docx`, `pptx` or `odt` documents, things are a bit more
58+complicated. Instead of a single template file, you need to
59+provide a customized `reference.docx/pptx/odt`.
60+See the manual for the
61+[`--reference-doc`](/MANUAL.html#option--reference-doc) option.
62+
63+### Example: changing the font and line spacing in a Word docx
64+
65+TODO
66+
67+## Filters
68+
69+Templates are very powerful, but they are only a sort of scaffold to
70+place your document's body text in. You cannot directly change the
71+body text using the template.
72+
73+If you need to affect the output of the actual body text, you
74+can use a pandoc filter. A filter is a small program that
75+transforms the document, between the parsing and the writing phase,
76+while it is still in pandoc's native format. For example,
77+a filter might find all the Header elements of a document
78+and capitalize their text.
79+
80+Pandoc's native representation of a document is an
81+abstract syntax tree (AST), not unlike the HTML DOM. It is
82+documented
83+[here](https://hackage.haskell.org/package/pandoc-types/docs/Text-Pandoc-Definition.html). A `Pandoc` document is a chunk of
84+metadata (`Meta`) and a list of `Block`s. The `Block`s, in
85+turn, are composed of other `Block`s and `Inline` elements.
86+(`Block` elements are things like paragraphs, lists, headers,
87+and code blocks. `Inline` elements are individual words,
88+links, emphasis, and so on.) Filters operate on these
89+elements.
90+
91+There are two kinds of filters: JSON filters (which transform a
92+JSON serialization of the pandoc AST, and may be written in any
93+language that can parse and emit JSON), and Lua filters (which
94+use an interface built directly into pandoc, and must be written
95+in the Lua language). If you are writing your own filters, it
96+is best to use Lua filters, which are more portable (they
97+require only pandoc itself) and more efficient. See [Lua
98+filters](lua-filters.html) for documentation and examples. If
99+you would prefer to write your filter in another language, see
100+[Filters](filters.html) for a gentle introduction to JSON
101+filters.
102+
103+There's a repository of lua filters at
104+[pandoc/lua-filters](https://github.com/pandoc/lua-filters)
105+on GitHub. A number of pandoc filters, written in
106+Haskell, are available on
107+[Hackage](https://hackage.haskell.org/packages/search?terms=pandoc+filter)
108+and can be installed using the `stack` or `cabal` tools.
109+The wiki also lists [third party
110+filters](https://github.com/jgm/pandoc/wiki/Pandoc-Filters).
111+
112+### Example: capitalizing headers
113+
114+TODO
115+
116+### Example: code extractor
117+
118+TODO
119+
120+## Generic Divs and Spans
121+
122+TODO
123+[Divs and Spans](/MANUAL.html#divs-and-spans): generic blocks
124+that can be transformed with filters
125+
126+### Example: colored text
127+
128+
129+### Example: custom styles in docx
130+
131+[Custom Styles in Docx](/MANUAL.html#custom-styles-in-docx)
132+
133+## Raw attributes
134+
135+TODO
136+[Generic raw attributes](/MANUAL.html#generic-raw-attribute):
137+to include raw snippets
138+
139+## Custom writers
140+
141+TODO
142+[Custom writers](/MANUAL.html#custom-writers)
143+
144+## Custom syntax highlighting
145+
146+TODO
147+[Custom syntax highlighting](/MANUAL.html#syntax-highlighting),
148+provided by the [skylighting
149+library](https://github.com/jgm/skylighting)
150+
151+including highlighting styles
152+