Wiki

The page about the wiki itself!

A complex system that works is invariably found to have evolved from a simple system that worked. The inverse proposition also appears to be true: A complex system designed from scratch never works and cannot be made to work. You have to start over, beginning with a working simple system.

- John Gall

Objective

How it works

A builder.coffee script is run that reads in .md files and writes out .html files.

There is a very simple template for all the pages.

There is a CSS file that is included on all pages.

ComingSoon:tm: A .js file that is included on all pages.

The output is static html, css, and js. No webserver, no database, they live in S3 or any other static hosting environment.

Directory Structure

pages/
  index.md
  wiki.md
  ...
source/
  script.coffee
  style.styl
  template.html
builder.coffee
favicon.png
index.html (compiled)
main.css (compiled)
wiki.html (compiled)

All the pages live in pages/. The Markdown files are converted into .html files that live at the top level. The html generated from the markdown files is inserted into the html template. The title for the page is the first line of the markdown file.

main.js is compiled from source/script.coffee. Let's try and just use one file for simplicity's sake. 500 lines tops. We may load some other files later for fancier interactive pages, but the core should be quite small.

main.css is compiled from source/style.styl. We're not savages.

favicon.png is a png that can be edited from the default pixel editor that ships with ZineOS.

Philosophy

Keep it simple

Example: we want to have an html template that includes the basic page header, footer, layout, shared resources.

Possible solution: find a templating library that is simple enough and featureful enough to meet our needs. Consider how large it is, how well it will integrate into ZineOS, how easy it is to call from JS.

Selected solution: write a two line function that does a good enough job for today and possibly for a long time. It has significant constraints, but is surprisingly robust. It took only 15 minutes to implement and is easy to understand where it succeeds and fails. When we outgrow it, it should be easy to replace.

simpleTemplate = (template, data) ->
  template.replace /\$[a-z]+/g, (match) ->
    data[match.substr(1)] or ""

Example: we want to render markdown into html.

Selected solution: Just use marked :P. Markdown is a nightmare. If we want to extend it we can add a pre or post processing step. The extensions will be kept to a minimum. Anyway, how can we judge before we know what they are?

Wiki every day

The only way to discover what is important is through consistent usage. Write a new page every day. Build the wiki every day. If something is harder than it needs to be it will show itself through usage. There will be simple ideas that appear through usage. It is much harder to imagine what is needed than to live and feel what is needed. The human mind will go to any length to avoid facing reality.

Only add features after they are sorely needed

Do we need a navigation bar? A list of recent articles? Not before we've written at least three or four articles.