How to use TiddlyWiki as a static website generator in 3 steps

TiddlyWiki is an amazing tool for thought. It’s free, open source, and extremely modular. If you gave it a quick try and want to take things a bit further, you’re in the right place. We’re going to look at TiddlyWiki as a static website generator. Static websites are fast, they’re easily indexed by search engines, cheap to host, and virtually unhackable. And with TiddlyWiki, your website can feature bi-directional links and more.

In this tutorial, you will learn how to turn your TiddlyWiki notes into a static website. We will first install TiddlyWiki on your laptop using a local Node.js server, then we will export your wiki to a static website, and finally we will host it on GitHub Pages, which is free. You can see the TiddlyWiki official static website for an example of the final output.

I’ll walk you through everything you need to install as we go, but here are a couple of things I think are helpful which you may want to install before you get started:

• Hyper (a nice looking terminal)
• VS Code (a great code editor, other options include Atom, Sublime, and Brackets)

Again, you can install these later. This tutorial is aimed at non-technical people. It may sound daunting but we’ll take it step by step, so buckle up!

1. Install the Node.js version of TiddlyWiki

If you have never heard about Node.js before, this is going to feel quite technical, but just follow the steps and it will be alright. It is a bit of extra effort to run any piece of software locally, but what you will learn in the following steps can be re-used to install any other software on your laptop. And you will only need to go through these steps once. Let’s do this.

If any of the following steps throw an error about admin privileges or permissions, add sudo at the beginning of the command, type in your password (the one you use to log into your computer) and try again. The sudo command allows you to run programs with the security privileges of an administrator. If you’re still getting some errors, the TiddlyWiki support group is your friend!

• Install Node.js on your laptop. Node.js lets you execute JavaScript code outside of a web browser. And TiddlyWiki is based on JavaScript. Get the Windows or MacOS installer here. Make sure your user account has administrator privileges on your laptop (this may not be the case if you use a work laptop). With either of these installers, you just need to keep on clicking on “next” until it’s done. If you want more detailed instructions (it’s seriously just download and click next, but just in case) see instructions for MacOS and instructions for Windows.
• Install TiddlyWiki. Node.js comes packaged with a nifty thing called npm which lets you very easily install new software on your laptop by just typing a couple of keywords. For this, we are going to use something called the “command line”—which is what you see in movies with hackers, with a bunch of text on a black screen. There are different ways to open the command line on different kinds of operating systems, so my advice is to just download Hyper, which is the awesome free terminal I use myself. To install TiddlyWiki on your laptop, open Hyper, paste the following, and press enter: npm install -g tiddlywiki
• Check it worked. The previous step should trigger a bunch of text in the terminal showing the packages getting installed. Let’s make sure it all worked. Type or paste tiddlywiki --version in Hyper and press enter. If it reports the current version of TiddlyWiki, you’re golden! It worked. If not, post your question here and be as detailed as possible in terms of your current configuration.
• Create your first wiki. Type or paste tiddlywiki myfirstwiki --init server and press enter. This will initialise the server (“init server”) and create a new folder with everything you need for to run your first wiki (called “myfirstwiki” in the above command).
• Start your wiki. Type or paste tiddlywiki myfirstwiki --listen to start your wiki. In the previous step you started the server, now you are actually listening to it, making your wiki live. If you ever close Hyper by mistake, just re-open it and type the tiddlywiki myfirstwiki --listen command again.
• Use your wiki. You can now go to http://127.0.0.1:8080/ in your browser and you should see a brand new wiki. Great job! You have installed TiddlyWiki on your computer and you are now accessing your very own wiki, running locally on your laptop. I recommend adding http://127.0.0.1:8080/ to your browser’s bookmark bar for easy access in the future.
• Create a few pages. First, create an index page. This is not necessary to use TiddlyWiki itself, but we need an index.html in our final website. Create a new page, call it “Index”, write something like “This is my first static website with TiddlyWiki!” and save it. Then, create 2-3 more pages. Even better if you link them together by using [[Name of the linked page]].

If everything worked well, play around a little bit and create some more notes (called “tiddlers” in TiddlyWiki). You can also play with the format of the content, with bullet lists, bold, italic, blockquotes, etc. If you look at the saving icon in the right-hand menu, you will see it automatically turns from red (unsaved changes) to light grey (all changes saved) without any manual action on your part. That’s the beauty of installing TiddlyWiki properly.

