The goal of ipymd is to replace .ipynb
notebook files like:
{
"cells": [
{
"cell_type": "markdown",
"source": [
"Here is some Python code:"
]
},
{
"cell_type": "code",
"outputs": [
{
"name": "stdout",
"output_type": "stream",
"text": [
"Hello world!\n"
]
}
],
"source": [
"print(\"Hello world!\")"
]
},
...
by:
Here is some Python code:
```python
>>> print("Hello world!")
Hello world!
```
The JSON .ipymd
are removed out from the equation, and the conversion happens on-the-fly. The IPython notebook becomes an interactive Markdown text editor!
A drawback is that you loose metadata, prompt numbers, and images (for now).
This is useful when you write technical documents, blog posts, books, etc.
Pros:
- Excellent UI for executing code interactively and writing text
Cons:
- .ipynb not git-friendly
- Cannot easily edit in a text editor
- Cannot easily edit on GitHub's web interface
Pros:
- Simple ASCII format to write code and text
- Can easily edit in a text editor
- Can easily edit on GitHub's web interface
- Git-friendly
Cons:
- No UI to execute code interactively
All pros of IPython notebook and Markdown, no cons!
-
Write in Markdown in
document.md
- Either in a text editor (convenient when working on text)
- Or in the notebook (convenient when writing code examples)
-
Only the Markdown cells and code cells are saved in the file
-
Collaborators can work on the Markdown document using GitHub's web interface.
-
By convention, a notebook code cell is equivalent to a Markdown code block with explicit
python
syntax highlighting:>>> print("Hello world") Hello world
-
The back-and-forth conversion is not strictly the identity:
- Extra line breaks in Markdown are discarded
- Text output and standard output are combined into a single text output (stdout lines first, output lines last)
WARNING: use this library at your own risks, backup your data, and version-control your notebooks and Markdown files!
- Renaming doesn't work yet (issue #4)
- New notebook doesn't work yet (issue #5)
- Only nbformat v4 is supported currently (IPython 3.0)
-
You need IPython 3.0.
-
git clone https://github.com/rossant/ipymd
-
python setup.py install
-
Add this in your
ipython_notebook_config.py
file:c.NotebookApp.contents_manager_class = 'ipymd.IPymdContentsManager'
-
Now, you can open
.md
files in the notebook.
ipymd uses a modular architecture that lets you define new formats. The following formats are currently implemented:
- IPython notebook (
.ipynb
) - Markdown (
.md
)c.IPymdContentsManager.format = 'markdown'
- O'Reilly Atlas (
.md
with special HTML tags for code and mathematical equations)c.IPymdContentsManager.format = 'atlas'
You can convert from any supported format to any supported format. This works by converting to an intermediate format that is basically a list of notebook cells.
An ipymd cell is a Python dictionary with the following fields:
cell_type
:markdown
orcode
input
: a string with the code input (code cell only)output
: a string with the text output and stdout (code cell only)source
: a string containing Markdown markup (markdown cell only)
You can customize the exact way the notebook is converted from/to Markdown by deriving from BaseMarkdownReader
or MarkdownReader
(idem with writers). Look at ipymd/formats/markdown.py
.
You can also implement your own format by following these instructions:
-
Create a
MyFormatReader
class that implements:self.read(contents)
: yields ipymd cells from acontents
string
-
Create a
MyFormatWriter
class that implements:self.write(cell)
: append an ipymd cellself.contents
: return the contents as a string
-
To activate this format, call this:
from ipymd import format_manager format_manager().register('my_format', reader=MyFormatReader, writer=MyFormatWriter, file_extension='.md', # or anything else file_type='text', # or JSON )
-
Now you can convert contents:
ipymd.convert(contents, from_='notebook', to='my_format')
or any other combination. -
To further integrate your format in ipymd, create a
ipymd/formats/my_format.py
file. -
Put your reader and writer class in there, as well as a global variable (needs to end with
FORMAT
):MY_FORMAT = dict( name='markdown', reader=MyFormatReader, writer=MyFormatWriter, file_extension='.md', file_type='text', )
-
Import this file in
ipymd/formats/__init__.py
. -
Add
c.IPymdContentsManager.format = 'my_format'
to your IPython notebook config file. -
Add some unit tests in
ipymd/formats/tests
. -
Propose a PR!
Look at the existing format implementations for more details.