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

.gitignore

@@ -61,4 +61,7 @@ vitest.config.*.timestamp*
 .claude/worktrees
 .nx/polygraph
 .nx/self-healing
-.nx/migrate-runs
+.nx/migrate-runs
+
+# TypeDoc auto-generated API reference
+**/src/content/docs/reference/

.prettierignore

@@ -14,4 +14,8 @@ bun.lock
 .angular
 
 /.nx/workspace-data
-.nx/self-healing
+.nx/self-healing
+
+# Astro generated + TypeDoc auto-generated reference
+.astro
+**/src/content/docs/reference/

CLAUDE.md

@@ -9,7 +9,7 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 - **`@naxodev/nx-cloudflare`** (`packages/nx-cloudflare`) — Nx plugin for Cloudflare Workers (generators, executors, and a `createNodesV2` inference plugin around Wrangler).
 - **`@naxodev/gonx`** (`packages/gonx`) — Nx plugin for using Go in an Nx workspace (fork of nx-go, modernized). Includes a tree-sitter–based Go static-analysis graph.
 
-Supporting (non-published) projects: `e2e-utils` (shared e2e helpers), `nx-cloudflare-e2e` / `gonx-e2e` (e2e suites), and `gonx-docs` (Astro Starlight docs site at `packages/docs/gonx-docs`).
+Supporting (non-published) projects: `e2e-utils` (shared e2e helpers), `nx-cloudflare-e2e` / `gonx-e2e` (e2e suites), and two Astro Starlight docs sites (`docs/nx-cloudflare-docs`, `docs/gonx-docs`).
 
 **Workspace structure:** a **bun workspace** (`workspaces: ["packages/*"]`) using **TypeScript project linking** — a composite `tsconfig.base.json` (`module/moduleResolution: nodenext`, `customConditions: ["@naxodev/source"]`), a root solution `tsconfig.json` with project `references`, and the `@nx/js/typescript` inference plugin (managed by `nx sync`); there are no `tsconfig` `paths`. Shared dependency versions live in a single root `catalog` (referenced as `"catalog:"`); the two plugins' **published** runtime deps stay explicit (loose ranges). Tests run on `bun test` (see below).
 

docs/gonx-docs/astro.config.mjs

@@ -1,19 +1,57 @@
-import { defineConfig } from 'astro/config';
+import react from '@astrojs/react';
+import sitemap from '@astrojs/sitemap';
 import starlight from '@astrojs/starlight';
