Being able to browse by tags and links is nice. For many use cases that's enough, and indeed it's often better not to tie ourselves into trying to organize all of our notes into a single hierarchy. Sometimes, though, we have a cluster of notes about a particular topic that naturally forms into a hierarchy – for example, an individual project – and being able to view that hierarchy in a table of contents is a valuable way to see an overview of the topic. And certain applications of TiddlyWiki, such as writing a book, really do benefit from a hierarchy covering the entire contents of the wiki.
Important disclaimer: you can only use the built-in table-of-contents functionality with a hierarchy built out of tags, not one built out of fields or links. Fortunately, that's how we chose to do it in our example wiki. The TiddlyWiki Locator plugin is useful if you need more powerful tools, including navigating hierarchies built of fields or links.
Creating structure tiddlers
Let's look at how we can create a table of contents for our onboarding project. We'll begin by creating some basic structure underneath it. Let's say the project is broadly divided into three parts. We'll need to create a tiddler for each of these parts to define the hierarchy:
- HR stuff about the company and government-mandated training –
OnboardingHr - Introductions and social events/notes –
OnboardingPeople - Training for the position –
OnboardingTraining
Go ahead and create those three tiddlers and tag them OnboardingProcess, thus marking them as direct members of the idea OnboardingProcess. Rather than create new tiddlers and tag them manually, here's a handy timesaver: click the more drop-down on the OnboardingProcess tiddler and choose New here. A new tiddler will open, already tagged OnboardingProcess.
There's no need to put any content in the tiddlers for the time being. If we later find we need to give an overview of that part of the onboarding process, or we have information about it that doesn't seem to deserve its own tiddler, we can add it at that time.
Creating the table of contents
The most basic table of contents is created with the wikitext <<toc "Root">>, where Root is the name of the tiddler you want the table of contents to start at. In our case, this will be:
<<toc "OnboardingProcess">>The funny double angle brackets <<>> introduce a reference to a variable. You don't need to worry about what that is for now; we'll learn a whole lot more about them in Chapter 4.
Go ahead and edit the OnboardingProcess tiddler and drop that snippet in. You'll see that a numbered list of the items tagged OnboardingProcess shows up. But oops, the EmployeeProfileSetupMeeting probably doesn't belong at the top level now that we've added our three subparts of the onboarding project. It makes more sense to have it in OnboardingHr, agreed? Let's open the EmployeeProfileSetupMeeting, remove the OnboardingProcess tag, and add the OnboardingHr tag. If we save it and go back up to OnboardingProcess now, we'll see that now it's indented into a second level.
This is great, but what happens if we have a project tiddler that has dozens of tiddlers in it? This list is going to get long really fast! Try changing the code to this:
<<toc-expandable "OnboardingProcess">>You'll see that only the topmost level of the hierarchy is displayed now, and little chevrons appear next to the items. If you click the chevron by OnboardingHr, it turns to point down and the next level shows up.
But wait…why are there chevrons next to OnboardingPeople and OnboardingTraining? Those don't have any content yet! If you click on one of them, you'll see that the chevron changes direction but nothing else happens. That's irritating, isn't it?
All right, third time's the charm:
<<toc-selective-expandable "OnboardingProcess">>Ah, that's better! (If only it were so easy to solve annoying behavior in all of tech.) Now the chevrons only show up by the elements that can actually be expanded.
Straight quotes and curly quotes
There are many types of quotation marks available on computers. The most common are "straight quotes" (available on most keyboards), where the opening and closing marks are identical, and “curly quotes,” where there are two different characters that point inward towards the quoted text. Curly quotes are preferable in text – you would never see straight quotes in a published book, for instance. But curly quotes aren't valid in most computer code, including wikitext.
In the examples above, for instance, if we had instead written:
<<toc-expandable “OnboardingProcess”>>...this would not work correctly.
If you just type the quotation mark key on your keyboard when writing wikitext directly in TiddlyWiki, you'll usually be OK. However, if you write wikitext in another app, like Microsoft Word, and then try to paste it into TiddlyWiki, it's possible that app will automatically convert your straight quotes to curly quotes, and then your wikitext will mysteriously not work. In this case, you'll need to backspace the quotation marks and add new straight ones when you paste.
A similar problem occurs on some Mac and iOS devices, which may be configured to automatically convert straight quotes to curly quotes in text entry fields across all applications, potentially including your web browser. If you find this happening on the Mac, you can turn it off by unchecking Edit > Substitutions > Smart Quotes on your menu bar.
Ordering items
You might be wondering whether we can change the order of the items under each branch of the table of contents. TiddlyWiki has a general mechanism for ordering the tiddlers of a particular tag, and this order, once established, will be respected in many places, including tables of contents. We'll learn about this mechanism in the next section, Ordering Tiddlers.
Exercises
Make up and create another meeting under one of the other subcategories, either OnboardingPeople or OnboardingTraining. Be sure to include at least one participant and a time as we did when we set up the initial meeting. Check to make sure that it shows up in the table of contents.
There are two more (rarely used) kinds of tables of contents, toc-tabbed-internal-nav and toc-tabbed-external-nav. Try these out. Can you figure out the difference between them?
Having the word Onboarding appear repeatedly in a table of contents within the OnboardingProcess tiddler seems a little silly, especially when those top-level tiddlers don't have any useful content of their own. We'd really like to be able to give them names that make sense in this context, without having to make the title of the tiddler something vague like “HR” that would be ambiguous in the context of the entire wiki.
Fortunately for us, the table-of-contents functionality looks for a field called caption and uses that instead of the title if it exists. Add appropriate caption fields to each of the three top-level items displayed in the table of contents to pretty up the list.
Suppose that, during our meeting, Jane gave us some advice about the company that probably shouldn't stray. We might want to put that in a separate tiddler to reduce the chance we accidentally copy and paste it over to someone else who asks what happened at the meeting.
Create such a tiddler with the following text, and make it a child of the EmployeeProfileSetupMeeting, so we'll still be able to keep track of it:
JaneDoe told me, while we were together at the EmployeeProfileSetupMeeting, that I should be very careful about saying the word "fudge" in this office, due to an incident involving Robert at the 2018 Christmas party that nobody wants to talk about.Check the OnboardingProcess table of contents again. Did you get a third level of hierarchy?
Revisit the tiddler you created in the previous exercise.
- Logically, is it a child of that meeting? Or is it a separate idea that just happened to occur during that meeting?
- Would it be better to use a different kind of relationship, like a link?
- Think about the title you chose: does it serve as metacommentary on the idea?