Using Markdown and Make to maintain a bunch of documents

Note: This is an archived copy of a document that was originally located at The document has been reformatted for display here, but the content has not been modified.

Revision 1 (P. Damian Cugley, 2005-04-02)


Markdown is a program that converts text files in to HTML fragments. The text format understood by Markdown uses a minimum of weird punctuation, which makes it more readable when editing it than the HTML is. At work when I have to write documentation, I have switched to using Markdown rather than writing raw HTML: it allows me to concentrate on the words rather than the coding side.

Markdown generates only the body of the page, not a complete document. This note describes the combination of make and sed I use to manage collections of documents with common headers and footers.

Getting make and sed

The programs make and sed are standard-issue on Unix-like operating systems like GNU/Linux and Mac OS X.

On Windows XP, I use the nmake command that comes with Microsoft Visual Studio .NET (use start button → All Programs → Microsoft Visual Studio.NET 2003 → Tools → Command Prompt to create a window with the environment variables set up right). For sed I use the Cygwin package, a collection of GNU utilities ported to Microsoft Windows.

Getting Markdown

On Windows, I unpacked the ZIP archive from the Daring Fireball project page in to a directory of my C:\Program Files and then added the Markdown-1.0.1 directory to my Path environment variable (control panel → System → Advanced → Environment). This allows the use of markdown as a command.

On my Debian GNU/Linux box, apt-get install markdown does the trick.

I have not yet succeeded in installing Markdown on Mac OS X 10.2 ‘Jaguar’. This is slightly annoying because I do most of my writing at home on my PowerBook. Up until now I have made do with a partial implementation of Markdown in Python, but this is not very satisfactory. The funny thing is, John Gruber developed Markdown on Mac OS X…

Using make to format documents

Write documents as .txt files using a plain text editor (such as vi or Notepad). For example:

Increasing Human Happiness with Jam

Revision 1 (P. Damian Cugley 2005-04-07)


The exact number of equals signs under the titles does not matter. The important thing is that the page title, underlined with equals signs, goes first in the document.

The simplest useful Makefile for Markdown would look like this:

MARKDOWN = markdown
txtFiles = index.txt

all: $(txtFiles:.txt=.html)

        rm -f $(txtFiles:.txt=.html)

.SUFFIXES: .txt .html
        $(MARKDOWN) < $< > $@

The variable txtFiles lists all the .txt files in the directory. The command make all runs them all through Markdown. The conventional make clean deletes all the HTML files.

The resulting HTML files are adequate (old versions of HTML did not require the document to be wrapped in html and body elements) but will look very plain.

Using sed to complete the HTML files

We want to wrap the ‘raw’ documents in extra HTML boilerplate. We do this by adding sed to the mix: the last 2 lines of the Makefile is changed to the following:

        $(MARKDOWN) < $< | sed -f finish.sed > $@

Now we create a sed script that adds HTML code before and after the output of Markdown. I admit I have to read the sed manual each time I make one of these. It goes like this:

# Devilish cunning sed script for wrapping Markdown output as HTML

1   {
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"\
<html xml:lang="en-GB" lang="en-GB">\

2   {

$   {

The first clause matches line 1 and replaces the h1 element with a complete HTML preamble and head element. The contents of the h1 is used for the document title, and additional metadata is read from the file, if it exists. Then the HTML code in file is appended.

The second clause happens on line 2: all it does is reinstate the h1 element snarfed from line 1. Finally, the last line has and the HTML close tags appended to it.

The sed program does not care that these files do not exist yet; do the command make clean; make and it will generate valid HTML files without any additional mark-up.

Adding a stylesheet

Create a file containing the following:

<link rel="stylesheet" type="text/css" href="main.css" />

After you rebuild the HTML files, they will have reference to the style sheet main.css. Add as many link and meta elements as you like.

Adding header and footer

This is fairly obvious: create with something like this as its contents:

<div id="header">
<p id="trail"><a href="../../">Alleged Literature</a> &rarr;</p>

Then add stuff to the CSS file to visually distinguish the header. (Arguably this is not particularly ‘semantic’ mark-up, but what the hey.) I also have a footer for this set of documents, that goes something like this:

<div id="footer">
<a href=""
    id="poweredByMarkdown">Powered by Markdown</a>

just for fun.

List of all the files

Here are links to the files used to make this here note: