|
34 | 34 | - 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 |
35 | 35 | - After adding a sub-project, always run `npm run build` and `npm test` from the **root** to verify isolation |
36 | 36 |
|
| 37 | +## Website / Astro link strategy |
| 38 | + |
| 39 | +**The trailing-slash rule:** GitHub Pages serves every page at a URL ending in `/` |
| 40 | +(e.g. `/AstroChart/quickstart/`). The browser resolves `./` relative to that directory, |
| 41 | +so `./guides/foo` from a root page resolves to `/AstroChart/quickstart/guides/foo` — **broken**. |
| 42 | + |
| 43 | +Use this rule for all links inside `src/content/docs/`: |
| 44 | + |
| 45 | +| From page depth | Link target | Correct prefix | Example | |
| 46 | +|---|---|---|---| |
| 47 | +| Root page (`quickstart.md`) | Any other page (sibling OR subdir) | `../` | `../installation`, `../guides/radix-chart` | |
| 48 | +| Subdir page (`guides/radix-chart.mdx`) | Sibling in same subdir | `./` | `./transit-chart` | |
| 49 | +| Subdir page (`guides/radix-chart.mdx`) | Root page or other subdir | `../` | `../api/settings` | |
| 50 | +| Nested subdir (`guides/frameworks/react.md`) | Sibling in same nested subdir | `./` | `./vue` | |
| 51 | +| Nested subdir (`guides/frameworks/react.md`) | Parent subdir | `../` | `../radix-chart` | |
| 52 | +| Nested subdir (`guides/frameworks/react.md`) | Root or other top-level subdir | `../../` | `../../api/chart` | |
| 53 | + |
| 54 | +> **Why root pages always use `../`:** GitHub Pages (and `trailingSlash: 'always'`) serves |
| 55 | +> every page at a URL ending in `/` (e.g. `/AstroChart/installation/`). The browser treats |
| 56 | +> that as a directory, so `./quickstart` resolves to `/AstroChart/installation/quickstart` — |
| 57 | +> **wrong even for siblings**. Use `../` to escape to `/AstroChart/` first. |
| 58 | +
|
| 59 | +- **In `.astro` templates:** use `import.meta.env.BASE_URL + '/path'` (already correct in `index.astro`). |
| 60 | +- **In Starlight config (`astro.config.mjs`):** use `slug:` values — never `link:` with absolute paths. |
| 61 | +- **Never** use root-absolute paths like `/guides/foo` inside `.md`/`.mdx` — they ignore the `base` setting. |
| 62 | +- **Future domain migration** (`astrochart.dev`): change only `site` and `base` in `astro.config.mjs` — no content files change. |
| 63 | + |
| 64 | +> **⚠️ Do not set `trailingSlash: 'always'`** in `astro.config.mjs`. |
| 65 | +> Astro's markdown pipeline emits relative link hrefs verbatim (`../guides/foo`, no trailing |
| 66 | +> slash). Setting `'always'` makes the dev server 404 every one of the ~50 relative links in |
| 67 | +> the content tree. GitHub Pages issues a silent 301 for slash-less URLs in production, so |
| 68 | +> links work correctly without the strict setting. The default (`'ignore'`) is correct here. |
| 69 | +
|
| 70 | +**⚠️ 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. |
| 71 | + |
37 | 72 | ## Website / Astro content rules |
38 | 73 | - **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. |
39 | 74 | - **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: |
|
0 commit comments