Skip to content

jacobwhall/plaited

Repository files navigation

plaited 🪢

build Coverage Status

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 PyPI:

pip install 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

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:

Similar tools that influenced this project:

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.