About panda

Panda is a Pandoc Lua filter that works on internal Pandoc’s AST.

It provides several interesting features:

• variable expansion (minimalistic templating)
• conditional blocks
• file inclusion (e.g. for source code examples)
• script execution (e.g. to include the result of a command)
• diagrams (Graphviz, PlantUML, ditaa, Asymptote, blockdiag, mermaid…)

Panda is heavily inspired by abp reimplemented as a Pandoc Lua filter.

If you need a more generic text preprocessor, ypp may be a better choice.

Releases

It is strongly recommended to build Panda from source, as this is the only reliable way to install the exact version you need.

However, if you do require precompiled binaries, this page offers a selection for various platforms: https://cdelord.fr/pub.

Pricing

Panda is a free and open source software. But it has a cost. It takes time to develop, maintain and support.

To help Panda remain free, open source and supported, users are cordially invited to contribute financially to its development.

<a href='https://liberapay.com/LuaX/donate' target='_blank'><img height='36' style='border:0px;height:36px;' src='https://liberapay.com/assets/widgets/donate.svg' border='0' alt='Donate using Liberapay' /></a> <a href='https://ko-fi.com/K3K11CD108' target='_blank'><img height='36' style='border:0px;height:36px;' src='https://storage.ko-fi.com/cdn/kofi6.png?v=6' border='0' alt='Buy Me a Coffee at ko-fi.com' /></a>

Feel free to promote Panda!

Open source

Panda is an Open source software. Anybody can contribute on Codeberg to:

• suggest or add new features
• report or fix bugs
• improve the documentation
• add some nicer examples
• find new usages
• …

Installation

Installing Panda from sources requires Ninja, LuaX and Bang.

1. Download the sources: git clone https://codeberg.org/cdsoft/panda.
2. Run bang to generate build.ninja.
3. Run ninja test to run tests.
4. Run ninja install to install panda and panda.lua to ~/.local/bin or PREFIX=prefix ninja install to install panda and panda.lua to prefix/bin

panda and panda.lua can also be installed anywhere. Nothing else is required (except from Pandoc obviously).

Usage

panda.lua is a Pandoc Lua filter and is not meant to be called directly. panda is just a shell script that calls pandoc -L panda.lua ....

$ pandoc -L panda.lua ...

or

$ panda ...

A complete example is given as a Makefile in the doc directory.

Cheat sheet

| Syntactic item | Class | Attributes | Description | |----|----|----|----| | any string | | | {{var}} is replaced by the value of var if it is defined (variables can be environment variables or Lua variables) | | any block | comment | | commented block | | any block | | include=file | replaces the div block with the content of file (rendered according to its format) | | div block | | doc=file from=start_pattern to=end_pattern | replaces the div block with text blocks from file (rendered according to its format). Blocks are separated by the patterns from and to (@@@ is the default separator). | | div block, code block | | shift=n | adds n to header levels in an imported div block | | div block, code block | | pattern="Lua string pattern" format="output format" | applies a Lua string pattern to the content of the file. The emitted text is format. format may contain captures from pattern. | | code block | meta | | definitions for the string expansion (Lua script), defined in the code block | | any block, any inline | if | name=val | block emitted only if name’s value is val | | code block, inline code | | include=file | replaces the code block content with the content of file | | code block, inline code | | fromline=n from=n | includes a file from line number n | | code block, inline code | | toline=n to=n | includes a file up to line number n | | code block, inline code | | cmd="shell command" icmd="shell command" | replaces the code block by the result of the shell command. Withicmd the code block content is parsed by Pandoc and included in a Div block. | | code block | | render="command" | replaces the code block by a link to the image produced by the command (%i is the input file name, its content is the content of the code block, %o is the output file name) |

Commented blocks

Div blocks with the comment class are commented:

::: comment
This block is a comment and is discarded by panda.
:::

String expansion

