Document Code

Guide for adding and updating Syncpack's documentation website.

Quick Decision

What are you documenting?

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

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

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