5 janvier, 2017

I’m using Markdown as a markup syntax for many things: the syntax is indeed really simple to use, it lets me focus on the content I need to write, and it can later be converted to HTML for « real life » display once I’m done. In the open-source community, it has become largely spread, and many developpers use it, like me, for non code-related stuff, like keeping notes or writing their journal.

Until recently, I’ve been using Markdown Preview. It’s a sublime-text plugin for previewing the HTML transformation a markdown file. It works well, but it has a few issues for me. The first is that it uses Github as a backend for HTML conversion. When working for a long time on a file, I often reach the max amount of allowed calls to the webservice for the conversions, then conversions are not possible for a while, which is quite annoying.

The second problem is that, recently, I’ve become interested in writing math things. LaTeX comes immediately to the mind, as the language invented by Donald Knuth in the beginning of the 80x is the de facto standard for writing equations in the academic world. But it is not possible to have LaTeX properly converted when it is in the middle of a markdown file using Github flavoured markdown. There are ways to cheat this though, but it is not easy and it is not compatible as-is with Markdown Preview.

We will take a different route.

The problem

The use-case is the following : I want to write my markdown files in sublime-text. They can contain LaTeX content, and I want to be able to generate an HTML output with the proper transformations applied. How to do that ? Can it be simple ? The answer is yes, let’s see how.

A bash script to the rescue

Pandoc is a swiss knife for conversion between markup formats. It works well for markdown to html, but can calso convert LaTeX to HTML. The latest release can be downloaded here,w e will use it later.

The thing is that pandoc either converts markdown to html or latex to html, but not both at the same time. However, we can cheat: the trick is to convert from markdown to html, and include the JavaScript MathJax library in the HTML output. That way, the LaTeX is not transformed during the markdown to HTML conversion, but it is transformed at runtime, in the browser.

The syntax « ${1%.*} ».html means « remove the extension then add .html ». So the script creates a file.html out of the pandoc markdown conversion of a file.something. In this HTML file, the javascript library MathJax is included

Once it has the proper execution rights ($ chmod +x mdtex2html.sh), it can be used to convert a file with any extension

$ ./mdtex2html.sh sample.mdtex

Thanks to that, we can have the expected output.

We could decide that we are done here, but every time we want to convert the markdown file, we have to execute the script from the command line. We can do better 🙂 We can create a custom sublime-text build.

Making it better with a build script

First, let’s move our shell script to a path-aware directory :

$ sudo cp mdtex2html.sh /usr/bin

Now we can invoke mdtex2html.sh from anywhere :

$ mdtex2html.sh sample.mdtex

Then, we’ll create a build for our markdown files. The .mdtex extension is arbitrary, but it will be useful now : Tools -> Build system -> New build system. Immediately save the build file as mdtex.sublime-build:

{
"cmd": ["mdtex2html.sh", "${file_path}/${file_name}"]
}

The build calls mdtex2html.sh and provide the current file name as an argument.

Now, every time we run a build (with Ctrl+B) from our .mdtex files, it will be compiled into HTML.

Even better with live reload

So. Now, every time we hit Ctrl+B, files with a .mdtex extension are converted into HTML. We then have to refresh the page in the browser in order to see the changes. It needs to open the tab, hit F5, and wait for the rendering to be over.

We can do better, and skip the F5 update with the proper tool. One solution is to use system tools like inotify (or variants like pynotify, in python) to watch the changes on the HTML file. There is a detailled setup here: it works well for complex solutions, like a jekyll blog that involve a lot of files.

There however are various browser extensions, like Auto-reload for Firefox, that watch file and reload the page when they change. Once it is setup, you can work from sublime text, save with Ctrl+S, build with Ctrl+B, and the latest built version will be updated in the browser.

It is also possible to trigger the build on save with the Build on save extension, but I did not do that.