diff options
Diffstat (limited to 'doc/customizing-pandoc.md')
| -rw-r--r-- | doc/customizing-pandoc.md | 157 |
1 files changed, 157 insertions, 0 deletions
diff --git a/doc/customizing-pandoc.md b/doc/customizing-pandoc.md new file mode 100644 index 000000000..0fdfc8115 --- /dev/null +++ b/doc/customizing-pandoc.md @@ -0,0 +1,157 @@ +--- +author: +- Mauro Bieg +- John MacFarlane +title: Customizing Pandoc +--- + +This document provides a quick overview over the various ways to +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, +and `$title$` by the title from metadata. Variables will +be automatically populated by the contents of like-named +metadata fields (with proper escaping). (See +[YAML metadata blocks](/MANUAL.html#extension-yaml_metadata_block) +for documentation on setting metafields in pandoc markdown +documents; the command line option +[`--metadata`](/MANUAL.html#option--metadata) can also be +used.) Values for variables can also be specified directly +from the command line using `--variable` (which does no escaping). + +To look at the default template for an output format, you can do +`pandoc -D FORMAT`, where `FORMAT` is replaced by the name of +the format. You can also replace the defaults with your +own custom templates, either by using the `--template` option +or by putting the custom template in your user data directory +(on linux and macOS, `~/.pandoc/templates/`). + +Note that in many cases you can avoid the need for a custom +template by making use of the `--include-in-header`, +`--include-before-body`, and `--include-after-body` options. + +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 +elements. You can use `pandoc -t native` to learn about the +AST's structure. + +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 + |