Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
Mirrored from https://github.com/Camo67/composio.git
Synced Nov 21, 03:37 UTC
Change the Composio docs
Use a pull request for a specific docs fix. For Composio team members, use a Developer Marketing issue in Linear with the Docs label when the work needs investigation, coordination, or a larger content plan. Link the issue and its source context in the PR so the reviewer can check the original problem.
Composio team members and designated maintainers can open PRs directly. External contributors need an existing, open GitHub issue. For large external changes, get maintainer agreement on the approach before implementation. Read the root Contribution Policy, including the third-party links policy. Authoritative technical references needed to use or contribute to Composio are allowed. For a partnership request, contact us through composio.dev/contact.
For a runtime bug, include a reproducible example and involve the SDK or platform owner. A docs change cannot establish behavior that the product does not support.
Choose the source
| Change | Edit |
|---|---|
| A guide or explanation | content/docs/ |
| An application example | content/examples/ |
| A release note | content/changelog/ and the changelog guide |
| Sidebar order | The nearest meta.json; product navigation also uses lib/home-navigation.ts |
| Page layout or an MDX component | app/, components/, or lib/ |
| API or SDK reference, toolkit data | The owning source or generator; do not patch generated output by hand |
| A public support answer | The knowledge publication workflow |
Read AGENTS.md for repository rules. For typed code examples, read the Twoslash guide. Check the docs decisions before changing an established architecture or content pipeline.
Prepare a change
- Find the existing page and search for related issues or PRs. Extend the canonical page when it already covers the topic.
- Branch from the latest
origin/next. Target the PR atnext. - Reproduce the problem or write down the reader's task and the expected result. Include the affected URL and source evidence.
- Verify API behavior against SDK code, the current API schema, or a reproducible request. For an unresolved product or architecture question, get confirmation from the responsible team before documenting a recommendation.
- Make the smallest complete change. Use relative site links, add new pages to navigation, and preserve the Markdown representation of task-critical content.
From the repository root, install the pinned toolchain with mise install. Then run the docs commands from docs/:
bun install
bun run dev
Open the changed page at http://localhost:3000. Inspect its layout, links, and code examples. Also inspect its .md URL if the change contains commands, warnings, component content, or navigation.
Validate the PR
Run these checks from docs/:
bun run test
bun run lint
bun run lint:links
bun run types:check
bun run check:kb-semantic --allow-stale
bun run build
To check the built site's endpoints, run bun run start in one terminal and bun run test:integration in another. The integration tests use http://localhost:3000 by default. Set TEST_BASE_URL if your server uses another address.
The semantic artifact covers both regular docs and KB articles, so edits to either can make it stale. PR checks use --allow-stale to warn about freshness while still rejecting missing or corrupt artifacts. Search falls back to keyword results until the artifact is rebuilt.
The Docs - Rebuild KB Semantic Artifact workflow can rebuild it for eligible same-repository PRs after Docs - Tests runs. The scheduled Docs - Repair KB Semantic Artifact workflow also proposes repairs for anything that reached next stale. If you rebuild locally with bun run build:kb-semantic, use an authorized OPENAI_API_KEY: the generator sends the indexed docs content to the embeddings service. Run bun run check:kb-semantic without --allow-stale to verify a rebuild. Never edit embedding values or content hashes by hand.
Agent-readable representations
Request a page with Accept: text/markdown (or text/plain), append .md or .mdx, or use its /llms.mdx/ route. HTML pages with a Markdown representation advertise it with <link rel="alternate" type="text/markdown">. Negotiated responses include Vary: Accept so caches distinguish HTML from Markdown.
Next.js 16.3.8 replaces middleware's Vary header in its Node HTML response template. The docs package carries a two-line dependency patch that appends Next's cache dimensions instead. The upstream regression is tracked in Next.js issue #85852. Keep the live negotiation test when upgrading Next. Remove the patch once an unpatched production build passes that test.
Per-page Markdown starts with YAML front matter. For example, /reference/authenticating-to-composio.md identifies its HTML and Markdown URLs independently of the URL you requested:
---
canonical_url: "https://docs.composio.dev/reference/authenticating-to-composio"
markdown_url: "https://docs.composio.dev/reference/authenticating-to-composio.md"
product: "platform"
version: "3.1"
last_updated: null
---
product uses the URL-based docs product, platform or for-you, without reading your product cookie. Shared pages default to platform. version is the documented REST version (3.1 or legacy 3.0), or null for pages that don't document a REST version. It isn't an SDK package version. last_updated is a UTC ISO 8601 timestamp, or null when freshness can't be established. The example uses null, not an invented update time.
The sitemap's lastmod and Markdown's last_updated use the same build-generated source freshness data. They never use build time or filesystem modification time. Missing pages return Markdown discovery and search links with HTTP 404; error responses don't claim a content update time.
The prebuild, predev, and type-check steps generate .generated/content-freshness.json from each page's backing files. Deployed routes read that artifact without Git. Freshness is limited to authored pages and dated changelog entries. Generated API and toolkit pages, KB guides, and browse pages return last_updated: null and omit sitemap lastmod. Their shared specifications, catalogs, or manifests can change without changing the page. Add timestamps for these pages only when changes can be attributed to each page.
You can declare last_updated: YYYY-MM-DD or a timezone-qualified ISO timestamp in authored front matter. A date-only value means midnight UTC; an invalid value fails generation. Otherwise, freshness uses the source file's last Git commit. Dated changelog pages use the latest known update across entries for that date. A source commit records an edit, not a review or a guarantee that the guidance is current.
Docs CI fetches full history. The Vercel build command fetches missing history before running bun run build. If that fetch fails, the deployment fails instead of silently publishing incomplete freshness. For other CI/CD builds, provide full history (fetch-depth: 0 with actions/checkout) for complete freshness coverage. A shallow checkout retains dates for changes proven within its history but omits unknown shallow-boundary dates. Source archives without history also omit unknown dates. Neither case substitutes the checkout or build time.
Request review and verify publication
Describe the reader's problem, the resulting behavior, and the checks you ran. Include screenshots for visual changes and list checks that failed or could not run. Link the Linear issue when one exists. Docs-only changes do not need a Changeset.
Request review from @jkomyno, the designated PR reviewer, and involve someone who can verify the changed topic. Involve the product owner for behavior, security, tenancy, or contractual claims. Follow the repository's review and merge requirements; a passing build alone does not verify those claims.
After merge, confirm the deployment succeeds and inspect the live page and .md representation. Check Docs - Sync Algolia Search for changes that affect retrieval. Update the linked issue with the published result once the change is verified. If the live result is wrong, report the affected URL and commit so the next fix starts from evidence.