The Background

The annual hosting bill was due next month, but I wasn’t happy with Joomla and I didn’t feel like organizing another whipround to pay for it. Also, the nwcpp.org domain was about to expire and Network Solutions wanted a surprisingly large amount of money to renew it. So I transferred the domain to Namecheap and set to work creating a static site.

A CMS like Joomla seemed like a good idea when I took over from the previous webmaster three years ago. The preceding website had been built with CityDesk, which generated static HTML files and required a lot of messing around with FTP. Joomla turned out to be a big pain and I spent a lot of time fighting with it. And then there was the time when I was on vacation and learned that the NWCPP website had been defaced, thanks to an unpatched vulnerability in our installation.

A recent trend has been to move away from CMSes and dynamic blogs to static site generators for simpler sites. I wanted to explore some of them and I quickly settled on Pelican. It’s built on Python (my primary language nowadays) and accepts input in the lightweight markup languages, reStructuredText, Markdown, and AsciiDoc. I have extensive history with reStructuredText, though I would also have been happy with Markdown.

In a typical CMS, the content is stored in a database. I’m a developer; I like Git for version control of my documents. Pelican and other SSGs lend themselves to this.

Converting HTML to reStructuredText

I mirrored the Joomla website with Wget and used Pandoc to convert the HTML to reST. That was followed by a lot of hand-editing to clean up the files—13 years of near-monthly meetings led to about 150 files. In retrospect, I could probably have saved some editing time if I had used BeautifulSoup to filter out some of the HTML cruft on each page before feeding it to Pandoc or html2rest.

I set up Pelican, plugged the reST in, and ran the devserver locally. Already, it looked pretty good.

Multiple Identities at Github

I wanted to create a separate Github identity for nwcpp, as I won’t be the webmaster forever. That was a little tricky to manage, but I found enough clues in a StackOverflow question to figure it out.

Here’s my ~/.ssh/config:

Host github-gvr
    HostName github.com
    User git
    PreferredAuthentications publickey
    IdentityFile ~/.ssh/id_rsa
    IdentitiesOnly yes

Host github-nwcpp
    HostName github.com
    User git
    PreferredAuthentications publickey
    IdentityFile ~/.ssh/id_rsa_nwcpp

I have two SSH keys: github-gvr is tied to my primary Github account while github-nwcpp is tied to the NWCPP account. Note the IdentitiesOnly.

I have to use a different git remote for the latter, instead of git@github.com:nwcpp/pelican-site.git:

$ git remote -v
origin      git@github-nwcpp:nwcpp/pelican-site.git (fetch)
origin      git@github-nwcpp:nwcpp/pelican-site.git (push)

Github Pages

Github Pages is an easy, free way to publish static websites from a Github repo. Pelican provides documentation on publishing to Github Pages.

To get the nwcpp.org domain hosted there, I had to set up a custom domain and change the Namecheap DNS configuration. I also had to add a CNAME file to the repository and ensure that Pelican published it to the root of the output.

Contact Form

I wanted to add a contact form rather than publishing email addresses for the NWCPP board. Obviously, there’s no server-side piece in a pure static site, so it has to be handled by a third party. I found a helpful article on setting up a Google Docs contact form, which emails us as well as saving the form details in a spreadsheet.

Conclusion

Pelican is fine for me and I’m much happier with it than Joomla. It clearly wouldn’t work for non-developers.

One annoyance is that Pelican is very blog-centric and wants to generate a timeline of posts. For dated announcements of monthly meetings, that works very well. For pages that don’t fit on the timeline, such as the contact form or the sponsorship howto, it’s awkward.