SKILL.md

---
name: updating-site-config
description: Use when changing docs.json through the Mintlify Admin MCP — theme, colors, logo, favicon, navbar, footer, fonts, SEO metadata, site name or description, banners, redirects, or any site-wide setting.
---

# Updating Site Config

## Overview

`update_config` (inside a checked-out session) edits any top-level `docs.json` field except `navigation`. Changes land on the session branch and publish via `save`, like content edits. The full field reference is https://www.mintlify.com/docs.json.

## Operations

**`set`** — merge at the top level only. Each top-level key you provide **replaces that key's entire value**; sibling keys you omit are untouched, but nested fields inside a key you provide are not merged.

```
update_config {
  op: 'set',
  docsConfig: { name: 'Acme Docs', colors: { primary: '#0D9373', light: '#07C983', dark: '#0D9373' } }
}
```

Sending `colors: { primary: '#0D9373' }` alone would drop `colors.light` and `colors.dark`. There is no config-read tool, so use this recovery loop: send the `set`, then inspect the returned `diff` — it reports the `before` values of everything you changed, including nested fields you accidentally dropped. If the diff shows unintended removals, re-`set` that key with the complete object reconstructed from the diff's `before` values. Nothing is live until `save`, so this loop is safe.

Set a top-level key to `null` to remove it entirely. The merged result is validated against the full schema — any violation rejects the whole call with no partial writes. `navigation` and `$schema` keys are rejected.

**`add_redirect`** — append to `redirects`:

```
update_config { op: 'add_redirect', redirect: { source: '/old-path', destination: '/new-path', permanent: true } }
```

Rejects on duplicate `source`. Sources match by exact string comparison against stored redirects — keep the leading-slash form consistent.

**`remove_redirect`** — `{ op: 'remove_redirect', source: '/old-path' }`. Rejects if the exact source string is not present.

## Response

Returns `{ diff }` of only what changed: scalars as `{ before, after }`, nested objects recurse under `{ changed }`, arrays (`redirects`, `navbar.links`) as `{ added, removed }`. Read the diff to confirm the merge did what you intended.

## Which description tool?

| Target | Tool |
|--------|------|
| Site-level SEO/social description (`docs.json` `description`) | `update_config` |
| One page's frontmatter `description` | `update_node` with `data.type: 'page'` |
| Text inside a page body | `edit_page` |

## Common mistakes

- Sending `navigation` through `set` — rejected; use the node tools (`create_node`, `move_node`, …).
- Sending a partial nested object — `set` replaces the whole top-level key; follow the diff-recovery loop above when you don't know the current nested values.
- Editing `docs.json` as if it were a page via `write_page` — config has its own tool and validation path.
- Forgetting `save` — config edits are session-scoped until published.