Add Mintlify documentation site

- Add docs/ folder with Mintlify configuration
- Add generate_mintlify_agents.py to generate agent cards from registry
- Update update-versions.yml to regenerate docs on version updates
- Update CLAUDE.md with documentation site instructions

Author: ignatov

.github/workflows/generate_mintlify_agents.py

@@ -0,0 +1,126 @@
+#!/usr/bin/env python3
+from __future__ import annotations
+
+import json
+from pathlib import Path
+import re
+
+ROOT = Path(__file__).resolve().parents[2]
+DOCS_DIR = ROOT / "docs"
+TEMPLATE_PATH = DOCS_DIR / "_index.mdx"
+OUTPUT_PATH = DOCS_DIR / "index.mdx"
+PLACEHOLDER = "$$AGENTS_CARDS$$"
+
+
+def _escape_html(text: str) -> str:
+    return (
+        text.replace("&", "&")
+        .replace("<", "&lt;")
+        .replace(">", "&gt;")
+        .replace('"', "&quot;")
+        .replace("'", "&#39;")
+    )
+
+
+def _escape_text(text: str) -> str:
+    return _escape_html(text).replace("\n", " ")
+
+
+def _sanitize_svg(svg: str) -> str:
+    svg = svg.strip()
+    svg = re.sub(r'\s(width|height)="[^"]*"', "", svg)
+    svg = re.sub(r'\sclass="[^"]*"', "", svg)
+    svg = re.sub(
+        r"<svg\b",
+        (
+            '<svg width="20" height="20" '
+            'className="agent-icon" '
+            'aria-hidden="true" focusable="false"'
+        ),
+        svg,
+        count=1,
+    )
+    replacements = {
+        "fill-rule": "fillRule",
+        "clip-rule": "clipRule",
+        "clip-path": "clipPath",
+        "stroke-width": "strokeWidth",
+        "stroke-linecap": "strokeLinecap",
+        "stroke-linejoin": "strokeLinejoin",
+        "stroke-miterlimit": "strokeMiterlimit",
+        "stroke-dasharray": "strokeDasharray",
+        "stroke-dashoffset": "strokeDashoffset",
+        "stroke-opacity": "strokeOpacity",
+        "fill-opacity": "fillOpacity",
+        "stop-color": "stopColor",
+        "stop-opacity": "stopOpacity",
+        "vector-effect": "vectorEffect",
+    }
+    for old, new in replacements.items():
+        svg = svg.replace(f"{old}=", f"{new}=")
+    return svg
+
+
+def _load_icon_svg(agent: dict) -> str:
+    icon_src = agent["_dir"] / "icon.svg"
+    if not icon_src.exists():
+        return ""
+    return _sanitize_svg(icon_src.read_text())
+
+
+def _load_agents() -> list[dict]:
+    agents: list[dict] = []
+    for entry in sorted(ROOT.iterdir()):
+        if not entry.is_dir():
+            continue
+        agent_file = entry / "agent.json"
+        if not agent_file.exists():
+            continue
+        data = json.loads(agent_file.read_text())
+        data["_dir"] = entry
+        agents.append(data)
+    agents.sort(key=lambda agent: agent.get("name", "").lower())
+    return agents
+
+
+def _render_agent_cards(agents: list[dict]) -> str:
+    lines: list[str] = ["<Columns cols={2}>"]
+
+    for agent in agents:
+        agent_id = agent.get("id", "-")
+        name = agent.get("name", agent_id)
+        description = _escape_text(agent.get("description", "-"))
+        version = _escape_text(agent.get("version", "-"))
+        repository = agent.get("repository", "")
+        icon_svg = _load_icon_svg(agent)
+
+        lines.append("  <Card")
+        lines.append(f'    title="{_escape_html(name)}"')
+        if icon_svg:
+            lines.append("    icon={")
+            for line in icon_svg.splitlines():
+                lines.append(f"      {line}")
+            lines.append("    }")
+        if repository:
+            lines.append(f'    href="{_escape_html(repository)}"')
+            lines.append('    arrow="true"')
+        lines.append("  >")
+        lines.append(f"    {description}")
+        version_text = version if version not in ("", "-") else "version unknown"
+        lines.append(f"    <p><code>{_escape_text(version_text)}</code></p>")
+        lines.append("  </Card>")
+
+    lines.append("</Columns>")
+    return "\n".join(lines)
+
+
+def main() -> None:
+    agents = _load_agents()
+    template = TEMPLATE_PATH.read_text()
+    cards = _render_agent_cards(agents)
+    output = template.replace(PLACEHOLDER, cards)
+    OUTPUT_PATH.write_text(output)
+
+
+if __name__ == "__main__":
+    main()

.github/workflows/update-versions.yml

@@ -143,6 +143,9 @@ jobs:
           pip install jsonschema
           SKIP_URL_VALIDATION=1 python .github/workflows/build_registry.py
 
+      - name: Generate docs
+        run: python .github/workflows/generate_mintlify_agents.py
+
       - name: Generate commit message
         id: commit_msg
         run: |

CLAUDE.md

@@ -110,3 +110,47 @@ Using `currentColor` enables icons to adapt to different themes (light/dark mode
 **Invalid patterns:**
 - Hardcoded colors: `fill="#FF5500"`, `fill="red"`, `stroke="rgb(0,0,0)"`
 - Missing currentColor: `fill` or `stroke` without `currentColor`
+
+## Documentation Site
+
+The registry has a documentation site built with [Mintlify](https://mintlify.com/) in the `docs/` folder.
+
+### Structure
+
+```
+docs/
+├── docs.json          # Mintlify configuration
+├── _index.mdx         # Template for index page (contains $$AGENTS_CARDS$$ placeholder)
+├── index.mdx          # Generated index page with agent cards
+├── registry.mdx       # Registry format documentation
+└── logo/              # Logo assets
+```
+
+### Commands
+
+```bash
+# Generate docs (regenerates index.mdx from template)
+uv run .github/workflows/generate_mintlify_agents.py
+
+# Run local dev server
+cd docs && npx mintlify dev --port 3000
+```
+
+### How It Works
+
+1. `_index.mdx` is a template containing `$$AGENTS_CARDS$$` placeholder
+2. `generate_mintlify_agents.py` reads all `agent.json` files from the registry
+3. Generates `<Card>` components for each agent with name, description, version, and icon
+4. Icons are inlined as sanitized SVG (converted to JSX-compatible attributes)
+5. Replaces placeholder and writes to `index.mdx`
+
+### Automation
+
+Docs are automatically regenerated when agent versions are updated:
+- The `update-versions.yml` workflow runs `generate_mintlify_agents.py` after applying updates
+- Changes to `docs/index.mdx` are committed along with version updates
+
+### Adding New Pages
+
+1. Create new `.mdx` file in `docs/`
+2. Add the page name (without extension) to `docs.json` navigation

docs/_index.mdx

@@ -0,0 +1,23 @@
+---
+title: Official ACP Registry
+description: Discover Agent Client Protocol agents
+---
+
+<style>{`
+.agents-cards img,
+.agents-cards svg {
+  width: 20px;
+  height: 20px;
+  color: currentColor;
+}
+.agents-cards {
+  color: #111827;
+}
+.dark .agents-cards {
+  color: #f9fafb;
+}
+`}</style>
+
+<div className="agents-cards">
+$$AGENTS_CARDS$$
+</div>

docs/docs.json

@@ -0,0 +1,78 @@
+{
+  "$schema": "https://mintlify.com/docs.json",
+  "theme": "maple",
+  "name": "Agent Client Protocol Registry",
+  "description": "Official registry of authenticated ACP agents",
+  "colors": {
+    "primary": "#0084d1",
+    "light": "#00bcff",
+    "dark": "#0084d1"
+  },
+  "background": {
+    "color": {
+      "light": "#f8f8f6",
+      "dark": "#12141A"
+    }
+  },
+  "fonts": {
+    "heading": {
+      "family": "Lora",
+      "format": "woff2"
+    },
+    "body": {
+      "family": "Public Sans",
+      "format": "woff2"
+    }
+  },
+  "favicon": {
+    "light": "/logo/fav-light.png",
+    "dark": "/logo/fav-dark.png"
+  },
+  "logo": {
+    "light": "/logo/light.svg",
+    "dark": "/logo/dark.svg"
+  },
+  "navbar": {
+    "links": [
+      {
+        "label": "GitHub",
+        "href": "https://github.com/agentclientprotocol/registry"
+      },
+      {
+        "label": "agentclientprotocol.com",
+        "href": "https://agentclientprotocol.com"
+      },
+      {
+        "label": "JetBrains",
+        "href": "https://jetbrains.com"
+      },
+      {
+        "label": "Zed Industries",
+        "href": "https://zed.dev"
+      }
+    ]
+  },
+  "navigation": {
+    "pages": [
+      "index",
+      "registry"
+    ]
+  },
+  "seo": {
+    "metatags": {
+      "og:image": "https://zed.dev/img/acp/og-dark.webp"
+    },
+    "indexing": "navigable"
+  },
+  "footer": {
+    "socials": {
+      "github": "https://github.com/agentclientprotocol/agent-client-protocol"
+    }
+  },
+  "contextual": {
+    "options": [
+      "copy",
+      "view"
+    ]
+  }
+}