Simple static site generation

When you're young it makes sense to want to make your website complex and using the latest technologies. You have time and it's a great way to learn. But as you get older or simply find better things to program than yet another skin for a database, you may not want the maintenance and risk that comes with running a site that's backed by a database and possibly a mess of javascript.

I know I don't so going down the static site route makes sense. Still, I feel often there is too much complexity because people still want a lot. I guess perhaps tags may be nice but look at this my site, it's basic - what would tags really add that would make the worry of compatibility and templates worth the time? In my mind not much.

I wanted little to no maintenance, little effort to get it from Ulysses to html and it has to work easily on iOS. One thing we often forget, as developers, is how to make nice, simple and reliable. Perhaps from spending our youth learning to do the complex things.

Anyway, those were my requirements and the rest of this article covers how I decided to solve my problem.

First, I need to translate markdown to html on Mac or Linux and preferably in a sane unix command line way. So I thought I'll grab John Sundell’s Ink, write a cli interface and build it on my Mac and host. Well, he did the cli interface already! So executables are built and backed up so even swift compatibilities do not become an issue for a long time.

Great, I can now read a file and spit out HTML. What's next? Work out a simple directory structure of source files and output directories. Agree on a file name convention and now I just need to plumb these things together.

I want to write as little code as possible, do as little as possible to get it working. So, I chose Bash. It might seem weird and crusty but it makes the most sense in many way.

  1. It's simple as it does effectively just link tools together
  2. Mac and Linux will have Unix tools. Even python requires installation of software and had some recent versioning issues with setuptools.
  3. That's what those tools are there for. Use them and do reinvent them.

Now, Mac’s toolset is quite old so I believe in only one case I've had use Perl to do a task to get cross compatibility without pain. But otherwise once it's written that's likely going to be it for a long time.

I've got a private repository holding the script and my markdown for this site. I'll do a public one that doesn't contain my things at some point but it can be done now.

While everything resides on my Mac the intention will be to simply write markdown and commit it. On iOS I have the option of Working copy to commit to git. Secure shellfish to get files easily on server and Prompt for manual intervention.

The intention long term is simply git commit markdown files anywhere and then a a cronjob (or systemd timer) will run something that occasionally pulls and builds. Likely with a directory swap to make the files public. This way, if it dies then the previous copy can be put back, timer stopped and worry about only when I feel like adding something to the site.

There are still some rough edges I want to tweak but the nice thing is that I don't have to. What I’ve created builds a site that will run anywhere, it’s unlikely to break for years if not decades and the surface area is so small fixing it won’t be a problem. Now, my only concern is my ability to type things out without errors.