PBE Games on DriveThruRPG

Wednesday, February 10, 2010

Using TiddlyWiki - Part 1

I've mentioned before that I use TiddlyWiki to store my campaign notes and write this blog. I thought it might be useful to write an article covering the basics of how to use it, along with some of the features I make use of in my campaign notes.

First a brief introduction. If you're not familiar with TiddlyWiki, it's essentially an implementation of a full-featured wiki in a single file. That means you can carry it around on a USB stick or email it with ease. The file contains not only the content you create, but all the tools required to edit and update that content. The exceptions to the one file structure are images and external files, which are treated as external links (more on that in a bit).

Obtaining TiddlyWiki

Getting a copy of the empty file is easy. Simply visit the download page here or here and save locally. Once you have the file downloaded you can move it around using the standard tools provided by your operating system (i.e. drag and drop or copy commands). The basic unit of information in TiddlyWiki is a tiddler, which corresponds to an article in standard wiki-speak. Each tiddler is referenced by a name either written as a WikiWord, or, if you like spaces in your titles, [[Surrounded by Double Square Brackets]]. My personal preference is to use spaces and double square brackets, but either method works.

If you're going to make use of TiddlyWiki, it's probably worth bookmarking the TiddlyWiki wiki site. There's a ton of useful information there. Here's the link: http://tiddlywiki.org/wiki/Main_Page


