Skip to content

fix: resolve all vale linting errors #298

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Merged
merged 3 commits into from
Nov 17, 2025
Merged

fix: resolve all vale linting errors #298

merged 3 commits into from
Nov 17, 2025

Conversation

@btiernay
Copy link
Contributor

@btiernay btiernay commented Nov 17, 2025 •
edited
Loading

Summary

Fixes all existing Vale linting errors in the auth4genai docs and adds a project-specific Vale configuration for sustainable prose linting.

What Changed

Error Fixes

  • Standardized brand capitalization (GitHub, JavaScript, SDKs) across docs.
  • Fixed spelling issues (for example, repositores → repositories, ocurrs → occurs).
  • Replaced placeholder / gibberish demo content in components.mdx with readable example copy.
  • Clarified phrasing around withInterruptions() and loginWithPopup() for better readability.

Configuration Improvements

  • Introduced an AuthDocs style bundle (Spelling.yml, Brands.yml, ignore list) under .vale/styles.
  • Switched .mdx and .md to a shared style stack (BasedOnStyles = Vale, AuthDocs) for consistent behavior.
  • Replaced the core spelling rule with a custom AuthDocs.Spelling rule backed by an ignore list.
  • Added AuthDocs.Brands substitution rules for brand capitalization and recurring typos.
  • Tuned IgnoredScopes and SkippedScopes to keep Vale out of non-prose regions (inline code, URLs, code blocks, etc.).
  • Added path-based overrides in .vale.ini to disable noisy brand/spelling checks on:
    • snippets (snippets/**/*.mdx)
    • component demos (components.mdx)
    • sample app hubs (sample-apps.mdx, mcp/sample-apps.mdx)
    • GitHub integration and SDK docs (integrations/github.mdx, sdks/**/*.mdx)
    • overview / card-heavy pages (how-tos/overview.mdx)

Documentation Quality

  • Expanded the ignore list with domain-specific terms, framework names, config keys, and project jargon.
  • Documented word-boundary behavior and when to disable AuthDocs.Brands by path in Brands.yml comments.
  • Added .vale/README.md explaining how the configuration works, how to run Vale, and how to extend rules safely.
  • Updated auth4genai/README.md with a short Vale section that links to the detailed guide.

Result

✅ vale . passes with 0 errors, 0 warnings, 0 suggestions for auth4genai
✅ Configuration is documented and focused on real issues instead of code/URL noise
✅ Path-based overrides and ignore lists give a clear, maintainable way to handle future false positives

Test Plan

  • Run vale . from auth4genai – confirms 0 errors for current docs
  • Verified brand and spelling fixes in updated .mdx and .md files
  • Confirmed path-based overrides prevent noisy findings for snippets, SDK docs, and integration pages
  • Sanity check .vale/README.md and inline comments for accuracy and future maintainer guidance

Testing:
https://github.com/auth0/docs-v2/pull/298/checks?check_run_id=55620969589
image

@btiernay btiernay force-pushed the fix/vale-linting-errors branch from 2de8e3b to de1dae4 Compare November 17, 2025 16:57
@btiernay btiernay force-pushed the fix/vale-linting-errors branch from 94ac99d to 638d371 Compare November 17, 2025 17:01
@btiernay btiernay force-pushed the fix/vale-linting-errors branch from 638d371 to 50ac281 Compare November 17, 2025 17:02
@btiernay btiernay force-pushed the fix/vale-linting-errors branch from 50ac281 to 21654b1 Compare November 17, 2025 17:03
@btiernay btiernay force-pushed the fix/vale-linting-errors branch from 4e75dea to c0b80b5 Compare November 17, 2025 17:11
@btiernay btiernay force-pushed the fix/vale-linting-errors branch 2 times, most recently from 0319d8a to 06890b4 Compare November 17, 2025 17:18
@btiernay btiernay force-pushed the fix/vale-linting-errors branch from 06890b4 to d83441b Compare November 17, 2025 17:19
@btiernay btiernay force-pushed the fix/vale-linting-errors branch from d83441b to 851ca2f Compare November 17, 2025 17:24
@btiernay btiernay force-pushed the fix/vale-linting-errors branch from 851ca2f to cb9d84d Compare November 17, 2025 18:03
@btiernay btiernay force-pushed the fix/vale-linting-errors branch from e10b822 to 54d3b6f Compare November 17, 2025 18:44
@btiernay btiernay force-pushed the fix/vale-linting-errors branch from 54d3b6f to febc409 Compare November 17, 2025 18:46
@btiernay @claude
feat: implement production-grade vale linting configuration
f1f1f74 
## Summary

