@chassis-ui/docs 0.6.3 → 0.8.0

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # @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
+
+- **Breaking.** The package needs `@chassis-ui/css` 0.6.0 or later: the peer range is `>=0.6.0`, it was `^0.5.0-0`. The layouts use the CSS grid of css 0.6, `.grid` with `col-span-*`, in place of the flexbox grid, `.row` with `.col-*`, which css 0.6 deprecates and css 0.7 removes. The header of `SingleLayout`, the sections list of `DocsLayout`, the footer and the lists of the header are grids. `NavLink` no longer sets a width: the lists of the header are two columns below `lg` by themselves. The loading rows of the search use the fraction widths, `w-4/12`. `.cxd-gutter` sets `--cx-container-padding` in place of `--cx-gutter-x`, with the same page margin of 1rem. The pages look as before, except that the footer columns are separated by the gutter of the breakpoint and move by a few pixels. See [UPGRADING.md](https://github.com/chassis-ui/website/blob/main/packages/docs/UPGRADING.md#from-06-to-07) for the classes to replace in a site's own pages.
+
 ## 0.6.3
 
 ### Patch 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
 
@@ -23,7 +23,7 @@ pnpm add @chassis-ui/docs
 ```json
 {
   "@astrojs/markdown-remark": "^7.0.0",
-  "@chassis-ui/css": "^0.5.0-0",
+  "@chassis-ui/css": ">=0.6.0",
   "@pagefind/component-ui": "^1.0.0",
   "@shikijs/transformers": "^4.3.1",
   "astro": "^7.0.0",
@@ -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,8 @@ 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 |
 | 0.6.1              | `^7.0.0`                   | `^0.5.0-0`                 | `>=22.12.0`   | Astro 7.3.5, css 0.5.2, tokens 0.6.0 |

package/UPGRADING.md

@@ -1,5 +1,145 @@
 # 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,
+`.grid` with `col-span-*`, in place of the flexbox grid, `.row` with `.col-*`. css 0.6
+deprecates the flexbox grid and css 0.7 removes it.
+
+### 1. Update the dependencies
+
+```sh
+pnpm add -D @chassis-ui/docs@^0.7.0 @chassis-ui/css@^0.6.0
+```
+
+css 0.6.0 has changes of its own. Read its
+[changelog](https://github.com/chassis-ui/css/blob/main/packages/css/CHANGELOG.md) first:
+among them, the default gap of `.grid` is now the gutter token of the breakpoint.
+
+### 2. Move your own pages off the flexbox grid
+
+css 0.6 still has the flexbox grid, so the site builds and looks as before without this
+step. css 0.7 removes it. Replace the classes in your own components, pages and content:
+
+| Flexbox grid                             | CSS grid                                           |
+| ---------------------------------------- | -------------------------------------------------- |
+| `row`                                    | `grid`                                             |
+| `col-6`, `md:col-6`                      | `col-span-6`, `col-span-full md:col-span-6`        |
+| `col-12`                                 | `col-span-full`                                    |
+| `row row-cols-1 md:row-cols-3` and `col` | `grid grid-cols-1 md:grid-cols-3`, no class inside |
+| `offset-1`                               | `col-start-2`                                      |
+| `col lg:col-10 mx-auto`                  | `col-span-full lg:col-span-10 lg:col-start-2`      |
+| `g-md`, `gx-md`, `gy-md`                 | `gap-md`, `column-gap-md`, `row-gap-md`            |
+| `col-auto`                               | `d-flex` with `gap-*` on the parent                |
+| `col-6` outside a `row`                  | `w-6/12`                                           |
+| `col` outside a `row`                    | `flex-fill`                                        |
+
+- An item without a span is one column wide. A column that was full width below its
+  breakpoint, such as `md:col-6`, needs `col-span-full` too.
+- A `row` without a gutter class had a gutter of 1.5rem between columns and none between
+  rows. A `grid` has the gutter of the breakpoint in both directions, from 0.5rem to 3rem.
+  Add `row-gap-0` where the items have margins of their own.
+- A grid beside the sidebar, or in a card, is narrower than the viewport that the gutter
+  follows. Give it a `gap-*` class, and `grid-cols-{n}` in place of twelve columns.
+- An auto margin shrinks a grid item to its content. Center an item with `col-start-*`.
+
+The [grid page](https://chassis-ui.com/css/docs/layout/grid/) of Chassis CSS has the full
+table.
+
+### What changes in the package
+
+- **`NavLink` sets no width.** Its item was `nav-item col-6 lg:col-auto`, half of the list
+  below `lg`. It is `nav-item` now, and the lists of the header are a grid of two columns
+  below `lg`. A list of your own that relied on the two columns takes
+  `d-grid grid-cols-2 lg:d-flex`.
+- **`.cxd-gutter` sets `--cx-container-padding`.** It set `--cx-gutter-x`, which the
+  container stops reading in css 0.7. The page margin of the docs layout is 1rem, as
+  before. A rule of your own that set `--cx-gutter-x` on that element sets
+  `--cx-container-padding` to half of it.
+- **The footer and the header of `SingleLayout` take the gutter of the breakpoint.** The
+  footer columns move by a few pixels, 20 at most on the widest screens.
+
+### Check the result
+
+Build the site before and after the upgrade and compare the pages in a browser, at a phone
+width and a desktop width. Apart from the footer columns, nothing of the package moves.
+
 ## 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/*`

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@chassis-ui/docs",
   "description": "Shared Astro components and layouts for Chassis documentation sites.",
-  "version": "0.6.3",
+  "version": "0.8.0",
   "type": "module",
   "repository": {
     "type": "git",
@@ -70,7 +70,7 @@
   },
   "peerDependencies": {
     "@astrojs/markdown-remark": "^7.0.0",
-    "@chassis-ui/css": "^0.5.0-0",
+    "@chassis-ui/css": ">=0.6.0",
     "@pagefind/component-ui": "^1.0.0",
     "@shikijs/transformers": "^4.3.1",
     "astro": "^7.0.0",
@@ -106,8 +106,16 @@
     "unist-util-visit": "^5.1.0"
   },
   "devDependencies": {
+    "@astrojs/markdown-remark": "^7.3.1",
+    "@chassis-ui/css": "^0.7.1",
+    "@pagefind/component-ui": "^1.5.2",
+    "@shikijs/transformers": "^4.5.0",
     "astro": "^7.3.5",
+    "html-validate": "^11.16.1",
+    "rehype-autolink-headings": "^7.1.0",
     "remark-mdx": "^3.1.1",
-    "vfile": "^6.0.3"
+    "sass": "^1.105.1",
+    "vfile": "^6.0.3",
+    "vnu-jar": "^26.10.2"
   }
 }

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
     }
   },