@chassis-ui/docs 0.5.1 → 0.6.0-next.0

package/CHANGELOG.md

@@ -0,0 +1,256 @@
+# @chassis-ui/docs
+
+## 0.6.0-next.0
+
+### Minor Changes
+
+- **Breaking.** The package no longer imports `@libs/config`, `@libs/content`, `@libs/data`, `@libs/path`, `@libs/clipboard` or `@scss/docs.scss` from the site. A site adds the integration instead. [UPGRADING.md](https://github.com/chassis-ui/website/blob/main/packages/docs/UPGRADING.md) has the steps.
+- **Breaking.** The keys of `config.yml` are camelCase: `currentVersion`, `githubOrg`, `figmaHandle`, `xUsername` and `analytics.googleId`. An old name fails the build with a message that names the new one. The `docsDir` key is removed: the site root is the Astro root.
+- **Breaking.** Three more keys are camelCase: `iconColor` in `data/sidebar.yml`, and `added.showBadge` and `extraJs` in the frontmatter of docs pages. An old name fails the build.
+- **Breaking.** The schema of `config.yml` is strict. An unknown key fails the build. It was dropped silently.
+- **Breaking.** `exports` lists the supported import paths only: the root entry, `integration`, `schema`, `site`, the four layouts and six components by name, `shortcodes/*`, `js/*`, `scss/main` and `scss/vars`. These no longer resolve: `libs/*`, the other partials under `scss/`, the folders under `layouts/`, and `components/shortcodes/*`. Import a shortcode as `@chassis-ui/docs/shortcodes/Icon.astro`.
+- **Breaking.** `chassisAutoImport()` takes `{ root, dir, include, exclude }` and returns `{ imports, typeDefinitions, plugin }`. It finds the package's shortcodes from the package's own location, and the type declarations go to `.astro/`, not to `src/types/auto-import.d.ts`. Its `docsPath` and `modulesPath` options and its `integration()` are removed.
+- **Breaking.** `getSourceFsPath()`, `getSourceUrl()` and `getSiteFileUrl()` moved from `libs/source` to `@chassis-ui/docs/site`.
+- Add the `chassisDocs()` integration, at `@chassis-ui/docs/integration`. It reads `config.yml` and `data/sidebar.yml`, sets `site` and `markdown`, imports the shortcodes into MDX files and checks `[[docsref:]]` links. It finds every file from the Astro root, so the working directory of the build does not matter.
+- `@chassis-ui/docs/schema` exports the schemas of `config.yml`, the sidebar and the `docs` and `callouts` collections, with their types. A site extends `configSchema` for keys of its own.
+- `@chassis-ui/docs/site` exports what pages read from the site: `getConfig()`, `getSidebar()`, `getDocsPath()`, `getDocsPages()`, `getCallout()`, the path and URL helpers, `getPackageFilePath()` and `createDataLoader()`.
+- The root entry exports `loadConfig()`, `loadData()`, `loadSidebar()`, the remark plugins `remarkCxConfig` and `remarkCxDocsref`, and one implementation of `getChassisTokensFsPath()`, `getChassisAssetsFsPath()`, `getChassisCSSFsPath()` and `getChassisIconsFsPath()`.
+- The integration puts the default `chassis-tokens` of `@chassis-ui/css`, in its `scss/vendor` folder, on the Sass load path, after the site's own load paths. A site can delete the load path it set for it. A site with tokens of its own keeps the folder of its `_chassis-tokens.scss` in its config.
+- Add `include` and `exclude` options for the shortcodes. A shortcode of the site replaces the package's shortcode of the same name.
+- Add `js/clipboard.ts`, which every site carried a copy of.
+- `githubOrg`, `figmaHandle`, `xUsername` and `analytics.googleId` are optional. The header links, the X meta tags and Google Analytics are left out when their key is not set.
+- `anchors`, `toc`, `siteBranch` and `sourceDir` have defaults.
+- Add a versioning policy to the README, and make `scss/vars` a public partial.
+
+### Patch Changes
+
+- The scripts of the package and of the site share one copy of `@chassis-ui/css`. In the dev server of a site that installed the package, `example-mode.js` was pre-bundled with a copy of its own, which registered every listener twice: a dialog opened and closed at once. The integration keeps both packages out of pre-bundling and dedupes `@chassis-ui/css`, so a site needs no alias for it.
+- `<ScssDocs>`, `<ScssDocsSimple>` and `<JsDocs>` stop at the end marker of the part they show. A part whose name starts another name, such as `make-col` and `make-col-auto`, ran on to the end of the longer one.
+- A table of contents whose first heading is deeper than a later one, such as an `<h3>` before the first `<h2>`, nested the `<h2>` under the `<h3>`.
+- Packages whose types the shipped source imports are dependencies, not development dependencies.
+- The README links a starter site, `packages/docs/starter` in the repository, to copy as the start of a new Chassis docs site.
+
+Up to 0.5.1, this repository kept one changelog for the package and the website, headed by the versions of the package. The entries below are that changelog. Changesets writes the entries of later versions.
+
+## [0.5.1] - 2026-09-29
+
+### Added
+
+- `packages/docs`: four optional `config.yml` keys say where files live when a site is not built from the root of its repository: `sourceDir`, `sourcePath`, `sitePath` and `siteBranch`. A site that sets none behaves as before. See the package README.
+- `packages/docs`: the README lists what a site must provide: the `@libs/*` modules, the `config.yml` keys and the `docs` content collection.
+- `packages/docs`: the package ships its `LICENSE` and declares Astro's Node requirement in `engines`.
+
+### Fixed
+
+- `packages/docs`: `<ScssDocs>`, `<ScssDocsSimple>`, `<JsDocs>` and `<Code filePath>` read and link source files relative to `sourceDir` and `sourcePath`, so they work for a site in `packages/site` ([#2](https://github.com/chassis-ui/website/issues/2)).
+- `packages/docs`: "View on GitHub" links to the page's own source file. It linked to `<repo>/blob/<id>.mdx`, which never existed ([#1](https://github.com/chassis-ui/website/issues/1)).
+- `packages/docs`: the README named example imports that do not exist and an outdated `@chassis-ui/css` peer range.
+
+### Changed
+
+- Website: moved to `@chassis-ui/css` 0.5.2 and `@chassis-ui/tokens` 0.5.3, which changes colours, border radii and dark-mode backgrounds.
+- Updated dependencies within their ranges, including Astro 7.3.5. This clears every `pnpm audit` advisory, including a critical one in Astro.
+- The production build uses the `vendor/assets` commit pinned in this repository instead of the latest `app/docs`.
+- CI builds the site and validates its HTML. The Lighthouse run works again.
+
+### Removed
+
+- Stale files: `PROJECT_REVIEW.md`, the multi-platform sync tooling under `build/`, and committed build output under `examples/`.
+
+## [0.5.0] - 2026-09-19
+
+### Changed
+
+- Reworked breakpoint and sizing utility classes/tokens across `packages/docs` and `packages/website` to use the shorthand naming from the updated Chassis CSS (e.g. `large:px-xsmall` → `lg:px-xs`, `medium` → `md`), spanning layouts, components, shortcodes, SCSS partials, and page templates
+- Bumped `@chassis-ui/css` and `@chassis-ui/tokens` peer dependencies to `^0.5.0`
+
+## [0.4.0] - 2026-09-15
+
+### Changed
+
+- Bumped `@chassis-ui/css` and `@chassis-ui/tokens` to `^0.4.0`
+- `packages/docs/src/scss/_sidebar.scss`: reworked subgroup label styling (uppercase, `--cx-font-size-xsmall`, `--cx-primary-fg-main` color, adjusted spacing) and the `::before` connector line selectors to correctly handle first-child/only-child/subgroup combinations
+- `packages/docs/src/scss/_search.scss`: adjusted the search dialog's large-breakpoint offset from `13rem` to `11rem` (both LTR and RTL)
+- `ThemeToggler.astro` and header nav links (`Navigation.astro`): replaced `px-0 large:px-small` with `px-0 large:px-xsmall`; `ThemeToggler` also gained a `caret` class
+- `SearchDialog.astro`: renamed the search icon wrapper class from `input-help` to `input-adorn`
+
+## [0.3.10] - 2026-07-21
+
+### Added
+
+- Blog link to the navbar
+
+## [0.3.9] - 2026-07-19
+
+### Added
+
+- `packages/docs`: new `zoom.js` script — initialises `medium-zoom` on any element tagged `[data-zoomable]`; `medium-zoom` added as a dependency
+- `packages/docs/src/libs/image.ts`: new `getRemoteImageSize()` helper that fetches a remote image at build time and returns its pixel dimensions; used by `Social.astro` for CDN-hosted thumbnails
+- `packages/docs/src/layouts/head/Social.astro`: `<meta property="og:site_name">` tag
+
+### Changed
+
+- `packages/docs/src/layouts/head/Social.astro`: supports remote thumbnail URLs — when `thumbnail` starts with `http(s)://` it uses `getRemoteImageSize()` instead of reading a local file
+- `packages/docs/src/components/ResponsiveImage.astro`: forwards extra props (`...rest`) to the rendered `<img>` element
+- `packages/docs/package.json`: bumped `@chassis-ui/css` peer dependency to `>=0.3.4`
+
+## [0.3.8] - 2026-07-14
+
+### Added
+
+- `<link rel="preconnect">` hints for Google Fonts (`fonts.googleapis.com`, `fonts.gstatic.com`) in `Head.astro`, and for the jsDelivr CDN (Swiper) on the homepage
+
+### Fixed
+
+- `packages/docs/src/scss/main.scss`: corrected an invalid `margin--block-start` property to `margin-block-start`
+
+## [0.3.7] - 2026-07-13
+
+### Fixed
+
+- `api/contact.ts`: the contact form handler now checks the `error` returned from `resend.emails.send()`'s response and returns a 500 instead of silently reporting success; previously only request-level failures (network errors, etc.) were caught, not API-level errors returned in the response body
+- Support form (`SupportSection.astro`) success/error states now use the `notification` component.
+- `packages/website/config.yml`: `repo` was pointing at the `chassis-ui/docs` repository; corrected to `chassis-ui/website`
+
+### Changed
+
+- Renamed the `x` site config key to `x_username`, changed `github_org` to hold a bare org slug instead of a full URL, and added a new `figma_handle` key (config schema updated to match)
+- Docs header navigation: replaced the X/Twitter link with a new link to the Chassis Figma Community profile, alongside GitHub
+- CI: bumped `pnpm/action-setup` to v6 and `softprops/action-gh-release` to v3 in `publish-packages.yml`, and renamed the docs npm publish token secret to `NPM_CHASSIS_UI`
+- Bumped `@chassis-ui/css` to `^0.3.3` in `packages/docs` peerDependencies
+- Bumped `@chassis-ui/icons` to `^0.3.1` in `packages/website`
+
+## [0.3.6] - 2026-07-06
+
+### Fixed
+
+- Multi-site search no longer breaks entirely when a sibling Chassis site's Pagefind index is unreachable (bad deploy, rollout still in progress across the separate repos). Previously `mergeIndex` was passed up front and a single failed merge threw and corrupted the shared instance for every future search, including the current site's own results. Now the current site's own index loads first, and each sibling is probed — both its `pagefind-entry.json` and the language-specific `pagefind.<hash>.pf_meta` chunk `init()` actually requests — before `mergeIndex` is attempted, so an unreachable sibling is skipped instead of taking down search
+- The site filter dropdown (`cxd-search-filter`) is now always rendered instead of only when other sites were successfully merged in at load time
+- Search result item icons now reference the shared icon sprite (`/static/icons/chassis-icons.svg#…`) instead of a bare `#id` fragment, which resolved against the current page instead of the sprite
+- Removed the unused `vite` devDependency from `@chassis-ui/docs`; it only backed the `chassisBundlePlugin` removed in 0.3.4 and had no remaining imports
+- `@pagefind/component-ui` is no longer marked `optional` in `peerDependenciesMeta` — every docs layout unconditionally renders the search dialog and imports it, and every consuming site already installs it directly, so it was never actually optional
+- `README.md`: corrected the peer dependencies list (was just `astro: ^5.0.0`; now matches the full, actual `package.json` peer set) and the `@chassis-ui/docs` exports table, which was missing `highlight`, `markdown`, `placeholder`, `shortcodes`, `site` and listed a nonexistent `chassis` module
+
+### Changed
+
+- Refactored `search.js`: renamed the `renderItem` params `title`/`excerpt` to `titleHtml`/`excerptHtml` to make explicit that callers must pass pre-escaped/pre-marked HTML, and extracted `renderResultsList` and `addListeners` helpers to remove repeated markup and bind/track/remove boilerplate across the custom elements
+
+## [0.3.5] - 2026-07-06
+
+### Added
+
+- Multi-site Pagefind search: the docs search dialog now merges every Chassis project's index (`website`, `tokens`, `css`, `assets`, `icons`, `figma`) into one site-filterable search with a new site filter dropdown (`cxd-search-filter`) to scope results to a single project or "Everywhere"
+
+### Changed
+
+- `_search.scss` rules moved into `@layer custom` to fix cascade ordering against `@chassis-ui/css`
+- `pagefind.yml`: added `root_selector: "main"` so indexing skips shared chrome (nav, footer) and only picks up page content
+
+### Fixed
+
+- `packages/website/src/scss/home.scss`: removed unused `docs`/`@chassis-ui/css/scss/config` imports and a leftover `background-image` override on `.module-item`, and dropped an unnecessary `#{calc(...)}` interpolation
+- `HeroSection.astro`: added missing whitespace between the two `<h1>` text segments
+
+## [0.3.4] - 2026-07-05
+
+### Fixed
+
+- Removed the dev-mode virtual-module Vite plugin (`chassisBundlePlugin`) that resolved `@chassis-ui/css` to a fake module in `Scripts.astro`. Vite's `optimizeDeps` pre-bundling of `@chassis-ui/docs/js/example-mode.js` ran before the plugin's `resolveId`/`load` hooks could apply, inlining a second, un-deduped copy of every `@chassis-ui/css` component — duplicate `document`-level `data-cx-toggle`/`data-cx-dismiss` click handlers, causing modal/drawer/etc. to double-toggle in consumers' dev servers
+- `Scripts.astro` now loads Chassis JS with a plain `import '@chassis-ui/css'` instead of a hand-computed dev/prod `<script is:inline>` src. Consumers who install `@chassis-ui/css` as a real dependency (e.g. `packages/website`) need no special config — the import resolves normally and Vite's own dependency optimizer dedupes it. Consumers who self-host `@chassis-ui/css` (i.e. _are_ that package) need to alias it to their own build output in dev themselves — see chassis-css's own `site/src/libs/astro.ts` for the pattern
+- `packages/website/src/libs/astro.ts`: removed a call to the now-removed `chassisBundlePlugin`
+- `packages/website/astro.config.ts`: removed a dead `rollupOptions.external`/`output.paths` pair that never applied — Astro 7.0.6's client build config only reads the `output` sub-key of `rolldownOptions`, never `external`, so `@chassis-ui/css` was never actually externalized despite the config implying it was
+- Worked around a `@chassis-ui/css` bug (fixed upstream in `@chassis-ui/css@0.3.2`) where a missing `sideEffects` entry for its package entry point let bundlers tree-shake away components nobody imported by name (`Dialog`, `Drawer`, `Accordion`, etc.), breaking modal/drawer in `packages/website`'s production build
+
+## [0.3.3] - 2026-07-05
+
+### Fixed
+
+- Corrected an incorrect `@chassis-ui/css` peer dependency version on `@chassis-ui/docs`
+
+## [0.3.2] - 2026-07-05
+
+### Fixed
+
+- `<ScssDocs>` no longer drops rules when a compiled snippet mixes plain declarations with directives that emit their own selectors (e.g. `@each`); sentinel unwrapping now walks brace depth instead of matching a single block
+- `<ScssDocs>` Sass compilation now resolves bare npm specifiers (e.g. `@chassis-ui/tokens/...`) by adding `node_modules` to `loadPaths`
+- `change-version` script no longer bumps the root `package.json` version, which was unused and unrelated to the published `@chassis-ui/docs` version
+
+## [0.3.1] - 2026-07-05
+
+### Fixed
+
+- Moved `@chassis-ui/docs`'s runtime-only dependencies (`image-size`, `github-slugger`, `remark`, `remark-html`, `mdast-util-from-markdown`, `mdast-util-to-string`, `unist-util-visit`) from `devDependencies` to `dependencies`, since consumers couldn't resolve them under `devDependencies`
+- Bumped the `htmlparser2` and `sass` peer dependency ranges on `@chassis-ui/docs` to match the versions consumers actually install
+
+## [0.3.0] - 2026-07-04
+
+### Added
+
+- Pagefind-powered site search, replacing the Algolia search integration
+- New `Icon` component for docs/website, replacing ad-hoc icon markup across shortcodes and pages, with accessibility improvements (proper SVG titles, ARIA handling)
+- New `Code`, `Example`, `ResizableExample`, and `ScssDocs` shortcode components, and a `clipboard.ts` utility for copy-to-clipboard in code blocks
+
+### Changed
+
+- Large-scale Chassis CSS update and SCSS variable reorganization across the docs and website packages
+- Upgraded dependencies and refreshed the lockfile
+- Reworked Astro config, shortcode registration, and homepage section components to match the updated design system
+- Moved `example-mode.js` from the website package into docs.
+- Removed the old `icon-loader.js`, `Icon` component uses path to SVG sprite
+- Replaced Prism-based syntax highlighting with Shiki
+- Removed the Algolia search plugin
+- Rewrote reference docs to reflect the current setup
+- Cleaned up code and removed unused website dependencies
+
+### Fixed
+
+- Astro type-check errors across docs/website pages
+- `sync-submodules` build script
+
+## [0.2.0] - 2026-05-03
+
+### Added
+
+- Updated test pages and containers/responsive utilities
+
+### Changed
+
+- Updated Chassis CSS
+
+### Fixed
+
+- CI workflow fixes and linting issues
+- `placeholder.ts` fix
+
+## [0.1.10] - 2026-04-28
+
+### Added
+
+- Staging branch deployment support
+- Coming soon page for the main branch
+- Docs test page and sitemap filter updates
+
+### Changed
+
+- Improved blog and updated layouts
+- Bumped docs package version
+
+### Fixed
+
+- Vercel deployment configuration
+- vnu (HTML validator) errors and path ignoring in `vnu-jar.js`
+- Linting errors
+
+## [0.1.0] - 2025-08-24
+
+### Added
+
+- Initial project setup: Astro-based website, docs package, and Chassis UI vendor submodule
+- Build-time icon integration, submodule configuration, and initial CI workflows
+
+[0.3.2]: https://github.com/chassis-ui/website/compare/v0.3.1...v0.3.2
+[0.3.1]: https://github.com/chassis-ui/website/compare/v0.3.0...v0.3.1
+[0.3.0]: https://github.com/chassis-ui/website/compare/v0.2.0...v0.3.0
+[0.2.0]: https://github.com/chassis-ui/website/compare/v0.1.10...v0.2.0
+[0.1.10]: https://github.com/chassis-ui/website/compare/v0.1.0...v0.1.10
+[0.1.0]: https://github.com/chassis-ui/website/releases/tag/v0.1.0

package/README.md

@@ -2,26 +2,22 @@
 
 > Shared Astro layouts, components, and utilities for Chassis documentation sites.
 
-[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT) [![Version: 0.5.1](https://img.shields.io/badge/Version-0.5.1-blue.svg)](https://www.npmjs.com/package/@chassis-ui/docs) [![npm](https://img.shields.io/npm/v/@chassis-ui/docs.svg)](https://www.npmjs.com/package/@chassis-ui/docs)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT) [![npm](https://img.shields.io/npm/v/@chassis-ui/docs.svg)](https://www.npmjs.com/package/@chassis-ui/docs)
 
 ## Overview
 
-`@chassis-ui/docs` powers every documentation site in the Chassis ecosystem — the main `chassis-ui.com` website and the per-package docs for `chassis-css`, `chassis-tokens`, `chassis-icons`, `chassis-figma`, and `chassis-assets`. It ships pre-built layouts, navigation components, content-processing utilities, and SCSS helpers so each site stays consistent without duplicating code.
+`@chassis-ui/docs` powers every documentation site in the Chassis ecosystem: the main `chassis-ui.com` website and the docs of `chassis-css`, `chassis-tokens`, `chassis-icons`, `chassis-figma`, `chassis-assets` and `chassis-react`. It ships layouts, navigation components, shortcodes for MDX, content-processing utilities and SCSS, so each site stays consistent without copying code.
 
 > [!NOTE] This package is developed inside the [`chassis-website`](https://github.com/chassis-ui/website) monorepo at `packages/docs/` and published to npm. Source, issues, and pull requests live in that repository.
 
+Coming from 0.5? See [UPGRADING.md](UPGRADING.md).
+
 ## Installation
 
 ```sh
 pnpm add @chassis-ui/docs
 ```
 
-or:
-
-```sh
-npm install @chassis-ui/docs
-```
-
 ### Peer Dependencies
 
 ```json
@@ -38,96 +34,255 @@ npm install @chassis-ui/docs
 }
 ```
 
-In practice, sites also install the rest of the Chassis stack — `@chassis-ui/tokens`, `@chassis-ui/icons` — to render the layouts and styles correctly.
+A site also installs `@astrojs/mdx` and the rest of the Chassis stack, `@chassis-ui/tokens` and `@chassis-ui/icons`.
+
+## Setup
 
-## Usage
+A site needs four things before it can use the layouts: the integration, a `config.yml`, two content collections and the static files that the layouts link to.
+
+The [starter site](starter/) has all four. Copy it to start a new site, and follow its README. CI builds it from the packed package on every push, so it works with the version of the package next to it.
+
+### 1. Add the integration
+
+```ts
+// astro.config.ts
+import { defineConfig } from 'astro/config'
+import mdx from '@astrojs/mdx'
+import { chassisDocs } from '@chassis-ui/docs/integration'
+
+export default defineConfig({
+  integrations: [chassisDocs(), mdx()]
+})
+```
+
+The integration:
+
+- reads and validates `config.yml` and `data/sidebar.yml`, and gives them to the layouts and components
+- sets `site` from `baseURL`, unless the Astro config sets `site` itself
+- sets `markdown`: heading anchors, Shiki themes, and the `[[config:key]]` and `[[docsref:/path]]` replacements
+- imports the shortcodes into every MDX file
+- fails the build when a `[[docsref:]]` link points to a page that was not built
+- makes the scripts of the package and of the site share one copy of `@chassis-ui/css`, so that no listener is registered twice
+- puts the default design tokens of `@chassis-ui/css` on the Sass load path, which the styles need
+
+It finds every file from the Astro root, the directory that holds `astro.config.ts`. The working directory of the build does not matter.
+
+| Option           | Default                                  | Meaning                                                                                            |
+| ---------------- | ---------------------------------------- | -------------------------------------------------------------------------------------------------- |
+| `config`         | none                                     | The config, when the site has loaded it itself with `loadConfig()`                                 |
+| `configFile`     | `'config.yml'`                           | Path of the config file, from the site's root                                                      |
+| `configSchema`   | `configSchema`                           | Schema of the config file. See [keys of your own](#keys-of-your-own)                               |
+| `sidebarFile`    | `'data/sidebar.yml'`, when it exists     | Path of the sidebar data, or `false` for no sidebar                                                |
+| `styles`         | `['src/scss/docs.scss']`, when it exists | Stylesheets that every page loads. Without one, the package's own styles are loaded                |
+| `shortcodes`     | all                                      | `{ dir, include, exclude }`. See [shortcodes](#shortcodes)                                         |
+| `markdown`       | none                                     | `{ remarkPlugins, rehypePlugins, remarkRehype }` of the site. They run after the package's plugins |
+| `brokenDocsrefs` | `'error'`                                | `'error'`, `'warn'` or `'ignore'`                                                                  |
+
+#### Tokens of your own
+
+The styles of `@chassis-ui/css` load the design tokens as `chassis-tokens`. The integration adds the folder with the default one, `scss/vendor` of `@chassis-ui/css`, as the last Sass load path. A site with tokens of its own adds the folder of its `_chassis-tokens.scss` in its Astro config, which comes first:
+
+```ts
+// astro.config.ts
+export default defineConfig({
+  vite: {
+    css: { preprocessorOptions: { scss: { loadPaths: ['src/scss/tokens'] } } }
+  }
+})
+```
+
+### 2. Write `config.yml`
+
+```yaml
+title: 'Chassis - CSS'
+subtitle: 'A Tokenized CSS Framework'
+description: 'An open-source, tokenized CSS framework.'
+authors: 'Ozgur Gunes'
+baseURL: 'https://chassis-ui.com/css'
+docsPath: '/css/docs'
+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. Loaded in production builds only                                             |
+| `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>`.
+
+The schema is strict. A key that it does not know fails the build, so a typing error cannot go unnoticed.
+
+#### Keys of your own
+
+Extend the schema and pass it to the integration. Use the `z` that the package exports, so that the site and the package share one copy of Zod.
+
+```ts
+// src/libs/config.ts
+import { configSchema, z } from '@chassis-ui/docs/schema'
+
+export const siteConfigSchema = configSchema.extend({
+  download: z.object({ dist: z.url(), source: z.url() })
+})
+
+export type SiteConfig = z.infer<typeof siteConfigSchema>
+```
+
+```ts
+// astro.config.ts
+integrations: [chassisDocs({ configSchema: siteConfigSchema })]
+```
 
 ```astro
 ---
-import BaseLayout from '@chassis-ui/docs/layouts/BaseLayout.astro'
-import DocsLayout from '@chassis-ui/docs/layouts/DocsLayout.astro'
-import SingleLayout from '@chassis-ui/docs/layouts/SingleLayout.astro'
+import { getConfig } from '@chassis-ui/docs/site'
+import type { SiteConfig } from '@libs/config'
+
+const { download } = getConfig<SiteConfig>()
+---
+```
+
+### 3. Define the content collections
+
+The layouts read the `docs` collection, and `<Callout name>` reads the `callouts` collection.
+
+```ts
+// src/content.config.ts
+import { defineCollection } from 'astro:content'
+import { glob } from 'astro/loaders'
+import { calloutsSchema, docsSchema } from '@chassis-ui/docs/schema'
+
+export const collections = {
+  docs: defineCollection({
+    loader: glob({ pattern: '**/*.{md,mdx}', base: './content/docs' }),
+    schema: docsSchema
+  }),
+  callouts: defineCollection({
+    loader: glob({ pattern: '**/*.md', base: './content/callouts' }),
+    schema: calloutsSchema
+  })
+}
+```
+
+### 4. Provide the static files
 
-import TableOfContents from '@chassis-ui/docs/components/TableOfContents.astro'
-import ThemeToggler from '@chassis-ui/docs/components/ThemeToggler.astro'
+The layouts link to files under `/static/`, which the site puts into its `public` directory:
 
-import { generateToc, getStaticImageSize } from '@chassis-ui/docs'
+| URL                                                                  | From                                      |
+| -------------------------------------------------------------------- | ----------------------------------------- |
+| `/static/css/chassis.css`, `/static/css/chassis.min.css`             | the `dist` folder of `@chassis-ui/css`    |
+| `/static/icons/chassis-icons.svg`, `/static/icons/chassis-icons.css` | the `icons` folder of `@chassis-ui/icons` |
+| `/static/images/*`: logo, favicons, social image                     | the docs build of `chassis-assets`        |
+
+These helpers find the folders, whether `node_modules` is in the site's root or in the root of the repository: `getChassisCSSFsPath()`, `getChassisIconsFsPath()`, `getChassisAssetsFsPath()` and `getChassisTokensFsPath()`. Each takes `{ root, dir }`.
+
+A site that type-checks with `astro check` declares the `@chassis-ui/css` module, which has no types: `declare module '@chassis-ui/css'`.
+
+### 5. Use the layouts
+
+```astro
+---
+import SingleLayout from '@chassis-ui/docs/layouts/SingleLayout.astro'
 ---
 
-<SingleLayout title="About" description="…">
-  <slot />
+<SingleLayout title="About" description="What Chassis is and who makes it.">
+  <p>Page content.</p>
 </SingleLayout>
 ```
 
-## What a site must provide
+## Shortcodes
 
-The layouts and components read from the consuming site. A site must provide the
-following, or the build fails.
+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.
 
-### Modules behind the `@libs/*` path alias
+```ts
+chassisDocs({
+  shortcodes: {
+    // Leave out shortcodes whose names the site uses for something else
+    exclude: ['Icon']
+  }
+})
+```
 
-The site maps `@libs/*` to its own `src/libs/*` in `tsconfig.json`, and each module
-exports:
+## What pages read from the site
 
-| Module            | Exports                                                                         | Read by                                |
-| ----------------- | ------------------------------------------------------------------------------- | -------------------------------------- |
-| `@libs/config`    | `getConfig()`, returning the parsed `config.yml`                                | most layouts and components            |
-| `@libs/content`   | `docsPages`, the `docs` collection. `getCalloutByName(name)` and `CalloutName`. | `DocsLayout`, `DocsSidebar`, `Callout` |
-| `@libs/data`      | `getData('sidebar')`, and the types `SidebarItem` and `SidebarSubItem`          | `DocsSidebar`                          |
-| `@libs/path`      | `getChassisDocsPath(path)` and `getDocsPublicFsPath()`                          | `DocsLayout`, `Social`                 |
-| `@libs/clipboard` | `initCopyButtons(selector, getText)`                                            | `Code`                                 |
+`@chassis-ui/docs/site` is for pages and components. It does not work in `astro.config.ts` or in the browser.
 
-The site also defines a `docs` content collection. Its entry type is used by
-`BaseLayout` and `DocsLayout`.
+| Function                                           | Returns                                                             |
+| -------------------------------------------------- | ------------------------------------------------------------------- |
+| `getConfig()`                                      | The parsed `config.yml`                                             |
+| `getSidebar()`                                     | The parsed `data/sidebar.yml`                                       |
+| `getDocsPath(path)`                                | URL path of a docs page                                             |
+| `getDocsPages()`                                   | The entries of the `docs` collection                                |
+| `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                   |
+| `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           |
+| `getPackageFilePath(file)`                         | Absolute path of a file of this package, e.g. `'js/color-modes.js'` |
+| `resolveConfigRefs(text)`, `resolveDocsrefs(text)` | `text` with `[[config:]]` or `[[docsref:]]` replaced                |
+| `createDataLoader(definitions)`                    | A `getData(name)` function for the site's own YAML files in `data/` |
 
-### Keys in `config.yml`
+Code that runs while Astro loads its configuration uses the library functions of the root entry instead: `loadConfig()`, `loadData()`, `loadSidebar()` and the path helpers.
 
-`getConfig()` must return these keys:
+## Exports
 
-- `title`, `subtitle`, `description`, `authors`
-- `repo`, `current_version`, `docsPath`
-- `github_org`, `figma_handle`, `x_username`
-- `anchors.min`, `anchors.max`
-- `analytics.google_id`
+These import paths are the public API.
 
-These keys are optional. They say where files live when the site is not built from the
-root of its repository:
+| Path                            | Contents                                                                                                                                                                                                                           |
+| ------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `@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 |
+| `@chassis-ui/docs/integration`  | `chassisDocs()` and the type of its options                                                                                                                                                                                        |
+| `@chassis-ui/docs/schema`       | `z`, `configSchema`, `sidebarSchema`, `docsSchema`, `calloutsSchema`, the version validators, and the types `ChassisConfig`, `Sidebar`, `SidebarItem`, `DocsFrontmatter`, `DocsPage`                                               |
+| `@chassis-ui/docs/site`         | What pages read from the site. See above                                                                                                                                                                                           |
+| `@chassis-ui/docs/layouts/*`    | `BaseLayout.astro`, `DocsLayout.astro`, `RedirectLayout.astro`, `SingleLayout.astro`                                                                                                                                               |
+| `@chassis-ui/docs/components/*` | `DocsSidebar.astro`, `FeatureCard.astro`, `NavLink.astro`, `ResponsiveImage.astro`, `TableOfContents.astro`, `ThemeToggler.astro`                                                                                                  |
+| `@chassis-ui/docs/shortcodes/*` | The MDX shortcodes                                                                                                                                                                                                                 |
+| `@chassis-ui/docs/js/*`         | Client-side scripts: `example-mode.js`, `clipboard.ts`, `color-modes.js` and others                                                                                                                                                |
+| `@chassis-ui/docs/scss/main`    | The styles of the package. The integration loads them when the site has no stylesheet of its own                                                                                                                                   |
+| `@chassis-ui/docs/scss/vars`    | The Sass variables and custom properties of the docs, for a site's own stylesheets                                                                                                                                                 |
 
-| Key          | Meaning                                                                                                           | Example           |
-| ------------ | ----------------------------------------------------------------------------------------------------------------- | ----------------- |
-| `sourceDir`  | Directory that the `file` props of the source-file shortcodes are relative to, from the build's working directory | `"../css"`        |
-| `sourcePath` | The same directory, from the root of the repository                                                               | `"packages/css"`  |
-| `sitePath`   | The site's root, from the root of the repository                                                                  | `"packages/site"` |
-| `siteBranch` | The branch that "View on GitHub" links to. Defaults to `main`.                                                    | `"main"`          |
+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 source-file shortcodes are `<ScssDocs>`, `<ScssDocsSimple>`, `<JsDocs>` and
-`<Code filePath>`. They link to their files at the tag `v<current_version>`.
+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.
 
-A site that validates `config.yml` with `z.object` must add the optional keys to its
-schema. Otherwise they are dropped silently.
+## Versioning
 
-## Exports
+The package follows [Semantic Versioning](https://semver.org/). Before 1.0 that means:
 
-| Subpath                         | Contents                                                                                                                     |
-| ------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
-| `@chassis-ui/docs`              | Library functions: `highlight`, `image`, `layout`, `markdown`, `placeholder`, `rehype`, `shortcodes`, `site`, `toc`, `utils` |
-| `@chassis-ui/docs/layouts/*`    | `BaseLayout`, `DocsLayout`, `RedirectLayout`, `SingleLayout`                                                                 |
-| `@chassis-ui/docs/components/*` | `DocsSidebar`, `FeatureCard`, `NavLink`, `ResponsiveImage`, `TableOfContents`, `ThemeToggler`                                |
-| `@chassis-ui/docs/shortcodes/*` | MDX shortcode components                                                                                                     |
-| `@chassis-ui/docs/libs/*`       | Direct access to individual library modules                                                                                  |
-| `@chassis-ui/docs/js/*`         | Client-side scripts                                                                                                          |
-| `@chassis-ui/docs/scss/*`       | SCSS utilities and partials                                                                                                  |
+- A minor release, 0.x.0, may contain breaking changes. Each one is listed in [CHANGELOG.md](CHANGELOG.md) and has a step in [UPGRADING.md](UPGRADING.md).
+- A patch release, 0.x.y, contains none.
 
-### Source Layout
+A change is breaking when it changes something that this README documents:
 
-```
-src/
-├── components/      # Astro components (+ shortcodes/)
-├── layouts/         # Page layouts (+ head/, header/, footer/)
-├── libs/            # Utility libraries
-├── js/              # Client-side scripts
-└── scss/            # Styling utilities
-```
+- the import paths listed under [Exports](#exports), and what they export
+- the options of the integration
+- 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 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.
+
+1.0 is released when all three hold:
+
+1. Every Chassis site uses the integration and carries no copy of code that the package provides.
+2. Unit tests and builds of a fixture site run before every release.
+3. Releases are automated and published with provenance.
 
 ## Chassis Ecosystem
 
@@ -141,6 +296,7 @@ This package is part of the Chassis Design System's multi-repository architectur
 | [chassis-icons](https://github.com/chassis-ui/icons)     | Icon library and build toolkit                                 |
 | [chassis-assets](https://github.com/chassis-ui/assets)   | Multi-platform asset management                                |
 | [chassis-figma](https://github.com/chassis-ui/figma)     | Figma component documentation                                  |
+| [chassis-react](https://github.com/chassis-ui/react)     | React component library                                        |
 
 All documentation sites in the ecosystem share this package for consistent layouts, components, and styling.