document-code

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

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)

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:

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:

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