I recently discovered GitBook. It’s a web-based book authoring system with support for scientific writing tools (such as MathJax for math).

At a first glance, it’s well-put-together; it builds on existing tools and standards (Markdown, MathJax) and provides features that I want in my writing (live preview, good presentation of math). It’s too bad I am not writing a book.

Or am I?

I’ve had my website for almost 20 years now, and every few years I revisit my choice of authoring tools. It’s been a long series of disappointments; every time I discover there is no good tool that meets my requirements:

1. The act of writing new content must not require editing raw HTML
2. My content must be stored in a format from which I can relatively easily migrate it to another tool
3. I must have complete control over my URLs, including the ability to keep URLs working indefinitely even if the underlying content is reorganized

Of course, there are a lot of nice-to-haves, but those are the minimum requirements: semantic and long-lasting URLs, no lock-in, no markup required for writing.

Broadly speaking:

• Many professional website authoring tools require editing bare markup.
• Many consumer website authoring tools on the desktop either store website data in a proprietary format or as raw HTML (both of which are impossible to sanely migrate to another tool)
• Many web-based authoring tools don’t have much support for URL longevity

Consequently, I am resigned to having to use some combination of niche tools. And while there are a lot of website generator tools in existence, very few of them have what I would call a decent editing experience.

(Editing experience is actually much better now that everyone supports Markdown — as long as you want to do things that Markdown is good for. As soon as you step out of that box (for example, with equations), you fall off a very steep usability cliff.)

So, when I discovered that someone had created a publishing tool that understands Markdown, works with math, and outputs HTML, I knew it was time to revisit my choice of tools again.

Out of the box, GitBook fails requirement #3; it generates URLs ending with “.html”, and GitBook-hosted books don’t support redirects.

I had to make some pretty major tweaks to GitBook (to produce better URLs, automatically generate category indices, produce an Atom feed, etc), which I packaged as a plugin.

The plugin is not ready for public consumption yet, but if you are feeling foolish you can get it from the plugin repository.

Having done that, I am now using GitBook Editor to edit my blog — which gives me a Markdown editor with live preview and MathJax support — and the GitBook command-line tools to generate a pile of HTML files ready for web server deployment.