diff --git a/CLAUDE.md b/CLAUDE.md index 70d4baa60..5877ed343 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -115,7 +115,9 @@ pnpm build pnpm preview ``` -Docs content lives in `docs/src/content/docs/` as `.md` and `.mdx` files organized by topic: `domain/`, `persistence/`, `application/`, `subscriptions/`, `read-models/`, `producers/`, `gateway/`, `diagnostics/`, and `infra/` (per-provider: esdb, postgres, mongodb, mssql, sqlite, kafka, rabbitmq, pubsub, elastic). MDX files can use Astro components. Mermaid diagrams are supported via `starlight-client-mermaid` plugin. Versioned docs (0.15) are managed by the `starlight-versions` plugin in `docs/src/content/docs/0.15/`. Sidebar is configured in `astro.config.mjs`. Frontmatter uses Starlight format (`sidebar.order` for ordering, not `sidebar_position`). +Docs content lives in `docs/src/content/docs/` as `.md` and `.mdx` files organized by topic: `domain/`, `persistence/`, `application/`, `subscriptions/`, `read-models/`, `producers/`, `gateway/`, `diagnostics/`, and `infra/` (per-provider: esdb, postgres, mongodb, mssql, sqlite, kafka, rabbitmq, pubsub, azure-service-bus, elastic). MDX files can use Astro components. Mermaid diagrams are supported via `starlight-client-mermaid` plugin. Sidebar is auto-generated from directories in `astro.config.mjs`. Frontmatter uses Starlight format (`sidebar.order` for ordering, not `sidebar_position`). + +For detailed docs versioning and authoring rules, see `docs/DOCS_VERSIONING.md`. ## Code Style diff --git a/docs/DOCS_VERSIONING.md b/docs/DOCS_VERSIONING.md new file mode 100644 index 000000000..9259ac461 --- /dev/null +++ b/docs/DOCS_VERSIONING.md @@ -0,0 +1,82 @@ +# Docs Versioning & Authoring Guide + +This file is for Claude Code. It documents how the Eventuous docs site versioning works so docs can be updated correctly. + +## Version Structure + +Managed by the `starlight-versions` plugin in `astro.config.mjs`. + +``` +docs/src/content/docs/ ← "current" version (root, shown by default) +docs/src/content/docs/0.15/ ← archived v0.15 snapshot +docs/src/content/docs/next/ ← preview placeholder for future version +docs/src/content/versions/ ← sidebar configs per version (JSON) +``` + +- **Root** (`docs/src/content/docs/`) is always the current stable version. +- **Archived versions** (e.g. `0.15/`) are read-only snapshots. Don't edit unless fixing a bug in old docs. +- **`next/`** is a minimal placeholder. When preparing a new release, content accumulates here, then gets promoted to root. + +## Config in astro.config.mjs + +```js +starlightVersions({ + current: { label: 'v0.16 (Stable)' }, + versions: [ + { slug: '0.15', label: 'v0.15' }, + { slug: 'next', label: 'Preview' }, + ], +}), +``` + +Each entry in `versions` must have a matching directory under `docs/src/content/docs/{slug}/` and a sidebar config at `docs/src/content/versions/{slug}.json`. + +## Relative Path Rules + +Component imports and markdown links use different base paths. Getting these wrong breaks the build. + +### Component imports (filesystem-relative) + +From `docs/src/content/docs/` to `docs/src/components/`: + +| File location | Import path | +|---|---| +| Root subdirectory (e.g. `subscriptions/checkpoint.mdx`) | `../../../components/Foo.astro` (3 levels) | +| Versioned subdirectory (e.g. `0.15/subscriptions/checkpoint.mdx`) | `../../../../components/Foo.astro` (4 levels) | + +### Markdown links (doc-tree-relative) + +Internal doc links resolve within the doc tree, not the filesystem: + +| File location | Link to another section | +|---|---| +| Root subdirectory (e.g. `infra/esdb.md`) | `../../application/app-service` (2 levels) | +| `next/` subdirectory (e.g. `next/infra/esdb.md`) | `../../../application/app-service` (3 levels) | + +### Hero image (index.mdx) + +| File location | Image path to `src/assets/logo.png` | +|---|---| +| Root `index.mdx` | `../../assets/logo.png` | +| `0.15/index.mdx` | `../../../assets/logo.png` | + +## How to Release a New Version + +To promote `next/` to a new stable version (e.g. v0.17): + +1. **Archive current root** → copy root content (excluding `next/` and version dirs) into a new directory (e.g. `0.16/`). Create a matching `src/content/versions/0.16.json` sidebar config (copy from `next.json` template). +2. **Replace root with `next/`** → delete root content files, copy `next/` to root. +3. **Fix relative paths** → reduce all `../` depths by 1 in the new root files (component imports: 4→3, markdown links: 3→2, hero image: 3→2). +4. **Fix archived version paths** → increase all `../` depths by 1 in the archived directory (component imports: 3→4). +5. **Update `astro.config.mjs`** → change `current.label`, add archived version to `versions` array. +6. **Reset `next/`** → delete all content, create a single `whats-new.mdx` placeholder. Update `next.json` sidebar to only reference `whats-new`. +7. **Build and verify** → `pnpm build` must pass. Check page count and spot-check version selector. + +> **Do not** rely on the plugin's auto-snapshot feature (`ensureNewVersion`). It fails on MDX files with complex Astro expressions. Always snapshot manually. + +## Adding New Doc Pages + +- Add `.md` or `.mdx` files to the appropriate topic directory under root docs. +- The sidebar auto-generates from directory contents. Use `sidebar.order` in frontmatter to control ordering. +- For new infrastructure providers, add to `infra/` with a descriptive filename (e.g. `azure-service-bus.md`). +- If adding pages to `next/` for a future version, remember that all relative paths need one extra `../` compared to root. diff --git a/docs/astro.config.mjs b/docs/astro.config.mjs index 3ff708870..b249b2fb6 100644 --- a/docs/astro.config.mjs +++ b/docs/astro.config.mjs @@ -18,8 +18,11 @@ export default defineConfig({ customCss: ['./src/styles/custom.css'], plugins: [ starlightVersions({ - current: { label: 'v0.15 (Stable)' }, - versions: [{ slug: 'next', label: 'Preview' }], + current: { label: 'v0.16 (Stable)' }, + versions: [ + { slug: '0.15', label: 'v0.15' }, + { slug: 'next', label: 'Preview' }, + ], }), starlightMermaid(), ], diff --git a/docs/src/components/ThemedImage.astro b/docs/src/components/ThemedImage.astro index 74244d241..a36c7c7d3 100644 --- a/docs/src/components/ThemedImage.astro +++ b/docs/src/components/ThemedImage.astro @@ -1,16 +1,19 @@ --- +import { Image } from 'astro:assets'; +import type { ImageMetadata } from 'astro'; + interface Props { alt: string; - lightSrc: string; - darkSrc: string; + lightSrc: ImageMetadata; + darkSrc: ImageMetadata; } const { alt, lightSrc, darkSrc } = Astro.props; --- - {alt} - {alt} + {alt} + {alt}