It Ain’t Over ‘Til The Paperwork Is Done: Test Driving TiddlyWiki

Working on projects is fun. Documenting them is often not so much. However, if you want anyone to duplicate your work — or even just want to remember what you were doing a few years ago when something needs upgrading or repairing.

There’s a ton of ways to keep track of the details of your projects. We love seeing how things come together and of course we’re happy to suggest documenting on Hackaday.io. But sometimes, you just want to keep your own notes to yourself. There’s always a notebook, of course, but that seems kind of old fashioned. A lot of projects are on Wikis but you hate to stand up a web server and a Wiki instance just to keep notes. But what if you could have a local Wiki with minimal setup?

I recently came across TiddlyWiki and decided to take it for a spin. Join me after to break to see what it’s all about.

Low-Overhead Wikis

With TiddlyWiki You can actually store a pretty nice Wiki in a single file. If you don’t like to depend on an internet connection, you can store it on your own computer or a flash drive. But you can also arrange to host it on the cloud if you like. You could even save it to Hackaday.io, although you’d have to zip it as the platform doesn’t accept straight HTML files.

How much power can you get in a single file? Actually, quite a lot. The infrastructure is one single HTML file, so maybe you can’t host Wikipedia with it. But you can modify that HTML file and, in fact, there are lots of plugins and other things that you can add even if your HTML skills aren’t up to doing it yourself. But more on that later.

Basics

It is dead easy to get started, tust download an empty TiddlyWiki template. You can name it anything you like and when you open it with a web browser, you’ll see it gives you a form to set things up. That form is actually written in the Wiki, so that should give you some idea of how powerful this is.

The file will contain one or more topics, called tiddlers. These can be visible or hidden and there are many ways to find, open, and close them. Each tiddler can have tags and hyperlinks. You might build a sidebar that lists all the tiddlers marked with a menu tag, for example. Or you might want to tag all your RISC-V tiddlers with that tag so you can find them easily. You can also search or dynamically include one tiddler inside another.

Every time you open a tiddler, it adds to your view. You can close any that you don’t want. You can also minimize them or you can minimize or close all other tiddlers if you want to focus on your work.

Saving and Other Features

The only small problem is how do you save your changes? In the default online Wiki, there is a topic called “GettingStarted” that actually shows you all the choices you have broken down by platform and web browser. There are connectors for storing your files locally or on a variety of cloud services including GitHub. There are also browser extensions available to make it easier to work with TiddlyWiki. There isn’t just one way, and everyone’s situation will be different. Worst case, you can elect to download the updated Wiki as you would any other file in your browser.

You can use a Tiddler to store bookmarks, organize tasks, keep inventories, organize images — you can even edit images. The nice thing is since it is all in one file, you can easily send it to someone and they can open it with just a web browser. You can, in fact, post it online and use it as a web site — something the tiddlywiki.com site does.

Plugins

There are a wide variety of plugins you can install. For example, there is a syntax coloring plugin. Another one will embed Twitter data into the Wiki. In addition to the standard plugins, there are many user-contributed ones. For example, you can get tools to migrate from Evernote, generate QR codes, or work with Google Analytics.

Of particular interest is one plugin that provides the CodeMirror editor. It is made to edit code and you can install extra features for it such as syntax highlighting, brace completion, and keymappings.

In addition to plugins, you can download more themes and languages, too. Some of the themes are cosmetic, but some are practical. For example, you can install a theme that hides the ability to edit a tiddler. This would be useful if you were using it to deliver a web site. You can also require a password to save.

There are also many macros and widgets. For example, there’s a widget called <$codeblock> which will display a block of code appropriately. There’s even an encryption widget. Macros allow you to define shortcuts for things you want either repeated in a tiddler or — if you put it in the right place — to multiple or even all tiddlers. You can also write macros in Javascript.

On Your Own

This isn’t meant to be a full TiddlyWiki tutorial — there are plenty of those online. If you prefer video, the series that appears below will get you started, too.

You can use TiddlyWiki for just about anything. We’ve even seen it used to build an adventure game. If you are using it now, or you plan to, drop a comment to tell us how. We’ve seen wikis used for a lot of neat documentation, including signal identification. Since the system is pretty extensible, we wonder if you could push a Jupyter notebook inside of it?

