Skip to main content

Working on the documentation

Documentation is stored as Markdown/MDX under docs/. Docusaurus configuration, theme files, generated output, and npm dependencies live under docs/site/. Do not copy product pages into docs/site.

Run locally​

cd docs/site
npm install
npm start

Docusaurus starts its development server at http://localhost:3000 by default. For a CI-equivalent check:

cd docs/site
npm ci
npm run architecture:validate
npm run build

The production build regenerates the interactive LikeC4 Web Component and fails on an invalid LikeC4 model, unresolved internal links, or invalid Mermaid diagrams. Generated folders (node_modules, .docusaurus, static/generated, and build) are ignored by Git.

Authoring rules​

  • Link to the source of truth instead of copying a full route/schema or contract.
  • Use Mermaid only when a relationship or execution sequence is clearer as a diagram.
  • Follow the architecture documentation conventions for DAT, C4, LikeC4, Mermaid, and ADR ownership. Structural C4 views come from the single shared LikeC4 model; Mermaid remains appropriate for dynamic behavior.
  • Use the architecture documentation reconciliation workflow for transverse reviews; directly affected documentation still changes with the owning feature or technical work.
  • Mark unavailable behavior as Planned, Experimental, Preview, or Not implemented yet.
  • Keep conceptual pages independent of C# class names; put implementation details in Architecture or Reference.
  • Update the sidebar when adding a new top-level page that should be discoverable.

Versioning​

The current documentation line is Next. Do not create Docusaurus snapshots for 0.x releases. Versioned major documentation will be enabled after a stable 1.0 release; see the versioning strategy.

Publication​

The site is configured for https://docs.agentstration.io. Pull requests validate the production build without publishing it. A push or manual workflow run from main publishes the same build through GitHub Pages after Pages is enabled for GitHub Actions and the custom-domain DNS is configured. It requires no repository secret beyond GitHub's standard Pages token.

Last updated on