{"id":16576412,"url":"https://github.com/kiwi0fruit/knitty","last_synced_at":"2025-03-16T20:31:32.657Z","repository":{"id":46952157,"uuid":"117350837","full_name":"kiwi0fruit/knitty","owner":"kiwi0fruit","description":"Jupyter power in plain Python/Julia/R/any-kernel-lang. Jupyter kernels output as Pandoc filter. Atom/Hydrogen friendly Markdown literature programming. Stitch/Knotr fork.","archived":false,"fork":false,"pushed_at":"2021-09-20T18:23:57.000Z","size":2184,"stargazers_count":45,"open_issues_count":5,"forks_count":2,"subscribers_count":5,"default_branch":"master","last_synced_at":"2025-02-27T13:23:46.885Z","etag":null,"topics":["jupyter","literate-programming","markdown","pandoc","python"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/kiwi0fruit.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2018-01-13T14:38:50.000Z","updated_at":"2024-09-26T15:01:35.000Z","dependencies_parsed_at":"2022-09-14T12:31:03.494Z","dependency_job_id":null,"html_url":"https://github.com/kiwi0fruit/knitty","commit_stats":null,"previous_names":[],"tags_count":44,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kiwi0fruit%2Fknitty","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kiwi0fruit%2Fknitty/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kiwi0fruit%2Fknitty/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kiwi0fruit%2Fknitty/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kiwi0fruit","download_url":"https://codeload.github.com/kiwi0fruit/knitty/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243830912,"owners_count":20354848,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["jupyter","literate-programming","markdown","pandoc","python"],"created_at":"2024-10-11T22:08:08.902Z","updated_at":"2025-03-16T20:31:32.177Z","avatar_url":"https://github.com/kiwi0fruit.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Knitty\n\n[![Build Status](https://travis-ci.org/kiwi0fruit/knitty.svg?branch=master)](https://travis-ci.org/kiwi0fruit/knitty)\n\nKnitty is a Pandoc filter and [Atom/Hydrogen](https://atom.io/packages/hydrogen)-friendly reproducible report generation tool via Jupyter, Pandoc and Markdown (fork of the [Stitch](https://github.com/kiwi0fruit/knitty/blob/master/docs/stitch.md) that is a [Knitr](http://yihui.name/knitr/)-[RMarkdown](http://rmarkdown.rstudio.com)-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.\n\nSee [**Knitty documentation**](https://github.com/kiwi0fruit/knitty/blob/master/docs/knitty.md). [Reddit introduction post](https://github.com/kiwi0fruit/knitty/blob/master/docs/reddit.md).\n\nYou can use:\n\n* [Pandoc \u003e=2.6](https://pandoc.org/MANUAL.html#creating-jupyter-notebooks-with-pandoc) to export to .ipynb notebooks (optionally: [install Pandoc in Python](https://github.com/kiwi0fruit/py-pandoc)),\n* [ipynb-py-converter](https://github.com/kiwi0fruit/ipynb-py-converter) to convert .ipynb to .py to use with Knitty.\n\n\n## Install\n\nInstall as part of [Pandoctools](https://github.com/kiwi0fruit/pandoctools) - convenient interface and works out of the box.\n\nNeeds Python 3.6+ but you can have other versions via Jupyter kernels as Knitty can use any installed kernel.\n\nVia conda:\n```bash\nconda install -c defaults -c conda-forge knitty\n```\n\nVia pip:\n\n```bash\npip install knitty\n```\n\n\n#### Jupyter kernels\n\nSee important additional info on how to [**install Jupyter kernels in Conda environments**](https://github.com/kiwi0fruit/pandoctools/blob/master/docs/tips.md).  \nSee main info on how to install Jupyter kernels in the Atom/Hydrogen documentstion (for example).\n\n\n#### Atom/Hydrogen\n\nKnitty is much better to be used with something like Atom/Hydrogen. See [Best Python/Jupyter/PyCharm experience + report generation with Pandoc filters](https://github.com/kiwi0fruit/pandoctools/blob/master/docs/best_python_jupyter_pycharm_experience.md) for more details. You can also try **VS Code** interface to Jupyter from [vscode-python](https://github.com/Microsoft/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.\n\n\n## Examples\n\nYou can see examples of using Knitty [**here**](https://github.com/kiwi0fruit/pandoctools/tree/master/examples). It's used together with some other CLI tools via Pandoctools there but cells management and options are from Knitty.\n\nAlso see [example from Knitty documentstion](https://github.com/kiwi0fruit/knitty/blob/master/docs/knitty.md#17-example-files-in-code-cells-mode).\n\n\n## Usage\n\nYou either can use Knitty as a standard Pandoc filter:\n\n```bash\ncat doc.md | pre-knitty | pandoc --filter knitty -o doc.ipynb\n```\nand 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.\n\nOr 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](https://git-scm.com/downloads).\n\n`./metadata.yaml`:\n```yaml\n---\nkernels-map:\n  r: ir\n  py: python\nstyles-map:\n  py: python\ncomments-map:\n  py: ['#', \"r'''\", \"'''\", \"'''\", \"'''\", \"r\\\"\\\"\\\"\", \"\\\"\\\"\\\"\", \"\\\"\\\"\\\"\", \"\\\"\\\"\\\"\"]\n  js: [\"//\", \"/*\", \"*/\"]\n  ts: [\"//\", \"/*\", \"*/\"]\n  r: ['#', \"'\", \"'\", \"\\\"\", \"\\\"\"]\n...\n```\n\n`./knitty`:\n```bash\n#!/bin/bash\nhere=\"$(cd \"$(dirname \"${BASH_SOURCE[0]}\")\" \u0026\u0026 pwd)\"\nexport LANG=C.UTF-8\nexport PYTHONIOENCODING=utf-8\n\nin=\"$1\"\nyml=\"$here/metadata.yaml\"\nR=(-f markdown)\nW=(-t html --standalone --self-contained)\n\nt=\"$(pandoc-filter-arg \"${W[@]}\")\"\ncat \"$in\" |\npre-knitty \"$in\" --yaml \"$yml\" |\ncat \"$yml\" \u003c(printf \"\\n\\n\") - |\npandoc \"${R[@]}\" -t json |\nknitty $t \"$in\" \"${R[@]}\" \"${W[@]}\" |\npandoc -f json \"${W[@]}\" -o \"$in.html\"\n```\n(`$t` is an arg that Pandoc passes to it's filters).\n\nThen use it like `./knitty /path/to/doc.py` that would save `/path/to/doc.py.html`.\n\n\n#### Batch\n\nAnd if you don't like Bash there is a Windows batch example below (see [setvar](https://github.com/kiwi0fruit/knitty/blob/master/examples/setvar.bat)):\n```bat\nchcp 65001 \u003e NUL\nset PYTHONIOENCODING=utf-8\n\nset in=doc.md\nset R=-f markdown\nset W=-t html --standalone --self-contained\n\npandoc-filter-arg %W% | call .\\setvar t\ntype \"%in%\" | pre-knitty | ^\npandoc %R% -t json | ^\nknitty %t% \"%in%\" %R% %W% | ^\npandoc -f json %W% -o \"%in%.html\"\n```\n\n\n#### To ipynb\n\nBefore v0.5.0 Knitty supported conversion to .ipynb via Notedown but since v0.5.0 it is adapted to be used with Pandoc \u003e=2.6. You can learn how to convert to ipynb via Pandoc [**here**](https://pandoc.org/MANUAL.html#creating-jupyter-notebooks-with-pandoc) (optionally: [install Pandoc in Python](https://github.com/kiwi0fruit/py-pandoc)). I also recommend using `knitty.self_contained_raw_html_img` Panflute filter (see [here](https://github.com/kiwi0fruit/knitty/blob/master/docs/knitty.md#self_contained_raw_html_img-panflute-filter)) to fix Pandoc attachments created when to .ipynb conversion.\n\n\n#### Using with pandoc-crossref\n\nWorth mentioning that you can use Knitty together with [pandoc-crossref](https://github.com/lierdakil/pandoc-crossref) (see [install instructions](https://github.com/kiwi0fruit/py-pandoc-crossref)). You may also need to tune output format in Pandoc and execute the notebook. See example without Knitty:\n\n```bash\npandoc doc.md --filter pandoc-crossref --to \"ipynb-bracketed_spans-fenced_divs\\\n-link_attributes-simple_tables-multiline_tables-grid_tables-pipe_tables\\\n-fenced_code_attributes-markdown_in_html_blocks-table_captions-smart\" | \\\njupyter nbconvert --to notebook --execute --stdin --stdout \u003e doc.ipynb\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkiwi0fruit%2Fknitty","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkiwi0fruit%2Fknitty","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkiwi0fruit%2Fknitty/lists"}