​

Mintlify documentation

​

Working relationship

• You can push back on ideas-this can lead to better documentation. Cite sources and explain your reasoning when you do so
• ALWAYS ask for clarification rather than making assumptions
• NEVER lie, guess, or make up information

​

Project context

• Format: MDX files with YAML frontmatter
• Config: docs.json for navigation, theme, settings
• Components: Mintlify components

​

Content strategy

• Document just enough for user success - not too much, not too little
• Prioritize accuracy and usability of information
• Make content evergreen when possible
• Search for existing information before adding new content. Avoid duplication unless it is done for a strategic reason
• Check existing patterns for consistency
• Start by making the smallest reasonable changes

​

docs.json

• Refer to the docs.json schema when building the docs.json file and site navigation

​

Frontmatter requirements for pages

• title: Clear, descriptive page title
• description: Concise summary for SEO/navigation
• og:image / twitter:image: do NOT hand-edit. The OG image workflow manages them (see below)

​

OG images (per-page social previews)

• Each page gets a 2400×1260 social preview rendered from scripts/og/template.html using its frontmatter title and description.
• The .github/workflows/og-images.yaml CI workflow runs on every PR that touches MDX or the generator, regenerates affected PNGs in images/og/, injects og:image and twitter:image into the page’s frontmatter, and commits the result back to the PR branch as github-actions[bot]. Authors do not run anything locally. Edit the page’s title/description and push.
• If the bot’s commit doesn’t appear on your PR, check the Action logs (most likely a permissions or fork issue).
• Local preview (optional, e.g. when iterating on the template):
  cd scripts/og
  npm install
  npx playwright install chromium
  node generate.mjs path/to/page.mdx           # one or more pages
  node generate.mjs --all                       # regenerate everything
  node generate.mjs --all --check               # dry-run, exits 1 if stale
  
• macOS-rendered PNGs differ slightly from CI’s Linux-rendered ones; CI is canonical. Don’t worry about local/CI byte differences. The next CI run normalizes them.
• Template / design changes go in scripts/og/template.html. Touching it triggers a full regeneration on the next PR.
• Pages without a frontmatter title (snippets, includes) are skipped automatically. The global og:image in docs.json remains as a fallback.

​

Writing standards

• Second-person voice (“you”)
• Prerequisites at start of procedural content
• Test all code examples before publishing
• Match style and formatting of existing pages
• Include both basic and advanced use cases
• Language tags on all code blocks
• Alt text on all images
• Relative paths for internal links

​

Writing guidelines

Adapted from Vercel’s writing guidelines. Use MUST/SHOULD/NEVER to guide decisions. Where a rule below conflicts with the sections above, the sections above win.

​

Planning

• MUST: Plan before writing (overview, goal, audiences, documentation plan, open questions)
• MUST: Decide the content type before writing: Tutorial, How-to, Reference, Conceptual, Troubleshooting, or Landing. The type drives the shape of the page
• MUST: Title is user-shaped (the user’s question), not feature-shaped
• MUST: Define every term on first use; link to its conceptual page
• SHOULD: Goal uses a Bloom’s taxonomy verb (configure, explain, debug)
• MUST: One page does one job (tutorial OR how-to OR reference, not all three)

​

Voice & tone

• MUST: Active voice. Test: append “by monkeys”. If the sentence parses, rewrite
• MUST: Direct address: you. Never the user or one can
• MUST: Imperative for steps (“Click Add Project”, not “You will need to click…”)
• SHOULD: Sentences under 20 words
• SHOULD: Contractions (you'll, it's)
• MUST: Present tense unless describing future behavior
• NEVER: we as a stand-in for you (only for deliberate Tensorlake actions, such as “we recommend”)
• NEVER: easy, simple, quick
• NEVER: Filler words: very, just, really, simply
• NEVER: Rhetorical questions
• MUST: Second-read test: each sentence parses on one read at speech pace; name the subject, action, and consequence (kill metaphor verbs and far-reaching pronouns)

​

Concision

• MUST: Earn every detail; cut a number, name, or implementation detail that wouldn’t change the reader’s understanding or action
• NEVER: Weasel words (significantly, many, often, typically, generally); give a specific number or claim
• NEVER: Vague quantifiers (near-zero, sub-second, most requests); give the figure and cite it
• NEVER: Filler/metaphor verbs (moves through, lands, carries, hits); name the literal step

