@@ -0,0 +1,109 @@
1+Lua Filters
2+===========
3+
4+Pandoc expects lua files to return a list of filters. The filters in that list
5+are called sequentially, each on the result of the previous filter.
6+
7+Lua Filter Structure
8+--------------------
9+
10+Lua filters are tables with element names as keys and values consisting
11+of functions acting on those elements.
12+
13+Filter Application
14+------------------
15+
16+For each filter, the document is traversed and each element subjected to
17+the filter. Elements for which the filter contains an entry (i.e. a
18+function of the same name) are passed to lua element filtering function.
19+In other words, filter entries will be called for each corresponding
20+element in the document, getting the respective element as input.
21+
22+The element function's output must be an element of the same type as the
23+input. This means a filter function acting on an inline element must
24+return an inline, and a block element must remain a block element after
25+filter application. Pandoc will throw an error if this condition is
26+violated.
27+
28+Elements without matching functions are left untouched.
29+
30+See [module documentation](pandoc-module.html) for a list of pandoc
31+elements.
32+
33+
34+Pandoc Module
35+=============
36+
37+The `pandoc` lua module is loaded into the filter's lua environment and
38+provides a set of functions and constants to make creation and
39+manipulation of elements easier. The global variable `pandoc` is bound
40+to the module and should generally not be overwritten for this reason.
41+
42+Two major functionalities are provided by the module: element creator
43+functions and access to some of pandoc's main functionalities.
44+
45+Element creation
46+----------------
47+
48+Element creator functions like `Str`, `Para`, and `Doc` are designed to
49+allow easy creation of new elements that are simple to use and can be
50+read back from the lua environment. Internally, pandoc uses these
51+functions to create the lua objects which are passed to element filter
52+functions. This means that elements created via this module will behave
53+exactly as those elements accessible through the filter function parameter.
54+
55+Exposed pandoc functionality
56+----------------------------
57+
58+Some filters will require access to certain functions provided by
59+pandoc. This is currently limited to the `read` function which allows to
60+parse strings into pandoc documents from within the lua filter.
61+
62+
63+Examples
64+--------
65+
66+### Macro substitution.
67+
68+The following filter converts strings containing `{{helloworld}}` with
69+emphasized text.
70+
71+``` lua
72+return {
73+ {
74+ Str = function (elem)
75+ if elem.text == "{{helloworld}}" then
76+ return pandoc.Emph {pandoc.Str "Hello, World"}
77+ else
78+ return elem
79+ end
80+ end,
81+ }
82+}
83+```
84+
85+### Default metadata file
86+
87+Using the metadata from an external file as default values.
88+
89+``` lua
90+-- read metadata file into string
91+local metafile = io.open('metadata-file.yaml', 'r')
92+local content = metafile:read("*a")
93+metafile:close()
94+-- get metadata
95+local default_meta = pandoc.read(content, "markdown").meta
96+
97+return {
98+ {
99+ Meta = function(meta)
100+ -- use default metadata field if it hasn't been defined yet.
101+ for k, v in pairs(default_meta) do
102+ if meta[k] == nil then
103+ meta[k] = v
104+ end
105+ end
106+ return meta
107+ end,
108+ }
109+```