## Summary
- Re-apply the Algolia docs search migration after the previous PR was
merged and reverted.
- Keep the existing Fumadocs search UI while using Algolia API when
search keys are configured, with `/api/search` fallback for local
development and tests.
- Add a first-party Algolia index builder/sync script that creates
section-sized docs records from MDX/OpenAPI/toolkit/changelog content,
configures index relevance settings, and replaces index objects without
relying on Algolia Crawler.
- Add Algolia Insights view/click events and a terminal search relevance
test script.
- Clean search breadcrumbs so results show labels like `Toolkit` and
`Cookbook` instead of duplicated `toolkits > Gmail` formatting.
## Tests
- `cd docs && bun run types:check`
- `cd docs && bun run sync:search --dry-run`
- `cd docs && bunx eslint components/custom-search-dialog.tsx
lib/search-index.ts scripts/sync-algolia-search.ts
scripts/test-algolia-search.ts`
## Notes
- Live Algolia sync requires `ALGOLIA_ADMIN_API_KEY`.
- Live search relevance tests require `ALGOLIA_SEARCH_API_KEY` or
`NEXT_PUBLIC_ALGOLIA_SEARCH_API_KEY`.
## Summary
- Switch docs search dialog to Algolia when public Algolia env vars are
configured, with local `/api/search` fallback for development/tests
- Add a shared docs search index builder plus `bun run sync:search` to
publish records to Algolia
- Add a GitHub Actions workflow to dry-run and sync the Algolia index on
`next` docs changes when secrets are configured
- Document required Algolia env vars and sync command
## Tests
- `cd docs && bun run types:check`
- `cd docs && bun run sync:search --dry-run`
- `cd docs && bun test tests/static/`
- `cd docs && bunx eslint components/custom-search-dialog.tsx
lib/search-index.ts scripts/sync-algolia-search.ts`
- `cd docs && bun run build`
## Notes
- `bun run lint` still fails on existing unrelated repo-wide lint errors
in files outside this change (for example `app/global-error.tsx`,
`components/ask-ai-button.tsx`, `components/version-selector.tsx`). The
changed search files pass targeted ESLint.
- Production search requires `NEXT_PUBLIC_ALGOLIA_APP_ID`,
`NEXT_PUBLIC_ALGOLIA_SEARCH_API_KEY`, and optionally
`NEXT_PUBLIC_ALGOLIA_INDEX_NAME` (default `composio_docs`). Index
syncing requires `ALGOLIA_APP_ID`/`ALGOLIA_ADMIN_API_KEY` secrets.
generate-api-index.ts iterates every tag in spec.tags but used to `continue`
silently when a tag had zero operations in both v3.1 and v3.0 specs. After a
tag rename (e.g. Webhooks → Webhook Endpoints + Webhook Subscriptions), the
old tag dir still has an index.mdx from a prior run that points at the old
operationIds. The auto-update PR never includes a deletion for it, so the
phantom category lingers in the docs.
Replace the silent skip with an rmSync of any stale index.mdx for that tag
in both content/reference/api-reference/ and content/reference/v3/api-reference/.
Next auto-update run picks up the orphan and removes it.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
- Re-fetch OpenAPI spec which now includes v3.1 tool endpoints (hermes#8990)
- Update fetch-openapi.mjs to remove older API versions when a newer one
exists for the same endpoint path (e.g. v3 hidden when v3.1 available)
- Update generate-api-index.ts with the same version deduplication logic
- Regenerate API reference index pages
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Add a programmatic Meta Tools reference under Reference > Meta Tools,
powered by data fetched from the Tool Router API.
- Generator script fetches tool schemas from API, produces JSON + MDX
- CI auto-updates via docs-update-data.yml on Apollo deploys
- Individual tool pages show tags, input parameters, and response schemas
- .md endpoint renders full parameter details for LLM consumers
- Updated existing docs to include COMPOSIO_GET_TOOL_SCHEMAS
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Surface the `composioManagedAuthSchemes` field from the API on toolkit
pages so users know upfront whether they can use Composio's managed
OAuth or need to provide their own credentials.
- Add `composioManagedAuthSchemes` to Toolkit type and generate script
- Show badge next to Authentication Details heading (OAuth toolkits only)
- Include managed app status in markdown/LLM export and toolkits index
- Regenerate toolkits.json with managed auth data (114/980 toolkits)
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
The OpenAPI spec now uses `x-internal` as a tag on internal endpoints.
Instead of maintaining a hardcoded list of paths to ignore, filter any
operation tagged with `x-internal` automatically.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Replaces custom regex slugify with github-slugger to correctly handle
Unicode characters and duplicate heading suffixes.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
- Exclude scripts/preload.ts from tsconfig (Bun-only preload script)
- Add explicit PageOf type annotation to fix implicit any
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Use resolve() to normalize paths before deduplication so absolute paths
from Fumadocs sources match relative paths from glob.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
- Fix /toolkits/introduction → /toolkits in troubleshooting pages
- Remove broken relative links to source files in cookbooks
- Remove unnecessary "See Authenticating Users" link in errors.mdx
- Add dynamic toolkit slug validation from toolkits.json to link checker
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
The link checker was using the static referenceSource which only
includes MDX pages, missing all OpenAPI-generated API endpoint pages.
Switch to getReferenceSource() which merges both MDX and OpenAPI pages.
Eliminates 67 false positives from API reference index pages.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Moves FAQ markdown files from content/toolkit-faq/ into
content/toolkits/faq/ so they live alongside other toolkit content.
The link checker now scans all .md files under content/ generically
instead of special-casing the FAQ directory.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
data.toc is unavailable when running outside the Next.js runtime (via
bun scripts), so fragment links were all flagged as invalid. Parse
headings from raw markdown content instead, with a fallback chain:
data.toc -> getText('raw') -> readFile.
Also adds bunfig.toml with fumadocs-mdx bun preload plugin (recommended
by fumadocs docs for running scripts outside Next.js).
Reduces false positives from 134 errors to 90 real broken links.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
The populate keys in validate-links.ts were missing the (home) route
group prefix, so next-validate-link could never match them against the
actual file paths from app/(home)/. This meant zero URLs were registered
and all internal links passed validation silently.
Also adds toolkit FAQ markdown files to the link checker scope since
they are loaded outside of Fumadocs sources.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
The generate-toolkits script was missing the `toolkit_versions=latest`
query parameter when fetching tools and triggers. This caused MCP
toolkits (e.g. Granola) to show 0 tools, and older toolkits to
undercount (Gmail 23→40, Notion 28→46).
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Only keep slug, name, logo, category, toolCount, triggerCount in the
light JSON file used by the landing page client bundle. Reduces
toolkits-list.json from ~814KB to ~103KB. Full toolkits.json for
detail pages is unchanged.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
When both operationId and summary are undefined, use the same
method+path fallback for both to avoid empty/broken URLs.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
fumadocs-openapi uses operationId (e.g., getToolRouterSessionBySessionId)
not slugified summaries for page URLs.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Each endpoint now shows:
- HTTP method (GET, POST, PATCH, DELETE)
- Full path with parameters
- Linked title
- Full description from OpenAPI spec
Much more useful for LLMs to understand the API.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Instead of flat files like `auth-configs.mdx`, generate as
`auth-configs/index.mdx` so they become the index page for
each API folder, avoiding duplicate sidebar entries.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Create generate-api-index.ts script that reads OpenAPI spec
- Generate simple markdown index pages for each API tag
- Pages include tag description and links to all endpoints
- Run automatically as prebuild step
- Update overview page with links to index pages
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
The backend API spec contains anyOf/oneOf with many object variants
(e.g., connection_data with 68 variants, custom_connection_data with 10).
This caused fumadocs-openapi to render them as "object | object | object..."
This fix:
- Merges similar object schemas into a single object
- Combines enum values from all variants (e.g., authScheme now shows all 10 auth types)
- Recursively merges nested properties
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Replace the regex-based fix with a recursive solution that properly handles
all cases of invalid OpenAPI 3.0 schemas with "nullable: true" but no type.
The fix now:
- For additionalProperties: removes nullable (allows any type)
- For schemas with object examples: infers type: object
- For schemas with array examples: infers type: array
- For all other cases: defaults to type: object
This fixes 448 invalid schemas that caused fumadocs to crash when rendering
API reference pages like /tools/postToolsExecuteProxy.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
The backend API spec has ~394 instances of `additionalProperties: { nullable: true }`
which is invalid OpenAPI 3.0 - `nullable` requires a `type` field.
This causes fumadocs-openapi to error: "nullable cannot be used without type"
Fix: Transform these to `additionalProperties: {}` (any type allowed) during fetch.
Note: The proper fix is in the backend API spec generation.
See: https://swagger.io/docs/specification/v3_0/data-models/data-types/
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Add MCP to TypeScript SDK docs (remove from INTERNAL_CLASSES exclusion)
- Add MCP to Python SDK docs (add to EXPECTED_CLASSES and CLASS_MODULES)
- Fix acronym handling in TS generator (MCP -> mcp, not mCP)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Add MCP class documentation to TypeScript and Python SDK reference
- Move SDK doc generators from SDK dirs to docs/scripts/sdk-reference/
- Update CI workflow to run generators from docs/
- Fix acronym handling in TS generator (MCP -> mcp, not mCP)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Add /api/v3/labs/tool_router/session to IGNORED_PATHS
- Remove CookieAuth from securitySchemes
- Remove CookieAuth from all endpoint security arrays
- Mirrors filtering done in fern/apis/openapi-overrides.yml
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Move Tool Router content to main docs section:
- Authentication pages → /docs/authenticating-users/
- Guide pages → /docs/guides/
- Toolkit pages → /docs/toolkits/
- Add MCP and native tool examples to provider pages:
- openai-agents.mdx: Usage with Tools, Usage with MCP, Usage with direct tools
- vercel.mdx: Usage with Tools, Usage with MCP, Usage with direct tools
- anthropic.mdx: Usage with MCP, Usage with direct tools
- Remove Tool Router section entirely:
- Delete content/tool-router/ folder
- Delete app/(home)/tool-router/ routes
- Remove from navigation, search, and LLM routes
- Remove "Usage with direct MCP servers" sections (deprecated approach)
- Update all internal links from /tool-router/* to /docs/*
- Add redirects for old Tool Router URLs
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Add AuthDetailsSection component with accordion and TypeTable
- Update generate-toolkits script to fetch auth config details from API
- Add AuthConfigDetail and AuthConfigField types
- Display both auth_config_creation and connected_account_initiation fields
- Remove authentication guide button from toolkit detail
- Remove background from inline code in global CSS
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Generate separate toolkits-list.json without tools/triggers arrays
- Landing page imports light file (323KB vs 5.1MB)
- Add ToolkitSummary type for landing page usage
- Full toolkits.json still used for detail pages via filesystem read
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Rahul Tarak