TiddlyWiki Logo featuring black silhouette of a cat on a purple background

Self-hosting TiddlyWiki with GitHub Pages

TiddlyWiki is most often used as a private wiki for personal note taking and creating private journals.

Because it is a single text file usually named index.html written in HTML, CSS and some JavaScript, I thought it would make an ideal candidate for a simple-to-use personal website that can be hosted on one’s own domain. As a researcher who appreciates the IndieWeb and Domain of One’s Own philosophies and uses my personal website as a commonplace book for both work and personal reasons, how could I resist?

TiddlyWiki

TiddlyWiki is easy to use, highly flexible, modifiable, and can be easily copied, backed up, and shared. There’s an active community of users and developers for the platform which dates back to 2004. There are a variety of examples and documentation online and plugins are literally as simple as dragging and dropping some files from one source directly into your own Wiki. For those interested in the OER movement, individual Tiddlers (TiddlyWiki’s name for cards or discrete entries within the wiki) can be easily dragged and dropped from other TiddlyWikis to copy them!

There are some useful instructions for hosting it almost everywhere–except on one’s own domain name.

The few easy options I’ve found for hosting a TiddlyWiki publicly online as a website were rely on someone else’s service as a subdomain. As much as I like the idea of TiddlySpot I really wanted to use my own domain name (not to mention that it’s non-obvious how to host a newer TiddlyWiki version 5 (TW5) instance there). I’d also seen TiddlySpace shut down a few years ago and didn’t want to deal with that potentiality—though I will admit that exporting would be as simple as downloading and moving a single file!

So after a month or so at tinkering around at several complicated solutions that always seemed beyond my grasp, I went back to IndieWeb basics. What is their recommendation for the easiest way to get a website up and running? The fact that an empty TiddlyWiki file is named index.html gave me my answer: set up a GitHub Pages-based website and simply connect it to my domain!

However, as simple as this pathway may seem to some, I thought I’d briefly document the process I took so others can do the same for themselves.

