# Documentation site maintenance

> Contribution: Maintain the Mintlify docs site, navigation manifest, generated MCP pages, local preview, broken-link checks, and writing conventions.

- Repository: macro-inc/macro
- GitHub: https://github.com/macro-inc/macro
- Human docs: https://grok-wiki.com/public/docs/macro-inc-macro-bb988e1a448e
- Complete Markdown: https://grok-wiki.com/public/docs/macro-inc-macro-bb988e1a448e/llms-full.txt

## Source Files

- `docs/README.md`
- `docs/docs.json`
- `docs/package.json`
- `docs/scripts/generate-mcp-tool-pages.ts`
- `docs/config/tool-pages.json`
- `docs/AGENTS.md`
- `docs/CONTRIBUTING.md`

---

---
title: "Documentation site maintenance"
description: "Contribution: Maintain the Mintlify docs site, navigation manifest, generated MCP pages, local preview, broken-link checks, and writing conventions."
---

The documentation site lives in `docs/` as a Mintlify project with `docs/docs.json` as the active site manifest, Bun scripts for local operations, and generated MCP tool reference pages under `docs/AI/mcp/tools/`.

## Maintenance surface

```text
docs/
├── docs.json                         # active Mintlify manifest
├── package.json                      # dev, lint, generate:tools, prepare
├── README.md                         # local setup and monorepo deployment notes
├── AGENTS.md                         # agent-facing writing conventions
├── CONTRIBUTING.md                   # contributor workflow and style guidance
├── development.mdx                   # local Mintlify preview guide
├── AI/mcp/tools/                     # generated MCP tool reference pages
├── config/tool-pages.json            # generated tool page list
├── config/navigation.json            # secondary navigation fragment, not the active manifest
└── scripts/
    ├── generate-mcp-tool-pages.ts
    └── generate-changelog.ts
```

<Warning>
The checked-in MCP generator writes to `docs/AI/mcp/tools/`. If a maintenance note mentions `docs/reference/tools/`, verify it against `docs/scripts/generate-mcp-tool-pages.ts` before moving files or changing navigation.
</Warning>

## Local commands

Run documentation commands from `docs/`.

| Task | Command | Notes |
| --- | --- | --- |
| Install dependencies | `bun install` | Uses `docs/package.json` and `docs/bun.lock`. |
| Generate MCP tool pages | `bun run generate:tools` | Runs `bun ./scripts/generate-mcp-tool-pages.ts`. |
| Preview locally | `bun run dev` | Wraps `mint dev`. |
| Check links | `bun run lint` | Wraps `mint broken-links`. |
| Run generator through lifecycle script | `bun run prepare` | Calls `bun run generate:tools`. |

```bash
cd docs
bun install
bun run generate:tools
bun run dev
bun run lint
```

<Note>
Mintlify CLI commands may reject unsupported runtimes. The repository README recommends switching to Node 20 or Node 22 when `mint dev` or `mint broken-links` fails because of the active Node version.
</Note>

## Active site manifest

`docs/docs.json` controls the rendered site structure and global presentation.

| Area | Current value |
| --- | --- |
| Schema | `https://mintlify.com/docs.json` |
| Theme | `mint` |
| Site name | `Macro` |
| Default appearance | `dark` |
| Primary color | `#ff8f05` |
| Favicon | `/favicon.svg` |
| Logos | `/logo/light.svg`, `/logo/dark.svg` |
| Navbar CTA | `Get Macro` → `https://macro.com` |
| Tabs | `Documentation`, `Changelog` |

The `Documentation` tab contains `Getting Started` and `Product` groups. The `AI Chat` product group nests the MCP overview and generated Tool Reference pages. The `Changelog` tab points at `changelog/introduction`.

When adding a handwritten page:

1. Create the `.mdx` file under the matching content folder.
2. Add the route without the `.mdx` extension to `docs/docs.json`.
3. Use root-relative internal links such as `/product/ai-chat`.
4. Run `bun run lint`.

<Warning>
`docs/config/navigation.json` contains a `$ref` to `config/tool-pages.json`, but the active manifest in this checkout is `docs/docs.json`. Keep `docs/docs.json` synchronized unless the site is intentionally migrated to consume the navigation fragment.
</Warning>

## Generated MCP tool pages

`docs/scripts/generate-mcp-tool-pages.ts` rebuilds tool docs from the Rust tool schema registry.

### Inputs and outputs

| Path | Role |
| --- | --- |
| `rust/cloud-storage/ai_tools` | Rust crate used to build and run the schema generator. |
| `rust/cloud-storage/ai_tools/src/bin/gen_tool_schemas.rs` | Binary that writes `schemas/tools.json`. |
| `rust/cloud-storage/ai_tools/schemas/tools.json` | Intermediate generated schema file, ignored by `rust/cloud-storage/.gitignore`. |
| `docs/AI/mcp/tools/*.mdx` | Generated MDX pages and generated index page. |
| `docs/config/tool-pages.json` | Generated route list for tool navigation. |
| `docs/docs.json` | Active navigation manifest that must expose generated pages. |

### Generation lifecycle

<Steps>
<Step title="Build the Rust schema binary">

The script runs Cargo from `rust/cloud-storage` with offline SQLx mode:

```bash
SQLX_OFFLINE=true cargo build --bin gen_tool_schemas
```

</Step>

<Step title="Regenerate the schema JSON">

The script removes `rust/cloud-storage/ai_tools/schemas`, then executes the compiled `gen_tool_schemas` binary from `rust/cloud-storage/ai_tools`.

