plaited 🪢

plaited is a Pandoc filter that uses Jupyter kernels to generate code notebooks. It's a flexible tool for publishing documents that include code execution in a variety of languages and formats. It is a fork of Knitty, which is a fork of Stitch, which used code from knitpy and nbconvert.

Installation

plaited is available on TestPyPI:

pip install -i https://test.pypi.org/simple/ plaited

I will publish it to PyPI once it is more mature.

Getting Started

plaited is plug-and-play with Pandoc:

pandoc --filter plaited -o out.html input.md

Motivation

Why another code notebook generator?

Ultimately, plaited is a personal project that I work on for my own benefit. After reading about Codebraid, Stitch, and Knitty, I wanted a similar tool that meets the following criteria:

Pandoc filter

• embrace Pandoc AST, allowing other filters, templates, or Pandoc itself to make any formatting decisions
• use Panflute to manage document elements

Jupyter client

• embrace Jupyter kernels as the means of code execution
• use Jupyter Client to interface with the kernels

modern Python package

• aim to write hackable, maintainable code
• use modern setuptools configuration

Contributing

You are more than welcome to submit a pull request to this repository, or open an issue, or send me an email…I'd love to hear from you!

Thanks

plaited builds upon the work of hundreds of people! Here are a handful of them:

• John MacFarlane and other contributors to Pandoc
• Sergio Correia and other contributors to Panflute
• Tom Augspurger, who wrote Stitch
• Peter Zagubisalo, who created Knitty
• Jan Katins, who wrote knitpy

Similar tools that influenced this project:

• Knitr by Yihui Xie
• Codebraid by Geoffrey M. Poore
• pandoc-plot by Laurent P. René de Cotret
• Jupyter Book

License

There seems to have been a misunderstanding by previous developers of this project regarding license compatibility. Stitch and Knitty, by Tom Augspurger and Peter Zagubisalo respectively, were released using the MIT License. Their code is adapted from the knitpy and IPython projects, both released under BSD licenses. I am not a lawyer, but I do not believe that BSD licenses are compatible with the MIT license. I hope that by relicensing this project under the Modified (3-Clause) BSD License, work by all prior contributors is being used according to their original licenses. This is not legal advice, and I welcome any feedback regarding the licensure of this repository.