This is a stripped-down version of a single section of Grok TiddlyWiki, optimized for fast loading and readability by search engines. Some features are missing.

For the full Grok TiddlyWiki experience, please visit the wiki version of this page.

Writing Shell Scripts Against a TiddlyWiki

2nd May 2021 at 11:40am

(Prerequisite for this section: A basic background in shell scripting or some other scripting language like Python.)

If you're a Unix philosophy person and believe that programs should do one thing well and integrate well with other programs, you might be wondering whether your data is going to be trapped in TiddlyWiki. Good news: if you install the Node.js backend on your computer and host your wiki there, you can easily integrate with other programs in whatever way you please. (It's also possible to quickly convert a single-file wiki to a Node.js folder wiki, so if you prefer to use a single file but sometimes need to get at the contents programmatically, you can extract a new folder wiki from the file to a temporary directory and then operate on that.)

File structure

The Node.js backend stores text tiddlers in individual files, which are easy for a script or other application to read. The format is much like email: first the fields of the tiddler are listed with the name separated from the value by a colon and a space, and then after one blank line comes the contents of the text field.

Tiddlers containing non-textual data, such as images, are instead included unmodified, and the fields associated with their tiddlers are stored in a separate text file with a .meta extension. So if you have an image tiddler called image.png, there will be an image.png PNG file which can be opened in a normal image viewer, and an image.png.meta file containing the fields of the tiddler.

For the most part, the names of tiddlers are used as their filenames, with a .tid extension added. However, a few characters are changed so as to avoid those that are invalid in filenames on some operating systems. It's also possible to add additional transformations as TiddlyWiki filters, for instance to put tiddlers with particular tags in a different folder. The details can be found in the Customizing Tiddler File Naming tiddler in the TW documentation.

The TiddlyWiki CLI

When simply looking at the files is not enough, the tiddlywiki command, installed with the npm package, lets you perform most any operation you need, such as rendering tiddlers to HTML or plain text, or selecting tiddlers that match a filter and writing them into a new wiki.

The TiddlyWiki CLI has a rather unconventional syntax that often confuses new users. Most CLIs would use positional parameters with the first parameter being the operation to perform:

tiddlywiki render FILTER

Or perhaps a positional parameter for the operations and double-dashed options for the details:

tiddlywiki render --filter=FILTER

Instead, TiddlyWiki uses double-dashed options for the actual operations, and positional arguments for the details on each operation:

tiddlywiki --render FILTER

You can, and often must, chain these together. So to set the source wiki and then save the wiki folder, you would do:

tiddlywiki --load SOURCE_WIKI --render FILTER

This is important because the CLI is stateless. From the help message, you might expect this to work:

tiddlywiki --load SOURCE_WIKI
tiddlywiki --render FILTER

But it doesn't – the first command sets the wiki to load but doesn't persist that setting, then exits, so it amounts to a no-op. The second command will continue to use the default source location (the current directory).

Editing wiki files

If you're going to edit wiki files on disk, rather than just reading them, be aware that you will need to restart the server to pick up the changes, as it assumes it is the exclusive user of the folder while it's running and does not watch files on disk. The plugin Bob adds listening functionality along with some other helpful features and is worth a look if you plan to do this more than occasionally,


Takeaways are not available in the static version of Grok TiddlyWiki. Visit the wiki version of this page to study takeaways.

↑ 8: Getting Technical