@zarr-developers/vitepress-theme

Shared VitePress config and theme for the Zarr websites, so they look and navigate like one site:

Site	Repo
https://zarr.dev	zarr-developers/zarr-developers.github.io
https://extensions.zarr.dev	zarr-developers/zarr-extensions

Each site keeps its own repo, content and deployment, and pins a version of this package.

What it provides

• zarrConfig() (@zarr-developers/vitepress-theme/config): the shared site config.
  • The top nav. Links within the current site stay relative. Links to another Zarr site are absolute but open in the same tab, without the external-link icon. The current site's root (e.g. Resources → Extensions on extensions.zarr.dev) stays highlighted on all of its pages.
  • Favicons and logo, loaded from zarr.dev's public/ folder.
  • Social preview tags, analytics, social links and local search.
  • "Edit this page" links to the site's repo.
  • The footer copyright line.
• The theme (@zarr-developers/vitepress-theme/theme): VitePress's default theme with the Zarr brand colors.

Usage

Install it from a release tag:

npm install github:zarr-developers/vitepress-theme#v0.1.0

.vitepress/config.mts:

import { defineConfig } from 'vitepress'
import { zarrConfig } from '@zarr-developers/vitepress-theme/config'

export default defineConfig({
  extends: zarrConfig({
    site: 'extensions',              // a key of SITES in config.mjs
    title: 'Zarr Extensions',
    description: 'The registry of Zarr v3 extensions.',
    repo: 'zarr-developers/zarr-extensions',
    // github: 'https://github.com/zarr-developers',  // GitHub icon target, defaults to the repo
  }),
  themeConfig: {
    sidebar: [/* ... */],
    footer: { message: 'Site-specific footer text.' },
  },
})

.vitepress/theme/index.ts:

export { default } from '@zarr-developers/vitepress-theme/theme'

or, to add the site's own components and layout slots:

import ZarrTheme from '@zarr-developers/vitepress-theme/theme'

export default {
  extends: ZarrTheme,
  enhanceApp({ app }) { /* register components */ },
}

How extends merges

VitePress merges the site's config into zarrConfig(). Objects are merged key by key, and arrays are concatenated. In practice:

• Adding: a site can add its own head tags or vite.plugins.
• Overriding: a site can set themeConfig.footer.message, sidebar, base and so on.
• Not in a site's config: themeConfig.nav and themeConfig.socialLinks. Setting them there would append to the shared ones instead of replacing them. Change them here.

Adding a site

1. Add it to SITES in config.mjs with its URL.
2. Point the relevant nav entries at it with site: '<key>'.
3. Release a new version.

Development

npm ci
npm run example:dev     # example site using the package, at http://localhost:5173/
npm run example:build

CI builds the example site on every PR.

config.mjs must stay plain JavaScript: VitePress loads anything its config imports from node_modules with plain Node, without compiling it. It is type-checked through JSDoc (// @ts-check).

To try a change in a site before releasing it, run npm pack, then npm install --no-save <tarball> in the site's repo.

Releasing

1. Bump version in package.json.
2. Merge.
3. Tag the merge commit vX.Y.Z and push the tag.
4. Update the sites to the new tag.

Changes to the nav or the look affect every site, so call them out in the PR.