Skip to main content

Set of Pandoc filters to aid in literate programming

Project description

Test Badge codecov

Entangled - Pandoc filters

This contains several Pandoc filters and scripts for literate programming in Markdown. These filters are enough to get you going with literate programming using Pandoc.

Filter Function
pandoc-annotate-codeblocks Adds annotation to code blocks in the woven output.
pandoc-doctest Runs doc-tests by passing the content of code blocks through Jupyter.
pandoc-tangle Generate source files from the content of code blocks.
pandoc-bootstrap Expand some elements specifically targeting a Bootstrap page.



  • Python >=3.7: All of these filters are written in Python. This is mainly to encourage as many users (I mean YOU) to start developing Pandoc filters.
  • Dhall: the pandoc-bootstrap filter requires dhall-to-json to be installed: see Dhall language. TLDR: download dhall-json-*-[windows|macos|linux].[zip|tar.bz2] from the Dhall release page, and extract it to a location in your $PATH. Dhall is awesome, it will make your life better.
pip install entangled-filters

For development

To run tests, after doing a normal install (to get the executables installed), run

pip install --upgrade -e .[test]

The executables are auto-generated by the script and call some python -m command.

Supported syntax

See the project homepage for more info.

Named code blocks

``` {.python #hello}
print("Hello, World!")

Reference code blocks

``` {.python #main}
def main():

Define files

``` {.python}

if __name__ == "__main__":

Documentation tests

``` {.python .doctest #the-question}


Extracts code blocks and writes them to files.

pandoc -t plain --filter pandoc-tangle


Annotates code blocks in generated HTML or PDF output with name tags.

pandoc -t html5 -s --filter pandoc-anotate-codeblocks


Runs doctests, and include results into output. Also annotates the code blocks (so no need to run pandoc-annotate-codeblocks).

pandoc -t html5 -s --filter pandoc-doctest


Also annotates code blocks, and has two features:

  • Expand a Dhall specification into a card deck for Bootstrap, that is a flex-box with a single row and several columns of cards. This is nice to have at the top of a page to draw attention to some key points.

  • Collapsible/foldable code blocks. Add a .bootstrap-fold class to a code block to have the code block hidden behind a button. This is nice for some larger uninteresting code.

This filter should be used together with a Bootstrap template for Pandoc. An example of its use can be seen here: Chaotic Pendulum, with the source code at gh:jhidding/chaotic-pendulum.


The Entangled pandoc filters is available as a Docker image.


In your current working directory with a file run

docker run --rm -ti --user $UID -v $PWD:/data nlesc/pandoc-tangle

This will extracts code blocks and writes them to files.


docker build -t nlesc/pandoc-tangle .

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

entangled-filters-0.5.tar.gz (11.6 kB view hashes)

Uploaded source

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Huawei Huawei PSF Sponsor Microsoft Microsoft PSF Sponsor NVIDIA NVIDIA PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page