# 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;
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