AstroDraw · afucher · Apr 2, 2026 · Apr 1, 2026 · Apr 1, 2026 · Apr 2, 2026
diff --git a/AGENTS.md b/AGENTS.md
@@ -34,6 +34,41 @@
 - Any new sub-project directory **must** be added to the root `tsconfig.json` `exclude` list AND to the `exclude` regex in `webpack.config.js` before committing
 - After adding a sub-project, always run `npm run build` and `npm test` from the **root** to verify isolation
 
+## Website / Astro link strategy
+
+**The trailing-slash rule:** GitHub Pages serves every page at a URL ending in `/`
+(e.g. `/AstroChart/quickstart/`). The browser resolves `./` relative to that directory,
+so `./guides/foo` from a root page resolves to `/AstroChart/quickstart/guides/foo` — **broken**.
+
+Use this rule for all links inside `src/content/docs/`:
+
+| From page depth | Link target | Correct prefix | Example |
+|---|---|---|---|
+| Root page (`quickstart.md`) | Any other page (sibling OR subdir) | `../` | `../installation`, `../guides/radix-chart` |
+| Subdir page (`guides/radix-chart.mdx`) | Sibling in same subdir | `./` | `./transit-chart` |
+| Subdir page (`guides/radix-chart.mdx`) | Root page or other subdir | `../` | `../api/settings` |
+| Nested subdir (`guides/frameworks/react.md`) | Sibling in same nested subdir | `./` | `./vue` |
+| Nested subdir (`guides/frameworks/react.md`) | Parent subdir | `../` | `../radix-chart` |
+| Nested subdir (`guides/frameworks/react.md`) | Root or other top-level subdir | `../../` | `../../api/chart` |
+
+> **Why root pages always use `../`:** GitHub Pages (and `trailingSlash: 'always'`) serves
+> every page at a URL ending in `/` (e.g. `/AstroChart/installation/`). The browser treats
+> that as a directory, so `./quickstart` resolves to `/AstroChart/installation/quickstart` —
+> **wrong even for siblings**. Use `../` to escape to `/AstroChart/` first.
+
+- **In `.astro` templates:** use `import.meta.env.BASE_URL + '/path'` (already correct in `index.astro`).
+- **In Starlight config (`astro.config.mjs`):** use `slug:` values — never `link:` with absolute paths.
+- **Never** use root-absolute paths like `/guides/foo` inside `.md`/`.mdx` — they ignore the `base` setting.
+- **Future domain migration** (`astrochart.dev`): change only `site` and `base` in `astro.config.mjs` — no content files change.
+
+> **⚠️ Do not set `trailingSlash: 'always'`** in `astro.config.mjs`.
+> Astro's markdown pipeline emits relative link hrefs verbatim (`../guides/foo`, no trailing
+> slash). Setting `'always'` makes the dev server 404 every one of the ~50 relative links in
+> the content tree. GitHub Pages issues a silent 301 for slash-less URLs in production, so
+> links work correctly without the strict setting. The default (`'ignore'`) is correct here.
+
+**⚠️ Link audit rule:** Any task that adds/edits content files OR changes `base` config **must** end with a full grep audit of all `./` links across the entire `src/content/docs/` tree to confirm no root-level page has a `./` prefix remaining.
+
 ## Website / Astro content rules
 - **MDX required for component imports:** Starlight content files that use `import` and JSX component tags **must** have a `.mdx` extension. A `.md` file will print the import statement as plain text and silently ignore all component tags.
 - **Multi-instance inline script loading:** When an Astro `is:inline` script dynamically loads an external JS bundle, multiple component instances on the same page will all run simultaneously. Use a shared queue pattern to avoid race conditions:

diff --git a/website/astro.config.mjs b/website/astro.config.mjs
@@ -1,15 +1,18 @@
 import { defineConfig } from 'astro/config'
 import starlight from '@astrojs/starlight'
 import sitemap from '@astrojs/sitemap'
