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:
- The act of writing new content must not require editing raw HTML
- My content must be stored in a format from which I can relatively easily migrate it to another tool
- 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.
- 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.