Using Markdown in Sublime Text 2 on Windows

11 years ago

I’m currently writing a series of articles that will be published as a set of (fairly) static webpages, not blog posts. So I can’t really use Windows Live Writer and consequently started off using Microsoft Word. The biggest problem with Word in this scenario is that, when you save a document as HTML, it produces the ugliest markup ever, even worse than FrontPage of old. In fact, there are whole collections of utilities out there that just strip the fugly markup out, just to give you a passing chance at getting reasonable HTML.

After a little while, I started getting up tight about this and wondered if I couldn’t just use something like Markdown. For those not in the know, Markdown was invented by John Gruber as a way to write text files with absolute minimal markup that can be read and understood as text, but that could, with minimal parsing and computation, be converted to HTML. Once you get to know the minimal markup (for example, typing *this is an emphasized statement* will produce this is an emphasized statement whereas **this is a strong statement** will give this is a strong statement – notice how the original markup gives a hint of how the text should be read), writing Markdown text is very fast.

Syntax highlighting

Enter my new text editor of choice, Sublime Text 2. There are lots of features to like here, but one of the biggest for me is its ability to produce syntax highlighting for any type of file. It even has a “Markdown” option, but unfortunately Sublime Text doesn’t produce any syntax highlighting for it out of the box. Since Sublime Text is extensible, my first port of call with Google was finding some highlighting for Markdown files. I came across this blog post by Bram Van Damme that had exactly the right extra code I needed. Although Brad talks about where to find the Monokai.tmTheme file on the Mac, he doesn’t for Windows. No problem: it can be found in this folder: C:\Users\\AppData\Roaming\Sublime Text 2\Packages\Color Scheme – Default.

I inserted the code into the theme file, restarted Sublime Text and my Markdown files were suddenly syntax highlighted. Nice.

Markdown preview

Onto the next problem I wanted to solve before I could use Markdown properly: seeing a preview in my browser as I was writing text. Even though Markdown is simple to write and read, sometimes all it takes is a preview of the finished HTML for you to notice formatting errors (consider for example that code blocks require every line to be preceded by four spaces).

Another quick session with Google gave me this open-source project on GitHub called Sublime Text 2 Markdown preview. The installation notes for this project state that you should use the Sublime Text 2 Package Control app for installing the preview into Sublime Text 2.

Sublime Package Control

Feeling a little as if I was going down a rabbit hole at this point, I went to the site and followed the installation instructions for the package manager – the first set of instructions that describe pasting a command line into the Sublime Text console (something I hadn’t seen until this point). It was simple and pretty much instantaneous, and, like the prompt said, I restarted Sublime Text.

Markdown preview, again

Now I had the package manager installed, it was time to install the Preview package. As it said in the installation notes (well, with my Windows hat on since it talks about Mac keys), I pressed Ctrl+Shift+P to bring up the Sublime Text command list, and then I clicked on Package Control: Install Package to bring up the packages that could be installed. There was Markdown Preview in the list so I clicked on that. It installed fine, after which I could press Ctrl+Shift+P again, select Markdown Preview to have it generate the HTML as a temporary file and display it in Firefox (my browser of choice at the moment).

Except that was a right royal pain in the neck: hitting Ctrl+Shift+P and selecting Markdown Preview every time I wanted to view the text as HTML. Yes, I could map a keystroke as suggested, but was there anything better?

LiveReload

Enter the next piece of the puzzle: the Sublime Text 2 LiveReload plugin. Installing it was simple now that I had the package manager installed: Ctrl+Shift+P, Package Control: Install Package, and find LiveReload.

This is where it all got a little flaky for me. The page on GitHub talks about browser extensions “You can use both major LiveReload versions. For old one you can find instructions bellow, for new ones please visit New browser extensions or try self loading version.” Er, what? What “major versions”? What’s the difference? Which is better? Etc.

There is a header link underneath for “Firefox 4 extension”. I decided to try that one despite my using Firefox 19 at the moment. The link goes to the add-on page at Mozilla, where it helpfully says it’s out of date. OK, there’s a link there to go find the latest versions so I followed that. On the page thus navigated to, there’s a link to download the “Firefox extension 2.0.8”. Clicked on that and it was installed into Firefox.

This add-on adds a little icon into the address/search bar. It has two states that show LiveReload disabled

or enabled

but unhelpfully the tooltip is the same for both states: “Enable LiveReload”. Right. And the difference is incredibly subtle (originally I thought the red line meant “crossed out”, hence disabled; nope, it’s the other way round).

After some experimentation, I finally got the automatic reloading of the preview working (you might get a firewall warning though: allow it, since the reload functionality works by opening a socket between the package in Sublime Text and the add-in in your browser).

In essence, you preview the page for the first time (Ctrl+Shift+P, select Preview), and you make sure that on that browser tab, the LiveReload icon is set to enabled. After that you can press Ctrl+S to save the Markdown file in Sublime Text and the preview will automatically update.

I also pinned my Sublime Text window to the left of one of my screens (Windows key + left arrow while the window has focus), and the browser tab to the right of the same screen (Windows key + right arrow). This makes for a pretty simple workflow and look-and-feel.