Nicolò Boschi 24abf373da docs(integrations): single source of truth (integrations.json) for gallery + sidebars (#2048) ...

* docs(integrations): single source of truth for sidebar + guardrails

Make src/data/integrations.json the single source for the Integrations
sidebar across every docs version, and add build-time guardrails so it
can't drift.

- Inject the Integrations sidebar category at render time from
  integrations.json via a DocRoot/Layout/Sidebar swizzle. Every docs
  version (current + frozen 0.3-0.7) now shows the same list, and adding
  one JSON entry is all it takes - no per-version sidebar edits. The
  sidebar files keep only a positional placeholder category (a link to
  the gallery), which the swizzle replaces.
- check-integrations.mjs, wired into `npm run build`:
  - forward: fail if a JSON entry has no docs-integrations/<slug> page
    (the injected sidebar isn't covered by Docusaurus link-checking).
  - reverse: fail if a released integration tag is missing from the JSON
    (skips gracefully without tags; excludes private cloudflare-oauth-proxy).
- Add the released-but-undocumented integrations to the JSON so the
  gallery + sidebar show them: claude-agent-sdk and superagent (with new
  doc pages) and paperclip.
- CI: fetch tags (fetch-depth: 0) in the docs build jobs so the reverse
  check can see them.

One name + one icon per integration come straight from the JSON; display
order is the JSON array order (manual, most-interesting-first).

* docs(code-review): require integrations.json entry + doc page for integrations

Add a review rule: every added/released integration must have an entry in
hindsight-docs/src/data/integrations.json (single source of truth for the
gallery + sidebar) and a docs-integrations/<slug> page, enforced by
check-integrations.mjs. Also note the changelog generator keeps its own
INTEGRATIONS list that must be updated for releases.

* docs(integrations): sidebar on (unversioned) integration pages + alphabetical order

- Give the integration doc pages their own sidebar without versioning them:
  point the unversioned `integrations` plugin at sidebars-integrations.ts,
  generated from integrations.json (doc items so each page associates with the
  sidebar and renders it). Previously these pages had sidebarPath: false (no
  sidebar at all).
- Sort integrations alphabetically by name in all three surfaces — the
  Integrations Hub gallery, the main docs sidebar, and the new integration-page
  sidebar — via a shared src/lib/integrations.ts helper (gallery + swizzle) and
  an inline sort in the config-loaded integration sidebar. JSON array order is
  no longer significant for display.
- The swizzle now only fills the main-docs placeholder category, leaving the
  generated integration-page sidebar untouched.

* docs(integrations): replace placeholder/wrong icons with official brand icons

Fetch real brand icons from each integration's official site (apple-touch-icon
/ high-res favicon) and point integrations.json at them, replacing
self-generated, generic, or reused placeholders:

- New brand icons for claude-agent-sdk, superagent, paperclip, codex, grok-build,
  ai-sdk, chat, local-mcp, openclaw, langgraph, autogen, opencode, n8n, pipecat,
  smolagents, dify, strands, outsystems, pydantic-ai, and refreshed many others
  (litellm, crewai, perplexity, llamaindex, vapi, flowise, hindclaw, agno,
  hermes, agentcore, google-adk, openai-agents, roo-code, skills, claude-code).
- claude-agent-sdk now uses the Claude/Anthropic brand (was reused claude-code
  icon); context-forge uses the MCP logo (it's an MCP gateway); superagent uses
  its pyramid logo (was generic package icon); paperclip its paperclip mark.
- Kept the existing real marks for nemoclaw (NVIDIA NeMo) and right-agent — no
  official brand favicon exists for those, and the auto-fetched candidates were
  wrong (a letter favicon / the repo author's avatar).
- Removed 7 now-orphaned icon files.

* ci(docs): add explicit integrations check step to build-docs

Run scripts/check-integrations.mjs as a named, fail-fast step before the docs
build (the build runs it too, but this surfaces it clearly and fails before the
slow build). Pure Node, no npm install; uses the tags already fetched via
fetch-depth: 0.

* ci(docs): trigger build-docs (integrations check) on integration changes

Add hindsight-integrations/** to the docs path filter so the integrations
single-source check runs on integration-only PRs (which can add/rename an
integration without touching hindsight-docs/**).

2026-06-08 15:23:17 +02:00

1.5 KiB

180x180px

Raw Permalink History