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

​
Commands

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.

​
Prose rules

Run pnpm check:prose. Rules live in styles/ and split into two sets. ExtensionJS/ enforces the Voice, Punctuation, and Verbs conventions above, which were documented here from the start but never machine-checked. STE/ is a small subset of ASD-STE100 (Simplified Technical English), chosen for the rules that reduce mistranslation into the zh-Hans and zh-Hant mirrors:
  • SentenceLength: descriptive sentences under 25 words.
  • StepLength: procedural steps under 20 words.
  • RelativePronoun: write “the file that you created”, never “the file you created”. A dropped pronoun forces a translator to guess the clause boundary.
  • OneInstruction: one action per step, no “and then” chains.
The full ASD-STE100 dictionary is deliberately not adopted. It is licensed, its approved word list does not cover this domain, and its one-meaning-per-word rule conflicts with terms like build, run, and load that are genuinely overloaded here. One STE rule cannot be automated and belongs on the review checklist instead: warnings and prerequisites go before the step they apply to, never after. Vale matches text patterns, not document structure, so it cannot see ordering. The rules are English-only. Do not run them against zh-Hans/ or zh-Hant/.

​
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 following the workspace rule in the parent CLAUDE.md: one single line written as a natural human sentence, 74 characters maximum, no docs: / fix: / feat: prefix, no scope, no em dashes, and no AI co-author or generated-with trailer. Example: Add Vale rules for house voice and STE.

​
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.