Using TiddlyWiki with Git

Screen Shot 2020-09-09 at 7.58.58 PM
Reading Time: 2 minutes

I like to monorepo things, so I’ll have a /frontend /backend /docs in my git root.

In /docs I use yarn to install the tiddlywiki node package, and make a couple of scripts in the package.json:

"scripts": {
    "wiki": "tiddlywiki docs --listen",
    "build": "tiddlywiki docs --build"
  },

So when you run yarn wiki it starts up a TiddlyWiki local server, and saves all you individual .tid files into the new docs subfolder. Each of these .tid files is basically markdown and really easy for git to parse and merge (unlike the single file TiddlyWiki which git has no idea how to handle merges on). None of the code that makes TiddlyWiki work is ever stored in the repo, you just fetch it as a dependency via yarn.

So as I’m writing features in whatever branch I’m in, I can spin up the TiddlyWiki and write documentation related to them. And since the documentation about the feature is in the branch with the feature, the documentation only gets published when the feature also makes it to master.

When you run yarn build it takes all your .tid files and runs them through the node version of TiddlyWiki’s build process and spits out the single self-contained HTML file you expect from TiddlyWiki. This file behaves just like any other HTML file, so you can host it on any webserver. To automate that process I use continuous integration.

I use GitLab, so I have the exact gitlab-ci.yml you need, but the process should be similar for other CI providers:

stages:
    - build
pages:
    stage: build
    image: node:14-buster-slim
    before_script:
        - yarn
    script:
        - yarn build
        - mv docs/output public
    artifacts:
        paths:
            - public
    only:
        refs:
            - master
        changes:
            - "docs/**/*"
            - ".gitlab-ci.yml"

Basically what this does is whenever the master branch has changes inside of /docs, rebuild the TiddlyWiki and publish the HTML file to GitLab pages (GitLab’s free web hosting). But you can just as easily pipe the output to your own web server via rsync.

Screen Shot 2020-09-09 at 7.58.58 PM