*Python 2/3 and IPython 4 / Jupyter compatible!*
Convert IPython Notebooks to markdown (and back)
------------------------------------------------
`notedown <http://github.com/aaren/notedown>`__ is a simple tool to
create `IPython notebooks <http://www.ipython.org/notebook>`__ 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
~~~~~~~~~~~~~~~~~~~~~~~~~~~
::
notedown notebook.md --run > executed_notebook.ipynb
Editing 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 is ``jupyter_notebook_config.py`` in
``~/.jupyter``. For IPython your config is
``ipython_notebook_config.py`` in your ipython profile (probably
``~/.ipython/profile_default``):
R-markdown
~~~~~~~~~~
You can use ``notedown`` to convert r-markdown as well. We just need to
tell ``notedown`` to use `knitr <yihui.name/knitr>`__ to convert the
r-markdown. This requires that you have R installed with
`knitr <yihui.name/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 rpy2.ipython`` at the start of the
notebook, allowing you to execute code cells using the rmagic
extension (requires `rpy2 <http://rpy.sourceforge.net/>`__). 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 <http://nbviewer.ipython.org/github/ipython/ipython/blob/1.x/examples/notebooks/Cell%20Magics.ipynb>`__.
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 (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 the
``NotedownContentsManager`` (see above).
You can get an interactive ipython session in vim by using
`vim-ipython <http://www.github.com/ivanov/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 <https://github.com/tpope/vim-markdown>`__ or
`vim-pandoc <https://github.com/vim-pandoc/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 ```` 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] Python 3 support
- [x] unicode support
- [x] IPython 3 support
- [x] IPython 4 (Jupyter) support
- [ ] Allow kernel specification
Raw data
{
"_id": null,
"home_page": "http://github.com/aaren/notedown",
"name": "notedown",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "",
"author": "Aaron O'Leary",
"author_email": "dev@aaren.me",
"download_url": "https://files.pythonhosted.org/packages/58/1b/a926945216cb7d1d21abdbc975195bd7beb3bceafa41c186ecb95f8f9121/notedown-1.5.1.tar.gz",
"platform": "",
"description": "*Python 2/3 and IPython 4 / Jupyter compatible!*\n\nConvert IPython Notebooks to markdown (and back)\n------------------------------------------------\n\n`notedown <http://github.com/aaren/notedown>`__ is a simple tool to\ncreate `IPython notebooks <http://www.ipython.org/notebook>`__ from\nmarkdown (and r-markdown).\n\n``notedown`` separates your markdown into code and not code. Code blocks\n(fenced or indented) go into input cells, everything else goes into\nmarkdown cells.\n\nUsage:\n\n::\n\n notedown input.md > output.ipynb\n\nInstallation:\n\n::\n\n pip install notedown\n\nor the latest on github:\n\n::\n\n pip install https://github.com/aaren/notedown/tarball/master\n\nConversion to markdown\n~~~~~~~~~~~~~~~~~~~~~~\n\nConvert a notebook into markdown, stripping all outputs:\n\n::\n\n notedown input.ipynb --to markdown --strip > output.md\n\nConvert a notebook into markdown, with output JSON intact:\n\n::\n\n notedown input.ipynb --to markdown > output_with_outputs.md\n\nThe outputs are placed as JSON in a code-block immediately after the\ncorresponding input code-block. ``notedown`` understands this convention\nas well, so it is possible to convert this markdown-with-json back into\na notebook.\n\nThis means it is possible to edit markdown, convert to notebook, play\naround a bit and convert back to markdown.\n\nNB: currently, notebook and cell metadata is not preserved in the\nconversion.\n\nStrip the output cells from markdown:\n\n::\n\n notedown with_output_cells.md --to markdown --strip > no_output_cells.md\n\nRunning an IPython Notebook\n~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\n::\n\n notedown notebook.md --run > executed_notebook.ipynb\n\nEditing in the browser *(new!)*\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\nYou can configure IPython / Jupyter to seamlessly use markdown as its\nstorage format. Add the following to your config file:\n\n::\n\n c.NotebookApp.contents_manager_class = 'notedown.NotedownContentsManager'\n\nNow you can edit your markdown files in the browser, execute code,\ncreate plots - all stored in markdown!\n\nFor Jupyter, your config file is ``jupyter_notebook_config.py`` in\n``~/.jupyter``. For IPython your config is\n``ipython_notebook_config.py`` in your ipython profile (probably\n``~/.ipython/profile_default``):\n\nR-markdown\n~~~~~~~~~~\n\nYou can use ``notedown`` to convert r-markdown as well. We just need to\ntell ``notedown`` to use `knitr <yihui.name/knitr>`__ to convert the\nr-markdown. This requires that you have R installed with\n`knitr <yihui.name/knitr>`__.\n\nConvert r-markdown into markdown:\n\n::\n\n notedown input.Rmd --to markdown --knit > output.md\n\nConvert r-markdown into an IPython notebook:\n\n::\n\n notedown input.Rmd --knit > output.ipynb\n\n- ``--rmagic`` will add ``%load_ext rpy2.ipython`` at the start of the\n notebook, allowing you to execute code cells using the rmagic\n extension (requires `rpy2 <http://rpy.sourceforge.net/>`__). notedown\n does the appropriate ``%R`` cell magic automatically.\n\nMagic\n~~~~~\n\nFenced code blocks annotated with a language other than python are read\ninto cells using IPython's ``%%`` `cell\nmagic <http://nbviewer.ipython.org/github/ipython/ipython/blob/1.x/examples/notebooks/Cell%20Magics.ipynb>`__.\n\nYou can disable this with ``--nomagic``.\n\n- ``--pre`` lets you add arbitrary code to the start of the notebook.\n e.g.\n ``notedown file.md --pre '%matplotlib inline' 'import numpy as np'``\n\nHow do I put a literal code block in my markdown?\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\nBy using the ``--match`` argument. ``notedown`` defaults to converting\n*all* code-blocks into code-cells. This behaviour can be changed by\ngiving a different argument to ``--match``:\n\n- ``--match=all``: convert all code blocks (the default)\n- ``--match=fenced``: only convert fenced code blocks\n- ``--match=language``: only convert fenced code blocks with 'language'\n as the syntax specifier (or any member of the block attributes)\n- ``--match=strict``: only convert code blocks with Pandoc style\n attributes containing 'python' and 'input' as classes. i.e. code\n blocks must look like\n\n ::\n\n ```{.python .input}\n code\n ```\n\nThis isn't very interactive!\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\nTry editing the markdown in the IPython Notebook using the\n``NotedownContentsManager`` (see above).\n\nYou can get an interactive ipython session in vim by using\n`vim-ipython <http://www.github.com/ivanov/vim-ipython>`__, which allows\nyou to connect to a running ipython kernel. You can send code from vim\nto ipython and get code completion from the running kernel. Try it!\n\nWhere's my syntax highlighting?!\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\nTry using either\n`vim-markdown <https://github.com/tpope/vim-markdown>`__ or\n`vim-pandoc <https://github.com/vim-pandoc/vim-pandoc>`__. Both are\nclever enough to highlight code in markdown.\n\nRendering outputs in markdown\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\nThis is experimental!\n\nConvert a notebook into markdown, rendering cell outputs as native\nmarkdown elements:\n\n::\n\n notedown input.ipynb --render\n\nThis means that e.g. png outputs become ```` images and\nthat text is placed in the document.\n\nOf course, you can use this in conjuntion with runipy to produce\nmarkdown-with-code-and-figures from markdown-with-code:\n\n::\n\n notedown input.md --run --render > output.md\n\nNot a notebook in sight!\n\nThe ``--render`` flag forces the output format to markdown.\n\nTODO\n~~~~\n\n- [x] Python 3 support\n- [x] unicode support\n- [x] IPython 3 support\n- [x] IPython 4 (Jupyter) support\n- [ ] Allow kernel specification\n",
"bugtrack_url": null,
"license": "BSD 2-Clause",
"summary": "Convert markdown to IPython notebook.",
"version": "1.5.1",
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"md5": "4ab6898e3c6cca8bf47a2fea1c364315",
"sha256": "82c5aeebe8c9f56c39ca4dd66c3b0fdfcc12874fda5a3e955004314b3ed879ac"
},
"downloads": -1,
"filename": "notedown-1.5.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "4ab6898e3c6cca8bf47a2fea1c364315",
"packagetype": "bdist_wheel",
"python_version": "3.6",
"requires_python": null,
"size": 19456,
"upload_time": "2017-11-16T17:59:43",
"upload_time_iso_8601": "2017-11-16T17:59:43.342377Z",
"url": "https://files.pythonhosted.org/packages/d3/3a/d7c1817f3acb2e958b32fe85a35f52d270820fb9cebf1364b36c772cf3d0/notedown-1.5.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"md5": "00d72f37e8a64d7f4c66ea8e0d214236",
"sha256": "36e033ebbbe5aca0fab031ffaf3611d5bc5c50237df68ff81bb95f8be353a1ee"
},
"downloads": -1,
"filename": "notedown-1.5.1.tar.gz",
"has_sig": false,
"md5_digest": "00d72f37e8a64d7f4c66ea8e0d214236",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 17106,
"upload_time": "2017-11-16T17:59:41",
"upload_time_iso_8601": "2017-11-16T17:59:41.426042Z",
"url": "https://files.pythonhosted.org/packages/58/1b/a926945216cb7d1d21abdbc975195bd7beb3bceafa41c186ecb95f8f9121/notedown-1.5.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2017-11-16 17:59:41",
"github": true,
"gitlab": false,
"bitbucket": false,
"github_user": "aaren",
"github_project": "notedown",
"travis_ci": true,
"coveralls": false,
"github_actions": false,
"lcname": "notedown"
}
JSON
