update-starlight-docs

Update Starlight Documentation

Update the Astro Starlight user documentation site to reflect code changes that affect user-facing features, configuration, or behavior.

Before Starting

1. Identify what changed in the code that affects users
2. Read the current Starlight docs structure: site/src/content/docs/
3. Determine affected pages (EN and ES)

Documentation Architecture

Two documentation systems coexist:

System	Path	Audience	Format
Developer docs	docs/	Contributors, AI agents	Markdown
User docs	site/src/content/docs/	End users	MDX (Starlight)

Rule: Code changes that affect user-facing behavior MUST update BOTH systems.

Steps

1. Map code changes to affected docs

Code Change	User Doc Pages
New MCP tool	tools-reference, relevant domain page
New config option	configuration, env-reference
New capability	capabilities, getting-started
Transport change	getting-started, http-server-mode
Error handling change	troubleshooting, error-handling
Security change	security

2. Edit EN pages first

All pages live under site/src/content/docs/en/:

site/src/content/docs/en/
├── index.mdx          # Landing page
├── getting-started.mdx
├── configuration.mdx
├── tools-reference.mdx
├── ...

3. Edit corresponding ES pages

Mirror structure under site/src/content/docs/es/ with translated content.

4. Frontmatter requirements

Every .mdx file must have:

---
title: "Page Title"
description: "Brief description for SEO and sidebar"
sidebar:
  order: 5  # Controls sidebar ordering
---

5. Use Starlight components

import { Aside, Tabs, TabItem, Card, CardGrid, Steps, FileTree, LinkCard } from '@astrojs/starlight/components';

<Aside type="tip">Helpful tip here</Aside>
<Aside type="caution">Warning message</Aside>
<Aside type="danger">Critical warning</Aside>

<Tabs>
  <TabItem label="Linux">Linux instructions</TabItem>
  <TabItem label="macOS">macOS instructions</TabItem>
  <TabItem label="Windows">Windows instructions</TabItem>
</Tabs>

<Steps>
1. First step
2. Second step
3. Third step
</Steps>