First I’ll presume you’ve got a domain name and a host that will allow you to change the CNAME for where your domain name is pointed. (If you don’t, check out https://indieweb.org/personal-domain for details.)

In short, you’re going to upload a single file to your GitHub account and then point your domain name at it.

The idea of GitHub may scare a lot of people, but you won’t need to use git, know any git commands, or even know how git works since I’ll describe steps that entirely use the graphical user interface and don’t come anywhere near using the command line or any complicated GitHub applications. It’ll be as easy as dragging and dropping.

Let’s start!

Step-by-Step Tutorial

Get TiddlyWiki

  • Go to https://tiddlywiki.com/ and click on the “Download Empty” button on their homepage. This will allow you to save a file called index.html to a convenient place on your computer.
  • This one file is the entirety of your future website! Guard it well.

GitHub

  • If you don’t already have one, create an account at https://github.com/
    • You’ll use this account and their free GitHub Pages service to host your website for free as long as the project folder (also known as a repository) you are hosting is public.
  • At GitHub create a new repository.
    • Name it username.github.io, where username is your username (or organization name if you’re doing it for your organization) on GitHub.
    • Give your repository an optional descriptive name. I named mine “A TiddlyWiki commonplace book”
    • Choose the “Public” option, otherwise no one will be able to visit your new website.
    • Click “Create Repository”
  • Upload your TiddlyWiki to your new repository
    • In the Quick Set Up box click on the link for “uploading an existing file”.
    • On the subsequent page you can either drag and drop the empty TiddlyWiki index.html file you saved on your computer or you can click “choose your files” to find and upload the file.
    • If you like, you can optionally add any additional README, License, or gitignore files as necessary. If you don’t know what these are you can safely skip them or revisit doing this later.
    • Under “Commit changes” give your upload a short title; the suggested “Add files via upload” is fine. You can add an optional extended description if you like.
    • Click on the “Commit Changes” button.
      • P.S.: If you haven’t done so before you’ve just made your first Git commit. Congratulations!!
    • Your https://github.com/username/username.github.io repository folder should now be ready and have your index.html file in it.

Setting up your domain

Setting up your website

  • It may take a while for the DNS system to propagate the changes from your host, but you should be able to visit your website and see your empty TiddlyWiki online. Congrations! You’ve got a new website.
  • You’ll notice in the TiddlyWiki documentation that the first rule of TiddlyWiki is to always save or back up your wiki!
    • (The second rule, in true Fight Club fashion, is–let’s say it together–to always save or back up your wiki!)
    • Since our wiki is on GitHub, we’ll want to use the Save to a Git Service instructions. Once set up, the changes to our TiddlyWiki should automatically self-save (this can be changed within your wiki’s Control Panel too) or they can be saved manually using the TiddlyWiki checkmark save functionality.
    • I’ll note that you can presently use your GitHub password in these settings, but this isn’t quite as secure as generating a custom token (or password), and sometime in late 2020, GitHub won’t allow you to use your basic account password this way, so you may as well set up the personal access token now.
  • Setting up Personal Access Tokens
    • You will need a Personal Access Token (essentially a password that will be specific to your TiddlyWiki account) in order to save your TiddlyWiki file.
    • On GitHub, click on your user icon, select “Settings”, then “Developer Settings”
    • Next click on the “Personal Access Tokens” tab and then click “Generate new token”
    • Give your token a descriptive name like “TiddlyWiki”
    • Under scopes, select “repo” (and all of its sub-scopes)
    • Click the “Generate Token” button at the bottom of the page.
    • Once created, immediately copy this string somewhere safe since navigating away from the page will not allow you to recover it. (If you do, you’ll need to regenerate a new token.)
    • Finally copy the text of your token into the Tiddler noted above in place of your password. There’s no explicit save button, just ‘X’ out of the settings control panel and click your TiddlyWiki’s main save button.
    • Your token value should be stored in browser local storage.
    • Now you can edit any Tiddler and save it.
      • After edits to your wiki, you’ll see that the checkmark icon on the page is red (depending on your theme), indicating changes to save. You can click on it to force a save.
      • I’ve found it convenient to wait for the TiddlyWiki to schedule the save on its own, however, make sure you’ve saved any changes you want before closing your browser tab.
      • Sometimes saves aren’t always successful and you’ll see error warnings, but usually they’ll clear themselves up on subsequent auto saves.
      • If necessary, you can visit your GitHub repository for your wiki and it will indicate the interval of time since the last save.

We’re done!

  • Everything after this you may be able to either handle yourself by poking around your new wiki or you can find lots of help in the two Google Groups listed above or by searching around online, in fora, or even step-by-step videos on YouTube.
  • If you’ve done this as part of the IndieWeb or A Domain of One’s Own, be sure to log yourself into the IndieWeb wiki and add yourself to the examples on their TiddlyWiki page where you might also find some other useful ideas.
  • If you like, you can delve deeper into GitHub and use one of their apps or command line functionality to regularly back up your website to your desktop, or you can make branches of your site on your local computer and then push those changes up to the cloud.
  • If you find problems or encounter issues, feel free to drop me a line or catch me or others in the IndieWeb chat.
Home

Published by

Chris Aldrich

I'm a biomedical and electrical engineer with interests in information theory, complexity, evolution, genetics, signal processing, IndieWeb, theoretical mathematics, and big history. I'm also a talent manager-producer-publisher in the entertainment industry with expertise in representation, distribution, finance, production, content delivery, and new media.

46 thoughts on “Self-hosting TiddlyWiki with GitHub Pages”

  1. @c thanks for this write up. I’ve been interested in setting up a wiki on TW for awhile, but felt like there were too many barriers for me. I didn’t look at the using GitHub to Save page you linked to yet, but am I reading this right, that if you have the token, you can edit and save from any browser?

  2. @kordumb I just double checked it. You’ll need to add the token in each browser in which you use your TW (otherwise it would be a security issue and anyone could modify your wiki on your behalf). The token is saved in the browser for future edits.

    1. Dan Foley says:

      How do you get this working. Currently, I’m using the github saver. I end my personal access token, and it allows me to save for a few days, until, I assume, github revokes my token because the token itself Is being saved with the wiki. How do you get around this?

      1. Chris Aldrich says:

        In my experience, your browser should be keeping the details locally, so perhaps it’s an issue with your browser deleting cookies/cache?

  3. @c I edit it locally then rsync it to a server behind nginx. For a while I had it running via node and edited “live” on the server but after moving servers around I decided to “de-complicate” it :). Using the iPad more is making me re-think how I manage it.

  4. @chrisaldrich I used tiddlywiki for years as my lab notebook (I’m a computational biologist). It was great. Unfortunately, I ran into conflicts with the helper programs required for the file to self modify and browser versions mandated by my employer. I’m using a custom variant of markdown from daring fireball now, but I remember tw fondly.

    1. @sconlan@radical.town I’ve had lots of quirks with those helper programs too. Saving things privately was much easier for me than figuring out how to host it publicly though. Is your lab notebook on a public facing server? I’m collecting examples of people using these as notebooks or commonplace books.

      1. @chrisaldrich no, they are not on public servers, just local copies. Since it’s primary scientific research I wouldn’t feel comfortable sharing in a public way.That said, I think the project is great.As a side note, I think about electronic notebooks a fair amount. There are all kinds of horror stories about people or labs locking into proprietary ELNs and getting screwed when the company folds or license expires. I insist on open systems that can be read by any computer.

  5. Hi Chris,
    This worked very well for me, I already had some git hub pages so just added another directory https://git.johnj.info/tiddly/
    Took a few goes to get the settings to stick but I got there. I also found if I had two browsers open saving failed. Get the odd save error, but it seems to sort itself out in the end.
    Not sure what I am going to do with this as I’ve a couple of other Tiddlywikis, but it is fun to play with.

    1. Awesome! I’m still tinkering myself to figure out what works best for what. Glad you managed to use the notes to get things working. I like that featured photo when it opens up btw.

  6. Cheri says:

    Thanks for the instructions! I’ve been thinking about setting up a wiki and your post is a huge time saver.

    1. Most welcome. Let me know how it goes (or if the details take you off the rails somewhere.)

  7. While doing some random searching today, I coincidentally ran across two GitHub repos for TiddlyWikis that are on GitHub Pages. They also both indicate that they’re online commonplace books! My favorite is that at least one of them credits me for its existence on GitHub pages.

    1. https://github.com/joshcsullivan/joshcsullivan.github.io for https://wiki.joshsullivan.io
    2. https://github.com/luanaoliv/luanaoliv.github.io which was made 5 days ago and has little content at http://wiki.lu4.org/
  8. I noticed the other day (because I follow him), that Jack Baty mentioned this article on his TiddlyWiki: https://rudimentarylathe.org/#Saturday%2C%20April%204%2C%202020

  9. @stefp There’s a way to do it when running node so that only users logged in can edit. I’ve simplified things by just uploading the .html file and serving via a web server. It looks editable online that way, but saving doesn’t actually do anything.

  10. @jack Thanks. Just tried it that way and it seems to be working. It doesn’t seem obvious at first. I’ve noticed some small differences between Firefox and Safari. I can’t get the “save changes” button to appear in FF. It was a great relief to find out what it could do in Safari.

  11. @stefp I haven’t seen any public/online versions that allow anyone to save edits to your server (node might give you an option to if you wanted, but I haven’t delved into it yet). All the public versions require some sort of account/authentication set up to actually save the TW. On the other hand, it’s generally very easy for people to download your entire Wiki and save a copy, or to drag/drop Tiddlers from yours to theirs. In most cases, if they do make changes and attempt to save it, the browser will simply force a download of the entire wiki to their local computer without any changes to your hosted version.

  12. @jack The button has disappeared again. Very frustrating. There’s a button in tools marked “save all” that will let you save an html snapshot if you hold it down. It seems to come and go. I’ll try that Timimi plugin.

  13. @jack I’ve set TW up with Github Pages last week, mostly following @c‘s post, and it works reasonably well in Safari, on macOS and iOS as well.

    If you can ignore the occasional 409 errorsthat resolve themselves on the second or fifth try…

  14. TiddlyWiki is a responsive website platform built as a single file in HTML, CSS, and JavaScript.

  15. This Article was mentioned on tomcritchlow.com

    1. Thomas says:

      When I put my access token into TiddlyWiki, does that mean that it‘s public and can be used by everybody?

      1. Chris Aldrich says:

        I personally used the “Github saver” option, so the token is hidden and thus only makes the changes savable and useable by me while remaining publicly readable by others. See additional details at https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens

Leave a Reply

Your email address will not be published. Required fields are marked *