The Starlight Web Site

The Starlight Web Site output turns a driver’s help content into a complete documentation website built with Astro and Starlight — with a navigation sidebar, built-in full-text search, dark/light mode, responsive layout, breadcrumbs, previous/next links, and syntax highlighting, all out of the box.

It is one of the output formats the Markdown help template system can produce, and it draws on the same conceptual content, table of contents, and Mustache values as every other format. Content is authored once, and the web site is one more output of it.

There are two ways to publish it, covered below. It can be committed to a GitHub repository and built and hosted by GitHub Pages, which needs nothing installed at all; or it can be built locally and the finished site uploaded to any static host. The same generated folder serves both.

Tip

This documentation site is itself built with Astro Starlight, so the site Nimbus generates looks and behaves like the pages presented here.

Enabling it

Select Starlight Web Site in any of the places help output formats are chosen — they all set the same project setting:

• The General page of the help project’s properties.
• The New Help Project wizard, when the project is created.
• Tools → Options → Help, for the default choices applied to new projects.

The selection is stored as the BuildStarlight project property, so command-line builds honor it too. It is available for all three driver flavors — IVI.NET, IVI-COM, and IVI-C.

Like the other modern formats, the Starlight site requires a Markdown help template. A project still using the legacy HTML template system produces only CHM and Microsoft Help Viewer; switching it to a Markdown template unlocks the Starlight output.

Prerequisite: Node.js

The Starlight site is the only output format with an external prerequisite, and only for two of the three things that can be done with it:

	Node.js
Generating the site as part of a driver build	Not needed — Nimbus writes it
Publishing it through GitHub Pages	Not needed — GitHub runs the build
Building or previewing it locally	Required
Serving the finished site	Not needed

Where it is required, the version is Node.js 22.12 or later (which includes npm 9.6.5 or later). Report the installed version with node --version.

Caution

On an older Node.js, npm install or npm run build fails with an error from Astro rather than a clear message about the Node.js version. If either command fails unexpectedly, check the Node.js version first.

The built output is plain static HTML, CSS and JavaScript that any web server or file share serves with nothing installed. All the other Nimbus output formats are produced entirely by Nimbus with no additional tooling.

What gets generated

When the help project builds with Starlight enabled, Nimbus writes a complete Astro + Starlight project to Help/Starlight/ in the build output:

Help/Starlight/
├── package.json            Node dependencies (astro, @astrojs/starlight)
├── astro.config.mjs        Astro/Starlight config
├── sidebar.config.mjs      Navigation sidebar, generated from the help TOC
├── chrome.config.mjs       Header credit and footer copyright, from the template's manifest
├── wrangler.jsonc          Publishes the site to Cloudflare, named after the driver
├── README.md               Build/preview/deploy notes for this site
├── .github/
│   └── workflows/
│       └── pages.yml       Publishes the site with GitHub Actions
├── public/
│   ├── favicon.svg
│   └── assets/             Images, copied from the template's assets/ folder
└── src/
    ├── content/docs/       The generated help — one Markdown file per topic, plus index.md (home)
    ├── components/         Component overrides that place the credit and copyright lines
    ├── lib/                Helpers those components use
    └── styles/
        └── company-theme.css   Branding (accent color, fonts, sidebar width, …)

This is one project, not several. The same folder can be built by hand and uploaded anywhere, committed to a repository and built by GitHub, or deployed to Cloudflare. pages.yml and wrangler.jsonc are the only host-specific files in it, and each does nothing until that host is the one being used.

The home page is the first topic in the table of contents. API signatures keep their clickable type links, and wide data tables scroll horizontally rather than squeezing.

Links between pages are written relative to the page holding them, so the site works wherever it is served from — a domain root, a GitHub Pages project path, or a folder on a company web server — with nothing to configure and nothing that can be configured wrongly.

Checking the site before publishing it

There are two local commands, and they answer different questions. Run both, in this order, from the generated Help/Starlight/ folder.

npm install        # once — downloads Astro/Starlight (requires Node.js)

While authoring

npm run dev        # usually http://localhost:4321

A development server that reloads as content and branding are edited. This is the one to leave running while adjusting a stylesheet or reading through topics.

It does not build the site. Anything that only goes wrong during a real build — a page that fails to render, a link that resolves differently once written to disk — will not appear here.

Before publishing

npm run build      # writes the finished site to dist/
npm run preview    # serves dist/ — what actually gets published

npm run preview serves the built output rather than a development version of it, so it is the first point at which the published site can be seen as it will be. Defects that reach a reader have been found here and not in npm run dev.

Check it at the path it will be served from

A site previewed at http://localhost:4321/ is being served from a root. A GitHub Pages project site is served under the repository’s name, and a site uploaded to a company web server often sits in a folder. Build once with that path set to confirm the site behaves the same way:

SITE_BASE=/my-driver-help npm run build
npm run preview

Nimbus writes the links between pages relative to the page holding them, so this should need no adjustment — but it costs one build to know, rather than finding out from a published site.

Publishing it

The built site is plain static HTML, CSS and JavaScript. Nothing needs to be installed to serve it.

Let GitHub build and host it

Nimbus generates .github/workflows/pages.yml. Nothing in it needs editing, and Node.js is not needed on any machine for this route — GitHub does the build.

1. Commit the contents of Help/Starlight/ to a GitHub repository, including the .github folder.
2. In the repository, open Settings → Pages.
3. Under Build and deployment, set Source to GitHub Actions.

