Rules

File and folder naming

• Use kebab-case for all new route files and folders. Examples: getting-started, api-reference, quick-start, release-notes.
• Use folder segments ending in + for nested URL groups. Example: guides+/integrations+/webhooks.mdx.
• Do not introduce camelCase route files (apiReference, quickStart, releaseNotes). Our repositories use kebab-case for documentation files and assets.
• Do not add new content under legacy mixed-case folders such as Images/, Files/, or any folder using a previous casing convention. Migrate the old structure rather than growing it.
• Keep each MDX route responsible for one page type. Split large mixed pages instead of adding more headings.
• Watch filenames for typos. Once a typo lands in a route it shows up in URLs, link text, and search results, and is hard to remove without breaking inbound links. Fix typos in filenames the first time you touch the file.

---
title: API Reference
---

# {frontmatter.title}

- [Authentication](/api-reference/authentication)
- [Users](/api-reference/users)
- [Webhooks](/api-reference/webhooks)

Frontmatter

• Every MDX page starts with frontmatter that declares a title.

  ---
  title: Quick Start
  ---

• Use # {frontmatter.title} as the page H1. Do not hard-code a different H1 and let it drift from frontmatter.

• Pages intentionally hidden from navigation may add hidden: true to their frontmatter.

Headings

• One H1 per page (always the frontmatter title).
• H2 sections cover the main reader tasks or topics.
• H3 and H4 only when they add useful hierarchy. Do not skip heading levels.
• Do not create headings for decorative grouping or as a substitute for explanation.
• Do not add a manual list of H2-H4 headings. The site renders its own table of contents.
• Banned weak heading text: Screenshot, UI, Details, Below Steps, Important Notes, Steps.
• Good heading text: ## Prerequisites, ## Authenticate the request, ## Verify the response, ## Troubleshoot rate-limit errors.
• Keep headings brief. A heading introduces a section; the detail belongs in the paragraphs within. Do not paste a full sentence or question into the heading.
• Do not style heading text with bold or italics. Use ## My Heading, not ## **My Heading**.
• Do not end heading text with : or other trailing punctuation. The colon is implied.

Avoid (too wordy):

## When the API returns a 429 status code, what does the rate limit reset value mean and how do I calculate when I can retry the request?

Same information, easier to scan:

## How is the rate-limit reset value calculated?

Detail goes in the paragraphs below the heading.

MDX formatting

• Do not add <br> or <br /> tags. QUI Docs handles vertical spacing automatically. Extra <br> tags compound the spacing and break the visual rhythm.
• Do not use inline HTML style attributes or wrap content in styled <div> blocks to force layout. Let the doc theme render consistently across pages.
• Do not use emojis anywhere in docs content. AI-generated copy is often flagged by an overuse of emojis; write plainly without them.

Links

• Use root-relative links for docs pages: /api-reference/users/list-users. Do not use relative paths or old-style absolute paths.
• Use descriptive link text that names the target task, concept, or reference.
• Banned link text: click here, below, this page, more details.
• Do not link to pages that have been replaced by compatibility .ts redirects.
• Do not use old casing or old route spellings from prior routing conventions in new content.
• After moving a page, update every inbound link you touch in the same PR.

Navigation (qui-docs.config.ts)

• Add a page to qui-docs.config.ts when its order, nesting, or visibility matters.
• Keep sidebar labels aligned with page titles and route names.
• Use overview pages only when they explain what a section is about. Do not list sibling routes or repeat the sidebar.
• Prefer stable, predictable section order over alphabetical accidents.
• Collapse deep groups by default unless the section is central to the reader's current workflow.

Assets

• Use lower-case asset root folders: assets/images and assets/files.
• Use kebab-case directory and file names.
• Group assets by documentation area, mirroring the structure of your routes. Examples: images/getting-started/quick-start, images/api-reference/authentication.
• Rename imported or linked image paths when an asset moves.
• Do not add new assets under mixed-case folders such as Images or Files.
• All screenshots in .png format, with lowercase filenames.

When adding a screenshot:

• Name the file for the state or action it shows: connection-error-state.png, users-list-filters.png.
• Place it near the text that explains it.
• Write alt text that describes the state or action, not "screenshot".
• Explain what the reader should notice in the surrounding prose.
• Remove screenshots that only show obvious navigation or button placement.

Recommended dimensions:

• Full-screen screenshots: 1880 × 1025 px.
• Dialog or small-component screenshots: 950 × 450 px.
• Minimum width 900 px to avoid blurring.
• Highlight color: #FF0000, 2 px solid, 4-8 px padding.
• Alt text starting with UI- inherits global CSS that stretches the image to 100 % width.

Terminology

Use the same term every time. Inconsistent terminology hurts search and makes procedures feel unreliable.

