docs: upgrade both docs sites to maelstrom-level architecture with Diataxis, TypeDoc, and Tailwind design system (#156)

[NachoVazquez]

TL;DR

Both docs sites (gonx-docs and nx-cloudflare-docs) have been upgraded from basic Starlight setups to a maelstrom-level architecture: Tailwind v4 + glassmorphism design system, custom component overrides (sidebar, theme toggle, pagination with page feedback + copy-for-AI), TypeDoc auto-generated API reference, llms.txt generation, view transitions, Fumadocs-style TOC serpentine indicator, and Diátaxis content restructure.

Files to review (113, +7103 / -2171):

File	Why
docs/nx-cloudflare-docs/ (start here)	New docs site — 22 pages, full design system, TypeDoc reference
docs/gonx-docs/	Upgraded site — 23 pages, restructured into Diátaxis dirs
package.json	Added Tailwind, TypeDoc, sitemap, starlight plugins to catalog; upgraded Astro 5→6, Starlight 0.35→0.39, Vite 8→7

Why

The docs sites were functional but basic — default Starlight styling, no custom components, no API reference, no search enhancements, and the content structure didn't follow a consistent framework. The maelstrom docs site (maelstrom-co/maelstrom/apps/docs) had already solved these problems with a mature architecture. This PR ports that architecture to both plugins while adapting the branding (orange for nx-cloudflare, purple for gonx).

How

Phase 1 — Infrastructure port (per site, 26 files each):

1. Tailwind v4 + glassmorphism design system — 7 CSS files: custom.css (theme tokens, noise texture, h2 gradient borders), theme-vars.css (dark/light Starlight variable overrides), code-blocks.css (glass code blocks with copy buttons), sidebar.css (active states, scrollable nav), layout.css (desktop/mobile header, view transitions), toc.css (serpentine indicator), components.css (inline code pills, glass cards, search dialog, feedback buttons, focus indicators, reduced motion)
2. Custom Starlight component overrides — 6 components: PluginLogo.astro (inline SVG wordmark), Header.astro (mobile-only), Sidebar.astro (logo + search + scrollable nav + bottom bar with social icons + theme toggle), ThemeSelect.astro (sun/moon toggle with FOUC prevention), Head.astro (Inter + JetBrains Mono fonts, view transitions, code-block/toc-path init), Pagination.astro (page feedback + copy-for-AI + prev/next)
3. Client-side libs — 5 libs: code-blocks.ts (copy buttons + title bars), copy-for-ai.ts (page → markdown for LLMs), page-feedback.ts (localStorage "was this page helpful?"), preferences.ts (safe localStorage wrappers), toc-path.ts (Fumadocs-style SVG serpentine with scroll-tracked active highlight)
4. Config — astro.config.mjs rewritten: Tailwind vite plugin, React + sitemap integrations, starlight-llms-txt plugin, starlight-typedoc plugin (auto-generates API reference from src/index.ts), custom shiki themes (github-light/dark), meta-title transformer, fonts via Astro Fonts API, component overrides, Diátaxis sidebar structure, lastUpdated + pagination enabled

Phase 2 — Diátaxis content restructure:

Both sites reorganized into quadrant-based directories:

• getting-started/ — introduction, quick-start, installation (new)
• guides/ — generators and targets/executors (how-to reference)
• reference/ — TypeDoc auto-generated API docs (new)
• understanding/ — explanation pages (wrangler config inference, static analysis)
• community/ — migration, contributing (new)
• tutorials/ — first-go-project (gonx only, new)

New pages created: introduction.md, installation.md (both sites), contributing.md, static-analysis.md, first-go-project.md (gonx). All internal links updated to new slugs.

Dropped from maelstrom (by design):

• Framework selector (not applicable to Nx plugins)
• PostHog analytics (page feedback is localStorage-only)

Dependency upgrades:

• Astro 5.18 → 6.4 (required by Starlight 0.39)
• Starlight 0.35 → 0.39 (plugin API, component overrides)
• Vite 8.0 → 7.3 (Astro 6 + Vitest 4 peer dep compatibility)
• Added: @astrojs/react, @astrojs/sitemap, @astrojs/starlight-tailwind, @tailwindcss/vite, tailwindcss, starlight-llms-txt, starlight-typedoc, typedoc, typedoc-plugin-markdown

Reviewer notes

• Brand adaptation. nx-cloudflare uses an orange accent scale (#F38020); gonx uses purple (#667eea). Both have matching warm/cool light-mode backgrounds.
• TypeDoc generates from barrel exports. nx-cloudflare's src/index.ts re-exports 3 generator functions + 3 schema interfaces → 7 reference pages. gonx's src/index.ts exports the NxPlugin object → 2 reference pages. Both use excludeInternal: true and GitHub source links.
• No PostHog. Page feedback stores in localStorage only — no analytics, no external requests.
• .astro/ generated files are gitignored. The root .gitignore has .astro — these are build artifacts, not committed.
• Astro 6 upgrade. Required for Starlight 0.39's plugin API. The preload font option was removed in Astro 6 (fonts are preloaded by default).
• Vite downgrade. Vite 8.0.9 in the catalog was incompatible with Astro 6 (needs Vite 7.x) and Vitest 4 (needs Vite 6||7). Downgraded to ^7.3.2.
• implicitDependencies wired. Both docs project.json files declare implicit deps on their plugin packages, so nx affected -t build rebuilds docs when plugin source changes.
• Custom domains. nx-cloudflare docs → nx-cloudflare.naxo.dev, gonx docs → gonx.naxo.dev (already configured). Both need Cloudflare dashboard wiring.

Tests

Both docs sites build successfully:

• bunx nx build nx-cloudflare-docs → 22 pages, 0 errors, sitemap generated, pagefind search index built
• bunx nx build gonx-docs → 23 pages, 0 errors, sitemap generated, pagefind search index built
• bunx nx format:check → clean

Links

• Closes nx-cloudflare: set up a dedicated documentation site #156
• Part of nx-cloudflare: modernization epic (Nx 22 + Wrangler v4) #115 (nx-cloudflare modernization epic)
• Architecture adapted from maelstrom-co/maelstrom docs site

[cloudflare-workers-and-pages]

Deploying with    Cloudflare Workers

The latest updates on your project. Learn more about integrating Git with Workers.

Status	Name	Latest Commit	Preview URL	Updated (UTC)
✅ Deployment successful! View logs	gonx-docs	a5753ef	Commit Preview URL Branch Preview URL	Jun 22 2026, 10:55 AM

[cloudflare-workers-and-pages]

Deploying with    Cloudflare Workers

The latest updates on your project. Learn more about integrating Git with Workers.

Status	Name	Latest Commit	Updated (UTC)
✅ Deployment successful! View logs	nx-cloudflare	a5753ef	Jun 22 2026, 10:55 AM

[nx-cloud]

🤖 Nx Cloud AI Fix

Ensure the fix-ci command is configured to always run in your CI pipeline to get automatic fixes in future runs. For more information, please see https://nx.dev/ci/features/self-healing-ci

---

View your CI Pipeline Execution ↗ for commit a5753ef

Command	Status	Duration	Result
nx affected -t e2e --parallel=1	✅ Succeeded	3m 24s	View ↗
nx affected -t build --yes	✅ Succeeded	24s	View ↗
nx affected -t lint test	✅ Succeeded	39s	View ↗
nx-cloud record -- nx format:check	✅ Succeeded	2s	View ↗

💡 Verify your cache is correct by running tasks in a sandbox. Read docs ↗

---

☁️ Nx Cloud last updated this comment at 2026-06-22 10:59:49 UTC