@chassis-ui/docs 0.6.1 → 0.6.3

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # @chassis-ui/docs
 
+## 0.6.3
+
+### Patch Changes
+
+- The home page of a site under a path gets the home form of the title, `title · subtitle`. The layouts took the page at `/` as the home page, so a site with `baseURL` `https://chassis-ui.com/css/` never got it: its home page is at `/css/`. The home page is now the page at the path of `baseURL`. The title of such a home page changes with this release, and the `title` prop of its layout is used for the social tags only. Keep `title · subtitle` within 70 characters where the site validates its HTML.
+- The color mode script is inline in the head and runs before the first paint. It was a module, which runs after the document is parsed, so a page in dark mode showed light first.
+- Five fixes of the search dialog. The page scrolls again after a search result on the current page is opened: the dialog closed without removing the scroll lock of the body. The input has the focus when the dialog is opened with the button, so typing works at once. The keyboard shortcuts open the dialog as the button does: the page behind it no longer scrolls, and a click outside closes it. A click or Enter on a loading placeholder no longer closes the dialog and saves an empty visit. Escape closes the dialog in Safari when the focus is in the empty input.
+
+## 0.6.2
+
+### Patch Changes
+
+- Add the `staticPath` key of `config.yml`: the URL path that the pages load the static files from, `/static` by default. A site that is served under a path of another host, such as `chassis-ui.com/css`, sets it to `/css/static` and rewrites that path to `/static`, so that its files no longer depend on the `Referer` header to be found. The layouts, the `Icon` shortcode and the scripts of the package use it, and `getStaticPath()` of `@chassis-ui/docs/site` returns a URL under it for the site's own files. See [A site under a prefix](https://github.com/chassis-ui/website/tree/main/packages/docs#a-site-under-a-prefix) in the README.
+
 ## 0.6.1
 
 ### Patch Changes

package/README.md

