See Flat Files

Install a wiki server on your laptop and observe what files it makes for you. Understand what each file does and how each is updated.

Wiki is at its core an editor. Run wiki on your laptop to edit files there. With no other command line options wiki will add and and modify files in the ~/.wiki directory.


Visit this wiki at localhost:3000. Edit the welcome page and make a new page or two. This will make files which you can discard later. Explore these pages.

ls -l ~/.wiki ls -l ~/.wiki/pages ls -l ~/.wiki/status

# Schema

Wiki expects to serve json pages in files named by their title reduced to a computer friendly slug. A page must be a valid json object. A page has fields for title, story and journal, all of which are optional.

The smallest possible page is an empty object.


Try creating or modifying pages with an ordinary text editor. Notice what goes wrong when various wiki expectations are not met.

Try changing the capitalization of the welcome page.

Try changing the name of the welcome page (harder).

Try creating a new page with just a title of your choosing.

Wiki is tolerant of most things except invalid json. Search online for "json lint" and use that to fix broken pages.

# Sitemap

The wiki server creates a sitemap.json file by scanning pages on startup and occasionally thereafter. If you delete the sitemap the server will recreate it when asked.

The sitemap includes the first paragraph of each page which the client uses for its search.

Try text editing the first paragraph of the welcome page.

The client can see the new text, but not search.

Try deleting ~/.wiki/status/sitemap.json

The client search will see the new text on reload.

Find the sitemaps as stored in the client. Open the inspector, view the javascript console, and examine the wiki neighborhood global.


# Farms

Start a second server on another port and include the farm option for serving multiple virtual sites from one server.

wiki -p 4000 -f

Compare what you find at each of these addresses.

localhost:3000 localhost:4000

These four urls address three different sites, each manufactured on demand. Find these inside ~/.wiki.

With dns wildcards the supply of sites is as limitless as directories on disk.

# Reflection

Wiki is an editor that manages hypertext stored in a simple json format. The server makes these pages discoverable by publishing a searchable sitemap.

The wiki client must be suspicious of all pages it fetches from remote servers. The json format is intrinsically inert but still capable of misleading the client and its user.

The server insulates the federation from local storage decisions. Various servers already store pages through different mechanisms. However, for all but the largest sites flat files are sufficient and convenient.