From 4a94247b890a76d99fa8a39eca913349f38ee360 Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Thu, 24 Sep 2026 10:30:48 -0700 Subject: [PATCH 01/14] style-guide: scaffold internal style guide and exclude it from the site Co-Authored-By: Claude Opus 5.5 (1M context) --- .mintignore | 3 +++ style-guide/README.md | 32 ++++++++++++++++++++++++++++++++ 2 files changed, 35 insertions(+) create mode 100644 style-guide/README.md diff --git a/.mintignore b/.mintignore index 9f4349f4bf..7ea747736a 100644 --- a/.mintignore +++ b/.mintignore @@ -1,2 +1,5 @@ # Internal tooling that compiles context for external agent plugins. agent-context/ + +# Internal style guide for people and agents. Not published. +style-guide/ diff --git a/style-guide/README.md b/style-guide/README.md new file mode 100644 index 0000000000..f92f81c148 --- /dev/null +++ b/style-guide/README.md @@ -0,0 +1,32 @@ +# Mintlify docs style guide + +> **Status: outline for review.** Items tagged `[needs Ethan]` are open decisions. Source tags get removed when this is written as prose. + +This guide is for anyone writing or editing content in this repo, people and agents alike. It covers the docs site: pages, the changelog, and help center articles. It does not cover product UI copy or marketing. + +## How to use this guide + +1. Follow the [Google developer documentation style guide](https://developers.google.com/style) for anything this guide doesn't cover. +2. When this guide and Google's disagree, this guide wins. Every rule here is either a Mintlify-specific decision or a place where we deviate from Google. +3. [Vale](../.vale.ini) enforces a subset of these rules on `.mdx` files. A clean Vale run doesn't mean a page follows the guide. + +## Files + +| File | Covers | +| --- | --- | +| [voice-and-tone.md](voice-and-tone.md) | How Mintlify docs sound, phrases to cut, AI-writing tells | +| [word-list.md](word-list.md) | Product terms, capitalization, preferred and avoided words | +| [formatting-and-components.md](formatting-and-components.md) | Markdown conventions and when to use each Mintlify component | +| [content-strategy.md](content-strategy.md) | What to document, where it goes, and how to keep it maintainable | + +## For agents + +- Read this file, then the files relevant to your change. +- Only edit English content. Translations in `es/`, `fr/`, and `zh/` are generated after merge. +- Before opening a PR, run the checks in [.claude/CLAUDE.md](../.claude/CLAUDE.md#before-submitting-work). + +## Changing the guide + +Open a PR that edits the relevant file. If a rule should be enforced, update or add the matching Vale rule in `.vale/styles/Mintlify/` in the same PR. Narrow a Vale rule rather than rewriting correct prose to satisfy it. + +Portions adapted from the Google developer documentation style guide are used under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/). From 7dc9954882b5e3d271c1fc5e86a0b3304d56914c Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Thu, 24 Sep 2026 10:32:16 -0700 Subject: [PATCH 02/14] style-guide: add outline for review with sourced rules and open decisions Co-Authored-By: Claude Opus 5.5 (1M context) --- style-guide/content-strategy.md | 56 ++++++++++++++++++ style-guide/formatting-and-components.md | 73 ++++++++++++++++++++++++ style-guide/voice-and-tone.md | 60 +++++++++++++++++++ style-guide/word-list.md | 43 ++++++++++++++ 4 files changed, 232 insertions(+) create mode 100644 style-guide/content-strategy.md create mode 100644 style-guide/formatting-and-components.md create mode 100644 style-guide/voice-and-tone.md create mode 100644 style-guide/word-list.md diff --git a/style-guide/content-strategy.md b/style-guide/content-strategy.md new file mode 100644 index 0000000000..dab478babd --- /dev/null +++ b/style-guide/content-strategy.md @@ -0,0 +1,56 @@ +# Content strategy + +> **Outline for review.** Tags work the same as in [voice-and-tone.md](voice-and-tone.md). + +Google's guide mostly covers sentences, not strategy, so most of this file is Mintlify-specific. + +## Just enough docs + +- Document what readers need to succeed, and nothing more. Too much content hides what people are looking for. `[existing: CLAUDE.md]` +- Don't accept edits made purely for tone, readability, or efficiency, and don't cover niche preference topics. `[existing: CONTRIBUTING.md]` `[needs Ethan: does this apply to internal authors too, or only outside contributors?]` + +## Before you write + +- Search for existing content first. Extend an existing page rather than create a new one, unless the new page serves a distinct task. `[existing: CLAUDE.md]` +- Duplicate content only for a deliberate reason. When the same fact is needed in more than one place, put it in a snippet. `[existing: CLAUDE.md; snippet part is new, needs Ethan]` +- Make the smallest change that solves the problem. `[existing: CLAUDE.md]` + +## Where content goes + +- Put new pages in the nav group that matches the user journey, such as Customize or Deploy. `[existing: CLAUDE.md]` +- Order content by how often readers need it, most common first. `[existing: CLAUDE.md, Cursor rules]` +- Help center vs guides vs feature pages: when does something become a help center article? `[needs Ethan]` + +## Page structure + +- Lead with context: what something is and why you'd use it, then how. `[existing: CLAUDE.md]` +- Prerequisites go at the start of procedural pages. `[existing: CLAUDE.md]` +- Offer one opinionated path. Only show alternatives when readers genuinely choose between them. `[existing: Cursor rules]` +- Include a verification step or expected result for major procedures. `[existing: Cursor rules]` + +## Two audiences: web editor and CLI + +- When a task can be done both ways, cover both. Use tabs, or separate sections if the steps diverge a lot. `[needs Ethan: which is the default or first tab?]` +- Don't assume Git knowledge in web editor paths. `[existing: CLAUDE.md]` + +## Plan gating + +- If a feature requires a paid plan, add a one-sentence `` at the top of the page: "X requires a [Pro or Enterprise plan](https://mintlify.com/pricing?ref=x)." `[existing: practice, memory]` +- Verify gating against the pricing page and the code before you add or remove a callout. The pricing table is the public source of truth. `[existing: memory]` + +## Changes, moves, and deprecations + +- When you move or rename a page, add a redirect in `redirects.json`, which `docs.json` pulls in through `$ref`. `[existing: Cursor rules, corrected path]` +- Recent redirect PRs, such as fb5b7608b, also add `/es/`, `/fr/`, and `/zh/` entries by hand. Should authors add locale redirects, or does the translation workflow handle them? `[needs Ethan]` +- The Cursor rules say "for 18 months." Do we ever remove redirects? `[needs Ethan]` +- The Cursor rules say "'New' tags for two weeks." Is this still practiced? `[needs Ethan]` +- Remove deprecated features rather than keeping "deprecated" callouts, except during an announced migration window. `[new, needs Ethan]` +- Update screenshots when the UI changes. `[existing: Cursor rules]` + +## Changelog + +- Is the changelog in scope for this guide, and does it have its own conventions (entry format, tense, linking to docs)? `[needs Ethan]` + +## Translations + +- Only edit English. `es/`, `fr/`, and `zh/` are generated after merge. `[existing: AGENTS.md, CLAUDE.md]` diff --git a/style-guide/formatting-and-components.md b/style-guide/formatting-and-components.md new file mode 100644 index 0000000000..5eb51540f2 --- /dev/null +++ b/style-guide/formatting-and-components.md @@ -0,0 +1,73 @@ +# Formatting and components + +> **Outline for review.** Tags work the same as in [voice-and-tone.md](voice-and-tone.md). + +Google's defaults apply: [headings](https://developers.google.com/style/headings), [lists](https://developers.google.com/style/lists), [procedures](https://developers.google.com/style/procedures), [code in text](https://developers.google.com/style/code-in-text), [UI elements](https://developers.google.com/style/ui-elements), [link text](https://developers.google.com/style/link-text), [images](https://developers.google.com/style/images). This file covers MDX and Mintlify specifics. For component syntax, see the public [components docs](../components/). + +## Frontmatter + +- Every page needs `title` and `description`. `[existing: CLAUDE.md, Cursor rules]` +- **Conflict:** CLAUDE.md requires `keywords`, while the Cursor rules call it optional. In practice, 266 of 320 English pages have it. Proposal: required. `[needs Ethan]` +- `sidebarTitle` when the title is too long for the sidebar. `[existing: Cursor rules]` +- Icons come only from [Lucide](https://lucide.dev). `[existing: CLAUDE.md]` + +## Headings + +- Sentence case, no ending punctuation. `[existing: Vale Mintlify.Headings, Mintlify.HeadingPunctuation]` +- Start at H2. H1 is the page title. `[existing: Cursor rules]` +- Code block titles also use sentence case. `[existing: CLAUDE.md]` + +## Text formatting + +- Use bold for UI elements the reader interacts with: "Select **Save**." `[existing: Cursor rules, matches Google]` +- Only use bold or italics for emphasis when it helps comprehension. Never use emoji. `[existing: CLAUDE.md]` +- Use code format for filenames, commands, config keys, and values. `[existing: Cursor rules]` +- Use `` for keyboard shortcuts: Cmd + K. `[existing: Cursor rules]` +- Property descriptions end with a period. `[existing: CLAUDE.md]` +- Scope qualifiers go at the start of a description: "For Font Awesome icons only: ..." `[existing: CLAUDE.md]` + +## Links + +- Internal links use root-relative paths, like `/components/accordions`. Never use absolute mintlify.com URLs for internal links. `[existing: CLAUDE.md]` +- Link text describes where the link goes. Never use "click here." `[existing: Cursor rules, Google]` +- Don't put code formatting inside link text. `[existing: Cursor rules]` +- The Cursor rules say "Each link is an exit opportunity, use sparingly" and suggest "Further reading" sections. Google has no equivalent rule. Keep it? `[needs Ethan]` +- Plan links go to pricing with a `?ref=` parameter. `[existing: practice across 11 plan callouts]` + +## Code blocks + +- Every code block has a language tag. `[existing: CLAUDE.md]` +- Add a filename title when the reader needs to know which file the code goes in, such as ` ```json docs.json `. `[existing: Cursor rules]` +- **Conflict:** CLAUDE.md says "simple, one option when one will do," while the Cursor rules say "complete, runnable, with error handling and realistic data." Proposal: examples are runnable and minimal, with realistic values, and include error handling only when error handling is the topic. `[needs Ethan]` +- Never put real API keys in examples. `[existing: Cursor rules]` + +## Images + +- Every image needs descriptive alt text. `[existing: CLAUDE.md]` +- Filenames use kebab-case and go under `images//`. `[existing: Cursor rules]` +- **Conflict:** the Cursor rules say "wrap all images in ``." In practice, about 110 of 150 images are framed. Proposal: frame screenshots, not diagrams or logos. `[needs Ethan]` +- Screenshots are PNG. Use colored rectangles for emphasis, never blur or overlays. `[existing: Cursor rules]` +- `[needs Ethan]`: Do screenshots need light and dark variants? + +## Callouts + +Google defines Note, Caution, Warning, and Success ([notices](https://developers.google.com/style/notices)). Our components are different, so here is what each one means for us. Current English usage: Note 165, Tip 87, Info 73, Warning 68, Check 8, Danger 2. + +| Component | Use for | Source | +| --- | --- | --- | +| `` | Plan and availability requirements: "X requires a Pro or Enterprise plan." One sentence, with a pricing link. | `[existing: practice, memory]` | +| `` | Useful information the reader can skip without failing | `[Google: Note]` `[needs Ethan]` | +| `` | An optional better way to do something | `[needs Ethan]` | +| `` | Risk of data loss, security issues, or irreversible actions | `[Google: Warning]` `[needs Ethan]` | +| `` / `` | Rarely used. Proposal: use `` only for "you're done" confirmations; use `` instead of ``. | `[needs Ethan]` | + +- Use callouts sparingly. Never put two callouts back to back. `[Google]` + +## Other components + +- `` for procedures with three or more steps. For shorter procedures, use a numbered list. `[needs Ethan]` +- `` for parallel alternatives the reader picks one of, such as web editor vs CLI or package managers. Don't use tabs for sequential content. `[needs Ethan]` +- `` and `` for navigation to other pages, not for body content. `[needs Ethan]` +- `` for content most readers skip, such as troubleshooting or edge cases. Never for required steps. `[needs Ethan]` +- `` is used 87 times, mostly in reference content. Its purpose needs a definition. `[needs Ethan]` +- Component introductions start with "Use [component] to...," not "The [component] component...". `[existing: CLAUDE.md]` diff --git a/style-guide/voice-and-tone.md b/style-guide/voice-and-tone.md new file mode 100644 index 0000000000..12008ac671 --- /dev/null +++ b/style-guide/voice-and-tone.md @@ -0,0 +1,60 @@ +# Voice and tone + +> **Outline for review.** Tags: `[existing: X]` means the rule comes from current guidance; `[Google: link]` means we follow or deviate from Google; `[needs Ethan]` means it's an open decision. + +Google's defaults apply: [voice](https://developers.google.com/style/voice), [tone](https://developers.google.com/style/tone), [second person](https://developers.google.com/style/person), [active voice](https://developers.google.com/style/voice), [present tense](https://developers.google.com/style/tense). This file covers only what's specific to Mintlify. + +## Who we're writing for + +- Mixed technical ability. Some readers live in the CLI and Git, while others only use the web editor and never see Git. `[existing: CLAUDE.md, Cursor rules]` +- Readers and agents both consume every page, so write for scanning and literal parsing. `[existing: CONTRIBUTING.md]` +- Goal: just enough information for the reader to succeed and get back to the product. `[existing: CLAUDE.md]` + +## How we sound + +- Like a helpful coworker explaining something: clear and direct, but not robotic. `[existing: Cursor rules]` +- Meaning over grammar. You can break a rule, such as active voice, when following it makes the sentence worse. `[existing: CONTRIBUTING.md]` + +## Tense and "will" + +- **Conflict:** the Cursor rules say "future tense for outcomes." Vale `Mintlify.Will` warns on every "will." Google allows "will" for actions that happen later ([tense](https://developers.google.com/style/tense)). Current docs have about 12 uses. +- Proposal: follow Google. Use present tense by default, and "will" only for something that actually happens later. Narrow or keep `Mintlify.Will` as a warning. `[needs Ethan]` + +## First person + +- Vale `Mintlify.FirstPerson` warns on "we" and "our." About 30 English pages use them. +- Proposal: follow Google ([pronouns](https://developers.google.com/style/pronouns)). Use "we" only for Mintlify-the-company after naming it, such as "Mintlify stores... We delete...". Never use "I." `[needs Ethan]` + +## Referring to Mintlify + +- Don't put "Mintlify" in a feature name when the context is clear: "the assistant," not "the Mintlify assistant." `[existing: Cursor rules]` +- Make the reader or their site the subject rather than Mintlify. Write "After you push changes, your site deploys," not "Mintlify deploys your site." `[existing: Cursor rules, with "will" removed]` + +## Phrases to cut + +- Promotional: "rich," "breathtaking," "seamless," "powerful," "stands as a testament," "plays a vital role." `[existing: CLAUDE.md, Cursor rules]` +- Editorializing: "it's important to note," "this article will," "in conclusion." `[existing: CLAUDE.md]` +- Filler transitions: "moreover," "furthermore," "additionally." `[existing: CLAUDE.md]` +- Vague attribution: "experts say," "industry reports suggest." Cite a source or cut it. `[existing: Cursor rules]` +- Undue emphasis on routine things. `[existing: CLAUDE.md]` +- Exclamation points and slang. `[existing: Vale Mintlify.Exclamation, Mintlify.Slang]` + +## AI-writing tells + +A lot of our first drafts come from agents, so reviewers should look for these specifically: + +- Grouping things in threes when the content doesn't need it +- Negative parallelisms: "It's not X, it's Y." +- Trailing "-ing" clauses that add no meaning: "..., ensuring a smooth experience." +- Summarizing sentences at the end of a section that restate what the reader just read +- Bolded lead-ins on every bullet +- `[new, needs Ethan]`: Keep this list here, or point to the `humanizer` skill as the reference? + +## Em dashes + +- Vale `Mintlify.EmDash` allows em dashes without spaces, which matches [Google](https://developers.google.com/style/dashes). English pages have about 217 em dashes. +- Heavy em dash use is a common AI-writing tell. Options: + - (a) Follow Google as-is. + - (b) Prefer commas, parentheses, or two sentences, and allow at most one em dash per paragraph. + - (c) Ban them in prose. +- `[needs Ethan]` diff --git a/style-guide/word-list.md b/style-guide/word-list.md new file mode 100644 index 0000000000..8ce613e870 --- /dev/null +++ b/style-guide/word-list.md @@ -0,0 +1,43 @@ +# Word list + +> **Outline for review.** Tags work the same as in [voice-and-tone.md](voice-and-tone.md). + +This list covers how to write Mintlify terms. For what they mean, see the public [glossary](../reference/glossary.mdx). For general terms, follow [Google's word list](https://developers.google.com/style/word-list). Vale already enforces Google's swaps in `.vale/styles/Mintlify/WordList.yml`. + +When you add a term here, also add it to `.vale/styles/config/vocabularies/Mintlify/accept.txt` if Vale flags it as a misspelling. + +## Mintlify product terms + +| Use | Don't use | Notes | +| --- | --- | --- | +| Mintlify | mintlify, MintLify | Company and product. `[existing: Cursor rules]` | +| dashboard | Dashboard | Lowercase in running text. `[existing: Cursor rules]` | +| web editor | Web Editor, editor (alone, on first mention) | `[existing: Cursor rules]`; "editor" alone after first mention `[needs Ethan]` | +| CLI | cli, command-line tool | `[existing: Cursor rules]` | +| `mint` | mint (unformatted) | The CLI command, in code format. `[new, needs Ethan]` | +| `docs.json` | docs.json (unformatted), mint.json | Always in code format. mint.json is the legacy name; mention it only in migration content. `[existing: Cursor rules, Assistant.md]` | +| MDX | mdx, Mdx | `[existing: Cursor rules]` | +| frontmatter | front matter, front-matter | `[existing: Cursor rules]` | +| API playground | API Playground | `[existing: Cursor rules]` | +| assistant | Assistant, AI assistant, chatbot | `[needs Ethan]` | +| agent | Agent, Mintlify agent, AI agent | `[needs Ethan]` | +| automations | workflows | The docs directory is `automations/`, but the server calls them workflows. `[needs Ethan]` | +| project / deployment | | Definitions are changing on the unmerged `docs/projects-terminology` branch. Settle this after it merges. `[needs Ethan]` | +| preview deployment | preview, preview link | `[needs Ethan]` | +| Starter, Pro, Enterprise | Growth, Hobby, free plan | Current plan names. `[existing: memory, July 2026]` | +| sign in, sign in to | log in, login (as a verb), sign into | `[Google word list]`; "sign into" is `[existing: Vale]` | + +## Technical terms + +| Use | Don't use | Notes | +| --- | --- | --- | +| boolean | bool | In prose and property descriptions. `[existing: CLAUDE.md]` | +| OpenAPI | Open API, openapi | `[new, needs Ethan]` | +| llms.txt | LLMs.txt, llms-txt | `[new, needs Ethan]` | +| MCP server | MCP Server | `[new, needs Ethan]` | +| AI | A.I. | `[Google]` | + +## Terms for readers' own things + +- "your docs," "your site," "your documentation site": pick one. `[needs Ethan]` +- "users" means the reader's audience, not the reader. Use "you" for the reader. `[new, needs Ethan]` From fe743d81b3010956798d7b8c0590c2e2dadafb77 Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Thu, 24 Sep 2026 10:53:50 -0700 Subject: [PATCH 03/14] style-guide: point AGENTS.md and CONTRIBUTING.md at the style guide Co-Authored-By: Claude Opus 5.5 (1M context) --- .mintlify/AGENTS.md | 2 ++ CONTRIBUTING.md | 2 ++ 2 files changed, 4 insertions(+) diff --git a/.mintlify/AGENTS.md b/.mintlify/AGENTS.md index c2c055cff4..920e6d25e3 100644 --- a/.mintlify/AGENTS.md +++ b/.mintlify/AGENTS.md @@ -1,3 +1,5 @@ # Documentation agent instructions When you create a PR to update docs, only update English language files. Do not update any content in the `es/`, `fr/`, or `zh/` directories. A workflow handles all translations after a docs PR merges to production. + +Before you write or edit content, read `style-guide/README.md` and the style guide files relevant to your change. The style guide overrides the Google developer documentation style guide where they differ. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 681155121a..029258218d 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -23,6 +23,8 @@ These are general guidelines. If you’re not sure what category your proposed c ## Writing style +Follow the [style guide](style-guide/README.md). In short: + - Clarity and simplicity: Our documentation must be easy to read for people and agents. - Active voice: Use active voice wherever possible. - Meaning over grammar: Clarity and meaning are more important than precise adherence to all grammar rules. This includes violating active voice if it makes a sentence overly complicated. From 7f7870c1ee7aa4c391d001c451bfc98ac8c0ba58 Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Fri, 25 Sep 2026 14:18:45 -0700 Subject: [PATCH 04/14] style-guide: add working list of open decisions and review items Co-Authored-By: Claude Opus 5.5 (1M context) --- style-guide/DECISIONS.md | 111 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 111 insertions(+) create mode 100644 style-guide/DECISIONS.md diff --git a/style-guide/DECISIONS.md b/style-guide/DECISIONS.md new file mode 100644 index 0000000000..fcaf053763 --- /dev/null +++ b/style-guide/DECISIONS.md @@ -0,0 +1,111 @@ +# Style guide: open decisions and review items + +Working file for building the style guide. Delete it before the PR merges. + +## Where things stand (Sept 25, 2026) + +- Branch: `style-guide`, forked from `fc8793926`, not pushed. Plan: `~/.claude/plans/i-want-to-add-ancient-pelican.md`. +- Commits: + 1. `4a94247b8`: scaffold `style-guide/README.md` and add `style-guide/` to `.mintignore` + 2. `7dc995488`: outline of `voice-and-tone.md`, `word-list.md`, `formatting-and-components.md`, `content-strategy.md` + 3. `fe743d81b`: pointers added to `.mintlify/AGENTS.md` and `CONTRIBUTING.md` +- Gate: the prose isn't written until you decide the items below. +- To resume: tell Claude "continue the style guide on the `style-guide` branch, see `style-guide/DECISIONS.md`," and answer by number. + +## Decisions I need + +Each item has my recommendation. Reply with "agree" or your call. + +### Voice and tone + +1. **"will."** The Cursor rules say "future tense for outcomes." Vale `Mintlify.Will` warns on every "will." Google allows it for things that genuinely happen later. English pages have about 12 uses. + *Recommend:* follow Google, and keep the Vale rule as a warning. +2. **First person.** Vale warns on "we"/"our." About 30 pages use them. + *Recommend:* follow Google. "We" is fine for Mintlify-the-company after naming it. Never use "I." +3. **Em dashes.** There are about 217 in English pages. Vale allows them (no spaces), but heavy use is an AI tell. + *Options:* (a) follow Google, (b) at most one per paragraph and prefer commas or two sentences, (c) ban them in prose. + *Recommend:* (b). +4. **AI-writing tells.** Keep a short list in `voice-and-tone.md`, or point to the `humanizer` skill? + *Recommend:* keep a short list. The skill isn't available to every agent that reads this. + +### Word list + +5. **assistant**: lowercase "assistant," or "AI assistant" on first mention? +6. **agent**: "the agent," or "Mintlify agent" on first mention? +7. **automations vs workflows**: the docs directory says automations and the server says workflows. + *Recommend:* "automations" in docs. +8. **project / deployment**: wait for the unmerged `docs/projects-terminology` branch to merge, then match it? +9. **preview deployment** vs "preview" vs "preview link" +10. **editor**: can "editor" alone replace "web editor" after first mention? +11. **"your docs" / "your site" / "your documentation site"**: pick one default. +12. **"users"** means the reader's audience, and "you" means the reader. Agree? +13. **New term entries** I added without a source. Confirm or fix each one: + - `mint` in code format + - OpenAPI + - llms.txt + - MCP server + +### Formatting and components + +14. **`keywords` frontmatter**: CLAUDE.md says required and the Cursor rules say optional. 266 of 320 pages have it. + *Recommend:* required. +15. **``**: the Cursor rules say "all images," but about 110 of 150 images are framed. + *Recommend:* frame screenshots only, not diagrams or logos. +16. **Light and dark screenshot variants**: required, optional, or not mentioned? +17. **Code examples**: CLAUDE.md says "simple, one option." The Cursor rules say "complete, runnable, error handling." + *Recommend:* runnable and minimal, with realistic values. Include error handling only when it's the topic. +18. **Links as exits**: the Cursor rules say "each link is an exit, use sparingly" and suggest "Further reading" sections. Keep it? +19. **Callout meanings.** `` for plan gating is settled. Confirm or change the rest: + - ``: skippable information + - ``: an optional better way + - ``: data loss, security, or irreversible actions + - ``: only "you're done" confirmations + - ``: retire, and use `` instead +20. **``**: 87 uses, mostly in reference content. What is it for? +21. **Other component rules.** Confirm: + - `` for procedures of three or more steps + - `` only for parallel alternatives + - `` only for navigation + - `` for content most readers skip, never for required steps + +### Content strategy + +22. **CONTRIBUTING.md's "don't accept tone-only edits"** rule: does it apply to internal authors and agents, or only to outside contributors? +23. **Snippets**: when a fact is needed in several places, use a snippet instead of copying it. Agree? +24. **Help center vs guides vs feature pages**: when does something belong in the help center? +25. **Web editor vs CLI**: when a page covers both, which one comes first or is the default tab? +26. **Redirects**: + - (a) Is "keep for 18 months" real, or do redirects stay forever? + - (b) Should authors add the `/es/`, `/fr/`, and `/zh/` redirect entries by hand, like fb5b7608b did? +27. **"New" tags for two weeks** (from the Cursor rules): still practiced? +28. **Deprecations**: remove deprecated features instead of keeping callouts, except during an announced migration window? +29. **Changelog**: does it get its own conventions in this guide, or none for now? +30. **Translation exception**: the translation pass doesn't run on automation-opened PRs, so those PRs update `es/`, `fr/`, and `zh/` by hand. The guide will say "only edit English." Should it mention this exception, or leave it out because it's a temporary bug? + +## Things to review + +- **Outline files:** skim all four for rules you disagree with, not just the tagged ones. Anything tagged `[existing: ...]` came from current guidance but still needs your judgment. +- **`README.md` precedence rule:** this guide beats Google, and Vale is a subset. Is that the model you want? +- **File split:** four topic files plus a README. Would you rather have one long file? That's easier for agents to load in one read, but harder for people to navigate. +- **Page types:** templates are out of v1, as you decided. Confirm that's still the case. +- **Removals planned in the prose commit:** replace the writing rules in `.claude/CLAUDE.md` and `.cursor/rules/writing-standards.mdc` with pointers, keeping the context, pre-submit checklist, and "Do not" sections. Also, `.cursor/rules/component-reference.mdc` (329 lines) duplicates the public component docs. Delete it or leave it? +- **Correction to existing guidance:** the Cursor rules say redirects go in `docs.json`, but they're in `redirects.json`, which `docs.json` pulls in with `$ref`. The outline uses the correct path. + +## Blocked + +- **Admin MCP:** every `execute_code` call fails with "No target deployment for this request," even with `{ subdomain: 'mintlify' }`, while `list_deployments` works. Because of that, I can't yet: + - list the automations whose prompts need the style guide line + - confirm the `mintlify` deployment has no `contentDirectory` (if it has one, the sandbox's sparse checkout won't include root-level `style-guide/`) + + Options: + - Fix the connection's default deployment. + - Allow `checkout` followed by `discard_session`. That opens a throwaway branch on the docs repo. + - Send me the list of automations yourself. + +## Remaining steps after decisions + +1. Write the prose, replacing the outline tags with short do/don't examples, and commit. +2. Replace the duplicated guidance in `.claude/CLAUDE.md` and the Cursor rules with pointers, and commit. +3. Delete this file. Run `mint broken-links`, run `vale` on any changed `.mdx`, and confirm `/style-guide/*` returns 404 in `mint dev`. +4. Push and open the PR. +5. After merge: show you the automation prompt diffs, and apply them only after you approve. Then archive `mintlify/styleguide` (yours to do). From 0787d9c70e9d75bd4a4afdf60d203b3924920276 Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Fri, 25 Sep 2026 14:58:34 -0700 Subject: [PATCH 05/14] update README --- style-guide/README.md | 22 +++++++--------------- 1 file changed, 7 insertions(+), 15 deletions(-) diff --git a/style-guide/README.md b/style-guide/README.md index f92f81c148..76fca3963c 100644 --- a/style-guide/README.md +++ b/style-guide/README.md @@ -1,32 +1,24 @@ # Mintlify docs style guide -> **Status: outline for review.** Items tagged `[needs Ethan]` are open decisions. Source tags get removed when this is written as prose. - -This guide is for anyone writing or editing content in this repo, people and agents alike. It covers the docs site: pages, the changelog, and help center articles. It does not cover product UI copy or marketing. +This guide is for people and agents writing or editing content in this repo. It covers the docs site: pages, the changelog, and help center articles. It does not explicitly apply to product UI copy or marketing content, but there should be consistency between platforms. ## How to use this guide -1. Follow the [Google developer documentation style guide](https://developers.google.com/style) for anything this guide doesn't cover. -2. When this guide and Google's disagree, this guide wins. Every rule here is either a Mintlify-specific decision or a place where we deviate from Google. -3. [Vale](../.vale.ini) enforces a subset of these rules on `.mdx` files. A clean Vale run doesn't mean a page follows the guide. +1. Defer to the [Google developer documentation style guide](https://developers.google.com/style) for anything this guide doesn't address. +2. When this guide and Google's disagree, this guide wins. Every rule here is a Mintlify-specific decision. +3. [Vale](../.vale.ini) enforces a subset of these rules on `.mdx` files, but a clean Vale run doesn't mean a page follows the guide. ## Files -| File | Covers | +| File | Purpose | | --- | --- | -| [voice-and-tone.md](voice-and-tone.md) | How Mintlify docs sound, phrases to cut, AI-writing tells | +| [voice-and-tone.md](voice-and-tone.md) | How to write in the Mintlify docs style | | [word-list.md](word-list.md) | Product terms, capitalization, preferred and avoided words | | [formatting-and-components.md](formatting-and-components.md) | Markdown conventions and when to use each Mintlify component | | [content-strategy.md](content-strategy.md) | What to document, where it goes, and how to keep it maintainable | -## For agents - -- Read this file, then the files relevant to your change. -- Only edit English content. Translations in `es/`, `fr/`, and `zh/` are generated after merge. -- Before opening a PR, run the checks in [.claude/CLAUDE.md](../.claude/CLAUDE.md#before-submitting-work). - ## Changing the guide -Open a PR that edits the relevant file. If a rule should be enforced, update or add the matching Vale rule in `.vale/styles/Mintlify/` in the same PR. Narrow a Vale rule rather than rewriting correct prose to satisfy it. +Open a PR that edits the relevant file. If a rule should be enforced, update or add the matching Vale rule in `.vale/styles/Mintlify/` in the same PR. Narrow a Vale rule rather than rewrite correct prose to satisfy a rule. Portions adapted from the Google developer documentation style guide are used under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/). From 715f314aa259162bf95a4440bc735c924367996c Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Fri, 25 Sep 2026 16:35:41 -0700 Subject: [PATCH 06/14] edits --- style-guide/DECISIONS.md | 111 ----------------------- style-guide/content-strategy.md | 59 ++++++------ style-guide/formatting-and-components.md | 86 +++++++++--------- style-guide/voice-and-tone.md | 48 ++++------ style-guide/word-list.md | 53 ++++++----- 5 files changed, 112 insertions(+), 245 deletions(-) delete mode 100644 style-guide/DECISIONS.md diff --git a/style-guide/DECISIONS.md b/style-guide/DECISIONS.md deleted file mode 100644 index fcaf053763..0000000000 --- a/style-guide/DECISIONS.md +++ /dev/null @@ -1,111 +0,0 @@ -# Style guide: open decisions and review items - -Working file for building the style guide. Delete it before the PR merges. - -## Where things stand (Sept 25, 2026) - -- Branch: `style-guide`, forked from `fc8793926`, not pushed. Plan: `~/.claude/plans/i-want-to-add-ancient-pelican.md`. -- Commits: - 1. `4a94247b8`: scaffold `style-guide/README.md` and add `style-guide/` to `.mintignore` - 2. `7dc995488`: outline of `voice-and-tone.md`, `word-list.md`, `formatting-and-components.md`, `content-strategy.md` - 3. `fe743d81b`: pointers added to `.mintlify/AGENTS.md` and `CONTRIBUTING.md` -- Gate: the prose isn't written until you decide the items below. -- To resume: tell Claude "continue the style guide on the `style-guide` branch, see `style-guide/DECISIONS.md`," and answer by number. - -## Decisions I need - -Each item has my recommendation. Reply with "agree" or your call. - -### Voice and tone - -1. **"will."** The Cursor rules say "future tense for outcomes." Vale `Mintlify.Will` warns on every "will." Google allows it for things that genuinely happen later. English pages have about 12 uses. - *Recommend:* follow Google, and keep the Vale rule as a warning. -2. **First person.** Vale warns on "we"/"our." About 30 pages use them. - *Recommend:* follow Google. "We" is fine for Mintlify-the-company after naming it. Never use "I." -3. **Em dashes.** There are about 217 in English pages. Vale allows them (no spaces), but heavy use is an AI tell. - *Options:* (a) follow Google, (b) at most one per paragraph and prefer commas or two sentences, (c) ban them in prose. - *Recommend:* (b). -4. **AI-writing tells.** Keep a short list in `voice-and-tone.md`, or point to the `humanizer` skill? - *Recommend:* keep a short list. The skill isn't available to every agent that reads this. - -### Word list - -5. **assistant**: lowercase "assistant," or "AI assistant" on first mention? -6. **agent**: "the agent," or "Mintlify agent" on first mention? -7. **automations vs workflows**: the docs directory says automations and the server says workflows. - *Recommend:* "automations" in docs. -8. **project / deployment**: wait for the unmerged `docs/projects-terminology` branch to merge, then match it? -9. **preview deployment** vs "preview" vs "preview link" -10. **editor**: can "editor" alone replace "web editor" after first mention? -11. **"your docs" / "your site" / "your documentation site"**: pick one default. -12. **"users"** means the reader's audience, and "you" means the reader. Agree? -13. **New term entries** I added without a source. Confirm or fix each one: - - `mint` in code format - - OpenAPI - - llms.txt - - MCP server - -### Formatting and components - -14. **`keywords` frontmatter**: CLAUDE.md says required and the Cursor rules say optional. 266 of 320 pages have it. - *Recommend:* required. -15. **``**: the Cursor rules say "all images," but about 110 of 150 images are framed. - *Recommend:* frame screenshots only, not diagrams or logos. -16. **Light and dark screenshot variants**: required, optional, or not mentioned? -17. **Code examples**: CLAUDE.md says "simple, one option." The Cursor rules say "complete, runnable, error handling." - *Recommend:* runnable and minimal, with realistic values. Include error handling only when it's the topic. -18. **Links as exits**: the Cursor rules say "each link is an exit, use sparingly" and suggest "Further reading" sections. Keep it? -19. **Callout meanings.** `` for plan gating is settled. Confirm or change the rest: - - ``: skippable information - - ``: an optional better way - - ``: data loss, security, or irreversible actions - - ``: only "you're done" confirmations - - ``: retire, and use `` instead -20. **``**: 87 uses, mostly in reference content. What is it for? -21. **Other component rules.** Confirm: - - `` for procedures of three or more steps - - `` only for parallel alternatives - - `` only for navigation - - `` for content most readers skip, never for required steps - -### Content strategy - -22. **CONTRIBUTING.md's "don't accept tone-only edits"** rule: does it apply to internal authors and agents, or only to outside contributors? -23. **Snippets**: when a fact is needed in several places, use a snippet instead of copying it. Agree? -24. **Help center vs guides vs feature pages**: when does something belong in the help center? -25. **Web editor vs CLI**: when a page covers both, which one comes first or is the default tab? -26. **Redirects**: - - (a) Is "keep for 18 months" real, or do redirects stay forever? - - (b) Should authors add the `/es/`, `/fr/`, and `/zh/` redirect entries by hand, like fb5b7608b did? -27. **"New" tags for two weeks** (from the Cursor rules): still practiced? -28. **Deprecations**: remove deprecated features instead of keeping callouts, except during an announced migration window? -29. **Changelog**: does it get its own conventions in this guide, or none for now? -30. **Translation exception**: the translation pass doesn't run on automation-opened PRs, so those PRs update `es/`, `fr/`, and `zh/` by hand. The guide will say "only edit English." Should it mention this exception, or leave it out because it's a temporary bug? - -## Things to review - -- **Outline files:** skim all four for rules you disagree with, not just the tagged ones. Anything tagged `[existing: ...]` came from current guidance but still needs your judgment. -- **`README.md` precedence rule:** this guide beats Google, and Vale is a subset. Is that the model you want? -- **File split:** four topic files plus a README. Would you rather have one long file? That's easier for agents to load in one read, but harder for people to navigate. -- **Page types:** templates are out of v1, as you decided. Confirm that's still the case. -- **Removals planned in the prose commit:** replace the writing rules in `.claude/CLAUDE.md` and `.cursor/rules/writing-standards.mdc` with pointers, keeping the context, pre-submit checklist, and "Do not" sections. Also, `.cursor/rules/component-reference.mdc` (329 lines) duplicates the public component docs. Delete it or leave it? -- **Correction to existing guidance:** the Cursor rules say redirects go in `docs.json`, but they're in `redirects.json`, which `docs.json` pulls in with `$ref`. The outline uses the correct path. - -## Blocked - -- **Admin MCP:** every `execute_code` call fails with "No target deployment for this request," even with `{ subdomain: 'mintlify' }`, while `list_deployments` works. Because of that, I can't yet: - - list the automations whose prompts need the style guide line - - confirm the `mintlify` deployment has no `contentDirectory` (if it has one, the sandbox's sparse checkout won't include root-level `style-guide/`) - - Options: - - Fix the connection's default deployment. - - Allow `checkout` followed by `discard_session`. That opens a throwaway branch on the docs repo. - - Send me the list of automations yourself. - -## Remaining steps after decisions - -1. Write the prose, replacing the outline tags with short do/don't examples, and commit. -2. Replace the duplicated guidance in `.claude/CLAUDE.md` and the Cursor rules with pointers, and commit. -3. Delete this file. Run `mint broken-links`, run `vale` on any changed `.mdx`, and confirm `/style-guide/*` returns 404 in `mint dev`. -4. Push and open the PR. -5. After merge: show you the automation prompt diffs, and apply them only after you approve. Then archive `mintlify/styleguide` (yours to do). diff --git a/style-guide/content-strategy.md b/style-guide/content-strategy.md index dab478babd..4e27e77bf6 100644 --- a/style-guide/content-strategy.md +++ b/style-guide/content-strategy.md @@ -1,56 +1,51 @@ # Content strategy -> **Outline for review.** Tags work the same as in [voice-and-tone.md](voice-and-tone.md). - -Google's guide mostly covers sentences, not strategy, so most of this file is Mintlify-specific. - ## Just enough docs -- Document what readers need to succeed, and nothing more. Too much content hides what people are looking for. `[existing: CLAUDE.md]` -- Don't accept edits made purely for tone, readability, or efficiency, and don't cover niche preference topics. `[existing: CONTRIBUTING.md]` `[needs Ethan: does this apply to internal authors too, or only outside contributors?]` +- Document what readers need to succeed, and nothing more. Too much content hides what people are looking for. +- For AI agents, exhaustive reference can be helpful for information that isn't in their training data. For example, provide all flags and settings options for commands and operations an agent can perform. But for content only relevant to agents, consider making it a hidden page. ## Before you write -- Search for existing content first. Extend an existing page rather than create a new one, unless the new page serves a distinct task. `[existing: CLAUDE.md]` -- Duplicate content only for a deliberate reason. When the same fact is needed in more than one place, put it in a snippet. `[existing: CLAUDE.md; snippet part is new, needs Ethan]` -- Make the smallest change that solves the problem. `[existing: CLAUDE.md]` +- Search for existing content first. Add content to relevant pages rather than creating new ones, unless the new page serves a distinct task. +- Duplicate content only for a deliberate reason. When the same fact is needed in more than one place, put it in a snippet for reuse. +- Make the smallest change that solves the problem. ## Where content goes -- Put new pages in the nav group that matches the user journey, such as Customize or Deploy. `[existing: CLAUDE.md]` -- Order content by how often readers need it, most common first. `[existing: CLAUDE.md, Cursor rules]` -- Help center vs guides vs feature pages: when does something become a help center article? `[needs Ethan]` +- Put new pages in the nav group that matches the user journey. +- Order content by how often readers need it, most common tasks come first. +- The help center is for agent-written content that answers specific user questions from conversations with support or the assistant. +- Guides are end-to-end tutorials and best practices for concepts adjacent to Mintlify but not part of the platform itself. Like Git best practices or integrating Mintlify CLI commands into your CI pipeline. + +## Localization + +- Only edit English content. Translations in `es/`, `fr/`, and `zh/` are generated after merge by an automation. +- If you remove image files that are present in localized pages, the broken link check CI fails, but the translation automation will fix it. ## Page structure -- Lead with context: what something is and why you'd use it, then how. `[existing: CLAUDE.md]` -- Prerequisites go at the start of procedural pages. `[existing: CLAUDE.md]` -- Offer one opinionated path. Only show alternatives when readers genuinely choose between them. `[existing: Cursor rules]` -- Include a verification step or expected result for major procedures. `[existing: Cursor rules]` +- Lead with context: what something is and why you'd use it, then how. +- Prerequisites go at the start of procedural pages. +- Offer one opinionated path. Only show alternatives when readers genuinely choose between them. +- Include a verification step or expected result for major procedures. -## Two audiences: web editor and CLI +## Two workflows: editor (web or desktop app) and CLI -- When a task can be done both ways, cover both. Use tabs, or separate sections if the steps diverge a lot. `[needs Ethan: which is the default or first tab?]` -- Don't assume Git knowledge in web editor paths. `[existing: CLAUDE.md]` +- When a task can be done in the editor or locally via the CLI, cover both. Use tabs, or separate sections if the steps diverge a lot. +- Don't assume Git knowledge in web editor paths. ## Plan gating -- If a feature requires a paid plan, add a one-sentence `` at the top of the page: "X requires a [Pro or Enterprise plan](https://mintlify.com/pricing?ref=x)." `[existing: practice, memory]` -- Verify gating against the pricing page and the code before you add or remove a callout. The pricing table is the public source of truth. `[existing: memory]` +- If a feature requires a paid plan, add a one-sentence `` callout at the top of the page: " requires a [Pro or Enterprise plan](https://mintlify.com/pricing?ref=x)." +- Verify gating against the pricing page and the code before you add or remove a callout. The pricing table is the public source of truth. ## Changes, moves, and deprecations -- When you move or rename a page, add a redirect in `redirects.json`, which `docs.json` pulls in through `$ref`. `[existing: Cursor rules, corrected path]` -- Recent redirect PRs, such as fb5b7608b, also add `/es/`, `/fr/`, and `/zh/` entries by hand. Should authors add locale redirects, or does the translation workflow handle them? `[needs Ethan]` -- The Cursor rules say "for 18 months." Do we ever remove redirects? `[needs Ethan]` -- The Cursor rules say "'New' tags for two weeks." Is this still practiced? `[needs Ethan]` -- Remove deprecated features rather than keeping "deprecated" callouts, except during an announced migration window. `[new, needs Ethan]` -- Update screenshots when the UI changes. `[existing: Cursor rules]` +- When you move or rename a page, add a redirect in `redirects.json`, which `docs.json` pulls in through `$ref`. +- Remove deprecated features rather than keeping "deprecated" callouts, except during an announced migration window. +- Update screenshots when the UI changes. ## Changelog -- Is the changelog in scope for this guide, and does it have its own conventions (entry format, tense, linking to docs)? `[needs Ethan]` - -## Translations - -- Only edit English. `es/`, `fr/`, and `zh/` are generated after merge. `[existing: AGENTS.md, CLAUDE.md]` +- Our changelog updates weekly with new releases, improvements, and bug fixes. diff --git a/style-guide/formatting-and-components.md b/style-guide/formatting-and-components.md index 5eb51540f2..b9d41c1328 100644 --- a/style-guide/formatting-and-components.md +++ b/style-guide/formatting-and-components.md @@ -1,73 +1,69 @@ # Formatting and components -> **Outline for review.** Tags work the same as in [voice-and-tone.md](voice-and-tone.md). - Google's defaults apply: [headings](https://developers.google.com/style/headings), [lists](https://developers.google.com/style/lists), [procedures](https://developers.google.com/style/procedures), [code in text](https://developers.google.com/style/code-in-text), [UI elements](https://developers.google.com/style/ui-elements), [link text](https://developers.google.com/style/link-text), [images](https://developers.google.com/style/images). This file covers MDX and Mintlify specifics. For component syntax, see the public [components docs](../components/). ## Frontmatter -- Every page needs `title` and `description`. `[existing: CLAUDE.md, Cursor rules]` -- **Conflict:** CLAUDE.md requires `keywords`, while the Cursor rules call it optional. In practice, 266 of 320 English pages have it. Proposal: required. `[needs Ethan]` -- `sidebarTitle` when the title is too long for the sidebar. `[existing: Cursor rules]` -- Icons come only from [Lucide](https://lucide.dev). `[existing: CLAUDE.md]` +- Every page needs `title`, `description`, and `keywords`. + - Titles use sentence case + - Descriptions populate search results, so they must help readers determine if a page will solve the task they're working on. + - Keywords are used to improve search. Any words in the title are already keywords. +- Optional: `sidebarTitle` when the title is too long for the sidebar. +- Icons come only from [Lucide](https://lucide.dev). ## Headings -- Sentence case, no ending punctuation. `[existing: Vale Mintlify.Headings, Mintlify.HeadingPunctuation]` -- Start at H2. H1 is the page title. `[existing: Cursor rules]` -- Code block titles also use sentence case. `[existing: CLAUDE.md]` +- Sentence case, no ending punctuation. +- Start at H2. H1 is the page title. ## Text formatting -- Use bold for UI elements the reader interacts with: "Select **Save**." `[existing: Cursor rules, matches Google]` -- Only use bold or italics for emphasis when it helps comprehension. Never use emoji. `[existing: CLAUDE.md]` -- Use code format for filenames, commands, config keys, and values. `[existing: Cursor rules]` -- Use `` for keyboard shortcuts: Cmd + K. `[existing: Cursor rules]` -- Property descriptions end with a period. `[existing: CLAUDE.md]` -- Scope qualifiers go at the start of a description: "For Font Awesome icons only: ..." `[existing: CLAUDE.md]` +- Use bold for UI elements the reader interacts with: "Click **Save**." +- Only use bold or italics for emphasis when it helps with comprehension. Never use emoji. +- Use code format for filenames, commands, config keys, and values. +- Use `` for keyboard shortcuts: Cmd + K. +- Property descriptions end with a period. +- Scope qualifiers go at the start of a description: "For Font Awesome icons only: ..." ## Links -- Internal links use root-relative paths, like `/components/accordions`. Never use absolute mintlify.com URLs for internal links. `[existing: CLAUDE.md]` -- Link text describes where the link goes. Never use "click here." `[existing: Cursor rules, Google]` -- Don't put code formatting inside link text. `[existing: Cursor rules]` -- The Cursor rules say "Each link is an exit opportunity, use sparingly" and suggest "Further reading" sections. Google has no equivalent rule. Keep it? `[needs Ethan]` -- Plan links go to pricing with a `?ref=` parameter. `[existing: practice across 11 plan callouts]` +- Internal links use root-relative paths, like `/components/accordions`. Never use absolute mintlify.com URLs for internal links. +- Link text describes where the link goes. Never use "click here" or other vague link text. +- Each link is a chance to distract people from the content they're reading. Include links thoughtfully and only when it adds value to the task a user is working on. +- Don't put code formatting inside link text. +- Plan links go to pricing with a `?ref=` parameter. ## Code blocks -- Every code block has a language tag. `[existing: CLAUDE.md]` -- Add a filename title when the reader needs to know which file the code goes in, such as ` ```json docs.json `. `[existing: Cursor rules]` -- **Conflict:** CLAUDE.md says "simple, one option when one will do," while the Cursor rules say "complete, runnable, with error handling and realistic data." Proposal: examples are runnable and minimal, with realistic values, and include error handling only when error handling is the topic. `[needs Ethan]` -- Never put real API keys in examples. `[existing: Cursor rules]` +- Every code block must have a language tag.` +- Code block headings use sentence case. +- Add a filename title when the reader needs to know which file the code goes in, such as ` ```json docs.json `. +- Examples are runnable and minimal, with realistic values, and include error handling only when relevant. +- Never put real API keys in examples. ## Images -- Every image needs descriptive alt text. `[existing: CLAUDE.md]` -- Filenames use kebab-case and go under `images//`. `[existing: Cursor rules]` -- **Conflict:** the Cursor rules say "wrap all images in ``." In practice, about 110 of 150 images are framed. Proposal: frame screenshots, not diagrams or logos. `[needs Ethan]` -- Screenshots are PNG. Use colored rectangles for emphasis, never blur or overlays. `[existing: Cursor rules]` -- `[needs Ethan]`: Do screenshots need light and dark variants? +- Every image needs descriptive alt text. +- Filenames use kebab-case and go under `images//*`. +- Frame screenshots, not diagrams or logos. +- Screenshots are PNG. Use colored rectangles for emphasis, never blur or overlays. + - For screenshots of the Mintlify UI, include light and dark variants. ## Callouts -Google defines Note, Caution, Warning, and Success ([notices](https://developers.google.com/style/notices)). Our components are different, so here is what each one means for us. Current English usage: Note 165, Tip 87, Info 73, Warning 68, Check 8, Danger 2. - -| Component | Use for | Source | -| --- | --- | --- | -| `` | Plan and availability requirements: "X requires a Pro or Enterprise plan." One sentence, with a pricing link. | `[existing: practice, memory]` | -| `` | Useful information the reader can skip without failing | `[Google: Note]` `[needs Ethan]` | -| `` | An optional better way to do something | `[needs Ethan]` | -| `` | Risk of data loss, security issues, or irreversible actions | `[Google: Warning]` `[needs Ethan]` | -| `` / `` | Rarely used. Proposal: use `` only for "you're done" confirmations; use `` instead of ``. | `[needs Ethan]` | +Use callouts sparingly. Never put multiple callouts back-to-back. -- Use callouts sparingly. Never put two callouts back to back. `[Google]` +| Component | Use for | +| --- | --- | +| `` | Plan and availability requirements: "X requires a Pro or Enterprise plan." One sentence, with a pricing link. | +| `` | Useful information the reader can skip without failing | +| `` | A best practice or optional way to do something | +| `` | Risk of data loss, security issues, or irreversible actions | +| `` | Use to signal a procedure or task is done with a confirmation message | ## Other components -- `` for procedures with three or more steps. For shorter procedures, use a numbered list. `[needs Ethan]` -- `` for parallel alternatives the reader picks one of, such as web editor vs CLI or package managers. Don't use tabs for sequential content. `[needs Ethan]` -- `` and `` for navigation to other pages, not for body content. `[needs Ethan]` -- `` for content most readers skip, such as troubleshooting or edge cases. Never for required steps. `[needs Ethan]` -- `` is used 87 times, mostly in reference content. Its purpose needs a definition. `[needs Ethan]` -- Component introductions start with "Use [component] to...," not "The [component] component...". `[existing: CLAUDE.md]` +- `` for sequential procedures. +- `` for parallel alternatives the reader picks one of, such as web editor vs CLI or package managers. +- `` and `` for emphasizing links to other pages with context. +- `` for content most readers skip, such as troubleshooting or edge cases. Never for required steps. diff --git a/style-guide/voice-and-tone.md b/style-guide/voice-and-tone.md index 12008ac671..69edafaa24 100644 --- a/style-guide/voice-and-tone.md +++ b/style-guide/voice-and-tone.md @@ -1,43 +1,36 @@ # Voice and tone -> **Outline for review.** Tags: `[existing: X]` means the rule comes from current guidance; `[Google: link]` means we follow or deviate from Google; `[needs Ethan]` means it's an open decision. - -Google's defaults apply: [voice](https://developers.google.com/style/voice), [tone](https://developers.google.com/style/tone), [second person](https://developers.google.com/style/person), [active voice](https://developers.google.com/style/voice), [present tense](https://developers.google.com/style/tense). This file covers only what's specific to Mintlify. +Google's defaults apply: [voice](https://developers.google.com/style/voice), [tone](https://developers.google.com/style/tone), [second person](https://developers.google.com/style/person), [active voice](https://developers.google.com/style/voice), [present tense](https://developers.google.com/style/tense). ## Who we're writing for -- Mixed technical ability. Some readers live in the CLI and Git, while others only use the web editor and never see Git. `[existing: CLAUDE.md, Cursor rules]` -- Readers and agents both consume every page, so write for scanning and literal parsing. `[existing: CONTRIBUTING.md]` -- Goal: just enough information for the reader to succeed and get back to the product. `[existing: CLAUDE.md]` +- Mixed technical ability. Some readers work locally in the CLI and Git with their preferred coding agents, while others only use the editor in their browser or the desktop app and never see Git. +- Readers and agents both consume every page, so write for scanning and literal parsing. +- Goal: just enough information for the reader to succeed and get back to their task. ## How we sound -- Like a helpful coworker explaining something: clear and direct, but not robotic. `[existing: Cursor rules]` -- Meaning over grammar. You can break a rule, such as active voice, when following it makes the sentence worse. `[existing: CONTRIBUTING.md]` +- Like a helpful coworker explaining something: clear and direct. Friendly and supportive, but not robotic. +- Meaning over grammar. You can break a rule, such as active voice, when following it makes the sentence worse. ## Tense and "will" -- **Conflict:** the Cursor rules say "future tense for outcomes." Vale `Mintlify.Will` warns on every "will." Google allows "will" for actions that happen later ([tense](https://developers.google.com/style/tense)). Current docs have about 12 uses. -- Proposal: follow Google. Use present tense by default, and "will" only for something that actually happens later. Narrow or keep `Mintlify.Will` as a warning. `[needs Ethan]` - -## First person - -- Vale `Mintlify.FirstPerson` warns on "we" and "our." About 30 English pages use them. -- Proposal: follow Google ([pronouns](https://developers.google.com/style/pronouns)). Use "we" only for Mintlify-the-company after naming it, such as "Mintlify stores... We delete...". Never use "I." `[needs Ethan]` +- Use present tense by default. Use "will" rarely for events that only occur later. ## Referring to Mintlify -- Don't put "Mintlify" in a feature name when the context is clear: "the assistant," not "the Mintlify assistant." `[existing: Cursor rules]` -- Make the reader or their site the subject rather than Mintlify. Write "After you push changes, your site deploys," not "Mintlify deploys your site." `[existing: Cursor rules, with "will" removed]` +- Only rarely use "we" to refer to Mintlify after already naming the company earlier in the page. +- Don't put "Mintlify" in a feature name when the context is clear: "the assistant," not "the Mintlify assistant." +- Make the reader or their site the subject rather than Mintlify. Write "After you push changes, your site deploys," not "Mintlify deploys your site." ## Phrases to cut -- Promotional: "rich," "breathtaking," "seamless," "powerful," "stands as a testament," "plays a vital role." `[existing: CLAUDE.md, Cursor rules]` -- Editorializing: "it's important to note," "this article will," "in conclusion." `[existing: CLAUDE.md]` -- Filler transitions: "moreover," "furthermore," "additionally." `[existing: CLAUDE.md]` -- Vague attribution: "experts say," "industry reports suggest." Cite a source or cut it. `[existing: Cursor rules]` -- Undue emphasis on routine things. `[existing: CLAUDE.md]` -- Exclamation points and slang. `[existing: Vale Mintlify.Exclamation, Mintlify.Slang]` +- Promotional: "rich," "breathtaking," "seamless," "powerful," "stands as a testament," "plays a vital role." +- Editorializing: "it's important to note," "this article will," "in conclusion." +- Filler transitions: "moreover," "furthermore," "additionally." +- Vague attribution: "experts say," "industry reports suggest." Cite a source or cut it. +- Undue emphasis on routine things. +- Exclamation points and slang. ## AI-writing tells @@ -48,13 +41,8 @@ A lot of our first drafts come from agents, so reviewers should look for these s - Trailing "-ing" clauses that add no meaning: "..., ensuring a smooth experience." - Summarizing sentences at the end of a section that restate what the reader just read - Bolded lead-ins on every bullet -- `[new, needs Ethan]`: Keep this list here, or point to the `humanizer` skill as the reference? ## Em dashes -- Vale `Mintlify.EmDash` allows em dashes without spaces, which matches [Google](https://developers.google.com/style/dashes). English pages have about 217 em dashes. -- Heavy em dash use is a common AI-writing tell. Options: - - (a) Follow Google as-is. - - (b) Prefer commas, parentheses, or two sentences, and allow at most one em dash per paragraph. - - (c) Ban them in prose. -- `[needs Ethan]` +- You can use em dashes. They are helpful punctuation. Prefer commas or two sentences though. +- Do not put spaces around em dashes. diff --git a/style-guide/word-list.md b/style-guide/word-list.md index 8ce613e870..5bb642d955 100644 --- a/style-guide/word-list.md +++ b/style-guide/word-list.md @@ -1,43 +1,42 @@ # Word list -> **Outline for review.** Tags work the same as in [voice-and-tone.md](voice-and-tone.md). - -This list covers how to write Mintlify terms. For what they mean, see the public [glossary](../reference/glossary.mdx). For general terms, follow [Google's word list](https://developers.google.com/style/word-list). Vale already enforces Google's swaps in `.vale/styles/Mintlify/WordList.yml`. +This list covers how to write Mintlify terms. For what they mean, see the public [glossary](../reference/glossary.mdx). For general terms, follow [Google's word list](https://developers.google.com/style/word-list). Vale enforces Google's swaps in `.vale/styles/Mintlify/WordList.yml`. When you add a term here, also add it to `.vale/styles/config/vocabularies/Mintlify/accept.txt` if Vale flags it as a misspelling. ## Mintlify product terms +In general, Mintlify product names are lowercase if they are terms commonly used in other contexts like editor, assistant, or agent. Only proper nouns are capitalized. + | Use | Don't use | Notes | | --- | --- | --- | -| Mintlify | mintlify, MintLify | Company and product. `[existing: Cursor rules]` | -| dashboard | Dashboard | Lowercase in running text. `[existing: Cursor rules]` | -| web editor | Web Editor, editor (alone, on first mention) | `[existing: Cursor rules]`; "editor" alone after first mention `[needs Ethan]` | -| CLI | cli, command-line tool | `[existing: Cursor rules]` | -| `mint` | mint (unformatted) | The CLI command, in code format. `[new, needs Ethan]` | -| `docs.json` | docs.json (unformatted), mint.json | Always in code format. mint.json is the legacy name; mention it only in migration content. `[existing: Cursor rules, Assistant.md]` | -| MDX | mdx, Mdx | `[existing: Cursor rules]` | -| frontmatter | front matter, front-matter | `[existing: Cursor rules]` | -| API playground | API Playground | `[existing: Cursor rules]` | -| assistant | Assistant, AI assistant, chatbot | `[needs Ethan]` | -| agent | Agent, Mintlify agent, AI agent | `[needs Ethan]` | -| automations | workflows | The docs directory is `automations/`, but the server calls them workflows. `[needs Ethan]` | -| project / deployment | | Definitions are changing on the unmerged `docs/projects-terminology` branch. Settle this after it merges. `[needs Ethan]` | -| preview deployment | preview, preview link | `[needs Ethan]` | -| Starter, Pro, Enterprise | Growth, Hobby, free plan | Current plan names. `[existing: memory, July 2026]` | -| sign in, sign in to | log in, login (as a verb), sign into | `[Google word list]`; "sign into" is `[existing: Vale]` | +| Mintlify | mintlify | Company and product. | +| dashboard | Dashboard | | +| editor | Web Editor | the editor can be accessed in a web browser or the desktop app, so make sure it is clear what you're referring to | +| CLI | cli, command-line tool | | +| `mint` | mint (unformatted) | The CLI command, in code format. | +| `docs.json` | docs.json (unformatted), mint.json | Always in code format. mint.json is the legacy name; mention it only in migration content. | +| MDX | mdx, Mdx | | +| frontmatter | front matter, front-matter | | +| API playground | API Playground | Can refer to it as the playground when the context is clear | +| assistant | Assistant, AI assistant, chatbot | | +| agent | Agent, Mintlify agent, AI agent | | +| automations | workflows | Automations were previously called workflows | +| project | deployment | Projects were previously called deployments | +| preview deployment | preview, preview link | | +| Starter, Pro, Enterprise | Growth, Hobby, free plan | Current plan names. | +| sign in, sign in to | log in, login (as a verb), sign into | | ## Technical terms | Use | Don't use | Notes | | --- | --- | --- | -| boolean | bool | In prose and property descriptions. `[existing: CLAUDE.md]` | -| OpenAPI | Open API, openapi | `[new, needs Ethan]` | -| llms.txt | LLMs.txt, llms-txt | `[new, needs Ethan]` | -| MCP server | MCP Server | `[new, needs Ethan]` | -| AI | A.I. | `[Google]` | +| boolean | bool | In prose and property descriptions. | +| OpenAPI | Open API, openapi | | +| llms.txt | LLMs.txt, llms-txt | | +| MCP server | MCP Server | | +| AI | A.I. | | -## Terms for readers' own things +## Miscellaneous -- "your docs," "your site," "your documentation site": pick one. `[needs Ethan]` -- "users" means the reader's audience, not the reader. Use "you" for the reader. `[new, needs Ethan]` +- "users" means the reader's audience interacting with their site, not the reader. Use "you" for the reader. From 76a032998e5c37b7902fe6a13ceadd6cf899fb3e Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Fri, 25 Sep 2026 16:37:53 -0700 Subject: [PATCH 07/14] style-guide: point Cursor rules at the style guide Replace duplicated and conflicting writing rules with a pointer to style-guide/. Keep component syntax examples only. Co-Authored-By: Claude Opus 5.5 (1M context) --- .cursor/rules/component-reference.mdc | 94 +--------- .cursor/rules/writing-standards.mdc | 240 ++------------------------ 2 files changed, 18 insertions(+), 316 deletions(-) diff --git a/.cursor/rules/component-reference.mdc b/.cursor/rules/component-reference.mdc index 7ca3818171..5b4c25494e 100644 --- a/.cursor/rules/component-reference.mdc +++ b/.cursor/rules/component-reference.mdc @@ -5,33 +5,30 @@ alwaysApply: true --- # Mintlify component reference +Syntax examples for Mintlify components. For when to use each component, and for all other writing and formatting rules, follow `style-guide/formatting-and-components.md`. + docs.json schema: https://mintlify.com/docs.json ### Callout components -#### Note - Additional helpful information -Supplementary information that supports the main content without interrupting flow. Use for helpful context, related concepts, or non-critical details. +Useful information the reader can skip without failing. -#### Tip - Best practices and pro tips -Expert advice, shortcuts, or best practices that enhance user success. Use for optimization suggestions, time-savers, or friendly recommendations. +A best practice or optional way to do something. -#### Warning - Important cautions -Critical information about potential issues, breaking changes, or destructive actions. Use sparingly and only for genuine risks. +Risk of data loss, security issues, or irreversible actions. -#### Info - Neutral contextual information -Background information, context, or neutral announcements. Use for prerequisites, permissions, or required setup information. +FEATURE requires a [Pro or Enterprise plan](https://mintlify.com/pricing?ref=FEATURE). -#### Check - Success confirmations -Positive confirmations, successful completions, or achievement indicators. Use to verify steps were completed correctly. +Your site is deployed. ### Code components @@ -227,7 +224,6 @@ Complete walkthrough from installation to your first API call in under 10 minute ### Media and advanced components #### Frames for images -Wrap all images in frames with descriptive alt text. Main dashboard showing analytics overview @@ -251,79 +247,3 @@ API - Fixed pagination issue with large datasets - Resolved authentication timeout problems - -## Required page structure - -Every documentation page must begin with YAML frontmatter: - -```yaml ---- -title: "Clear, specific, keyword-rich title" -description: "Concise description explaining page purpose and value" ---- -``` - -## Content quality standards - -### Code examples requirements -- Always include complete, runnable examples that users can copy and execute -- Show proper error handling and edge case management -- Use realistic data instead of placeholder values (you can use `minty`, `wintergreen`, `spearmint` or similar for Mintlify examples) -- Include expected outputs and results for verification -- Test all code examples thoroughly before publishing -- Specify language and include filename when relevant -- Add explanatory comments for complex logic -- Never include real API keys or sensitive credentials - -### API documentation requirements -- Document all parameters including optional ones with clear descriptions -- Show both success and error response examples with realistic data -- Include rate limiting information with specific limits -- Provide authentication examples showing proper format -- Explain all HTTP status codes and error handling -- Cover complete request/response cycles -- Include pagination details when applicable - -### Accessibility requirements -- Include descriptive alt text for all images and diagrams -- Use specific, actionable link text instead of "click here" -- Ensure proper heading hierarchy starting with H2 -- Provide keyboard navigation considerations -- Use sufficient color contrast in examples and visuals -- Structure content for easy scanning with headers and lists -- Use semantic HTML elements appropriately - -## Component selection logic - -### When to use each component -- **Steps**: Procedures, tutorials, setup guides, and sequential instructions -- **Tabs**: Platform-specific content, alternative approaches, or multiple installation methods -- **CodeGroup**: Same concept demonstrated in multiple programming languages -- **Accordions**: Supplementary information that might interrupt main flow -- **Cards/CardGroup**: Navigation, feature overviews, and related resources -- **Frame**: Wrap all images with descriptive captions when helpful -- **RequestExample/ResponseExample**: Specifically for API endpoint documentation -- **Expandable**: Nested object properties or hierarchical information -- **ParamField**: API parameters with types and requirements -- **ResponseField**: API response documentation with clear descriptions - -### Callout selection guidelines -- **Note**: Extra relevant information that supports main content (not crucial to task completion) -- **Warning**: Potentially destructive actions, breaking changes, or critical cautions -- **Info**: Required information, permissions, prerequisites, neutral announcements, background context -- **Tip**: Opinionated best practices, expert advice, shortcuts, or friendly recommendations -- **Check**: Success confirmations, positive completions, achievement indicators -- Don't stack callouts - separate with content between them - -## Component selection decision trees - -### For procedures: -- Use ordered lists when: Sequential simple tasks. For example "Navigate to the dashboard" or "Click Configurations" -- Use when: Sequential complex tasks that require subtasks to complete -- Use when: Platform-specific alternatives -- Use when: Optional supplementary info - -### For code examples: -- Use single ``` when: One language, simple example -- Use when: Same concept in multiple languages -- Use / when: API documentation diff --git a/.cursor/rules/writing-standards.mdc b/.cursor/rules/writing-standards.mdc index e6550a17a8..5c860df3f6 100644 --- a/.cursor/rules/writing-standards.mdc +++ b/.cursor/rules/writing-standards.mdc @@ -1,236 +1,18 @@ --- -description: -globs: +description: Writing and style standards for Mintlify documentation +globs: alwaysApply: true --- -# Mintlify technical documentation assistant +# Mintlify documentation writing standards -You are an AI writing assistant specialized in creating exceptional technical documentation using Mintlify components and following industry-leading technical writing practices. +Before you write or edit content, read `style-guide/README.md` and the style guide files relevant to your change. The style guide is the source of truth for voice, tone, terminology, formatting, component usage, and content strategy. It overrides the Google developer documentation style guide where they differ. -## Core writing principles +For component syntax, see `component-reference.mdc` or the pages in `components/`. -### Audience context -- The Mintlify audience is varied in technical skill level -- Support users who prefer to work locally with the CLI and are comfortable with Git -- Support users who use the web editor and prefer Git to be abstracted away -- Write content that serves both technical and non-technical users appropriately +## Before publishing -### Language and style requirements -- Use clear, direct language appropriate for technical audiences -- Write in second person ("you") for instructions and procedures -- Use active voice over passive voice -- Employ present tense for current states, future tense for outcomes -- Maintain consistent terminology throughout all documentation -- Keep sentences concise while providing necessary context -- Use parallel structure in lists, headings, and procedures -- Avoid jargon unless necessary, and define technical terms when first introduced - -### Content organization standards -- Lead with the most important information (inverted pyramid structure) -- Structure content in the order users need it: most commonly needed information first, most specific information last -- Use progressive disclosure: basic concepts before advanced ones -- Break complex procedures into numbered steps -- Include prerequisites and context before instructions -- Provide expected outcomes for each major step -- End sections with next steps or related information -- Use descriptive, keyword-rich headings for navigation and SEO -- Group related information logically with clear section breaks -- Combine related information to reduce redundancy - -### User-centered approach -- Focus on user goals and outcomes rather than system features -- Anticipate common questions and address them proactively -- Include troubleshooting for likely failure points -- Provide multiple pathways when appropriate (beginner vs advanced), but offer an opinionated path to avoid overwhelming users -- Write for scanning - use headers, lists, and visual breaks -- Include verification steps to confirm successful completion - -## Component-specific guidelines - -### Component introductions -- Start with action-oriented language: "Use [component] to..." rather than "The [component] component..." -- Be specific about what components can contain or do -- Make introductions practical and user-focused - -### Property descriptions -- End all property descriptions with periods for consistency -- Be specific and helpful for actual use cases rather than generic -- Add scope clarification where needed (for example, "For Font Awesome icons only:") -- Use proper technical terminology ("boolean" not "bool") - -### Code examples -- Keep examples simple and practical -- Use consistent formatting and naming -- Provide clear, actionable examples rather than showing multiple options when one will do - -## Mintlify component reference - -For detailed component syntax and examples, see the [component-reference.mdc](.cursor/rules/component-reference.mdc) file. - -## Voice and tone guidelines - -### Writing style -- Be clear and concise, but not robotic -- Maintain humanity like a helpful coworker explaining concepts -- Use active voice unless it makes sentences overly complex -- Write in second person ("you") for instructions and procedures -- Use present tense for current states, future tense for outcomes -- Avoid exclamation marks or overly casual language -- Keep sentences concise while providing necessary context - -### Anti-patterns to avoid -- **Avoid promotional language**: Never use phrases like "rich heritage," "breathtaking," "captivates," "stands as a testament," "plays a vital role," or similar marketing language in technical documentation -- **Be specific, not vague**: Replace vague attributions like "industry reports suggest" or "some experts argue" with specific, citable sources -- **Reduce conjunction overuse**: Limit use of "moreover," "furthermore," "additionally," "on the other hand" - favor direct, clear statements -- **Avoid editorializing**: Remove phrases like "it's important to note," "this article will," "in conclusion," or personal interpretations -- **No undue emphasis**: Avoid overstating importance or significance of routine technical concepts - -### Formatting discipline -- **Purposeful formatting**: Use bold, italics, and emphasis only when it serves the user's understanding, not for visual appeal -- **Clean structure**: Avoid excessive formatting or decorative elements that don't add functional value. Never use emoji -- **Minimal markup**: Keep formatting clean and functional, avoiding unnecessary markdown or styling - -### Content organization -- Lead with the most important information (inverted pyramid structure) -- Use progressive disclosure: basic concepts before advanced topics -- Break complex procedures into numbered steps with expected outcomes -- Include prerequisites and context before instructions begin -- Provide verification steps and expected results for major procedures -- End sections with next steps or related information links -- Use descriptive, keyword-rich headings for navigation and SEO - -## Terminology standards - -### Product terms -- **Mintlify**: The documentation platform (capitalize when referring to company/product) -- **Dashboard**: Web-based control panel (not Dashboard) -- **CLI**: Command line interface (always capitalize) -- **docs.json**: Configuration file (always lowercase, always with backticks) -- **MDX**: File format (always capitalize) -- **Frontmatter**: YAML metadata (one word, lowercase unless starting sentence) -- **Web editor**: Browser-based editor (lowercase) -- **API playground**: Interactive API docs (lowercase) -- **WYSIWYG**: What you see is what you get (always capitalize) - -### Capitalization Rules -- Use sentence case for page and section titles -- Few capitalizations for product/feature names (web editor, not Web Editor) -- Omit "Mintlify" from feature names when context is clear -- Use: "Users can query the assistant" not "Users can query the Mintlify assistant" -- Use: "After you push changes, your site will deploy" not "After you push changes, Mintlify deploys your site" - -## Technical standards - -### File structure -- Use kebab-case for file names: `web-editor.png` -- Store images in `/images` directory with feature-based subdirectories -- Save screenshots as `.png` files -- Every page must begin with YAML frontmatter containing title and description - -### Code and technical content -- Always use backticks for inline code: `docs.json` -- Specify language for code blocks with filename when relevant: ```javascript config.js -- Use sentence case for code block titles: "Expandable example" not "Expandable Example" -- Include complete, runnable examples that users can copy and execute -- Show proper error handling and edge case management in examples -- Use realistic data instead of generic placeholder values -- Include expected outputs and results for verification -- Add explanatory comments for complex logic -- Test all code examples thoroughly for accuracy -- Never commit API keys to version control in examples - -### UI and interactive elements -- Style interactive elements with **bold text**: Select **Publish Pull Request** -- Use keyboard notation: Press Command + K -- Don't style links with code formatting: Use "See [Pricing](mdc:http:/mintlify.com/pricing)" not "See [`docs.json`](mdc:settings)" -- Only include links when you want someone to follow them -- Each link is an exit opportunity - use sparingly -- Put related but non-essential links in "Further reading" sections -- Make links descriptive, avoid "Click here" patterns - -### Images and screenshots -- Every screenshot needs descriptive alt text -- Use colored rectangles for emphasis (no blur or overlays) -- Group related images in subdirectories -- Wrap all images in Frame components -- Include captions when they provide additional context - -## Quality Assurance Checklist - -### Before publishing -- Preview changes locally with `mint dev` -- Run `mint broken-links` to check internal links -- Manually test external links to ensure they don't 404 -- Run `vale $(git diff --name-only main)` to check style and spelling -- Verify all code examples are syntactically correct and executable -- Validate Mintlify component syntax with all required properties -- Confirm proper heading hierarchy with H2 for main sections, H3 for subsections. Do not use H1 (reserved for page title) -- Ensure content flows logically from basic concepts to advanced topics -- Check for consistency in terminology, formatting, and component usage -- Include appropriate warnings for destructive or security-sensitive actions -- Validate all technical information through testing before publication - -### Error prevention strategies -- Always include realistic error handling in code examples -- Provide dedicated troubleshooting sections for complex procedures -- Explain prerequisites clearly before beginning instructions -- Include verification and testing steps with expected outcomes -- Add appropriate warnings for destructive or security-sensitive actions -- Validate all technical information through testing before publication - -### Accessibility and usability -- Ensure technical accuracy through testing before publication -- Follow proper heading hierarchy (H2 for main sections, H3 for subsections) -- Include description frontmatter for SEO optimization -- Structure content consistently across similar page types -- Include descriptive alt text for all images and diagrams -- Use specific, actionable link text instead of generic phrases -- Ensure sufficient context for keyboard navigation -- Write clear, scannable content with headers and organized lists -- Verify all links are functional and lead to relevant content -- Test all procedures and validate expected outcomes -- Use parallel structure in lists, headings, and procedures - -## MDX and frontmatter requirements - -### Required fields -- **title**: Clear, specific, keyword-rich title in sentence case -- **description**: Concise description explaining page purpose and value - -### Optional fields -- **icon**: Visual identifier for the page -- **sidebarTitle**: Custom title for sidebar navigation -- **keywords**: SEO keywords for search optimization -- **mode**: Page-specific configuration - -### Component syntax -- Always include proper MDX component syntax: ``, ``, ``, etc. -- Use correct component attributes and nesting -- Validate component structure before publishing - -## Maintenance and updates - -### Redirects -- When moving or renaming a page, add a redirect for 18 months -- Check for links on other parts of mintlify.com when updating URLs -- Use "New" tags for features to emphasize for two weeks - -### Content updates -- Regularly review and update outdated information -- Remove deprecated features and references -- Update screenshots when UI changes occur -- Maintain consistency across related documentation pages - -## Request handling examples - -### When asked to "create a new page": -1. First, determine the appropriate location in the file structure -2. Create the file with proper frontmatter -3. Structure content using appropriate Mintlify components -4. Include relevant images and code examples - -### When asked to "improve existing content": -1. Review current structure and identify gaps -2. Suggest specific component improvements -3. Add missing callouts or examples -4. Ensure proper heading hierarchy +- Preview changes locally with `mint dev`. +- Run `mint broken-links` to check internal links. +- Run `mint a11y` to check for accessibility issues. +- Manually test external links to make sure they don't 404. +- Run `vale $(git diff --name-only main)` to check style and spelling. From eff44a3cfe7ba61c915d26705757e409efbb2008 Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Fri, 25 Sep 2026 16:38:14 -0700 Subject: [PATCH 08/14] style-guide: point CLAUDE.md at the style guide Remove writing, formatting, and content rules that duplicate the style guide. Keep agent workflow guidance and the pre-submit checklist. Fix the example component path. Co-Authored-By: Claude Opus 5.5 (1M context) --- .claude/CLAUDE.md | 85 ++++------------------------------------------- 1 file changed, 7 insertions(+), 78 deletions(-) diff --git a/.claude/CLAUDE.md b/.claude/CLAUDE.md index 3f9ff6d779..14d7bdf60e 100644 --- a/.claude/CLAUDE.md +++ b/.claude/CLAUDE.md @@ -15,7 +15,7 @@ You are an experienced, pragmatic technical writer with robust content strategy - Use direct tool calls (Read, Glob, Grep) instead of sub-agents when you know file paths or can search for specific terms - Only use the Explore agent for genuinely open-ended codebase searches -- Example: If asked to "update the accordion component docs", read `/content/components/accordions.mdx` directly rather than spawning an agent to find it +- Example: If asked to "update the accordion component docs", read `components/accordions.mdx` directly rather than spawning an agent to find it ### Workflow for complex tasks @@ -29,87 +29,21 @@ For major documentation restructuring or complex multi-page changes: - Config: docs.json for navigation, theme, settings - See the docs.json schema: https://mintlify.com/docs.json - Use Mintlify components. If you ever need to learn how a component works, search in the docs/components/ dir -- Only update English language content. All translations are handled automatically after a PR merges into the docs repo. This includes languages other than English in the docs.json navigation. -## Content strategy -- We document just enough so that users are successful. Too much content makes it hard to find what people are looking for. Too little makes it too challenging to accomplish users' goals. -- Prioritize accuracy and usability of information -- 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 -- When creating new pages, include them in the navigation group related to the user journey. For example, new content on customizing a site would go in the "Customize" group and information about adding a second deployment would go in "Deploy" +## Style guide -## Frontmatter requirements for pages -- title: Clear, descriptive page title -- description: Concise summary for SEO/navigation -- keywords: relevant keywords for search and SEO +Before you write or edit content, read `style-guide/README.md` and the style guide files relevant to your change. The style guide is the source of truth for audience, voice and tone, terminology, formatting, component usage, content strategy, and localization. It overrides the Google developer documentation style guide where they differ. Don't restate its rules here; update the style guide instead. -## Audience -- The Mintlify audience is varied. Some people are highly technical and others are not -- We need to support users who prefer to work locally with the CLI and are comfortable with Git and people who use the web editor and prefer Git to be abstracted away - -## Writing standards -- Second-person voice ("you") -- Prerequisites at start of procedural and tutorial content -- Match style and formatting of existing pages -- All code blocks must have language tags -- All images and media must have descriptive alt text -- Use root-relative paths for internal links like `/components/accordions` -- Lead with context when helpful - explain what something is before diving into implementation details -- Use sentence case for all headings ("Getting started", not "Getting Started") -- Use sentence case for code block titles ("Expandable example", not "Expandable Example") -- Use active voice and direct language -- Remove unnecessary words while maintaining clarity -- Break complex instructions into clear numbered steps -- Use [Lucide](https://lucide.dev) icon library -- Use kebab-case for file naming - -### Language and tone standards -- **Avoid promotional language**: Never use phrases like "rich heritage," "breathtaking," "captivates," "stands as a testament," "plays a vital role," or similar marketing language in technical documentation -- **Reduce conjunction overuse**: Limit use of "moreover," "furthermore," "additionally," "on the other hand" - favor direct, clear statements -- **Avoid editorializing**: Remove phrases like "it's important to note," "this article will," "in conclusion," or personal interpretations -- **No undue emphasis**: Avoid overstating importance or significance of routine technical concepts - -### Technical accuracy standards -- **Verify all links**: Every internal link and external reference must be tested and functional before publication -- **Use precise citations**: Replace vague references with specific documentation, version numbers, and accurate sources -- **Maintain consistency**: Use consistent terminology, formatting, and language variety throughout all documentation -- **Valid technical references**: Ensure all code examples, API references, and technical specifications are current and accurate - -### Formatting discipline - -- **Purposeful formatting**: Use bold, italics, and emphasis only when it serves the user's understanding, not for visual appeal -- **Clean structure**: Avoid excessive formatting or decorative elements that don't add functional value. Never use emoji -- **Minimal markup**: Keep formatting clean and functional, avoiding unnecessary markdown or styling - -### Component introductions -- Start with action-oriented language: "Use [component] to..." rather than "The [component] component..." -- Be specific about what components can contain or do -- Make introductions practical and user-focused - -### Property descriptions -- End all property descriptions with periods for consistency -- Be specific and helpful for actual use cases rather than generic -- Add scope clarification where needed (for example, "For Font Awesome icons only:") -- Use proper technical terminology ("boolean" not "bool") - -### Code examples -- Keep examples simple and practical -- Use consistent formatting and naming -- Provide clear, actionable examples rather than showing multiple options when one will do - -## Content organization -- Structure content in the order users need it with most commonly needed information first and most specific information last -- Combine related information to reduce redundancy +Beyond the style guide: +- Never lie, guess, or make up information. Verify links, code examples, and technical claims before you publish them. +- Check existing pages for patterns and match them. ## Before submitting work - [ ] Run `mint broken-links` to check internal links - [ ] Run `mint a11y` to check for accessibility issues - [ ] Manually test external links don't 404 - [ ] Run `vale $(git diff --name-only main)` to check style and spelling -- [ ] Verify all code blocks have language tags -- [ ] Confirm frontmatter includes title, description, keywords -- [ ] Check formatting matches similar existing pages +- [ ] Check changes against the style guide, not only Vale - [ ] Read changes aloud to catch awkward phrasing - [ ] List any uncertain areas that need extra review @@ -120,8 +54,3 @@ Provide a structured summary: - **Rationale**: Why these changes solve the problem - **Alternatives considered**: Other approaches evaluated - **Areas of uncertainty**: What needs extra review - -## Do not -- Skip frontmatter on any MDX file -- Use absolute URLs for internal links -- Include untested code examples From 9df7d6a2563f4de8c4207a07295fae7166579b26 Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Fri, 25 Sep 2026 16:38:18 -0700 Subject: [PATCH 09/14] style-guide: link the style guide from README, PR template, and Vale README Co-Authored-By: Claude Opus 5.5 (1M context) --- .github/pull_request_template.md | 1 + .vale/README.md | 2 ++ README.md | 2 ++ 3 files changed, 5 insertions(+) diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index 7066d4defc..b14926767f 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -21,6 +21,7 @@ When reviewing documentation PRs, please consider: - [ ] Steps are in logical order - [ ] Nothing important is missing - [ ] Examples help illustrate the concepts +- [ ] Content follows the [style guide](https://github.com/mintlify/docs/blob/main/style-guide/README.md) ### ✅ User experience - [ ] A new user could follow these docs successfully diff --git a/.vale/README.md b/.vale/README.md index a20b417e78..589b48dc39 100644 --- a/.vale/README.md +++ b/.vale/README.md @@ -6,6 +6,8 @@ This directory contains the Vale linting configuration for Mintlify documentatio Start simple and grow incrementally as needs emerge. +Vale enforces a subset of the [style guide](../style-guide/README.md). The style guide is the source of truth. When you add or change a rule, make sure it matches the style guide, and update the style guide in the same PR if the rule is new. + ## Vale files - `.vale.ini` - Main configuration file - `styles/config/vocabularies/Mintlify/` - Mintlify-specific terms diff --git a/README.md b/README.md index dcde62128d..88fe72c0a5 100644 --- a/README.md +++ b/README.md @@ -11,3 +11,5 @@ Run the following command at the root of your documentation (where docs.json is) ``` mint dev ``` + +Before contributing, read [CONTRIBUTING.md](CONTRIBUTING.md) and the [style guide](style-guide/README.md). From a528ca7953b8a34c362e3e108cef568bd2d7259c Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Fri, 25 Sep 2026 16:38:18 -0700 Subject: [PATCH 10/14] style-guide: fix stray backtick Co-Authored-By: Claude Opus 5.5 (1M context) --- style-guide/formatting-and-components.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/style-guide/formatting-and-components.md b/style-guide/formatting-and-components.md index b9d41c1328..140238bd38 100644 --- a/style-guide/formatting-and-components.md +++ b/style-guide/formatting-and-components.md @@ -35,7 +35,7 @@ Google's defaults apply: [headings](https://developers.google.com/style/headings ## Code blocks -- Every code block must have a language tag.` +- Every code block must have a language tag. - Code block headings use sentence case. - Add a filename title when the reader needs to know which file the code goes in, such as ` ```json docs.json `. - Examples are runnable and minimal, with realistic values, and include error handling only when relevant. From ccd959c09a962d3105a441586c5342121ad289f6 Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Fri, 25 Sep 2026 16:41:53 -0700 Subject: [PATCH 11/14] style-guide: add filename, localization nav, CodeGroup, and API reference rules Co-Authored-By: Claude Opus 5.5 (1M context) --- style-guide/content-strategy.md | 11 ++++++++++- style-guide/formatting-and-components.md | 1 + 2 files changed, 11 insertions(+), 1 deletion(-) diff --git a/style-guide/content-strategy.md b/style-guide/content-strategy.md index 4e27e77bf6..359002fde1 100644 --- a/style-guide/content-strategy.md +++ b/style-guide/content-strategy.md @@ -14,13 +14,14 @@ ## Where content goes - Put new pages in the nav group that matches the user journey. +- Filenames use kebab-case, such as `custom-domain.mdx`. - Order content by how often readers need it, most common tasks come first. - The help center is for agent-written content that answers specific user questions from conversations with support or the assistant. - Guides are end-to-end tutorials and best practices for concepts adjacent to Mintlify but not part of the platform itself. Like Git best practices or integrating Mintlify CLI commands into your CI pipeline. ## Localization -- Only edit English content. Translations in `es/`, `fr/`, and `zh/` are generated after merge by an automation. +- Only edit English content, including in `docs.json`. Don't change the navigation for other languages. Translations in `es/`, `fr/`, and `zh/` are generated after merge by an automation. - If you remove image files that are present in localized pages, the broken link check CI fails, but the translation automation will fix it. ## Page structure @@ -30,6 +31,14 @@ - Offer one opinionated path. Only show alternatives when readers genuinely choose between them. - Include a verification step or expected result for major procedures. +## API reference pages + +- Document every parameter, including optional ones. +- Show authentication with a correctly formatted example. +- Include success and error response examples with realistic data. +- List the HTTP status codes the endpoint returns and what each means. +- Include rate limits and pagination details when they apply. + ## Two workflows: editor (web or desktop app) and CLI - When a task can be done in the editor or locally via the CLI, cover both. Use tabs, or separate sections if the steps diverge a lot. diff --git a/style-guide/formatting-and-components.md b/style-guide/formatting-and-components.md index 140238bd38..94b7c82b53 100644 --- a/style-guide/formatting-and-components.md +++ b/style-guide/formatting-and-components.md @@ -38,6 +38,7 @@ Google's defaults apply: [headings](https://developers.google.com/style/headings - Every code block must have a language tag. - Code block headings use sentence case. - Add a filename title when the reader needs to know which file the code goes in, such as ` ```json docs.json `. +- Use `` to show the same example in more than one language. - Examples are runnable and minimal, with realistic values, and include error handling only when relevant. - Never put real API keys in examples. From e8ff07eff3cf7898e9630fd5745484069fbf7482 Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Fri, 25 Sep 2026 16:42:53 -0700 Subject: [PATCH 12/14] style-guide: only document rate limits when confirmed Co-Authored-By: Claude Opus 5.5 (1M context) --- style-guide/content-strategy.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/style-guide/content-strategy.md b/style-guide/content-strategy.md index 359002fde1..6e606d3ef3 100644 --- a/style-guide/content-strategy.md +++ b/style-guide/content-strategy.md @@ -37,7 +37,8 @@ - Show authentication with a correctly formatted example. - Include success and error response examples with realistic data. - List the HTTP status codes the endpoint returns and what each means. -- Include rate limits and pagination details when they apply. +- Include pagination details when they apply. +- Include rate limits if you can confirm them. Don't guess or leave a placeholder. ## Two workflows: editor (web or desktop app) and CLI From 3be1e3294974b1b5701265ed9e9d473e9c3ef9de Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Fri, 25 Sep 2026 16:47:54 -0700 Subject: [PATCH 13/14] style-guide: enforce product terms and phrases to cut in Vale - Add ProductTerms for unambiguous word-list swaps. vocab: false is required because Vale skips any match containing a vocabulary term (API, MCP, chatbot). - Add suggestion-level CutPhrases for the voice and tone list. - Downgrade Will to suggestion; the guide allows rare use. - Document how to add word-list terms to Vale. Co-Authored-By: Claude Opus 5.5 (1M context) --- .vale/styles/Mintlify/CutPhrases.yml | 27 ++++++++++++++++++++++++++ .vale/styles/Mintlify/ProductTerms.yml | 24 +++++++++++++++++++++++ .vale/styles/Mintlify/Will.yml | 2 +- style-guide/voice-and-tone.md | 2 ++ style-guide/word-list.md | 7 +++++-- 5 files changed, 59 insertions(+), 3 deletions(-) create mode 100644 .vale/styles/Mintlify/CutPhrases.yml create mode 100644 .vale/styles/Mintlify/ProductTerms.yml diff --git a/.vale/styles/Mintlify/CutPhrases.yml b/.vale/styles/Mintlify/CutPhrases.yml new file mode 100644 index 0000000000..6d8851905a --- /dev/null +++ b/.vale/styles/Mintlify/CutPhrases.yml @@ -0,0 +1,27 @@ +extends: existence +message: "Cut or rephrase '%s'. See 'Phrases to cut' in the style guide." +link: https://github.com/mintlify/docs/blob/main/style-guide/voice-and-tone.md +level: suggestion +ignorecase: true +tokens: + # Promotional + - seamless(?:ly)? + - breathtaking + - captivat(?:e|es|ing) + - rich heritage + - stands as a testament + - plays an? (?:vital|crucial|key|pivotal) role + - powerful + # Editorializing + - it(?:'s| is) important to note + - it(?:'s| is) worth noting + - this (?:article|page|guide) will + - in conclusion + - needless to say + # Filler transitions + - moreover + - furthermore + - additionally + # Vague attribution + - experts (?:say|agree|argue) + - industry reports suggest diff --git a/.vale/styles/Mintlify/ProductTerms.yml b/.vale/styles/Mintlify/ProductTerms.yml new file mode 100644 index 0000000000..04640f982f --- /dev/null +++ b/.vale/styles/Mintlify/ProductTerms.yml @@ -0,0 +1,24 @@ +extends: substitution +message: "Use '%s' instead of '%s'." +link: https://github.com/mintlify/docs/blob/main/style-guide/word-list.md +level: warning +ignorecase: false +vocab: false +action: + name: replace +swap: + "(?:Web|web) Editor": editor + "[Ff]ront[- ]matter": frontmatter + API Playground: API playground + MCP Server: MCP server + Open API: OpenAPI + chatbot: assistant + '(? Date: Fri, 25 Sep 2026 16:52:59 -0700 Subject: [PATCH 14/14] style-guide: allow AI assistant, AI agent, and Mintlify agent when context needs them Co-Authored-By: Claude Opus 5.5 (1M context) --- style-guide/voice-and-tone.md | 1 + style-guide/word-list.md | 4 ++-- 2 files changed, 3 insertions(+), 2 deletions(-) diff --git a/style-guide/voice-and-tone.md b/style-guide/voice-and-tone.md index 20fc9567c5..6324b4516d 100644 --- a/style-guide/voice-and-tone.md +++ b/style-guide/voice-and-tone.md @@ -21,6 +21,7 @@ Google's defaults apply: [voice](https://developers.google.com/style/voice), [to - Only rarely use "we" to refer to Mintlify after already naming the company earlier in the page. - Don't put "Mintlify" in a feature name when the context is clear: "the assistant," not "the Mintlify assistant." +- Use "Mintlify" in a feature name when readers need to tell it apart from similar tools, such as "the Mintlify agent" on a page that also covers coding agents. - Make the reader or their site the subject rather than Mintlify. Write "After you push changes, your site deploys," not "Mintlify deploys your site." ## Phrases to cut diff --git a/style-guide/word-list.md b/style-guide/word-list.md index 6eeb5af7bf..a5c72206c1 100644 --- a/style-guide/word-list.md +++ b/style-guide/word-list.md @@ -22,8 +22,8 @@ In general, Mintlify product names are lowercase if they are terms commonly used | MDX | mdx, Mdx | | | frontmatter | front matter, front-matter | | | API playground | API Playground | Can refer to it as the playground when the context is clear | -| assistant | Assistant, AI assistant, chatbot | | -| agent | Agent, Mintlify agent, AI agent | | +| assistant | Assistant, chatbot | Use "AI assistant" when readers need context about what the assistant is or when you describe the general category. | +| agent | Agent | Use "Mintlify agent" to distinguish it from other agents, such as coding agents. Use "AI agent" for the general category. | | automations | workflows | Automations were previously called workflows | | project | deployment | Projects were previously called deployments | | preview deployment | preview, preview link | |