@chassis-ui/docs 0.7.0 → 0.8.0

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # @chassis-ui/docs
 
+## 0.8.0
+
+### Minor Changes
+
+- **Breaking.** The pages load their fonts from the site's own static files, no longer from Google Fonts. `Head.astro` links `fonts/text.css`, `fonts/display.css` and `fonts/code.css` under the static path, `/static/` by default, in place of the Google Fonts stylesheet and the `preconnect` links to `fonts.googleapis.com` and `fonts.gstatic.com`. The three stylesheets and the font files they load are in the docs build of `chassis-assets`, which a site copies into `static/` already. A site moves its `vendor/assets` submodule to `acb5d2e` of `app/docs` or later, with `pnpm sync-submodules`: there the stylesheets declare Inter, Archivo Narrow and Fira Code as variable fonts, with every weight the styles use. With a commit before `77912ed` they declare four weights of each family. The Inter of the assets has an optical size axis, which the font of Google Fonts had not, and a browser follows it: text above 14 pixels is narrower, 7% at 57 pixels. A site keeps the look it had by building the assets with `--subset` of `chassis-docs vendor`, which fixes the axis at 14 from `acb5d2e` on, or by setting `font-optical-sizing: none` in its styles. A site that does not copy the docs build provides the three stylesheets itself.
+- `chassis-docs vendor` and `chassis-docs sync-submodules` take `--subset <range>`, repeatable, and `--split` or `--no-split` with it. With `--subset` the fonts of the docs build of `chassis-assets` are written with the characters of the ranges only, such as `--subset latin --subset latin-ext`, and the optical size axis of Inter is fixed at 14, as `chassis-assets` sets it for the `chassis` brand. With `--split` each font is also written in a file per range, and its stylesheet names them with a `unicode-range`, so a page loads a range only when it has a character of it; without `--split` and `--no-split` the setting of `chassis-assets` decides, which is one file. With the two ranges and the split, a page in English loads `text-latin.woff2`, 69 KB, where the whole `text.woff2` is 349 KB, and `code-latin.woff2`, 43 KB, where `code.woff2` is 109 KB. A character outside the ranges is drawn with the next font of the font stack. With `--subset` the commands run `pnpm install --filter ./packages/assets --prod` in the submodule, in place of `pnpm install --ignore-workspace`, since the build loads a package to subset a font. The options need `vendor/assets` at `acb5d2e` of `app/docs` or later. Without them nothing changes.
+
 ## 0.7.0
 
 ### Minor Changes

package/README.md

@@ -10,7 +10,7 @@
 
 > [!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).
+Coming from an earlier version? See [UPGRADING.md](UPGRADING.md).
 
 ## Installation
 
