Project Review

Our project to rebase XProgramming.com has a number of aspects, all of which are important. To review the objectives:

  • Ultimately host all of XProgramming.com, or at least all but the most arrant crap.
  • New writings to be done in Markdown.
  • Articles in separate folders, article assets in same folder.
  • Be a completely static site. (Client-side JavaScript allowed.)

Technically, here are some highlights:

  • We started thinking we’d use Sinatra. That results in a non-static site, and thinking about that is what made it clear that we didn’t just want to get off WordPress, we wanted to be completely static.
  • We need to “scrape” all the WordPress articles and get them in shape to be put up as static HTML. We chose nokogiri for that part.
  • We’re converting the articles to Markdown to match the desired style for writing.
  • We need to scan all the folders, convert markdown to HTML, fold in all the various CSS and such, ready to push to a static site. Using Jekyll for this at present.

Our planned flow

Here’s a picture of our planned workflow. We export from WordPress to XML, “scrape” the XML to make folders full of articles, use Jekyll to get from the articles to static HTML, then use Transmit to put the files on the web site. And here we are!

Learnings and Findings

We rather liked Sinatra. The ability to use ERB with its embedded Ruby was powerful and as we’re comfortable with Ruby, it was a good choice. But maintaining a live Ruby site would be almost as much trouble as a WordPress one, so we regretfully moved on from Sinatra.

We do believe that Middleman runs on top of Sinatra but an intial look at Middleman did not grab us.

We chose Jekyll more or less randomly, and in part because its documents look so nice. Unfortunately, the look is misleading: one needs much more explanation and more examples than are forthcoming. But we muddle through.

Jekyll uses Liquid for template rendering. Liquid is sort of an emasculated Ruby dialect. It has been bent and twisted so that no one could do anything bad on Github, which runs Jekyll live to generate sites. Good for them, not good for people who want to do anything tricky.

What’s tricky, you ask? Well, one example is paginated index pages. It’s easy to see how you’d do that in a real programming language: grab N articles at a time, generate an index page, grab N more, generate another page. While Liquid has support for pagination, it only applies in its blog mode, which requires specific folder and file name formats. That’s not good for us.

The solution, to jump ahead, is to build a “plug-in” for Jekyll, and generate the index pages there. We’ve not done this yet, but we expect no serious difficulty.

But the concern got us thinking about not liking Liquid, so we spent yesterday talking about alternatives. I like to consider alternatives, especially early on in a project, but there is always the cost of switching. One imagines that cost to be low and the cost of staying the course to be high, because one imagines that the new technology will make everything so much easier. A half century of experience to the contrary has not disabused me of this notion. (I also get this way about cars.)

Nonetheless, cooler heads are still prevailing, and we’re sticking with the current approach for now.