Package: notedown
Python 2/3 and IPython 4 / Jupyter compatible!Convert IPython Notebooks to markdown (and back)notedownis a simple tool to
createIPython notebooksfrom
markdown (and r-markdown).notedownseparates 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.ipynbInstallation:pip install notedownor the latest on github:pip install https://github.com/aaren/notedown/tarball/masterConversion to markdownConvert a notebook into markdown, stripping all outputs:notedown input.ipynb --to markdown --strip > output.mdConvert a notebook into markdown, with output JSON intact:notedown input.ipynb --to markdown > output_with_outputs.mdThe outputs are placed as JSON in a code-block immediately after the
corresponding input code-block.notedownunderstands 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.mdRunning an IPython Notebooknotedown notebook.md --run > executed_notebook.ipynbEditing in the browser(new!)You can configure IPython / Jupyter to seamlessly use markdown as its
storage format. Add the following to your config file:c.NotebookApp.contents_manager_class = 'notedown.NotedownContentsManager'Now you can edit your markdown files in the browser, execute code,
create plots - all stored in markdown!For Jupyter, your config file isjupyter_notebook_config.pyin~/.jupyter. For IPython your config isipython_notebook_config.pyin your ipython profile (probably~/.ipython/profile_default):R-markdownYou can usenotedownto convert r-markdown as well. We just need to
tellnotedownto useknitrto convert the
r-markdown. This requires that you have R installed withknitr.Convert r-markdown into markdown:notedown input.Rmd --to markdown --knit > output.mdConvert r-markdown into an IPython notebook:notedown input.Rmd --knit > output.ipynb--rmagicwill add%load_ext rpy2.ipythonat the start of the
notebook, allowing you to execute code cells using the rmagic
extension (requiresrpy2). notedown
does the appropriate%Rcell magic automatically.MagicFenced code blocks annotated with a language other than python are read
into cells using IPython’s%%cell
magic.You can disable this with--nomagic.--prelets you add arbitrary code to the start of the notebook.
e.g.notedown file.md--pre'%matplotlib inline' 'import numpy as np'How do I put a literal code block in my markdown?By using the--matchargument.notedowndefaults to convertingallcode-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 (or any member of the block attributes)--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
```This isn’t very interactive!Try editing the markdown in the IPython Notebook using theNotedownContentsManager(see above).You can get an interactive ipython session in vim by usingvim-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!Where’s my syntax highlighting?!Try using eithervim-markdownorvim-pandoc. Both are
clever enough to highlight code in markdown.Rendering outputs in markdownThis is experimental!Convert a notebook into markdown, rendering cell outputs as native
markdown elements:notedown input.ipynb --renderThis 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.mdNot a notebook in sight!The--renderflag forces the output format to markdown.TODO[x] Python 3 support[x] unicode support[x] IPython 3 support[x] IPython 4 (Jupyter) support[ ] Allow kernel specification