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

# AUTHORING

# Docs authoring spec

Everything here is enforced by `pnpm lint-frontmatter`. A PR that touches any `.mdx` under `docs/` fails CI if the changed files don't conform.

Mintlify's built-in search ranks pages on four signals: `title`, `description`, `keywords`, and body text. Getting the first three right is the difference between "users find what they need in one search" and "users give up and open a support ticket". Treat frontmatter as a search surface, not metadata.

## Required frontmatter

Every page — content pages and API reference alike — must ship this frontmatter:

```yaml theme={"dark"}
---
title: 'Zendesk overview'
sidebarTitle: 'Overview'
description: 'Run Zendesk as the surface your agents work in while OpenCX resolves, routes, and grounds every conversation in your Help Center.'
icon: 'ticket'
keywords:
  - zendesk
  - zendesk integration
  - zendesk handoff
  - connect zendesk
  - zd tickets
  - help center sync
  - sunshine conversations
  - zendesk 401
---
```

### `title` — unique, descriptive

* **Never** a bare word from this denylist: `Overview`, `Troubleshooting`, `Connect`, `Index`, `Introduction`, `Get started`, `Configuration`, `Setup`.
* Format: `<Product or Feature> <Page type>` — e.g. `Zendesk overview`, `Notion troubleshooting`, `Shopify connect`, `Voice agent introduction`.
* The title is what Mintlify's search results show. Two pages titled `Overview` are indistinguishable to a searching user.
* Use `sidebarTitle` if you want the sidebar to stay short (`Overview`); it doesn't affect search ranking.

### `description` — 120–160 chars, "what + when"

* Answer two questions: *what does this page do* and *when should I read it*.
* Example: `Connect Zendesk as a knowledge source to sync help center articles and tickets into OpenCX agents. Use when onboarding an existing Zendesk account.`
* Shows up in search results underneath the title and as the `<meta description>` for SEO.
* Hard lint range: 80–200 chars. Target range: 120–160.

### `keywords` — 8–15 entries, four categories

Pick from these buckets — at least one entry from each of the first three:

1. **Product / aliases (2–3)** — product name + common abbreviations or misspellings. `zendesk`, `zd`, `zen desk`.
2. **Task phrases (2–3)** — verbs a user would type. `connect zendesk`, `sync zendesk tickets`, `zendesk oauth`.
3. **Synonyms (2–3)** — alternate terminology. `help desk integration`, `ticket sync`, `zendesk crm`.
4. **Error / failure terms (1–2, when relevant)** — symptoms users search when something breaks. `zendesk 401`, `subdomain invalid`, `token expired`.

Rules of thumb:

* **Don't duplicate keywords from a parent page.** If `integrations/zendesk/overview.mdx` already owns `zendesk integration`, don't repeat it on `integrations/zendesk/channels/email.mdx` — that page should own `zendesk email`, `zendesk email channel`, etc.
* **Don't over-keyword.** More than 20 entries dilutes ranking.
* **Use phrases, not single words, for specificity.** `zendesk email` beats `email` in a large corpus.
* **Mirror real user language.** Steal phrasing from support tickets, Slack questions, competitor docs.

## Author PR checklist

Paste into your PR description:

* [ ] `title` unique and descriptive (not bare `"Overview"` / `"Troubleshooting"`)
* [ ] `description` 120–160 chars, answers *what + when*
* [ ] `keywords` 8–15 entries with ≥1 alias, ≥1 task phrase, ≥1 synonym
* [ ] Searched the page title + 2 alternate phrases in `pnpm dev` and confirmed top-3 ranking
* [ ] No keyword overlap with parent / sibling pages that would dilute ranking

## Tools

* `pnpm dev` — run Mintlify locally on port 3009 and test search interactively.
* `pnpm lint-frontmatter` — runs the frontmatter lint. Fails on missing title/description/keywords, denylisted titles, and out-of-range description lengths.
* `pnpm lint-frontmatter:fix` — auto-patches trivially-fixable cases (e.g. adds `sidebarTitle` when rewriting `title`).
* `pnpm suggest-frontmatter -- <path/to/file.mdx>` — prints a suggested keyword set and rewritten title for one page.
* `pnpm suggest-frontmatter -- --missing-only` — lists every file currently missing `keywords`.
* `pnpm enrich-api-stubs -- <path/to/api-reference/xxx.mdx>` — fills in a stub API page from the OpenAPI spec.
* `pnpm benchmark-search` — runs the 25-query benchmark against `http://localhost:3009` and prints a scorecard.

## Opt-out

For the rare page where the rules genuinely don't apply (landing page, coming-soon stub), add this comment as the very first line of the MDX body (after the closing `---`):

```mdx theme={"dark"}
{/* lint-frontmatter-disable: <one-line reason> */}
```

Use sparingly. The lint output lists every opt-out so they stay visible.