​

AI-generated tells

• NEVER: Summary-style transitions recapping the previous paragraph (With this setup complete…); pivot to the next point
• NEVER: Stop-start fragments splitting one dependent idea into choppy sentences
• NEVER: Spec-sheet voice reading like a datasheet (provides, is configurable, is explicitly labeled)
• NEVER: Cold-open body paragraphs with no antecedent; carry the prior subject forward
• NEVER: Personified artifacts performing human-physical actions (hand the browser a URL → the browser fetches the URL)
• NEVER: Reused/template framing not specific to the page (The question most teams face is whether…)

​

Tone, by content type

• Tutorial: warm, encouraging, predictable structure
• How-to: terse, direct (reader is mid-task)
• Reference: neutral, exhaustive, quotable
• Conceptual: explain like the reader will teach it back
• Troubleshooting: empathetic but not apologetic

​

Headings & structure

• MUST: Sentence case for page headings (H1 through H6)
• MUST: Title case for nav labels in docs.json
• MUST: Subheadings descriptive (Caveats when self-hosting on Cloudflare, not Caveats)
• MUST: Every page opens with a TL;DR paragraph
• MUST: Every major section opens with a summary sentence
• MUST: Acronyms spelled out on first use (Content Security Policy (CSP))
• MUST: Keep paragraphs to 2 to 4 sentences; split anything longer or covering two ideas

​

Lists

• MUST: Three or more list-shaped items convert to a list
• MUST: Always introduce a list with a colon
• MUST: Bold/description format: - **Term**: description
• NEVER: Periods on list items unless they’re full sentences

​

Code

• MUST: Language tag on every code block
• MUST: Wrap multi-step flows in <Steps>
• SHOULD: ≤80 columns per line; ≤25 lines per snippet (split with prose)
• SHOULD: Highlight load-bearing lines (```python {8-12})
• MUST: Explain what each code block does in prose
• NEVER: Reference “see the full example file” at the end of a guide

​

Placeholders, units, & numbers

• MUST: Text placeholders are snake_case, descriptive (your_access_token_here)
• MUST: Number placeholders count up (1234567890123)
• NEVER: <TOKEN>, xxx, your-token, ABC123
• MUST: Data sizes have a space and uppercase unit (64 KB, 200 ms)
• MUST: Seconds bare (30s)
• MUST: Numerals for counts (8 deployments, not eight)

​

Typography

• NEVER: Em dashes (—) or dashes (-) as punctuation. Use colons, commas, periods, or rephrase
• MUST: Curly quotes (“ ” ‘ ’) in prose, not straight
• MUST: Ellipsis character (…), not three dots (...)
• MUST: Loading states end with … (Loading…, Saving…)
• MUST: Non-breaking spaces for glued terms (10 MB, ⌘ K, brand names)
• SHOULD: & over and only where space-constrained

​

Source formatting

• NEVER: Hard-wrap paragraphs (each paragraph is one line in source)
• MUST: One blank line before headings; before and after code blocks
• NEVER: --- horizontal rules between sections

​

Emphasis

• MUST: Bold for UI elements or critical facts only, never for emphasis
• MUST: Inline code for paths, file extensions, identifiers, short snippets (/api, .tsx, body)

​

Links

• MUST: Define every term on first appearance; link to its conceptual page
• MUST: Anchor text names the destination
• NEVER: Bare URLs or here/link as anchor text

​

Pricing & money pages

• MUST: Use tables for pricing
• MUST: Document the pricing model explicitly
• NEVER: Assume the reader knows what counts as one invocation

​

Review

• MUST: PR description links the plan, lists what to review, links the preview URL
• MUST: Author is accountable; reviewers liberal with approvals
• SHOULD: Suggestion comments for small fixes; preview comments for bigger feedback

​

Git workflow

• NEVER use —no-verify when committing
• Ask how to handle uncommitted changes before starting
• Create a new branch when no clear branch exists for changes
• Commit frequently throughout development
• NEVER skip or disable pre-commit hooks

​

Do not

• Skip frontmatter on any MDX file
• Use absolute URLs for internal links
• Include untested code examples
• Make assumptions - always ask for clarification