@chassis-ui/docs 0.6.1 → 0.6.2

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @chassis-ui/docs
 
+## 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                                                                                                  |
+| `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. chassis-ui.com has one for each Chassis site.
+- 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
@@ -233,6 +255,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 +366,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 +374,7 @@ 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.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 +402,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.2",
   "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,6 +13,7 @@
 // is needed here.
 
 import { getInstanceManager } from '@pagefind/component-ui'
+import { staticPath } from 'virtual:chassis-docs/static'
 
 const DIALOG_SELECTOR = '#cxdSearchDialog'
 const SUB_RESULTS_LIMIT = 3
@@ -233,7 +234,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>

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/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,10 @@ 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
+}

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' {}