> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zapier.com/llms.txt
> Use this file to discover all available pages before exploring further.

> [Workflow] The standard workflow for contributing to docs.zapier.com (public-api-docs). Covers local setup, creating a page, registering it in docs.json, sections and sub-sections, moves and redirects, llms.txt, quality checks, and opening a merge request. Use when adding, editing, moving, or removing any page, or onboarding a new contributor.

# SKILL

# 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](../writing-standards-dev-docs/SKILL.md), [accessibility-inclusivity](../accessibility-inclusivity/SKILL.md), [formatting-guidelines](../formatting-guidelines/SKILL.md), [code-examples](../code-examples/SKILL.md), [glossary-terminology](../glossary-terminology/SKILL.md), and [dev-doc-types](../dev-doc-types/SKILL.md).

For the content-authoring workflow, pair this with [create-new-dev-docs](../create-new-dev-docs/SKILL.md) (drafting a new page) or [update-existing-dev-docs](../update-existing-dev-docs/SKILL.md) (editing an existing one), and finish with [review-before-done](../review-before-done/SKILL.md). 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

```bash theme={null}
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](../dev-doc-types/SKILL.md).
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.

```json theme={null}
{
  "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`:

```json theme={null}
{
  "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](../../rules/generated-content-safety.mdc).

**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](../sdk-content-pipeline/SKILL.md).

***

***

## 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:

```mdx theme={null}
<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](../template-how-to/SKILL.md) 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](#3-move-rename-consolidate-or-remove-a-page): 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

```bash theme={null}
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

```bash theme={null}
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](../writing-standards-dev-docs/SKILL.md).