mirror of
https://github.com/vectorize-io/hindsight.git
synced 2026-09-14 19:31:49 +08:00
Nicolò Boschi
24abf373da
* 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/**).
51 lines
1.2 KiB
YAML
51 lines
1.2 KiB
YAML
name: Deploy Docs to GitHub Pages
|
|
|
|
on:
|
|
push:
|
|
branches: [main]
|
|
paths:
|
|
- 'hindsight-docs/**'
|
|
- '.github/workflows/deploy-docs.yml'
|
|
workflow_dispatch:
|
|
|
|
permissions:
|
|
contents: read
|
|
pages: write
|
|
id-token: write
|
|
|
|
concurrency:
|
|
group: pages
|
|
cancel-in-progress: false
|
|
|
|
jobs:
|
|
build:
|
|
runs-on: ubuntu-latest
|
|
steps:
|
|
- uses: actions/checkout@v6
|
|
with:
|
|
fetch-depth: 0 # fetch tags so check-released-integrations can see them
|
|
- uses: actions/setup-node@v6
|
|
with:
|
|
node-version: 20
|
|
cache: npm
|
|
cache-dependency-path: package-lock.json
|
|
- uses: astral-sh/setup-uv@v7
|
|
- run: npm ci --workspace=hindsight-docs
|
|
- run: uv run generate-llms-full
|
|
- run: npm run build --workspace=hindsight-docs
|
|
env:
|
|
UMAMI_URL: https://analytics.hindsight.vectorize.io
|
|
UMAMI_WEBSITE_ID: ${{ secrets.UMAMI_WEBSITE_ID }}
|
|
- uses: actions/upload-pages-artifact@v5
|
|
with:
|
|
path: hindsight-docs/build
|
|
deploy:
|
|
environment:
|
|
name: github-pages
|
|
url: ${{ steps.deployment.outputs.page_url }}
|
|
runs-on: ubuntu-latest
|
|
needs: build
|
|
steps:
|
|
- uses: actions/deploy-pages@v5
|
|
id: deployment
|