Introducing My New Blog

Welcome to my new blog. It may seem a lot of effort to switch from one blog to another. But I've been working with Material for MKDocs for some years, thanks to Stephan Wissel, and it's a great framework for documentation. I've been aware of the blog plugin for some time, so it made sense to consider it as a good fit for the future.

Don't get me wrong, Jekyll and GitHub Pages was the right choice for me back when I started the blog in 2016. It was still the right choice for me when I joined HCL and started blogging more frequently in 2019. But the right choice changes, depending on how the frameworks evolve and the individual's experience and level of comfort with both the framework and ancillary technologies.

My experience of Jekyll has not increased much, even though my level of experience with Liquid did increase when setting up HCL's open source site. On the contrary, my experience with Material for MKDocs has increased massively through Domino REST API documentation and using it extensively for VoltScript documentation. There are places where it's not as flexible - integrating non-static data into a page. But there are places it offers significant usability improvements that I cannot easily solve with Jekyll, with better anchor tags in blog posts, nicer integration with code samples, better annotations, easy integration with Mermaid JS for diagramming. Note, I don't say they can't be solved, it's that they're more easy for me to solve with MKDocs.

But the opportunity to migrate a blog is also a good opportunity to leverage other learning to improve the content.

Visual Studio Code

My experience of Visual Studio Code has significantly improved since I started blogging. Alongside it has improved my use of extensions and other quality improvements.

Markdownlint

All our VoltScript documentation sites use Markdownlint configuration to tailor settings, as does the Domino REST API documentation. There are a variety of settings that are overridden, some for personal preference. But cleaning up the Markdown definitely makes me feel a lot happier with the quality of the content.

Code Spell Checker

One of the de facto plugins I use with all my documentation is Code Spell Checker. As I've gone through updating all the blog posts, I've picked up a number of typos thanks to this plugin. It will almost certainly help minimise the number of typos in future blog posts too.

Problem Pane

The right-hand gutter of the editor in VS Code is very useful for seeing errors visually - yellow for Markdownlint violations, blue for typos. But the problems pane allows you to see them all quickly and easily navigate to them. The key to using any IDE is learning and leveraging what it offers out-of-the-box - as I found when Domino Designer was rebased into Eclipse.

Material for MKDocs and Docker

My preference, where possible, is always to use Docker containers for development. It helps keep the host clean and minimises problems with technology conflicts. Material for MKDocs is no different. Stephan Wissel set up a customised Docker image for MKDocs which is used by HCL. But this was missing some plugins I needed and, with the Docker skills I've honed over the years, creating a custom Dockerfile from the main Material for MKDocs image was not difficult.

The difficult part was that I had an older image of Material for MKDOcs locally, and the build didn't work. A rookie mistake, solved by pulling down the latest image first. Once I did that, everything built fine.

Professional Bio

In my old blog, my professional bio pulled from JSON files and added styling to show and hide sections. I could have done the same in MKDocs, with a single page, but it was a good opportunity to split it into different pages. I think this provides a cleaner navigation.

Post Updates

The big difference between Jekyll and MKDocs is the frontmatter that's needed. There are also differences to how relative links are done. All images had been referenced with absolute links, which are discouraged by MKDocs. I was also using post excerpts and validating in the mkdocs.yml to force every blog post to have an excerpt. And doing things like tags and categories is different.

So unfortunately that meant modifying all blog posts. That was a few hours work, but gave me the opportunity to fix any of those quality issues I mentioned above. So worth doing.

But it also allowed me to add a page linking to all blog series, which will hopefully make it easier to track linked blog posts.

RSS Feeds

Unfortunately, the change means the RSS feed URLs are changing. But I realised as I was doing this that there is nothing in the old site to tell users about the RSS feeds. So I added something.

Comments

GitHub Discussions are something added a few years ago to GitHub repositories. This allows you to store comments in GitHub, and Material for MKDocs has easy-to-follow steps for integrating Giscus, which has a GitHub application that you can integrate with specific repositories. So I've decided to take this opportunity to change my commenting engine to use Giscus.

Based on the direction my career has gone over the last five years, as well as the increased usage of GitHub, expecting my audience to have a GitHub account is very reasonable. But there may be other ways added to manage discussions in the future, options which I can't talk about at this time.

Summary

Hopefully you will enjoy the new site. But I'd welcome feedback.