Before we export your TiddlyWiki as a static website, we’ll make a tiny tweak which will make the end result look better. Click on More > Shadows in the right side menu, then CMD+F or CTRL+F to find this one in the list: $:/core/templates/static.tiddler.html. Click on it top open it, then click on the edit icon, and paste the following just under the body class="tc-body" tag:

<div class="tc-sidebar-scrollable" style="overflow: auto;">
<div class="tc-sidebar-header"><h1 class="tc-site-title">Title of my website</h1></div>

<div class="tc-site-subtitle">This is my very first website created with TiddlyWiki</div>
</div>

Save this tiddler and you’re done with this section! You won’t see any changes right now, but this little bit of code will export a nicely formatted title and description in your final website.

2. Export your TiddlyWiki as a static website

Here are the official instructions to export your TiddlyWiki notes as a static website. I’m going to walk you through them. Remember the command line? Let’s open Hyper again. Make sure you are in the myfirstwiki directory. To do this in Hyper, you can use the cd command, which stands for “change directory”, by pasting this and pressing enter: cd myfirstwiki.

First, paste this and press enter:

tiddlywiki --rendertiddlers [!is[system]] $:/core/templates/static.tiddler.html static text/plain

Then, paste this and press enter again:

tiddlywiki --rendertiddler $:/core/templates/static.template.html static.html text/plain

Finally, paste this and press enter one last time:

tiddlywiki --rendertiddler $:/core/templates/static.template.css static/static.css text/plain

These basically render your dynamic TiddlyWiki into a static HTML + CSS website. Because it would be really annoying to have to do this every time you want to update your website, let’s make it easier.

Open your text editor (I use VS Code), and paste the following, which is a concatenation of the previous three commands (credits):

tiddlywiki --rendertiddlers [!is[system]] $:/core/templates/static.tiddler.html static text/plain --rendertiddler $:/core/templates/static.template.css static/static.css text/plain

Then save the file as build.sh inside the root folder of your wiki. If you have been following this tutorial from the beginning, that should be myfirstwiki. From now on, you’ll be able to just type ./build.sh in Hyper (make sure to include the dot at the beginning) to convert your dynamic TiddlyWiki into a static website.

Please note: you may not have the right admin privileges to create the build.sh file. Try the sudo command I mentioned earlier. And if that still doesn’t work, the good news is you don’t need that file to use the TiddlyWiki static website generator. Just copy and paste the concatenated command starting with tiddlywiki --rendertiddlers into the command line, it’s the same but a bit more manual.

Now, go to myfirstwiki/output/static/ and double click on any HTML file to open it in your browser. Yep, that’s a fully fledged website for you with just a couple of commands. Now, let’s get this baby into the world.

3. Host your TiddlyWiki on GitHub

You have a static website, now you want to make it live. There are many options to host a static website for free, such as Netlify, Vercel, and even Neocities (probably the simplest if you’re not used to web hosting), but for the purpose of this tutorial we’ll use GitHub Pages, which is free forever and lets you use your own domain for free as well. If you already have another host, feel free to skip this step.

• Create an account on Github. Click on “sign up” on this page and fill the form. Write down your GitHub username somewhere, you will need it for the next step.
• Create a new repository. Click on the “+” sign just next to your profile picture in the top right corner of the page, then “new repository.” It should be named username.github.io, where username is your GitHub username. (this is very important, it won’t work if you use something else)
• Click on “upload”. Upload all of the files you have in the “static” folder.

If any of this was confusing, have a look at the GitHub Pages wizard here. It will explain how to upload your content to GitHub pages in detail.

You can now go to username.github.io in your browser. Here you go! And there’s more—you can actually use your own domain for your TiddlyWiki website, for free. See this tutorial from GitHub for the very simple step-by-step instructions.

If you want to take it to the next level, you could use the command line to automate your website updates, or deploy your website to Netlify. To play with the HTML structure or the CSS, the files you want to look at are $:/core/templates/static.tiddler.html and $:/core/templates/static.template.css (which you can access in your TiddlyWiki by clicking on More > Shadows in the right side menu). You can also start adding features to your TiddlyWiki such as bi-directional linking, which will appear in the exported static website.

The sky is the limit, but I hope this short tutorial gave you a good idea of what you can achieve with the TiddlyWiki static website generator. See my own static website made with TiddlyWiki for some inspiration. Have fun!