Semantic-docs

• Semantic Docs Spring Update: Astro 6, Auto-Releases, npm

  The last two months on Semantic Docs have mostly been maintenance work, but a few things I wanted to talk about. I pushed through a major framework upgrade, swapped out a vendored library for a real published package, and finally automated the release pipeline. Five tagged releases later, here’s where we are.

  The Headlines

  • Upgraded to Astro 6
  • Switched from a vendored logger to the published logan-logger npm package
  • Shipped an auto-release workflow driven by Conventional Commits
  • Three rounds of dependency updates plus a security-focused sweep
  • Five tagged releases, v1.3.3 through v1.5.0

  Astro 6

  The Astro 6 upgrade was easy. Semantic Docs runs a hybrid setup, static article pages plus a server-rendered search endpoint, and that part barely needed any attention. Most of the work was in the dependency layout, not the application code.

  One note if you’re forking or syncing this theme: if you’re upgrading from v1.3.5 or earlier (anything pre-Astro-6, which landed in v1.4.0), delete your node_modules and your lockfile and do a clean install. Skip that step and you’ll get weird errors that look like your code is broken when it’s really just leftover state.

  A Real npm Package Instead of a Vendored Logger

  For a while, the project was using a logger I wrote to experiment with publishing to both npm and JSR. It was a useful exercise. I wanted to see what a clean foundational package looked like across both registries, and I think it turned out well.

  But for this repo, I wanted consistency over experimentation. So I swapped the vendored copy for the published logan-logger npm package. Behavior is the same, the surface area is the same, it’s just back on the npm registry.

  Automated Releases

  I’ve liked using Conventional Commits to drive automated releases. When a PR merges to main, the workflow figures out the next version from the commit messages, tags it, and publishes a GitHub release with a generated changelog.

  The commit type determines the version bump. feat: bumps the minor, fix: bumps the patch, breaking changes bump the major. The changelog falls out of the same metadata. More automation here the better.

  If you’ve been on the fence about Conventional Commits, this is the use case that sold me.

  What’s Next: Embedding Quality

  The reference implementation uses TEI for search embeddings, and that’s been fine. But “fine” is not the same as “good,” and I want to actually compare quality across providers before I commit to anything long term.

  Two I want to test:

  • Jina (now owned by Elastic)
  • Mistral, which has been putting out genuinely strong embedding models

  The goal is to run the same corpus through each, evaluate the search results, and figure out which one earns a highlight. Whatever I learn from that work will get folded back into the open source Semantic Docs repo so anyone running their own instance can make an informed choice instead of just trusting my defaults.

  I’d appreciate a follow. You can subscribe with your email below. The emails go out once a week, or you can find me on Mastodon at @[email protected].

  May 9, 2026 / DevOps / Open-source / Astro / Semantic-docs

  Enjoyed this?