Skip to content

AGENTS.md

Latest commit

 

History

History
214 lines (152 loc) · 5.71 KB

AGENTS.md

File metadata and controls

214 lines (152 loc) · 5.71 KB

Mergify Documentation Site

Official documentation for Mergify - the merge queue and CI optimization platform.

Quick Facts

  • Framework: Astro 5.x with MDX
  • UI Libraries: React 19, Vue (for specific components)
  • Language: TypeScript (strict mode)
  • Node Version: 24 (see .node-version)
  • Formatter: Biome (primary), Prettier (for .astro files)
  • Linter: ESLint 9 (flat config)
  • Testing: Vitest
  • Deployment: Cloudflare Pages

Key Commands

# Development
npm start              # Start dev server (pages build on-demand)
npm run build          # Full production build with type checking
npm run preview        # Preview production build locally

# Code Quality
npm run check          # Run all checks: astro check + eslint + biome
npm run format         # Auto-format with Biome
npm run format:check   # Check formatting without modifying

# Testing
npm run test           # Run Vitest unit tests
./scripts/detect-broken-links.sh  # Check for broken links

Key Directories

  • src/content/docs/ - Main documentation pages (MDX files)
  • src/content/changelog/ - Changelog entries
  • src/components/ - Astro and React components
  • src/layouts/ - Page layout templates
  • src/util/ - Utility functions (with tests)
  • integrations/ - Custom Astro integrations
  • plugins/ - Custom Remark/Rehype plugins
  • public/ - Static assets

Code Style

TypeScript

  • Strict mode enabled
  • Use ~/* path alias for imports from src/
  • Prefer interfaces over types (except unions)

MDX Documentation Files

  • Always include YAML frontmatter with title and description
  • Import components at top of file
  • Use custom components for callouts: <Aside type="note|tip|caution|danger">
  • Code blocks use Shiki syntax highlighting

Formatting

  • 100 character line width
  • Single quotes
  • 2-space indentation
  • Trailing commas (ES5 style)
  • Semicolons required

Content Structure

Documentation is organized into sections:

  • configuration/ - Mergify configuration reference
  • merge-queue/ - Merge queue features and setup
  • workflow/ - Workflow automation
  • commands/ - GitHub comment commands
  • ci-insights/ - CI analytics and optimization
  • merge-protections/ - Branch protection rules
  • integrations/ - Third-party integrations
  • enterprise/ - Enterprise features

Callout Boxes

When writing documentation, use directive syntax for callouts:

:::note
  Important information here.
:::

:::tip
  Helpful suggestion.
:::

:::caution
  Be careful about this.
:::

:::danger
  Critical warning.
:::

Note: Content inside directives should be indented with 2 spaces.

Git Workflow

Creating Branches

When creating a new branch, always track the main branch:

git checkout -b my-feature-branch --track origin/main

Pushing Changes

Use Mergify's stack command to push:

mergify stack push

Do NOT use regular git push - always use mergify stack push.

Critical Rules

  1. Always run npm run check before committing - Catches TypeScript, lint, and format errors

  2. MDX files must have valid frontmatter - Title and description required

  3. Images go in src/content/docs/images/ - Use relative imports

  4. Test locally with npm run build - Ensures SSG works correctly

  5. Use mergify stack push to push - Not regular git push

  6. Never modify changelog entries - Files in src/content/changelog/ are autogenerated externally and must not be created, edited, or deleted

Documentation Proofreading

After editing MDX files in src/content/docs/, if the total changed/added lines across all edited docs files is 10 or more lines, you MUST run the proofreading pipeline before considering the work done.

How It Works

  1. Collect the diff: Get the diff of all changed MDX files in src/content/docs/ (use git diff for staged/unstaged changes).

  2. Spawn 4 proofreading subagents in parallel using the Agent tool, each with the diff and the list of changed files:

    • Style (proofread-style): AI patterns, banned words, tone, voice

    • Technical (proofread-technical): code examples, config keys, links, feature names

    • Structure (proofread-structure): frontmatter, headings, callouts, missing context

    • Consistency (proofread-consistency): terminology drift, capitalization, naming

  3. Each subagent:

    • Reads the skill with the Skill tool for its full guidelines

    • Reviews ONLY the changed/added lines

    • Fixes issues directly in the files

    • Reports what it changed

    • Notes FOLLOW-UP: suggestions for issues in surrounding unchanged content (does NOT edit those)

  4. After all subagents complete:

    • Summarize all fixes applied

    • List any FOLLOW-UP: suggestions as optional improvements for a separate commit

    • If follow-up suggestions exist, ask the user if they want to apply them as a separate change

Subagent Prompt Template

When spawning each subagent, include:

  • The skill name to invoke (e.g., "Read the proofread-style skill using the Skill tool, then follow its instructions")

  • The full diff output

  • The list of changed file paths

  • Instruction: "Fix issues directly. Report changes. Note FOLLOW-UP items for unchanged content."

When to Skip

  • Changes are fewer than 10 lines of docs content

  • Changes are ONLY to frontmatter metadata (title/description tweaks)

  • Changes are ONLY to code blocks with no prose changes

  • Changes are to files outside src/content/docs/

Common Issues

  • Build fails on MDX: Check for unclosed JSX tags or invalid frontmatter
  • Component not found: Ensure correct import path with ~/ alias
  • Styling issues: Check CSS scoping in components