created: 20140502213500000
modified: 20160622111355787
tags: Features Concepts
title: PermaLinks
type: text/vnd.tiddlywiki

Permalinks allow direct links to individual tiddlers within a TiddlyWiki.

! Simple Permalinks

The simplest form of permalink ({{$:/core/images/permalink-button}}) 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|Filters]]:

[[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:

<a href="https://tiddlywiki.com/#:[tags[task]]" rel="noopener noreferrer">~https://tiddlywiki.com/#:[tags[task]]</a>

! 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|$:/ControlPanel]] {{$:/core/images/options-button}} ''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).

# If the permalink contains a colon, treat the string before as the ''target'' and the string after it as the ''story filter''
# If the permalink doesn't contain a colon, treat the entire string as the ''target'' and mark the ''story filter'' as //unspecified//
# 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
# If the ''story filter'' was unspecified and we're not starting up, then set the ''story filter'' to the current story list
# Evaluate the ''story filter'' as the ''story list''
# If the ''target'' is specified and not present in the ''story list'' then add it at the top
# If the ''target'' is specified then navigate to it, otherwise navigate to the first tiddler in the ''story list''