​

Docs

​

Audience

• Community admins and managers (Docs tab): setting up and running a community.
• Developers (API and Webhooks tabs): integrating through the API and webhooks.

​

Commands

• mise install: install the pinned Node and pnpm.
• pnpm install: install dependencies, including mint.
• pnpm dev: preview locally at localhost:3000 (mint dev).
• pnpm validate: validate docs.json and build the docs (mint validate). Run before every commit.
• pnpm broken-links: find broken internal links (mint broken-links). Run before every commit.
• Other CLI commands: pnpm exec mint <command>.

​

Project structure

• docs.json: all site config: theme, branding, navigation, navbar, footer. Single source of truth for navigation.
• mise.toml, package.json, pnpm-lock.yaml, pnpm-workspace.yaml: tooling. Commit the lockfile.
• *.mdx pages: content. Each page must be listed in docs.json navigation or it won’t appear in the sidebar.
• images/: static assets, referenced with root-relative paths (/images/...).
• api/v1/: API pages (the API tab), starting with api/v1/overview.mdx. One page per resource.
• webhooks/: webhook pages (the Webhooks tab), starting with webhooks/overview.mdx. One page per event.

​

Configuration (docs.json)

• Keep it valid against the schema: "$schema": "https://mintlify.com/docs.json" should be the first key.
• Page entries in navigation are paths without the .mdx extension and without a leading slash ("guides/setup").
• Group related pages under group and keep nesting shallow (tabs > groups > pages; avoid deeper unless needed).
• Every tab, group and menu item gets a short, sentence-case label.
• Whenever you add, move, rename or delete a page, update docs.json in the same change.
• When renaming or moving a page, add a redirects entry ({ "source": "/old", "destination": "/new" }) so existing links and bookmarks keep working.
• Keep branding values (colours, logos, fonts) in docs.json. Don’t override them with inline styles in pages.

​

Writing pages

​

Frontmatter

---
title: "Set up your community"
description: "Create and brand your organisation's community on Zapnito."
---

• title is required. Make it specific and unique; avoid generic titles like “Introduction” except for the first page of a section, and never duplicate a title across pages.
• description is required: one sentence, under ~160 characters. It is used for SEO and link previews.
• Optional: sidebarTitle (shorter sidebar label), icon, tag (e.g. "New"). Use them sparingly.
• Don’t add an # H1 in the body. Mintlify renders title as the H1. Start body headings at ##.

​

Style

• Task-oriented: lead with what the reader can do, then how.
• Second person (“you”), active voice, present tense, sentence-case headings.
• Short paragraphs; prefer numbered steps for procedures and bullets for lists of options.
• Use descriptive heading text. Headings generate anchors, so don’t rename them casually: that breaks inbound links.
• Name UI elements exactly as they appear in the product, in bold.
• Don’t use “click here” link text. Link text should describe the destination.
• Don’t document unreleased or unconfirmed features.

​

Links

• Internal links are root-relative with no extension: [Webhooks](/developers/webhooks). No .mdx, no relative ../ paths, no absolute URLs to our own docs domain.
• External links use full https:// URLs.
• Run pnpm broken-links after any link or file change.

​

Images and media

• Store files in images/; reference as /images/<name>.png.
• Always write meaningful alt text. Decorative images are the only exception.
• Use kebab-case, descriptive filenames (community-branding-settings.png). Existing logo files are the exception.
• Prefer .png/.svg/.webp; keep files reasonably small. Provide light and dark variants for images with a background that clashes with the theme (the site defaults to dark mode).
• Wrap images in <Frame> when they are screenshots.
• Never include real customer data, member names, emails or API keys in screenshots or examples.

​

Components

• Don’t overuse callouts. More than one or two per page loses their weight.
• Don’t nest components deeply.
• Reuse repeated content with snippets (put in a snippets/ directory and import) rather than copy-pasting.

​

Code samples

• Always set a language on fenced code blocks (```bash, ```json, ```javascript).
• Add a title to code blocks where the filename or purpose matters.
• Use <CodeGroup> for the same example in multiple languages, with curl first.
• Use obvious placeholders (YOUR_API_KEY, https://your-community.zapnito.com), never real credentials.
• Examples must be complete and runnable as written.

​

MDX gotchas

• Curly braces {} and < in prose are parsed as JSX. Wrap literals in backticks or escape them.
• Blank line required between a component tag and Markdown content inside it.
• Self-close void components (<Card ... />), and always close everything else.
• HTML comments (<!-- -->) break MDX. Use {/* comment */}.

​

API reference (API tab)

• If we add an OpenAPI spec, reference it from docs.json and let Mintlify generate endpoint pages instead of hand-writing them. Keep the spec in the repo and validate with mint openapi-check.
• Document authentication, rate limits, pagination and error formats once, and link to them from endpoint pages.
• Webhook pages should list each event and its payload.

​

Before you commit

1. pnpm validate passes.
2. pnpm broken-links reports nothing.
3. Every new or moved page is in docs.json navigation (and has a redirect if moved).
4. Every page has title and description, and every image has alt text.
5. Previewed the page in both light and dark mode with pnpm dev.