Add style guide - #7526
Merged
Merged
Add style guide#7526
Conversation
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
…ions Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
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) <noreply@anthropic.com>
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) <noreply@anthropic.com>
…README Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
…ence rules Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
- 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) <noreply@anthropic.com>
…ntext needs them Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Contributor
|
Preview deployment for your docs. Learn more about Mintlify Previews.
|
11 tasks
This branch was successfully deployed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Documentation changes
v1 of the Mintlify docs style guide
Adds style guide
Updates Vale to adhere to it
Updates agent context files to point to it instead of having contradictory style rules
For Reviewers
When reviewing documentation PRs, please consider:
✅ Technical accuracy
✅ Clarity and completeness
✅ User experience
Note
Low Risk
Internal contributor/agent documentation and lint rules only; no published user-facing docs content or runtime behavior changes.
Overview
Introduces a new
style-guide/tree (voice/tone, word list, formatting/components, content strategy) as the single source of truth for Mintlify docs writing. It defers to Google’s guide where silent, overrides where Mintlify-specific, and is excluded from the published site via.mintignore.Agent and contributor tooling no longer duplicate long rule lists:
.claude/CLAUDE.md,.cursor/rules/writing-standards.mdc, and.cursor/rules/component-reference.mdcnow point authors at the style guide; the component reference keeps syntax examples only. CONTRIBUTING.md, README.md, the PR template, and.mintlify/AGENTS.mdadd explicit “read the style guide” expectations, including a checklist item to verify against the guide—not only Vale.Vale is aligned with the guide: new
CutPhrases.ymlandProductTerms.yml,Will.ymldowngraded to suggestion, and.vale/README.mddocuments that Vale enforces a subset and must stay in sync when rules change.Reviewed by Cursor Bugbot for commit 0920feb. Bugbot is set up for automated code reviews on this repo. Configure here.