Wiki Formats

For years I've dealt with raw HTML for a lot of my web pages. After some experience with various wiki sites, I've finally realized that it's a lot easier to maintain a bunch of simple text files marked up in some wiki format, and use clever scripts to convert them to HTML for publishing.

Source code should always be readable, and HTML does not quite make the cut. Reading documentation in raw HTML form is painful. Inspired by the Inform 7 language, I want my text file marked up with wiki to as close to a real document as possible. In other words, I want the source to be a pretty text file that you can read even if you don't have the HTML version. A bit like txt2html, but I want more control. Compare my homepage with it's wiki source.

And if you do need complex HTML, it's easy enough to provide a mechanism to temporarily disregard wiki tags.

I wrote a script that takes converts a text file, marked up in a certain way, and converts it to HTML with these goals in mind, and it's kept in a Git repository at

• http://cs.stanford.edu/~blynn/scrap/wiki.git

[20090608: updated link]
I'll have to write instructions one day, but basically, headings are designated with equal signs around the heading, two single quotes are italics, asterisks are used to mark text as bold, a minus sign and indentation for lists. Other indentations mean text that should be displayed unformatted and as fixed width.

I'm gradually converting all my HTML to this wiki format, as it's easier to edit and maintain. An added bonus is that I can easily write scripts to output a different format, such as DocBook.