Skip to main content

Reproducible report generation tool via Jupyter, Pandoc and Markdown.

Project description


Build Status

Knitty is a Pandoc filter and Atom/Hydrogen-friendly reproducible report generation tool via Jupyter, Pandoc and Markdown (fork of the Stitch that is a Knitr-RMarkdown-like library in Python). Insert python code (or other Jupyter kernel code) to the Markdown document or write in plain Python/Julia/R/any-kernel-lang with block-commented Markdown and have code's results in the Pandoc output document.

See Knitty documentation. Reddit introduction post.

You can use:


Install as part of Pandoctools - convenient interface and works out of the box.

Needs Python 3.6+ but you can have other versions via Jupyter kernels as Knitty can use any installed kernel.

Via conda:

conda install -c defaults -c conda-forge knitty

Via pip:

pip install knitty

Jupyter kernels

See important additional info on how to install Jupyter kernels in Conda environments.
See main info on how to install Jupyter kernels in the Atom/Hydrogen documentstion (for example).


Knitty is much better to be used with something like Atom/Hydrogen. See Best Python/Jupyter/PyCharm experience + report generation with Pandoc filters for more details. You can also try VS Code interface to Jupyter from vscode-python instead of Atom/Hydrogen. I highly recommend to try to think about ipynb as merely an output format like pdf (albeit dynamic and rich) instead of main format or intermediate format.


You can see examples of using Knitty here. It's used together with some other CLI tools via Pandoctools there but cells management and options are from Knitty.

Also see example from Knitty documentstion.


You either can use Knitty as a standard Pandoc filter:

cat | pre-knitty | pandoc --filter knitty -o doc.ipynb

and specify some subset of Knitty options in metadata: self_contained: True, standalone: True. But this way you cannot switch from Markdown to RST for example.

Or you can set all Knitty options (including those in metadata) by using it as a Pandoc filter with multiple arguments. Knitty is intended to be used in Pandoctools bash profiles (so it's CLI is split-up) but you can easily use Knitty independently. You should only save and tweak shell script for this. There is a Bash example below. If on Windows I strongly recommend to install Git together with Bash.


  r: ir
  py: python
  py: python
  py: ['#', "r'''", "'''", "'''", "'''", "r\"\"\"", "\"\"\"", "\"\"\"", "\"\"\""]
  js: ["//", "/*", "*/"]
  ts: ["//", "/*", "*/"]
  r: ['#', "'", "'", "\"", "\""]


here="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
export LANG=C.UTF-8

R=(-f markdown)
W=(-t html --standalone --self-contained)

t="$(pandoc-filter-arg "${W[@]}")"
cat "$in" |
pre-knitty "$in" --yaml "$yml" |
cat "$yml" <(printf "\n\n") - |
pandoc "${R[@]}" -t json |
knitty $t "$in" "${R[@]}" "${W[@]}" |
pandoc -f json "${W[@]}" -o "$in.html"

($t is an arg that Pandoc passes to it's filters).

Then use it like ./knitty /path/to/ that would save /path/to/


And if you don't like Bash there is a Windows batch example below (see setvar):

chcp 65001 > NUL

set R=-f markdown
set W=-t html --standalone --self-contained

pandoc-filter-arg %W% | call .\setvar t
type "%in%" | pre-knitty | ^
pandoc %R% -t json | ^
knitty %t% "%in%" %R% %W% | ^
pandoc -f json %W% -o "%in%.html"

To ipynb

Before v0.5.0 Knitty supported conversion to .ipynb via Notedown but since v0.5.0 it is adapted to be used with Pandoc >=2.6. You can learn how to convert to ipynb via Pandoc here (optionally: install Pandoc in Python). I also recommend using knitty.self_contained_raw_html_img Panflute filter (see here) to fix Pandoc attachments created when to .ipynb conversion.

Using with pandoc-crossref

Worth mentioning that you can use Knitty together with pandoc-crossref (see install instructions). You may also need to tune output format in Pandoc and execute the notebook. See example without Knitty:

pandoc --filter pandoc-crossref --to "ipynb-bracketed_spans-fenced_divs\
-fenced_code_attributes-markdown_in_html_blocks-table_captions-smart" | \
jupyter nbconvert --to notebook --execute --stdin --stdout > doc.ipynb

Project details

Download files

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

Files for knitty, version 0.6.1
Filename, size File type Python version Upload date Hashes
Filename, size knitty-0.6.1.tar.gz (40.5 kB) File type Source Python version None Upload date Hashes View

Supported by

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