PBE Games on DriveThruRPG

Thursday, February 11, 2010

Using TiddlyWiki - Part 2

In the last article in this series, we talked about obtaining and setting up TiddlyWiki for basic use. In this article I'm going to focus on using it effectively. I'm not going to go into vast detail here, first because TiddlyWiki isn't that complicated (though there are quite a few plugins available that add features), and second because I believe in the KISS principle. Let's start with the basics, creating content.

Adding Content

Adding content to TiddlyWiki is as simple as hitting the new tiddler link on the right sidebar and typing text. You'll probably want to read a bit about markup and tagging before you really dive in, but you don't have to. The only requirement for a tiddler is that it have a name. See how hard that was?

Basic Markup

The last article already talked about how to edit a tiddler. TiddlyWiki markup is a way to add headers, lists, text formatting, links and images to your tiddler. Here are some of the most commonly used markup elements:

Basic Text - Just type. Any text without markup is treated as plain text. The edit box automatically word wraps. Use the enter key to denote the end of a paragraph.

Headers - Headers are denoted by one or more ! characters at the beginning of a line, followed by the header text. More ! are less important headers. A typical header:

! Section 1
!! Section 1.1 
!! Section 1.2
!!! Section 1.2.1

Lists - List entries begin with one or more * characters for bullet lists or one or more # characters for numbered lists. Multiple markers increase the indent level. Each list entry should start at the beginning of a line. Example:

* Bullet
** Nested bullet
** Another nested bullet
# Numbered
## Nested numbered
# Numbered again

Text formatting - Most inline text formatting is done with two marks on either side of the text receiving the formatting.
  • Bold - double single-quotes around the text.
  • Italic - double forward slashes around the text.
  • Bold Italic - double single-quotes around double forward slashes around the text.
  • Underline - double under-bar characters around the text.
