notedown is a simple tool to create IPython notebooks from markdown and r-markdown.
notedown
separates your markdown into code and not code. Code
blocks (fenced or indented) go into input cells, everything else
goes into markdown cells.
Usage:
notedown input.md > output.ipynb
Installation:
pip install notedown
or the latest on github:
pip install https://github.com/aaren/notedown/tarball/master
Convert a notebook into markdown, stripping all outputs:
notedown input.ipynb --to markdown --strip > output.md
Convert a notebook into markdown, with output JSON intact:
notedown input.ipynb --to markdown > output_with_outputs.md
The outputs are placed as JSON in a code-block immediately after the
corresponding input code-block. notedown
understands this
convention as well, so it is possible to convert this
markdown-with-json back into a notebook.
This means it is possible to edit markdown, convert to notebook, play around a bit and convert back to markdown.
NB: currently, notebook and cell metadata is not preserved in the conversion.
Strip the output cells from markdown:
notedown with_output_cells.md --to markdown --strip > no_output_cells.md
You can run notebooks non-interactively from the command line using runipy:
pip install runipy
runipy your_notebook.ipynb
runipy
can be used with notedown to turn markdown into an
executed notebook:
notedown notebook.md --run > executed_notebook.ipynb
This is experimental!
Convert a notebook into markdown, rendering cell outputs as native markdown elements:
notedown input.ipynb --render
This means that e.g. png outputs become ![](data-uri)
images and
that text is placed in the document.
Of course, you can use this in conjuntion with runipy to produce markdown-with-code-and-figures from markdown-with-code:
notedown input.md --run --render > output.md
Not a notebook in sight!
The --render
flag forces the output format to markdown.
Fenced code blocks annotated with a language other than python are
read into cells using IPython's %%
cell magic.
You can disable this with --nomagic
.
--pre
lets you add arbitrary code to the start of the notebook. e.g.notedown file.md --pre '%matplotlib inline' 'import numpy as np'
You can use notedown
to convert r-markdown as well. We just need
to tell notedown
to use knitr to convert the r-markdown.
This requires that you have R installed with knitr.
Convert r-markdown into markdown:
notedown input.Rmd --to markdown --knit > output.md
Convert r-markdown into an IPython notebook:
notedown input.Rmd --knit > output.ipynb
--rmagic
will add%load_ext rmagic
at the start of the notebook, allowing you to execute code cells using the rmagic extension. notedown does the appropriate%R
cell magic automatically.
By using the --match
argument. notedown
defaults to converting
all code-blocks into code-cells. This behaviour can be changed by
giving a different argument to --match
:
-
--match=all
: convert all code blocks (the default) -
--match=fenced
: only convert fenced code blocks -
--match=language
: only convert fenced code blocks with 'language' as the syntax specifier. -
--match=strict
: only convert code blocks with Pandoc style attributes containing 'python' and 'input' as classes. i.e. code blocks must look like```{.python .input} code ```
You can get an interactive ipython session in vim by using vim-ipython, which allows you to connect to a running ipython kernel. You can send code from vim to ipython and get code completion from the running kernel. Try it!
Try using either vim-markdown or vim-pandoc. Both are clever enough to highlight code in markdown.
- support more markdowns
- allow other cell types?
- allow different language code cells (using %%lang magic)
- allow code attributes? pass to cell creator?
- code block format agnostic (fenced / indented)