Skip to main content

Convert markdown to IPython notebook.

Project description

Please note: IPython 3 has been released but I haven’t got round to supporting it yet. Therefore notedown requires IPython < 3.

If this is important to you then encourage me to fix it on the `issue <https://github.com/aaren/notedown/issues/13>`__ or help me out on the `pull request <https://github.com/aaren/notedown/issues/14>`__.

Convert IPython Notebooks to markdown (and back)

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

Conversion to markdown

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

Running an IPython Notebook

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

R-markdown

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.

Magic

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'

How do I put a literal code block in my markdown?

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
    ```

This isn’t very interactive!

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!

Where’s my syntax highlighting?!

Try using either vim-markdown or vim-pandoc. Both are clever enough to highlight code in markdown.

Rendering outputs in markdown

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.

TODO

  • [x] support more markdowns

  • [ ] allow other cell types?

  • [x] allow different language code cells (using %%lang magic)

  • [x] allow code attributes? pass to cell creator?

  • [x] code block format agnostic (fenced / indented)

Project details


Download files

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

Source Distribution

notedown-1.2.9.tar.gz (14.5 kB view hashes)

Uploaded Source

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page