Skip to main content

​
Formatting guidelines (Mintlify)

docs.zapier.com runs on Mintlify. All content files are .mdx (Markdown plus JSX components). Plain .md does not render Mintlify components. This skill is for components and page mechanics. For writing rules see writing-standards-dev-docs; for code blocks see code-examples.

​
Critical rules

  • Use JSX comments, never HTML comments. {/* like this */}. HTML comments (<!-- -->) break the page render.
  • Leave a blank line after an opening tag and before a closing tag, or the content may not render.
  • New pages must be registered in docs.json to appear in the sidebar — see contribute-docs.
  • Do not hand-edit generated files — see generated-content-safety.
  • Do not hardcode the app count. Import it: import { appCount } from "/snippets/sdk/vars.mdx"; then use {appCount}.

​
Frontmatter

Every page opens with frontmatter. At minimum set title and description, both written as task-oriented answers to “what does this page help the reader do?” (this also drives search and AI-answer quality). Use sidebarTitle when the H1 is long. 
---
title: "Create a trigger inbox for an app"
sidebarTitle: "Create a trigger inbox"
description: "Connect to Slack, Gmail, and 9,000+ other apps using the user's app connection and the Trigger Inbox API."
---
Optional, section-dependent: icon, tag (e.g. "Experimental", "Deprecated", "New"), noindex, mode. Do not add non-standard fields (such as doc_type, goal, prerequisites, or audience) — Mintlify ignores unknown frontmatter.

​
Callouts

Mintlify has six variants. Pick by severity so <Warning> and <Danger> keep their impact. 
<Note>Useful information the reader should notice.</Note>
<Info>Neutral, supporting context.</Info>
<Tip>A recommendation or shortcut.</Tip>
<Warning>Something that could cause a problem.</Warning>
<Check>A success state or confirmation.</Check>
<Danger>A serious or destructive consequence.</Danger>
Add a title with title="...". Note: unlike helpdocs, Mintlify <Tip> is always visible and there is no <Example> component.

​
Layout components

ComponentUse forNotes
<AccordionGroup> + <Accordion title="...">Optional detail, alternatives, FAQsGroup wrapper is AccordionGroup (helpdocs uses Accordions)
<Tabs> + <Tab title="...">Different approaches or workflowsUse <CodeGroup> instead when only the language differs
<CodeGroup>Same call in multiple languagesSee code-examples
<Card> + <CardGroup cols={N}>Landing-page and navigation linksAccepts icon, href, horizontal
<Columns cols={N}>Responsive multi-column content1–4 columns
<Steps> + <Step title="...">Setup and quickstart flowsRicher than a numbered list
<Frame caption="...">ScreenshotsStyled container; always include alt on the <img>
<AccordionGroup>
  <Accordion title="Other ways to find a connection">
    Alternatives live here, not inline. The happy path stays linear.
  </Accordion>
</AccordionGroup>

​
Diagrams

Use a live-rendered Mermaid block instead of a screenshot for flows, lifecycles, and state machines (agents can parse it; screenshots are opaque): 
```mermaid
sequenceDiagram
  Partner->>Zapier: Exchange JWT for token
  Zapier-->>Partner: Access token
```

​
Snippets (reusable content)

Single-source content lives in snippets/ and is imported: 
import WatchExample from "/snippets/sdk/example-watch-trigger-inbox.mdx";

<WatchExample />
Files under snippets/sdk/ are auto-generated — edit the source .ts/.sh and re-run pnpm run sync-sdk, never the snippet. See generated-content-safety.

​
API reference components

Reference pages are normally generated from OpenAPI (do not hand-edit). For hand-authored reference content, Mintlify provides <ParamField>, <ResponseField>, <RequestExample>, and <ResponseExample>.

​
helpdocs → Mintlify translation

If you know the helpdocs (Zendesk) component set, note the differences:
helpdocsMintlify
<Note> (one variant)Six callouts: <Note> <Info> <Tip> <Warning> <Check> <Danger>
<Accordions><AccordionGroup>
<Plan> / <Beta> / <Alpha>No equivalent — use a callout, <Badge>, or a table
<Content-block>Snippet import
<Example>No equivalent — use <Tip> or <Accordion>
(none)<CodeGroup>, <Card>, <Steps>, Mermaid, OpenAPI playground