HOWTO: Latest GitHub Release Metadata in Documentation

Published February 1, 2024

Somewhat recently1 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. 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 and narrowed it down to this API signature:$USER/$REPOSITORY/releases so for me that looks like 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:

(async () => {
  const response = await fetch(``)
  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/, '')}`))

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.

  1. Going by the commits, 6+ months ago in July 2023↩︎

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

← Newer post  •  Older post →