All writing

How I Add a Devlog to Every Game (and Why It's Just Markdown and HTML)

By Bronson Dunbar ·

My games each get a public development log: Piko, Venture Life, and Ash & Oath. Motive's is on the way. The same log also appears on each game's page on this site.

A devlog is the simplest form of building in public. It shows players the game is alive, gives search engines a steady stream of new content, and reminds me how far each game has come. But it only works if it stays up to date, so the whole system is designed to make that nearly effortless.

One Markdown file per game

The devlog lives in the game's repo as DEVLOG.md. There's no CMS and no database. Entries are grouped into months, newest at the bottom, with a heading format strict enough to parse:

## Release summary

| Version | Date | Headline |
| --- | --- | --- |
| 1.0.1 | 2026-08-14 | First Mac and Windows desktop builds |

## August 2026 — First build and foundations

### 2026-08-12 · The first playable Piko (`0cf5d63`, `55ed43c`)
- A cozy virtual-pet game for the browser, inspired by 1990s pocket companions.
- **Six companions:** each with its own habitat and weather they love.

The key detail is in the heading: the commit hashes that each entry covers. They're stripped from the published page, but they connect the log to the git history, and that's what makes the next part possible.

A script that tells me what I haven't logged

npm run devlog:check compares the git history with the hashes in DEVLOG.md and lists every commit since the newest logged one. Its output looks like this (example commits):

devlog: 4 commit(s) since the last logged one (a1b2c3d4):
  2026-11-14 9f8e7d6c Add Prism Run high scores
  2026-11-15 5a4b3c2d Fix bathroom bubbles on iOS
  ...
Add the bigger ones to DEVLOG.md (minor ones can be folded in by hash).

I don't have to remember what I've shipped since the last entry: the script tells me. Small fixes get folded into an existing entry by adding their hash, so they stop showing up as unlogged without cluttering the page.

Two design choices keep it from becoming a chore:

  • It never fails a normal build. It just prints the list. A --strict flag makes it exit with an error, for when I want to enforce it.
  • It copes with shallow clones. Hosting providers like Vercel often build from a shallow clone with no history. The script notices, prints a note and moves on, instead of breaking the deploy.

The build renders the page

At build time, a small parser (about a hundred lines, no dependencies) turns DEVLOG.md into a static HTML page at /devlog. It:

  • reads the release table and the monthly sections
  • turns 2026-08-12 into "12 Aug 2026" and supports date ranges for multi-day work
  • applies a tiny subset of inline Markdown (code, bold, italics and links) after escaping everything else
  • removes the commit hashes
  • reverses the order, so the newest entry is first

Nothing generated is committed. The Markdown file is the only source, so a deploy always ships the current log. Tests check that the file still parses and that the page is still in the sitemap, so a malformed heading fails the tests rather than silently dropping an entry.

Because it's a real static page with a title, a description and structured data, the devlog is also an SEO page. Each update is fresh, indexable content about the game, written as a side effect of shipping.

One HTML contract for every game

Each game has its own code, but all of them render their devlog with the same markup:

<li class="devlog-entry">
  <article aria-labelledby="first-playable">
    <time datetime="2026-08-12">12 Aug 2026</time>
    <span class="devlog-version">1.0.0</span>   <!-- optional -->
    <h3 id="first-playable">The first playable Piko</h3>
    <ul>
      <li><strong>Six companions:</strong> each with its own habitat…</li>
    </ul>
  </article>
</li>

That shared contract is what lets this portfolio show the latest entries for every game without any API.

Reading it back on this site

When this site renders a game's page, it fetches that game's public /devlog page on the server, finds every li.devlog-entry article, and keeps only the text: the date, optional version, title and bullets. No HTML from the remote page is ever rendered, so a broken or compromised devlog can't inject anything here. A bullet that starts with a bold "Lead-in:" keeps the lead-in separate so it can be styled.

const entries = doc.querySelectorAll("li.devlog-entry article").map((article) => ({
  title: clean(article.querySelector("h3")?.text ?? ""),
  date: article.querySelector("time")?.getAttribute("datetime") ?? null,
  version: clean(article.querySelector(".devlog-version")?.text ?? "") || null,
  bullets: /* each <li>, as plain text */,
}));

The result is cached for an hour. If a game's devlog can't be reached, or its markup changes and nothing parses, the section is simply left out. A devlog is a nice extra on a project page, never a reason for it to fail.

Why this setup works for me

  • It lives with the code. I update the log in the same commit as the feature, often in the same editor session.
  • It reminds me. devlog:check turns "I should update the devlog" into a list I can work through.
  • It's plain. Markdown in, HTML out, no services to pay for or keep running.
  • It's reusable. A shared HTML contract means any site, this one included, can read any game's log.

Most of all, I think it's nice for players to see how a game develops and grows. A devlog turns a list of updates into a story they can follow from the first playable build onwards.

If you make games, start a devlog today. It doesn't need to be fancy, it just needs to be easy enough that you keep it going.