panda stores variables in an environment used to expand strings. Variables can be defined by a Lua script with the meta class. The include attribute can also be used to point to an external file. Variables can only contain inline elements, not blocks.

The initial environment contains:

• the environment variables
• the document metadata (title, author, date)
• vars alias of PANDOC_WRITER_OPTIONS.variables to access pandoc variables given on the command line

Variable names are enclosed between double curly brackets.

E.g.:

```meta
foo = "bar (note: this is parsed as **Markdown**)"
```

foo is {{foo}}.

```{.meta include=foo.lua}
This text is ignored, definitions are in foo.lua.
```

foo is defined in `foo.lua` and is {{foo}}.

meta code blocks contain Lua code executed by the Pandoc Lua interpretor. Panda also contains the LuaX modules reimplemented in Lua. More details are available in the [Luax documentation].

Conditional blocks

Blocks can be conditionally kept or omitted. The condition is described with attributes.

:::{.if name="value"}
This block is emitted only if the value of the variable "name" is "value"
:::

Div inclusion

Fragments of documents can be imported from external files. The include attribute contains the name of the file to include. The content of the file is parsed according to its format (deduced from its name) and replaces the div block content.

:::{include=file.md shift=n}
This text is optional and will be replaced by the content of file.md.
Section title levels are shifted by n (0 if not specified).
:::

The included file can be in a different format (e.g. a markdown file can include a reStructuredText file).

If the block has an input format as a class, the file is parsed according to this format.

Block inclusion

Code examples can be imported from external files. The include attribute contains the name of the file to include. The content of the file replaces the code block content.

```{.c include=foo.c fromline=3 toline=10 pattern="Lua string pattern" format="%1"}
This text is optional and will be replaced by the content of foo.c.
```

The optional fromline and toline defines the first and last lines to be included.

The optional pattern describes the part of the text that will be rendered. The format uses the captures defined by the pattern to format the content of the block ("%1" if not defined).

If the block has an input format as a class, its result is parsed according to this format.

Documentation extraction

Documentation fragments can be extracted from other source code files. The doc attribute contains the name of the file where documentation is extracted. All the documentation blocks are extracted, concatenated and parsed. The result replaces the div block content.

:::{doc=file.h shift=n from="@@@" to="@@@"}
This text is optional and will be replaced by the content of file.h
which is delimited by @@@.
Section title levels are shifted by n (0 if not specified).
:::

Scripts

Scripts can be executed by inline or code blocks. The cmd attribute defines the command to execute. The content of the block is in a temporary file which name is added to the command. If the command contains the %s char, it is replaced by the temporary file name. If the command does not contain any %s, the file name is appended to the command. The result replaces the content of the code block.

icmd can be used instead of cmd to let Pandoc parse the result of the command and include it in the document as a Span or Div node.

An explicit file extension can be given after %s for languages that require specific file extensions (e.g. %s.fs for F#).

<table> <colgroup> <col style="width: 50%" /> <col style="width: 50%" /> </colgroup> <thead> <tr> <th>Source</th> <th>Result</th> </tr> </thead> <tbody> <tr> <td><div class="sourceCode" id="cb1"><pre class="sourceCode markdown"><code class="sourceCode markdown"><span id="cb1-1"><a href="#cb1-1" aria-hidden="true" tabindex="-1"></a><span class="in">```{.python cmd=python}</span></span> <span id="cb1-2"><a href="#cb1-2" aria-hidden="true" tabindex="-1"></a><span class="in">print(&quot;Hello from Python!&quot;)</span></span> <span id="cb1-3"><a href="#cb1-3" aria-hidden="true" tabindex="-1"></a><span class="in">```</span></span></code></pre></div></td> <td><div class="sourceCode" id="cb2"><pre class="sourceCode python"><code class="sourceCode python"><span id="cb2-1"><a href="#cb2-1" aria-hidden="true" tabindex="-1"></a>Hello <span class="im">from</span> Python<span class