Skip to content
Formly Contract

Contributing to docs

The docs app is @formly-contract/docs under apps/docs/. It uses Astro Starlight and builds to static files.

Local workflow

Section titled “Local workflow”

From the repository root:

Terminal window
pnpm install --frozen-lockfile
pnpm docs:dev

Before handoff:

Terminal window
pnpm check:docs

That command checks Markdown links, heading fragments, repository-local GitHub links, raw site routes, and trailing whitespace across the repository, then performs a production Astro build. The Starlight build also creates the Pagefind search index.

Use pnpm docs:preview to inspect the production output locally.

Find the owning documentation

Section titled “Find the owning documentation”
  • The root README.md is the repository landing page and shortest product overview.
  • Group and package READMEs explain local purpose, boundaries, and focused contributor commands where someone encounters the code.
  • The root docs/ guide distinguishes canonical specifications and ADRs from research, plans, and historical handoffs.
  • This Starlight site is the concise user journey and current reference layer.

When a package or fixture becomes confusing without prior repository context, improve the nearest README and link it from the relevant group guide. Avoid forcing users to read a planning document to understand current behavior.

Deployment workflow

Section titled “Deployment workflow”

The Docs Site workflow publishes the static build to GitHub Pages after relevant changes reach main. It uses GitHub’s github-pages environment and artifact deployment rather than committing generated output to a branch.

The production build receives its canonical origin, repository subpath, edit repository, and default branch from GitHub context. Maintainers can run the workflow manually from the Actions page. See the docs app README for local reproduction and custom-domain overrides.

Where content belongs

Section titled “Where content belongs”
  • src/content/docs/start/ — evaluation, installation, adoption, status
  • src/content/docs/concepts/ — stable mental models and boundaries
  • src/content/docs/reference/ — current package, config, CLI, and artifact surfaces
  • src/content/docs/resources/ — troubleshooting, roadmap navigation, and contributor guidance
  • tokens.css and src/styles/custom.css — the site design system and Starlight theme overrides

Add a sidebar entry in astro.config.mjs for every navigable page.

Source-of-truth rule

Section titled “Source-of-truth rule”

Existing root docs and ADRs remain canonical. A site page may:

  • orient a newcomer;
  • assemble a workflow across several canonical sources;
  • link to maintained fixture or package code; and
  • clearly label current, consumer-owned, or planned capability.

Do not paste an entire specification into the site or silently restate future research as shipped behavior. Add a “Canonical source” aside on pages that summarize a contract. If behavior changes, update the canonical doc and the site’s orientation page in the same change.

Review checklist

Section titled “Review checklist”
  • Commands and package names exist on the current branch.
  • Examples parse generated JSON before trusting it.
  • Planned capabilities are visually and verbally labelled.
  • No customer or workplace data appears in examples or screenshots.
  • Links resolve and pnpm check:docs passes.
  • Root-relative links do not bypass the configured GitHub Pages base path.
  • Theme assets do not add an unreviewed third-party request.
  • The page remains usable at 320, 375, 414, and 768 CSS pixels.