Migrating from HermesDocs v1 to v2

Upgrading to v2 is straightforward. Here’s what changed and how to update.

Version URLs

v1: Versions used query params: /docs?version=v1
v2: Versions use paths: /docs/v1, /docs/v2

Update any hardcoded links and redirects. The version switcher now generates path-based URLs automatically.

Content Structure

Version-specific content lives under src/content/docs/ with a version field in frontmatter. Split content by version if you have different docs per release.

Configuration

src/config.ts gains new options for healthchecks and status page. Existing config remains valid; new fields are optional.

Theme Toggle

The theme toggle now uses a simple light/dark switch instead of a three-state cycle. If you customized the toggle logic, update it to match the new behavior.

View Transitions

v2 enables Astro View Transitions by default. If you have custom scripts that depend on full page loads, test them—some listeners may need to use event delegation.

Checklist

1. Update internal links to use path-based version URLs
2. Test the theme toggle on all pages
3. Verify search works with your content
4. Add healthchecks to config.ts if using the status page
5. Run a build and fix any deprecation warnings

Need help? Check the full migration guide in the docs.