Readme -- 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.

Install

Entangled filters has the following prerequisites:

• 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.

Installation is easiest using pip,

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]
pytest

The executables are auto-generated by the setup.py 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():
    <<hello>>
```

Define files

``` {.python file=hello.py}
<<main>>

if __name__ == "__main__":
    main()
```

Documentation tests

``` {.python .doctest #the-question}
6*7
---
42
```

pandoc-tangle

Extracts code blocks and writes them to files.

pandoc -t plain --filter pandoc-tangle hello.md

pandoc-annotate-codeblocks

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

pandoc -t html5 -s --filter pandoc-anotate-codeblocks hello.md

pandoc-doctest

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 hello.md

pandoc-bootstrap

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.

Docker

The Entangled pandoc filters is available as a Docker image.

Run

In your current working directory with a README.md file run

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

This will extracts code blocks and writes them to files.

Build

docker build -t nlesc/pandoc-tangle .