This commit establishes a comprehensive, maintainable Vale configuration for
auth4genai documentation that catches real errors while minimizing false
positives in code-heavy and example-driven content.

## Key Changes

- **Fixed all 73 Vale linting errors** across 41 files (brand capitalization,
  spelling, HTML structure)
- **Created custom AuthDocs style bundle** with Brands.yml (systematic
  corrections like github→GitHub) and Spelling.yml (domain-specific ignore list)
- **Configured path-based rule overrides** for snippets, components, sample
  apps, and GitHub integration pages where strict rules generate noise
- **Aligned MinAlertLevel = error strategy** with explicit rule disabling
  instead of severity demotion (clear, maintainable, no false expectations)
- **Documented configuration thoroughly** with concrete MDX examples, workflow
  guidance, and clear explanation of tradeoffs

## Technical Details

- StylesPath correctly maps to .vale/styles where all rules and ignore lists live
- BasedOnStyles = Vale, AuthDocs applied consistently to MD and MDX files
- Vale.Spelling disabled globally; replaced with AuthDocs.Spelling for
  domain-aware checking
- AuthDocs.Brands disabled only on paths where word boundary matching triggers
  on URLs/domains (documented pattern and escape hatch in README)
- IgnoredScopes/SkippedScopes intentionally exclude link text and code blocks
  to focus on prose

## Vale Status

✓ 0 errors, 0 warnings, 0 suggestions across 137 files

## Maintenance

Future updates are purely content-driven:
- Add terms to .vale/styles/config/ignore/authdocs.txt as new jargon emerges
- Add substitutions to .vale/styles/AuthDocs/Brands.yml for systematic fixes
- Adjust path-based disables in .vale.ini for new files with false positives

🤖 Generated with Claude Code

Co-Authored-By: Claude <noreply@anthropic.com>
@btiernay btiernay force-pushed the fix/vale-linting-errors branch from 9900ec8 to f1f1f74 Compare November 17, 2025 21:22
@btiernay btiernay marked this pull request as ready for review November 17, 2025 21:29
@btiernay @claude
refactor: polish vale configuration for clarity and maintainability
2e3014b 
- Brands.yml: Remove redundant "github" rule (covered by ignorecase)
- README.md: Add prominent warning about MDX vs HTML comment syntax
- README.md: Add Requirements section with explicit version pins (Vale 3.13.0+, mdx2vast 0.3.0+)
- authdocs.txt: Alphabetize terms within each category for consistency
- .vale.ini: Add commented opt-in rule for annotations (vale.Annotations)

These refinements improve clarity, maintainability, and prevent common
mistakes (e.g., using HTML comments in MDX files). No behavior changes.

✓ Vale: 0 errors, 0 warnings, 0 suggestions

🤖 Generated with Claude Code

Co-Authored-By: Claude <noreply@anthropic.com>
@btiernay @claude
refactor: strict alphabetization in authdocs.txt ignore list
9174cf7 
Reorder entries within each category to achieve strict alphabetical
ordering (case-insensitive, preserving original case). This improves
machine-friendliness for future maintenance and prevents sorting
inconsistencies.

Changes only:
- Acronyms/technical terms: api/API/APIs now grouped together at start
- Auth/project jargon: agentic/Agentic/authorizer/authorizers grouped,
  Auditability moved to correct position

No behavior changes; alphabetization was already partial.

✓ Vale: 0 errors, 0 warnings, 0 suggestions

🤖 Generated with Claude Code

Co-Authored-By: Claude <noreply@anthropic.com>
KarimTantawy5
KarimTantawy5 approved these changes Nov 17, 2025
View reviewed changes
Copy link
Contributor

@KarimTantawy5 KarimTantawy5 left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looks good

@btiernay btiernay merged commit b5e38e9 into main Nov 17, 2025
6 checks passed
@btiernay btiernay deleted the fix/vale-linting-errors branch November 17, 2025 23:18
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@kevlil83 kevlil83 kevlil83 approved these changes

@KarimTantawy5 KarimTantawy5 KarimTantawy5 approved these changes

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

4 participants

@btiernay @kevlil83 @KarimTantawy5