Document Code

Documents

document-code

Document Code is an Agent Skill for documents published in the JamieMason/syncpack repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

Add and update the documentation website for Syncpack. Use when making user-facing changes to the codebase.

View on GitHub ↗

QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

Open your project in Codex.
Copy and paste the prompt below.
Review files and risks before approving any action.

Prompt to paste

Inspect the Agent Skill at https://github.com/JamieMason/syncpack/blob/HEAD/.claude/skills/document-code/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/document-code, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

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

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:

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:

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