2.2. Editing Source Files

No matter whether it is a pure text file or a Jupyter notebook, we recommend that you save it as a markdown file. If it is a notebook, you can clear output before saving to make code review and version control easier.

You can use your favorite markdown editors, e.g. Typora, to edit markdown files directly. We enhanced markdown to support additional feature such as image/table captions and references, please refer to Section 2.5 for more details. For a notebook, a Jupyter source code block is placed in a markdown code block with a {.python .input} tag, for example,

```{.python .input}
print('this is a Jupyter code cell')
```

Another way we recommend is using Jupyter to edit markdown files directly, especially when they contain source code blocks. Jupyter’s default file format is ipynb. We can use the notedown plugin to have Jupyter open and save markdown files.

You can install this extension by

pip install mu-notedown

(mu-notedown is a fork of notedown with several modifications. You may need to uninstall the original notedown first.)

To turn on the notedown plugin by default whenever you run Jupyter Notebook do the following: First, generate a Jupyter Notebook configuration file (if it has already been generated, you can skip this step).

jupyter notebook --generate-config

Then, add the following line to the end of the Jupyter Notebook configuration file (for Linux/macOS, usually in the path ~/.jupyter/jupyter_notebook_config.py):

c.NotebookApp.contents_manager_class = 'notedown.NotedownContentsManager'

Next restart your Jupyter, you should be able to open these markdowns in Jupyter as notebooks now.

Fig. 2.2.1 Use Jupyter to edit Section 2.1