document-code

---
name: document-code
description: Add and update the documentation website for Syncpack. Use when making user-facing changes to the codebase.
---

# Document Code

Guide for adding and updating Syncpack's documentation website.

## Quick Decision

What are you documenting?

| Adding/Updating...    | Location                                         |
| --------------------- | ------------------------------------------------ |
| Command docs          | `site/src/content/docs/command/[cmd].mdx`        |
| Config property       | `site/src/content/docs/config/[prop].mdx`        |
| Version group variant | `site/src/content/docs/version-groups/[var].mdx` |
| Semver group variant  | `site/src/content/docs/semver-groups/[var].mdx`  |
| Status code           | `site/src/content/docs/status/[code].mdx`        |
| FAQ                   | `site/src/faq/[id].mdx`                          |
| Shared option partial | `site/src/_partials/option/[opt].mdx`            |
| Reusable component    | `site/src/components/[name].astro`               |

## Workflow

1. **Read source** — `cli.rs` for commands, `rcfile.rs` for config, `instance_state.rs` for status codes
2. **Create/update MDX** — Match existing structure exactly
3. **Add link identifier** — Update `globalReferenceLinks` in `astro.config.mjs`
4. **Test locally** — `pnpm run dev` from `site/`
5. **Verify links** — Check all `(IDENTIFIER)` links resolve

## Source to Docs Mapping

| Source                  | Documentation                                         |
| ----------------------- | ----------------------------------------------------- |
| `src/cli.rs` Subcommand | `site/src/content/docs/command/*.mdx`                 |
| `src/rcfile.rs` Rcfile  | `site/src/content/docs/config/*.mdx`                  |
| `src/instance_state.rs` | `site/src/content/docs/status/*.mdx`                  |
| `src/specifier.rs`      | `site/src/content/docs/reference/specifier-types.mdx` |

## Local Development

```bash
cd site
pnpm run dev          # Start at http://localhost:4321/syncpack
pnpm run build        # Verify build succeeds
```

## Site Overview

- Source located at `site/src/`
- Built with [Starlight](https://starlight.astro.build/) on top of [Astro](https://astro.build/)
- Content at `site/src/content/docs/**/*.mdx`
- Reusable partials at `site/src/_partials/**/*.mdx`
- Reusable components at `site/src/components/*.astro`

## Command Documentation

Each command has a corresponding file at `site/src/content/docs/command/[command].mdx`.

### Required Structure (in order)

1. Description of the command's purpose from end user perspective
2. `## Examples` — Single bash code block with commented examples
3. `## Options` — Start with `<QuoteFilters />` callout, then `###` for each option alphabetically (`--help` last)

### Shared Option Partials

Many commands share options. Define reusable partials at `site/src/_partials/option/*.mdx`:

```mdx
import ConfigOption from "@partials/option/config.mdx";

<ConfigOption command="update" />
```

## Config Documentation

Each config property has a file at `site/src/content/docs/config/[property].mdx`.

### Required Structure

1. Description of the config's purpose from end user perspective
2. `## Default Value` — Code block showing default (when applicable)
3. `## Examples` — Code blocks with commented examples

### Version Groups and Semver Groups

Each variant has its own page:

- `site/src/content/docs/version-groups/*.mdx`
- `site/src/content/docs/semver-groups/*.mdx`

#### Required Structure

1. Description of the group's purpose from end user perspective
2. `## Examples` — Code block per example, capture novel use cases
3. `## Configuration` — `###` for each config property

## Status Code Documentation

Each status code has a file at `site/src/content/docs/status/[code].mdx`.

Reference page at `site/src/content/docs/reference/status-codes.mdx` explains the `InstanceState` enum and its nested enums (`ValidInstance`, `InvalidInstance`, `SuspectInstance`).

## FAQ Documentation

- Create FAQ files at `site/src/faq/[id].mdx`
- Listed at `/syncpack/faq` via `site/src/pages/faq.astro`
- Individual pages via `site/src/pages/faq/[id].astro`

## Linking Between Pages

Use named identifiers in markdown links:

```mdx
When using the [update](COMMAND_UPDATE) command
```

Define identifiers in `globalReferenceLinks` function in `site/astro.config.mjs`.

## Open Graph Images

Generated by `site/src/pages/og/[...path].png.ts` using [Satori](https://github.com/vercel/satori).

## Troubleshooting

| Problem                       | Fix                                           |
| ----------------------------- | --------------------------------------------- |
| Link not working              | Check identifier in `globalReferenceLinks`    |
| Partial not rendering         | Verify import path uses `@partials/` alias    |
| OG image broken               | Check `og/[...path].png.ts` handles new route |
| Build fails                   | Run `pnpm run build` locally to see error     |
| Page not appearing in sidebar | Check frontmatter and Starlight config        |

## Checklist

Before submitting documentation:

- [ ] Structure matches existing pages of same type
- [ ] Link identifier added to `astro.config.mjs`
- [ ] Local dev server renders correctly
- [ ] Build succeeds (`pnpm run build`)
- [ ] All internal links resolve

More agent context in JamieMason/syncpack

10 other files this repository gives its agents.