@chassis-ui/docs 0.10.0 → 0.11.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +18 -0
- package/README.md +83 -41
- package/UPGRADING.md +144 -2
- package/index.ts +1 -0
- package/package.json +9 -8
- package/src/components/MediaImage.astro +59 -0
- package/src/components/ResponsiveImage.astro +6 -3
- package/src/components/shortcodes/Example.astro +7 -3
- package/src/components/shortcodes/Icon.astro +2 -2
- package/src/components/shortcodes/ResizableExample.astro +7 -3
- package/src/integration.ts +23 -5
- package/src/js/example-mode.js +3 -3
- package/src/js/search.js +5 -3
- package/src/layouts/head/Favicons.astro +1 -1
- package/src/layouts/head/Head.astro +2 -2
- package/src/layouts/head/Social.astro +23 -10
- package/src/layouts/head/Stylesheet.astro +3 -11
- package/src/layouts/header/SearchTrigger.astro +0 -1
- package/src/libs/icon.ts +11 -4
- package/src/libs/media.ts +158 -0
- package/src/libs/schema.ts +18 -0
- package/src/libs/static-version.ts +53 -0
- package/src/scss/_search.scss +12 -9
- package/src/site.ts +49 -0
- package/virtual.d.ts +2 -0
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,23 @@
|
|
|
1
1
|
# @chassis-ui/docs
|
|
2
2
|
|
|
3
|
+
## 0.11.1
|
|
4
|
+
|
|
5
|
+
### Patch Changes
|
|
6
|
+
|
|
7
|
+
- Images of a media library on Cloudinary, for images that do not belong in the repository. `media.cloudinary` of `config.yml` names the account, and a page names an image by its path in the library. `<MediaImage>` of `@chassis-ui/docs/components/MediaImage.astro` renders it with a `srcset` of copies up to twice its width, in AVIF or WebP when the browser accepts them, cropped around the subject when it has a `height`. A `thumbnail` of `media:` and a path links a 1200 × 630 JPEG copy in the social meta tags, with its size and type and without loading it. `getMediaUrl()` and `getMediaSrcSet()` of `@chassis-ui/docs/site` return the URLs, the root entry exports the functions they use, and `zMediaPath` of `@chassis-ui/docs/schema` checks a path in a content schema. The social meta tags now name the large card for X, `summary_large_image`, which the misspelt `summary_lg_image` did not, and give the `og:image:type` of the thumbnail's file instead of `image/png` for every image.
|
|
8
|
+
- The search trigger of the header takes its accessible name from its label, "Search docs…" by default, instead of an `aria-label` that left out the shortcut hint the trigger shows, ⌘K or Ctrl K. axe-core 4.14 reports that as `label-content-name-mismatch`. The hint is `aria-hidden`, and `aria-keyshortcuts` still announces the shortcut. Below the `lg` breakpoint the label is visually hidden instead of `display: none`, so the icon-only trigger keeps its name. Nothing changes on screen.
|
|
9
|
+
- `<ResponsiveImage>` links both files of an image with `?v=` and the hash of the file in the site's `public` directory, like the shared stylesheets, so a host can let the browser keep them for good. A path without a file in `public` is linked as before. `getVersionedPublicPath(urlPath)` of `@chassis-ui/docs/site` versions a URL path that a page or a prop already holds, such as `/static/images/home/hero.webp`.
|
|
10
|
+
|
|
11
|
+
## 0.11.0
|
|
12
|
+
|
|
13
|
+
### Minor Changes
|
|
14
|
+
|
|
15
|
+
- **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).
|
|
16
|
+
|
|
17
|
+
### Patch Changes
|
|
18
|
+
|
|
19
|
+
- 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`.
|
|
20
|
+
|
|
3
21
|
## 0.10.0
|
|
4
22
|
|
|
5
23
|
### Minor Changes
|
package/README.md
CHANGED
|
@@ -106,24 +106,25 @@ repo: 'https://github.com/chassis-ui/css'
|
|
|
106
106
|
currentVersion: '0.5.2'
|
|
107
107
|
```
|
|
108
108
|
|
|
109
|
-
| Key | Required | Meaning
|
|
110
|
-
| --------------------------------------------- | -------- |
|
|
111
|
-
| `title`, `subtitle`, `description`, `authors` | yes | Used in the page title and the meta tags
|
|
112
|
-
| `baseURL` | yes | Canonical URL of the site. The page at its path is the home page: `/css/` for `https://chassis-ui.com/css/`
|
|
113
|
-
| `docsPath` | yes | URL path of the docs pages. Starts with `/`
|
|
114
|
-
| `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)
|
|
115
|
-
| `repo` | yes | URL of the repository
|
|
116
|
-
| `currentVersion` | yes | Version that the site documents. Links to source files use the tag `v<currentVersion>`
|
|
117
|
-
| `githubOrg` | no | GitHub organisation name, not a URL. The header links to it
|
|
118
|
-
| `figmaHandle` | no | Figma Community handle. The header links to it
|
|
119
|
-
| `xUsername` | no | X handle. Used in the social meta tags
|
|
120
|
-
| `
|
|
121
|
-
| `
|
|
122
|
-
| `
|
|
123
|
-
| `
|
|
124
|
-
| `
|
|
125
|
-
| `
|
|
126
|
-
| `
|
|
109
|
+
| Key | Required | Meaning |
|
|
110
|
+
| --------------------------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------- |
|
|
111
|
+
| `title`, `subtitle`, `description`, `authors` | yes | Used in the page title and the meta tags |
|
|
112
|
+
| `baseURL` | yes | Canonical URL of the site. The page at its path is the home page: `/css/` for `https://chassis-ui.com/css/` |
|
|
113
|
+
| `docsPath` | yes | URL path of the docs pages. Starts with `/` |
|
|
114
|
+
| `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) |
|
|
115
|
+
| `repo` | yes | URL of the repository |
|
|
116
|
+
| `currentVersion` | yes | Version that the site documents. Links to source files use the tag `v<currentVersion>` |
|
|
117
|
+
| `githubOrg` | no | GitHub organisation name, not a URL. The header links to it |
|
|
118
|
+
| `figmaHandle` | no | Figma Community handle. The header links to it |
|
|
119
|
+
| `xUsername` | no | X handle. Used in the social meta tags |
|
|
120
|
+
| `media.cloudinary` | no | Cloud name of the Cloudinary account that holds the media library. See [Images of the media library](#images-of-the-media-library) |
|
|
121
|
+
| `analytics.googleId` | no | Google Analytics ID. In production builds, loaded after the visitor accepts in a consent banner |
|
|
122
|
+
| `anchors.min`, `anchors.max` | no | Heading levels that get an anchor link. Default 2 to 5 |
|
|
123
|
+
| `toc.min`, `toc.max` | no | Heading levels in the table of contents. Default 2 to 6 |
|
|
124
|
+
| `sourceDir` | no | Directory that `file` props are relative to, from the site's root, e.g. `"../css"`. Default `"."` |
|
|
125
|
+
| `sourcePath` | no | The same directory from the root of the repository, e.g. `"packages/css"` |
|
|
126
|
+
| `sitePath` | no | The site's root from the root of the repository, e.g. `"packages/site"` |
|
|
127
|
+
| `siteBranch` | no | The branch that "View on GitHub" links to. Default `main` |
|
|
127
128
|
|
|
128
129
|
`file` props are those of `<ScssDocs>`, `<ScssDocsSimple>`, `<JsDocs>` and `<Code filePath>`.
|
|
129
130
|
|
|
@@ -184,15 +185,15 @@ export const collections = {
|
|
|
184
185
|
|
|
185
186
|
The layouts link to files under `/static/`, which the site puts into `static/` of its `public` directory:
|
|
186
187
|
|
|
187
|
-
| URL | From
|
|
188
|
-
| ---------------------------------------------------------------------------------------------------------------------------------- |
|
|
189
|
-
| `/static/css/chassis.css`, `/static/css/chassis.min.css` | the `dist` folder of `@chassis-ui/css`
|
|
190
|
-
| `/static/icons/chassis-icons.svg`, `/static/icons/chassis-icons.css` | the `icons` folder of `@chassis-ui/icons`
|
|
191
|
-
| `/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`
|
|
192
|
-
| `/static/images/favicon.png`, `favicon-16x16.png`, `favicon-32x32.png` and `apple-touch-icon.png` | the docs build of `chassis-assets`
|
|
193
|
-
| `/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`
|
|
194
|
-
| `/static/fonts/fonts.css`, and the font files it loads | the docs build of `chassis-assets`
|
|
195
|
-
| `/static/
|
|
188
|
+
| URL | From |
|
|
189
|
+
| ---------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
|
|
190
|
+
| `/static/css/chassis.css`, `/static/css/chassis.min.css` | the `dist` folder of `@chassis-ui/css` |
|
|
191
|
+
| `/static/icons/chassis-icons.svg`, `/static/icons/chassis-icons.css` | the `icons` folder of `@chassis-ui/icons` |
|
|
192
|
+
| `/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` |
|
|
193
|
+
| `/static/images/favicon.png`, `favicon-16x16.png`, `favicon-32x32.png` and `apple-touch-icon.png` | the docs build of `chassis-assets` |
|
|
194
|
+
| `/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` |
|
|
195
|
+
| `/static/fonts/fonts.css`, and the font files it loads | the docs build of `chassis-assets` |
|
|
196
|
+
| `/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 |
|
|
196
197
|
|
|
197
198
|
`chassis-docs vendor` builds the docs build of `chassis-assets` in the `vendor/assets` submodule. See [Commands](#commands).
|
|
198
199
|
|
|
@@ -210,9 +211,9 @@ The sites of the Chassis projects read these files besides, by name, from the do
|
|
|
210
211
|
| ------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------- |
|
|
211
212
|
| `icons/cx-sprite.svg` | The home page of each of the seven sites, which imports it. The build fails without it |
|
|
212
213
|
| `images/apple-touch-icon.png`, `images/favicon.png` | Each of the seven sites, which copies them to `/apple-touch-icon.png` and `/favicon.ico` |
|
|
213
|
-
| `images/android-chrome-192x192.png`, `images/android-chrome-512x512.png` |
|
|
214
|
+
| `images/android-chrome-192x192.png`, `images/android-chrome-512x512.png` | `other/manifest.json` of the docs build, which the head links |
|
|
214
215
|
| `images/home/` | The home page of the website. The home page of chassis-tokens reads `comp-gallery-*` of it |
|
|
215
|
-
| `images/logo/
|
|
216
|
+
| `images/logo/logo-{light,dark}.svg` | The about page of the website |
|
|
216
217
|
| `images/social-image.png` | The blog of the website, for a post without an image |
|
|
217
218
|
| `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 |
|
|
218
219
|
| `images/figma/components/` | The component pages of chassis-figma |
|
|
@@ -242,6 +243,8 @@ Two kinds of URL are the site's own to move:
|
|
|
242
243
|
|
|
243
244
|
A social image named in the frontmatter as `static/images/…` is read from the `public` directory and linked under `staticPath`.
|
|
244
245
|
|
|
246
|
+
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.
|
|
247
|
+
|
|
245
248
|
### 5. Use the layouts
|
|
246
249
|
|
|
247
250
|
```astro
|
|
@@ -283,6 +286,10 @@ chassisDocs({
|
|
|
283
286
|
| `getSiteRoot()`, `getSiteFsPath(file)` | Absolute path of the site's root, or of a file in it |
|
|
284
287
|
| `getPublicFsPath(file)` | Absolute path of a file in the `public` directory |
|
|
285
288
|
| `getStaticPath(file)` | URL path of a static file, under `staticPath` of the config |
|
|
289
|
+
| `getVersionedStaticPath(file)` | The same, with `?v=` and a hash of the file in `public` |
|
|
290
|
+
| `getVersionedPublicPath(urlPath)` | A URL path of a file in `public`, with `?v=` and the file's hash |
|
|
291
|
+
| `getMediaUrl(path, transform)` | URL of a copy of an image of the media library |
|
|
292
|
+
| `getMediaSrcSet(path, widths, transform)` | The `srcset` of an image of the media library |
|
|
286
293
|
| `getSourceFsPath(file)` | Absolute path of a file that a `file` prop names |
|
|
287
294
|
| `getSourceUrl(file)` | URL of a source file on GitHub, at the tag of the current version |
|
|
288
295
|
| `getSiteFileUrl(filePath)` | URL of a file of the site on GitHub, on the site's branch |
|
|
@@ -292,6 +299,39 @@ chassisDocs({
|
|
|
292
299
|
|
|
293
300
|
Code that runs while Astro loads its configuration uses the library functions of the root entry instead: `loadConfig()`, `loadData()`, `loadSidebar()` and the path helpers.
|
|
294
301
|
|
|
302
|
+
## Images of the media library
|
|
303
|
+
|
|
304
|
+
Images that do not belong in the repository, such as the covers of blog posts, are in a media library on Cloudinary. `media.cloudinary` of `config.yml` is the cloud name of the account, and a page names an image by its path in the library, such as `blog/2026/color-system/cover.jpg`. The path is the public ID of the image, with or without an extension. The folders of the library do not take part in it unless the public ID has them. A URL, a path that starts with `/`, `..` and a query are refused.
|
|
305
|
+
|
|
306
|
+
```astro
|
|
307
|
+
---
|
|
308
|
+
import MediaImage from '@chassis-ui/docs/components/MediaImage.astro'
|
|
309
|
+
---
|
|
310
|
+
|
|
311
|
+
<MediaImage
|
|
312
|
+
src="blog/2026/color-system/cover.jpg"
|
|
313
|
+
alt="Paint chips beside an empty floor plan"
|
|
314
|
+
width={1200}
|
|
315
|
+
height={630}
|
|
316
|
+
sizes="(width >= 64rem) 50vw, 100vw"
|
|
317
|
+
/>
|
|
318
|
+
```
|
|
319
|
+
|
|
320
|
+
| Prop | Meaning |
|
|
321
|
+
| -------- | -------------------------------------------------------------------------------------------------------------------- |
|
|
322
|
+
| `src` | Path of the image in the media library |
|
|
323
|
+
| `alt` | Alternative text |
|
|
324
|
+
| `width` | Largest width in CSS pixels that the image is shown at |
|
|
325
|
+
| `height` | Height at `width`. The image is cropped to that ratio, around its subject. Without it, the image keeps its own ratio |
|
|
326
|
+
| `widths` | Widths of the copies in the `srcset`. Default: the widths from 320 to 2400 up to twice `width`, and `width` |
|
|
327
|
+
| `sizes` | The `sizes` attribute. Default: `width` pixels, or the width of the viewport when smaller |
|
|
328
|
+
|
|
329
|
+
Other attributes go to the `<img>`. `loading` is `lazy` and `decoding` is `async` unless the page sets them. A browser that accepts AVIF or WebP gets that format.
|
|
330
|
+
|
|
331
|
+
A `thumbnail` of `media:` and a path, such as `media:blog/2026/color-system/cover.jpg`, links a 1200 × 630 JPEG copy, cropped around the subject, in the social meta tags. Its size is known, so the build does not load it. `zMediaPath` of `@chassis-ui/docs/schema` checks a path in a content schema of the site.
|
|
332
|
+
|
|
333
|
+
The page CSP of the host must allow images from `https://res.cloudinary.com`. Only `src/libs/media.ts` knows the URL format of Cloudinary, so a move to another provider changes that file and the config key, and no page.
|
|
334
|
+
|
|
295
335
|
## Commands
|
|
296
336
|
|
|
297
337
|
The package installs a `chassis-docs` command with the build steps that every Chassis site shares. Call it from the scripts of `package.json`:
|
|
@@ -394,18 +434,18 @@ A rule or filter applies to every file that the command checks. To make an excep
|
|
|
394
434
|
|
|
395
435
|
These import paths are the public API.
|
|
396
436
|
|
|
397
|
-
| Path | Contents
|
|
398
|
-
| ------------------------------- |
|
|
399
|
-
| `@chassis-ui/docs` | Library functions that work anywhere: config and data loaders, path helpers, `getSiteUrl`, `getDocsMarkdownConfig`, the remark and rehype plugins, `chassisAutoImport`, `generateToc`, `highlightCode`, image and string utilities |
|
|
400
|
-
| `@chassis-ui/docs/integration` | `chassisDocs()` and the type of its options
|
|
401
|
-
| `@chassis-ui/docs/schema` | `z`, `configSchema`, `sidebarSchema`, `docsSchema`, `calloutsSchema`, the version validators, and the types `ChassisConfig`, `Sidebar`, `SidebarItem`, `DocsFrontmatter`, `DocsPage`
|
|
402
|
-
| `@chassis-ui/docs/site` | What pages read from the site. See above
|
|
403
|
-
| `@chassis-ui/docs/layouts/*` | `BaseLayout.astro`, `DocsLayout.astro`, `RedirectLayout.astro`, `SingleLayout.astro`
|
|
404
|
-
| `@chassis-ui/docs/components/*` | `DocsSidebar.astro`, `FeatureCard.astro`, `NavLink.astro`, `ResponsiveImage.astro`, `TableOfContents.astro`, `ThemeToggler.astro`
|
|
405
|
-
| `@chassis-ui/docs/shortcodes/*` | The MDX shortcodes
|
|
406
|
-
| `@chassis-ui/docs/js/*` | Client-side scripts: `example-mode.js`, `clipboard.ts`, `color-modes.js` and others
|
|
407
|
-
| `@chassis-ui/docs/scss/main` | The styles of the package. The integration loads them when the site has no stylesheet of its own
|
|
408
|
-
| `@chassis-ui/docs/scss/vars` | The Sass variables and custom properties of the docs, for a site's own stylesheets
|
|
437
|
+
| Path | Contents |
|
|
438
|
+
| ------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
439
|
+
| `@chassis-ui/docs` | Library functions that work anywhere: config and data loaders, path helpers, `getSiteUrl`, `getDocsMarkdownConfig`, the remark and rehype plugins, `chassisAutoImport`, `generateToc`, `highlightCode`, image, media and string utilities |
|
|
440
|
+
| `@chassis-ui/docs/integration` | `chassisDocs()` and the type of its options |
|
|
441
|
+
| `@chassis-ui/docs/schema` | `z`, `configSchema`, `sidebarSchema`, `docsSchema`, `calloutsSchema`, the version validators, `zMediaPath`, and the types `ChassisConfig`, `Sidebar`, `SidebarItem`, `DocsFrontmatter`, `DocsPage` |
|
|
442
|
+
| `@chassis-ui/docs/site` | What pages read from the site. See above |
|
|
443
|
+
| `@chassis-ui/docs/layouts/*` | `BaseLayout.astro`, `DocsLayout.astro`, `RedirectLayout.astro`, `SingleLayout.astro` |
|
|
444
|
+
| `@chassis-ui/docs/components/*` | `DocsSidebar.astro`, `FeatureCard.astro`, `MediaImage.astro`, `NavLink.astro`, `ResponsiveImage.astro`, `TableOfContents.astro`, `ThemeToggler.astro` |
|
|
445
|
+
| `@chassis-ui/docs/shortcodes/*` | The MDX shortcodes |
|
|
446
|
+
| `@chassis-ui/docs/js/*` | Client-side scripts: `example-mode.js`, `clipboard.ts`, `color-modes.js` and others |
|
|
447
|
+
| `@chassis-ui/docs/scss/main` | The styles of the package. The integration loads them when the site has no stylesheet of its own |
|
|
448
|
+
| `@chassis-ui/docs/scss/vars` | The Sass variables and custom properties of the docs, for a site's own stylesheets |
|
|
409
449
|
|
|
410
450
|
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.
|
|
411
451
|
|
|
@@ -417,6 +457,8 @@ The integration provides five modules: `virtual:chassis-docs/config`, `virtual:c
|
|
|
417
457
|
|
|
418
458
|
| `@chassis-ui/docs` | Requires Astro | Requires `@chassis-ui/css` | Requires Node | Built with |
|
|
419
459
|
| ------------------ | -------------------------- | -------------------------- | ------------- | -------------------------------------- |
|
|
460
|
+
| 0.11.1 | `^7.0.0` | `>=0.10.0` | `>=22.12.0` | Astro 7.4.2, css 0.11.1, tokens 0.10.1 |
|
|
461
|
+
| 0.11.0 | `^7.0.0` | `>=0.10.0` | `>=22.12.0` | Astro 7.3.8, css 0.10.0, tokens 0.10.0 |
|
|
420
462
|
| 0.10.0 | `^7.0.0` | `>=0.10.0` | `>=22.12.0` | Astro 7.3.8, css 0.10.0, tokens 0.10.0 |
|
|
421
463
|
| 0.9.0 | `^7.0.0` | `>=0.10.0` | `>=22.12.0` | Astro 7.3.8, css 0.10.0, tokens 0.10.0 |
|
|
422
464
|
| 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
CHANGED
|
@@ -1,5 +1,138 @@
|
|
|
1
1
|
# Upgrading @chassis-ui/docs
|
|
2
2
|
|
|
3
|
+
## From 0.10 to 0.11
|
|
4
|
+
|
|
5
|
+
0.11.0 links the web app manifest of the docs build of `chassis-assets`,
|
|
6
|
+
`other/manifest.json` under the static path, in place of `images/manifest.json`, which each
|
|
7
|
+
site provided itself. chassis-assets added the manifest, with a maskable icon, in `v0.5.0`
|
|
8
|
+
of `app/docs` on 2026-10-23.
|
|
9
|
+
|
|
10
|
+
### 1. Update the dependency and the assets
|
|
11
|
+
|
|
12
|
+
In the package of the site, then from the root of the repository:
|
|
13
|
+
|
|
14
|
+
```sh
|
|
15
|
+
pnpm add -D @chassis-ui/docs@^0.11.0
|
|
16
|
+
pnpm sync-submodules
|
|
17
|
+
git add vendor/assets
|
|
18
|
+
```
|
|
19
|
+
|
|
20
|
+
The docs build has `other/manifest.json` from `v0.5.0` on. With an earlier commit the page
|
|
21
|
+
links a manifest that is not there. Stage or commit the pin before you run `pnpm vendor` or a
|
|
22
|
+
build, which check the submodule out at the commit that the repository records.
|
|
23
|
+
|
|
24
|
+
### 2. Remove the site's own manifest
|
|
25
|
+
|
|
26
|
+
Delete `images/manifest.json` from the files that the site copies into `public/static/`,
|
|
27
|
+
`static/static/images/` in most Chassis repositories. A site that keeps a manifest with a name
|
|
28
|
+
of its own puts it at `static/other/manifest.json` of what it copies after the docs build, as
|
|
29
|
+
the starter does, and names the icons `../images/…`.
|
|
30
|
+
|
|
31
|
+
### What changes in the package
|
|
32
|
+
|
|
33
|
+
- **The head links `other/manifest.json`** under the static path, and no longer
|
|
34
|
+
`images/manifest.json`.
|
|
35
|
+
- The pages link the Chassis CSS, `icons/chassis-icons.css`, `fonts/fonts.css` and the icon
|
|
36
|
+
sprite with `?v=` and a hash of the file, so a host can cache them for good.
|
|
37
|
+
|
|
38
|
+
### Check the result
|
|
39
|
+
|
|
40
|
+
Open the page in a browser and check that the manifest loads: in Chrome, Application >
|
|
41
|
+
Manifest names the site and shows its icons.
|
|
42
|
+
|
|
43
|
+
## From 0.8 to 0.10
|
|
44
|
+
|
|
45
|
+
0.9 and 0.10 are both breaking minors, and a site on 0.8 takes them in one upgrade: the
|
|
46
|
+
steps of [From 0.8 to 0.9](#from-08-to-09) and [From 0.9 to 0.10](#from-09-to-010) together,
|
|
47
|
+
in this order. 0.9 reads the typography names of `@chassis-ui/css` 0.10. 0.10 links one font
|
|
48
|
+
stylesheet, `fonts/fonts.css`, and inlines the logo, after chassis-assets changed both on
|
|
49
|
+
`app/docs` on 2026-10-19.
|
|
50
|
+
|
|
51
|
+
### 1. Update the dependencies
|
|
52
|
+
|
|
53
|
+
In the package of the site, `packages/site` in most Chassis repositories:
|
|
54
|
+
|
|
55
|
+
```sh
|
|
56
|
+
pnpm add -D @chassis-ui/docs@^0.10.0 @chassis-ui/css@^0.10.0 @chassis-ui/tokens@^0.10.0
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
The default token source of css, `scss/vendor/_chassis-tokens.scss`, forwards the
|
|
60
|
+
`@chassis-ui/tokens` that the site installs, and css 0.10 reads tokens that only tokens 0.10
|
|
61
|
+
has, so the three move together. A site that takes css or tokens from its own workspace keeps
|
|
62
|
+
that dependency and moves the workspace to 0.10. css 0.8 to 0.10 have changes of their own.
|
|
63
|
+
Read the [changelog of css](https://github.com/chassis-ui/css/blob/main/packages/css/CHANGELOG.md)
|
|
64
|
+
first.
|
|
65
|
+
|
|
66
|
+
### 2. Move the `vendor/assets` submodule
|
|
67
|
+
|
|
68
|
+
From the root of the repository:
|
|
69
|
+
|
|
70
|
+
```sh
|
|
71
|
+
pnpm sync-submodules
|
|
72
|
+
git add vendor/assets
|
|
73
|
+
```
|
|
74
|
+
|
|
75
|
+
`sync-submodules` moves the submodule to the latest commit of `app/docs` and builds it. The
|
|
76
|
+
docs build has `fonts/fonts.css` and the `ui-*` font files from `db6d64b` on, and the logo
|
|
77
|
+
for inline use from `4382de9` on. With a commit before `db6d64b` the pages show the fallback
|
|
78
|
+
fonts.
|
|
79
|
+
|
|
80
|
+
Stage the pin, or commit it, before you run `pnpm vendor` or a build: `vendor` checks the
|
|
81
|
+
submodule out at the commit that the repository records, and a build from the old pin links a
|
|
82
|
+
stylesheet that is not there.
|
|
83
|
+
|
|
84
|
+
chassis-assets has no submodule: its site is built from its own `source/`, which has
|
|
85
|
+
`fonts.css` from `db6d64b` on. A site that does not copy the docs build provides
|
|
86
|
+
`fonts/fonts.css` and the font files it names itself.
|
|
87
|
+
|
|
88
|
+
### 3. Rename the typography names in your own pages and styles
|
|
89
|
+
|
|
90
|
+
The table under [From 0.8 to 0.9](#2-rename-the-typography-names-in-your-own-pages-and-styles)
|
|
91
|
+
lists them: `.h1` to `.h6` are `.font-h1` to `.font-h6`, `.font-text` is `.font-ui`, the
|
|
92
|
+
`--cx-*-text-*` properties are `--cx-*-ui-*`, and the `$font-context-*` maps are `$font-*`.
|
|
93
|
+
css 0.10 keeps `.h1` to `.h6`, `.font-text` and `--cx-font-family-text` as deprecated names.
|
|
94
|
+
The other old names are gone: a Sass name that is gone fails the build, and a class or a
|
|
95
|
+
custom property that is gone does nothing, so look for those in the pages.
|
|
96
|
+
|
|
97
|
+
### 4. Look for the old files of the docs build in your own files
|
|
98
|
+
|
|
99
|
+
The package links the new files, but a page or a stylesheet of your own may name the old
|
|
100
|
+
ones:
|
|
101
|
+
|
|
102
|
+
```sh
|
|
103
|
+
git grep -nE "fonts/(text|display|code)\.css|text-[a-z0-9-]*\.woff2|site-logo\.svg" -- ':!vendor'
|
|
104
|
+
```
|
|
105
|
+
|
|
106
|
+
- **`fonts/text.css`, `fonts/display.css`, `fonts/code.css`:** link `fonts/fonts.css`.
|
|
107
|
+
- **`text-*.woff2`:** the files of the `text` role are `ui-*.woff2` now, such as
|
|
108
|
+
`ui-latin.woff2` and `ui-normal.woff2`.
|
|
109
|
+
- **`images/site-logo.svg` in an `<img>`:** the logo from `4382de9` on has no `xmlns`, so a
|
|
110
|
+
browser does not show it as an image, and its paths take their colors from the classes
|
|
111
|
+
`icon-default` and `icon-primary` of the page. Inline it, as the navigation bar does, or use a
|
|
112
|
+
file of `images/logo/`, which an `<img>` shows, such as `images/logo/chassis-logo-brand.svg`.
|
|
113
|
+
|
|
114
|
+
### What changes on the pages
|
|
115
|
+
|
|
116
|
+
- **The head links `fonts/fonts.css`** under the static path, in place of the three
|
|
117
|
+
stylesheets of the roles.
|
|
118
|
+
- **The navigation bar and the footer inline the logo,** `2rem` high, in the colors of the
|
|
119
|
+
theme. The build reads `static/images/site-logo.svg` of the site's `public` directory and
|
|
120
|
+
fails without it. The link of the logo in the footer has the margin `mb-md`, where it was
|
|
121
|
+
`mb-xs`.
|
|
122
|
+
- **The search of the header is `5rem` wide** from the `lg` breakpoint, the icon and the
|
|
123
|
+
shortcut, and `12.5rem` from `xl`, where it was 200px.
|
|
124
|
+
- **The footer and the docs sidebar use `.font-h6` and `.font-h5`,** and `.cxd-subtitle`
|
|
125
|
+
reads `$font-lead`.
|
|
126
|
+
- **From css 0.10 and tokens 0.10:** the headings and the titles are in the display family,
|
|
127
|
+
Montserrat, the default tokens have new base colors, and buttons, badges and the other
|
|
128
|
+
components that had one lose their background gradient.
|
|
129
|
+
|
|
130
|
+
### Check the result
|
|
131
|
+
|
|
132
|
+
Build the site before and after the upgrade and compare the pages in a browser, in both color
|
|
133
|
+
modes and between 1024 and 1280 pixels, where the search of the header changes. In the
|
|
134
|
+
network panel, no request under `/static/fonts/` may fail.
|
|
135
|
+
|
|
3
136
|
## From 0.9 to 0.10
|
|
4
137
|
|
|
5
138
|
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.
|
|
|
11
144
|
|
|
12
145
|
### 1. Update the dependency and the assets
|
|
13
146
|
|
|
147
|
+
In the package of the site, then from the root of the repository:
|
|
148
|
+
|
|
14
149
|
```sh
|
|
15
150
|
pnpm add -D @chassis-ui/docs@^0.10.0
|
|
16
151
|
pnpm sync-submodules
|
|
152
|
+
git add vendor/assets
|
|
17
153
|
```
|
|
18
154
|
|
|
19
155
|
The docs build of `chassis-assets` has `fonts/fonts.css` from `db6d64b` of `app/docs` on. With
|
|
20
|
-
an earlier commit the pages show the fallback fonts.
|
|
21
|
-
|
|
156
|
+
an earlier commit the pages show the fallback fonts. Stage or commit the pin before you run
|
|
157
|
+
`pnpm vendor` or a build, which check the submodule out at the commit that the repository
|
|
158
|
+
records. A site that does not copy the docs build provides `fonts/fonts.css` itself. Step 2
|
|
159
|
+
and step 4 of [From 0.8 to 0.10](#from-08-to-010) say more, and how to find the old files in
|
|
160
|
+
your own pages.
|
|
22
161
|
|
|
23
162
|
### What changes in the package
|
|
24
163
|
|
|
@@ -30,6 +169,9 @@ provides `fonts/fonts.css` itself.
|
|
|
30
169
|
logo of an earlier docs build, with its own colors, a width and a height, shows at the same
|
|
31
170
|
height.
|
|
32
171
|
- **The link of the logo in the footer has the bottom margin `mb-md`,** where it was `mb-xs`.
|
|
172
|
+
- **The search of the header is `5rem` wide** from the `lg` breakpoint, the icon and the
|
|
173
|
+
shortcut, and `12.5rem` from `xl`, where it was 200px, so that no link of the header runs
|
|
174
|
+
under it between 1024 and 1280 pixels.
|
|
33
175
|
|
|
34
176
|
### Check the result
|
|
35
177
|
|
package/index.ts
CHANGED
|
@@ -6,6 +6,7 @@ export * from './src/libs/highlight'
|
|
|
6
6
|
export * from './src/libs/image'
|
|
7
7
|
export * from './src/libs/layout'
|
|
8
8
|
export * from './src/libs/markdown'
|
|
9
|
+
export * from './src/libs/media'
|
|
9
10
|
export * from './src/libs/paths'
|
|
10
11
|
export * from './src/libs/placeholder'
|
|
11
12
|
export * from './src/libs/rehype'
|
package/package.json
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@chassis-ui/docs",
|
|
3
3
|
"description": "Shared Astro components and layouts for Chassis documentation sites.",
|
|
4
|
-
"version": "0.
|
|
4
|
+
"version": "0.11.1",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"repository": {
|
|
7
7
|
"type": "git",
|
|
@@ -47,6 +47,7 @@
|
|
|
47
47
|
"./layouts/SingleLayout.astro": "./src/layouts/SingleLayout.astro",
|
|
48
48
|
"./components/DocsSidebar.astro": "./src/components/DocsSidebar.astro",
|
|
49
49
|
"./components/FeatureCard.astro": "./src/components/FeatureCard.astro",
|
|
50
|
+
"./components/MediaImage.astro": "./src/components/MediaImage.astro",
|
|
50
51
|
"./components/NavLink.astro": "./src/components/NavLink.astro",
|
|
51
52
|
"./components/ResponsiveImage.astro": "./src/components/ResponsiveImage.astro",
|
|
52
53
|
"./components/TableOfContents.astro": "./src/components/TableOfContents.astro",
|
|
@@ -95,7 +96,7 @@
|
|
|
95
96
|
"clipboard": "^2.0.11",
|
|
96
97
|
"github-slugger": "^2.0.0",
|
|
97
98
|
"image-size": "^2.0.4",
|
|
98
|
-
"js-yaml": "^5.
|
|
99
|
+
"js-yaml": "^5.5.0",
|
|
99
100
|
"mdast-util-from-markdown": "^2.1.0",
|
|
100
101
|
"mdast-util-mdx-jsx": "^3.2.0",
|
|
101
102
|
"mdast-util-to-string": "^4.0.0",
|
|
@@ -106,16 +107,16 @@
|
|
|
106
107
|
"unist-util-visit": "^5.1.0"
|
|
107
108
|
},
|
|
108
109
|
"devDependencies": {
|
|
109
|
-
"@astrojs/markdown-remark": "^7.3.
|
|
110
|
-
"@chassis-ui/css": "^0.
|
|
110
|
+
"@astrojs/markdown-remark": "^7.3.4",
|
|
111
|
+
"@chassis-ui/css": "^0.11.1",
|
|
111
112
|
"@pagefind/component-ui": "^1.5.2",
|
|
112
113
|
"@shikijs/transformers": "^4.5.0",
|
|
113
|
-
"astro": "^7.
|
|
114
|
-
"html-validate": "^11.
|
|
114
|
+
"astro": "^7.4.2",
|
|
115
|
+
"html-validate": "^11.17.0",
|
|
115
116
|
"rehype-autolink-headings": "^7.1.0",
|
|
116
117
|
"remark-mdx": "^3.1.1",
|
|
117
|
-
"sass": "^1.
|
|
118
|
+
"sass": "^1.106.1",
|
|
118
119
|
"vfile": "^6.0.3",
|
|
119
|
-
"vnu-jar": "^26.10.
|
|
120
|
+
"vnu-jar": "^26.10.12"
|
|
120
121
|
}
|
|
121
122
|
}
|
|
@@ -0,0 +1,59 @@
|
|
|
1
|
+
---
|
|
2
|
+
/**
|
|
3
|
+
* Media Image
|
|
4
|
+
*
|
|
5
|
+
* An image of the media library that `media` of the config names. The `srcset` has a copy
|
|
6
|
+
* of the image at several widths, and the browser loads the smallest that fills the image,
|
|
7
|
+
* in AVIF or WebP when it accepts them.
|
|
8
|
+
*/
|
|
9
|
+
|
|
10
|
+
import type { HTMLAttributes } from 'astro/types'
|
|
11
|
+
import { getMediaImageWidths } from '../libs/media'
|
|
12
|
+
import { getMediaSrcSet, getMediaUrl } from '../site'
|
|
13
|
+
|
|
14
|
+
interface Props extends Omit<
|
|
15
|
+
HTMLAttributes<'img'>,
|
|
16
|
+
'alt' | 'height' | 'sizes' | 'src' | 'srcset' | 'width'
|
|
17
|
+
> {
|
|
18
|
+
/** Path of the image in the media library, e.g. `"blog/2026/color-system/cover.jpg"` */
|
|
19
|
+
src: string
|
|
20
|
+
/** Alternative text for the image */
|
|
21
|
+
alt: string
|
|
22
|
+
/** Largest width in CSS pixels that the image is shown at */
|
|
23
|
+
width: number
|
|
24
|
+
/**
|
|
25
|
+
* Height in CSS pixels at `width`. The image is cropped to the ratio of `width` and
|
|
26
|
+
* `height`, around its subject. Without it, the image keeps its own ratio and the `height`
|
|
27
|
+
* attribute is left out
|
|
28
|
+
*/
|
|
29
|
+
height?: number
|
|
30
|
+
/** Widths of the copies in the `srcset`. Default: the widths up to twice `width` */
|
|
31
|
+
widths?: number[]
|
|
32
|
+
/** The `sizes` attribute. Default: `width` pixels, or the width of the viewport when smaller */
|
|
33
|
+
sizes?: string
|
|
34
|
+
}
|
|
35
|
+
|
|
36
|
+
const {
|
|
37
|
+
src,
|
|
38
|
+
alt,
|
|
39
|
+
width,
|
|
40
|
+
height,
|
|
41
|
+
widths = getMediaImageWidths(width),
|
|
42
|
+
sizes = `(width >= ${width}px) ${width}px, 100vw`,
|
|
43
|
+
loading = 'lazy',
|
|
44
|
+
decoding = 'async',
|
|
45
|
+
...rest
|
|
46
|
+
} = Astro.props
|
|
47
|
+
---
|
|
48
|
+
|
|
49
|
+
<img
|
|
50
|
+
src={getMediaUrl(src, { width, height })}
|
|
51
|
+
srcset={getMediaSrcSet(src, widths, { width, height })}
|
|
52
|
+
sizes={sizes}
|
|
53
|
+
alt={alt}
|
|
54
|
+
width={width}
|
|
55
|
+
height={height}
|
|
56
|
+
loading={loading}
|
|
57
|
+
decoding={decoding}
|
|
58
|
+
{...rest}
|
|
59
|
+
/>
|
|
@@ -2,9 +2,12 @@
|
|
|
2
2
|
/**
|
|
3
3
|
* Responsive Image
|
|
4
4
|
*
|
|
5
|
-
* Render responsive images with 1x and 2x resolution variants.
|
|
5
|
+
* Render responsive images with 1x and 2x resolution variants. A file of the `public`
|
|
6
|
+
* directory is linked with the version of its content, so the host can let the browser keep it.
|
|
6
7
|
*/
|
|
7
8
|
|
|
9
|
+
import { getVersionedPublicPath } from '../site'
|
|
10
|
+
|
|
8
11
|
interface Props {
|
|
9
12
|
/** Path to the image file */
|
|
10
13
|
imgPath: string
|
|
@@ -30,8 +33,8 @@ const basePath = imgPath.split('/').slice(0, -1).join('/')
|
|
|
30
33
|
const basename = imgPath.split('/').pop()?.split('.')[0] || ''
|
|
31
34
|
const ext = imgPath.includes('.') ? `.${imgPath.split('.').pop()}` : ''
|
|
32
35
|
|
|
33
|
-
const imgPath1x = `${basePath}/${basename}${ext}`
|
|
34
|
-
const imgPath2x = `${basePath}/${basename}@2x${ext}`
|
|
36
|
+
const imgPath1x = getVersionedPublicPath(`${basePath}/${basename}${ext}`)
|
|
37
|
+
const imgPath2x = getVersionedPublicPath(`${basePath}/${basename}@2x${ext}`)
|
|
35
38
|
---
|
|
36
39
|
|
|
37
40
|
<img
|
|
@@ -3,7 +3,7 @@ import { replacePlaceholdersInHtml } from '../../libs/placeholder'
|
|
|
3
3
|
import { replaceIconsInHtml } from '../../libs/icon'
|
|
4
4
|
import Code from './Code.astro'
|
|
5
5
|
import Icon from './Icon.astro'
|
|
6
|
-
import { getStaticPath } from '../../site'
|
|
6
|
+
import { getStaticPath, getVersionedStaticPath } from '../../site'
|
|
7
7
|
|
|
8
8
|
interface Props {
|
|
9
9
|
/**
|
|
@@ -70,7 +70,11 @@ const {
|
|
|
70
70
|
|
|
71
71
|
let markup = Array.isArray(code) ? code.join('\n') : code
|
|
72
72
|
markup = replacePlaceholdersInHtml(markup)
|
|
73
|
-
markup = replaceIconsInHtml(
|
|
73
|
+
markup = replaceIconsInHtml(
|
|
74
|
+
markup,
|
|
75
|
+
getStaticPath(),
|
|
76
|
+
getVersionedStaticPath('icons/chassis-icons.svg')
|
|
77
|
+
)
|
|
74
78
|
markup = markup
|
|
75
79
|
.split('\n')
|
|
76
80
|
.map((line) => line.trimEnd())
|
|
@@ -93,7 +97,7 @@ const simplifiedMarkup = sourceMarkup
|
|
|
93
97
|
(_match, classes) => `<img src="..."${classes ? ` class="${classes}"` : ''} alt="...">`
|
|
94
98
|
)
|
|
95
99
|
.replace(/(<svg class="icon\b[^"]*")\s+width="\d+"\s+height="\d+"/g, '$1')
|
|
96
|
-
.replace(/href="\/static\/icons\/chassis-icons\.svg
|
|
100
|
+
.replace(/href="\/static\/icons\/chassis-icons\.svg(?:\?v=[0-9a-f]+)?#/g, 'href="#')
|
|
97
101
|
---
|
|
98
102
|
|
|
99
103
|
<div class="cxd-example-snippet cxd-code-snippet not-prose" data-pagefind-ignore>
|
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
---
|
|
2
|
-
import {
|
|
2
|
+
import { getVersionedStaticPath } from '../../site'
|
|
3
3
|
|
|
4
4
|
/**
|
|
5
5
|
* Icon
|
|
@@ -31,7 +31,7 @@ const {
|
|
|
31
31
|
size = 24,
|
|
32
32
|
font = false,
|
|
33
33
|
title,
|
|
34
|
-
sprite =
|
|
34
|
+
sprite = getVersionedStaticPath('icons/chassis-icons.svg'),
|
|
35
35
|
...rest
|
|
36
36
|
} = Astro.props
|
|
37
37
|
---
|
|
@@ -3,7 +3,7 @@ import { replacePlaceholdersInHtml } from '../../libs/placeholder'
|
|
|
3
3
|
import { replaceIconsInHtml } from '../../libs/icon'
|
|
4
4
|
import Code from './Code.astro'
|
|
5
5
|
import Icon from './Icon.astro'
|
|
6
|
-
import { getStaticPath } from '../../site'
|
|
6
|
+
import { getStaticPath, getVersionedStaticPath } from '../../site'
|
|
7
7
|
|
|
8
8
|
interface Props {
|
|
9
9
|
/**
|
|
@@ -68,7 +68,11 @@ const {
|
|
|
68
68
|
|
|
69
69
|
let markup = Array.isArray(code) ? code.join('\n') : code
|
|
70
70
|
markup = replacePlaceholdersInHtml(markup)
|
|
71
|
-
markup = replaceIconsInHtml(
|
|
71
|
+
markup = replaceIconsInHtml(
|
|
72
|
+
markup,
|
|
73
|
+
getStaticPath(),
|
|
74
|
+
getVersionedStaticPath('icons/chassis-icons.svg')
|
|
75
|
+
)
|
|
72
76
|
|
|
73
77
|
// The resizable container needs `overflow: hidden` for the CSS `resize` handle
|
|
74
78
|
// to work, which clips popovers like menus/dropdowns when they open. Render them
|
|
@@ -95,7 +99,7 @@ const simplifiedMarkup = sourceMarkup
|
|
|
95
99
|
(_match, classes) => `<img src="..."${classes ? ` class="${classes}"` : ''} alt="...">`
|
|
96
100
|
)
|
|
97
101
|
.replace(/(<svg class="icon\b[^"]*")\s+width="\d+"\s+height="\d+"/g, '$1')
|
|
98
|
-
.replace(/href="\/static\/icons\/chassis-icons\.svg
|
|
102
|
+
.replace(/href="\/static\/icons\/chassis-icons\.svg(?:\?v=[0-9a-f]+)?#/g, 'href="#')
|
|
99
103
|
---
|
|
100
104
|
|
|
101
105
|
<div class="cxd-example-snippet cxd-code-snippet" data-pagefind-ignore>
|