Contributing to OAT Docs

Documentation should ship with the code it explains. This page covers the core docs contract and local workflow; the syntax reference now lives in Markdown Features.

Navigation contract

• Every documentation directory must contain an index.md.
• Each index.md must include a ## Contents section.
• The ## Contents section is the machine-readable local map for sibling pages and child directories.
• Use .md-suffixed relative links in ## Contents: [Page](page.md) for leaf pages and [Section](subdir/index.md) for child directories.
• Fumadocs and MkDocs share this authored contract, but they regenerate different artifacts.

Local workflow

1. Start the dev server from the repo root:

   pnpm dev:docs

2. Build the docs site locally (verifies the static export succeeds):

   pnpm build:docs

3. Check rendered links against a local or deployed docs host:

   pnpm docs:check-links
   # or target a local docs server explicitly
   pnpm docs:check-links --url http://127.0.0.1:3000/open-agent-toolkit/

4. Run Markdown linting:

   pnpm --filter oat-docs docs:lint

5. Run Markdown formatting:

   pnpm --filter oat-docs docs:format

Authoring Expectations

• Keep docs aligned with the current repo behavior and current command surface.

• Give each Markdown or MDX page exactly one document H1. pnpm docs:validate reports the file and count when a page has zero or multiple H1s. ATX and Setext headings count, including headings inside blockquotes or lists; frontmatter and fenced code do not.

• Prefer cross-links over duplicated conceptual content.

• Use oat-docs-authoring for targeted OAT/Fumadocs docs edits; it delegates universal page-quality guidance to authoring-docs and keeps local navigation, generated-index, and validation expectations in scope.

• When you add, remove, or rename docs pages in this Fumadocs app, refresh the generated Fumadocs root index. It is a generated file-tree manifest that should be checked against authored docs/**/index.md maps, not hand-edited:

  pnpm -w run cli:source -- docs generate-index --docs-dir apps/oat-docs/docs --output apps/oat-docs/index.md

• Then refresh the sidebar navigation. oat docs nav sync rewrites the committed meta.json files from the ## Contents maps and reports any page no map lists; list the page in its directory's ## Contents rather than editing meta.json. The build runs the read-only --check form and fails while the navigation is stale or a page is unlisted:

  pnpm -w run cli:source -- docs nav sync --target-dir apps/oat-docs

• In MkDocs apps, the same oat docs nav sync command refreshes the nav: block in mkdocs.yml instead.

• Use Markdown Features for supported syntax and examples.

Agent guidance

• Treat index.md plus its ## Contents section as the local discovery source of truth.
• Prefer linking to source files and commands explicitly when documenting behavior.
• Regenerate or freshness-check the docs surface index after adding, removing, renaming, or reordering pages.

Related Guides

• Markdown Features
• Docs Tooling

If You Are Trying To...

• use docs commands or bootstrap a docs app, start with Docs Tooling
• follow the authoring contract for index.md and navigation, stay on this page and then read Docs Index Contract
• understand supported markdown patterns, use Markdown Features