+import tailwindcss from '@tailwindcss/vite';
+import { defineConfig, fontProviders } from 'astro/config';
+import starlightLlmsTxt from 'starlight-llms-txt';
+import { createStarlightTypeDocPlugin } from 'starlight-typedoc';
+
+const [gonxTypeDoc, gonxTypeDocSidebarGroup] = createStarlightTypeDocPlugin();
+
+const repoRoot = '../../';
+const sourceLinkTemplate =
+  'https://github.com/naxodev/oss/blob/main/{path}#L{line}';
 
 export default defineConfig({
+  site: 'https://gonx.naxo.dev',
+  output: 'static',
   outDir: '../../dist/docs/gonx-docs',
+  redirects: {
+    '/': { destination: '/getting-started/introduction/', status: 301 },
+  },
+  markdown: {
+    shikiConfig: {
+      themes: {
+        light: 'github-light',
+        dark: 'github-dark',
+      },
+      defaultColor: false,
+      transformers: [
+        {
+          name: 'meta-title',
+          pre(node) {
+            const raw = this.options.meta?.__raw;
+            if (!raw) return;
+            const match = raw.match(/title="([^"]+)"/);
+            if (match) {
+              node.properties['data-title'] = match[1];
+            }
+          },
+        },
+      ],
+    },
+  },
   integrations: [
     starlight({
-      title: 'GoNx Docs',
+      title: 'GoNx',
       description: 'Nx plugin for Go development',
       favicon: '/favicon.svg',
       disable404Route: true,
       social: [
         {
           icon: 'github',
           label: 'GitHub',
-          href: 'https://github.com/naxodev/oss/tree/main/packages/gonx',
+          href: 'https://github.com/naxodev/oss',
         },
         {
           icon: 'npm',
@@ -26,34 +64,135 @@ export default defineConfig({
           href: 'https://discord.gg/zjDCGpKP2S',
         },
       ],
+      editLink: {
+        baseUrl: 'https://github.com/naxodev/oss/edit/main/docs/gonx-docs/',
+      },
+      plugins: [
+        starlightLlmsTxt({
+          projectName: 'GoNx',
+          description:
+            'Nx plugin for Go development — generators, executors, and a tree-sitter–based Go static-analysis graph for Nx workspaces.',
+          customSets: [
+            {
+              label: 'Getting Started',
+              paths: ['getting-started/**'],
+              description: 'Introduction, quick start, and installation',
+            },
+            {
+              label: 'Guides',
+              paths: ['guides/**'],
+              description: 'Task-oriented how-tos for generators and executors',
+            },
+            {
+              label: 'Reference',
+              paths: ['reference/**'],
+              description: 'API documentation for @naxodev/gonx',
+            },
+          ],
+          promote: ['getting-started/quick-start'],
+        }),
+        gonxTypeDoc({
+          entryPoints: ['../../packages/gonx/src/index.ts'],
+          tsconfig: '../../packages/gonx/tsconfig.lib.json',
+          output: 'reference',
+          sidebar: { label: '@naxodev/gonx', collapsed: true },
+          typeDoc: {
+            excludeInternal: true,
+            disableGit: true,
+            basePath: repoRoot,
+            sourceLinkTemplate,
+          },
+        }),
+      ],
+      customCss: ['./src/styles/custom.css'],
+      expressiveCode: false,
+      components: {
+        Header: './src/components/Header.astro',
+        Sidebar: './src/components/Sidebar.astro',
+        ThemeSelect: './src/components/ThemeSelect.astro',
+        Head: './src/components/Head.astro',
+        Pagination: './src/components/Pagination.astro',
+      },
       sidebar: [
-        { label: 'Quick Start', slug: 'quick-start' },
         {
-          label: 'Generators',
+          label: 'Getting Started',
+          items: [
+            { slug: 'getting-started/introduction' },
+            { slug: 'getting-started/quick-start' },
+            { slug: 'getting-started/installation' },
+          ],
+        },
+        {
+          label: 'Tutorials',
+          items: [{ slug: 'tutorials/first-go-project' }],
+        },
+        {
+          label: 'Guides',
           items: [
-            { label: 'init', slug: 'generators/init' },
-            { label: 'application', slug: 'generators/application' },
-            { label: 'library', slug: 'generators/library' },
-            { label: 'go-blueprint', slug: 'generators/go-blueprint' },
-            { label: 'preset', slug: 'generators/preset' },
-            { label: 'options', slug: 'generators/options' },
+            {
+              label: 'Generators',
+              items: [
+                { slug: 'guides/generators/application' },
+                { slug: 'guides/generators/library' },
+                { slug: 'guides/generators/init' },
+                { slug: 'guides/generators/preset' },
+                { slug: 'guides/generators/go-blueprint' },
+                { slug: 'guides/generators/options' },
+              ],
+            },
+            {
+              label: 'Executors',
+              items: [
+                { slug: 'guides/executors/build' },
+                { slug: 'guides/executors/serve' },
+                { slug: 'guides/executors/test' },
+                { slug: 'guides/executors/lint' },
+                { slug: 'guides/executors/tidy' },
+                { slug: 'guides/executors/generate' },
+                { slug: 'guides/executors/nx-release-publish' },
+              ],
+            },
           ],
         },
         {
-          label: 'Executors',
+          label: 'Reference',
+          items: [gonxTypeDocSidebarGroup],
+        },
+        {
+          label: 'Understanding',
+          items: [{ slug: 'understanding/static-analysis' }],
+        },
+        {
+          label: 'Community',
           items: [
-            { label: 'generate', slug: 'executors/generate' },
-            { label: 'build', slug: 'executors/build' },
-            { label: 'lint', slug: 'executors/lint' },
-            { label: 'test', slug: 'executors/test' },
-            { label: 'tidy', slug: 'executors/tidy' },
-            { label: 'serve', slug: 'executors/serve' },
-            { label: 'release', slug: 'executors/nx-release-publish' },
+            { slug: 'community/migration' },
+            { slug: 'community/contributing' },
           ],
         },
-        { label: 'Migration from nx-go', slug: 'migration' },
       ],
-      customCss: ['./src/styles/custom.css'],
+      lastUpdated: true,
+      pagination: true,
     }),
+    react(),
+    sitemap(),
+  ],
+  vite: {
+    plugins: [tailwindcss()],
+  },
+  fonts: [
+    {
+      provider: fontProviders.google(),
+      name: 'Inter',
+      cssVariable: '--font-heading',
+      weights: [400, 500, 600, 700],
+      fallbacks: ['system-ui', 'sans-serif'],
+    },
+    {
+      provider: fontProviders.google(),
+      name: 'JetBrains Mono',
+      cssVariable: '--font-code',
+      weights: [400, 500],
+      fallbacks: ['monospace'],
+    },
   ],
 });

docs/gonx-docs/project.json

@@ -7,6 +7,7 @@
     "default": ["{projectRoot}/**/*"],
     "production": ["!{projectRoot}/**/*.spec.tsx"]
   },
+  "implicitDependencies": ["gonx"],
   "targets": {
     "build": {
       "inputs": ["production", "^production"],

docs/gonx-docs/src/components/Head.astro

@@ -0,0 +1,27 @@
+---
+import { Font } from 'astro:assets';
+import { ClientRouter } from 'astro:transitions';
+
+const { head } = Astro.locals.starlightRoute;
+---
+
+{head.map(({ tag: Tag, attrs, content }) => <Tag {...attrs} set:html={content} />)}
+<Font cssVariable="--font-heading" preload />
+<Font cssVariable="--font-code" />
+<ClientRouter />
+<script>
+  import { enhanceCodeBlocks } from '../lib/code-blocks';
+  import { initTocPath, cleanupTocPath } from '../lib/toc-path';
+  import { initCopyForAi } from '../lib/copy-for-ai';
+
+  enhanceCodeBlocks();
+  initTocPath();
+  initCopyForAi();
+
+  document.addEventListener('astro:before-swap', cleanupTocPath);
+  document.addEventListener('astro:after-swap', () => {
+    enhanceCodeBlocks();
+    requestAnimationFrame(initTocPath);
+    initCopyForAi();
+  });
+</script>

docs/gonx-docs/src/components/Header.astro

@@ -0,0 +1,35 @@
+---
+import PluginLogo from './PluginLogo.astro';
+---
+
+<div class="header">
+  <PluginLogo height={18} />
+</div>
+
+<style>
+  .header {
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    height: 100%;
+    gap: 0.5rem;
+  }
+
+  :global(:root[data-theme='dark']) .header {
+    color: white;
+  }
+
+  :global(:root[data-theme='light']) .header {
+    color: #1e1b2e;
+  }
+
+  .header:hover {
+    opacity: 0.8;
+  }
+
+  @media (min-width: 50rem) {
+    .header {
+      display: none;
+    }
+  }
+</style>