One Starlight theme for the documentation of every Pulzar open-source project, so they read as one family: the same brand, the same chrome, the same components for the pages every project needs, and a starter that gives a new project its docs site in one command.
- Brand. The Pulzr mark, and colors and type from the Pulzr console's design tokens (Inter for text, Outfit for headings, the console's surfaces and accent), light and dark.
- Shared chrome. A project switcher across the family
(
projects.mjs), a footer with "Maintained by Pulzar", the license and the security reporting link, edit links to the page's source, a GitHub link, the favicon, and Starlight's Pagefind search. - Link checking. Every internal link is checked at build time (starlight-links-validator); a broken link fails the build.
- Components for MDX pages:
| Component | For |
|---|---|
Hero |
a landing page's title, pitch and calls to action |
Features |
feature cards in a responsive grid |
StatusBadge |
a tested, expected, in progress, planned or unsupported pill |
StatusMatrix |
a feature matrix with status badges and versions |
HardwareTable |
hardware with tested, expected and unsupported badges |
ReleaseDownload |
download a release binary and check it against SHA256SUMS |
MqttTopic |
one MQTT topic: direction, retention, purpose, example payload |
Snippet |
a code region from another file (between ANCHOR: lines), so docs show code a test runs |
A plain Markdown table needs no component for its badges: in a column headed
State or Status, a cell that is only a status word (tested,
expected, in progress, planned, unsupported, ...) is drawn as that
badge.
The component gallery shows each one with its props.
In the root of the project's repository:
npx --yes @pulzr/docs-theme init --project my-project --description "What it is, in one sentence."This writes docs/ (a Starlight site with the theme, a landing page and a
getting started page) and .github/workflows/docs.yml (build, link check,
publish to GitHub Pages). It never overwrites a file. Then:
cd docs && npm install && npm run devEnable GitHub Pages with the source "GitHub Actions", and add the project to
projects.mjs so it appears in every site's switcher.
The site pins the theme at an exact version. To get each new release as a pull request, give Dependabot the docs directory:
# .github/dependabot.yml, under updates:
- package-ecosystem: npm
directory: /docs
schedule:
interval: weeklynpm install --save-exact @pulzr/docs-theme// astro.config.mjs
import { defineConfig } from 'astro/config';
import starlight from '@astrojs/starlight';
import { pulzarPlugins } from '@pulzr/docs-theme';
export default defineConfig({
site: 'https://pulzar-net.github.io',
base: '/my-project',
build: { format: 'file' },
integrations: [
starlight({
title: 'my-project',
plugins: pulzarPlugins({ project: 'my-project' }),
}),
],
});| Option | Default | What |
|---|---|---|
project |
required | the project's id, as in projects.mjs, and its repository name |
repo |
https://github.com/pulzar-net/<project> |
the repository, for edit links, the footer and the GitHub link |
license |
MIT |
the license the footer names |
editBranch |
main |
the branch edit links open |
siteDir |
docs |
the docs site's directory in the repository, for edit links |
validateLinks |
true |
fail the build on a broken internal link |
linkExclude |
[] |
link patterns the validator skips, such as API docs added after the build |
linkValidator |
{} |
more starlight-links-validator options, such as errorOnRelativeLinks: false for a page that embeds a README |
Components:
import { Hero, StatusMatrix } from '@pulzr/docs-theme/components';- URLs are
page.html(build: { format: 'file' }), the way GitHub Pages serves files, so links keep working with or without.html. An index page in a folder (library/index.md) islibrary.html; if an older site hadlibrary/index.html, addredirects: { '/library/index': '/<base>/library.html' }. - Links in pages are absolute with the base, such as
/my-project/mqtt.html#topics, so the link checker can follow them. - Generated pages (a configuration reference from the code, one page per
board from its config file) are written into
src/content/docsbefore the build by the project's own tooling, and their freshness is checked in CI.
npm install
npm run dev # the demo site, with every component
npm run buildTo release, set version in package.json, add its section to
CHANGELOG.md, and push the tag vX.Y.Z on main. The
release workflow publishes @pulzr/docs-theme to npm with provenance and
makes the GitHub release from the changelog. Sites pin an exact version and
move to a new one with a one-line change.
MIT. See LICENSE. The Pulzr mark and the Pulzar wordmark are Pulzar LLC's trademarks; use them only for Pulzar's own projects.
Maintained by Pulzar for its open-source projects.