| 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
- 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
pnpm run build
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/*.mdxsite/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:
