Starlight plugins in use

Installed · wired · blocked · MDX-only

This page is the runtime inventory of Starlight plugins for ZajLibrary — pulled from app/package.json and app/astro.config.mjs. For how to author with these tools, see Site Authoring Capabilities and the live demos in Component library.

Status key

Status	Meaning
Wired	Registered in astro.config.mjs (integrations or starlight({ plugins: [...] })) and active in dev + production builds.
MDX-only	Installed npm package; import components in .mdx — no plugins: [] entry required.
Parked	Installed but intentionally not wired because it conflicts with current site overrides or no live page needs it yet.
Blocked	Installed but not wired — fails or breaks the build on Astro 6 / Zod 4 until upstream fixes.
Core	Framework integration — not optional.

All packages (complete list)

Package	Version (pinned)	Status	What it does
@astrojs/starlight	^0.39.3	Core	Docs framework on Astro — content collections, sidebar, search (Pagefind), Starlight components, default theme hooks.
astro	^6.3.1	Core	Static site builder (Vite 7, Node 22+). Starlight runs as an Astro integration.
Local zaj-mermaid integration	local	Wired	Renders ```mermaid fenced diagrams using Astro 6’s markdown.processor API plus the mermaid runtime.
mermaid	^11.15.0	Dependency	Diagram engine used by the local zaj-mermaid integration.
starlight-theme-rapide	^0.5.2	Wired	Base Starlight theme (CSS layer). Brand palette still wins via tokens.css + theme.css loaded after.
starlight-sidebar-topics	^0.7.1	Wired	Five intent shelves (Learn · Build · Resources · Directories · System docs) — each with its own autogenerated sidebar + header section nav.
starlight-auto-sidebar	^0.4.0	Wired	Per-folder _meta.yaml tuning (label, order, badge, collapsed) for autogenerated sidebar groups. Must load before @lorenzo_lewis/starlight-utils if multiSidebar is enabled.
@lorenzo_lewis/starlight-utils	^0.3.2	Wired	Nav utilities — optional navLinks (breadcrumbs) and multiSidebar switcher. Empty config today (middleware only; compatible with sidebar-topics).
starlight-heading-badges	^0.7.0	Wired	Status badges on page headings from status: current | target | future | draft frontmatter.
starlight-auto-drafts	^0.3.0	Wired	draft: true pages hidden in production builds; visible in npm run dev.
starlight-videos	^0.4.0	Parked	Video guide / course layouts and components. Not wired today because it tries to own PageTitle and MarkdownContent, which ZajLibrary already overrides.
starlight-tags	^1.0.1	Wired	Tag index + one page per tag from tags: frontmatter. onInlineTagsNotFound: 'create' auto-creates missing tag routes (keeps links-validator green).
starlight-markdown-blocks	^0.1.0	Wired	Custom ::: callout directives — idea, decision, start, next, summary.
starlight-links-validator	^0.24.0	Wired	Build gate — fails npm run build on broken internal links. Excludes /kits/** (static public/ assets).
starlight-scroll-to-top	^1.0.1	Wired	Floating scroll-to-top control (right side).
starlight-image-zoom	^0.14.2	Wired	Click-to-zoom on content images (screenshots stay legible).
starlight-github-alerts	^0.2.0	Wired	GitHub-style markdown alerts: > [!NOTE], > [!TIP], > [!WARNING], etc.
starlight-llms-txt	^0.10.0	Wired	Generates /llms.txt — machine-readable site summary for LLM crawlers and agents.
starlight-kbd	^0.4.0	Wired	<Kbd mac="…" windows="…" /> for platform-aware shortcut docs. globalPicker: false (custom header has no ThemeSelect slot for the picker).
starlight-package-managers	^0.12.0	MDX-only	<PackageManagers> — synced npm / pnpm / yarn / bun tabs for install commands.
starlight-showcases	^0.3.2	MDX-only	Showcase cards — <ShowcaseText>, profiles, quotes, embeds.
starlight-changelogs	^0.5.0	Blocked	Would serve changelog pages from CHANGELOG.md + content collection. Not wired — v0.5.0 uses z.url() (Zod 3 API); Astro 6 ships Zod 4. Static fallback: Changelog.

By job (quick lookup)

Theme and layout

Plugin	Author / reader effect
starlight-theme-rapide	Rapide shell — typography, spacing, default Starlight chrome. Overridden by Zaj paper-workbook CSS.
Custom Header.astro	Second-row shelf nav (desktop) from sidebar-topics data — not a plugin; site override.
Custom PageTitle.astro / Footer.astro	“Copy as prompt” (title bar + page footer) + Open in ChatGPT/Claude — not a plugin; site overrides.

Navigation and IA

Plugin	Author / reader effect
starlight-sidebar-topics	Five top-level shelves; clicking a shelf switches sidebar tree. Topic exclude list handles tag pages and directory detail routes.
starlight-auto-sidebar	_meta.yaml per folder — reorder groups, rename labels, add sidebar badges.
@lorenzo_lewis/starlight-utils	Ready for breadcrumbs or multi-sidebar when IA needs them; currently no visible UI.

Authoring and MDX

Plugin	Author / reader effect
starlight-markdown-blocks	:::idea, :::decision, :::start, :::next, :::summary in .md / .mdx.
starlight-github-alerts	Standard GitHub alert syntax in markdown.
starlight-heading-badges	Visual status on the page title from frontmatter.
starlight-package-managers	Per-tool install commands without hand-maintaining four copies.
starlight-showcases	Editorial showcase cards on gallery / hub pages.
starlight-kbd	Keyboard glyphs that respect macOS vs Windows labeling.
starlight-videos	Parked until a real video lesson page needs the override chain.
Local zaj-mermaid integration	Flowcharts, sequence diagrams, graphs in plain markdown fences.

Discovery, tags, and machine readers

Plugin	Author / reader effect
starlight-tags	/tags/<tag>/ indexes every doc with that tag; link tags freely in prose.
starlight-llms-txt	/llms.txt for agents and external LLM tools.
Pagefind (Starlight built-in)	Full-text search index on production build — not a separate package.

Build quality and drafts

Plugin	Author / reader effect
starlight-links-validator	No shipping broken internal links — build fails instead.
starlight-auto-drafts	WIP pages stay out of production until draft is removed.

Reader UX (in-page)

Plugin	Author / reader effect
starlight-scroll-to-top	Long playbook pages get a one-click return to top.
starlight-image-zoom	Zoom screenshots and figures without leaving the doc.

Wiring order (do not reorder casually)

flowchart TB
  subgraph integrations["astro.config.mjs → integrations[]"]
    M[zaj-mermaid]
    S["@astrojs/starlight"]
    M --> S
  end
  subgraph plugins["starlight({ plugins: [...] }) — registration order"]
    T1[starlight-theme-rapide]
    T2[starlight-sidebar-topics]
    T3[starlight-auto-sidebar]
    T4[starlight-utils]
    T5[heading-badges · auto-drafts · tags · markdown-blocks]
    T6[links-validator · scroll-to-top · image-zoom · github-alerts · llms-txt · kbd]
    T1 --> T2 --> T3 --> T4 --> T5 --> T6
  end
  S --> plugins

Rules worth keeping:

1. zaj-mermaid before Starlight — browser rendering is registered before Starlight pages render; Markdown conversion lives in top-level markdown.processor.
2. starlight-auto-sidebar before starlight-utils — required if multiSidebar is ever turned on.
3. starlight-theme-rapide first among plugins — its CSS is the base layer; customCss loads after and wins on tokens.
4. New plugins — check peerDependencies against Starlight ^0.39 and Astro ^6; run npm run build before merging.

Site-specific config notes

Plugin	Our config
starlight-sidebar-topics	Five shelves; topics.directory maps /directory/*/* detail pages; exclude for tags and directory detail routes that use the default sidebar.
starlight-tags	onInlineTagsNotFound: 'create', tagsIndexSlug: 'tag-index' — auto-create individual tag pages while the custom /tags/ explorer owns the main tags route.
starlight-markdown-blocks	Custom blocks: idea (green), decision (purple), start (accent), next (orange), summary (blue).
starlight-links-validator	exclude: ['/kits/**'] — kit ZIPs live under public/, not Starlight routes.
starlight-kbd	macOS + Windows types; globalPicker: false because Header.astro overrides ThemeSelect.
starlight-changelogs	Commented out — see Changelog.

Adding or removing a plugin

1. cd app && npm install <package> (or remove from package.json).
2. Register in astro.config.mjs if it exposes a Starlight plugin (most starlight-* packages do; component-only packages do not).
3. Update Site Authoring Capabilities if authors need to know about it.
4. Add a demo to Component library when the plugin ships UI components.
5. Run npm run build — links-validator and the new plugin’s own build hooks must pass.
6. Record the change in Changelog and app/CHANGELOG.md.

Related

Page	Use it for
Site Authoring Capabilities	Author-facing “what can I use on a page?” inventory (plugins + custom components + tokens).
Best Starlight Plugins — By Purpose	Wider catalog for evaluating future additions.
Component library	Live regression gallery for Starlight + Zaj add-on components.
Changelog	When plugins were wired, blocked, or upgraded.