Skip to main content

​
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: 
---
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 ---): 
{/* lint-frontmatter-disable: <one-line reason> */}
Use sparingly. The lint output lists every opt-out so they stay visible.