The site is published a few minutes later and rebuilt on every push to the default branch. The Actions tab shows each run and its log, and the address appears on the run’s deploy job and under Settings → Pages.

This is the only way an Astro site reaches GitHub Pages: GitHub cannot build one from a branch on its own.

Note

GitHub runs workflows only from .github/workflows at the top of a repository. When the site is the whole repository — the usual case — the generated file is already in the right place. When the site sits inside a larger repository, move pages.yml to the repository’s own .github/workflows folder and set SITE_DIR at the top of it to the folder holding astro.config.mjs. Moving the file also takes it out of the generated output, so a later driver build will not overwrite it.

By default a GitHub Pages site is public, even when built from a private repository. Restricting the published site to people with access to the repository requires GitHub Enterprise Cloud; the setting is Settings → Pages → GitHub Pages visibility.

Publish it to Cloudflare

Nimbus generates wrangler.jsonc alongside the site, already named after the driver. Cloudflare serves the built files as static assets on a Worker.

npm run build
npx wrangler login     # once, to authorize the Cloudflare account
npx wrangler deploy

The deploy prints the address, https://<name>.<subdomain>.workers.dev. To serve it from a domain instead, add a custom domain to the Worker in the Cloudflare dashboard.

The Worker is named after the driver — acme4301-help for a driver called Acme4301 — because a Worker name is unique within a Cloudflare account, and two drivers sharing one would publish over each other. To change it, edit wrangler.jsonc in the help template.

The dashboard’s drag-and-drop will not take a driver help site

Cloudflare’s dashboard offers a drag-and-drop upload, and it is the obvious thing to reach for. It belongs to Cloudflare Pages rather than Workers, and it accepts at most 1,000 files — fewer than a driver reference of any size produces, since each topic is a page of its own. The upload fails after transferring everything, individual files cannot then be replaced, and the whole project has to be sent again.

Deploying static assets to a Worker is done with Wrangler or the Cloudflare API; there is no dashboard equivalent. The commands above are not the developer-flavored option, they are the route.

Note

A *.workers.dev address is public. Restricting who can reach it means putting the Worker behind Cloudflare Access, which is a Cloudflare setting rather than anything in the generated site.

Each deploy uploads the whole site rather than only what changed, and it uploads from the machine running the command. Publishing through GitHub Pages instead moves that work to GitHub.

Build it and upload it anywhere

npm run build

dist/ is the finished site. Upload it to any static host — Netlify, Azure Static Web Apps, Amazon S3, IIS, or a network share. This route needs Node.js on whichever machine runs the build, and nothing on the machine that serves the result.

Branding

The site’s branding lives in company-theme.css in the driver’s help template, under the starlight/ scaffold (starlight/src/styles/company-theme.css). It is plain CSS built on Starlight’s own custom properties — no build tooling required. The file is heavily commented; the common edits are:

• Accent color — --sl-color-accent-low / --sl-color-accent / --sl-color-accent-high (links, the active sidebar item, focus rings), with separate light-mode overrides.
• Fonts — --sl-font and --sl-font-mono.
• Sidebar width — --sl-sidebar-width, sized so long API member names fit on one line.

The site title (e.g. “Acme4301 IVI.NET Driver Reference”) is injected automatically from the driver — no edit needed. There is no logo by default; Starlight shows the site title as text.

The credit and copyright lines come from the header and footer defined in the template’s manifest.yaml, the same ones every other output format shows. Starlight has no place of its own for either, so the scaffold supplies two small component overrides — SocialIcons.astro puts the credit at the right of the header, Footer.astro puts the copyright below the page — each rendering Starlight’s own component first and adding to it.

For deeper changes, edit astro.config.mjs in the template’s starlight/ scaffold — for example to set a canonical site: URL for sitemaps and SEO, or to add an Astro integration.

Edit the template, not the generated output

Branding belongs in the driver’s help template (starlight/src/styles/company-theme.css), not in the generated Help/Starlight/ site. Help/Starlight/ is build output and nothing in it survives a rebuild: Nimbus re-copies the template’s starlight/ scaffold over it every build, and regenerates the content (src/content/docs/), the sidebar (sidebar.config.mjs), the header and footer lines (chrome.config.mjs), and the site title each time.

The same applies to astro.config.mjs and to the component overrides under src/components/ — edit the copies in the template, which is what the driver project carries in source control.

How content is authored

Authoring for the Starlight site is identical to every other output format — there is nothing Starlight-specific to learn:

• Write conceptual topics as Markdown in the template’s conceptual/ folder and arrange them with the manifest’s toc: section.
• Use driver Mustache values such as {{driver.name}} and standard GitHub-Flavored Markdown.
• Add images by dropping them in the template’s assets/ folder and referencing them topic-relative — Nimbus copies them into the site automatically.

The same conceptual content and table of contents produce the CHM, the Microsoft Help Viewer package, the Markdown, the MadCap Flare output, and the Starlight site.

What Starlight provides automatically

All of the following is present without any configuration:

• A navigation sidebar generated from the help table of contents.
• Full-text search (client-side — no server required).
• A dark/light mode toggle.
• Responsive mobile and desktop layout.
• Breadcrumbs and previous/next topic links.
• Syntax highlighting for code, and an accessible design.

See also

• Output Formats
• The Template Manifest
• Building and Viewing the Help Content
• Deploy an Astro site to GitHub Pages — Astro’s own guide, which the generated workflow follows
• Component overrides — the mechanism the credit and copyright lines use, and the route to deeper customization