Using Markdown and Make to maintain a bunch of documents ===== Revision 1 (P. Damian Cugley, 2005-04-02) Overview ----- [Markdown][1] 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][1] 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\ \ \ s/h1>/title>/g rmetadata.inc a\ \ rheader.inc } 2 { x p x } $ { rfooter.inc a\ \ } 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: 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: 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: just for fun. List of all the files ----- Here are links to the files used to make this here note: * [`index.txt`](index.txt) * [`Makefile`](Makefile) * [`finish.sed`](finish.sed) * [`metadata.inc`](metadata.inc) * [`header.inc`](header.inc) * [`footer.inc`](footer.inc) * [`main.css`](main.css) [1]: http://daringfireball.net/projects/markdown/ [2]: https://sourceforge.net/projects/pywin32/ [3]: http://www.jedit.org/