@@ -184,18 +184,43 @@ export const collections = {
 
 The layouts link to files under `/static/`, which the site puts into `static/` of its `public` directory:
 
-| 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`        |
+| 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/site-logo.svg`, the logo of the navigation bar and the footer                                                      | the docs build of `chassis-assets`                       |
+| `/static/images/favicon.png`, `favicon-16x16.png`, `favicon-32x32.png` and `apple-touch-icon.png`                                  | the docs build of `chassis-assets`                       |
+| `/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`                       |
+| `/static/fonts/text.css`, `/static/fonts/display.css`, `/static/fonts/code.css`, and the font files they load                      | the docs build of `chassis-assets`                       |
+| `/static/images/manifest.json`, the web app manifest                                                                               | the site itself. The starter has one in `static/images/` |
 
 `chassis-docs vendor` builds the docs build of `chassis-assets` in the `vendor/assets` submodule. See [Commands](#commands).
 
+Nothing else of the docs build is read by the package. A site copies the whole build into `static/`, and its own pages may read more of it.
+
 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'`.
 
+#### What the Chassis sites read from the docs build
+
+The sites of the Chassis projects read these files besides, by name, from the docs build of the `chassis` brand:
+
+| File of the docs build                                                   | Read by                                                                                                         |
+| ------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------- |
+| `icons/cx-sprite.svg`                                                    | The home page of each of the seven sites, which imports it. The build fails without it                          |
+| `images/apple-touch-icon.png`, `images/favicon.png`                      | Each of the seven sites, which copies them to `/apple-touch-icon.png` and `/favicon.ico`                        |
+| `images/android-chrome-192x192.png`, `images/android-chrome-512x512.png` | The `manifest.json` of each of the seven sites                                                                  |
+| `images/home/`                                                           | The home page of the website. The home page of chassis-tokens reads `comp-gallery-*` of it                      |
+| `images/logo/chassis-{logo,icon}-{brand,white}-banner.svg`               | The about page of the website                                                                                   |
+| `images/social-image.png`                                                | The blog of the website, for a post without an image                                                            |
+| `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 |
+| `images/figma/components/`                                               | The component pages of chassis-figma                                                                            |
+
+The vanilla HTML example, in the `vanilla-example` repository, builds the assets itself from a `vendor/assets` submodule of its own, for the brand of each of its sites, and takes `fonts/text.css`, `fonts/display.css` and `fonts/code.css`, the font files they load, the license of each font and `images/logo/chassis-icon-brand.svg`.
+
+`contracts` in `chassis.checks.json` of `chassis-assets` names the files that a site reads, with the code that reads each, and `pnpm assets:contract` there checks a build against it.
+
 #### A site under a prefix
 
 A site that is served under a path of another host, such as `chassis-ui.com/css`, cannot use `/static/` there: that path belongs to the host's own site. It loads its static files under a path of its own instead:
@@ -292,6 +317,22 @@ The package installs a `chassis-docs` command with the build steps that every Ch
 
 `vendor` and `sync-submodules` work from any folder of the repository. They need Git, Git LFS and pnpm. `sync-submodules --branch <name>`, or the `SUBMODULE_BRANCH` variable, follows another branch.
 
+Both take `--subset <range>`, which writes the fonts of the build with the characters of the range only, so that a page downloads smaller font files. A range is a name that `chassis-assets` knows, such as `latin` or `latin-ext`, or a range written as `U+0370-03FF`, and the option is repeatable:
+
+```json
+{
+  "scripts": {
+    "vendor": "chassis-docs vendor --subset latin --subset latin-ext --split"
+  }
+}
+```
+
+A character outside the ranges is drawn with the next font of the font stack. With the option, the commands install the package of the build in the submodule, `pnpm install --filter ./packages/assets --prod`, in place of `pnpm install --ignore-workspace`: it holds the package that subsets a font.
+
+`--subset` also fixes the axes of a variable font that `chassis-assets` names for the brand: the optical size of Inter at 14, so that text has the width it had with Google Fonts. A site that builds without `--subset` sets `font-optical-sizing: none` in its styles for the same look.
+
+`--split`, with `--subset`, writes each font in a file per range as well, such as `text-latin.woff2` and `text-latin-ext.woff2`, and the stylesheets name them with a `unicode-range`: a page loads the file of a range only when it has a character of it. `--no-split` writes one file per font. Without either, the setting of `chassis-assets` decides, which is one file.
+
 Each command exits with 1 when it fails, so a script or CI job stops there.
 
 ### Validating HTML
@@ -376,6 +417,7 @@ The integration provides five modules: `virtual:chassis-docs/config`, `virtual:c
 
 | `@chassis-ui/docs` | Requires Astro             | Requires `@chassis-ui/css` | Requires Node | Built with                           |
 | ------------------ | -------------------------- | -------------------------- | ------------- | ------------------------------------ |
+| 0.8.0              | `^7.0.0`                   | `>=0.6.0`                  | `>=22.12.0`   | Astro 7.3.5, css 0.7.1, tokens 0.7.0 |
 | 0.7.0              | `^7.0.0`                   | `>=0.6.0`                  | `>=22.12.0`   | Astro 7.3.5, css 0.6.0, tokens 0.6.0 |
 | 0.6.3              | `^7.0.0`                   | `^0.5.0-0`                 | `>=22.12.0`   | Astro 7.3.5, css 0.5.2, tokens 0.6.0 |
 | 0.6.2              | `^7.0.0`                   | `^0.5.0-0`                 | `>=22.12.0`   | Astro 7.3.5, css 0.5.2, tokens 0.6.0 |

package/UPGRADING.md

@@ -1,5 +1,81 @@
 # Upgrading @chassis-ui/docs
 
+## From 0.7 to 0.8
+
+0.8.0 loads the fonts from the site's own static files, no longer from Google Fonts. The
+head of every page links `fonts/text.css`, `fonts/display.css` and `fonts/code.css` under
+the static path, `/static/` by default. The three stylesheets and the font files they load
+are in the docs build of `chassis-assets`, which a site copies into `static/` already.
+
+### 1. Update the dependency
+
+```sh
+pnpm add -D @chassis-ui/docs@^0.8.0
+```
+
+### 2. Move the `vendor/assets` submodule
+
+```sh
+pnpm sync-submodules
+```
+
+The pages need `vendor/assets` at `acb5d2e` of `app/docs` or later: there the stylesheets
+declare Inter, Archivo Narrow and Fira Code as variable fonts, with every weight the styles
+use. With a commit before `77912ed` they declare four weights of each family. Commit the
+new pointer.
+
+A site that does not copy the docs build provides the three stylesheets itself, at the
+same paths.
+
+### 3. Subset the fonts
+
+Add `--subset` and `--split` to the `vendor` and `sync-submodules` scripts:
+
+```json
+{
+  "scripts": {
+    "vendor": "chassis-docs vendor --subset latin --subset latin-ext --split",
+    "sync-submodules": "chassis-docs sync-submodules --subset latin --subset latin-ext --split"
+  }
+}
+```
+
+The step is optional, and it does two things:
+
+- The fonts hold the characters of the ranges only, each range in a file of its own that a
+  page loads when it has a character of it. A page in English loads `text-latin.woff2`,
+  69 KB, where the whole `text.woff2` is 349 KB. A character outside the ranges is drawn
+  with the next font of the font stack, so name the range of every script your pages use:
+  a name that `chassis-assets` knows, or a range written as `U+0370-03FF`. See
+  [Commands](README.md#commands) in the README.
+- The optical size axis of Inter is fixed at 14. See "What changes on the pages" below.
+
+With `--subset` the commands install the package of the build in the submodule, which
+holds the package that subsets a font.
+
+### 4. Remove Google Fonts from your policy and your privacy page
+
+No page requests `fonts.googleapis.com` or `fonts.gstatic.com` any more. Remove the two
+hosts from a content security policy of your own, and a sentence about Google Fonts from a
+privacy page. The sites under chassis-ui.com have the policy of the website, which no
+longer allows the two hosts.
+
+### What changes on the pages
+
+- **Inter follows its optical size axis.** The Inter of the assets has the axis, which the
+  font of Google Fonts had not, and a browser follows it: text above 14 pixels is narrower,
+  7% at 57 pixels. Step 3 fixes the axis at 14, so text has the width it had. A site that
+  builds without `--subset` sets `font-optical-sizing: none` in its styles for the same
+  look.
+- **Inter has an italic file.** Italic text was drawn by slanting the upright font.
+- **The head has no `preconnect` links** to the two hosts of Google Fonts.
+
+### Check the result
+
+Build the site before and after the upgrade and compare the pages in a browser. With
+step 3 the text keeps its width, so nothing moves. Check in the network panel that no
+request goes to `fonts.googleapis.com` or `fonts.gstatic.com`.
+
 ## From 0.6 to 0.7
 
 0.7.0 needs `@chassis-ui/css` 0.6.0 or later. The layouts use the CSS grid of that version,

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@chassis-ui/docs",
   "description": "Shared Astro components and layouts for Chassis documentation sites.",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "type": "module",
   "repository": {
     "type": "git",
@@ -107,7 +107,7 @@
   },
   "devDependencies": {
     "@astrojs/markdown-remark": "^7.3.1",
-    "@chassis-ui/css": "^0.6.0",
+    "@chassis-ui/css": "^0.7.1",
     "@pagefind/component-ui": "^1.5.2",
     "@shikijs/transformers": "^4.5.0",
     "astro": "^7.3.5",

package/src/cli/assets.js

@@ -11,6 +11,9 @@ export const ASSETS_OUTPUT = 'dist/web/docs/chassis'
 /** The branch of chassis-assets that the docs sites follow. */
 export const DEFAULT_BRANCH = 'app/docs'
 
+/** The package of the build inside the submodule, which names the packages its options load. */
+export const ASSETS_PACKAGE = './packages/assets'
+
 /**
  * The root of the repository that contains the working directory, so that the commands
  * work from a site's folder too.
@@ -22,24 +25,34 @@ function repositoryRoot(run) {
 
 /**
  * Checks out `vendor/assets` at the commit that the repository pins, and builds it.
- * @param {{ root?: string, run?: typeof defaultRun }} [options]
+ * @param {{ root?: string, subset?: string[], split?: boolean, run?: typeof defaultRun }} [options]
  */
-export function buildAssets({ run = defaultRun, root = repositoryRoot(run) } = {}) {
+export function buildAssets({
+  run = defaultRun,
+  root = repositoryRoot(run),
+  subset = [],
+  split
+} = {}) {
+  const fonts = fontOptions(subset, split)
+
   log(`Building ${ASSETS_PATH} at the pinned commit`)
   run('git', ['submodule', 'update', '--init', ASSETS_PATH], { cwd: root })
-  buildCheckout(root, run)
+  buildCheckout(root, run, fonts)
 }
 
 /**
  * Moves `vendor/assets` to the latest commit of `branch`, and builds it. The repository
  * then has a changed submodule pointer to commit.
- * @param {{ root?: string, branch?: string, run?: typeof defaultRun }} [options]
+ * @param {{ root?: string, branch?: string, subset?: string[], split?: boolean, run?: typeof defaultRun }} [options]
  */
 export function syncAssets({
   run = defaultRun,
   root = repositoryRoot(run),
-  branch = DEFAULT_BRANCH
+  branch = DEFAULT_BRANCH,
+  subset = [],
+  split
 } = {}) {
+  const fonts = fontOptions(subset, split)
   const dir = path.join(root, ASSETS_PATH)
   const git = (args, quiet = true) => run('git', args, { cwd: dir, quiet })
 
@@ -68,7 +81,7 @@ export function syncAssets({
   }
 
   git(['pull', '--ff-only', 'origin', branch])
-  buildCheckout(root, run)
+  buildCheckout(root, run, fonts)
 
   const commit = git(['rev-parse', '--short', 'HEAD']).trim()
   const moved = run('git', ['status', '--porcelain', '--', ASSETS_PATH], {
@@ -92,14 +105,49 @@ function hasLocalBranch(git, branch) {
   }
 }
 
-function buildCheckout(root, run) {
+/**
+ * The options of the build for the fonts: the ranges of `--subset`, then `--split` or
+ * `--no-split` when the site decides it, and nothing when the fonts stay whole. Without
+ * either of the two, the build takes `split` of `chassis.subset` of chassis-assets.
+ * @param {string[]} subset
+ * @param {boolean} [split]
+ * @returns {string[]}
+ */
+function fontOptions(subset, split) {
+  if (subset.length === 0) {
+    if (split !== undefined) {
+      throw new CommandError('--split and --no-split need --subset: a font is split by its ranges.')
+    }
+
+    return []
+  }
+
+  const decided = split === undefined ? [] : [split ? '--split' : '--no-split']
+
+  return ['--subset', ...subset, ...decided]
+}
+
+function buildCheckout(root, run, fonts = []) {
   const dir = path.join(root, ASSETS_PATH)
 
   // The images are stored with Git LFS. Without it they are pointer files.
   run('git', ['lfs', 'install', '--local'], { cwd: dir, quiet: true })
   run('git', ['lfs', 'pull'], { cwd: dir })
-  run('pnpm', ['install', '--ignore-workspace'], { cwd: dir })
-  run('pnpm', ['assets:site'], { cwd: dir })
+
+  if (fonts.length > 0) {
+    // The subsetter is a package that the build loads, so the package of the build is
+    // installed, without the tools of its tests. Where an install without the workspace
+    // ran before, pnpm removes its modules first, and would ask.
+    run(
+      'pnpm',
+      ['install', '--filter', ASSETS_PACKAGE, '--prod', '--config.confirmModulesPurge=false'],
+      { cwd: dir }
+    )
+    run('pnpm', ['assets:site', ...fonts], { cwd: dir })
+  } else {
+    run('pnpm', ['install', '--ignore-workspace'], { cwd: dir })
+    run('pnpm', ['assets:site'], { cwd: dir })
+  }
 
   const output = path.join(dir, ASSETS_OUTPUT)
 

package/src/cli/main.js

@@ -14,6 +14,14 @@ Commands:
   vendor                 Build vendor/assets at the commit that the repository pins
   sync-submodules        Move vendor/assets to the latest commit of a branch, and build it
       --branch <name>    The branch of chassis-assets (default: $SUBMODULE_BRANCH or ${DEFAULT_BRANCH})
+
+  Both builds:
+      --subset <range>   Write the web fonts with the characters of a range only, such as
+                         latin or U+0370-03FF. Repeatable
+      --split            With --subset, write a font in a file per range, which a page
+                         loads when it has a character of the range
+      --no-split         With --subset, write a font in one file (default: the setting
+                         of chassis-assets)
   html-validate [paths]  Validate the HTML files in paths (default: _site) with html-validate
       --config <file>    A JSON config of html-validate, added to the defaults
   vnu [paths]            Validate paths (default: _site) with the Nu Html Checker. Needs Java
@@ -27,6 +35,21 @@ Commands:
 
 html-validate and vnu need the html-validate and vnu-jar packages in the site's devDependencies.`
 
+const fontOptions = {
+  subset: { type: 'string', multiple: true },
+  split: { type: 'boolean' },
+  'no-split': { type: 'boolean' }
+}
+
+// `--split` is true and `--no-split` is false. Neither leaves the decision to chassis-assets.
+function splitOf(values) {
+  if (values.split && values['no-split']) {
+    throw new CommandError('Give --split or --no-split, not both.')
+  }
+
+  return values.split ? true : values['no-split'] ? false : undefined
+}
+
 const ignoreOptions = {
   ignore: { type: 'string', multiple: true },
   'no-default-ignore': { type: 'boolean' }
@@ -39,16 +62,20 @@ function ignoresOf(values, paths) {
 
 const commands = {
   vendor: {
-    options: {},
-    run: () => {
-      buildAssets()
+    options: { ...fontOptions },
+    run: ({ values }) => {
+      buildAssets({ subset: values.subset, split: splitOf(values) })
       return 0
     }
   },
   'sync-submodules': {
-    options: { branch: { type: 'string' } },
+    options: { branch: { type: 'string' }, ...fontOptions },
     run: ({ values }) => {
-      syncAssets({ branch: values.branch ?? process.env.SUBMODULE_BRANCH ?? DEFAULT_BRANCH })
+      syncAssets({
+        branch: values.branch ?? process.env.SUBMODULE_BRANCH ?? DEFAULT_BRANCH,
+        subset: values.subset,
+        split: splitOf(values)
+      })
       return 0
     }
   },

package/src/components/DocsSidebar.astro

@@ -16,120 +16,118 @@ const docsPages = await getDocsPages()
 
 <nav class="cxd-links w-100" id="cxd-docs-nav" aria-label="Docs navigation">
   <menu class="p-0 m-0">
-    {
-      sidebar.map((group) => {
-        const groupSlug = getSlug(group.title)
+    {sidebar.map((group) => {
+      const groupSlug = getSlug(group.title)
 
-        if (group.pages) {
-          return (
-            <li
-              class:list={[
-                'cxd-links-group',
-                groupSlug === Astro.params.slug?.split('/')[0] ? 'active' : undefined
-              ]}
-            >
-              <strong class="cxd-links-heading">
-                {group.icon && (
-                  <Icon
-                    name={group.icon}
-                    style={group.iconColor && `color: var(--cx-${group.iconColor});`}
-                  />
-                )}
-                {group.title}
-              </strong>
-              <ul class="nav flex-column cxd-links-nav">
-                {group.pages?.map((item: SidebarItem) => {
-                  // Handle sub-groups
-                  if (item.group && item.pages) {
-                    return (
-                      <>
-                        <li class="cxd-links-subgroup">{item.group}</li>
-                        {item.pages.map((page: SidebarSubItem) => {
-                          const docSlug = getSlug(page.title)
-                          const unversionedPageSlug = `${groupSlug}/${docSlug}`
-
-                          const url = getDocsPath(unversionedPageSlug)
-                          const active = Astro.params.slug === unversionedPageSlug
+      if (group.pages) {
+        return (
+          <li
+            class:list={[
+              'cxd-links-group',
+              groupSlug === Astro.params.slug?.split('/')[0] ? 'active' : undefined
+            ]}
+          >
+            <strong class="cxd-links-heading">
+              {group.icon && (
+                <Icon
+                  name={group.icon}
+                  style={group.iconColor && `color: var(--cx-${group.iconColor});`}
+                />
+              )}
+              {group.title}
+            </strong>
+            <ul class="nav flex-column cxd-links-nav">
+              {group.pages?.map((item: SidebarItem) => {
+                // Handle sub-groups
+                if (item.group && item.pages) {
+                  return (
+                    <>
+                      <li class="cxd-links-subgroup">{item.group}</li>
+                      {item.pages.map((page: SidebarSubItem) => {
+                        const docSlug = getSlug(page.title)
+                        const unversionedPageSlug = `${groupSlug}/${docSlug}`
 
-                          const generatedPage = docsPages.find(
-                            (page) => page.id === unversionedPageSlug
-                          )
+                        const url = getDocsPath(unversionedPageSlug)
+                        const active = Astro.params.slug === unversionedPageSlug
 
-                          // This test should not be necessary, see comments for `getSlug()` in `src/libs/utils.ts`.
-                          if (!generatedPage) {
-                            throw new Error(
-                              `The page '${page.title}' referenced in 'data/sidebar.yml' does not exist at '${url}'.`
-                            )
-                          }
+                        const generatedPage = docsPages.find(
+                          (page) => page.id === unversionedPageSlug
+                        )
 
-                          return (
-                            <li>
-                              <a
-                                href={url}
-                                class:list={['cxd-links-link', { active }]}
-                                aria-current={active ? 'page' : undefined}
-                              >
-                                {page.title}
-                              </a>
-                            </li>
+                        // This test should not be necessary, see comments for `getSlug()` in `src/libs/utils.ts`.
+                        if (!generatedPage) {
+                          throw new Error(
+                            `The page '${page.title}' referenced in 'data/sidebar.yml' does not exist at '${url}'.`
                           )
-                        })}
-                      </>
-                    )
-                  }
+                        }
 
-                  // Handle regular pages
-                  if (!item.title) {
-                    return null
-                  }
+                        return (
+                          <li>
+                            <a
+                              href={url}
+                              class:list={['cxd-links-link', { active }]}
+                              aria-current={active ? 'page' : undefined}
+                            >
+                              {page.title}
+                            </a>
+                          </li>
+                        )
+                      })}
+                    </>
+                  )
+                }
 
-                  const docSlug = getSlug(item.title)
-                  const unversionedPageSlug = `${groupSlug}/${docSlug}`
+                // Handle regular pages
+                if (!item.title) {
+                  return null
+                }
 
-                  const url = getDocsPath(unversionedPageSlug)
-                  const active = Astro.params.slug === unversionedPageSlug
+                const docSlug = getSlug(item.title)
+                const unversionedPageSlug = `${groupSlug}/${docSlug}`
 
-                  const generatedPage = docsPages.find((page) => page.id === unversionedPageSlug)
+                const url = getDocsPath(unversionedPageSlug)
+                const active = Astro.params.slug === unversionedPageSlug
 
-                  // This test should not be necessary, see comments for `getSlug()` in `src/libs/utils.ts`.
-                  if (!generatedPage) {
-                    throw new Error(
-                      `The page '${item.title}' referenced in 'data/sidebar.yml' does not exist at '${url}'.`
-                    )
-                  }
+                const generatedPage = docsPages.find((page) => page.id === unversionedPageSlug)
 
-                  return (
-                    <li>
-                      <a
-                        href={url}
-                        class:list={['cxd-links-link', { active }]}
-                        aria-current={active ? 'page' : undefined}
-                      >
-                        {item.title}
-                      </a>
-                    </li>
+                // This test should not be necessary, see comments for `getSlug()` in `src/libs/utils.ts`.
+                if (!generatedPage) {
+                  throw new Error(
+                    `The page '${item.title}' referenced in 'data/sidebar.yml' does not exist at '${url}'.`
                   )
-                })}
-              </ul>
-            </li>
-          )
-        } else {
-          const active = Astro.params.slug === groupSlug
+                }
 
-          return (
-            <>
-              <li class="cxd-links-span-all mt-2xs mb-md mx-lg border-top" />
-              <a
-                href={getDocsPath(`${groupSlug}/`)}
-                class:list={['cxd-links-link cxd-links-span-all', { active }]}
-                aria-current={active ? 'page' : undefined}
-              >
-                {group.title}
-              </a>
-            </>
-          )
-        }
-      })
-    }
+                return (
+                  <li>
+                    <a
+                      href={url}
+                      class:list={['cxd-links-link', { active }]}
+                      aria-current={active ? 'page' : undefined}
+                    >
+                      {item.title}
+                    </a>
+                  </li>
+                )
+              })}
+            </ul>
+          </li>
+        )
+      } else {
+        const active = Astro.params.slug === groupSlug
+
+        return (
+          <>
+            <li class="cxd-links-span-all mt-2xs mb-md mx-lg border-top" />
+            <a
+              href={getDocsPath(`${groupSlug}/`)}
+              class:list={['cxd-links-link cxd-links-span-all', { active }]}
+              aria-current={active ? 'page' : undefined}
+            >
+              {group.title}
+            </a>
+          </>
+        )
+      }
+    })}
   </menu>
 </nav>

package/src/components/FeatureCard.astro

@@ -44,13 +44,11 @@ const headerClasses = [
 
 <div class={cardClasses}>
   <div class={headerClasses}>
-    {
-      icon && (
-        <div class="feature-thumb">
-          <Icon name={icon} class="feature-icon icon-3xl md:icon-4xl" sprite="" />
-        </div>
-      )
-    }
+    {icon && (
+      <div class="feature-thumb">
+        <Icon name={icon} class="feature-icon icon-3xl md:icon-4xl" sprite="" />
+      </div>
+    )}
     <div>
       <h3 class="feature-title font-lg md:font-xl mb-3xs md:mb-2xs">
         <slot name="title" />

package/src/components/TableOfContents.astro

@@ -27,16 +27,14 @@ let entryLevel = level ? level + 1 : 1
 ---
 
 <ul>
-  {
-    toc.map(({ children, slug, text }) => {
-      return (
-        <li>
-          <a href={`#${slug}`} class={`level-${entryLevel}`}>
-            {text}
-          </a>
-          {children.length > 0 && <Astro.self entries={children} level={entryLevel} />}
-        </li>
-      )
-    })
-  }
+  {toc.map(({ children, slug, text }) => {
+    return (
+      <li>
+        <a href={`#${slug}`} class={`level-${entryLevel}`}>
+          {text}
+        </a>
+        {children.length > 0 && <Astro.self entries={children} level={entryLevel} />}
+      </li>
+    )
+  })}
 </ul>