HOWTO: Latest GitHub Release Metadata in Documentation

Published February 1, 2024

Somewhat recently¹ I decided to dynamically add the latest semver release to the technical documentation for a personal project of mine, bic. This outlines how I did so.

A few things I wanted from the start:

1. The feature should be a progressive enhancement and should only add to the experience.
2. In particular, I wanted to change from a :latest Docker image tag to the actual latest release e.g. :1.0.0-beta.2.

Since my releases are done via the native GitHub Releases feature e.g. https://github.com/Pinjasaur/bic/releases I figured I could leverage their own API to pull the releases for the repository and grab the most recent one. I tracked this in https://github.com/Pinjasaur/bic/issues/11 and narrowed it down to this API signature: api.github.com/repos/$USER/$REPOSITORY/releases so for me that looks like https://api.github.com/repos/pinjasaur/bic/releases. And for me, I’m able to grab the first (index 0) item from the response and the tag_name key has the information I’m after e.g. v1.0.0-beta.2.

Now, I added a few lines of JavaScript to the documentation to pull it all together:

<script>
(async () => {
  const response = await fetch(`https://api.github.com/repos/pinjasaur/bic/releases`)
  const releases = await response.json()
  document.querySelectorAll(`.js-release`).forEach($el => $el.textContent = releases[0].tag_name)
  document.querySelectorAll(`code`).forEach($el => $el.innerHTML = $el.innerHTML.replace(`bic:latest`, `bic:${releases[0].tag_name.replace(/^v/, '')}`))
})();
</script>

Let’s break that down:

1. Grab the release data from the GitHub API.
2. Enumerate all elements with a js-release class and set the inner content to the tag_name verbatim.
3. Enumerate over all <code> elements and specifically find-and-replace any :latest Docker image tags with the latest tag_name sans the leading v prefix.

I’m a fan of this subtle enhancement to the docs and I intend on doing another similar post that focuses on embedding metadata into the application itself e.g. container, healthcheck, source code, etc.

Last modified January 28, 2024  #howto   #dev   #documentation