Skip to content

AGENTS.md

Latest commit

 

History

History
113 lines (96 loc) · 4.2 KB

AGENTS.md

File metadata and controls

113 lines (96 loc) · 4.2 KB
Raw

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 information

Project context

  • Framework: Mintlify. https://mintlify.com/docs/llms.txt
  • Format: MDX files with YAML frontmatter
  • Config: docs.json for navigation, theme, settings. Tabs set top level navigation, Groups set sidebar navigation within Tabs.
  • Components: We use Mintlify components and documentation. -- Headers and text -- Images and embeds -- Lists and tables -- Code -- Reusable snippets -- Accordions -- Callouts -- Cards -- Columns -- Code groups -- Examples -- Expandables -- Fields -- Frames -- Icons -- Mermaid -- Panel -- Steps -- Tabs -- Tooltips -- Update

Content strategy

  • Search for existing information before adding new content. Avoid duplication unless it is done for a strategic reason
  • Check existing patterns for consistency
  • Start by making the smallest reasonable changes
  • Document just enough for user success - not too much. Don't be verbose.
  • Prioritize accuracy and usability of information
  • Make content evergreen

docs.json

  • Refer to the docs.json schema when building the docs.json file and site navigation
  • Tabs -- Groups --- Pages

Frontmatter requirements for pages

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

Writing standards

  • Second-person voice ("you")
  • Test all code examples before publishing
  • Match style and formatting of existing pages
  • Include both basic and advanced use cases
  • Language tags on all code blocks
  • Alt text on all images
  • Relative paths for internal links

Component usage rules

  • Use Steps component for sequential procedures sparingly.
  • Don't use Cards to display information. Only for navigation on Overview type pages
  • Use CodeGroups and Dropdowns for code examples that show the same example in different languages
  • Use Note/Tip/Warning callouts appropriately

Code snippet typecheck

CI typechecks Checkly CLI snippets in .mdx files against the latest checkly release. Run it locally with npm run check:snippets.

  • Complete snippets (with a checkly import or require) and fragments that use a checkly export (new ApiCheck(, Frequency.EVERY_5M) are checked automatically.
  • /* More options... */ marks a shortened snippet. Missing required props are allowed; wrong or unknown props still fail.
  • Add a marker comment on the line before the code fence when you need one:
    • {/* typecheck-wrap: ApiCheck */}: checks a property fragment like request: {...} inside that construct.
    • {/* typecheck-wrap */}: checks a statement like export default defineConfig(...), adding imports only.
    • {/* typecheck-skip */}: opts the block out. Use it only when the snippet can't match the latest CLI.

CodeGroup Dropdown

  • Use <CodeGroup dropdown={true}> for code examples that show the same functionality in different programming languages
  • The dropdown automatically creates a language selector based on the code block language identifiers
  • Example usage:
```typescript example.ts // TypeScript code here ``` 
// JavaScript code here
  • This replaces the older <Tabs> pattern for language-specific code examples

Guides

  • Any change under guides/, samples/guides/, or images/guides/ follows the guide-authoring skill in .claude/skills/guide-authoring/SKILL.md: agent path first, tested samples, real screenshots, brand diagrams.

Git workflow

  • NEVER use --no-verify when committing
  • Ask how to handle uncommitted changes before starting
  • Create a new branch when no clear branch exists for changes
  • Commit frequently throughout development
  • NEVER skip or disable pre-commit hooks

Do not

  • Skip frontmatter on any MDX file
  • Use absolute URLs for internal links
  • Include untested code examples
  • Make assumptions - always ask for clarification
  • overuse components like Cards or Accordion ​