Codebraid – live code in Pandoc Markdown

Codebraid is a Python program that enables executable code in Pandoc Markdown documents. Using Codebraid can be as simple as adding a class to your code blocks' attributes, and then running codebraid rather than pandoc to convert your document from Markdown to another format. codebraid supports almost all of pandoc's options and passes them to pandoc internally. See Codebraid Preview for VS Code for editor support. See the Codebraid website for additional examples and documentation.

Codebraid provides two options for executing code. It includes a built-in code execution system that currently supports Python 3.7+, Julia, Rust, R, Bash, JavaScript, GAP and SageMath. Code can also be executed using Jupyter kernels, with support for rich output like plots.

Development: https://github.com/gpoore/codebraid

Citing Codebraid: "Codebraid: Live Code in Pandoc Markdown", Geoffrey M. Poore, Proceedings of the 18th Python in Science Conference, 2019, 54-61.

View example HTML output, or see the Markdown source or raw HTML (the Python and Rust examples demonstrate more advanced features at the end):

• Python example [Pandoc Markdown source] [raw HTML]
• Jupyter example [Pandoc Markdown source] [raw HTML]
• Rust example [Pandoc Markdown source] [raw HTML]
• Julia example [Pandoc Markdown source] [raw HTML]
• R example [Pandoc Markdown source] [raw HTML]
• Bash example [Pandoc Markdown source] [raw HTML]
• JavaScript example [Pandoc Markdown source] [raw HTML]
• GAP example [Pandoc Markdown source] [raw HTML]

Simple example

Markdown source test.md:

```{.python .cb-run}
var = 'Hello from Python!'
var += ' $2^8 = {}$'.format(2**8)
```

```{.python .cb-run}
print(var)
```

Run codebraid (to save the output, add something like -o test_out.md, and add --overwrite if it already exists):

codebraid pandoc --from markdown --to markdown test.md

Output:

Hello from Python! $2^8 = 256$

As this example illustrates, variables persist between code blocks; by default, code is executed within a single session. Code output is also cached by default so that code is only re-executed when modified.

Features

Comparison with Jupyter, knitr, and Pweave

| | Codebraid | Jupyter Notebook | knitr | Pweave | |------------------------------------------------|-----------|------------------|----------|----------| | multiple programming languages per document | ✓ | ✓* | ✓† | ✓* | | multiple independent sessions per language | ✓ | | | | | inline code execution within paragraphs | ✓ | | ✓ | ✓ | | no out-of-order code execution | ✓ | | ✓‡ | ✓ | | no markdown preprocessor or custom syntax | ✓ | ✓ | | | | minimal diffs for easy version control | ✓ | | ✓ | ✓ | | insert code output anywhere in a document | ✓ | | ✓ | | | can divide code into incomplete snippets | ✓ | | ✓ | ✓ | | support for literate programming | ✓ | | ✓ | | | compatible with any text editor | ✓ | | ✓ | ✓ |

* One primary language from the Jupyter kernel. The IPython kernel supports additional languages via %%script magics. There is no continuity between %%script cells, because each cell is executed in a separate process. Some magics, such as those provided by PyJulia and rpy2, provide more advanced capabilities. <br> † knitr only provides continuity between code chunks for R, and more recently Python and Julia. Code chunks in other languages are executed individually in separate processes. <br> ‡ Out-of-order execution is possible with R Markdown notebooks.

<hr>

The table above summarizes Codebraid features in comparison with Jupyter notebooks (without extensions), knitr (R Markdown), and Pweave, emphasizing Codebraid's unique features. Here are some additional points to consider:

Jupyter notebooks — Notebooks have a dedicated, browser-based graphical user interface. Jupyter kernels typically allow the code in a cell to be executed without re-executing any preceding code, providing superior interactivity. Codebraid has advantages for projects that are more focused on creating a document than on exploratory programming.

knitr — R Markdown documents have a dedicated user interface in R Studio. knitr provides superior support for R, as well as significant Python and Julia support that includes R integration. Codebraid offers continuity between code chunks for all supported languages, as well as multiple independent sessions per language. It also provides unique options for displaying code and its output.

More about key features

Easy debugging — By default, stderr is shown automatically in the document whenever there is an error, right next to the code that caused it. It is also possible to monitor code output in real time during execution via --live-output.

Simple language support — Codebraid supports Jupyter kernels. It also has a built-in system for executing code. Adding support for a new language with this system can take only a few minutes. Just create a config file that tells Codebraid which program to run, which file extension to use, and how to write to stdout and stderr. See languages/ for examples.

No preprocessor — Unlike many approaches to making code in Markdown executable, Codebraid is not a preprocessor. Rather, Codebraid acts on the abstract syntax tree (AST) that Pandoc generates when parsing a document. Preprocessors often fail to disable commented-out code blocks because the preprocessor doesn't recognize Markdown comments. Preprocessors can also fail due to the finer points of Markdown parsing. None of this is an issue for Codebraid, because Pandoc does the Markdown parsing.

No custom syntax — Codebraid introduces no additional Markdown syntax. Making a code block or inline code executable uses Pandoc's existing syntax for defining code attributes.

Installation and requirements

Installation: pip3 install codebraid or pip install codebraid

Manual installation: python3 setup.py install or python setup.py install

Requirements:

• Pandoc 2.4+ (2.17.1.1+ recommended for commonmark_x).

• Python 3.7+ with setuptools, and bespon 0.6 (bespon installation is typically managed by pip/setup.py)

• For Jupyter support, jupyter_client and language kernels

• For YAML metadata support, ruamel.yaml (can be ruamel_yaml for Anaconda installations)

Converting a document

Simply run codebraid pandoc <normal pandoc options>. Codebraid currently supports Pandoc Markdown (--from markdown) and CommonMark with Pandoc extensions (--from commonmark_x) as input formats.

Note that --overwrite is required to overwrite existing files. If you are using a defaults file, --from, --to, and --output must be given explicitly and cannot be