path: root/doc
diff options
authorAlbert Krewinkel <>2017-09-17 10:34:24 +0200
committerJohn MacFarlane <>2017-09-24 12:04:15 -0700
commit2d416e203e6dd3d11ed69f2f65d594c30329b125 (patch)
treeb439a9df1a78cbbe7d6bf4ff9e5f9b35cf231a82 /doc
parent71f69cd0868f0eecf43ddb606be3074f83a8295c (diff)
Document possible return values of lua filter functions
This is mostly copy'n'pasted from the pandocfilters documentation.
Diffstat (limited to 'doc')
1 files changed, 16 insertions, 5 deletions
diff --git a/doc/ b/doc/
index 9e4d438ea..5e43afb26 100644
--- a/doc/
+++ b/doc/
@@ -105,11 +105,22 @@ element filtering function. In other words, filter entries will
be called for each corresponding element in the document,
getting the respective element as input.
-The element function's output must be an element of the same
-type as the input. This means a filter function acting on an
-inline element must return an inline, and a block element must
-remain a block element after filter application. Pandoc will
-throw an error if this condition is violated.
+The return of a filter function must one of the following:
+- nil: this means that the object should remain unchanged.
+- a pandoc object: this must be of the same type as the input
+ and will replace the original object.
+- a list of pandoc objects: these will replace the original
+ object; the list is merged with the neighbors of the orignal
+ objects (spliced into the list the original object belongs
+ to); returning an empty list deletes the object.
+The function's output must result in an element of the same type
+as the input. This means a filter function acting on an inline
+element must return either nil, an inline, or a list of inlines,
+and a function filtering a block element must return one of nil,
+a block, or a list of block elements. Pandoc will throw an error
+if this condition is violated.
If there is no function matching the element's node type, then
the filtering system will look for a more general fallback