Installation

The TiddlyWiki server is a Node.js application. You will need to have npm installed before you can install TiddlyWiki.

Install TiddlyWiki via:

npm install --global tiddlywiki

This will likely need to be done via an administrator account.

Basic Operation

Each Tiddler is a separate file on disk in either Markdown or WikiText format. The node server will pull it all together into a single system for editing.

The server.sh script will start the Node server.

The build.sh script will produce a single self-contained HTML file that is what the students will see.

Hosting is via GitBucket — build the HTML file, push everything to GitBucket, and share the link to the 'raw' version of HTML file with the students.

Publish vs Edit Mode

The deployed HTML file is effectively read-only, so we don't want students to think that they can use the editing features to add their own notes to this file since anything they add will not be saved unless they download the modified HTML file. As such, we disable the editing features in the deployed version.

The modes can be toggled via the #edit Tiddler. Use the Advanced Search ⇒ System to search for #edit, then click the $:/ou/editing/#edit link. There are buttons for toggling the modes in that Tiddler.

Folder Structure

The primary content goes in the tiddlers/content folder. Anything in this folder that TiddlyWiki recognises will become part of the document. You have full control over the path structure — TiddlyWiki will recursively scan everything in this folder. It makes sense to match the file system path structure with the paths structure in the Tiddler titles (although this is not necessary).

One annoyance with the Node server is that every time you edit a Tiddler, it is moved into the tiddlers/content folder. Before building/deploying you should move everything back into its correct location.

Workflow

Get an initial copy of the repository via a Git clone.

Editing

1. Git pull to make sure have have the latest copy (there may be other people working on the document).

2. Start the Node server via the server.sh script.

3. Search for #edit in Advanced Search ⇒ System to find the $:/ou/editing/#edit. Click the link for that Tiddler to open it.

4. Click the Edit Mode to enable the editing features.

5. Edit the document.

Cheatsheet

There is a cheatsheet reference section in the document that has sections for Markdown and useful macros that can be used. You can get to it via the sidebar More ⇒ Cheatsheet. You need to bet in 'edit' mode to see the 'More' tab in the sidebar.

Publishing

1. Open the #edit Tiddler (there is button in the More sidebar that takes you there), and click Publish Mode to disable the editing buttons.

2. Switch back to the light theme if you have been using the dark theme.

3. Stop the Node server ( Ctrl + c ).

4. Build the HTML file with the build.sh script.

5. Commit and push.

6. Check the version on GitBucket to make sure it contains what you expect. Things to check:

   • Are the edit buttons hidden?

   • Is the light theme being used?

   • Is there any crap in the 'Contents' side bar — these are files that TiddlyWiki doesn't recognise, and probably shouldn't be in the tiddlers/contents folder.

Gotchas

Make sure that you are working on the correct version — it is easy to accidentally work on the read-only version on GitBucket, rather than the version running on the Node server. Check the URL in the browser's location bar before editing anything (the Node version will be 127.0.0.1).