Expected binary output:

```text
Generated ai_tools/schemas/tools.json
```

</Step>

<Step title="Rewrite generated MDX pages">

The script deletes and recreates `docs/AI/mcp/tools/`, sorts schemas by `name`, slugifies each tool name, writes one page per tool, and writes `docs/AI/mcp/tools/index.mdx`.

</Step>

<Step title="Rewrite the generated page list">

The script writes `docs/config/tool-pages.json` with routes such as:

```json
[
  "AI/mcp/tools/index",
  "AI/mcp/tools/content-search"
]
```

</Step>
</Steps>

### Slug and page rules

| Rule | Behavior |
| --- | --- |
| Sorting | Tool schemas are sorted with `name.localeCompare`. |
| Slug conversion | CamelCase boundaries become hyphens; underscores and whitespace become hyphens; output is lowercase. |
| Page title | Uses the tool schema `name`. |
| Page description | Uses the tool schema `description`, or `Generated from the Macro Rust tool registry.` |
| Parameters table | Built from `inputSchema.properties`; required fields come from `inputSchema.required`. |
| Output schema | Loaded but not rendered into the generated MDX pages. |

Example generated route mapping:

| Tool name | Route |
| --- | --- |
| `ContentSearch` | `/AI/mcp/tools/content-search` |
| `text_editor_code_execution` | `/AI/mcp/tools/text-editor-code-execution` |
| `web_fetch` | `/AI/mcp/tools/web-fetch` |

## Updating MCP documentation after Rust tool changes

Use this checklist when a Rust tool name, schema, field, or description changes.

<Steps>
<Step title="Update the Rust tool schema source">

Edit the Rust tool definition, schema annotations, or tool registry entry that owns the tool behavior.

</Step>

<Step title="Regenerate docs">

```bash
cd docs
bun run generate:tools
```

</Step>

<Step title="Review generated diffs">

Check these paths first:

```text
docs/AI/mcp/tools/
docs/config/tool-pages.json
```

If a tool was added, removed, or renamed, update the Tool Reference page list in `docs/docs.json`.

</Step>

<Step title="Validate local docs">

```bash
bun run lint
bun run dev
```

Open the local preview and verify the MCP overview, Tool Reference index, and the changed tool page.

</Step>
</Steps>

## Broken-link checks

`bun run lint` runs `mint broken-links`. Use it after:

- adding, moving, or deleting an MDX page;
- changing `docs/docs.json` navigation;
- regenerating MCP tool pages;
- changing root-relative links;
- changing changelog output.

If `mint broken-links` fails after generated tool changes, check for one of these causes:

| Symptom | Likely cause | Fix |
| --- | --- | --- |
| Tool page exists but is missing from sidebar | `docs/docs.json` was not updated | Add the route under the Tool Reference group. |
| Sidebar route points to a deleted file | Tool was renamed or removed | Remove or replace the stale route in `docs/docs.json`. |
| Link works in generated index but not navigation | `config/tool-pages.json` and `docs/docs.json` diverged | Sync the active manifest. |
| CLI fails before checking links | Unsupported Node runtime | Switch to Node 20 or Node 22 and rerun. |

## Writing conventions

Documentation files are MDX with YAML frontmatter. Follow the repository’s current contribution and agent guidance:

| Convention | Rule |
| --- | --- |
| Voice | Use active voice. |
| Reader address | Use second person in procedures. |
| Sentences | Keep sentences concise; one idea per sentence. |
| Headings | Use sentence case. |
| UI labels | Bold UI labels, for example **Settings**. |
| Technical identifiers | Use code formatting for file names, commands, paths, and code references. |
| Terminology | Do not alternate between synonyms for the same product concept. |
| Examples | Include concrete examples when documenting behavior or commands. |

Use existing nearby pages as the shape reference. Product pages live under `docs/product/`, MCP setup lives under `docs/AI/mcp/`, and generated tool reference pages should not be manually polished in place because the generator rewrites them.

## Changelog generation

`docs/scripts/generate-changelog.ts` is separate from the MCP generator. It fetches GitHub releases for `macro-inc/macro`, keeps tags matching `vYYYY.M.D.N`, rewrites `docs/changelog/introduction.mdx`, and rewrites the `Changelog` tab in `docs/docs.json`.

Operational constraints:

- It uses `GITHUB_TOKEN` when present.
- It can also rely on GitHub CLI authentication according to its file header.
- It removes old per-release MDX files in `docs/changelog/` except `introduction.mdx`.
- It escapes unsupported MDX angle brackets before writing release bodies.

Run it only when intentionally refreshing changelog content from GitHub releases.

## Deployment configuration

For Mintlify’s monorepo setup, configure the docs path as:

```text
/docs
```

Keep deployment-facing changes inside `docs/` unless the generated MCP pages require Rust schema changes. The docs project is independent from model-provider configuration: MCP reference generation reads repository-local Rust schemas and does not require an AI provider key.

## Related pages

<CardGroup cols={2}>
  <Card title="MCP setup" href="/AI/mcp/overview">
    Connect AI clients to the Macro MCP endpoint.
  </Card>
  <Card title="Tool reference" href="/AI/mcp/tools">
    Browse generated MCP tool pages.
  </Card>
  <Card title="Development" href="/development">
    Preview and validate the Mintlify site locally.
  </Card>
  <Card title="Changelog" href="/changelog/introduction">
    Review release notes generated from GitHub releases.
  </Card>
</CardGroup>