Skip to main content

​
AGENTS.md

Entry point for AI coding agents working on the Extension.js documentation site.

​
What this repo is

The source for extension.js.org, the documentation site for Extension.js, a cross-browser extension framework. Built with Mintlify.

​
Layout

extension.js.org/
├── docs.json              # Site config (navigation, theme, integrations)
├── docs/                  # All documentation pages (MDX)
│   ├── getting-started/
│   ├── concepts/
│   ├── features/
│   ├── workflows/
│   ├── commands/
│   ├── browsers/
│   ├── languages-and-frameworks/
│   ├── integrations/
│   ├── implementation-guide/
│   └── ai-access.mdx      # MCP and llms.txt entry points
├── blog/                  # Blog posts
├── snippets/              # Reusable MDX components
├── images/                # Static assets referenced as /images/...
├── index.mdx              # Site landing page
├── style.css              # Custom styling on top of Mintlify theme
├── robots.txt
└── .agents/skills/        # Skill files for agents (mintlify, mintlify-api, mintlify-docs)

​
Commands

pnpm install        # Install dependencies (Node >= 22.18.0, pnpm 10)
pnpm dev            # Local preview at localhost:3000
pnpm build          # Build the site (mint build)
pnpm broken-links   # Check internal links
pnpm validate       # Validate the docs build
pnpm check          # lint + format + spellcheck
pnpm test           # Run vitest tests
Always run pnpm check before opening a PR.

​
Conventions

  • Page format: MDX with YAML frontmatter. title is required, description is strongly recommended for SEO.
  • Filenames: kebab-case (getting-started.mdx, manifest-v3.mdx).
  • Internal links: root-relative without extension (/concepts/manifest, never ../concepts/manifest.mdx).
  • Images: store in /images, reference as /images/example.png.
  • Navigation: every new page must be registered in docs.json or it will be hidden.
  • Voice: second person, active voice, sentence-case headings. No marketing language (“powerful”, “seamless”), no filler (“in order to”, “it’s important to note”).
  • Punctuation: no em dashes. Use commas, colons, or parentheses.
  • Verbs: prefer “choose” over “pick” or “select” for selection/option language (see commit history for prior standardizations).
  • Code blocks: always tag with a language.

​
AI access surfaces

The site exposes two AI-accessible endpoints, documented in docs/ai-access.mdx:
  • MCP server: https://extensionjs.mintlify.app/mcp (full search and page-fetch tools)
  • llms.txt: /llms.txt (index) and /llms-full.txt (full bundle), auto-generated by Mintlify on every deploy
When pointing other agents at this docs site for grounded answers, prefer the MCP server.

​
Skills available

.agents/skills/ contains reusable skill files for agents working on the site:
  • mintlify/SKILL.md: writing docs, components, navigation, deployment
  • mintlify-api/SKILL.md: programmatic deployment and metadata via REST API
  • mintlify-docs/SKILL.md: Mintlify-specific documentation patterns
Load these when working on related tasks rather than guessing Mintlify behavior.

​
Workflow for changes

  1. Read docs.json to understand navigation structure.
  2. Search existing pages before creating new ones, prefer updates and links over duplication.
  3. Read 2-3 nearby pages to match tone and structure.
  4. Write content, update docs.json if a new page is added.
  5. Run pnpm check, pnpm broken-links, pnpm validate.
  6. Commit with a conventional prefix (docs:, fix:, feat:). Do not include AI co-author trailers.

​
What not to do

  • Do not introduce a hand-rolled index.mdx redesign without flagging the brand gap first, the current landing page is intentional.
  • Do not rename docs.json to mint.json, mint.json is deprecated.
  • Do not add files to the root docs/ folder without a navigation entry.
  • Do not use relative paths or file extensions in internal links.