Using Markdown in projects

I write lots of minor documentation files: Readme’s; release notes; instructions for checking out and building the project; weekly reports; todo lists; internal documentation; etc. If I want to keep these in sync with the source code they refer to, then I need to put it in git/Hg/SVN/CVS version control which rules out using MS Word (not that I was seriously planning to use Word). So it’s plain text then…

But, just as Word locks me into one tool, so plain text locks me in to a certain look: 12pt Courier, no bold, italics, section headers, tables, etc. Surely we can do better than that?

Markdown

Markdown is an almost plaintext ‘markup’ notation based on the formatting conventions we already use in emails. You use _ round a phrase to add emphasis, * at the start of a line to create bulleted lists, > at the start of a line to quote a block of text and use — and === to underline section headings. We all use these conventions anyway so all you have to learn is how to be consistent about it.

A fair number of the more techy blogs use Markdown (e.g., Brett Terpstra’s blog), it’s used in GitHub, it’s used in Jekyll, … It’s used by geeks like us.

I’ve started using Markdown for all the text files sitting around in my current work project. Not much so far: a README and RELEASE notes, some internal documentation.

What do you have to do to use Markdown? Since Markdown uses normal text formatting conventions the answer is not that much: just use the particular set of conventions that Markdown uses. And then add a few Makefile rules

%.html: %.txt 
    multimarkdown $< > $@

And you are all set. (Instructions on installing markdown at the end.)

Making it pretty

The resulting HTML is entirely functional but you can make it a lot more readable by adding a simple stylesheet.

It may just be a fashion thing but Times-Roman feels a little dated to me. I like the look of the Palatino font used by Safari Reader so I specify that and, following the Font Families advice I add settings that work too on Windows and Linux. I base my monospace font choice on the same advice except that I prefer Inconsolata-dz font if available.
```
  body { font-family: Palatino, "Palatino Linotype", "URW Palladio L", serif; }
  code { font-family: "Courier New", Courier, "Nimbus Mono L", monospace; font-size: 90%; }
```
A lot of web pages these days (also Safari Reader) don’t use plain black and white: they use a dark grey for the main text so that headings can use a blacker font instead of a bolder font.
```
  body { color: #333333; }
  h1, h2, h3, h4 { colour: #111111; font-weight: normal; }
```
Good web pages also add a little extra space round the margins and limit the line width. Your 30” monitor looks awesome but do you really want 2560-pixel lines of text?
```
  body { padding: 20px; line-height: 1.5; max-width: 960px; }
```

I like my code blocks to stand out just a little so I put a subtle border round them and add a faint background colour.

  pre {
    background-color: #f8f8f8;
    border: 1px solid #cccccc; padding: 6px 10px; border-radius: 3px;
    overflow: auto;
  }

The easy way to use this stylesheet is to add this line to the start of your file:

CSS: doc.css

(You might also want to specify other metadata like ‘Title: …’, ‘Author: …’, ‘Date: …’, etc.)

But I think that would look out of place at the start of the release notes so, for txt files I hardwire it in the Makefile.

%.html:: %.txt
    echo '<head><link type="text/css" rel="stylesheet" href="doc.css"/></head>' > $@
    multimarkdown $< >> $@

Editing Markdown

Markdown is a very popular format so there are helpful tools for every platform. On a Mac, the ones I use are:

.nvALT: a note taking application with live Markdown preview.
marked/marked2: a Markdown viewer that works with any editor: each time you save a file, the viewer updates the display. Includes the ability to generate PDF, MS-Word and RTF format output and some considerably more advanced stylesheets than the one I sketched above.
Markdown Service tools: a collection of Mac “services” that let you do things like write an email in Markdown, select all, apply the “Markdown to RTF” service and send the resulting RTF email.

Installing tools

You can install multimarkdown using sudo apt-get install libtext-multimarkdown-perl or brew install multimarkdown.

Written on October 20, 2013.
The opinions expressed are my own views and not my employer's.