@chassis-ui/docs 0.5.1 → 0.6.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.
 

package/UPGRADING.md

@@ -0,0 +1,243 @@
+# Upgrading @chassis-ui/docs
+
+## From 0.5 to 0.6
+
+0.6.0 is a breaking release. In 0.5 a site had to supply five modules behind a `@libs/*`
+path alias, and every site carried its own copy of them. In 0.6 the package owns that code.
+A site adds one integration and deletes its copies.
+
+Do the steps in order. The build fails with a message that names the step you missed.
+
+### 1. Update the dependency
+
+```sh
+pnpm add -D @chassis-ui/docs@^0.6.0
+```
+
+The package now brings these itself. Remove each one that your own code does not import:
+`js-yaml`, `zod`, `clipboard`, `unified`, `unist-util-visit`, `mdast-util-mdx-jsx`,
+`@types/mdast` and `astro-auto-import`.
+
+### 2. Rename the keys of `config.yml`
+
+| 0.5                   | 0.6                                         |
+| --------------------- | ------------------------------------------- |
+| `current_version`     | `currentVersion`                            |
+| `github_org`          | `githubOrg`                                 |
+| `figma_handle`        | `figmaHandle`                               |
+| `x_username`          | `xUsername`                                 |
+| `analytics.google_id` | `analytics.googleId`                        |
+| `docsDir`             | Delete it. The site root is the Astro root. |
+
+- `githubOrg` is the name of the organisation, such as `chassis-ui`. A URL is rejected.
+- `sourceDir` is now relative to the site's root, not to the working directory of the
+  build. For a site that is built from its own directory, the value stays the same.
+- The schema is strict. A key that the package does not know fails the build. See step 4
+  for the keys of your own, such as `blog`, `download` or `cdn`.
+
+Write your own keys in camelCase too, for example `docsVersion` and `exampleIcon`.
+
+Replace the old names in the content as well:
+
+```sh
+grep -rl '\[\[config:current_version\]\]' content src \
+  | xargs sed -i '' 's/\[\[config:current_version\]\]/[[config:currentVersion]]/g'
+```
+
+Three keys outside `config.yml` were renamed as well. An old name fails the build.
+
+| File                       | 0.5                | 0.6               |
+| -------------------------- | ------------------ | ----------------- |
+| `data/sidebar.yml`         | `icon_color`       | `iconColor`       |
+| Frontmatter of a docs page | `added.show_badge` | `added.showBadge` |
+| Frontmatter of a docs page | `extra_js`         | `extraJs`         |
+
+```sh
+sed -i '' 's/icon_color:/iconColor:/' data/sidebar.yml
+grep -rlE '^ *(show_badge|extra_js):' content \
+  | xargs sed -i '' -E 's/^( *)show_badge:/\1showBadge:/; s/^( *)extra_js:/\1extraJs:/'
+```
+
+Rename them in your own components and collection schemas too, where they read
+`icon_color`, `show_badge` or `extra_js`.
+
+### 3. Replace the Astro configuration
+
+Before:
+
+```ts
+import { chassis } from './src/libs/astro'
+import { getConfig } from './src/libs/config'
+import { remarkCxConfig, remarkCxDocsref } from './src/libs/remark'
+import { chassisAutoImportPlugin } from './src/libs/shortcode'
+import { getSiteUrl, getDocsMarkdownConfig } from '@chassis-ui/docs'
+
+export default defineConfig({
+  site: getSiteUrl(getConfig()),
+  integrations: [chassis()],
+  markdown: getDocsMarkdownConfig({
+    anchors: getConfig().anchors,
+    remarkPlugins: [chassisAutoImportPlugin(), remarkCxConfig, remarkCxDocsref, myPlugin]
+  })
+  // ...
+})
+```
+
+After:
+
+```ts
+import { loadConfig } from '@chassis-ui/docs'
+import { chassisDocs } from '@chassis-ui/docs/integration'
+import { chassis } from './src/libs/astro'
+import { siteConfigSchema } from './src/libs/config'
+
+const root = import.meta.dirname
+const config = loadConfig({ root, schema: siteConfigSchema })
+
+export default defineConfig({
+  integrations: [
+    chassisDocs({ config, markdown: { remarkPlugins: [myPlugin] } }),
+    chassis({ config, root })
+  ]
+  // ...
+})
+```
+
+- Remove `site` and `markdown`. The integration sets both.
+- Pass only your own remark and rehype plugins. `rehypeCxTable` is already included.
+- A site that does not need the config in `astro.config.ts` calls `chassisDocs()` with
+  `configSchema` and does not call `loadConfig()`.
+- Remove the Sass load path that points to `@chassis-ui/css/scss/vendor`, the folder of the
+  default `_chassis-tokens.scss`. The integration adds it, after the site's own load paths.
+  Keep a load path that points to tokens of your own.
+
+### 4. Replace the files in `src/libs`
+
+| File            | What to do                                                                                                                                                  |
+| --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `config.ts`     | Replace the content with the schema of your own keys. See below. Delete the file if you have none.                                                          |
+| `validation.ts` | Delete. `zVersionSemver`, `zVersionMajorMinor`, `zPrefixedVersionSemver` and `zLanguageCode` are in `@chassis-ui/docs/schema`. Keep validators of your own. |
+| `clipboard.ts`  | Delete. Import `initCopyButtons` from `@chassis-ui/docs/js/clipboard.ts` if your own code calls it.                                                         |
+| `shortcode.ts`  | Delete. See step 6.                                                                                                                                         |
+| `path.ts`       | Delete. See step 5 for the replacements.                                                                                                                    |
+| `remark.ts`     | Delete `remarkCxConfig`, `remarkCxDocsref` and their helpers. Keep plugins of your own.                                                                     |
+| `data.ts`       | Delete if `sidebar` was the only data you read. Otherwise replace the loader with `createDataLoader()`. See below.                                          |
+| `content.ts`    | Delete `callouts`, `getCalloutByName` and `CalloutName`. Keep the collections that your own pages read.                                                     |
+| `astro.ts`      | Keep. It copies the static files and adds `mdx()` and `sitemap()`. Change it as described below.                                                            |
+
+`src/libs/config.ts`:
+
+```ts
+import { configSchema, z } from '@chassis-ui/docs/schema'
+
+export const siteConfigSchema = configSchema.extend({
+  blog: z.url()
+})
+
+export type SiteConfig = z.infer<typeof siteConfigSchema>
+```
+
+`src/libs/data.ts`, for a site with data files of its own:
+
+```ts
+import { createDataLoader } from '@chassis-ui/docs/site'
+import { z } from '@chassis-ui/docs/schema'
+
+export const getData = createDataLoader({
+  breakpoints: z.object({ name: z.string() }).array()
+})
+```
+
+`src/libs/astro.ts`:
+
+- Take `{ config, root }` as the argument of `chassis()`, and stop calling `getConfig()`.
+- Remove `chassisAutoImportIntegration()` from the list of integrations.
+- Remove the `astro:build:done` hook that calls `validateChassisDocsPaths()`.
+- Import `getChassisAssetsFsPath`, `getChassisCSSFsPath`, `getChassisIconsFsPath` and
+  `getChassisTokensFsPath` from `@chassis-ui/docs` and call them with `{ root }`. Pass
+  `dir` when the folder is not the installed package, as in `chassis-css`, which copies
+  from `../css/dist`.
+- Replace `getDocsFsPath()` with `root`, `getDocsPublicFsPath()` with
+  `path.join(root, 'public')`, and `getDocsStaticFsPath()` with
+  `path.join(root, 'static')`.
+- Remove the Vite alias for `@chassis-ui/css` and `optimizeDeps: { exclude:
+['@chassis-ui/docs'] }`. The integration now makes every script use one copy of
+  `@chassis-ui/css`, in the dev server and in the build. It needs no alias.
+
+### 5. Replace the imports in pages and components
+
+| 0.5                                                 | 0.6                                                |
+| --------------------------------------------------- | -------------------------------------------------- |
+| `getConfig` from `@libs/config`                     | `getConfig` from `@chassis-ui/docs/site`           |
+| `getData('sidebar')` from `@libs/data`              | `getSidebar()` from `@chassis-ui/docs/site`        |
+| `getChassisDocsPath` from `@libs/path`              | `getDocsPath` from `@chassis-ui/docs/site`         |
+| `getDocsFsPath` from `@libs/path`                   | `getSiteRoot` from `@chassis-ui/docs/site`         |
+| `getDocsPublicFsPath` from `@libs/path`             | `getPublicFsPath` from `@chassis-ui/docs/site`     |
+| `getDocsRelativePath(file)` from `@libs/path`       | `getSiteFsPath(file)` from `@chassis-ui/docs/site` |
+| `replaceConfigInText` from `@libs/remark`           | `resolveConfigRefs` from `@chassis-ui/docs/site`   |
+| `replaceDocsrefInText` from `@libs/remark`          | `resolveDocsrefs` from `@chassis-ui/docs/site`     |
+| `getCalloutByName` from `@libs/content`             | `getCallout` from `@chassis-ui/docs/site`          |
+| A path into `node_modules/@chassis-ui/docs/src/`    | `getPackageFilePath('js/color-modes.js')`          |
+| `@chassis-ui/docs/components/shortcodes/Icon.astro` | `@chassis-ui/docs/shortcodes/Icon.astro`           |
+
+Only the paths that the README lists under "Exports" resolve. `@chassis-ui/docs/libs/*`, the
+folders inside `layouts/` and `components/`, and the partials under `scss/` other than `main`
+and `vars` fail with "not exported". Import a layout or component by its name, such as
+`@chassis-ui/docs/layouts/DocsLayout.astro`.
+
+`getConfig()` returns the keys of the package. For the keys of your own, name your type:
+`getConfig<SiteConfig>()`.
+
+Use the schemas of the package in `src/content.config.ts`:
+
+```ts
+import { calloutsSchema, docsSchema } from '@chassis-ui/docs/schema'
+
+const docsCollection = defineCollection({
+  loader: glob({ pattern: '**/*.{md,mdx}', base: './content/docs' }),
+  schema: docsSchema
+})
+```
+
+`docsSchema` is already partial. Do not call `.partial()` on it.
+
+### 6. Shortcodes
+
+- Delete `src/types/auto-import.d.ts`. The integration writes the declarations into
+  `.astro/`.
+- A shortcode in `src/components/shortcodes/` replaces the package's shortcode of the same
+  name. No configuration is needed.
+- To leave out a shortcode of the package, pass
+  `chassisDocs({ shortcodes: { exclude: ['Icon'] } })`.
+
+### 7. Path aliases
+
+The package no longer needs `@libs/*`, `@scss/*` or `@shortcodes/*` in `tsconfig.json`.
+Keep the ones that your own code imports.
+
+The stylesheet that every page loads was `@scss/docs.scss`. It is now `src/scss/docs.scss`
+in the site's root, which is the same file. Pass `styles` to the integration to name
+another one.
+
+### What changes in behaviour
+
+- **Broken `[[docsref:]]` links fail the build.** Five sites only logged them. Fix the
+  links, or pass `brokenDocsrefs: 'warn'` until they are fixed.
+- **A page of the sidebar may have no `title`.** The schema of `data/sidebar.yml` now
+  allows groups, so the type of `title` is `string | undefined`. Code of your own that
+  reads the sidebar has to handle that.
+- **The header shows the Figma and GitHub links only when `figmaHandle` and `githubOrg`
+  are set.** The same holds for the X meta tags and `xUsername`, and for Google Analytics
+  and `analytics.googleId`.
+- **`@chassis-ui/docs` and `@chassis-ui/css` are not pre-bundled in the dev server.** Both
+  are served from source, so a script of the site and a script of the package import the
+  same copy of `@chassis-ui/css`. The dependency `clipboard` is still pre-bundled.
+- **The working directory of the build does not matter.** `config.yml`, `data/` and the
+  `file` props are found from the Astro root. A site that is built with
+  `astro build --root site` no longer names `./site/` in its paths.
+
+### Check the result
+
+Build the site before and after the upgrade and compare the output. An upgrade from 0.5.1
+changes nothing in the output. An upgrade from 0.5.0 or 0.5.0-0 changes the "View on
+GitHub" links, as the changelog describes for 0.5.1.

package/index.ts

@@ -1,11 +1,17 @@
-// Shared libraries for documentation sites
+// Library functions. They are safe to import anywhere: in `astro.config.ts`, in a site's own
+// integrations, and in pages. What pages read from the site is in `@chassis-ui/docs/site`.
+export * from './src/libs/config'
+export * from './src/libs/docs-path'
 export * from './src/libs/highlight'
 export * from './src/libs/image'
 export * from './src/libs/layout'
 export * from './src/libs/markdown'
+export * from './src/libs/paths'
 export * from './src/libs/placeholder'
 export * from './src/libs/rehype'
+export * from './src/libs/remark'
 export * from './src/libs/shortcodes'
 export * from './src/libs/site'
+export * from './src/libs/source'
 export * from './src/libs/toc'
 export * from './src/libs/utils'