Developer's Diary
Software development, with Terry Ebdon
20-May-2020 GitHub Pages

Table of Contents

Slow GitHub Pages deployment

This blog is hosted on GitHub Pages, which can be a problem. I generate a static site, using my WebDoxy tool (a wrapper around Doxygen). I commit the generated files and, hopefully, GH Pages will deploy the site. It doesn't always work, and the reasons are rarely obvious. The site is marked as pending, following the commit, then there's a random delay before the site deploys. The "experts" on Stack Exchange claim deployment occurs within 10 minutes and you have to have a Jekyll theme, even if you don't use Jekyll. In my experience, none of that is true. Yesterday it was sometimes taking over an hour for GitHub to deploy the site.

Bad UTF-8 breaks deployment

When I first committed a GH Pages site, three years ago, the site never deployed. After it had sat in pending for 24 hours I deleted the repository and started from scratch. It failed again. I eventually tracked the issue down to an invalid Unicode character in a markdown file.

Missing pages

Yesterday's deployment looked good,until I noticed the About Me and Photography pages were missing. Clicking a link to them resulted in a 404 error. Yet the files were present in the repo and I'm pretty sure they used to work. Everything was fine on my local machine, this was a GH Pages issue. I realised these were the only two page with a leading underscore in the name. But why would that make a difference? The '_' was due to Doxygen's CASE_SENSE_NAMES setting. On Windows and Mac this defaults to NO, causing Doxygen to change Photography to _photography and AboutMe to _About_Me Adding CASE_SENSE_NAMES = YES to the project's Doxygen configuration allows GH Pages to recognise the files. That's a pretty odd requirement. But it still wasn't quite right. I've enabled the tree navigation bar, which works fine … unless you're viewing a sub-page of Photography. That's a minor GitHub bug, I'll put up with it. Again this works fine locally, it's only an issue on GitHub Pages.

14-MAY-2020 👈 Top of page 👉 24-MAY-2020

© 2020 Terry Ebdon.

Find me coding on GitHub, networking on LinkedIn, answering questions on Stack Exchange and hanging out on twitter.