1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
|
Lua Filters
===========
Pandoc expects lua files to return a list of filters. The filters in that list
are called sequentially, each on the result of the previous filter. If there is
no value returned by the filter script, then pandoc will try to generate a
filter by collecting all top-level functions whose names correspond to those of
pandoc elements (e.g., `Str`, `Para`, `Meta`, or `Pandoc`).
Filters are expected to be put into separate files and are passed via the
`--lua-filter` command-line argument. E.g., if a filter is defined in a file
`current-date.lua`, then it would be applied like this:
pandoc --lua-filter=current-date.lua -f markdown MANUAL.txt
The `--lua-filter` can be supplied multiple times, causing the filters to be
applied sequentially in the order they were given. If other, non-Lua filters are
given as well (via `--filter`), then those are executed *after* all Lua filters
have been applied.
Lua Filter Structure
--------------------
Lua filters are tables with element names as keys and values consisting
of functions acting on those elements.
Filter Application
------------------
For each filter, the document is traversed and each element subjected to
the filter. Elements for which the filter contains an entry (i.e. a
function of the same name) are passed to lua 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.
Elements without matching functions are left untouched.
See [module documentation](pandoc-module.html) for a list of pandoc
elements.
Pandoc Module
=============
The `pandoc` lua module is loaded into the filter's lua environment and
provides a set of functions and constants to make creation and
manipulation of elements easier. The global variable `pandoc` is bound
to the module and should generally not be overwritten for this reason.
Two major functionalities are provided by the module: element creator
functions and access to some of pandoc's main functionalities.
Element creation
----------------
Element creator functions like `Str`, `Para`, and `Pandoc` are designed to
allow easy creation of new elements that are simple to use and can be
read back from the lua environment. Internally, pandoc uses these
functions to create the lua objects which are passed to element filter
functions. This means that elements created via this module will behave
exactly as those elements accessible through the filter function parameter.
Exposed pandoc functionality
----------------------------
Some filters will require access to certain functions provided by
pandoc. This is currently limited to the `read` function which allows to
parse strings into pandoc documents from within the lua filter.
Examples
--------
### Macro substitution.
The following filter converts strings containing `{{helloworld}}` with
emphasized text.
``` lua
return {
{
Str = function (elem)
if elem.text == "{{helloworld}}" then
return pandoc.Emph {pandoc.Str "Hello, World"}
else
return elem
end
end,
}
}
```
### Default metadata file
Using the metadata from an external file as default values.
``` lua
-- read metadata file into string
local metafile = io.open('metadata-file.yaml', 'r')
local content = metafile:read("*a")
metafile:close()
-- get metadata
local default_meta = pandoc.read(content, "markdown").meta
return {
{
Meta = function(meta)
-- use default metadata field if it hasn't been defined yet.
for k, v in pairs(default_meta) do
if meta[k] == nil then
meta[k] = v
end
end
return meta
end,
}
```
### Setting the date in the metadata
```lua
function Meta(m)
m.date = os.date("%B %e, %Y")
return m
end
```
### Extracting information about links
This filter prints a table of all the URLs linked to
in the document, together with the number of links to
that URL.
```lua
links = {}
function Link (el)
if links[el.target] then
links[el.target] = links[el.target] + 1
else
links[el.target] = 1
end
return el
end
function Doc (blocks, meta)
function strCell(str)
return {pandoc.Plain{pandoc.Str(str)}}
end
local caption = {pandoc.Str "Link", pandoc.Space(), pandoc.Str "count"}
local aligns = {pandoc.AlignDefault, pandoc.AlignLeft}
local widths = {0.8, 0.2}
local headers = {strCell "Target", strCell "Count"}
local rows = {}
for link, count in pairs(links) do
rows[#rows + 1] = {strCell(link), strCell(count)}
end
return pandoc.Doc(
{pandoc.Table(caption, aligns, widths, headers, rows)},
meta
)
end
```
### Replacing placeholders with their metadata value
Lua filter functions are run in the order *Inlines → Blocks → Meta → Pandoc*.
Passing information from a higher level (e.g., metadata) to a lower level (e.g.,
inlines) is still possible by using two filters living in the same file:
``` lua
local vars = {}
function get_vars (meta)
for k, v in pairs(meta) do
if v.t == 'MetaInlines' then
vars["$" .. k .. "$"] = v
end
end
end
function replace (el)
if vars[el.text] then
return pandoc.Span(vars[el.text])
else
return el
end
end
return {{Meta = get_vars}, {Str = replace}}
```
If the contents of file `occupations.md` is
``` markdown
---
name: John MacFarlane
occupation: Professor of Philosophy
---
Name
: \$name\$
Occupation
: \$occupation\$
```
then running `pandoc --lua-filter=meta-vars.lua occupations.md` will output:
``` html
<dl>
<dt>Name</dt>
<dd><p><span>John MacFarlane</span></p>
</dd>
<dt>Occupation</dt>
<dd><p><span>Professor of Philosophy</span></p>
</dd>
</dl>
```
|
