Upgrading docs

Claude: Treat this document as authoritative.

The doc site is split into two parts: content (your markdown files) and the engine (the docs-kit generator that turns them into HTML). The engine ships inside the @bydefaultstudio/design-system npm package and runs in place from node_modules - it is never copied into the project. Upgrading the engine means upgrading the package.

What stays per-project (never touch these)

How to upgrade

The docs-kit has no version of its own - it is versioned by the design system package. To upgrade:

npm update @bydefaultstudio/design-system
npm run docs:build

Dependabot also opens a PR whenever a new package version publishes; merging it and rebuilding the docs is the same upgrade.

Customising a project's doc site

Edit docs/docs.config.js in the project. All paths are project-root-relative:

module.exports = {
  // The docs site is served at this subpath of the main site
  // ('' if the output is served as its own site root)
  basePath: '/docs/site',

  // Optional extra brand stylesheet, copied into the output and
  // linked after the framework CSS
  brandCssPath: 'assets/css/theme.css',

  // Footer copyright text
  footerText: '© 2025 Your Studio Name',

  // Description shown on the docs homepage
  indexDescription: 'Documentation for Project Name.',
};

The full configuration reference lives in the docs-kit README inside the package: node_modules/@bydefaultstudio/design-system/dist/docs-kit/README.md.

Favicons are optional: drop favicon.svg and/or favicon.ico into docs/site/assets/icons/ and rebuild - pages link them once the files exist.

Design system CSS convention

With no designSystemPath configured (this template's setup), the generator uses the packaged design-system.css and copies it into the output automatically - the docs are always styled by the same framework version the project installs. The brand stylesheet configured in brandCssPath is copied into the output and linked after it.

If the docs look unstyled, run npm install at the repo root (a fresh clone has no node_modules until then), then npm run docs:build.

Doc generator commands

Run these from the repo root:

npm run docs:build # Generate HTML from markdown
npm run docs:watch # Auto-regenerate on markdown changes

When to update the template first

Engine improvements happen in the design-system repo (the docs-kit ships with the package). Template-side, the only thing to keep current is the package version - Dependabot handles that. Improve project docs content here; improve the engine upstream.