I’ve been meaning to clean up my blog for a while and was intrigued by the ability to serve complete websites from github. Sure, these have to be static websites but for what I do with my blog I don’t see that as much of a limitation. As a secondary benefit I was hoping to finally get my pictures back online and the VCS via generator to static web format seemed good for that.
Which static site generator to use?
The obvious initial answer was Jekyll because then github could take care of compiling and serving and I theoretically like the file layout. Practically, however, I was too late to that game and with Jekyll 3 things are so broken that you might be able to use the minimal theme but anything beyond that is likely only going to work if you do the generation on your end and check in the results. So what are the alternatives?
Apparently this is a topic of some importance with its own site dedicated to tracking this. As of this writing the favorits are jekyll, hugo, and hexo. With jekyll out of the running, hexo seemed easier to adopt.
Framework vs. Theme
Maybe the hardest bit to understand is where the framework ends and the themes begin. This appears to be a problem with all of the static site generators, presumably because they are trying to be “flexible” instead of “opinionated”.
Fixing up the landscape theme
Hexo 3 ships with the “landscape theme” which has a good set of starting functionality and works well on mobile too. Sadly there are a few things that you will need to modify in the theme right away: the banner image and the navbar links. Once that’s done you should be good for a while.
To change the banner image:
|
|
To modify the navbar, e.g. to add an about section, create a static page
|
|
You will notice that this cdreatd a subfolder called /about/ with an index file in it. You may subsequently edit the index file and maybe even change the title in the front matter, e.g. for proper uppercasing to “About”. However, it is the directory that will be referenced going forward. You now need to add the name of this directory to the theme configuration, in my case the landscape theme:
|
|
then edit the file to point at your about page. Note that the key “About” will be the text in your navbar while the value “about” is the name of the directory referenced to find the relevant page:
|
|
Adding a favicon
Simply add an image in source/favicon.png and hexo will do its magic to create a favicon.
Making RSS atom feed work
The landscape theme has an RSS icon but when you click on it nothing happens. To resolve this simply include the relevant generator which will then automagically create the missing atom.xml file:
|
|
Creating a sitemap
Just like for the atom feed, there is a hexo generator that will create a sitemap:
|
|
However, this only creates a sitemap file in /sitemap.xml. While I expect that some crawlers will find this explicitly, it is probably a good idea to reference the sitemap using robots.txt, maybe like so:
User-agent: *
Disallow: /tags/
Disallow: /categories/
Disallow: /archives/
Sitemap: https://artiverse.github.io/sitemap.xml
This particular configuration will also exclude crawling of the autogenerated locations which matches what the sitemap creates.