+import starlightLinksValidator from 'starlight-links-validator'
+
+const isDev = process.env.NODE_ENV === 'development'
 
 export default defineConfig({
   site: 'https://astrodraw.github.io/AstroChart',
   base: '/AstroChart',
   integrations: [
     starlight({
+      plugins: [...(isDev ? [] : [starlightLinksValidator({ errorOnRelativeLinks: false })])],
       title: 'AstroChart',
       description: 'Pure SVG astrology charts for the web',
-      favicon: '/favicon.svg',
       logo: {
         src: './public/img/logo.svg',
         alt: 'AstroChart Logo'

diff --git a/website/package-lock.json b/website/package-lock.json
diff --git a/website/package.json b/website/package.json
@@ -10,12 +10,13 @@
     "astro": "astro"
   },
   "dependencies": {
-    "astro": "^6.0.0",
-    "@astrojs/starlight": "^0.38.0",
     "@astrojs/sitemap": "^3.1.0",
+    "@astrojs/starlight": "^0.38.0",
+    "astro": "^6.0.0",
     "sharp": "^0.33.0"
   },
   "devDependencies": {
+    "starlight-links-validator": "^0.21.0",
     "typescript": "^5.3.3"
   },
   "engines": {

diff --git a/website/src/content/docs/changelog.md b/website/src/content/docs/changelog.md
@@ -53,7 +53,7 @@ This project adheres to [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
 
 ### Changed
 - **Breaking:** Package renamed to `@astrodraw/astrochart`
-- **Breaking:** `AstroData` shape changed to `{ planets: Record<string, number[]>, cusps: number[] }` — see the [Getting Started guide](./guides/getting-started)
+- **Breaking:** `AstroData` shape changed to `{ planets: Record<string, number[]>, cusps: number[] }` — see the [Introduction](../introduction)
 - Cusps array must contain exactly 12 values; validation throws a descriptive error on mismatch
 - `SHIFT_IN_DEGREES` default changed to `180` (0° on the West / Ascendant side)
 

diff --git a/website/src/content/docs/guides/frameworks/angular.md b/website/src/content/docs/guides/frameworks/angular.md
@@ -160,4 +160,4 @@ export class AstroChartComponent implements AfterViewInit, OnDestroy {
 
 - **[React Integration](./react)** — Use with React
 - **[Vue Integration](./vue)** — Use with Vue
-- **[Multiple Charts](../multiple-charts)** — Render several instances on one page
+- **[Multiple Charts](../../multiple-charts)** — Render several instances on one page
diff --git a/website/src/content/docs/guides/frameworks/vue.md b/website/src/content/docs/guides/frameworks/vue.md
@@ -203,4 +203,4 @@ const chartData = { planets: { Sun: [120.5] }, cusps: [0,30,60,90,120,150,180,21
 
 - **[React Integration](./react)** — Use with React
 - **[Angular Integration](./angular)** — Use with Angular
-- **[Multiple Charts](../multiple-charts)** — Render several instances on one page
+- **[Multiple Charts](../../multiple-charts)** — Render several instances on one page
diff --git a/website/src/content/docs/installation.md b/website/src/content/docs/installation.md
@@ -81,9 +81,9 @@ No additional `@types/` package needed.
 | Browsers (modern) | ✅ Supported |
 | IE11 | ⚠️ Requires polyfills |
 | Mobile browsers | ✅ Supported |
-| React | ✅ See [React guide](./guides/frameworks/react) |
-| Vue | ✅ See [Vue guide](./guides/frameworks/vue) |
-| Angular | ✅ See [Angular guide](./guides/frameworks/angular) |
+| React | ✅ See [React guide](../guides/frameworks/react) |
+| Vue | ✅ See [Vue guide](../guides/frameworks/vue) |
+| Angular | ✅ See [Angular guide](../guides/frameworks/angular) |
 
 ## Verification
 
@@ -98,6 +98,6 @@ console.log('AstroChart version:', version)
 
 ## Next Steps
 
-- **[Quick Start](./quickstart)** — Render your first chart
-- **[API Reference](./api/chart)** — Learn all available methods
-- **[Guides](./guides/radix-chart)** — Explore common use cases
+- **[Quick Start](../quickstart)** — Render your first chart
+- **[API Reference](../api/chart)** — Learn all available methods
+- **[Guides](../guides/radix-chart)** — Explore common use cases
diff --git a/website/src/content/docs/introduction.mdx b/website/src/content/docs/introduction.mdx
@@ -88,10 +88,10 @@ Here's a basic radix chart rendered with AstroChart:
 
 ## Next Steps
 
-- **[Installation Guide](./installation)** — Detailed setup instructions for npm, CDN, and more
-- **[Quick Start Guide](./quickstart)** — A step-by-step walkthrough with examples
-- **[Radix Chart Guide](./guides/radix-chart)** — Learn how to render complete natal charts
-- **[API Reference](./api/chart)** — Complete documentation of all classes and methods
+- **[Installation Guide](../installation)** — Detailed setup instructions for npm, CDN, and more
+- **[Quick Start Guide](../quickstart)** — A step-by-step walkthrough with examples
+- **[Radix Chart Guide](../guides/radix-chart)** — Learn how to render complete natal charts
+- **[API Reference](../api/chart)** — Complete documentation of all classes and methods
 
 ## Browser Support
 
@@ -105,8 +105,8 @@ AstroChart is released under the **MIT License**. See the [GitHub repository](ht
 
 ## Contributing
 
-Found a bug? Have a feature request? We'd love your help! See the [Contributing Guide](./contributing) for instructions.
+Found a bug? Have a feature request? We'd love your help! See the [Contributing Guide](../contributing) for instructions.
 
 ---
 
-Ready to dive in? [Get started now](./quickstart).
+Ready to dive in? [Get started now](../quickstart).
diff --git a/website/src/content/docs/quickstart.mdx b/website/src/content/docs/quickstart.mdx
@@ -127,11 +127,11 @@ Here's a live example you can interact with:
 
 ## Next Steps
 
-- **[Radix Chart Guide](./guides/radix-chart)** — Learn more about radix charts and all available planets
-- **[Transit Charts](./guides/transit-chart)** — Add a transit ring to overlay current positions
-- **[Animation](./guides/animation)** — Animate chart transitions
-- **[Custom Settings](./guides/custom-settings)** — Customize colors, fonts, and more
-- **[API Reference](./api/chart)** — See all available methods and options
+- **[Radix Chart Guide](../guides/radix-chart)** — Learn more about radix charts and all available planets
+- **[Transit Charts](../guides/transit-chart)** — Add a transit ring to overlay current positions
+- **[Animation](../guides/animation)** — Animate chart transitions
+- **[Custom Settings](../guides/custom-settings)** — Customize colors, fonts, and more
+- **[API Reference](../api/chart)** — See all available methods and options
 
 ## Troubleshooting
 
@@ -146,5 +146,5 @@ Here's a live example you can interact with:
 
 **Need help?**
 - [Open an issue on GitHub](https://github.com/AstroDraw/AstroChart/issues)
-- Check the [API Reference](./api/chart)
-- See [Common Guides](./guides/radix-chart)
+- Check the [API Reference](../api/chart)
+- See [Common Guides](../guides/radix-chart)