Git tip: Automatically converting iPython notebook READMEs to Markdown

A small but useful tip today, on using iPython notebooks for a git project README while keeping an auto-generated version in the Markdown format that Github prefers.


I’m in the midst of refreshing and updating the HTRC Feature Reader library. Since the README for that project walks you through the tool and sample output, I converted it to an iPython notebook: it’s easier to maintain and easier for some people to try it themselves.

While Github now formats iPython notebooks properly, it only does so when viewed directly, making it useless for a landing page (e.g. See how the raw text is shown in this repository).

My solution was to automatically generate the ‘pretty’ Markdown version that Github prefers, using git hooks and iPython’s nbconvert command. Git hooks allow you to hook in client-side or server-side scripts before or after various git actions, like pre-commitpost-checkout, pre-rebase, etc.

The Notebook-to-Markdown conversion script runs post-commit* by adding the following code to .git/hooks/post-commit:

This code checks if README.ipynb was committed without README.md. If it has, it generates the latter and amends the previous commit. If you want to commit a file without the check, you can always run git commit with –no-verify.

By the way, if you’re looking for a way to only track substantial iPython Notebook changes in git, this tip works for me.


*Why post-commit and not pre-commit? It seems that at pre-commit, newer installs of Git don’t allow you to git add to commit you’re adding to: the file ends up staged.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s