Exploring the TiddlyWiki personal wiki

Little Helper

By Dmitri Popov

Dennis Cox, Fotolia

Sometimes you come across a piece of software that is so simple and useful that you can't understand how you managed without it. TiddlyWiki is one such application. On the face of it, TiddlyWiki looks and behaves like a conventional wiki, but if you dig deeper, you will discover that it is a rather ingenious application.

One of the most powerful things about wikis is that they let you create and edit web pages on the fly. Most Wikis start with a single page; you can add new pages using what are called wiki words (often wiki words are written in camel case like this: WikiWord). When you add a wiki word to the text, the wiki turns it into a link, and once you click the link, the system creates a new page. The beauty of a wiki is that it frees you from the most tedious task: managing your website's structure. Moreover, since most wikis use a simple markup language, they are perfectly suited for casual users with no knowledge of HTML.

Figure 1: TiddlyWiki looks like an ordinary wiki.

What is TiddlyWiki?

What makes TiddlyWiki so unique? Unlike traditional wikis, which are intended for web-based collaboration, TiddlyWiki is a personal tool designed as a single-user application. Most traditional wikis are server-based software written in PHP, Perl, or another scripting language. Some wikis store data in text files; other rely on a database back-end like MySQL. In any case, a typical wiki consists of hundreds of files, which you have to install and run on a server.

The entire TiddlyWiki consists of just one HTML file, which includes CSS and JavaScript codes, and everything you enter in the wiki is stored inside this file. TiddlyWiki also does away with separate pages, and instead it uses what are called tiddlers. Each tiddler is a text fragment that is stored in the wiki file, and you can show and hide it. To understand this concept, imagine a book consisting of one page with an unlimited number of paragraphs (corresponding to tiddlers in TiddlyWiki); you can show and hide paragraphs individually. You can also add new paragraphs, delete and modify existing paragraphs, and shuffle paragraphs as you see it fit. This makes TiddlyWiki a useful tool for managing your text fragments (or using a more fashionable word, microcontent) in a non-linear manner.

