Using Markdown and Make to maintain a bunch of documents
Overview
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)
Overview
-----
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)
clean:
rm -f $(txtFiles:.txt=.html)
.SUFFIXES: .txt .html
.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:
.txt.html:
$(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 {
h
i\
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"\
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">\
<html xml:lang="en-GB" lang="en-GB">\
<head>
s/h1>/title>/g
rmetadata.inc
a\
</head>\
<body>
rheader.inc
}
2 {
x
p
x
}
$ {
rfooter.inc
a\
</body>\
</html>
}
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 metadata.inc, if it exists. Then the HTML code in file
header.inc 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 footer.inc
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 metadata.inc 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 header.inc with something like this
as its contents:
<div id="header">
<p id="trail"><a href="../../">Alleged Literature</a> →</p>
</div>
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="http://daringfireball.net/projects/markdown/"
id="poweredByMarkdown">Powered by Markdown</a>
</div>
just for fun.
List of all the files
Here are links to the files used to make this here note: