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 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. 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/.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/.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/.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/.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 + '(?` 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`. +- Remove deprecated features rather than keeping "deprecated" callouts, except during an announced migration window. +- Update screenshots when the UI changes. + +## Changelog + +- 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 new file mode 100644 index 0000000000..94b7c82b53 --- /dev/null +++ b/style-guide/formatting-and-components.md @@ -0,0 +1,70 @@ +# Formatting and components + +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`, `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. +- Start at H2. H1 is the page title. + +## Text formatting + +- 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. +- 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 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. + +## Images + +- 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 + +Use callouts sparingly. Never put multiple callouts back-to-back. + +| 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 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 new file mode 100644 index 0000000000..6324b4516d --- /dev/null +++ b/style-guide/voice-and-tone.md @@ -0,0 +1,51 @@ +# Voice and tone + +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 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. 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" + +- Use present tense by default. Use "will" rarely for events that only occur later. + +## Referring to Mintlify + +- 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 + +Vale flags these as suggestions with `.vale/styles/Mintlify/CutPhrases.yml`. Keep the two lists in sync. + +- 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 + +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 + +## Em dashes + +- 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 new file mode 100644 index 0000000000..a5c72206c1 --- /dev/null +++ b/style-guide/word-list.md @@ -0,0 +1,45 @@ +# Word list + +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` and the unambiguous product terms from this list in `.vale/styles/Mintlify/ProductTerms.yml`. + +When you add a term here: + +- If the "Don't use" form is unambiguous, add a swap to `ProductTerms.yml`. +- If Vale flags the term as a misspelling, add it to `.vale/styles/config/vocabularies/Mintlify/accept.txt`. Prefix the entry with `(?i)` unless you want Vale to enforce its capitalization. An entry with capitals, like `Agent`, flags every lowercase "agent." + +## 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 | 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, 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 | | +| 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. | +| OpenAPI | Open API, openapi | | +| llms.txt | LLMs.txt, llms-txt | | +| MCP server | MCP Server | | +| AI | A.I. | | + +## Miscellaneous + +- "users" means the reader's audience interacting with their site, not the reader. Use "you" for the reader.