@chassis-ui/docs 0.10.0 → 0.11.0

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # @chassis-ui/docs
 
+## 0.11.0
+
+### Minor Changes
+
+- **Breaking.** The head links the web app manifest of the docs build of `chassis-assets`, `other/manifest.json` under the static path, in place of `images/manifest.json`, which each site provided itself. chassis-assets added it in `v0.5.0` of `app/docs` on 2026-10-23, with a maskable icon. A site moves its `vendor/assets` submodule to `v0.5.0` or later with `pnpm sync-submodules`, and deletes its own `images/manifest.json`; with an earlier commit the page links a manifest that is not there. The starter keeps a manifest with its own name at `static/other/manifest.json`. See [UPGRADING.md](https://github.com/chassis-ui/website/blob/main/packages/docs/UPGRADING.md#from-010-to-011).
+
+### Patch Changes
+
+- The head links the Chassis CSS, `icons/chassis-icons.css` and `fonts/fonts.css` with `?v=` and the first 8 characters of the MD5 hash of the file, and the `<Icon>` shortcode, the icons of `<Example>` and `<ResizableExample>`, the search results and the color mode button of the examples load the sprite the same way: `/static/css/chassis.min.css?v=8e2106f6`. A new file is a new URL, so a host can let the browser keep these files for good, and a new CSS reaches a visitor with the pages that need it. The hash is read from the file of the site's `public` directory at the path of the URL; without that file the URL has no version, as before. `getVersionedStaticPath(file)` of `@chassis-ui/docs/site` returns such a URL, `replaceIconsInHtml()` takes the sprite as a third argument, and `virtual:chassis-docs/static` exports `spritePath`.
+
 ## 0.10.0
 
 ### Minor Changes

package/README.md

@@ -184,15 +184,15 @@ export const collections = {
 
 The layouts link to files under `/static/`, which the site puts into `static/` of its `public` directory:
 
-| URL                                                                                                                                | From                                                     |
-| ---------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------- |
-| `/static/css/chassis.css`, `/static/css/chassis.min.css`                                                                           | the `dist` folder of `@chassis-ui/css`                   |
-| `/static/icons/chassis-icons.svg`, `/static/icons/chassis-icons.css`                                                               | the `icons` folder of `@chassis-ui/icons`                |
-| `/static/images/site-logo.svg`, the logo of the navigation bar and the footer. The build inlines it, and fails without the file    | the docs build of `chassis-assets`                       |
-| `/static/images/favicon.png`, `favicon-16x16.png`, `favicon-32x32.png` and `apple-touch-icon.png`                                  | the docs build of `chassis-assets`                       |
-| `/static/images/social-image.png`, the image of a page without a `thumbnail`. The build reads its size, and fails without the file | the docs build of `chassis-assets`                       |
-| `/static/fonts/fonts.css`, and the font files it loads                                                                             | the docs build of `chassis-assets`                       |
-| `/static/images/manifest.json`, the web app manifest                                                                               | the site itself. The starter has one in `static/images/` |
+| URL                                                                                                                                | From                                                                                                                      |
+| ---------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
+| `/static/css/chassis.css`, `/static/css/chassis.min.css`                                                                           | the `dist` folder of `@chassis-ui/css`                                                                                    |
+| `/static/icons/chassis-icons.svg`, `/static/icons/chassis-icons.css`                                                               | the `icons` folder of `@chassis-ui/icons`                                                                                 |
+| `/static/images/site-logo.svg`, the logo of the navigation bar and the footer. The build inlines it, and fails without the file    | the docs build of `chassis-assets`                                                                                        |
+| `/static/images/favicon.png`, `favicon-16x16.png`, `favicon-32x32.png` and `apple-touch-icon.png`                                  | the docs build of `chassis-assets`                                                                                        |
+| `/static/images/social-image.png`, the image of a page without a `thumbnail`. The build reads its size, and fails without the file | the docs build of `chassis-assets`                                                                                        |
+| `/static/fonts/fonts.css`, and the font files it loads                                                                             | the docs build of `chassis-assets`                                                                                        |
+| `/static/other/manifest.json`, the web app manifest                                                                                | the docs build of `chassis-assets`, `v0.5.0` or later. A site may put its own in its `static/other/`, as the starter does |
 
 `chassis-docs vendor` builds the docs build of `chassis-assets` in the `vendor/assets` submodule. See [Commands](#commands).
 
@@ -210,9 +210,9 @@ The sites of the Chassis projects read these files besides, by name, from the do
 | ------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------- |
 | `icons/cx-sprite.svg`                                                    | The home page of each of the seven sites, which imports it. The build fails without it                          |
 | `images/apple-touch-icon.png`, `images/favicon.png`                      | Each of the seven sites, which copies them to `/apple-touch-icon.png` and `/favicon.ico`                        |
-| `images/android-chrome-192x192.png`, `images/android-chrome-512x512.png` | The `manifest.json` of each of the seven sites                                                                  |
+| `images/android-chrome-192x192.png`, `images/android-chrome-512x512.png` | `other/manifest.json` of the docs build, which the head links                                                   |
 | `images/home/`                                                           | The home page of the website. The home page of chassis-tokens reads `comp-gallery-*` of it                      |
-| `images/logo/chassis-{logo,icon}-{brand,white}-banner.svg`               | The about page of the website                                                                                   |
+| `images/logo/logo-{light,dark}.svg`                                      | The about page of the website                                                                                   |
 | `images/social-image.png`                                                | The blog of the website, for a post without an image                                                            |
 | `images/site-logo.svg`                                                   | The examples of the navbar page of chassis-css. The README of `@chassis-ui/react`, by its URL on chassis-ui.com |
 | `images/figma/components/`                                               | The component pages of chassis-figma                                                                            |
@@ -242,6 +242,8 @@ Two kinds of URL are the site's own to move:
 
 A social image named in the frontmatter as `static/images/…` is read from the `public` directory and linked under `staticPath`.
 
+The layouts link the Chassis CSS, the icon stylesheet, `fonts/fonts.css` and the icon sprite with a version: `/static/css/chassis.min.css?v=8e2106f6`, the first 8 characters of the MD5 hash of the file. A new file is a new URL, so a host can let the browser keep these files for good. The version is read from the file of `public` at the path of the URL, so a site under a prefix whose `public` holds the files in `static/` links them without one.
+
 ### 5. Use the layouts
 
 ```astro
@@ -283,6 +285,7 @@ chassisDocs({
 | `getSiteRoot()`, `getSiteFsPath(file)`             | Absolute path of the site's root, or of a file in it                |
 | `getPublicFsPath(file)`                            | Absolute path of a file in the `public` directory                   |
 | `getStaticPath(file)`                              | URL path of a static file, under `staticPath` of the config         |
+| `getVersionedStaticPath(file)`                     | The same, with `?v=` and a hash of the file in `public`             |
 | `getSourceFsPath(file)`                            | Absolute path of a file that a `file` prop names                    |
 | `getSourceUrl(file)`                               | URL of a source file on GitHub, at the tag of the current version   |
 | `getSiteFileUrl(filePath)`                         | URL of a file of the site on GitHub, on the site's branch           |
@@ -417,6 +420,7 @@ The integration provides five modules: `virtual:chassis-docs/config`, `virtual:c
 
 | `@chassis-ui/docs` | Requires Astro             | Requires `@chassis-ui/css` | Requires Node | Built with                             |
 | ------------------ | -------------------------- | -------------------------- | ------------- | -------------------------------------- |
+| 0.11.0             | `^7.0.0`                   | `>=0.10.0`                 | `>=22.12.0`   | Astro 7.3.8, css 0.10.0, tokens 0.10.0 |
 | 0.10.0             | `^7.0.0`                   | `>=0.10.0`                 | `>=22.12.0`   | Astro 7.3.8, css 0.10.0, tokens 0.10.0 |
 | 0.9.0              | `^7.0.0`                   | `>=0.10.0`                 | `>=22.12.0`   | Astro 7.3.8, css 0.10.0, tokens 0.10.0 |
 | 0.8.0              | `^7.0.0`                   | `>=0.6.0`                  | `>=22.12.0`   | Astro 7.3.5, css 0.7.1, tokens 0.7.0   |

package/UPGRADING.md

@@ -1,5 +1,138 @@
 # Upgrading @chassis-ui/docs
 
+## From 0.10 to 0.11
+
+0.11.0 links the web app manifest of the docs build of `chassis-assets`,
+`other/manifest.json` under the static path, in place of `images/manifest.json`, which each
+site provided itself. chassis-assets added the manifest, with a maskable icon, in `v0.5.0`
+of `app/docs` on 2026-10-23.
+
+### 1. Update the dependency and the assets
+
+In the package of the site, then from the root of the repository:
+
+```sh
+pnpm add -D @chassis-ui/docs@^0.11.0
+pnpm sync-submodules
+git add vendor/assets
+```
+
+The docs build has `other/manifest.json` from `v0.5.0` on. With an earlier commit the page
+links a manifest that is not there. Stage or commit the pin before you run `pnpm vendor` or a
+build, which check the submodule out at the commit that the repository records.
+
+### 2. Remove the site's own manifest
+
+Delete `images/manifest.json` from the files that the site copies into `public/static/`,
+`static/static/images/` in most Chassis repositories. A site that keeps a manifest with a name
+of its own puts it at `static/other/manifest.json` of what it copies after the docs build, as
+the starter does, and names the icons `../images/…`.
+
+### What changes in the package
+
+- **The head links `other/manifest.json`** under the static path, and no longer
+  `images/manifest.json`.
+- The pages link the Chassis CSS, `icons/chassis-icons.css`, `fonts/fonts.css` and the icon
+  sprite with `?v=` and a hash of the file, so a host can cache them for good.
+
+### Check the result
+
+Open the page in a browser and check that the manifest loads: in Chrome, Application >
+Manifest names the site and shows its icons.
+
+## From 0.8 to 0.10
+
+0.9 and 0.10 are both breaking minors, and a site on 0.8 takes them in one upgrade: the
+steps of [From 0.8 to 0.9](#from-08-to-09) and [From 0.9 to 0.10](#from-09-to-010) together,
+in this order. 0.9 reads the typography names of `@chassis-ui/css` 0.10. 0.10 links one font
+stylesheet, `fonts/fonts.css`, and inlines the logo, after chassis-assets changed both on
+`app/docs` on 2026-10-19.
+
+### 1. Update the dependencies
+
+In the package of the site, `packages/site` in most Chassis repositories:
+
+```sh
+pnpm add -D @chassis-ui/docs@^0.10.0 @chassis-ui/css@^0.10.0 @chassis-ui/tokens@^0.10.0
+```
+
+The default token source of css, `scss/vendor/_chassis-tokens.scss`, forwards the
+`@chassis-ui/tokens` that the site installs, and css 0.10 reads tokens that only tokens 0.10
+has, so the three move together. A site that takes css or tokens from its own workspace keeps
+that dependency and moves the workspace to 0.10. css 0.8 to 0.10 have changes of their own.
+Read the [changelog of css](https://github.com/chassis-ui/css/blob/main/packages/css/CHANGELOG.md)
+first.
+
+### 2. Move the `vendor/assets` submodule
+
+From the root of the repository:
+
+```sh
+pnpm sync-submodules
+git add vendor/assets
+```
+
+`sync-submodules` moves the submodule to the latest commit of `app/docs` and builds it. The
+docs build has `fonts/fonts.css` and the `ui-*` font files from `db6d64b` on, and the logo
+for inline use from `4382de9` on. With a commit before `db6d64b` the pages show the fallback
+fonts.
+
+Stage the pin, or commit it, before you run `pnpm vendor` or a build: `vendor` checks the
+submodule out at the commit that the repository records, and a build from the old pin links a
+stylesheet that is not there.
+
+chassis-assets has no submodule: its site is built from its own `source/`, which has
+`fonts.css` from `db6d64b` on. A site that does not copy the docs build provides
+`fonts/fonts.css` and the font files it names itself.
+
+### 3. Rename the typography names in your own pages and styles
+
+The table under [From 0.8 to 0.9](#2-rename-the-typography-names-in-your-own-pages-and-styles)
+lists them: `.h1` to `.h6` are `.font-h1` to `.font-h6`, `.font-text` is `.font-ui`, the
+`--cx-*-text-*` properties are `--cx-*-ui-*`, and the `$font-context-*` maps are `$font-*`.
+css 0.10 keeps `.h1` to `.h6`, `.font-text` and `--cx-font-family-text` as deprecated names.
+The other old names are gone: a Sass name that is gone fails the build, and a class or a
+custom property that is gone does nothing, so look for those in the pages.
+
+### 4. Look for the old files of the docs build in your own files
+
+The package links the new files, but a page or a stylesheet of your own may name the old
+ones:
+
+```sh
+git grep -nE "fonts/(text|display|code)\.css|text-[a-z0-9-]*\.woff2|site-logo\.svg" -- ':!vendor'
+```
+
+- **`fonts/text.css`, `fonts/display.css`, `fonts/code.css`:** link `fonts/fonts.css`.
+- **`text-*.woff2`:** the files of the `text` role are `ui-*.woff2` now, such as
+  `ui-latin.woff2` and `ui-normal.woff2`.
+- **`images/site-logo.svg` in an `<img>`:** the logo from `4382de9` on has no `xmlns`, so a
+  browser does not show it as an image, and its paths take their colors from the classes
+  `icon-default` and `icon-primary` of the page. Inline it, as the navigation bar does, or use a
+  file of `images/logo/`, which an `<img>` shows, such as `images/logo/chassis-logo-brand.svg`.
+
+### What changes on the pages
+
+- **The head links `fonts/fonts.css`** under the static path, in place of the three
+  stylesheets of the roles.
+- **The navigation bar and the footer inline the logo,** `2rem` high, in the colors of the
+  theme. The build reads `static/images/site-logo.svg` of the site's `public` directory and
+  fails without it. The link of the logo in the footer has the margin `mb-md`, where it was
+  `mb-xs`.
+- **The search of the header is `5rem` wide** from the `lg` breakpoint, the icon and the
+  shortcut, and `12.5rem` from `xl`, where it was 200px.
+- **The footer and the docs sidebar use `.font-h6` and `.font-h5`,** and `.cxd-subtitle`
+  reads `$font-lead`.
+- **From css 0.10 and tokens 0.10:** the headings and the titles are in the display family,
+  Montserrat, the default tokens have new base colors, and buttons, badges and the other
+  components that had one lose their background gradient.
+
+### Check the result
+
+Build the site before and after the upgrade and compare the pages in a browser, in both color
+modes and between 1024 and 1280 pixels, where the search of the header changes. In the
+network panel, no request under `/static/fonts/` may fail.
+
 ## From 0.9 to 0.10
 
 0.10.0 links one font stylesheet, `fonts/fonts.css`, in place of `fonts/text.css`,
@@ -11,14 +144,20 @@ and the classes `icon-default` and `icon-primary` of the page color its paths.
 
 ### 1. Update the dependency and the assets
 
+In the package of the site, then from the root of the repository:
+
 ```sh
 pnpm add -D @chassis-ui/docs@^0.10.0
 pnpm sync-submodules
+git add vendor/assets
 ```
 
 The docs build of `chassis-assets` has `fonts/fonts.css` from `db6d64b` of `app/docs` on. With
-an earlier commit the pages show the fallback fonts. A site that does not copy the docs build
-provides `fonts/fonts.css` itself.
+an earlier commit the pages show the fallback fonts. Stage or commit the pin before you run
+`pnpm vendor` or a build, which check the submodule out at the commit that the repository
+records. A site that does not copy the docs build provides `fonts/fonts.css` itself. Step 2
+and step 4 of [From 0.8 to 0.10](#from-08-to-010) say more, and how to find the old files in
+your own pages.
 
 ### What changes in the package
 
@@ -30,6 +169,9 @@ provides `fonts/fonts.css` itself.
   logo of an earlier docs build, with its own colors, a width and a height, shows at the same
   height.
 - **The link of the logo in the footer has the bottom margin `mb-md`,** where it was `mb-xs`.
+- **The search of the header is `5rem` wide** from the `lg` breakpoint, the icon and the
+  shortcut, and `12.5rem` from `xl`, where it was 200px, so that no link of the header runs
+  under it between 1024 and 1280 pixels.
 
 ### Check the result
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@chassis-ui/docs",
   "description": "Shared Astro components and layouts for Chassis documentation sites.",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "type": "module",
   "repository": {
     "type": "git",

package/src/components/shortcodes/Example.astro

@@ -3,7 +3,7 @@ import { replacePlaceholdersInHtml } from '../../libs/placeholder'
 import { replaceIconsInHtml } from '../../libs/icon'
 import Code from './Code.astro'
 import Icon from './Icon.astro'
-import { getStaticPath } from '../../site'
+import { getStaticPath, getVersionedStaticPath } from '../../site'
 
 interface Props {
   /**
@@ -70,7 +70,11 @@ const {
 
 let markup = Array.isArray(code) ? code.join('\n') : code
 markup = replacePlaceholdersInHtml(markup)
-markup = replaceIconsInHtml(markup, getStaticPath())
+markup = replaceIconsInHtml(
+  markup,
+  getStaticPath(),
+  getVersionedStaticPath('icons/chassis-icons.svg')
+)
 markup = markup
   .split('\n')
   .map((line) => line.trimEnd())
@@ -93,7 +97,7 @@ const simplifiedMarkup = sourceMarkup
     (_match, classes) => `<img src="..."${classes ? ` class="${classes}"` : ''} alt="...">`
   )
   .replace(/(<svg class="icon\b[^"]*")\s+width="\d+"\s+height="\d+"/g, '$1')
-  .replace(/href="\/static\/icons\/chassis-icons\.svg#/g, 'href="#')
+  .replace(/href="\/static\/icons\/chassis-icons\.svg(?:\?v=[0-9a-f]+)?#/g, 'href="#')
 ---
 
 <div class="cxd-example-snippet cxd-code-snippet not-prose" data-pagefind-ignore>

package/src/components/shortcodes/Icon.astro

@@ -1,5 +1,5 @@
 ---
-import { getStaticPath } from '../../site'
+import { getVersionedStaticPath } from '../../site'
 
 /**
  * Icon
@@ -31,7 +31,7 @@ const {
   size = 24,
   font = false,
   title,
-  sprite = getStaticPath('icons/chassis-icons.svg'),
+  sprite = getVersionedStaticPath('icons/chassis-icons.svg'),
   ...rest
 } = Astro.props
 ---

package/src/components/shortcodes/ResizableExample.astro

@@ -3,7 +3,7 @@ import { replacePlaceholdersInHtml } from '../../libs/placeholder'
 import { replaceIconsInHtml } from '../../libs/icon'
 import Code from './Code.astro'
 import Icon from './Icon.astro'
-import { getStaticPath } from '../../site'
+import { getStaticPath, getVersionedStaticPath } from '../../site'
 
 interface Props {
   /**
@@ -68,7 +68,11 @@ const {
 
 let markup = Array.isArray(code) ? code.join('\n') : code
 markup = replacePlaceholdersInHtml(markup)
-markup = replaceIconsInHtml(markup, getStaticPath())
+markup = replaceIconsInHtml(
+  markup,
+  getStaticPath(),
+  getVersionedStaticPath('icons/chassis-icons.svg')
+)
 
 // The resizable container needs `overflow: hidden` for the CSS `resize` handle
 // to work, which clips popovers like menus/dropdowns when they open. Render them
@@ -95,7 +99,7 @@ const simplifiedMarkup = sourceMarkup
     (_match, classes) => `<img src="..."${classes ? ` class="${classes}"` : ''} alt="...">`
   )
   .replace(/(<svg class="icon\b[^"]*")\s+width="\d+"\s+height="\d+"/g, '$1')
-  .replace(/href="\/static\/icons\/chassis-icons\.svg#/g, 'href="#')
+  .replace(/href="\/static\/icons\/chassis-icons\.svg(?:\?v=[0-9a-f]+)?#/g, 'href="#')
 ---
 
 <div class="cxd-example-snippet cxd-code-snippet" data-pagefind-ignore>

package/src/integration.ts

@@ -4,13 +4,14 @@ import { fileURLToPath } from 'node:url'
 import type { AstroIntegration, AstroUserConfig, ViteUserConfig } from 'astro'
 import type { z } from 'astro/zod'
 import { loadConfig, loadSidebar } from './libs/config'
-import { joinDocsPath } from './libs/docs-path'
+import { joinDocsPath, joinStaticPath } from './libs/docs-path'
 import { getDocsMarkdownConfig, type DocsMarkdownConfigOptions } from './libs/markdown'
 import { getInstalledPackageFsPath, getPackageRoot } from './libs/paths'
 import { remarkCxConfig, remarkCxDocsref } from './libs/remark'
 import { configSchema, type ChassisConfig, type Sidebar } from './libs/schema'
 import { chassisAutoImport, type ChassisAutoImportOptions } from './libs/shortcodes'
 import { getSiteUrl } from './libs/site'
+import { versionStaticPath } from './libs/static-version'
 
 export interface ChassisDocsOptions<TSchema extends z.ZodType = typeof configSchema> {
   /**
@@ -56,7 +57,8 @@ type VitePlugin = Extract<NonNullable<ViteUserConfig['plugins']>[number], { name
 const virtualPrefix = 'virtual:chassis-docs/'
 const resolvedPrefix = '\0' + virtualPrefix
 
-function virtualModules(modules: Record<string, string>): VitePlugin {
+// The code of each module, or a function that returns it when the module is loaded.
+function virtualModules(modules: Record<string, string | (() => string)>): VitePlugin {
   return {
     name: 'chassis-docs:virtual',
     resolveId(id) {
@@ -66,7 +68,9 @@ function virtualModules(modules: Record<string, string>): VitePlugin {
     },
     load(id) {
       if (id.startsWith(resolvedPrefix)) {
-        return modules[id.slice(resolvedPrefix.length)]
+        const code = modules[id.slice(resolvedPrefix.length)]
+
+        return typeof code === 'function' ? code() : code
       }
     }
   }
@@ -92,6 +96,7 @@ declare module 'virtual:chassis-docs/paths' {
 
 declare module 'virtual:chassis-docs/static' {
   export const staticPath: string
+  export const spritePath: string
 }
 
 declare module 'virtual:chassis-docs/styles' {}
@@ -238,8 +243,21 @@ export function chassisDocs<TSchema extends z.ZodType = typeof configSchema>(
                 paths: Object.entries(paths)
                   .map(([name, value]) => `export const ${name} = ${JSON.stringify(value)}`)
                   .join('\n'),
-                // A config that was not loaded with `loadConfig()` may lack the default.
-                static: `export const staticPath = ${JSON.stringify(config.staticPath ?? '/static')}`,
+                // A config that was not loaded with `loadConfig()` may lack the default. The
+                // version of the sprite is read when a script loads the module: a site's own
+                // integration may copy the file into `public` after this hook.
+                static: () => {
+                  const staticPath = config.staticPath ?? '/static'
+                  const spritePath = versionStaticPath(
+                    joinStaticPath(staticPath, 'icons/chassis-icons.svg'),
+                    paths.publicDir
+                  )
+
+                  return [
+                    `export const staticPath = ${JSON.stringify(staticPath)}`,
+                    `export const spritePath = ${JSON.stringify(spritePath)}`
+                  ].join('\n')
+                },
                 styles: styles.map((file) => `import ${JSON.stringify(file)}`).join('\n')
               })
             ]

package/src/js/example-mode.js

@@ -1,5 +1,5 @@
 import { Tooltip } from '@chassis-ui/css'
-import { staticPath } from 'virtual:chassis-docs/static'
+import { spritePath } from 'virtual:chassis-docs/static'
 
 // Helper to detect the user's preferred theme
 function getPreferredTheme() {
@@ -44,7 +44,7 @@ function toggleTheme(button) {
   const iconUse = button.querySelector('use')
   if (iconUse) {
     const iconHref = newTheme === 'dark' ? 'sun-solid' : 'moon-solid'
-    iconUse.setAttribute('href', `${staticPath}/icons/chassis-icons.svg#${iconHref}`)
+    iconUse.setAttribute('href', `${spritePath}#${iconHref}`)
   }
 }
 
@@ -65,7 +65,7 @@ document.addEventListener('DOMContentLoaded', () => {
       const example = button.closest('.cxd-example-snippet')?.querySelector('.cxd-example')
       const currentTheme = example?.getAttribute('data-cx-theme') || preferredTheme
       const iconHref = currentTheme === 'dark' ? 'sun-solid' : 'moon-solid'
-      iconUse.setAttribute('href', `${staticPath}/icons/chassis-icons.svg#${iconHref}`)
+      iconUse.setAttribute('href', `${spritePath}#${iconHref}`)
     }
 
     // Add event listener if not already set through onclick

package/src/js/search.js

@@ -13,7 +13,7 @@
 // is needed here.
 
 import { getInstanceManager } from '@pagefind/component-ui'
-import { staticPath } from 'virtual:chassis-docs/static'
+import { spritePath } from 'virtual:chassis-docs/static'
 
 const DIALOG_SELECTOR = '#cxdSearchDialog'
 // The rows that are links. The loading skeleton reuses the class on a `<div>`,
@@ -237,7 +237,7 @@ const escapeHtml = (value) => String(value ?? '').replace(/[&<>"']/g, (char) =>
 const renderItem = ({ url, titleHtml, excerptHtml = '', icon, sub = false }) => `
   <a class="cxd-search-item${sub ? ' cxd-search-subitem' : ''}" href="${escapeHtml(url)}">
     <svg class="icon cxd-search-item-icon" width="16" height="16" aria-hidden="true">
-      <use href="${staticPath}/icons/chassis-icons.svg#${icon}"></use>
+      <use href="${spritePath}#${icon}"></use>
     </svg>
     <div class="cxd-search-item-body">
       <div class="cxd-search-item-title">${titleHtml}</div>

package/src/layouts/head/Favicons.astro

@@ -11,6 +11,6 @@ import { getStaticPath } from '../../site'
 <link rel="apple-touch-icon" href={getStaticPath('images/apple-touch-icon.png')} sizes="180x180" />
 <link rel="icon" href={getStaticPath('images/favicon-32x32.png')} sizes="32x32" type="image/png" />
 <link rel="icon" href={getStaticPath('images/favicon-16x16.png')} sizes="16x16" type="image/png" />
-<link rel="manifest" href={getStaticPath('images/manifest.json')} />
+<link rel="manifest" href={getStaticPath('other/manifest.json')} />
 <link rel="icon" href={getStaticPath('images/favicon.png')} />
 <meta name="theme-color" content="#00A4CC" />

package/src/layouts/head/Head.astro

@@ -5,7 +5,7 @@
  * HTML head section with meta tags, stylesheets, and SEO configuration.
  */
 
-import { getConfig, getStaticPath } from '../../site'
+import { getConfig, getVersionedStaticPath } from '../../site'
 import { isHomePath } from '../../libs/docs-path'
 import type { Layout } from '../../libs/layout'
 import Stylesheet from './Stylesheet.astro'
@@ -46,7 +46,7 @@ const pageTitle = isHome
   family of every role. A link, not an `@import` in the styles, so that the browser finds it
   with the page and not after the stylesheet that imports it
 -->
-<link rel="stylesheet" href={getStaticPath('fonts/fonts.css')} />
+<link rel="stylesheet" href={getVersionedStaticPath('fonts/fonts.css')} />
 
 <meta name="description" content={description} />
 

package/src/layouts/head/Stylesheet.astro

@@ -6,19 +6,11 @@
  */
 
 import type { HTMLAttributes } from 'astro/types'
-import { getStaticPath } from '../../site'
+import { getVersionedStaticPath } from '../../site'
 
 function getChassisCssProps() {
-  let cxCssLinkHref = getStaticPath('css/chassis')
-
-  if (import.meta.env.PROD) {
-    cxCssLinkHref = `${cxCssLinkHref}.min`
-  }
-
-  cxCssLinkHref = `${cxCssLinkHref}.css`
-
   const cxCssLinkProps: HTMLAttributes<'link'> = {
-    href: cxCssLinkHref,
+    href: getVersionedStaticPath(import.meta.env.PROD ? 'css/chassis.min.css' : 'css/chassis.css'),
     rel: 'stylesheet'
   }
 
@@ -27,4 +19,4 @@ function getChassisCssProps() {
 ---
 
 <link {...getChassisCssProps()} />
-<link rel="stylesheet" href={getStaticPath('icons/chassis-icons.css')} />
+<link rel="stylesheet" href={getVersionedStaticPath('icons/chassis-icons.css')} />

package/src/libs/icon.ts

@@ -18,9 +18,16 @@ interface IconOptions {
  * This is needed because the `<Example />` shortcode renders its `code` prop as raw HTML via `set:html`
  * rather than as MDX, so nested Astro components (like `<Icon />`, similar to `<Placeholder />`) are never
  * actually invoked — they need to be expanded to their rendered markup ahead of time.
+ *
+ * @param staticPath The `staticPath` of the site.
+ * @param sprite URL of the sprite that an icon without a `sprite` attribute uses.
  * @see src/components/shortcodes/Icon.astro
  */
-export function replaceIconsInHtml(html: string, staticPath = '/static') {
+export function replaceIconsInHtml(
+  html: string,
+  staticPath = '/static',
+  sprite = `${staticPath}/icons/chassis-icons.svg`
+) {
   return html.replace(iconRegex, (match) => {
     const document = htmlparser2.parseDocument(match, { xmlMode: true })
     const iconElement = document.firstChild
@@ -34,11 +41,11 @@ export function replaceIconsInHtml(html: string, staticPath = '/static') {
       throw new Error('Invalid icon element.')
     }
 
-    return renderIconToString(getOptionsWithDefaults(iconElement.attribs, staticPath))
+    return renderIconToString(getOptionsWithDefaults(iconElement.attribs, sprite))
   })
 }
 
-function getOptionsWithDefaults(attribs: Record<string, string>, staticPath: string): IconOptions {
+function getOptionsWithDefaults(attribs: Record<string, string>, sprite: string): IconOptions {
   if (!attribs.name) {
     throw new Error('Icon element is missing the required "name" attribute.')
   }
@@ -48,7 +55,7 @@ function getOptionsWithDefaults(attribs: Record<string, string>, staticPath: str
     class: attribs.class,
     size: attribs.size ? Number(attribs.size.replace(/[{}]/g, '')) : 24,
     font: attribs.font !== undefined && attribs.font !== '{false}',
-    sprite: attribs.sprite || `${staticPath}/icons/chassis-icons.svg`,
+    sprite: attribs.sprite || sprite,
     title: attribs.title
   }
 }

package/src/libs/static-version.ts

@@ -0,0 +1,53 @@
+import { createHash } from 'node:crypto'
+import fs from 'node:fs'
+import path from 'node:path'
+
+// The hash of each file, kept until its size or time of change differs: a page of the build
+// reads the same stylesheet as every other page, and the dev server sees a file copied anew.
+const versions = new Map<string, { mtimeMs: number; size: number; version: string }>()
+
+/**
+ * The first 8 characters of the MD5 hash of a file's content, or `undefined` when there is
+ * no file at `fsPath`.
+ */
+export function getFileVersion(fsPath: string): string | undefined {
+  let stats: fs.Stats
+
+  try {
+    stats = fs.statSync(fsPath)
+  } catch {
+    return undefined
+  }
+
+  if (!stats.isFile()) return undefined
+
+  const cached = versions.get(fsPath)
+
+  if (cached && cached.mtimeMs === stats.mtimeMs && cached.size === stats.size) {
+    return cached.version
+  }
+
+  const version = createHash('md5').update(fs.readFileSync(fsPath)).digest('hex').slice(0, 8)
+  versions.set(fsPath, { mtimeMs: stats.mtimeMs, size: stats.size, version })
+
+  return version
+}
+
+/**
+ * Adds `?v=` and the version of the file to the URL path of a file of the public directory:
+ * `/static/css/chassis.min.css?v=8e2106f6`. A new content is a new URL, so the file can be
+ * kept by the browser until the page names another. A path that the public directory has no
+ * file at is returned as it is.
+ *
+ * @param urlPath URL path of the file, e.g. `"/static/css/chassis.min.css"`.
+ * @param publicDir Absolute path of the site's `public` directory.
+ */
+export function versionStaticPath(urlPath: string, publicDir: string): string {
+  const fsPath = path.join(publicDir, urlPath)
+
+  if (path.relative(publicDir, fsPath).startsWith('..')) return urlPath
+
+  const version = getFileVersion(fsPath)
+
+  return version ? `${urlPath}?v=${version}` : urlPath
+}

package/src/site.ts

@@ -14,6 +14,7 @@ import { getNodeModulesFsPaths, resolvePackageFilePath } from './libs/paths'
 import { replaceConfigInText, replaceDocsrefInText } from './libs/remark'
 import type { ChassisConfig, DocsPage, Sidebar } from './libs/schema'
 import { resolveSiteFileUrl, resolveSourceFsPath, resolveSourceUrl } from './libs/source'
+import { versionStaticPath } from './libs/static-version'
 
 /**
  * The parsed `config.yml`.
@@ -43,6 +44,18 @@ export function getStaticPath(file = ''): string {
   return joinStaticPath(config.staticPath ?? '/static', file)
 }
 
+/**
+ * URL path of a static file with the version of its content:
+ * `getVersionedStaticPath('css/chassis.min.css')` is
+ * `/static/css/chassis.min.css?v=8e2106f6`. The version is read from the file of the site's
+ * `public` directory, so a page links the file of its own build, and a browser that keeps
+ * the file fetches it again when it changes. Without that file, the path is the one of
+ * `getStaticPath()`.
+ */
+export function getVersionedStaticPath(file: string): string {
+  return versionStaticPath(getStaticPath(file), paths.publicDir)
+}
+
 /** Absolute path of the site's root: the directory that holds `astro.config.ts`. */
 export function getSiteRoot(): string {
   return paths.root

package/virtual.d.ts

@@ -25,6 +25,8 @@ declare module 'virtual:chassis-docs/paths' {
 declare module 'virtual:chassis-docs/static' {
   /** `staticPath` of the config, for scripts that run in the browser. */
   export const staticPath: string
+  /** URL of the icon sprite, with the version of its content. */
+  export const spritePath: string
 }
 
 declare module 'virtual:chassis-docs/styles' {}