GitHub lets you publish websites using Jekyll, a static site generator that converts your code into a full HTML website. The combination of GitHub and Jekyll is pretty cool and has some nice benefits:
- Host your site for free under a custom domain,
- Use reusable layouts and dedicated blogging tools,
- Power pages with structured YAML data,
- SASS preprocessing for your styles,
- Rely on familiar Git/GitHub processes like version control and pull requests.
Starting simple with GitHub Pages
I started out really simple. At the time, I had a server-side rendered personal homepage basically showing my resume online. I took the generated HTML output of that, put it as the index file in my new GitHub repository, and configured the DNS settings of my domain to show the GitHub served website.
All this requires just a few small steps. Create a GitHub account, create a repository named <your-username>.github.io, add a file index.html with some markup, and a file CNAME containing your url. In my case, this was simply www.dennisclaassen.nl. There’s a bit of DNS configuration required, but GitHub itself has great documentation on that.
When initially exploring Jekyll and its features to generate a website, I found it was Ruby based using a template language called Liquid, and supported data files. I decided I could leverage these features to reduce code repetition and to separate data from the presentation. Jekyll supports using data files in different formats. So I went ahead and extracted all my resume data into YAML files.
Doing this can be pretty straightforward, since the data and the html format in which it’s presented already exists. First, extract all individual entries over to files in a new _data folder. YAML markup allows using consistent names for different properties, and adding multiple entries in a single file. After that, strip out the data from the HTML files, leaving behind a nice template to insert the data in. Now pull in the data using {{ site.data.<name-of-yaml-file>.<property> }} or to loop over data use {% for data in site.data.<name-of-yaml-file> %} {{ data.<property> }} {% endfor %}.
When I made the next step in my career, updating my resume was just a few data file changes to add my latest experience.
The initial commit in which this approach was implemented, can still be seen at https://github.com/d-claassen/d-claassen.github.io/commit/f76bf636db50b93ac3b5c92ef5044b59f84abe81
From resume site to SEO playground
After I joined Yoast, I revisited my personal site for the first time in a while. Updating it with my new role was easy, just a few additional lines in my YAML files. But it also sparked something: I wanted to bring new learnings into practice. That meant adding a blog to share lessons, to create my personal SEO playground where I could play with technical SEO topics like structured data in a way I fully controlled. So I started working out a GitHub-style navigation, borrowing from their directory-like look, for the blog. This actually turned into an interesting exercise in Jekyll’s data model.
To build the directory-like listings, compare the local page context to the global site.posts collection. Compare the parts from page.path | split: "/" with the parts from post.path | "/" for each post in site.posts. This can be used to find direct children of a page, both subcategories and posts. Also, since site.posts is sorted on date, it allows to find the most recent post in a subcategory. And even though the logic gets complex and more blog posts result in more iterations per loop, the fundamental concept of a static site generator ensures fast pages for visitors while the listing still feels dynamic.
With the blog prepared and a few posts up, the playground was ready to be put to use. The homepage still used microdata markup, which I transitioned to JSON-LD first. This gave me more flexibility in the visual representation of my content, removing specific nesting structures and additional HTML nodes to have structured data in the right relations. Then I went on to generating JSON-LD markup from my YAML data files. This felt very natural, as a proper separation between data and presentation, but now required tweaking in 3 different places for changes: the data files, the visual presentation, and the structured data markup.
Leaving Jekyll for WordPress
At a certain point I was struggling with structuring the data format in my YAML files for another iteration of both my visible (user-facing) blog and my invisible (bot-facing) schema.org blog. Eventually, I figured it out. But hand writing the data files and the schema output was tedious.
Then my employer organized a conference. Cool! Right?
I had attended a few more conferences in the past and decided it’d be good to keep track of what I attended, what I had learned (and from who), and who I had met. But as for my other pages, I’d want matching structured data telling the same thing.
I was not going down that road again.
What obstacles were on this road? Since events are organized by organizations, and my employer already appeared in my dataset as part of my resume, I wanted to reuse that data node rather than duplicate it. But I wouldn’t want my entire resume on these event pages. And deciding which organization to output when, would require another iteration over my handwritten data sets and schema generation, and probably content generation too. Then, hand-writing this new set of output was not very appealing. And taking on the burden of maintenance for structures data about events neither.
That’s when I decided to leave this platform, and migrate it all to WordPress. Luckily I knew I’d have Yoast SEO available, and I would use The Events Calendar as a referred schema integration to track many of the events I’ve attended since.