Universal rules — apply on every page:

Acronyms stay fully capitalized in prose. Multi-word names use their canonical casing (JavaScript, not javascript; OAuth, not Oauth).

For product-specific terms — feature names, object types, status values, system names — maintain a glossary in your product's docs repository or style guide. Pick one spelling per term and use it everywhere. When the UI literally shows a different label, quote the UI label when needed but use the canonical term in surrounding prose.

Writing mechanics

Use:

• Active voice.
• Present tense.
• Specific nouns.
• Short paragraphs.
• Imperative steps for procedures.
• Exact UI labels, field names, commands, statuses, and file names.

Avoid:

• below, above, here, and this when a direct name is clearer.
• please in procedural steps.
• user can when the step should be a direct command.
• as per, kindly, same, and other vague internal phrasing.
• Unexplained acronyms.
• Chat or IRC shorthand (pls, u, thx, refer :). Write complete sentences with proper punctuation — docs are not a Teams thread.
• Emojis.
• Unreviewed spelling and grammar errors. Run a spell-check and proofread before opening the PR; broken grammar forces readers to guess the technical meaning.

Banned opening phrases: This page contains..., The below..., This document explains.... Open with what the page helps the reader do.

Weak (chat shorthand):

More details pls refer :

Better (complete sentence):

For more details, see Authentication setup.

Examples must prove the workflow

Examples use realistic values. Developers copy-paste and adapt what they see.

Do not ship placeholder-only examples:

{
  "status": "string",
  "message": "string"
}

Ship examples that look like real responses:

{
  "userId": "usr_8f3d2a1b9c4e",
  "status": "active",
  "createdAt": "2026-05-08T14:23:11Z"
}

For UI tasks, include what object the reader starts with, what values they enter, and what result confirms success. For API or CLI tasks, include authentication/setup assumptions, the smallest working request, a successful response, at least one common error response, and how to store or reuse returned identifiers.

Every code snippet must run or compile without errors. Paste the snippet into a real environment, run it, and confirm the output before committing. Do not ship snippets that you have not executed — broken examples damage trust faster than missing examples.

API, CLI, and integration pages

Use this canonical order unless the page has a strong reason not to:

1. What the integration does.
2. Who should implement or call it.
3. Prerequisites and authentication.
4. Minimal working request or command.
5. Successful response.
6. Required fields and valid values.
7. Error handling.
8. Versioning, compatibility, or support notes.
9. Full reference tables or generated details.

If generated reference material is large, put the usage path first and move the generated dump behind it or to a separate reference page.

Compatibility routes

• Keep compatibility .ts modules small. They redirect or delegate, they do not duplicate page content.
• Remove the stale .mdx after the new page exists and the compatibility route is in place.
• Do not link to pages that are now .ts redirects — link to the new canonical route.

Reviewer rejection gates

A reviewer rejects the page when:

• It is only a screen tour (names a UI page, shows screenshots, explains obvious controls, and teaches no task, workflow, capability, troubleshooting path, concept, field/state set, recipe, or decision).
• It does not name its page type — the first paragraph opens with This page contains... or The below....
• It hides prerequisites, uses screenshots as the main content, includes placeholder examples, duplicates another page, or links to stale content.
• A new developer could not complete the documented work without asking the author for context.

A reviewer approves the page when a new developer can complete the documented work without asking the author for context, and an experienced developer can scan the page to find the field, status, command, API behavior, or failure mode they need.

Author self-check (reviewer checklist)

Before opening the PR, confirm each item:

• Page has one clear primary type.
• First paragraph states the reader value.
• Prerequisites are explicit.
• Steps produce a visible, testable, or inspectable result.
• Examples use realistic values, not "string" placeholders.
• Every code snippet has been run or compiled and confirmed error-free.
• Screenshots support the text instead of replacing it.
• H2-H4 headings are meaningful, brief, and do not repeat a manual ToC.
• No bold, italics, or trailing : in heading text.
• No <br> tags or inline HTML styling.
• No emojis in page content.
• Spelling and grammar are proofread; no chat shorthand.
• Terminology matches the canonical glossary; acronyms use canonical casing.
• Links are root-relative and use descriptive text.
• Filenames and routes are kebab-case, no camelCase, no typos.
• No section index.mdx pages. Use a sorted overview.mdx page only when it explains what the section is about.
• Frontmatter has title and H1 is # {frontmatter.title}.
• No duplicate page exists under another route.
• Page explains side effects, permissions, and failure modes when relevant.
• Page is short enough to maintain, or has been split by task, workflow, capability, or reference area.

Agentic Workflows

We provide agentic plugins that enforce these guidelines. Refer to the following for details:

• Claude Code
• Codex