Links - There are two types of links:
  • Internal link - Either the WikiWord name of the tiddler or the tiddler surrounded by double square brackets creates a link to the tiddler.
  • External link - An URL will automatically be translated to a link. If you want to use text and link to a URL, you can do it with double square brackets


    [[Some Text|http://rpgdump.blogspot.com]]
    creates a link called Some Text pointing to my blog.
Images - The basic image links are [img[Image Name]] or [img[Some Text|Image Name]] where:
  • Some Text - the optional tooltip for the image when the mouse is over it.
  • Image Name - the path to the file.
A bit more on images: If you place any images in the same folder as your TiddlyWiki, you can simply refer to them by name (no path required). You can also use a URL if the image is hosted elsewhere.

If you want to delve further into markup (and there's more available), check out the TiddlyWiki wiki, specifically the markup page.

Tags

Tags are labels you can apply to tiddlers as a means of organizing your information. With a little care they can provide very quick reference to both individual and groups of related tiddlers. Tags themselves are also tiddlers, so you can describe what the tag means in its own tiddler.

To tag a tiddler, simply place a label in the tag edit box at the bottom of the edit window. Tags can be single words or multiple words surrounded by double square brackets. My personal convention is to use all lower case letters for tags to avoid name clashes with content tiddlers.

The tags you use should fit the information you're trying to mark up. Using my recent Moria game as an example I have the following tags laid out:
  • Creatures - One tag per general creature type, for example: goblin, orc, troll. These tags get applied to the stat blocks and descriptive text for the creature, along with any  encounters that include them or locations inhabited by them.
  • Locations - One tag per broad location. For outdoor stuff, I use regions, towns or encounter locations. For dungeons, I use level names. This allows me to quickly find the relevant information for any specific locale.
  • Stats - A singular tag used to mark any stat block. It's a handy way to find any specific stat block on the fly.
  • Encounter - One tag per broad location. These match up to the location tags mentioned earlier, but are applied only to encounters. In Moria for example I have eregion encounter, hollin encounter, and moria encounter defined.
  • Other - I have a bunch of other tags, like item to mark important or unique items, rules to mark house rules or special mechanics, and magic to mark any unique magic effects or powers I might need for reference.
Check out PBE Games on DriveThruRPG

Transclusion

What? Yeah it's kind of a silly word. Transclusion is including one document inside another without cut/paste. It's a great feature supported by most wikis including TiddlyWiki. Here's how to do it:
<<tiddler [[Some Tiddler]]>> 
That's it. What this does is automatically put the contents of Some Tiddler inline in the new document. Any updates done to the transcluded tiddler are automatically updated anywhere it appears.

One of the best uses of this is to include stat blocks in an encounter tiddler. Simply transclude each stat block and they'll automatically be appended to the encounter text.

Organization

That pretty much covers the basics of how to use TiddlyWiki. There are a few best practices guidelines to keep in mind if you decide to use this tool.

Consistent Naming - Wikis are picky about exact names and upper and lower case. Be consistent with your naming and it'll help avoid extra work. Here are the conventions I use:
  • Tiddlers - Capitalized as titles, always surrounded in double square brackets when referenced. This is the most readable way I've found to name tiddlers.
  • Prefixes - I prefix all encounter tiddlers with Encounter: and all stat blocks with Stats:. It allows me to quickly spot these crucial elements.
  • Tags - All lower case, single word if possible, but clarity of grouping is more important than using a single word.

Save often and do backups - I have never experienced any problems with a TiddlyWiki, and I've used them for some pretty large projects. Prudence always wins though, and could save you a load of work if something goes wrong.

One thing, one tiddler - Keep this in mind when preparing content. Transclusion makes it easy to concatenate multiple tiddlers into a summary. It's more difficult to divide a huge mess of text into individual pieces. I generally use the following types of tiddlers:
  • Overviews - a top level summary of a major location or group.
  • Locales - individual locations within a region. In dungeons these are room by room. In towns they're business by business or location by location. Outdoors I stick with natural geographic areas.
  • Stat blocks - detailed information on specific creatures, spells or items, one thing per tiddler.
  • Encounters - locale plus opponents (often including transcluded information). Basically everything needed to run the encounter.
Link always - If you're referring to something in your text that you've already defined, link to the other tiddler. I generally do this with the first instance of a linkable word in a tiddler (i.e. the first mention of Goblins in an encounter gets a link to the Goblins summary tiddler). If you haven't defined the target tiddler yet it will show up in the Missing list on the sidebar. The real power of TiddlyWiki is being able to access related information quickly and easily.

OK, by now you're either sold or you're running screaming from the room. Hopefully the former. I hope this pair of articles has provided some insight into using TiddlyWiki for your own campaign notes. I'm happy to answer any questions that I may have left unanswered.

9 comments:

Unknown said...

Another great article! I had no idea about the Transclusion feature. It would have definitely cut down on unneccessary repetition in my Tiddly Wiki.

Mark Thomas said...

Transclusion is what really makes wiki shine for me. When building encounters it really lets me focus on the encounter itself. Stats are almost an afterthought, since adding them is essentially a one line per foe-type exercise.

Norman J. Harman Jr. said...

Transclusion was totally new to me and has caught my pants on fire.

Keith S said...

Thanks Mark, great article on a great tool.

Mark Thomas said...

Glad people found it useful! Thanks for the positive feedback!

Nope said...

Hey, thanks for writing this up! My internet connection is crap, and I have been having organizational issues with using one note as my digital notebook so this is a great option.

Also for google chrome users

http://tiddlywiki.org/wiki/Chrome

in case you are having troubles with saving your file, head over here and pick up the tiddly saver.

Mark Thomas said...

Mike -- glad it was helpful. TiddlyWiki should be just what you need. :)

Anonymous said...

Where is part 1?

Mark Thomas said...

Oops! I just added a link to Part I at the top of the article. You can also find it here:

http://rpgdump.blogspot.com/2010/02/using-tiddlywiki-part-1.html