Permalinks allow direct links to individual tiddlers within a TiddlyWiki.

Simple Permalinks

The simplest form of permalink () is a single target tiddler title appended to the base URL with #:

https://tiddlywiki.com/#HelloThere

The tiddler title can contain spaces if required:

https://tiddlywiki.com/#Using TiddlyWiki on Node.js

Note that double square brackets are not required around the target tiddler title; however, if present they are silently removed.

Story Permalinks

The permalink can also specify the story list of tiddlers that should be opened alongside the target tiddler as a TiddlerFilter:

https://tiddlywiki.com/#TiddlerFields:Tiddlers TiddlerTags TiddlerFields ContentType

If the target tiddler isn't present in the story list then it is automatically inserted at the top. This means that the following two examples both target the tiddler Tiddlers within the story sequence Tiddlers, Tags, TiddlerFields:

https://tiddlywiki.com/#Tiddlers:Tags TiddlerFields

https://tiddlywiki.com/#Tiddlers:Tiddlers Tags TiddlerFields

It is also possible to specify a story filter without specifying a target tiddler for navigation:

https://tiddlywiki.com/#:[tag[task]]

About URL encoding

There are technical restrictions on the legal characters in an URL fragment. To allow all tiddler titles to be addressed, illegal characters are subject to a process called "URL encoding" whereby problematic characters are replaced by their numeric code. For example, the space character is replaced with %20.

Both the target tiddler title and the story filter should be URL encoded (but not the separating colon). TiddlyWiki generates properly encoded URLs which can look quite ugly. However, in practice browsers will usually perfectly happily process arbitrary characters in URL fragments. Thus when creating permalinks manually you can choose to ignore URL encoding.

Permalink Behaviour

Two important aspects of TiddlyWiki's behaviour with permalinks can be controlled via options in the control panel Settings tab:

• Whether to automatically update the address bar at each navigation, and if so whether to include the story sequence as well as the target tiddler
• Whether the updates to the address bar should affect browser history. The default is no; when switched to yes you can rewind navigation between tiddlers using the browser back and forward buttons

Note that typing or navigating to a permalink will always cause the permalink to be processed, and tiddlers opened and closed as appropriate.

Technical Details

When TiddlyWiki starts up it processes permalinks according to the following steps; the same steps are repeated if the permalink changes dynamically (this happens in response to the user editing the address bar, for example).

1. If the permalink contains a colon, treat the string before as the target and the string after it as the story filter
2. If the permalink doesn't contain a colon, treat the entire string as the target and mark the story filter as unspecified
3. If the story filter was unspecified and we're in the process of starting up, then set the story filter to the empty string if the target is specified, or to the default tiddlers if the target is unspecified
4. If the story filter was unspecified and we're not starting up, then set the story filter to the current story list
5. Evaluate the story filter as the story list
6. If the target is specified and not present in the story list then add it at the top
7. If the target is specified then navigate to it, otherwise navigate to the first tiddler in the story list