@@ -106,23 +106,24 @@ repo: 'https://github.com/chassis-ui/css'
 currentVersion: '0.5.2'
 ```
 
-| Key                                           | Required | Meaning                                                                                           |
-| --------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------- |
-| `title`, `subtitle`, `description`, `authors` | yes      | Used in the page title and the meta tags                                                          |
-| `baseURL`                                     | yes      | Canonical URL of the site                                                                         |
-| `docsPath`                                    | yes      | URL path of the docs pages. Starts with `/`                                                       |
-| `repo`                                        | yes      | URL of the repository                                                                             |
-| `currentVersion`                              | yes      | Version that the site documents. Links to source files use the tag `v<currentVersion>`            |
-| `githubOrg`                                   | no       | GitHub organisation name, not a URL. The header links to it                                       |
-| `figmaHandle`                                 | no       | Figma Community handle. The header links to it                                                    |
-| `xUsername`                                   | no       | X handle. Used in the social meta tags                                                            |
-| `analytics.googleId`                          | no       | Google Analytics ID. In production builds, loaded after the visitor accepts in a consent banner   |
-| `anchors.min`, `anchors.max`                  | no       | Heading levels that get an anchor link. Default 2 to 5                                            |
-| `toc.min`, `toc.max`                          | no       | Heading levels in the table of contents. Default 2 to 6                                           |
-| `sourceDir`                                   | no       | Directory that `file` props are relative to, from the site's root, e.g. `"../css"`. Default `"."` |
-| `sourcePath`                                  | no       | The same directory from the root of the repository, e.g. `"packages/css"`                         |
-| `sitePath`                                    | no       | The site's root from the root of the repository, e.g. `"packages/site"`                           |
-| `siteBranch`                                  | no       | The branch that "View on GitHub" links to. Default `main`                                         |
+| Key                                           | Required | Meaning                                                                                                                    |
+| --------------------------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------- |
+| `title`, `subtitle`, `description`, `authors` | yes      | Used in the page title and the meta tags                                                                                   |
+| `baseURL`                                     | yes      | Canonical URL of the site. The page at its path is the home page: `/css/` for `https://chassis-ui.com/css/`                |
+| `docsPath`                                    | yes      | URL path of the docs pages. Starts with `/`                                                                                |
+| `staticPath`                                  | no       | URL path that the pages load the static files from. Default `/static`. See [A site under a prefix](#a-site-under-a-prefix) |
+| `repo`                                        | yes      | URL of the repository                                                                                                      |
+| `currentVersion`                              | yes      | Version that the site documents. Links to source files use the tag `v<currentVersion>`                                     |
+| `githubOrg`                                   | no       | GitHub organisation name, not a URL. The header links to it                                                                |
+| `figmaHandle`                                 | no       | Figma Community handle. The header links to it                                                                             |
+| `xUsername`                                   | no       | X handle. Used in the social meta tags                                                                                     |
+| `analytics.googleId`                          | no       | Google Analytics ID. In production builds, loaded after the visitor accepts in a consent banner                            |
+| `anchors.min`, `anchors.max`                  | no       | Heading levels that get an anchor link. Default 2 to 5                                                                     |
+| `toc.min`, `toc.max`                          | no       | Heading levels in the table of contents. Default 2 to 6                                                                    |
+| `sourceDir`                                   | no       | Directory that `file` props are relative to, from the site's root, e.g. `"../css"`. Default `"."`                          |
+| `sourcePath`                                  | no       | The same directory from the root of the repository, e.g. `"packages/css"`                                                  |
+| `sitePath`                                    | no       | The site's root from the root of the repository, e.g. `"packages/site"`                                                    |
+| `siteBranch`                                  | no       | The branch that "View on GitHub" links to. Default `main`                                                                  |
 
 `file` props are those of `<ScssDocs>`, `<ScssDocsSimple>`, `<JsDocs>` and `<Code filePath>`.
 
@@ -181,7 +182,7 @@ export const collections = {
 
 ### 4. Provide the static files
 
-The layouts link to files under `/static/`, which the site puts into its `public` directory:
+The layouts link to files under `/static/`, which the site puts into `static/` of its `public` directory:
 
 | URL                                                                  | From                                      |
 | -------------------------------------------------------------------- | ----------------------------------------- |
@@ -195,6 +196,27 @@ These helpers find the folders, whether `node_modules` is in the site's root or
 
 A site that type-checks with `astro check` declares the `@chassis-ui/css` module, which has no types: `declare module '@chassis-ui/css'`.
 
+#### A site under a prefix
+
+A site that is served under a path of another host, such as `chassis-ui.com/css`, cannot use `/static/` there: that path belongs to the host's own site. It loads its static files under a path of its own instead:
+
+```yaml
+# config.yml
+staticPath: '/css/static'
+```
+
+The layouts, the `Icon` shortcode and the scripts of the package then link `/css/static/css/chassis.min.css` and so on. The files do not move: they stay in `static/` of the `public` directory. Two rewrites make the path answer:
+
+- on the host, from `/css/static/*` to `/static/*` of the site's deployment.
+- in the site's own `vercel.json`, from `/css/static/(.*)` to `/static/$1`, so that the deployment also works when it is opened directly.
+
+Two kinds of URL are the site's own to move:
+
+- URLs that the site writes itself, in its pages and components. `getStaticPath('images/hero.png')` of `@chassis-ui/docs/site` returns the URL under `staticPath`.
+- The files that Astro builds, when the site puts them under `static/` with `build.assets`. Astro's `build.assetsPrefix` adds the prefix to them, `'/css'` here.
+
+A social image named in the frontmatter as `static/images/…` is read from the `public` directory and linked under `staticPath`.
+
 ### 5. Use the layouts
 
 ```astro
@@ -207,6 +229,8 @@ import SingleLayout from '@chassis-ui/docs/layouts/SingleLayout.astro'
 </SingleLayout>
 ```
 
+The `<title>` of a page is its `title` and the `title` of `config.yml`: `About · Chassis UI`. The home page, which is the page at the path of `baseURL`, gets `title` and `subtitle` of `config.yml` instead: `Chassis UI · Design Systems that Scale & Sync`. Its own `title` is used for the social tags only. html-validate reports a `<title>` of more than 70 characters, so keep the two within that.
+
 ## Shortcodes
 
 Every component in `@chassis-ui/docs/shortcodes/` is available in MDX files without an import. So is every component in the site's `src/components/shortcodes/`. A component of the site replaces the package's component of the same name.
@@ -233,6 +257,7 @@ chassisDocs({
 | `getCallout(name)`                                 | An entry of the `callouts` collection                               |
 | `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         |
 | `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           |
@@ -343,7 +368,7 @@ These import paths are the public API.
 
 No other path resolves: `exports` in `package.json` lists these and nothing else. The layouts and components are listed by name, so the folders inside `layouts/` and `components/` are not reachable.
 
-The integration provides four modules: `virtual:chassis-docs/config`, `virtual:chassis-docs/sidebar`, `virtual:chassis-docs/paths` and `virtual:chassis-docs/styles`. Use the functions of `@chassis-ui/docs/site` instead of importing them.
+The integration provides five modules: `virtual:chassis-docs/config`, `virtual:chassis-docs/sidebar`, `virtual:chassis-docs/paths`, `virtual:chassis-docs/static` and `virtual:chassis-docs/styles`. Use the functions of `@chassis-ui/docs/site` instead of importing them.
 
 ## Compatibility
 
@@ -351,6 +376,8 @@ The integration provides four modules: `virtual:chassis-docs/config`, `virtual:c
 
 | `@chassis-ui/docs` | Requires Astro             | Requires `@chassis-ui/css` | Requires Node | Built with                           |
 | ------------------ | -------------------------- | -------------------------- | ------------- | ------------------------------------ |
+| 0.6.3              | `^7.0.0`                   | `^0.5.0-0`                 | `>=22.12.0`   | Astro 7.3.5, css 0.5.2, tokens 0.6.0 |
+| 0.6.2              | `^7.0.0`                   | `^0.5.0-0`                 | `>=22.12.0`   | Astro 7.3.5, css 0.5.2, tokens 0.6.0 |
 | 0.6.1              | `^7.0.0`                   | `^0.5.0-0`                 | `>=22.12.0`   | Astro 7.3.5, css 0.5.2, tokens 0.6.0 |
 | 0.6.0              | `^7.0.0`                   | `^0.5.0-0`                 | `>=22.12.0`   | Astro 7.3.5, css 0.5.2, tokens 0.5.3 |
 | 0.5.1              | `^7.0.0`                   | `^0.5.0-0`                 | `>=22.12.0`   | Astro 7.3.5, css 0.5.2, tokens 0.5.3 |
@@ -378,7 +405,7 @@ A change is breaking when it changes something that this README documents:
 - the keys of `config.yml`, and the schemas of the sidebar and the content collections
 - the props and slots of the layouts, components and shortcodes
 - the `[[config:]]` and `[[docsref:]]` syntax
-- the URLs under `/static/` that the layouts link to
+- the URLs under `staticPath`, `/static/` by default, that the layouts link to
 - the supported versions of Node, Astro and `@chassis-ui/css`
 
 Everything else may change in a patch release: the rendered HTML, class names, the content of the styles, and every file that is not reachable through a documented import path.

package/package.json

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

package/src/components/shortcodes/Example.astro

@@ -3,6 +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'
 
 interface Props {
   /**
@@ -69,7 +70,7 @@ const {
 
 let markup = Array.isArray(code) ? code.join('\n') : code
 markup = replacePlaceholdersInHtml(markup)
-markup = replaceIconsInHtml(markup)
+markup = replaceIconsInHtml(markup, getStaticPath())
 markup = markup
   .split('\n')
   .map((line) => line.trimEnd())

package/src/components/shortcodes/Icon.astro

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

package/src/components/shortcodes/ResizableExample.astro

@@ -3,6 +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'
 
 interface Props {
   /**
@@ -67,7 +68,7 @@ const {
 
 let markup = Array.isArray(code) ? code.join('\n') : code
 markup = replacePlaceholdersInHtml(markup)
-markup = replaceIconsInHtml(markup)
+markup = replaceIconsInHtml(markup, getStaticPath())
 
 // The resizable container needs `overflow: hidden` for the CSS `resize` handle
 // to work, which clips popovers like menus/dropdowns when they open. Render them

package/src/integration.ts

@@ -90,6 +90,10 @@ declare module 'virtual:chassis-docs/paths' {
   export const packageRoot: string
 }
 
+declare module 'virtual:chassis-docs/static' {
+  export const staticPath: string
+}
+
 declare module 'virtual:chassis-docs/styles' {}
 `
 
@@ -234,6 +238,8 @@ 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')}`,
                 styles: styles.map((file) => `import ${JSON.stringify(file)}`).join('\n')
               })
             ]

package/src/js/example-mode.js

@@ -1,4 +1,5 @@
 import { Tooltip } from '@chassis-ui/css'
+import { staticPath } from 'virtual:chassis-docs/static'
 
 // Helper to detect the user's preferred theme
 function getPreferredTheme() {
@@ -43,7 +44,7 @@ function toggleTheme(button) {
   const iconUse = button.querySelector('use')
   if (iconUse) {
     const iconHref = newTheme === 'dark' ? 'sun-solid' : 'moon-solid'
-    iconUse.setAttribute('href', `/static/icons/chassis-icons.svg#${iconHref}`)
+    iconUse.setAttribute('href', `${staticPath}/icons/chassis-icons.svg#${iconHref}`)
   }
 }
 
@@ -64,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', `/static/icons/chassis-icons.svg#${iconHref}`)
+      iconUse.setAttribute('href', `${staticPath}/icons/chassis-icons.svg#${iconHref}`)
     }
 
     // Add event listener if not already set through onclick

package/src/js/search.js

@@ -13,8 +13,12 @@
 // is needed here.
 
 import { getInstanceManager } from '@pagefind/component-ui'
+import { staticPath } from 'virtual:chassis-docs/static'
 
 const DIALOG_SELECTOR = '#cxdSearchDialog'
+// The rows that are links. The loading skeleton reuses the class on a `<div>`,
+// which must not be followed, focused or saved as a visit.
+const ITEM_SELECTOR = 'a.cxd-search-item'
 const SUB_RESULTS_LIMIT = 3
 // How long a search may take before we show the loading skeleton. Most queries
 // resolve faster, so the previous results stay on-screen instead of flashing.
@@ -233,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="/static/icons/chassis-icons.svg#${icon}"></use>
+      <use href="${staticPath}/icons/chassis-icons.svg#${icon}"></use>
     </svg>
     <div class="cxd-search-item-body">
       <div class="cxd-search-item-title">${titleHtml}</div>
@@ -293,12 +297,21 @@ class CxdSearchInput extends HTMLElement {
       return
     }
 
+    // Safari keeps Escape for the search field, even an empty one, and the
+    // dialog never gets its cancel event. With text in the field the key clears
+    // it, as in every browser; without text it closes the dialog here.
+    if (event.key === 'Escape' && !this.input.value) {
+      event.preventDefault()
+      closeSearchDialog(this.closest('dialog'))
+      return
+    }
+
     // Enter follows the first result link.
     // Always preventDefault so the form never implicit-submits.
     if (event.key === 'Enter') {
       event.preventDefault()
       const dialogEl = this.closest('dialog')
-      dialogEl?.querySelector('.cxd-search-item')?.click()
+      dialogEl?.querySelector(ITEM_SELECTOR)?.click()
     }
   }
 
