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

Read source —
```
cli.rs
```
for commands,
```
rcfile.rs
```
for config,
```
instance_state.rs
```
for status codes
Create/update MDX — Match existing structure exactly
Add link identifier — Update
```
globalReferenceLinks
```
in
```
astro.config.mjs
```
Test locally —
```
pnpm run dev
```
from
```
site/
```
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 on top of Astro
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)

Description of the command's purpose from end user perspective
```
## Examples
```
— Single bash code block with commented examples
```
## 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

Description of the config's purpose from end user perspective
```
## Default Value
```
— Code block showing default (when applicable)
```
## 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

Description of the group's purpose from end user perspective
```
## Examples
```
— Code block per example, capture novel use cases
```
## 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.

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

document-code

NPX Install

Tags

SKILL.md Content

Document Code

Quick Decision

Workflow

Source to Docs Mapping

Local Development

Site Overview

Command Documentation

Required Structure (in order)

Shared Option Partials

Config Documentation

Required Structure

Version Groups and Semver Groups

Required Structure

Status Code Documentation

FAQ Documentation

Linking Between Pages

Open Graph Images

Troubleshooting

Checklist