TiddlyWiki as a Static Site Generator: Introduction

Posted in How-to

by digitalap3 on Wednesday 16th September 2020

  • Intro
  • Additional Posts to come

Introduction to TiddlyWiki

This first post will be an overview of what I think TiddlyWiki is and an attempt to describe its basic structure as I understand it and more importantly in the way that pertains to the posts explaining how I made and how to use and tweak this static site generator. Those posts will not be this simplistic.

Please note I am not anything close to an expert on TiddlyWiki and these are concepts I am trying to gain a deeper understanding of myself. The opinions below are mine alone and not necessarily those of Jeremy Ruston, the creator of TiddlyWiki, or the many many brilliant folks that work on it. There is ample discussion of what TiddlyWiki is in a variety of places.

TiddlyWiki is a platform for creating and manipulating documents and an application to create and manipulate documents and their contents. For example, you can do as I have over the last many years and just download the core empty wiki and fill it with linked pieces of text that you can easily reference through lists or the search function. That is in essence all my knowledge wiki is. Or on the application side you can use the functions 'inside' TiddlyWiki along with its NodeJS server to create an application like my static site generator that renders documents in a static page blog format. There are a huge number of such applications that seek to fill a need like making research easier and more organized, such as Stroll a Roam-like note-taking tool and TiddlyRemember which integrates with the flash card generator Anki. There are also a huge amount of plugins to help with any use case like Todo lists, project management, etc. and I do mean etc. etc.!

The basic unit of TiddlyWiki is the tiddler

At its core then TiddlyWiki is a wiki engine in that it consists of many parts, called tiddlers, that reference each other in a loose structure that emerges as documents and media are added and connected, forming more complex and wider relationships. It consists of small, inter-related components that can be manipulated and combined so that information can be stored and presented in many ways. This definition leaves out the traditional understanding of a wiki as primarily something that a community of users contributes to, though the idea of its structure is the same.

In addition to being a collection of media and documents, TiddlyWiki contains methods of creating and manipulating the information in those parts far beyond simple linking or referencing, such as the ability to perform about any operation (a link to some of the filter operations in Tiddlywiki) allowed in simple scripting and programming languages from string manipulation to incrementals. With the addition of plugins those powers expand greatly.

Stick with me here I'm getting back to basics!

To reiterate, the basic building block of TiddlyWiki is a tiddler. A tiddler is the basic unit of information storage inside a TiddlyWiki. Each 'box' you see on the TiddlyWiki website is a tiddler and many of them are constructed from other tiddlers.

A tiddler can further be broken down into a collection of fields. And a field can then be broken down into a key and a value.

TiddlyWiki --> made up of tiddlers --> made up of fields --> made up of a key and a value

So to reverse and explain this structure with an example: every tiddler has a key called title. The value for title is unique - it is in essence what creates the tiddler as an object that exists on its own. The combination of key/ title and value/ tiddler-title make up the field.

The field is identified or has the name of its key since this does not change from tiddler to tiddler. In other words every tiddler has a key called title so we call that field the "title field" and its value is the unique title of the tiddler. Like every person has a key called name and the value of their "name field" is their personal name. Every tiddler is built with certain default, or required, fields, including the date created, date modified, text (the content), etc. In fact you can use the down caret on a tiddler on the TiddlyWiki site to choose info and then view some of the many fields of that tiddler.

click on 'info' to see some of the fields of any tiddler

Indeed at the most basic level every object that we perceive has a field with the key: name and the value: that is the unique form of that key, along with some basic fields such as location in time and space that further identify it as a unique thing or object. The majority of our first years are spent learning those fields, those key:value pairs and how they relate to each other and our selves.

photo from YouTube

We Are Bob Ross

Let's put all this in more concrete terms. Painting and Bob Ross. If somehow you don't know who Bob Ross is please read his wikipedia page and spend a few minutes watching one of his youtube videos. Nothing I say can do justice.

As we construct this metaphor, think of each tiddler is a dollop of paint. Each dollop is an object made up of multiple qualities. Those qualities can be broken up into a framework of paired associations called fields. Each field has a key and a value. The key stays the same across every created dollop, or object or tiddler. The value however can and does change and those changes in value is what makes each object unique even though it is created using the same framework of a dollop of goo on a board.

So each dollop of paint (each tiddler) has a field to describe its color. The key of that field is the word "color". Every dollop of paint, if it is to be a dollop of paint, has this word associated with it. The value of the field "color" (the field being named for its key) however is different for each dollop. It can be blue, or red, or black.

And we can extend this out as far as we want. If we have two red dollops we can further distinguish them by adding a field with the key "size". The value for size can be large, small, etc.

And now you can see how we can begin to build bigger objects by making associations between the values of objects that have the same keys. I can look for dollops that are only red, or only large, or red and large, etc. and arrange them however I want on the board. Or I can mix a large blue dollop with a small red dollop. So I can now find the exact dollop I need for the brushstroke I want to make and I can qualify all the dollops in ways that make it easy for me to distinguish them depending on what I want to do with them. Or I can find a dollop that is large and make it small by changing the appropriate value. I can find all the dollops with the same value for the key "size" and list them. There are a seemingly endless variety of "operations" that I can perform on these dollops using their fields.

To complete this metaphor and keep this post from getting way too long: Tiddlywiki is the collection of brushes and techniques. The individual tiddlers are the dollops of paint. Your project or wiki is the painting, and you... YOU ARE BOB ROSS!

What lies ahead

The static site generator I will describe in coming posts, and really a lot of what you will find when you explore TiddlyWiki and the things people have made with it, are a paint by numbers project for you to fill in and not a complete painting because the painting is what you are going to produce! There are many such solutions to specific problems that people have used TiddlyWiki to make and, like this site generator, you can tweak to your liking so that you can create a masterpiece the way you want to.

The following posts describing the static site generator used to make this blog will assume either a basic understanding of TiddlyWiki, HTML5, and CSS or a willingness to learn and maybe even teach in the comments. You'll also need to be familiar with or willing to learn how to use the Linux command line and obviously work within a Linux environment like a full OS or Windows Subsystem for Linux (WSL) or Crostini (the ChromeOS/chromebook linux shell) or the many other implementations out there.

See ya there you Bob Ross's you!!


Feel free to make up a username and log in anonymously to comment