The landing page/index for the site does not currently include any posts (specifically the dummy post that exists at the time of writing). This is due to the default layout, which does not account for posts or any included user-defined content.

This should be changed to incorporate a list of the existing posts.

It's easy to forget to generate (up to date) diagrams from Mermaid definitions, especially when there are multiple diagrams per post. This is complicated by the process of adding copyright notices to the generated diagrams using an additional process, as Mermaid does not (yet) support adding captions to all its diagrams formats.

Writing a Makefile recipe would automate this process by capturing the required steps and, if written appropriately, would ensure all diagrams which are out of date relative to their definitions are automatically regenerated when the recipe is run.

In turn, this would support a GitHub Action to detect (or even automatically fix) the issue of stale images for diagrams. This additional functionality would be deferred to another issue, but is mentioned for completeness of context and motivation.

Much like the disclaimer, having the copyright notice somewhere immediately visible is important for conveying the conditions surrounding that from the outset.

Tags should be displayed both on post pages for post-specific tags and also as a full list on the index page.

This is a continuation from #21.

Currently there are two separate layouts for posts and other pages. However, these layouts are very similar, with the only base-level difference being that posts do not include the site's description/tag-line. Whilst I like the cleaner look of this for posts, as it removes a little bit of visual noise in a context wherein there is plenty else to focus on, it does mean keeping two highly duplicative layouts. Furthermore, it is not immediately obvious that these layouts have a lot in common.

At this stage it is not a significant concern either way, so it seems slightly easier to maintain if the post layout is explicitly based upon the default one.

A post layout may wish to remove the tag-line/blog description, for example, in order to have a cleaner, more legible style. It may also be sensible to have the post title, date, any tags, and any author(s) defined at the top.

Implementing this will require defining a new Jekyll layout under docs/_layouts. To this end, it may be desirable to refactor the default layout and have separate page and post layouts that handle the header section and other such information differently.

It would be interesting to gain insights on how many people are viewing pages and so on. There is support built in for Google Analytics, making this a reasonable starting point for collecting such information.

Things like adding a title in the front matter, defining a top-to-bottom flowchart, and adding the same styling for focus, supporting, and consuming systems is standard boilerplate which is tedious to have to copy/paste.

Instead, a Makefile recipe which accepts a file name would make this more convenient.

The blog should have a landing page that provides an overview of the (sorts of) content. It may also wish to provide a brief explanation of the blog name.

Currently the blog/site title does not change its appearance on hover, with the only visual indication it can be clicked coming from the change in cursor type. Changing colour would provide an additional visual indication of how to navigate the site.

By separating the credits/attribution from the header section, it has lost the styling from the original theme.

Compare the current state:

with that of the original theme:

This seems to be due to the SCSS rules defining credits only for the #title ID, rather than for a general .credits class within a section. See here.

The solution is likely to be overriding/extending the SCSS rules.

For longer posts, this provides a convenient means of not only navigation, but also quickly assessing content.

I'm not sure if Jekyll has an in-built way of listing page headings, but hopefully there is some reasonable way of approaching this without delving into plug-ins.