alm

alm Site Blog

Version 3.1 and XSite

Published on 2021-04-25

If you're reading this, that means I've rolled out alm 3.1. This version is based on the XSite static site generator. I wrote this software myself, as is the expected rite of passage for programmers doing Web sites; it's based on XML and written in Python, with an eye towards both relative simplicity and a strict content structure. Currently, it's less than 300 lines of code, which feels small for how much it's managed to do.

XSite doesn't currently support Markdown, so the process of switching from Jekyll to XSite was fairly complicated. It took over a dozen Git commits and seven hours of work. I started by modifying the Jekyll templates to remove the Liquid tags, replacing them with XSite's equivalents or discarding features XSite can't yet implement, and to convert from HTML to XML syntax where the two differed. I also replaced <!DOCTYPE html> declarations with <?xml version="1.0" encoding="utf-8"?> declarations and XHTML namespace declarations and added XSite processing instructions for template inheritance.

The part that took the longest was converting the content. At first, I used the Markdown files as a starting point, manually converting the Markdown syntax to XHTML, but later I started using the output from Jekyll instead, which was faster, especially for big pages. I replaced the YAML front-matter Jekyll used with the XML processing instructions XSite uses, and added some meta keywords here and there while I was at it.

The reason this conversion took longer than the Jekyll conversion is largely down to the blog. XSite has no blogging features, so I had to manually implement the entire blog structure, including the blog index. Also contributing is that there is simply more content on this site than there was when I converted it to Jekyll, and XHTML is of course more verbose than Markdown, so there was more typing.

One of XSite's nice points is that it generates relatively clean output. If you look at the source of any of the pages on the current site, you'll won't see any of the blank lines or jumpy indentation that Jekyll and Liquid are prone to produce; this is because XSite is parsing the XML (using the lxml Python package), doing its processing at the element level, and then reserializing back to text, rather than working at the raw text level like Jekyll, so it can format its output nicely.

I wouldn't recommend using XSite for your own site just yet, though (if what I've already said doesn't dissuade you enough, it's probably buggy as well). I'll probably continue to hack on it and implement a few more of my ideas, probably including XSLT support. XSLT will make it a lot easier to implement blogging functionality, like automatically generating an index of entries, so I hope that it will be usable for the real world at some point soon.

You can see the process I went through for this migration in this GitLab merge request.

Changelog for version 3.1

  • Switched from Jekyll to XSite
  • Simplified blog index to be easy to maintain by hand
  • Remove conditional behavior from navigation (may have a negative impact on accessibility, to be addressed once XSite is capable enough)

Tagged: Updates, Site, Projects, V3.1