aboutsummaryrefslogtreecommitdiff
path: root/doc
diff options
context:
space:
mode:
Diffstat (limited to 'doc')
-rw-r--r--doc/filters.md79
1 files changed, 79 insertions, 0 deletions
diff --git a/doc/filters.md b/doc/filters.md
index e398fc468..8b6002467 100644
--- a/doc/filters.md
+++ b/doc/filters.md
@@ -425,3 +425,82 @@ the Japanese characters (e.g. "Noto Sans CJK TC"), and add
5. Find all code blocks with class `python` and run them
using the python interpreter, printing the results to the console.
+# Technical details of JSON filters
+
+A JSON filter is any program which can consume and produce a
+valid pandoc JSON document representation. This section describes
+the technical details surrounding the invocation of filters.
+
+## Arguments
+
+The program will always be called with the target format as the
+only argument. A pandoc invocation like
+
+ pandoc --filter demo --to=html
+
+will cause pandoc to call the program `demo` with argument `html`.
+
+## Environment variables
+
+Pandoc sets additional environment variables before calling a
+filter.
+
+`PANDOC_VERSION`
+: The version of the pandoc binary used to process the document.
+ Example: `2.11.1`.
+
+`PANDOC_READER_OPTIONS`
+: JSON object representation of the options passed to the input
+ parser.
+
+ Object fields:
+
+ `readerAbbreviations`
+ : set of known abbreviations (array of strings).
+
+ `readerColumns`
+ : number of columns in terminal; an integer.
+
+ `readerDefaultImageExtension`
+ : default extension for images; a string.
+
+ `readerExtensions`
+ : integer representation of the syntax extensions bit
+ field.
+
+ `readerIndentedCodeClasses`
+ : default classes for indented code blocks; array of
+ strings.
+
+ `readerStandalone`
+ : whether the input was a standalone document with header;
+ either `true` or `false`.
+
+ `readerStripComments`
+ : HTML comments are stripped instead of parsed as raw HTML;
+ either `true` or `false`.
+
+ `readerTabStop`
+ : width (i.e. equivalent number of spaces) of tab stops;
+ integer.
+
+ `readerTrackChanges`
+ : track changes setting for docx; one of
+ `"accept-changes"`, `"reject-changes"`, and
+ `"all-changes"`.
+
+## Supported interpreters
+
+Files passed to the `--filter`/`-F` parameter are expected to be
+executable. However, if the executable bit is not set, then
+pandoc tries to guess a suitable interpreter from the file
+extension.
+
+ file extension interpreter
+ ---------------- --------------
+ .py `python`
+ .hs `runhaskell`
+ .pl `ruby`
+ .php `php`
+ .js `node`
+ .r `Rscript`