// Add and update the documentation website for Syncpack. Use when making user-facing changes to the codebase.
| name | document-code |
| description | Add and update the documentation website for Syncpack. Use when making user-facing changes to the codebase. |
Guide for adding and updating Syncpack's documentation website.
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 |
cli.rs for commands, rcfile.rs for config, instance_state.rs for status codesglobalReferenceLinks in astro.config.mjspnpm run dev from site/(IDENTIFIER) links resolve| 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 |
cd site
pnpm run dev # Start at http://localhost:4321/syncpack
pnpm run build # Verify build succeeds
site/src/site/src/content/docs/**/*.mdxsite/src/_partials/**/*.mdxsite/src/components/*.astroEach command has a corresponding file at site/src/content/docs/command/[command].mdx.
## Examples — Single bash code block with commented examples## Options — Start with <QuoteFilters /> callout, then ### for each option alphabetically (--help last)Many commands share options. Define reusable partials at site/src/_partials/option/*.mdx:
import ConfigOption from "@partials/option/config.mdx";
<ConfigOption command="update" />
Each config property has a file at site/src/content/docs/config/[property].mdx.
## Default Value — Code block showing default (when applicable)## Examples — Code blocks with commented examplesEach variant has its own page:
site/src/content/docs/version-groups/*.mdxsite/src/content/docs/semver-groups/*.mdx## Examples — Code block per example, capture novel use cases## Configuration — ### for each config propertyEach 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).
site/src/faq/[id].mdx/syncpack/faq via site/src/pages/faq.astrosite/src/pages/faq/[id].astroUse named identifiers in markdown links:
When using the [update](COMMAND_UPDATE) command
Define identifiers in globalReferenceLinks function in site/astro.config.mjs.
Generated by site/src/pages/og/[...path].png.ts using Satori.
| 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 |
Before submitting documentation:
astro.config.mjspnpm run build)Rust code style and conventions for Syncpack. Use when writing or modifying Rust code. Covers functional patterns, imports, naming, and quality standards.
Write tests for Syncpack using the TestBuilder pattern. Use when adding tests for commands, validation logic, or any new functionality. Covers TestBuilder API, assertion patterns, and common test scenarios.
Run coverage, inspect results, and identify missing test scenarios for a given source file. Use when analysing test coverage or finding untested branches.
Add new features to Syncpack including commands and validation logic. Use when implementing new CLI commands, adding InstanceState variants, or extending version group behaviour.
Debug and fix bugs in Syncpack using scientific debugging methodology. Use when a test is failing, unexpected behaviour occurs, or investigating issues. Covers hypothesis-driven debugging and TDD-based fixes.
Put the answer first, then context and details follow. Use when writing documentation, tutorials, error messages, or any communication where readers need to decide quickly if something is relevant to them.