Markdown for Everything

I like to use markdown for everything: for my blogs, my emails (though they are mostly plain text), most of my short technical writing, and for most presentations. There have been many reasons for this shift:

1. Markdown is so much faster. Creating a Power Point presentation from an existing writeup or notes used to take a couple of hours; when I started using LaTex/Beamer, the time came down to about half an hour, but markdown reduced it to as little as 15 minutes.

2. Because markdown is designed to look like plain text (and not like lots of tags and formatting instructions), it forces me to focus on the content. Instead of wasting time adding bells and whistles to a inane document or slides (as I often used to do with MS Office and LaTex), it is much better to spend time improving what I am actually saying.

3. The fact that markdown is basically plain text, means that it is easy to convert it into almost any other format without loss of formatting. My favourite way to send a Word file to a colleague is to use pandoc to convert my markdown text into Word. LaTex is at the other extreme: because it is publishing quality, conversion to almost any other format loses information.

4. It ties in with my long journey towards minimalism (see my blog post a couple of years ago and the two earlier posts referred to there). Less is More.

I am able to do so much with markdown because of several great tools like pandoc and jupyter.

Pandoc

Pandoc is the workhorse of document conversion. Years after I started using it, I keep discovering new features and capabilities of this remarkable software. It can convert from almost any format to any other format. Its default behaviour is usually good enough for most purposes, but it can be customized through a bewildering range of options and templates. And it is all open source.

Jupyter Notebook and RISE

Many years ago, I started using Jupyter to perform interactive computations in a web browser. It helps me to demonstrate complex models by executing python code, and viewing interactive plots using mathplotlib. I discussed some of this in a blog post two years ago.

More recently, I started using RISE which marries reveal.js with Jupyter to create a powerful presentation tool. Jupyter-RISE brings interactivity to the slides in a way that Power Point and LaTex/Beamer users cannot even dream about. In Jupyter-RISE, it is so easy to edit a sentence not only without leaving the presentation, but without even leaving full screen mode. It is even possible to start with a blank slide and fill it up with audience responses. The only other similar interactive solution that I am aware of is Xournal connected to a writing tablet.

If you have the Jupyter server running somewhere in the network, then you need only a web browser to launch the presentation. Within my Institute, that means I can walk into any classroom or meeting room empty handed, point the web browser to my Jupyter server running on one of the machines in the local network and get going. While travelling outside, and not carrying my laptop, I have often carried a portable installation of the open source WinPython on a pen drive. I simply plug it into any available machine, and start Jupyter.

Wrapper and Glue

To make my life easier, I have written a set of wrapper or glue scripts to convert to/from markdown using various open source tools. All the hard work is done by these great tools. My scripts only glue them together to do the job quickly and painlessly. These scripts are available on my github repo along with the usage instructions.

For example, there is a script to create Jupyter-RISE slides from markdown. I write the content using markdown, then mark the beginning of slides, subslides and fragments using a comment line with the appropriate keyword:

<!-- slide|sub-slide|fragment -->

The script md2ipnb.py is basically a pre-processor and wrapper around Jupyter-nbconvert that turns this file into a Jupyter-RISE notebook.

I can intersperse code cells demarcated by lines containing three backticks (```). But if my presentation is mostly python code with a bit of markdown here and there, I start with a python file, and intersperse the markdown as comments in this file. The script py2ipnb.py is basically a pre-processor and wrapper around Jupyter-nbconvert that turns this file into a Jupyter-RISE notebook. Following comment lines can be used in the python file to demarcate cells:

# <codecell>: [slide|sub-slide|fragment]
# <markdowncell>: [slide|sub-slide|fragment]
#% ipython magic commands like %matplotlib inline

The advantage is that the entire file is valid python code and can be edited and tested in my favourite python editor or IDE.

Often, it is desired to distribute the presentation as a PDF file. I have a script (ipnb2pdf) that converts Jupyter-RISE notebooks to PDF slides via html using Jupyter-nbconvert and wkhtmltopdf. This basically automates the manual process described in the RISE documentation.

Sometimes, I want to make my presentation using a PDF viewer and not a Jupyter-RISE notebook, but still want to write everything in markdown. If you want to do that, pandoc is your friend, and my small shell script md2beamer runs pandoc and then LaTex to produce a PDF file. Quite often, I want to “weave” the output of python code into my markdown text using pweave. In this situation, my shell script pwv-pandoc gets the job done by running pweave, pandoc and latex in succession.

Advertisement