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 ```bash 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](https://starlight.astro.build/) on top of [Astro](https://astro.build/) - 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`: ```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: ```mdx 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](https://github.com/vercel/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