@@ -338,11 +351,11 @@ class CxdSearchResults extends HTMLElement {
   }
 
   _getLinks() {
-    return [...this.querySelectorAll('.cxd-search-item')]
+    return [...this.querySelectorAll(ITEM_SELECTOR)]
   }
 
   _onKeydown(event) {
-    const link = event.target.closest('.cxd-search-item')
+    const link = event.target.closest(ITEM_SELECTOR)
     if (!link) return
 
     const links = this._getLinks()
@@ -616,6 +629,29 @@ const isEditableTarget = (target) => {
   return tag === 'INPUT' || tag === 'TEXTAREA' || tag === 'SELECT'
 }
 
+const TRIGGER_SELECTOR = `[data-cx-toggle="dialog"][data-cx-target="${DIALOG_SELECTOR}"]`
+
+// Puts the caret in the input once the dialog is open. The chassis Dialog
+// focuses the dialog element itself when it opens, so a key typed right after a
+// click on the trigger went nowhere.
+const focusSearchInput = (dialogEl) => {
+  requestAnimationFrame(() => {
+    if (!dialogEl.open) return
+    dialogEl.querySelector('cxd-search-input')?.focus()
+    if (!instance.searchTerm) {
+      dialogEl.querySelector('cxd-search-results')?._renderEmpty?.()
+    }
+  })
+}
+
+const registerTriggerHandler = () => {
+  document.addEventListener('click', (event) => {
+    if (!event.target.closest(TRIGGER_SELECTOR)) return
+    const dialogEl = document.querySelector(DIALOG_SELECTOR)
+    if (dialogEl) focusSearchInput(dialogEl)
+  })
+}
+
 const openSearchDialog = () => {
   const dialogEl = document.querySelector(DIALOG_SELECTOR)
   if (!dialogEl) return
@@ -625,15 +661,24 @@ const openSearchDialog = () => {
     return
   }
 
-  // Native showModal() — CSS @starting-style handles the entry animation without
-  // needing the chassis bundle. Works in both dev (no bundle) and prod.
-  dialogEl.showModal()
-  requestAnimationFrame(() => {
-    dialogEl.querySelector('cxd-search-input')?.focus()
-    if (!instance.searchTerm) {
-      dialogEl.querySelector('cxd-search-results')?._renderEmpty?.()
-    }
-  })
+  // Open through the trigger, so that a shortcut does what the button does: the
+  // chassis Dialog locks the scroll of the body, closes on a click on the
+  // backdrop and gives the focus back. Without the chassis bundle the click does
+  // nothing, and the native showModal() opens the dialog.
+  document.querySelector(TRIGGER_SELECTOR)?.click()
+  if (!dialogEl.open) {
+    dialogEl.showModal()
+    focusSearchInput(dialogEl)
+  }
+}
+
+// Closes through the dismiss button, so that the chassis Dialog animates the
+// dialog out, unlocks the scroll of the body and gives the focus back. Without
+// the chassis bundle the click does nothing, and the native close() closes it.
+const closeSearchDialog = (dialogEl) => {
+  if (!dialogEl?.open) return
+  dialogEl.querySelector('[data-cx-dismiss="dialog"]')?.click()
+  if (dialogEl.open && !dialogEl.classList.contains('hiding')) dialogEl.close()
 }
 
 const registerGlobalShortcuts = () => {
@@ -682,7 +727,7 @@ const setupDialogResetOnClose = () => {
 
 const registerResultLinkHandler = () => {
   document.addEventListener('click', (event) => {
-    const link = event.target.closest('.cxd-search-item')
+    const link = event.target.closest(ITEM_SELECTOR)
     if (!link) return
     const dialogEl = link.closest('dialog')
     if (!dialogEl?.matches(DIALOG_SELECTOR)) return
@@ -696,6 +741,14 @@ const registerResultLinkHandler = () => {
     })
 
     dialogEl.close()
+
+    // The trigger opens the dialog through the chassis Dialog, which locks the
+    // scroll of the body with this class and unlocks it in its own hide(). The
+    // native close() above skips that, so the class stays: when the result is on
+    // the current page, nothing reloads and the page can no longer scroll.
+    if (!document.querySelector('dialog[open]:modal')) {
+      document.body.classList.remove('dialog-open')
+    }
   })
 }
 
@@ -703,6 +756,7 @@ const registerResultLinkHandler = () => {
 
 defineSearchCustomElements()
 registerGlobalShortcuts()
+registerTriggerHandler()
 registerResultLinkHandler()
 
 if (document.readyState === 'loading') {

package/src/layouts/footer/Footer.astro

@@ -4,6 +4,8 @@
  *
  * Site footer with logo, license information, and navigation links.
  */
+
+import { getStaticPath } from '../../site'
 ---
 
 <footer class="cxd-footer py-6xl">
@@ -15,7 +17,7 @@
           href="/"
           aria-label="Chassis"
         >
-          <img src="/static/images/site-logo.svg" alt="Chassis UI" height="32" />
+          <img src={getStaticPath('images/site-logo.svg')} alt="Chassis UI" height="32" />
         </a>
         <p class="mb-xs">
           This project is licensed under the MIT License, which allows for free use, modification,

package/src/layouts/head/Favicons.astro

@@ -4,11 +4,13 @@
  *
  * Favicon and app icon link tags for various platforms.
  */
+
+import { getStaticPath } from '../../site'
 ---
 
-<link rel="apple-touch-icon" href={'/static/images/apple-touch-icon.png'} sizes="180x180" />
-<link rel="icon" href={'/static/images/favicon-32x32.png'} sizes="32x32" type="image/png" />
-<link rel="icon" href={'/static/images/favicon-16x16.png'} sizes="16x16" type="image/png" />
-<link rel="manifest" href={'/static/images/manifest.json'} />
-<link rel="icon" href={'/static/images/favicon.png'} />
+<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="icon" href={getStaticPath('images/favicon.png')} />
 <meta name="theme-color" content="#00A4CC" />

package/src/layouts/head/Head.astro

@@ -6,10 +6,12 @@
  */
 
 import { getConfig } from '../../site'
+import { isHomePath } from '../../libs/docs-path'
 import type { Layout } from '../../libs/layout'
 import Stylesheet from './Stylesheet.astro'
 import Favicons from './Favicons.astro'
 import Social from './Social.astro'
+import colorModes from '../../js/color-modes.js?raw'
 import 'virtual:chassis-docs/styles'
 
 interface Props {
@@ -29,7 +31,8 @@ const { description, layout, robots, thumbnail, title } = Astro.props
 
 const canonicalUrl = new URL(Astro.url.pathname, Astro.site)
 
-const isHome = Astro.url.pathname === '/'
+// The home page of a site under a path, such as `/css/`, is not at `/`
+const isHome = isHomePath(getConfig().baseURL, Astro.url.pathname)
 const pageTitle = isHome
   ? `${getConfig().title} · ${getConfig().subtitle}`
   : `${title} · ${getConfig().title}`
@@ -60,7 +63,11 @@ const pageTitle = isHome
 
 {robots && <meta name="robots" content={robots} />}
 
-<script src="../../js/color-modes.js"></script>
+<!--
+  Inline and not a module, so that it sets the theme before the first paint. A module runs
+  after the document is parsed, and a page in dark mode would show light first
+-->
+<script is:inline set:html={colorModes} />
 
 <Stylesheet />
 <slot name="styles" />

package/src/layouts/head/Social.astro

@@ -7,7 +7,7 @@
 
 import { getRemoteImageSize, getStaticImageSize } from '../../libs/image'
 import type { Layout } from '../../libs/layout'
-import { getConfig, getPublicFsPath } from '../../site'
+import { getConfig, getPublicFsPath, getStaticPath } from '../../site'
 
 interface Props {
   /** Page description */
@@ -22,7 +22,10 @@ interface Props {
 
 const { description, layout, thumbnail, title } = Astro.props
 
-const socialImageUrl = new URL(thumbnail, Astro.site)
+// A file in `static/` of the `public` directory is read from there, and linked under
+// `staticPath` of the config.
+const staticFile = thumbnail.match(/^\/?static\/(.+)$/)?.[1]
+const socialImageUrl = new URL(staticFile ? getStaticPath(staticFile) : thumbnail, Astro.site)
 const isRemoteThumbnail = /^https?:\/\//i.test(thumbnail)
 const socialImageSize = isRemoteThumbnail
   ? await getRemoteImageSize(thumbnail)

package/src/layouts/head/Stylesheet.astro

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

package/src/layouts/header/Navigation.astro

@@ -6,7 +6,7 @@
  */
 
 import type { Layout } from '../../libs/layout'
-import { getConfig } from '../../site'
+import { getConfig, getStaticPath } from '../../site'
 import NavLink from '../../components/NavLink.astro'
 import ThemeToggler from '../../components/ThemeToggler.astro'
 import SearchTrigger from './SearchTrigger.astro'
@@ -55,7 +55,7 @@ const isActive = (path: string) => {
     {layout !== 'docs' && <div class="lg:d-none" style="width: 4.25rem;" />}
 
     <a class="navbar-brand m-0 py-sm lg:me-md" href="/" aria-label="Chassis">
-      <img src="/static/images/site-logo.svg" alt="Chassis UI" width="123" height="32" />
+      <img src={getStaticPath('images/site-logo.svg')} alt="Chassis UI" width="123" height="32" />
     </a>
 
     <div class="d-flex">

package/src/libs/docs-path.ts

@@ -10,3 +10,23 @@ export function joinDocsPath(docsPath: string, inputPath: string): string {
 
   return page ? `${base}/${page}` : base
 }
+
+/** Joins the static path of the config and a file: `('/css/static', 'css/chassis.css')`. */
+export function joinStaticPath(staticPath: string, file = ''): string {
+  const name = file.replace(/^\/+/, '')
+
+  return name ? `${staticPath}/${name}` : staticPath
+}
+
+/**
+ * Whether a page is the home page of the site: the page at the path of `baseURL`. That is
+ * `/` for `https://chassis-ui.com` and `/css/` for `https://chassis-ui.com/css/`.
+ *
+ * @param baseURL The `baseURL` of the site's `config.yml`.
+ * @param pathname URL path of the page, with or without a trailing slash.
+ */
+export function isHomePath(baseURL: string, pathname: string): boolean {
+  const trim = (value: string) => value.replace(/\/+$/, '')
+
+  return trim(pathname) === trim(new URL(baseURL).pathname)
+}

package/src/libs/icon.ts

@@ -20,7 +20,7 @@ interface IconOptions {
  * actually invoked — they need to be expanded to their rendered markup ahead of time.
  * @see src/components/shortcodes/Icon.astro
  */
-export function replaceIconsInHtml(html: string) {
+export function replaceIconsInHtml(html: string, staticPath = '/static') {
   return html.replace(iconRegex, (match) => {
     const document = htmlparser2.parseDocument(match, { xmlMode: true })
     const iconElement = document.firstChild
@@ -34,11 +34,11 @@ export function replaceIconsInHtml(html: string) {
       throw new Error('Invalid icon element.')
     }
 
-    return renderIconToString(getOptionsWithDefaults(iconElement.attribs))
+    return renderIconToString(getOptionsWithDefaults(iconElement.attribs, staticPath))
   })
 }
 
-function getOptionsWithDefaults(attribs: Record<string, string>): IconOptions {
+function getOptionsWithDefaults(attribs: Record<string, string>, staticPath: string): IconOptions {
   if (!attribs.name) {
     throw new Error('Icon element is missing the required "name" attribute.')
   }
@@ -48,7 +48,7 @@ function getOptionsWithDefaults(attribs: Record<string, string>): IconOptions {
     class: attribs.class,
     size: attribs.size ? Number(attribs.size.replace(/[{}]/g, '')) : 24,
     font: attribs.font !== undefined && attribs.font !== '{false}',
-    sprite: attribs.sprite || '/static/icons/chassis-icons.svg',
+    sprite: attribs.sprite || `${staticPath}/icons/chassis-icons.svg`,
     title: attribs.title
   }
 }

package/src/libs/schema.ts

@@ -70,6 +70,16 @@ export const configSchema = z.strictObject({
   sourceDir: z.string().default('.'),
   /** The same directory from the root of the repository, e.g. `"packages/css"`. */
   sourcePath: z.string().optional(),
+  /**
+   * URL path that the pages load the static files from, e.g. `"/css/static"`. The files stay
+   * in `static/` of the `public` directory: a site under a prefix of another host sets this
+   * and rewrites the path to `/static`.
+   */
+  staticPath: z
+    .string()
+    .regex(/^\/(.*[^/])?$/, 'Expected a URL path that starts with "/" and has no trailing slash')
+    .refine((value) => value !== '/', 'Expected a path below the root, such as "/static"')
+    .default('/static'),
   subtitle: z.string(),
   title: z.string(),
   /** Heading levels that the table of contents lists. */

package/src/site.ts

@@ -9,7 +9,7 @@ import sidebar from 'virtual:chassis-docs/sidebar'
 import * as paths from 'virtual:chassis-docs/paths'
 import { getCollection, getEntry, type render } from 'astro:content'
 import { loadData } from './libs/config'
-import { joinDocsPath } from './libs/docs-path'
+import { joinDocsPath, joinStaticPath } from './libs/docs-path'
 import { getNodeModulesFsPaths, resolvePackageFilePath } from './libs/paths'
 import { replaceConfigInText, replaceDocsrefInText } from './libs/remark'
 import type { ChassisConfig, DocsPage, Sidebar } from './libs/schema'
@@ -35,6 +35,14 @@ export function getDocsPath(inputPath: string): string {
   return joinDocsPath(config.docsPath, inputPath)
 }
 
+/**
+ * URL path of a static file, under `staticPath` of the config:
+ * `getStaticPath('images/site-logo.svg')` is `/static/images/site-logo.svg` by default.
+ */
+export function getStaticPath(file = ''): string {
+  return joinStaticPath(config.staticPath ?? '/static', file)
+}
+
 /** 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

@@ -22,4 +22,9 @@ declare module 'virtual:chassis-docs/paths' {
   export const packageRoot: string
 }
 
+declare module 'virtual:chassis-docs/static' {
+  /** `staticPath` of the config, for scripts that run in the browser. */
+  export const staticPath: string
+}
+
 declare module 'virtual:chassis-docs/styles' {}