pandocker-lua-filters

Lua filters for pandoc

Install

• installs as a python package for ease of use
  • pip install pandocker-lua-filters
• Lua filters should be installed under <sys.prefix>/share/lua/{5.3|5.4}/pandocker where <sys.prefix> can be confirmed by python -c "import sys; print(sys.prefix)". It install both 5.3 and 5.4 directories no matter of actual lua versions in system. This <sys.prefix>/share/lua/{5.3|5.4} should be added to package.path which can be confirmed by lua -e "print(package.path)".

General use

Convert AAFigure ascii art

• requires aafigure python package

aafigure.lua

Convert CSV into table

• requires csv and penlight luarocks packages
• Pandoc below 2.10 applies "simple" filters

csv2table.lua
csv2table-simple.lua

Replace title subtitle date author metadata

hide-frontpage-metadata

Text file listing

• requires penlight luarocks package

listingtable.lua

Concatenate text files

preprocess.lua

Removable note block

removable-note.lua

Convert svgbob ascii art

svgbob.lua

Convert SVG images to other formats

• requires rsvg-convert in $PATH
• pandoc docx writer >= 3.1.10 will apply native feature

svgconvert.lua

Applies table attributes to a table

• requires penlight luarocks package
• Pandoc below 2.10 applies "simple" filters

table-width.lua
table-width-simple.lua

Wavedrom / Bit-Field

• requires wavedrom-cli in $PATH (npm i -g wavedrom-cli)
• requires lyaml and lua-cjson2 luarocks packages

wavedrom.lua

LaTeX output only

Landscape pages

tex-landscape.lua

Applies underline to .underline class span

tex-underline.lua

Docx output only

Inserts a comment

docx-comment.lua

Code block numbering

• Soft wrap will collapse layout. Set up Source Code paragraph style properly.

docx-codeblock-linenumber.lua

Apply custom (paragraph) styles for each table cell

docx-apply-cell-styles.lua

Apply custom (paragraph) styles for image and its caption

docx-image-styles.lua

Apply custom (character) styles for any span

docx-custom-span-styles.lua

Apply in-place color for any span

docx-colored-span.lua

Apply custom (paragraph) styles for any unnumbered bullet lists

Finds unnumbered bullet lists down to 3rd level and applies custom paragraph styles. 4th level and lower list items are escalated to 3rd level.

docx-extract-bullet-lists.lua

Requirement for template

• Prepare Bullet List 1 to Bullet List 3 paragraph styles (by the way this is 1st level list item)
  • Otherwise these headers inherit Body style (this is 2nd level)

TOC / Pagebreak / Linebreak / Sub section TOC

docx-pagebreak-toc.lua

• Adds TOC(Table Of Contents), sub sections, a line break or a page break at any point of document

Requirement for template

TOC title is set to "Table of Contents" by default. Metadata toc-title overrides this setting.

Appendix headings

docx-appendixheadings.lua

• Makes appendix class work to appendix headings in DOCX format
• Limited to level-1 to 5 headings

Requirement for template

• Prepare Appendix Heading 1 to Appendix Heading 5 heading styles
  • Otherwise these headers inherit Body style

Unnumbered headings

docx-unnumberedheadings.lua

• Makes UnnumberHeadings class work to unnumber headings in DOCX format
• Limited to level-1 to 5 headings

Requirement for template

• Prepare Heading Unnumbered 1 to Heading Unnumbered 5 heading styles
  • Otherwise these headers inherit Body style

Tabularize figures WIP

docx-tabularize-figures.lua

• Finds figurediv class Div
• Gets col attribute
• Tabularize images in the Div into a table size of col cols
• Adds figurediv class for each images to avoid further process by docx-image-styles.lua
• Compatible with pandoc-crossref
  • This filter must be applied before pandoc-crossref

Figure styles

docx-image-styles.lua

• Processes only paragraph having single image link except figurediv class
  • Blank lines required before and after image link
• Requires Graphic Anchor and Figure Caption paragraph styles in template otherwise these styles inherit Body style
  • the filter creates two divs having custom-style attribute
  • after process the image is placed in custom-style="Graphic Anchor" div and its caption is in custom-style="Figure Caption" div respectively

Requirement for template

• Prepare Graphic Anchor and Figure Caption styles

samples

![Centered image](https://github.com/pandocker/pandoc-docx-utils-py/raw/master/qr.png){width=100mm #fig:centered}

Want a new feature?

Feature request (via issues) and PRs are welcome. Post questions in issues with [Q] in issue title.

DIY

As lua filters only requires pandoc itself, it is relatively easy to try develop a new filter. I recommend to use k4zuki/pandocker-alpine docker image like

• docker pull k4zuki/pandocker-alpine to get image
• clone this repo git clone git@github.com:pandocker/pandocker-lua-filters.git
• cd pandocker-lua-filters
• docker run --rm -it -v/$PWD:/workdir k4zuki/pandocker-alpine to start docker image
• make install to install filters in image. They are installed in /usr/local/share/lua/5.3/pandocker/
• make reinstall to reinstall so that filters will be updated
• make uninstall to uninstall filters
• make html|pdf|docx to compile test document
• edit tests/Makefile to configure options for pandoc

You don't have to reinstall for every source code updates. Instead edit tests/Makefile to run your new filter from inside repository.