Skip to main content

​
AI contributing guide — docs.zapier.com

This repository is the source of truth for docs.zapier.com, Zapier’s public API and developer documentation. It is a Mintlify site; content files are .mdx.

​
Before you start

This repo includes guided skills that walk you through documentation tasks. Read and follow the relevant skill before starting work. Skills handle page-type selection, writing standards, formatting, and contribution mechanics so you do not have to remember them. The full catalog is at .cursor/skills/SKILLS-INDEX.md. Build and tooling details are in CLAUDE.md. Skills are universal (they apply to every section: integrations, SDK, MCP, Powered by Zapier, white-label) and tool-agnostic (authored in .cursor/skills/, mirrored to .claude/skills/ via pnpm run sync-skills). They live as flat folders, organized by the category tag in each description and the SKILLS-INDEX.

​
Pick your workflow

I want to…Read this skill first
Create a new pagecreate-new-dev-docs
Update an existing pageupdate-existing-dev-docs
Review a draft before mergingreview-before-done
Turn an engineering change into a docs requestrequest-docs-from-code
Handle repo mechanics (add, move, remove, redirect, MR)contribute-docs
Decide what kind of page to writedev-doc-types
Create or edit an Agent Skillcreate-edit-skills
Write a Platform release changelogdev-platform-release-changelog

​
Writing standards

All content must follow the developer-docs writing standards. Apply these whenever you write or edit a page. Key rules (always apply):
  • Sentence case for all titles and headings, in every section. No exceptions.
  • No negative contractions — write “do not”, “cannot”, “will not” (not “don’t”, “can’t”, “won’t”). Positive contractions like “you’ll” are fine.
  • No em-dashes (—) — rewrite with a colon, parentheses, commas, or two sentences.
  • No sensory language — write “check”, “review”, “go to” (not “see”, “look at”, “view”, “watch”).
  • Second person (“you”) for the reader; no marketing hype.
  • One action per step.
Full detail in the Foundational skills:
StandardSkill
Voice, tone, sentence case, em-dashes, headings, stepswriting-standards-dev-docs
Sensory language, alt text, link text, inclusive termsaccessibility-inclusivity
Mintlify components, frontmatter, snippetsformatting-guidelines
Multi-language code examplescode-examples
Terminologyglossary-terminology

​
Choose a page type

Every page is a tutorial, how-to, reference, or explanation. See dev-doc-types for the decision tree, per-type schema, and the agent-readability layer.

​
Choose a page template

Once you know the page type, follow the matching template. Each template skill carries the writing rules plus a starter .mdx skeleton in its assets/ folder.
Page typeBest forTemplate
TutorialLearning by building a working example end to end (quick start)template-tutorial
How-toA competent reader completing one known task, or resolving an errortemplate-how-to
ConceptExplaining what something is, how it works, and when to use ittemplate-concept
ReferenceFactual look-up: errors, limits, states (not OpenAPI endpoint pages)template-reference
Troubleshooting is not a separate type: error catalogs are reference, fixes are how-tos (the error-handling variant in template-how-to).

​
Repo essentials

  • Content: .mdx files under integrations/, sdk/, mcp/, powered-by-zapier/, white-label/, ai-actions/.
  • Navigation: every new page must be added to docs.json to appear in the sidebar.
  • Reusable content: lives in snippets/ and is imported.
  • Comments: use JSX comments {/* */}, never HTML comments.
  • Generated content: API reference pages, snippets/sdk/*, and the integration checks reference are generated — do not hand-edit. See .cursor/rules/generated-content-safety.mdc.
  • Validation: pnpm run dev to preview, pnpx mintlify broken-links to check links.
  • Branching: create a short-descriptive branch from main; MRs deploy a preview and merge to production.