[ home ]

Wiki?

Wiki?
- Rationale - a boring story
  - MicKI
  - Markdown
- Workflow and 'code'

Rationale - a boring story

The info-pages you are browsing now are not rendered by a wiki-engine of some sort, but consist of static, pre-generated HTML.

MicKI

My personal reasons for using a wiki a while ago were mainly:

being able to quickly make something look a bit good (i.e. abstracting from HTML and using a simple markup-language instead)
remote access (read/write from anywhere in the world)

To do this, I created a simple wiki-engine ('MicKI'). It was ok, but took effort (the horror!), there were bugs, flaws, and eventually it didn't work with a non-Apache httpd.

Then came Markdown.

Markdown

The canonical Markdown-implementation at Daringfireball.net is quite good; however, I am using MultiMarkdown now, because of the ability to generate a TOC.

Markdown follows the *nix-approach quite well:

rendering markup to HTML, period.

Assuming that we have remote access using SSH, this does exactly what I originally wanted.

In addition, Markdown for me is:

simpler to setup
simpler to use, and simpler to automate
so intuitive, that most plaintext-files are almost Markup-source already
more secure (it's plain HTML, no magic involved)

So there.

Workflow and 'code'

General workflow when editing content is as follows:

Human edits/creates a *.markdown file
*.markdown is converted to *.p.html ('pre-HTML') using Markdown
*.p.html is converted to HTML by fitting a header and footer to it
an index.html is generated, listing relevant files - itself using Markdown for rendering

At the time of writing, a GNU Make script binds everything together:

    SRC   = $(shell ls *.markdown | grep -v '^index\.markdown' )
    HTML  = $(subst .markdown,.html,$(SRC))
    TARG  = $(HTML) index.html
    MARKDOWN = multimarkdown --nosmart
        
    all: $(TARG)
        
    %.html: %.p.html header.html footer.html
    	( sed "s/___TITLE___/$(shell echo $(basename $@) | tr _ ' ')/" header.html; cat $< footer.html ) > $@
        
    %.p.html: %.markdown
    	$(MARKDOWN) $< > $@
        
    .INTERMEDIATE: header.html footer.html
        
    header.html:
    	echo                                                       \
    		'<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN">'   \
    		'<html><head><link rel="stylesheet" href="css.css">'   \
    		"<title>___TITLE___</title>"                           \
    		'</head><body>'                                        > $@
        
    footer.html:
    	echo '</body></html>' > $@
        
    .DELETE_ON_ERROR .INTERMEDIATE: index.markdown
        
    index.markdown: $(HTML)
    	printf '# Stuff that was once new.\n'                                                               >  $@
    	printf "Welcome to **Michai's Random Bits of Info!**\n"                                             >> $@
    	printf '\n'                                                                                         >> $@
    	printf '![](sheep.png)\n'                                                                           >> $@
    	printf '\n'                                                                                         >> $@
    	printf 'Apart from all the **awesome pages** below, ...\n'                                          >> $@
    	printf '\n'                                                                                         >> $@
    	printf '  - ... I occasionally make [YouTube-videos](https://www.youtube.com/user/mramakers),\n'    >> $@
    	printf '  - ... I occasionally record a [Podcast](https://podcast.cba.si) (audio only),\n'          >> $@
    	printf '  - ... I occasionally [Tweet](https://twitter.com/MichaiRamakers) about my own stuff.\n'   >> $@
    	printf '\n'                                                                                         >> $@
    	printf '_Suggestions, questions, comments and/or complaints? ---> <mailto:m.ramakers@gmail.com>_\n' >> $@
    	printf '\n---\n'                                                                                    >> $@
    	printf '\n'                                                                                         >> $@
    	printf '# Alphabetical page-list\n\n'                                                               >> $@
    	ls $(SRC)                                                                                           \
    		| sed 's@ *\(.*\).markdown.*@-   [\1](\1.html)@'                                                \
    		| sort -f                                                                                       >> $@
        
    clean:
    	-rm $(TARG)
        
    .PHONY: sync
        
    sync: 
    	./sync

And that's basically all of the code behind this wonderful website.

The contents itself are kept in a Fossil repository for versioning and backup. Fossil itself also has a nice wiki (with native and Markdown-markup!), but it was considered overkill for these info-pages.