md2nb - Converting Markdown Files to Jupyter Notebook

Created by Qin Yu, Nov 2020 - Dec 2020

Table of Contents

• Manifesto
• Installation
• Usage

Manifesto

Taking notes using Markdown makes it easier for sharing on GitHub, but GitHub doesn't display Latex-style mathematics in .md files. A good workaround is to write Markdown in Jupyter notebooks and share the .ipynb files on GitHub, since everything inside is usually rendered properly. However, it is easier to take notes on a local text editor such as VSCode with Markdown support, becuase it automatically generates and updates the table of content, and you don't have to run a notebook server to take notes.

This package is quite simple, all it does it to create a Jupyter notebook and paste the content of one file into a Markdown block in this notebook. But the author decided to make it a package because of the encouraging talk by Mark Smith at EuroPython 2019.

Installation

$ # install using:
$ python -m pip install md2nb
$
$ # to verify installation and show help:
$ md2nb

Usage

As the simplest example, in the root directory of this repo, this will convert all .md files to .ipynb files (if there is no .m2n file found in the specified directories):

$ md2nb --dir .
Converting '.md' files within ./:
	./README.md

But if .m2n files are found in the specified directories, e.g. here in the ./test/ folder, then only .m2n files are converted. This is because you may only want to convert some Markdown files to Jupyter notebooks, and you can mark these files by making their extension .m2n:

$ md2nb --dir ./test
Converting '.m2n' files within ./test/:
	./test/example.m2n
	./test/example-gB18030.m2n

In short, use md2nb PATH_TO_FILE1 PATH_TO_FILE2, or md2nb --dir PATH_TO_DIRECTORY1 PATH_TO_DIRECTORY2. There are two recommended ways of using md2nb:

1. md2nb converts all files with --ext specified extensions in the --dir specified directories into .ipynb files with a single Markdown block. For example:

   # to convert all Markdown and text files in the current directory and all of its subdirectories
   $ md2nb --dir . -r --ext .md .txt

2. md2nb converts all files identified by their file paths. For example:

   # to convert all Markdown files in the current directory and all of its subdirectories
   $ md2nb *.md -r

3. In fact, these two ways can be combined. For example:

   # to convert README, LICENSE, all .md and .txt files in . and ./doc/
   $ md2nb README.md LICENSE --dir . test --ext .md .txt

To check what files are going to be converted:

$ md2nb --dir . -r --dry-run