This library is meant to help creating filters for pandoc which is tool to convert between textual formats, notably markdown and LaTeX. It is vaguely inspired of the corresponding Haskell library.
The documentation for the library is available online.
Basically, a pandoc filter will
- read JSON data from the standard input with
Yojson.Basic.from_channel
, - convert it to the library's standard representation with
Pandoc.of_json
, - transform it using the
Pandoc.map
function which recursively maps functions on various elements, - convert the result to JSON with
Pandoc.of_json
, - print the result on the standard output using
Yojson.Basic.to_string
.
Once you have build your filter (say, myfilter
) you can use it to transform
pandoc documents while they are being processed by using the --filter
commandline argument. For instance:
pandoc --filter=myfilter file.md -o file.pdf
Some examples are provided in the examples directory for you convenience (or because I needed those).
-
pandoc-abbreviations
: adds non-breakable spaces after abbreviations (listed inabbreviations
file). Pandoc already does this natively, but it does not play well with other plugins. -
pandoc-crossref
: handles cross-references in LaTeX. It replaces references of the form#chap:bla
and#sec:bli
to\cref{chap:bla}
and\cref{sec:bli}
respectively. -
pandoc-include
: includes other documents. It replaces!include "file"
by the contents of the file
file
, it replaces```{.ocaml include="test.ml" from=2 to=5} ```
by the contents of the file
test.ml
between lines 2 and 5, it replaces```{.ocaml include="test.ml" from=2 to=-1} ```
by the content from line 2 to last but one line, it replaces
```{.ocaml include="test.ml" from="BEGIN" to="TO"} ```
by the content between lines containing "BEGIN" and "END", excluded. Useful for including small code snippets delimited by comments such as
(* BEGIN *)
and(* END *)
. -
pandoc-inspect
: acts as the identity plugin, but prints the JSON output given by pandoc on the standard error. Useful for debugging and adding missing features to the library. -
pandoc-pdf2png
: changes the extension of images from.pdf
to.png
. Useful if you want to compile both to pdf and html. -
pandoc-replace
: replaces words by others. Useful for fixing capitalization for instance.
The code is simple and stable enough for me but some features are missing. Feel free to fill bug reports or submit pull requests.