Skip to main content

​
Contribute to docs.zapier.com

The end-to-end workflow for changing content in public-api-docs (a Mintlify site). Use this for any structural change. Apply the foundational skills while you write: writing-standards-dev-docs, accessibility-inclusivity, formatting-guidelines, code-examples, glossary-terminology, and dev-doc-types. For the content-authoring workflow, pair this with create-new-dev-docs (drafting a new page) or update-existing-dev-docs (editing an existing one), and finish with review-before-done. This skill owns the repo mechanics those workflows hand off to.

​
When to use

  • Adding a new page or section
  • Editing or restructuring existing pages
  • Moving, renaming, consolidating, or removing pages
  • Deprecating a feature, API, or surface
  • Onboarding a new contributor

​
1. Set up locally

git clone https://gitlab.com/zapier/public-api/public-api-docs.git
cd public-api-docs
pnpm i        # use pnpm, never npm or yarn
pnpm run dev  # opens localhost:3000
You can also edit online through the Mintlify dashboard (including branches and PRs) without a local setup.
If pnpm i fails because of a broken asdf shim, bypass it by calling the full Node binary path for npm i -g pnpm and pnpm install. Request GitLab access to the zapier/public-api group if you do not have it.

​
2. Create a page

  1. Create the .mdx file in the right product folder (e.g. white-label/trigger-inbox/my-new-page.mdx).
  2. Choose the page type and follow its schema — see dev-doc-types.
  3. Add frontmatter (title, description, and sidebarTitle if the H1 is long).
  4. Register it in docs.json — a page does not appear in the sidebar until it is listed. Add the path (no .mdx) to the correct pages array. Position sets the sidebar order.
{
  "group": "Trigger Inbox",
  "pages": [
    "white-label/trigger-inbox/what-is-trigger-inbox-api",
    "white-label/trigger-inbox/my-new-page"
  ]
}
The site is organized as tabs → groups → pages. A sub-section is a group object nested inside another group’s pages array. A new top-level area is a new tab.

​
3. Move, rename, consolidate, or remove a page

Any change to a URL needs a redirect so existing links and search results keep working. Redirects live in the top-level redirects array in docs.json: 
{
  "source": "/white-label/use-cases/embedded-triggers",
  "destination": "/white-label/trigger-inbox/what-is-trigger-inbox-api"
}
Workflow:
  1. Move or rename the .mdx file.
  2. Update its entry in docs.json pages.
  3. Add a redirects entry from the old path to the new one (for a consolidation, redirect the removed page to the survivor).
  4. Update internal links that pointed at the old path.
  5. Update the committed llms.txt.

​
4. llms.txt

The committed root llms.txt is hand-curated. Update it when you add, rename, move, or remove a page or section. Routine text edits do not need an llms.txt change. Mintlify’s hosted /llms.txt and per-page .md URLs are auto-generated from docs.json — leave those alone.

​
5. Do not hand-edit generated content

API reference pages, snippets/sdk/*, the integration checks reference, and news.mdx are generated. Change the source and regenerate. See generated-content-safety. SDK section: The sdk/ docs have a specific generated-content pipeline (sync-sdk-docs.ts) that syncs code examples from src/sdk/snippets/ and API reference tables from the SDK package READMEs. For the full source→output map and regeneration commands, see sdk-content-pipeline.

​
6. Deprecate a feature or page

Use this when a feature, API, or surface is being retired but must stay live during a transition period (for example, AI Actions being replaced by MCP). Deprecate vs. remove immediately:
  • Deprecate if users still depend on the page or a migration path is needed.
  • Remove immediately (and redirect) only if the feature is already gone and no migration content is needed.

​
Add a deprecation notice

Place a <Warning> callout as the very first thing after the frontmatter, before any other content: 
<Warning>
  **AI Actions is deprecated.** [MCP](/mcp/what-is-zapier-mcp) is the
  replacement. Existing integrations continue to work, but no new features will
  be added to AI Actions. Follow the [migration guide](#migrate-to-mcp) below.
</Warning>
Keep the rest of the page intact so existing users can still follow it.

​
Write a migration guide

Either add a ## Migrate to [successor] section on the same page (for a short migration) or create a standalone how-to page using the template-how-to error-handling variant. Link from the <Warning> callout.

​
Update llms.txt

Annotate the entry with [deprecated] and add the successor URL: 
- [AI Actions overview](https://docs.zapier.com/ai-actions/overview) [deprecated — use /mcp/what-is-zapier-mcp]: How to use the AI Actions API.

​
When the page is eventually removed

Follow the standard redirect workflow in section 3: move/delete the file, add a redirects entry to docs.json, and remove the llms.txt entry.

​
7. Structural-change checklist

Run this whenever a change affects URLs or structure:
  • .mdx file created/moved/renamed in the right folder
  • docs.json pages updated (nested group added for a new sub-section)
  • README.md updated if adding a new top-level product folder (update the tree diagram and Content organization table)
  • redirects entry added for any old → new URL change
  • Internal links to the old path updated
  • Committed llms.txt updated
  • Local preview checked (pnpm run dev)
  • Broken-link check run (pnpx mintlify broken-links)

​
8. Quality checks before a merge request

pnpm run dev               # local preview at localhost:3000
pnpx mintlify broken-links # internal link check
pnpm run build             # full build (format + compile + scriptify)
A pre-commit hook runs automatically: it processes OpenAPI specs, updates navigation, and validates links and routes.

​
9. Open a merge request

git checkout -b short-descriptive-name
git add .
git commit -m "Brief description of changes"
git push origin short-descriptive-name
  1. Open an MR from your branch in GitLab.
  2. GitLab generates a preview environment — add the preview link to the MR description.
  3. Approval is not strictly required to merge a public-api-docs MR; request a review when you want a proofread or technical-accuracy check.
  4. After merge, docs deploy to production automatically.
Before calling it done, run the quick-check list in writing-standards-dev-docs.