SKILL.md

---
name: editing-docs-content
description: Use when changing the text or MDX body of documentation pages through the Mintlify Admin MCP — fixing typos, rewriting sections, updating code samples, or making any content edit that should ship as a commit or PR.
---

# Editing Docs Content

## Overview

Content edits happen inside a checked-out editing session on an isolated git branch. Nothing goes live until `save` publishes the branch. Every editor tool fails with "No active session" until you `checkout`.

## Workflow

1. `list_deployments` — find the subdomain (skip if pinned or already known).
2. `checkout { subdomain, slug: "fix-auth-typos" }` — opens the session (~7s). Surface the returned `editorUrl` to the user so they can follow along.
3. Locate content: `search { query }` greps every page on the branch (literal string by default, `regex: true` for regex, results capped at 30KB — refine if `truncated`). `read { path }` returns the full MDX of one page. Both reflect in-session edits immediately.
4. Edit:
   - Targeted change → `edit_page { path, oldString, newString, replaceAll? }` (string-replace, like a code editor Edit tool). `replaceAll` is per-page; a docs-wide sweep is one `edit_page` call per matched path from `search`.
   - Full rewrite → `write_page { path, content }`.
   - If a search hit might sit in frontmatter rather than body, `read` the page first — frontmatter fixes go through `update_node`, not `edit_page`.
5. Verify with `diff` (patch per changed file) or `get_session_state` (branch, edited files, nav diff).
6. `save { title, mode? }` — publishes (~10s).

## Save modes

| mode | Behavior |
|------|----------|
| `auto` (default) | Opens a PR; auto-merges only when the deployment's agent review setting is push-to-main and the deploy branch is unprotected (`merged: true` in the response) |
| `pr` | Opens a PR and always leaves it open for review |
| `commit` | Commits to the **session branch** in git without opening a PR — a snapshot, never a direct write to the deploy branch |

Saving again in the same session commits to the existing PR branch. `discard_session` abandons everything without publishing.

## Critical: frontmatter is not body content

`edit_page` / `write_page` are for the MDX **body only**. Frontmatter fields (`title`, `sidebarTitle`, `description`, `icon`, `canonical`, `og:*`, `keywords`, `noindex`, `hidden`, …) round-trip through structured node metadata — set them with `update_node { nodeId, data: { type: 'page', ... } }`. The site-level description lives in `docs.json` via `update_config`.

## Common mistakes

- Editing frontmatter with `edit_page` — silently wrong; use `update_node`.
- Calling `read`/`edit_page` before `checkout` — "No active session".
- Assuming `save` merged: check `merged` in the response; most deployments leave the PR open.
- Paths are page hrefs (`/quickstart` or `guides/setup`), leading slash and `.mdx` optional.
- Renaming a page path: `move_node`, never a write to a new path plus delete.