docs-page

name	docs-page
description	Use this skill when adding or substantially editing a page in the Astro Starlight docs site at docs/src/content/docs/. Handles the file layout, frontmatter format, sidebar registration in astro.config.mjs (the easy-to-miss step that leaves new pages unlinked), internal link conventions, and the .md vs .mdx choice.

Add or edit a docs page

The Omniglass developer documentation lives at docs/src/content/docs/ and is built with Astro Starlight. It is published to docs.hyperscaleav.com.

When to use

• Adding a new docs page (e.g. a follow-up to a feature PR, a new operations runbook, a new architecture explainer)
• Substantially editing an existing page where the structure or sidebar entry might need to change
• Reviewing whether a feature PR's accompanying docs are wired up correctly

For tiny edits (typo, fix a link), the skill is overkill — just edit the file.

The five things to get right

1. File location maps to the URL

The path under docs/src/content/docs/ maps directly to the URL slug:

File	URL
docs/src/content/docs/development/patching.md	/development/patching/
docs/src/content/docs/operations/going-to-production.md	/operations/going-to-production/
docs/src/content/docs/features/systems.md	/features/systems/

Pick the directory that matches the audience: development/ for contributors, features/ for what the product does, operations/ for runbooks, architecture.md (top-level) for the system shape, security/ for security topics. Create a new directory only if no existing bucket fits — adding to a heavy-traffic bucket is preferable to growing the navigation tree.

2. Frontmatter is Starlight-specific

Starlight expects title and description (not Astro's generic frontmatter). Both are required for proper rendering and SEO:

---
title: "Patching"
description: "How Zabbix source patches are created, applied, and retired."
---

This page covers...

The description is what shows up in search results and link previews, so write it for a human, not as a label.

3. Sidebar registration is manual — this is the failure mode

Adding a .md file under docs/src/content/docs/ creates a page but does not put it in the navigation. The page is reachable by direct URL but invisible from the sidebar, which means nobody finds it.

Edit docs/astro.config.mjs and add an entry under the appropriate section in the sidebar array:

{
  label: 'Development',
  items: [
    { label: 'Contributing', slug: 'development/contributing' },
    { label: 'Zabbix Patching', slug: 'development/patching' },
    { label: 'Release Strategy', slug: 'development/release-strategy' },
    { label: 'Testing', slug: 'development/testing' },
    // your new page goes here
    { label: 'Your New Page', slug: 'development/your-new-page' },
  ],
},

The slug is the file path under docs/src/content/docs/ without the .md extension. The label is the human-facing nav text — keep it short.

If you forget this step, the page exists but is unlinked. Always grep your slug in astro.config.mjs after creating a new file:

grep "your-new-page" docs/astro.config.mjs

If nothing matches, the page is orphaned.

4. Internal links use slug paths, not file paths

Inside a docs page, link to other docs pages by their URL slug, not by their .md file path:

See [Testing](/development/testing/) for the test tiers.

Not:

See [Testing](./testing.md) for the test tiers.

The slug-based form is portable across the rendered site, the GitHub view, and the IDE preview. It also survives file moves better than relative file paths. The trailing slash matches Starlight's URL convention — include it.

5. .md vs .mdx

Default to .md. The current site has only one .mdx file (quickstart.mdx) and that is because it imports an Astro component for an interactive element.

Choose .mdx only if you need to import and use a component inside the page. Plain markdown, code blocks, tables, callouts, and Mermaid diagrams all work fine in .md files — they do not require .mdx.

Mermaid diagrams

Mermaid is wired in via astro-mermaid (configured in astro.config.mjs) so a fenced ```mermaid block renders without any imports:

```mermaid
flowchart LR
    A[Operator] --> B[Omniglass]
    B --> C[Zabbix]
```

The site uses a dark Mermaid theme that auto-switches with the site theme.

Procedure summary

1. Pick the location. Choose the directory under docs/src/content/docs/ that matches the audience.
2. Create the file. Start with a frontmatter block (title, description) and write the body.
3. Register in the sidebar. Edit docs/astro.config.mjs and add your slug to the right section. Without this step the page is orphaned.
4. Verify links. Internal links use /path/to/page/ (slug + trailing slash), not ./page.md. Grep for any links in your new page and confirm the targets exist.
5. Build and preview locally (optional but recommended for non-trivial pages):

   cd docs
   npm install     # only if dependencies have changed
   npm run dev
   # open http://localhost:4321 and confirm the page renders, the sidebar entry appears, and internal links resolve
   

6. Verify with grep before committing:

   # Confirm the new file exists
   ls docs/src/content/docs/<your-section>/<your-page>.md
   
   # Confirm it's wired into the sidebar
   grep "<your-page>" docs/astro.config.mjs
   

   If either fails, the page is incomplete.

When this skill applies as part of feature work

Per the "Shipping a change" section in CLAUDE.md, any PR that adds or materially changes user-visible behavior must include docs updates in the same PR. That typically means one of:

• A new page in features/ for a new capability
• Edits to an existing features/ page when behavior changes
• Edits to architecture.md when the structure shifts
• Edits to operations/ when the runbook changes
• Edits to development/ when the contributor workflow changes

If you cannot identify which page would change, that is a signal the change is either internal-only (refactor — only tests required) or that the docs are missing a page that should be added now.