Exporting Static Sites from Tiddlywiki

Part 1 : Creating a Basic Workflow

Summary

_{This article assumes that you are familiar with the basics of using the command line to enter commands and run programs, if you need an introduction to this subject, read this article first. It also assumes a basic familiarity with Tiddlywiki. If you haven't used it before, you should look at the Introduction to Tiddlywiki}

Introduction

One of my main goals is to make the editing process basically the same as using Tiddlywiki in an ordinary way.

My other goal is for the statically generated site to behave in a completely 'ordinary' way.

Our first goal is to be able to create a static site from a wiki. We'd like to be able to write, you see, a wiki-like set of tutorials to explain about how to do things. The first thing we're going to explain is how to make a static site from your wiki, because it's kinda useful.

What it basically means is that you can use Tiddlywiki as your CMS and it's probably a good fit for lots of kinds of personal sites.

Once our site is a folder full of static files, life's a breeze. The important thing to note about static sites is they are only 'static' in the sense that all the assets are delivered to the client statically but many of those assets are themselves dynamic in nature.

Installing Node, NPM and Tiddlywiki

To see if you already have node or npm installed, type

node -v
npm -v

If you don't you should follow the instructions to install it. (I THINK) npm gets installed automatically along with node - is that only on the mac?

Once it's installed, you can install tiddlywiki like this

npm install -g tiddlywiki

You can check it's installed by typing

tiddlywiki -v

To use tiddlywiki as a node process, this is all you need. To keep your system up to date, you can periodically check your versions.

If you need to bring the software up to date, you can do...

npm upgrade???

Running the Tiddlywiki server

Now that you have it installed, there are just a few key commands you need to successfully use tiddlywiki.

First you need to initialise a directory for working with tiddlywiki

tiddlywiki --init server

This will make a tiddlywiki.info file in your current directory.

Now, from the same directory, you can run

tiddlywiki --server

And it will get served on port 8080 of the local host. This means that if you type 127.0.0.1:8080 into your browser address bar, you should see tiddlywiki running.

Once you have it running, make some tiddlers that link to each other and tag each of them with a tag that's going to denote that they should be published to your site (this way we can work of tiddlers before deeming that they should go live)

If you already work with Tiddlywiki, you can import a group of tiddlers from a static file wiki by drag and drop or using the import mechanism. If you're not sure how to do this, you can read more here.

Tag tiddlers with a tag that you like - I use "Live" at the moment and it's easiest if you use the same while you follow this tutorial, so that you don't need to modify the commands as presented here.

Exporting static pages

Now we want to export our tiddlers to static files and see what happens. To do this, we'll open another terminal window or tab (because we still have our server running in the other one) and, after making sure that we're in the top level directory of our server (the one that contains the tiddlers folder) type

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

List the contents of the directory and you should see that a new folder has been created, called output, and in it, another directory called static. And in that directory, we'll find our files, one for each tiddler.

Open one up in a browser and you should see your content, but it will look pretty plain.

Note that you shouldn't edit the html files directly. Whilst it might be tempting to tweak them, ideally we want to be able to regenerate the whole site each time we make changes and that's going to overwrite the files. If you had to do this, you'd need to remove the Live tag from the tiddler whose output you changed. In my opinion that goes against the simplicity we're aiming for.

Adding CSS

Now, make sure you navigate back to the top directory in your terminal and then run this command.

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

This generates a css file to go with your static pages. Look at one of them again.

I find it satisfying to have the folder structure open in finder alongside the terminal so that I can see my commands having an effect of the files live.

If you do this, you'll see that running the first command again deletes the whole static folder and then recreates it from scratch.

This is good, because it makes it easy to remove pages we no longer want from our site and makes sure we don't get any out-of-date pages hanging around, but it also means we need to also run the second command again to regenerate our css.

We can join these two commands together using the Unix && operator, like so

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

but even having to remember that and either type it in again without a mistake or find it in our bash history is a pain, so instead we can write it in a small bash file. (Creating and Editing Text Files )

If we wanted to make this easier to remember, so that we don't have to type this in every time (or, more likely, copy-paste it or find it in our terminal history), we can put these two commands in a simple text file, each on its own line, and give it the extension .sh (for shell script), eg; build.sh, we can run it from the terminal by typing ./build.sh (this is just the relative path of the file we just created) whilst in the parent directory (the one that contains the tiddlers folder).

Now all we have to do is re-issue that command and our site gets built.

Running a local web server

Up til now you may have just been accessing your static pages through the file api. You will probably want to run an actual web server to view these files over HTTP, the way they will be consumed by your audience. This isn't difficult at all.

Just open another terminal tab or window and navigate to the static folder. Then run the python web server (if you're on a mac)

Don't do that - run the node http-server module since you already have node on the go. —

NEXT : Part 2, solving the issue of css