20 thoughts on “It Ain’t Over ‘Til The Paperwork Is Done: Test Driving TiddlyWiki

  1. I used TiddlyWiki to write the User manual for a commercial microscopy product about 10 years or so ago. Worked beautifully and generated a very professional product that could grow with developing features.

    It was a nm scale metrology product based on white light confocal technology.

    1. One of the great features of TiddlyWiki is that when you open that file it still works the same as when you created it. You don’t need to install any extra software, just a browser because the entire wiki is a single HTML file..

  2. Imho hackaday.io is the last place to document yout project. Even twitter is better. Or farcebook or imgur for that matter. At least you get to see the contents without a lot of swiping to get to the actual info. No sir, mediawiki serves me well.

  3. Tiddlywiki is a very effective way of organising scrapbook of notes for a project.

    It is simple, so it doesn’t take long to learn.

    The core concepts are well chosen, so it doesn’t force you to work the way the designer decided you ought to work. You choose how to use it.

    The everything in a single file format avoids lots of problems with version control, and comparing two versions can be done with any text tool.

    Running in your browser makes execution and portability trivial.

  4. I came from the Vim era: it’s a popular text editor, mostly used by technical people. I tried out different ways to store my thoughts, for example: plain text (Asciidoctor) files, Jekyll (blog platform), Boostnote (note taking software). Whenever I tried out new ways, these was my most important requirements:

    * Offline first: I don’t want to depend on companies – when it’s closing its doors, my notes are gone
    * Export my notes easily: If I ever want to change to another tool, I want to move my notes into that easily (at least with minimal modifications)
    * The best would be to store as plain text: I’m using Git heavily, thus I like to keep my “backups” in a repository – for this job the text format is the best; besides this I can batch modify the notes via Vim
    * Be able to read my notes from everywhere: I would like to read my notes from any computer without installing the “editor” itself
    * Be portable: It has to work on Linux / Windows (Android is not reuired, but it’s good if it works) – the best would be to use exactly the same GUI on every platform
    * Require as few as possible external programs: For example compiling Asciidoctor files to HTML require Asciidoctor itself, which is written in Ruby -> needs that too
    * Tag feature: My habit is that write a note and add a lot of related tags to it – I don’t have to think where to put in the ToC, because I can find anything by tag intersections

    Whenever I tried out new stuff, it turned out that it doesn’t have some of these features, thus I switched back to old, but good plain text (Asciidoctor) format (because it’s the most flexible) + Vim editor (syntax highlighting, search and replace, basic file navigation).

    The problem with file based note taking is that

    * You are forced to use hierarchy: You have to place your files somewhere in the directory tree, but it’s not clear that a note about “NoteTaking” should go in to “TextEditing”, “Software”, “Practice”, because it belongs to all of these “categories”
    You can drop every note into one directory, but in this case looking for them is hard
    You can store the tags in the filename and use file searching, but if you want to share your notes with others, he/she will not know what to do
    * Hard to search for tags and tag intersections: With regular searching tools (like Grep) you cannot do fuzzy match, but you can search for regex, like “tags:.Software.TextEditing”, the disadvantages of this is that you has to store the tags in predefined (maybe alphabetical) order
    * You can use fuzzy file searchers (like FZF or Everything), but you cannot get the list of tags to pick from that
    * Cannot include images and other media types into notes

    So I continued searching for The Notetaking Software, then I found TiddlyWiki and fell in love with it, because it knows almost everything that I want, besides this it’s incredibly hackable: you can turn it to any kind of software, not just notetaking (todo list, book, GTD, project documentation, family tree, photo gallery with categories and tags, etc.)!

    For a better understanding of what is the real power of TiddlyWiki, please read [Joe Armstrong: My Eureka Moment with the TiddlyWiki](https://joearms.github.io/#2019-01-08%20My%20Eureka%20Moment%20with%20the%20TiddlyWiki) then have a look at these examples:

    * Great design by h0p3: https://philosopher.life/
    * Managing D&D and similar table top games (just download and open the HTML file – it’s the entire wiki itself, all in one): https://groups.google.com/d/msg/tiddlywiki/18jQ5gy0L-k/36KirLjSCQAJ
    * Include videos, images, music, etc. in to your wikis with RichLinks plugin (see Demos tab): http://richlinks.tiddlyspot.com/
    * TiddlyMap for mindmaps: http://tiddlymap.org/
    * Cardo for project and task management, Getting Things Done (GTD): https://cardo.wiki/

    If you have additional questions, look for the [TiddlyWiki mail group](https://groups.google.com/forum/#!forum/tiddlywiki), there are very helpful people (seriously, this is the best community I met on the net).

  5. Wow, I remember using this about 14 years ago. Had a gallery plugin and a means to graph data and functions encoded in a url (I think). I may even have the file in a backup somewhere…

    1. Yah, I’ve actually used it off and on for years (not sure why out of edit it came out that I just found it). However, it has had major features added over the years and even a major fork.

  6. I´m curious if, when printing, it will keep the formatting the same as the displayed page. Like, to be able to have a well formatted page, and after you are happy with your layouts, the pages can be printed for handier or safer storage.

  7. I run an A4 Spiral Bound Notebook. Within it you can see all of the revisions, the thinking going into design decisions, external references (some printed and stapled to the back) . The index is manually updated somewhat infrequently but the great thing about it is I know it so intimately because I wrote it down myself and it has the capacity to operate offline and the battery never goes flat….

Leave a Reply

This site uses Akismet to reduce spam. Learn how your comment data is processed.