Wikification, in TiddlyWiki, is the process of taking wikitext and turning it into pure HTML that a browser can read directly (or, occasionally, into plain text or some other format). This includes processing markup like //italics//, rendering widgets, invoking macros, transcluding other tiddlers, and so on.

Wikification can be understood as a sort of preprocessing or pre-rendering: first TiddlyWiki renders the wikitext into HTML, then your browser renders the HTML on your screen.

When wikification happens

Obviously, processing and formatting wikitext is one of the most essential functions of TiddlyWiki. It happens anytime a tiddler is displayed. However, just because you put some wikitext somewhere in TiddlyWiki does not guarantee it will be wikified.

In general, anytime a chunk of wikitext ends up in the body of a tiddler that is being displayed, TiddlyWiki tries to wikify it. The chunk might be the entire text of the tiddler or the result of a single field or variable transclusion or macro call. (As we discussed in Text Substitution, it will never be composed of the result of several of these things next to each other, or the result of one of these things plus some raw text in the body of the main tiddler: the result of each transclusion is a separate chunk.) If the result of wikifying one of these things still contains wikifiable wikitext – for instance, the result of wikifying the {{tiddler!!field}} transclusion syntax is some wikitext contained in the field field – TiddlyWiki will try to wikify that as well. It will repeat this step until there is no more unwikified wikitext, or until it detects that it has gotten stuck in an infinite loop (recall Ex:SelfTransclusion).

However, there is one huge exception: when you use a transclusion (whether of a field or a macro/variable) as a parameter to an HTML or widget attribute, the result of this transclusion is not wikified. In other words, TiddlyWiki doesn't attempt to repeatedly wikify the result of the initial transclusion like it does with body text; it does it exactly once and then stops.

This will become more clear with an example:

<$set name="testVar1" value="XYZ">
<$set name="testVar2" value="<<testVar1>>">
  <<testVar2>>
</$set>
</$set>

As you can see, XYZ is rendered by this snippet. Let's follow along with TiddlyWiki to see why:

1. In the first $set widget, the variable testVar1 gets set to the text XYZ.
2. In the second $set widget, the variable testVar2 gets set to the text <<testVar1>>.
3. The variable reference <<testVar2>> is used directly within the body of the tiddler. When rendering the tiddler, TiddlyWiki comes to it and looks up the value of the variable testVar2; it finds <<testVar1>>.
4. <<testVar1>> is a new chunk of wikitext that can be further processed, so TiddlyWiki wikifies that as well. This time that process substitutes the value of the variable testVar1, yielding XYZ.
5. At this point, there is nothing left to do with the text XYZ, since it is already plain text with no wikitext syntax, so TiddlyWiki shows XYZ on the screen and moves on to the rest of the tiddler.

However, if we make a minor change so that testVar2 is the attribute of a widget…

<$set name="testVar1" value="XYZ">
<$set name="testVar2" value="<<testVar1>>">
  <$text text=<<testVar2>>/>
</$set>
</$set>

…now the literal text <<testVar1>> prints out:

1. In the first $set widget, the variable testVar1 gets set to the text XYZ.
2. In the second $set widget, the variable testVar2 gets set to the text <<testVar1>>.
3. The macro substitution <<testVar2>> is used as an HTML attribute. When rendering the tiddler, TiddlyWiki comes to a variable substitution and looks up the value of the variable testVar2; it finds <<testVar1>>.
4. Because this is an HTML attribute, TiddlyWiki does not attempt to wikify the result, <<testVar1>>, again; instead, it passes it directly to the $text widget.
5. The $text widget sees that it's been asked to display the text <<testVar1>>, so it does so.

You might initially think this has something to do with the $text widget in particular, since that widget's usual use is to inhibit wikification or formatting, but that isn't the case; it applies to any widget or HTML tag, as we'll see in a moment.

Manual wikification

That was a good example for demonstrating what TiddlyWiki does and does not wikify, but it didn't do anything useful, so at this point it may be hard to see why the lack of wikified attributes would be a concern. As a more practical example, let's suppose that we're creating a wiki about animals, and we want to include a picture of each animal in its corresponding tiddler. We might add an imageurl field to each tiddler to store the URL of an appropriate image. We then want to create a template, called TiddlerImage, that displays the image found in the imageurl field of the current tiddler.

Let's try this in our sample wiki. We can start the TiddlerImage tiddler with the HTML syntax for an image:

<img src={{!!imageurl}}>

Now, if we populate the imageurl field on some tiddler with a URL and include the template transclusion {{||TiddlerImage}}, the image will appear. If you don't have an image URL handy, you can use this picture of a cat: https://upload.wikimedia.org/wikipedia/commons/b/bb/Kittyply_edit1.jpg?download.

However, what if you want to keep part of the URL in another tiddler? In the above URL, perhaps we are using a lot of images from Wikimedia Commons in our wiki, and we want to store the base URL https://upload.wikimedia.org/wikipedia/commons in a tiddler called WikimediaCommonsUrl. Then in the imageurl we could just use: {{WikimediaCommonsUrl}}/b/bb/Kittyply_edit1.jpg?download. This way, if Wikimedia Commons ever changes its web address (unlikely, to be sure!), we can quickly update all our links.

If you try this, though, you'll find that the image doesn't appear; instead a “broken image” icon will appear. Since it might be hard to see exactly why it doesn't work, try selecting the image with your browser's element inspector (if you've forgotten how that works, review When Things Go Wrong). After a close look at the HTML, the problem should be obvious: the src attribute literally begins with {{WikimediaCommonsUrl}}, it hasn't been replaced with the contents of that tiddler. Since that isn't a valid URL of an image, no image is displayed.

How, then, can we get the transclusion to expand? What we need is a way to wikify the wikitext while it's still in a variable, rather than waiting until it's actually rendered as part of a tiddler (because it never will be rendered as part of a tiddler the way we're using it). The appropriately named $wikify widget provides this capability. We can modify our example to use this widget as follows:

<$wikify name=wikifiedImageUrl text={{!!imageurl}}>
    <img src=<<wikifiedImageUrl>>>
</$wikify>

If you try again using this snippet, you'll find that the image appears as expected.

The $wikify widget has several other options, such as the format to parse the text into (plain text, HTML, a JSON parse tree, and so on). You can read about them in the documentation on https://tiddlywiki.com.

Parameter and variable references in macros require wikification

It is worth pointing out that both <<variable references>> and <<__macro-parameter-as-variable references__>> are not evaluated until they are wikified, which means that such references do not work at all when their containing macro is used as the value of an HTML or widget attribute:

\define myText(text) Text: <<__text__>>

* ''OK:'' <<myText "test text">>
* ''Bad:'' <$text text=<<myText "test text">>>

In practice, this means that text substitution must be used when the macro is being used as the value of an attribute.

Exercises

\define wikipediaLink(articleName)
https://en.wikipedia.org/wiki/$articleName$
\end

<$macrocall $name="wikipediaLink" articleName={{!!wikipedia-article}}/>

Takeaways