Skip to main content

Markdown to Jupyter Notebook converter.

Project description

md2ipynb

Markdown to Jupyter Notebook converter.

Setup

[optional] Virtual environment

Make sure you have virtualenv installed.

pip install -U virtualenv

Create and activate a new virtualenv.

python -m virtualenv env
source env/bin/activate

Note: Once you are all done, you can deactivate it by running deactivate.

Installation

The easiest way to install is through pip.

pip install -U md2ipynb

Example data

Now, to get some example data, we'll clone the repository.

# Clone the repository just to have access to the examples.
git clone git@github.com:davidcavazos/md2ipynb.git
cd md2ipynb

Note: If you make modifications to the source code and want to use that, you can install it in "editable" (development) mode.

pip install -e .

For more information, see the Contribution guide.

Installing the md2ipynb module will also install the md2ipynb command line tool. For custom preprocessing steps or integration with Python scripts, it is also available by importing the md2ipynb module from any Python script.

Minimal example

Here is a minimal example on how to convert a Markdown file. By default, the output is printed into stdout.

md2ipynb examples/pages/hello.md

You can also specify an output path with the -o or --output option.

md2ipynb examples/pages/hello.md -o examples/notebooks/hello.ipynb

Here is the generated notebook on Colab and GitHub.

Run in Colab View on GitHub

Example

Here is a more complete example on specifying an output path, import sections, variables, as well as more metadata for a Colab visualization.

md2ipynb examples/pages/hello.md \
    -o examples/notebooks/hello.ipynb \
    --imports examples/templates/license.md:0 \
              examples/templates/setup-py.md:1 \
              examples/templates/cleanup.md:-2 \
    --var package=md2ipynb \
          end_message="You're all done 🎉🎉" \
    --notebook-title 'Hello md2ipynb!' \
    --docs-url https://github.com/davidcavazos/md2ipynb \
    --docs-logo-url https://www.tensorflow.org/images/GitHub-Mark-32px.png \
    --github-ipynb-url https://github.com/davidcavazos/md2ipynb/blob/master/examples/notebooks/hello.ipynb

Note: For more information on the available options, run md2ipynb --help.

Here is the generated notebook on Colab and GitHub. Note that since we specified the --github-ipynb-url, there is now an "Open in Colab" button in the GitHub ipynb file.

Run in Colab View on GitHub

Python example

The following example shows how to use md2ipynb as a Python module. This example shows how to specify custom preprocessing steps, import sections, use variables, as well as more metadata for a Colab visualization.

import md2ipynb

def add_separators(paragraphs):
  for p in paragraphs:
    yield '---'
    yield p
  yield '---'

def replace(paragraphs, old, new):
  for p in paragraphs:
    yield p.replace(old, new)

# Create a new IPython notebook.
notebook = md2ipynb.new_notebook(
    input_file='examples/pages/hello.md',
    imports={
        0: ['examples/templates/license.md'],
        1: ['examples/templates/setup-py.md'],
        -1: ['examples/templates/cleanup.md'],
    },
    variables={
        'package': 'md2ipynb',
        'end_message': "You're all done 🎉🎉",
    },
    notebook_title='Hello md2ipynb!',
    docs_url='https://github.com/davidcavazos/md2ipynb',
    docs_logo_url='https://www.tensorflow.org/images/GitHub-Mark-32px.png',
    github_ipynb_url='https://github.com/davidcavazos/md2ipynb/blob/master/examples/notebooks/hello.ipynb',

    # Additional steps can be run in the order specified.
    # If the generator receives multiple arguments, they can be passed as a tuple.
    steps=[
        add_separators,
        (replace, 'Hello', 'Hi'),
    ],
)

# Write the notebook to a file.
import nbformat

with open('examples/notebooks/hello-custom.ipynb', 'w') as f:
  nbformat.write(notebook, f)

Here is the generated notebook on Colab and GitHub.

Run in Colab View on GitHub

Contributing

Contributions are welcome! For instructions on how to contribute, please check the Contribution guide.

Project details


Download files

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

Files for md2ipynb, version 0.2.1
Filename, size File type Python version Upload date Hashes
Filename, size md2ipynb-0.2.1-py3-none-any.whl (42.2 kB) File type Wheel Python version py3 Upload date Hashes View
Filename, size md2ipynb-0.2.1.tar.gz (17.6 kB) File type Source Python version None Upload date Hashes View

Supported by

Pingdom Pingdom Monitoring Google Google Object Storage and Download Analytics Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page