Skip to content

Automatically version documentation assets to prevent stale caches - #121

Merged
csandanov merged 2 commits into
masterfrom
fix/docs-stylesheet-cache
Sep 23, 2026
Merged

csandanov merged 2 commits into
masterfrom
fix/docs-stylesheet-cache

Conversation

@csandanov

@csandanov csandanov commented Sep 23, 2026 •

Copy link
Copy Markdown
Member

Custom theme assets previously kept the same URLs after their contents changed, allowing caches to serve old CSS, JavaScript, logos, and favicons after a deployment. Both documentation versions now generate content-hashed filenames for these assets and reference them in rendered pages. Unchanged assets retain their URLs, while changed assets automatically receive new ones.

A shared MkDocs hook handles versioning, including repeated development builds. Logo styling supports the generated filenames, and CI runs asset-versioning tests. Existing source asset URLs remain available for compatibility. No cache-purge credentials or deployment purge step are required.

Validation:

  • Both strict documentation builds and the 1.0 link check pass.
  • Three asset-versioning tests, nine documentation export tests, and the documentation contract check pass.
  • All 1,370 generated hashed asset references resolve to emitted files across both versions.
  • Browser verification confirms the new stylesheet and logo URLs render correctly.
  • git diff --check passes.

@csandanov csandanov changed the title Fix stale documentation styles after deployment Automatically version documentation assets to prevent stale caches Sep 23, 2026
@csandanov
csandanov merged commit 3e202e2 into master Sep 23, 2026
1 check passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant