Skip to main content

​
CLAUDE.md

Guidance for Claude Code in this repository.

​
What this is

Mintlify documentation for Guardway — a self-hosted LLM gateway governed from a SaaS dashboard. Published at docs.guardway.ai, auto-deployed from main by Mintlify’s GitHub integration. Theme: maple.

​
Commands

docker compose up dev                                # local preview, http://localhost:3001
docker compose --profile check run --rm broken-links # what the PR check runs
# Or if Node 20 is on the host:
mintlify dev
mintlify broken-links
mintlify build

​
Where everything lives

  • docs.json — the only config file. Navigation, branding, colors, fonts, anchors, redirects, SEO, contextual menu, 404, OG metadata.
  • getting-started/, platform/, guardway-gateway/, discovery/, resources/, api-reference/, changelog/ — MDX content. Folder structure mirrors the navigation.groups order in docs.json.
  • images/logo.png — 256×256 orange mark (source for the wordmark).
  • images/wordmark-{light,dark}.svg — combined mark + “Guardway Docs” text. What renders as the navbar logo. Regenerate via the HTML+headless-Chrome workflow used in git history if you need to change text or weight.
  • images/og.png — 1200×630 social preview card. Wired through metadata.og:image.
  • images/icons/mcp.svg — custom sidebar icon for the MCP page.
  • images/providers/<slug>-{light,dark}.{svg,png} — brand logos for the provider grid on connect-provider.
  • images/screenshots/<section>/*.png — screenshot placeholders. Every real filename is referenced from an MDX page; the assets are awaiting real images.
  • .github/workflows/pr-checks.yml — broken-links + build check on every PR.
  • Dockerfile + docker-compose.yml — local dev with Node 20 (Mintlify doesn’t support newer Node).

​
Design (non-obvious, don’t re-derive)

  • Layout inspiration: docs.perplexity.ai. Top-level groups with icons, theme toggle in default Mintlify position.
  • Brand primary #EC9322 (light #F5B04D, dark #C97A1A) — set once in docs.json, never override inline.
  • Font: Inter via docs.json.fonts. Do not import fonts in MDX or add custom CSS.
  • Logo is a combined wordmark SVG (mark base64-embedded + “Guardway Docs” in Inter 800) because Mintlify’s name text rendering hits a hard navbar-height cap and longer strings shrink to fit width. The wordmark lets us control the visual weight.
  • API reference is deliberately a Coming soon placeholder. Keep the group in the nav.
  • Changelog lives as a top-right anchor, not a sidebar group. Entries use <Update label="YYYY-MM-DD" tags={[…]}>.
  • Maple theme caps logo height at ~28 px. Source SVGs are sized for that cap.

​
Content rules

  • Accuracy over polish. Route paths (/dashboard/...), button labels, and feature lists must match the dashboard in ../guardway-dashboard. If you’re unsure, read the component source or run npm run dev there before writing.
  • Do not invent version history. The changelog contains only things that actually shipped. No fake “v2.5 — ML-Powered Threat Detection” entries.
  • Screenshots are placeholders. Use <Frame> with /images/screenshots/<section>/<name>.png and an MDX comment: {/* TODO(screenshot): <what it should show> */}. Do not fabricate screenshots.
  • Audit logs are local-only. Any page that mentions audit logs must say so (mirrors the workspace-root rule in ../.cursor/rules/audit-logs-local-only.mdc). Even platform/audit.mdx, despite living under Platform, reads from the local gateway — the page already explains this; don’t regress it.
  • Title case for multi-word page titles (“Usage and Spend”, “Organizations and Teams”, “API Keys”). Lowercase conjunctions (and, of, or).
  • Provider grid on connect-provider.mdx uses an MDX component (defined at the top of that file). New providers: drop logo files + add one <Provider slug="..." name="..." /> line.

​
Changelog rule

Every content change must add a dated <Update> block to changelog/whats-new.mdx. Typo-only fixes are exempt. Do not edit older <Update> blocks to backfill changes. Automation from dashboard prod deploys is not built — tracked in the README. Add entries by hand in the same PR as the content change.

​
Redirects

Every time you rename, move, or delete a page, add a permanent redirect to docs.json.redirects. Current redirects cover: configuration → environment, features → functionalities, whats-new route move, webhooks from gateway to platform, old troubleshooting/* and api-reference/glossary URLs. Don’t break bookmarks.

​
MDX components available

<CardGroup>, <Card>, <Steps>, <Step>, <Tabs>, <Tab>, <CodeGroup>, <AccordionGroup>, <Accordion>, <Note>, <Warning>, <Tip>, <Frame>, <Update>, <ParamField>. Icons are Font Awesome or Lucide names, or paths to local SVGs (e.g. icon: /images/icons/mcp.svg).

​
Deployment

Mintlify auto-deploys main to docs.guardway.ai. Branch pushes get a preview URL from the Mintlify GitHub app. Do not add any other build / deploy configuration.