feat: flag bad descriptive text#190
Conversation
There was a problem hiding this comment.
Pull request overview
Adds a new Vale (Canonical) style rule to flag non-descriptive link text (e.g., “here”, “click here”) to improve accessibility, addressing issue #145.
Changes:
- Enable
Canonical.027-bad-descriptive-linksin the Vale configuration. - Add a new Vale rule (
027-bad-descriptive-links) with regexes covering Markdown, reST, and Sphinx/MyST roles. - Add manifest-driven pytest cases to validate the new rule behavior for md/rst.
Reviewed changes
Copilot reviewed 3 out of 3 changed files in this pull request and generated 3 comments.
| File | Description |
|---|---|
vale.ini |
Registers the new Canonical rule and sets its configured alert level. |
styles/Canonical/027-bad-descriptive-links.yml |
Implements the new rule patterns and message. |
tests/data/manifest.yml |
Adds test coverage for the new rule (plus relocates the existing 026 block). |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
|
Similar feedback to @dwilding (good catch!) |
AnneCYH
left a comment
AnneCYH
left a comment
There was a problem hiding this comment.
Approve with the expectation of addressing David's feedback.
Nice rule!
| - id: bad-link-text-md | ||
| filetypes: [md] | ||
| content: | | ||
| See [here](https://example.com) for details. |
There was a problem hiding this comment.
Food for thought: I feel like the boilerplate should be self-explanatory, but with these full sentences it could look like we're testing for specific verbs and phrases. Might be clearer to leave out the surrounding text.
There was a problem hiding this comment.
The idea is that the test cases aren't just atomic representations of cases to capture - but rather a semi-realistic case that should be captured (or not captured) to give some level of confidence that it's ready to be applied. This has been important for rules like 004-Canonical-product-names.
| Canonical.025b-latinisms-to-reconsider = suggestion | ||
| Canonical.025c-latinisms-to-avoid = suggestion | ||
| Canonical.026-hints-tips = suggestion | ||
| Canonical.027-bad-descriptive-links = warning |
There was a problem hiding this comment.
What was the motivation for making this one a warning?
There was a problem hiding this comment.
It was the level Daniele wanted, but also given possible issues with accuracy, completeness, or even some possible false positives it's probably good to have at this level.
The idea will be for error level results to block PRs - not warnings or suggestions.
Addresses #145