Using Tiddlywiki with Git
TiddlyWiki for NodeJS enables version management via Git.
TiddlyWiki is great for all kinds of notes, including code documentation. This is especially powerful when combined with Git.
Init
I like to monorepo things, so I’ll have something like this in the root of my repository:
/frontend
/backend
/docs
In /docs I use yarn (or npm, whatever floats your boat) to install the TiddlyWiki node package, and make a couple of scripts in package.json:
"scripts": {
"wiki": "tiddlywiki docs --listen",
"build": "tiddlywiki docs --build"
},
Now when I run yarn wiki it starts up a TiddlyWiki local server on port 8080, and saves all you individual .tid files into the new docs sub-folder. 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 (which makes your repo way smaller than storying the entire TiddlyWiki HTML file), 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. Since the documentation about the feature is stored in the branch with the feature, the documentation makes it to master and gets published at the exact same time the feature also makes it to master and gets published.
Dist
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.
