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.

• 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

• In MkDocs apps, use oat docs nav sync to refresh mkdocs.yml instead. Do not use MkDocs nav sync as the Fumadocs regeneration step.

• 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