## 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 <kbd>Advanced Search</kbd> &Rightarrow; <kbd>System</kbd> 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 &mdash; 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).

1. Start the Node server via the `server.sh` script.

1. Search for `#edit` in <kbd>Advanced Search</kbd> &Rightarrow; <kbd>System</kbd> to find the `$:/ou/editing/#edit`.  Click the link for that Tiddler to open it.

1. Click the <kbd>Edit Mode</kbd> to enable the editing features.

1. 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 <kbd>More</kbd> &Rightarrow; <kbd>Cheatsheet</kbd>.  You need to bet in 'edit' mode to see the 'More' tab in the sidebar.

### Publishing

1. Open the `#edit` Tiddler (there is <kbd><svg height="16pt" class="tc-image-theme-button tc-image-button" viewBox="0 0 128 128"><g fill-rule="evenodd"><path d="M55.854 66.945a122.626 122.626 0 01-3.9-4.819c-11.064-14.548-16.645-6.888-22.96 0-6.315 6.888 1.664 12.47-4.33 17.335-5.993 4.866-5.623 6.552-15.737-2.35-10.115-8.9-10.815-11.351-6.172-16.43 4.644-5.08 8.524 2.918 18.01-6.108 9.485-9.026 1.517-17.026 1.517-17.026S42.03-2.824 68.42.157c26.39 2.982-9.984-3.86-19.031 27.801-3.874 13.556.72 10.362 8.066 16.087 1.707 1.33 6.428 4.732 12.671 9.318-6.129 5.879-11.157 10.669-14.273 13.582zm11.641 12.947c16.013 17.036 37.742 37.726 45.117 40.42 10.432 3.813 15.388-3.141 15.388-14.79 0-7.151-23.83-26.542-43.924-41.769-7.408 7.156-13.376 12.953-16.58 16.139z"></path><path d="M11.069 109.828L46.31 74.587a3.56 3.56 0 115.037-5.032l15.098 15.098a3.56 3.56 0 11-5.032 5.037l-35.24 35.241c-4.171 4.17-10.933 4.17-15.104 0-4.17-4.17-4.17-10.933 0-15.103zM124.344 6.622l5.034 5.034-7.49 12.524-7.613 2.58L61.413 79.62l-5.034-5.034 52.861-52.862 2.58-7.614 12.524-7.49z"></path></g></svg></kbd> button in the <kbd>More</kbd> sidebar that takes you there), and click <kbd>Publish Mode</kbd> to disable the editing buttons.

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

1. Stop the Node server ( <kbd>Ctrl</kbd> + <kbd>c</kbd> ).

1. Build the HTML file with the `build.sh` script.

1. Commit and push.

1. 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 &mdash; 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 &mdash; 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`).