There is, however, a tiny fly in the ointment. Due to TiddlyWiki's design, you can't move it to a server and work with it remotely using your browser: in order to save changes in your TiddlyWiki, it must reside on your computer. You can, of course, upload TiddlyWiki to your server and use it in read-only mode. This makes TiddlyWiki better suited for use as a personal local wiki. You can, for example, install it onto a USB key and use it to keep tabs on your notes. There are TiddlyWiki variants that allow you to install and use them on a remote server (for example, TiddlyWikiRemote http://phiffer.org/tiddly/), but since these expanded tools consist of multiple files, and some of them require a database back-end, they tend to defeat the whole idea of TiddlyWiki.

Figure 2: Use the GettingStarted tiddler to customize your TiddlyWiki.

Installing and Using TiddlyWiki

Actually, you don't have to install anything at all. Simply point your browser to http://www.tiddlywiki.com/, and download the latest empty.html file. Rename it to something more meaningful, and your TiddlyWiki is ready to go.

The first thing you might want to do is reconfigure some of the default settings. Open your TiddlyWiki in a browser, and use the GettingStarted section to change your TiddlyWiki's title and customize the main menu and default tiddlers. To change the title, click the SiteTitle link, press the Edit button, and enter the name of your TiddlyWiki into the main text area. Close the section by pressing the Done button, and the new title appears in your wiki's header. In a similar way, adjust other settings, and when you are satisfied with the result, press the Save changes link. Using the Options section, you can tweak the wiki's more advanced settings. Tick the SaveBackups check box if you want TiddlyWiki to create a backup file each time you save the changes. If you use TiddlyWiki on an older machine, you might want to disable the EnableAnimations option, and if you want to perform searches using regular expressions, tick RegExpSearch. To tweak TiddlyWiki even further, click the AdvancedOptions link.

Once you have configured your TiddlyWiki, you are ready to create your first tiddler. To add a new tiddler, simply click the New tiddler link. Like traditional wikis, TiddlyWiki uses special markup for formatting the contents of the tiddler. For example, to format a text fragment as bold, use the // markup like this: //this is bold text//. To add a subheading, put ! in the beginning of the line: his is a subheader. TiddlyWiki also supports more advanced formatting, like strikeout, subscript, superscript, and bold. You can also highlight text segments using the following code: @@color(red):Text highlighted in red@@.

Want to add a list? No problem: TiddlyWiki supports both numbered and unnumbered lists. Here is an example of an unnumbered list (you can see the result of this code in Figure 3):

*Level One
**Level A
***Level I
***Level II
**Level B
*Level Two
*Level Three

Tables are also supported; using simple formatting, you can create rather complex tables in TiddlyWiki. The following code produces a simple table, as pictured in Figure 4:

|!Table Heading 1 | !Table Hading 2 | !Table Hading 3 |
|Row 1 Column 1 | Row 1 Column 2 | Row 1 Column 3 |
|Row 2 Column 1 | Row 2 Column 2 | Row 2 Column 3 |

You can also include images in your tiddler using a simple code like this: [img[alternate text|filename or URL][link]]. Keep in mind, however, that linking to external files makes TiddlyWiki less portable. TiddlyWiki also supports WikiWords, and it converts all camel case words into links to other tiddlers. For example, the word FurtherReading in the sentence "To learn more, go to the FurtherReading section" is automatically converted into a link to a tiddler with the same name. If you don't want a camel case word to appear as a WikiWord, place a tilde in front of it like this: ~NotAWikiWord.

Before you close and save your first tiddler, it is a good idea to add some tags to it, which will allow you to quickly locate the tiddler using TiddlyWiki's Tags tab. You can add multiple tags to each tiddler.

Figure 3: An example of a TiddlyWiki list.

Figure 4: An example of a TiddlyWiki table.

Using Macros and Plugins

TiddlyWiki includes several default macros that allow you to add some nifty features to your wiki; for example the ToolbarMacro adds toolbar buttons that appear when the mouse hovers over a tiddler. To add, for example, Close, Edit, and Delete buttons to a tiddler, add the following code to its body: <<toolbar -closeTiddler +editTiddler deleteTiddler>>.

Figure 5: To install a plugin, you have to copy it from the source and paste it into a new tiddler.

Commands that are preceded by a + are executed when you press the Ctrl+Enter keyboard shortcut or when you double-click the tiddler. Commands preceded by a - are executed when you press the Esc key. The list of TiddlyWiki's ToolbarMacro commands is available at http://www.tiddlywiki.com/#tag:commands.

Using third-party plugins, you can extend TiddlyWiki's functionality beyond the functions provided by the default macros. Although installing plugins in TiddlyWiki consists of several steps, the entire procedure is straightforward enough even for non-technical users. Let's say you want to install the excellent TiddlerStatsPlugin that provides statistics on how many tiddlers there are in your TiddlyWiki, how big they are, and other useful info. Point your browser to http://thepettersons.org/PaulsNotepad.html#TiddlerStats. Double-click the tiddler or press the view button. Copy the entire text of the tiddler, open your TiddlyWiki in a new browser window, and create a new tiddler. Paste the contents of the clipboard into the tiddler body, name the title TiddlerStatsPlugin, add the tag systemConfig, and then press Done.

Click the Save changes link and reload your TiddlyWiki into the browser to enable the plugin. To view the statistics, add the <<tiddlerStats>> code to a tiddler. If you want to check out other TiddlyWikis plugins, http://del.icio.us/tag/tiddlywikiplugin is a good place to start.

Final Word

There is much more to TiddlyWiki. If you want to get the most out of this ingenious wiki, make sure to take a look at TiddlyWikiTutorial, which you will find at: http://www.blogjones.com/TiddlyWikiTutorial.html