Standardize a docs-site stack for pack templates: Hugo vs Astro vs Docusaurus

[viniciusdc]

Summary

We don't currently scaffold a docs site in this template: packs inherit a long README and three reference markdowns under docs/. As more packs ship and we want a consistent "Nebari pack" presentation, we need to pick a static site generator (SSG) and bake it into the template so that every new pack starts with the same shape.

The current state of the art across our repos is inconsistent:

Repo	Docs stack
nebari-dev/nebari-docs	Docusaurus
nebari-dev/nebari-nebi-pack	Docusaurus
nebari-dev/skillsctl	Custom site, without Nebari theming
Every other pack (incl. provenance-collector)	README only — no docs site

This issue captures the comparison and trade-offs from a recent design discussion, so the team (and future template consumers) can see how the choice was reached and what's still open.

Constraints we're working under

The decision is mostly determined by how nebari-dev/nebari-design is distributed. After looking at it in depth:

• It's a shadcn/ui-style registry, not a published npm package ("private": true in package.json).
• Components are TSX source under registry/nebari/ui/, built on React 19 + Base UI primitives + Tailwind v4 + lucide-react + class-variance-authority + tailwind-merge.
• Consumers integrate via bunx shadcn add <component> — which copies the React source into the consumer's repo. There's no CDN bundle, no compiled UMD, no web-component wrappers.
• The CSS tokens (registry/nebari/globals.css) are Tailwind v4 @theme declarations: light + dark, semantic naming (background / foreground / primary / etc.), OKLCH colors. These are framework-agnostic as long as your build runs Tailwind v4.
• The repo's own build:pages script ships Storybook + the registry to GitHub Pages, so the integration model is "consumers fetch from a hosted registry."

Two implications follow:

1. Any docs site that wants to use nebari-design components needs React + Tailwind v4 + TypeScript in its build. There's no escape hatch — the components don't exist as a pre-compiled bundle that you can <script src> into HTML.
2. Any docs site that wants nebari-design's colors / typography / spacing needs Tailwind v4 in its build, because the tokens are Tailwind v4 @theme declarations.

So the practical question is "which SSG fits a Tailwind-v4-plus-shadcn-React design system most naturally?"

Hosting policy

The org runs two different deploy targets depending on the docs site's scope:

• nebari.dev (the main docs, currently Docusaurus) lives on Netlify. Netlify earns its keep there: deploy previews on every PR, redirects, custom-domain wiring, larger build budget — the long-lived flagship docs need that.
• Pack docs sites should default to GitHub Pages. Reasons:
  • One workflow file per repo; no separate Netlify project or dashboard to manage per pack.
  • No subscription / build-minutes dependency. Public-repo gh-pages is free and scales horizontally to N packs.
  • Each pack gets a predictable URL (<org>.github.io/<repo> or a custom domain) without org-level coordination.
  • Avoids the "who pays for the Netlify account when a pack maintainer is no longer on the team" footgun.

This is a default, not a constraint — an individual pack maintainer can migrate their pack's docs to Netlify if they have a genuine need (deploy previews on PRs, large traffic, redirect rules). But the template scaffolding should ship a gh-pages workflow as the out-of-the-box path.

All three SSGs we're comparing deploy to gh-pages cleanly via the standard actions/upload-pages-artifact + actions/deploy-pages chain, so this constraint doesn't break the tie between them — but it does shape the workflow shape we'll bake into the template, and it's worth surfacing here so reviewers don't assume Netlify everywhere.

Options

Hugo

• Pros: blazing-fast builds (Go binary), single tool, simple authoring (markdown + frontmatter + occasional shortcodes), team has prior experience (Chuck + others). Native gh-pages deploy via the official action. Themes like Doks / Geekdoc / Hextra are technical-docs-friendly.
• Cons against nebari-design: needs a Tailwind v4 build step bolted on via Hugo Pipes + PostCSS, so the "no Node in CI" advantage evaporates the moment we import globals.css. Cannot consume shadcn components at all without us writing per-component web-component shims and re-publishing them — a maintenance liability that grows with nebari-design.
• Fit verdict: clean for pack docs that want visual identity without runtime components. Forces a parallel build pipeline if we ever want to ship an interactive widget.

Astro