Now that you have TiddlyWiki in hand, let's do something with it.
  • Create a new folder somewhere in your documents tree, and copy the TiddlyWiki file there. A separate folder isn't necessary, but it'll help keep linked images organized (remember they're not part of the base file).
  • Open the TiddlyWiki file with your web browser. This is probably as simple as double-clicking it, but you may have to use the File/Open menu in your browser. You should see something like the image here.
The important features:
  • Across the top is the backstage bar, tools to deal with plugins and imports. We'll ignore that for now.
  • Below the backstage bar is the title area, defined by two editable tiddlers that allow you to set the name of your wiki.
  • On the left is the MainMenu, an editable sidebar which you can modify to suit your needs.
  • In the center is the main content area. Tiddlers you create/open show up here. Each tiddler has the following features arranged around it:
    • Top right - the tiddler interaction links. These allow you to edit, close or check references on the current tiddler.
    • Right side - the tags box will show any tags that apply to this tiddler. More on tags later.
    • Top left - the tiddler title.
  • On the right is the sidebar, providing access to basic editing and navigation features.
Check out PBE Games on DriveThruRPG

Customize It

Let's do a bit of customization to make this TiddlyWiki ours. Once you're familiar with how things work you can set up a default TiddlyWiki with most of this stuff already done to save time. The default TiddlyWiki configuration automatically opens a tiddler called GettingStarted, and it's a good place to begin. You'll see several links in this tiddler. Note that they're in italics, indicating the content they link to isn't yet defined. These happen to be special shadow tiddlers, meaning the system has a default tiddler it uses if they're not yet defined. Let's change a few things.

Click on SiteTitle to open the empty tiddler, then hit edit, which leaves you with the default tiddler edit window open. It has a main edit box, with a smaller edit box for tags at the bottom (see image). Replace the text with whatever you like. I'm going to use Demo Tiddler. Hit the done button in the tiddler interaction links. Congratulations, you've just edited your first tiddler.

Repeat this process for the SiteSubTitle. I'll use [[RPG dumping ground|http://rpgdump.blogspot.com/]] which is a fancy way of applying a name to a link (more on that later).

Click on the MainMenu link and edit. I'm going to set this up to provide a link to itself, to my content, and label the sections with a couple headers. Here's what I'm going to type (includes some basic markup for headers):

!! Content
[[The Village]]
[[The Dungeon]]
!! Tools
Once you're happy with your edits, hit done in the tiddler interaction links. Note how the left menu has updated. You can click on any of these links to open the associated tiddlers (note that most of them are empty, ready for you to add content).

Click on the DefaultTiddlers link and edit. This tiddler contains a list of tiddlers that are automatically opened when you first open the TiddlyWiki file. The default content is GettingStarted, but I'm going to change this to read:

Last step: Fill in your user name in the box at the bottom of the GettingStarted tiddler. It doesn't really matter if you're the only person writing in this wiki, but it does let you track changes if multiple people use it.

OK, we've done some work, let's insure we save it. Click on the save changes item in the right-hand sidebar or save in the backstage bar at the top of the page. Note that your browser will likely complain bitterly about saving a file locally. I trust the TiddlyWiki site to provide a clean source file, but if you obtain one from elsewhere be careful. To save, check the remember this choice option and hit OK in the warning dialog. TiddlyWiki saved. The final result should look something like this image. The next time you open your TiddlyWiki file, it will look the same, except the empty Introduction tiddler will be open instead of GettingStarted.

The Sidebar

Before I close let me run down the sidebar options quickly. That will let me focus on content next time. Most of these are pretty straightforward, but can be confusing if you're not used to wikis. From the top:
  • Search - This is a simple search box that will find any text you type and automatically open the tiddlers that contain it. Note that searching on something like ''the'' in a big TiddlyWiki can take some time.
  • Close All - Closes all currently open tiddlers. Basically cleanup the display. Tiddlers stay open until you close them so it's possible to have quite a few open.
  • Permaview - Updates your browser URL window with a link to the currently active tiddler.
  • New Tiddler - Opens a fresh tiddler in edit mode, ready for input. You can also create new tiddlers by clicking on any link that names a non-existent tiddler.
  • New Journal - Journals are special tiddlers labeled with the current date and time. Useful if you're writing a diary or session log.
  • Save Changes - Saves the entire TiddlyWiki.
  • Options - Provides access to additional configuration options, including auto-save, backups, and search controls. There's also a link here to AdvancedOptions, which allows you to tweak even more stuff.

Tabbed Window

This section of the sidebar changes dynamically as you add tiddlers to your TiddlyWiki. Here's what the tabs contain:
  • Timeline - A tiddler listing organized by last edit time, newest first. Handy for finding what you just changed.
  • All - An alphabetic listing of every tiddler.
  • Tags - An alphabetic listing of every tag.
  • More - Several tiddler lists that might need attention:
    • Missing - Tiddlers that are linked to, but don't exist.
    • Orphans - Tiddlers that exist but aren't linked to.
    • Shadowed - Tiddlers that have default system values, generally built-in to TiddlyWiki.

OK, that should do it for today. At this point you should have a ready to use TiddlyWiki configured for your own project. In the next article I'll write about:
  • Basic markup - How to do headers, formatted text, lists and links.
  • Tags - How to organize tiddlers with the built in tag system.
  • Transclusion - A handy way to include one tiddler within another.
  • Organization - Some thoughts on organizing your notes.
Stay tuned.

Here's a link to part two.


Tyler said...

Thanks for the walkthrough of TiddlyWiki. It's a tool I keep meaning to use, but find myself falling back on Google Docs because I like leaving my data in the cloud. Next campaign, though, it'll be all tiddler, all the time.

Did you ever run across Uncle Bear's Ten Foot Wiki? It's TiddlyWiki with some modifications to make it a little friendlier to role playing uses. It seems to be back after a brief absence on his website.

Mark Thomas said...

Glad it was useful. One of the nice features of TiddlyWiki is its portability. All you need is a web browser and a USB drive. I see the attraction of google docs, but I really like Wiki-style linking too.

Joe said...

I am curious how you persuaded blogger to use your tiddlywiki layout. I've used tiddlywiki for a long while, but have never figured out how to make it play nice with blogger. Any tips would be greatly appreciated!

Mark Thomas said...

Joe -- I'm a bit confused what you're asking here. I use Tiddlywiki to write blog posts, but I cut/paste the content into a standard Blogger post. Sorry if I gave the impression I was using Tiddlywiki to directly publish to blogger.