​

Mintlify documentation

​

Working relationship

• You can push back on ideas-this can lead to better documentation. Cite sources and explain your reasoning when you do so
• ALWAYS ask for clarification rather than making assumptions
• NEVER lie, guess, or make up anything

​

Project context

• Mintlify docs site for Bodyguard (contextual AI content moderation)
• Format: MDX files with YAML frontmatter
• Config: docs.json drives navigation, theme, languages, redirects
• Bilingual site: English under en/, French under fr/
• API reference “Reference” group is auto-generated from openapi/analyze.openapi.yaml
• Components: Mintlify built-ins (Note, Warning, Card, CardGroup, CodeGroup)

​

Repository layout

AGENTS.md           — this file
docs.json           — navigation, theme, languages, redirects
.mintignore         — drafts/, *.draft.mdx excluded
en/                 — English content
  documentation/    — product docs (Getting started, Taxonomy)
  api-reference/    — hand-written API guides (introduction, reseller)
fr/                 — French mirror of en/
openapi/
  analyze.openapi.yaml  — drives API "Reference" group
images/             — logo-light.svg, logo-dark.svg, favicon.svg

​

Product & API facts

• Product: Bodyguard — classifies text, images, and usernames for harmful content
• API base: https://api.bodyguard.ai
• Auth header: Authorization: ApiKey <your-api-key> (scheme name is case-sensitive)
• Endpoints: /analyze/v1/text, /analyze/v1/image, /analyze/v1/username
• Text taxonomy has two layers:
  • Moderation signals: type, severity, directedAt
  • Classifications: General (everyone), Additional (Advanced plan, monitoring-only), Custom (per contract)
• Image taxonomy is flat — each classification stands on its own
• Reseller API keys unlock an analysisSettings object in request bodies (industry, defaultLanguage, imageVlmClassifications, imageVlmSettings, imageOcrSettings)
• Error envelope: { "error": { "code": "...", "details": { "<camelCaseOfCode>": { ... } } } }

​

Bilingual content

• Prefer mirroring every en/<path>.mdx at fr/<path>.mdx with identical relative path
• When adding or renaming a page, update both language blocks in docs.json navigation
• If the French mirror is pending, flag the missing mirror to the user rather than silently skipping it
• Translate frontmatter (title, description) and body; keep technical values (classification names, field names, code) unchanged

​

Navigation registration (docs.json)

• New pages are invisible until added to navigation.languages[].tabs[].groups[].pages[]
• Page path format: en/path/to/page — no leading slash, no .mdx extension
• openapi groups auto-populate from the YAML file — do not list those endpoints manually
• Refer to the docs.json schema when editing navigation
• Respect existing tab names per language: English uses “Documentation” / “API Reference”, French uses “Documentation” / “Référence API”

​

Components

• You can use any Mintlify built-in component. Full catalog: https://mintlify.com/docs/components
• Prefer existing components over custom markup. If unsure a component exists, check the Mintlify docs before inventing one
• Icon library is Lucide (set in docs.json) — icon names must match Lucide

​

Components already in use in this repo

• Callouts: <Note>, <Warning>
• Indexes and catalogs: <CardGroup cols={2|3}> containing <Card title="..." icon="..." href="/en/...">
• Multi-language code examples: <CodeGroup> with language-tagged fences (```bash cURL, ```javascript JavaScript, ```python Python, ```go Go)
• Card meta: tag= attribute — values seen in this repo: "Additional", "Removed by default", "Never removed", "Critical", "Mutually exclusive"

​

Other useful Mintlify components (non-exhaustive)

​

Taxonomy page conventions

• Each classification rendered as a <Card> inside a grouped <CardGroup>
• Card body structure:
  1. `TECHNICAL_NAME` · Type (type only for text taxonomy — image taxonomy is untyped)
  2. One-sentence description
  3. Italic example in quotes (*"..."*)
• Group classifications with ### subheadings. Existing groupings:
  • Text: Harmful content, Explicit content, Spam & low quality, Personal information (PII), Advertising, Positive signals, Brand & community, Context & topics
  • Image: Sexual content, Violence & harm, Hate & harassment, Substances & regulated activity, People & identity, Codes & information, Other

​

Style anchors

• API reference pages: match en/api-reference/introduction.mdx (auth, versioning, rate limits, errors, Next steps CardGroup)
• Reseller / advanced API pages: match en/api-reference/reseller.mdx
• Taxonomy pages: match en/documentation/taxonomy/text-classifications.mdx

​

Frontmatter requirements for pages

• title: Clear, descriptive page title
• description: Concise summary for SEO/navigation

​

Writing standards

• Second-person voice (“you”)
• Prerequisites at start of procedural content
• Test all code examples before publishing
• API code examples must stay consistent with openapi/analyze.openapi.yaml (endpoint path, field names, example values)
• Match style and formatting of existing pages — see Style anchors above
• Include both basic and advanced use cases
• Language tags on all code blocks
• Alt text on all images
• Relative paths for internal links

​

Content strategy

• Document just enough for user success - not too much, not too little
• Prioritize accuracy and usability
• Make content evergreen when possible
• Search for existing content before adding anything new. Avoid duplication unless it is done for a strategic reason
• Check existing patterns for consistency
• Start by making the smallest reasonable changes

​

Local preview

npm i -g mint
mint dev

​

Checklist before creating new content

1. Grep en/ for existing similar page — avoid duplication
2. Confirm target tab and group in docs.json with the user if unclear
3. Draft en/<path>.mdx following the matching Style anchor
4. Mirror to fr/<path>.mdx (or flag the pending mirror)
5. Register the new path in both language blocks of docs.json
6. Run mint dev to verify rendering and links

​

Do not

• Skip frontmatter on any MDX file
• Use absolute URLs for internal links
• Include untested code examples
• List OpenAPI-generated endpoints manually in docs.json
• Add a page without registering it in docs.json navigation
• Make assumptions - always ask for clarification