• Pros: purpose-built for "mostly static markdown, with islands of interactive components." Native React + Tailwind v4 + MDX. Can consume the shadcn registry directly — bunx shadcn add button inside an Astro pack's docs/ lands the same TSX the rest of Nebari uses. Static-by-default like Hugo; same gh-pages workflow shape. Components hydrate only on pages that use them, so markdown pages stay pure HTML.
• Cons: Node + a bundler in CI (but we're paying that anyway for Tailwind v4). Team has less institutional experience than Hugo. Versioning / search / i18n need to be assembled from parts (Pagefind for search, branch-based versioning, etc.) — not built-in like Docusaurus.
• Fit verdict: lowest-friction option for the nebari-design integration specifically. Marginal cost over Hugo is small once you accept Tailwind v4 in the toolchain.

Docusaurus

• Pros: already proven in nebari-docs and nebari-nebi-pack. Native React + MDX. Versioning, search, i18n, blog, plugins all built-in. Maintainers across the org already know the authoring conventions.
• Cons: heavier runtime than Astro for similar React-native capability. Theming is more opinionated; aligning with nebari-design's Tailwind v4 tokens fights Docusaurus's own theming layer somewhat. Larger bundles = slower first paint than Hugo or Astro.
• Fit verdict: correct choice for the deep, long-lived nebari-docs site. For a thin pack-docs scaffold that ships in every pack template, heavier than necessary.

Tradeoff at a glance

	Hugo	Astro	Docusaurus
Tailwind v4 (tokens)	Add via Hugo Pipes + PostCSS	Native	Native (but fights theme layer)
Shadcn component adoption	Custom-element shim per component	bunx shadcn add works directly	bunx shadcn add works directly
First paint	Lowest (no JS)	Low (islands hydrate only where used)	Medium (SSR + hydration of React shell on every page)
CI weight	Hugo binary + Node + Tailwind	Node + bundler	Node + bundler
Versioning / search / i18n	DIY	DIY (lightweight)	Built-in
Team familiarity	High (Chuck + others)	Medium (some experience)	High (nebari-docs incumbent)
Authoring	Markdown + Hugo shortcodes	Markdown / MDX + Astro components	MDX
Migration story for existing Docusaurus packs	Re-author	Re-author	None (already there)
gh-pages workflow fit (org default for packs — see "Hosting policy" above)	Native; standard upload-pages-artifact action	Native; standard upload-pages-artifact action	Native; docusaurus deploy or upload-pages-artifact. Main docs on Netlify is org-policy, not a tool limit.

Recommendation

Astro for pack docs, deployed to gh-pages, consuming nebari-design via shadcn add.

Reasoning:

1. The moment a pack imports nebari-design/registry/nebari/globals.css to get the visual identity, we need Tailwind v4 in the build. Hugo's "no Node toolchain" advantage stops being an advantage at that point.
2. The shadcn distribution model is fundamentally React-native. Astro consumes it with zero adapter code. Hugo would require a web-component shim layer that we'd maintain forever. That asymmetry is large enough to overrule team-familiarity arguments.
3. Astro is also lighter than Docusaurus for the same React capability, leaving nebari-docs (Docusaurus) as the heavy / long-lived docs site and packs as fast / lightweight satellites. Clean mental model: "deep docs = Docusaurus, pack docs = Astro."

Hugo stays defensible if the team decides pack docs explicitly don't need to consume nebari-design components — only its visual identity, hand-replicated in vanilla CSS. That's a valid simplification but it means the design library's value proposition stops at pack docs.

Docusaurus stays defensible as the choice for any individual pack that wants the nebari-docs feature set (versioning / search / i18n). New packs can opt in if they need it; the template default doesn't force them.

Proposed next step

Spike a minimal Astro docs site in provenance-collector to prove the integration end-to-end.

If it lands well, the skeleton graduates into this template as docs/site/ (or similar) and every future pack gets it for free via "Use this template."

References

• nebari-dev/nebari-design — shadcn registry, package.json, registry.json, registry/nebari/globals.css
• nebari-dev/nebari-docs — current Docusaurus incumbent for org-wide docs
• nebari-dev/nebari-nebi-pack — existing pack on Docusaurus
• nebari-dev/skillsctl — existing pack on a custom stack (untheamed)

[viniciusdc]

Open questions

Update: two of the four resolved below ✅. Two still open.

Storybook + Astro coexistence?

✅ Resolved: treat Storybook as authoritative

Pack docs link out to nebari-design's Storybook rather than try to lift stories into MDX. Reasoning:

• One source of visual truth. Storybook is already the canonical reference for what a Nebari component looks like — every state, every variant, every prop. Mirroring that surface into N pack docs sites would create N drift surfaces.
• Storybook ships at the design library's own deploy (build:pages on nebari-dev/nebari-design publishes Storybook + the shadcn registry side-by-side to GitHub Pages). Pack docs can link to a stable URL.
• Astro can still embed real components on a docs page when a pack-specific use case calls for it (e.g. an interactive "build your ArgoCD Application" widget). Embedding a story on a docs page is a different thing — the use case for that is much rarer and we can revisit it if a pack actually needs it.

Net: Storybook stays in nebari-design as the component showcase; pack docs are for pack content (install, config, examples) and use nebari-design components as building blocks, not as the subject matter.

Are the nebari-design components SSR-safe?

✅ Resolved: yes today, with a CI guard proposed

Audited every file in registry/nebari/:

File	Notes	Verdict
lib/utils.ts	Pure cn() over clsx + tailwind-merge. No state, no effects, no globals.	✓ SSR-safe
ui/spinner.tsx	Wraps lucide-react's LoaderCircle SVG with className + aria. Pure presentational; cva is server-pure.	✓ SSR-safe
ui/button.tsx	Uses Base UI's useRender for polymorphism. No useEffect / useLayoutEffect, no window / document reads, no portals. Render-only component; useRender is designed SSR-first.	✓ SSR-safe

One sticker-price note: @base-ui-components/react is pinned to 1.0.0-rc.0. Pre-1.0, but it's the Floating-UI / Radix team's new library and is SSR-first by design.

Practical consequence for the stack choice: Astro can render any of these with no client directive at all (purely static SSR output, zero JS shipped for the component). The client:load / client:visible modes become per-usage upgrades when an instance of the component needs interactivity — they aren't a baseline requirement.

Future risk + mitigation filed upstream: as the registry grows (Dialog, DropdownMenu, Tooltip, Popover, Select, Toast — all obvious shadcn-style additions), portals and focus management are the typical SSR slip points. Filed a follow-up at nebari-dev/nebari-design#52 proposing a CI test that auto-discovers components from registry.json and runs renderToString against each. ~30 min to wire up; turns this from a "trust but verify" property into a guarded one.

Still open: What's the right deploy story for the docs site within each pack repo?

A separate workflow on tag / merge to main? A docs/site/ subdirectory or a top-level astro/? The earlier Hosting policy section settles the target (gh-pages); this open question is about the per-pack directory layout and trigger semantics.

Still open: Theme / authoring conventions

A landing page template + sidebar pattern + frontmatter conventions need to live somewhere. Options:

• Baked into this template: every pack inherits the same layout by default; easy onboarding but harder to roll out theme updates org-wide (every pack pins its own copy).
• Separate nebari-pack-astro-theme repo: pack docs depend on it as an npm package or Astro integration; central updates propagate; one more moving part to maintain.

Both are defensible. The choice probably depends on whether we expect pack docs to diverge layout-wise (favor inline copy) or stay uniform (favor central theme).

[viniciusdc]

Conclusion — going with Astro for the template default

After working through the design-library integration question with a research pass (links below) and looking at the existing working Hugo example (nebari-dev/nebari-data-science-pack@aktech/docs-site), the team can now answer the original question with confidence.

The Hugo dynamic-sync path doesn't exist

Two things specifically:

1. Hugo + Tailwind v4 works. The css.TailwindCSS function natively supports v4, so consuming @nebari/theme's OKLCH tokens from a Hugo project is possible — you bunx shadcn add @nebari/theme to land the CSS file in your repo, then Hugo Pipes compiles it. But that's a manual periodic resync, not automatic. If @nebari/theme ships a token change, every Hugo pack repo needs a shadcn add re-run + commit.
2. The React components are unreachable from Hugo. There's no community tooling that bridges the shadcn registry into Hugo templates. The closest patterns (Babel + JSX in Hugo shortcodes, the ace-hugo project, etc.) are bespoke and pre-shadcn. Building a "shadcn-to-Hugo" derivation pipeline ourselves is significant ongoing engineering — not something this template should own.

So the practical Hugo path looks like this:

• Custom Hugo theme (Darby-style; could be a Nebari fork). Hand-built, parallel to nebari-design, must be re-skinned per visual change to nebari-design.
• Tokens-only consumption of @nebari/theme. Gets colors / spacing / typography, but the layout / navigation / cards / buttons in the Hugo theme are all hand-coded against those tokens.

Both are workable. Neither is dynamic in the sense of "nebari-design changes propagate automatically." The team would be maintaining two design surfaces (nebari-design's React/shadcn + the Hugo theme), with manual sync between them.

What Astro gets us that Hugo can't

With the same bunx shadcn add @nebari/<name> flow used in jbouder/nebari-ui-demo — Johnny's working consumer-side reference — an Astro pack-docs site:

• Consumes @nebari/theme natively, same one-line update path as any other consumer.
• Consumes @nebari/button, @nebari/spinner, and every future component the moment it lands in the registry. Astro renders them server-side by default (zero JS shipped when used statically); client:* directives upgrade specific instances to interactive.
• Does not require a separate theme repo, a shim layer, or a derivation pipeline. The same shadcn components.json model that the rest of the Nebari ecosystem already uses just works.

That's the design-system value proposition: one registry, N consumers, all in sync. Hugo can't participate in that loop without our building the bridge ourselves, and the bridge would only ever be partial (presentational components only; behavioral ones — Dialog, Tooltip, future Toast — can't be derived).

What about visual fidelity in pack docs?

The original framing was right: software packs don't need to fully utilize nebari-design components — a tokens-and-light-touch approach is enough. The argument here isn't that packs need every Dialog and Popover; it's that even the light-touch case is cheaper in Astro because the registry consumption flow is the same one Johnny's demo already uses. Picking Hugo would mean a separate Hugo-only adoption mechanism, and that mechanism would have no other home in the ecosystem.

A shared nebari-pack-astro-theme repo (per the original "Theme / authoring conventions" open question) can still own the layout / sidebar / navigation patterns common across pack docs — packs depend on it as an Astro integration; central updates propagate. The themed bits stay DRY; the registry consumption stays standard.

Decision

• Default for new pack docs: Astro + @nebari/* shadcn registry, deployed to gh-pages.
• Theme convention: tentatively a shared nebari-pack-astro-theme (final shape TBD as part of the spike below).
• Existing Docusaurus consumers (nebari-docs, nebari-nebi-pack): unchanged, coexist indefinitely.
• Hugo stays defensible for any maintainer who wants Amit's Darby experience for their pack. Not the default; documented in the template as an opt-out.

Next step: spike in provenance-collector

To turn this from a decision-on-paper into something the team can review against actual code, I'll prototype the Astro path in provenance-collector on a branch. Scope:

• docs-site/ directory with a minimal Astro project (astro.config.mjs, Tailwind v4, MDX).
• components.json configured for the @nebari registry (matching jbouder/nebari-ui-demo).
• Two pages: a landing page lifting the README intro, plus one content page exercising at least one shadcn-imported component (@nebari/button likely).
• gh-pages deploy workflow (actions/upload-pages-artifact + actions/deploy-pages), publishing to /docs/ so the helm-repo at gh-pages root stays untouched (same pattern as nebari-data-science-pack).
• docs-site/README.md explaining the structure and the shadcn add workflow.

If it lands well, the skeleton graduates into nebari-software-pack-template as the template's docs-site/ default. I'll open the PR with the spike branch shortly.

Sources

• css.TailwindCSS | Hugo docs — confirms Tailwind v4 + Hugo is supported, last updated 2026-06-05.
• Tailwind v4 - shadcn/ui — registry distribution model + the @theme / OKLCH design.
• shadcn-ui/registry-template — what nebari-design forked from; React-first, no Hugo target.
• components.json - shadcn/ui — registries block, used by Johnny's demo.
• Integrating React in Hugo (Hugo Discourse) — canonical "this is hard" community thread.
• aceHubert/ace-hugo — one of the few existing Hugo+React experiments; bespoke, not shadcn-aligned.
• Setting up TailwindCSS with PostCSS in Hugo — the manual integration pattern that's still the state of the art.
• jbouder/nebari-ui-demo — working consumer reference for the @nebari/* registry.
• nebari-dev/nebari-data-science-pack@aktech/docs-site — Hugo path Amit built; Darby theme.

[dcmcand]

We have standardized on Astro with the theme at https://github.com/nebari-dev/starlight