feat(docs): implement consolidated documentation linting with Vale #18220
Conversation
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
- Add Vale configuration for prose quality checking - Create smart change detection workflow for docs-only PRs - Implement incremental vs full linting based on change type - Add new Makefile targets for Vale integration - Update CI to avoid duplicate markdown linting - Remove old docs-ci.yaml workflow - Add comprehensive documentation linting guide The new system: - Runs incremental checks on typical content edits - Runs full checks when headings, navigation, or structure changes - Integrates Vale for prose quality alongside markdownlint - Provides clear feedback on why full checks are triggered
- Update Vale config to use GitLab style guide patterns (warnings) - Add minimal Coder-specific style rules for product names - Create inclusive language rules that error on problematic terms - Change most Vale issues to warnings instead of errors - Update documentation to reflect conservative approach This addresses feedback to: - Focus on quality and inclusivity over rigid style enforcement - Only error on inclusive language violations - Use warnings for style suggestions that won't block CI - Incorporate valuable GitLab documentation patterns
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
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.
Summary
This PR implements the first phase of consolidated documentation linting with smart change detection, as discussed in the documentation quality improvement initiative.
Changes
🔧 New Vale Integration
.vale.iniconfiguration with Microsoft Writing Style Guide, alex, and write-good🎯 Smart Change Detection
.github/workflows/docs-quality.yamlworkflow with intelligent change detectiondocs/manifest.json)docs/images/**)🛠️ Enhanced Makefile Targets
make lint/markdown: Full linting with markdownlint + Valemake lint/markdown-incremental: Lint only changed filesmake lint/markdown-smart: Auto-choose incremental vs fullmake lint/vale: Vale-only prose quality checks🚀 CI Optimization
docs-ci.yamlworkflow (replaced bydocs-quality.yaml)📚 Documentation
docs/CONTRIBUTING.mdBenefits
Testing
Migration Notes
This is Phase 1 of the documentation quality improvement:
make lint/markdownPhase 2 (future): MegaLinter integration for comprehensive tooling consolidation.
Related