[index] [home]



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.


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

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.


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:

So there.

Workflow and 'code'

General workflow when editing content is as follows:

  1. Human edits/creates a *.markdown file
  2. *.markdown is converted to *.p.html ('pre-HTML') using Markdown
  3. *.p.html is converted to HTML by fitting a header and footer to it
  4. 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))
    MWIKI = $(subst .markdown,.mediawiki,$(SRC))
    TARG  = $(HTML) $(MWIKI) index.html
    #TARG  = $(HTML) index.html

    # Origin: https://about.twitter.com/resources/buttons#follow

    TWITTER_FOLLOW_BUTTON =                                            \
        "<a href=\"https://twitter.com/MichaiRamakers\" "              \
        "class=\"twitter-follow-button\" data-show-count=\"false\""    \
        "data-show-screen-name=\"false\">"                             \
        "Follow @MichaiRamakers</a><script>!function(d,s,id)"          \
        "{var js,fjs=d.getElementsByTagName(s)[0],"                    \
        "p=/^http:/.test(d.location)?'http':'https';"                  \
        "if(!d.getElementById(id)){js=d.createElement(s);"             \
        "js.id=id;js.src=p+'://platform.twitter.com/widgets.js';"      \
        "fjs.parentNode.insertBefore(js,fjs);}}(document, 'script',"   \

    TWITTER_SHARE_BUTTON =                                                        \
        "<a href=\"https://twitter.com/share\" class=\"twitter-share-button\""    \
        "data-via=\"MichaiRamakers\">Tweet</a><script>!function(d,s,id)"          \
        "{var js,fjs=d.getElementsByTagName(s)[0],p=/^http:/.test(d.location)?"   \
        "'http':'https';if(!d.getElementById(id)){js=d.createElement(s);"         \
        "js.id=id;js.src=p+'://platform.twitter.com/widgets.js';"                 \
        "fjs.parentNode.insertBefore(js,fjs);}}(document, 'script',"              \

    ifeq ($(shell uname),Linux)
    #   MARKDOWN = markdown
        MARKDOWN = multimarkdown
        MARKDOWN = Markdown

    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) $< > $@

    %.mediawiki: %.markdown
        sed '/{{TOC}}/d' $< | pandoc -f markdown_strict -t mediawiki -o $@

    .INTERMEDIATE: header.html footer.html 

        echo                                                       \
            '<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN">'   \
            '<html><head><link rel="stylesheet" href="css.css">'   \
            "<title>___TITLE___</title>"                           \
            '</head><body>'                                        \
            '<a href="http://mircad.nl/">'                         \
            '<img class="logo" src="logo.png" alt="[MiRCAD]"/>'    \
            '</a><br/>'                                            \
            '[<a href="index.html">index</a>] '                    \
            '[<a href="home.html">home</a>] '                      \
            '<br/>'                                                \
            '<hr/>'                                                \
            $(TWITTER_SHARE_BUTTON)                                > $@

        echo                                              \
            '<h6><i><p align="right">'                    \
            $(TWITTER_FOLLOW_BUTTON)                      \
            '</p><hr/><p align="right">'                  \
            'Delivered to you by Vim, GNU Make,'          \
            'Markdown, bozohttpd, NetBSD, and 1 human.'   \
            '</br/>'                                      \
            '</p></i></h6></body></html>'                 > $@

    .DELETE_ON_ERROR .INTERMEDIATE: index.markdown

    index.markdown: $(HTML)
        printf '# Alphabetical page-list\n\n' > $@
        ls $(SRC)                                              \
            | sed 's@ *\(.*\).markdown.*@-   [\1](\1.html)@'   \
            | sort -f                                          >> $@

        -rm $(TARG)

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.

Delivered to you by Vim, GNU Make, MultiMarkdown, bozohttpd, NetBSD, and 1 human.