-
Notifications
You must be signed in to change notification settings - Fork 13.7k
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.
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
Markdownlint: note-box-headings
custom rule
#28372
base: main
Are you sure you want to change the base?
Markdownlint: note-box-headings
custom rule
#28372
Conversation
Add to markdownlint config custom rules array
Original propose TOP011 closed
Now made generic for multiple aspects of note box headings
3 different types of note box heading errors now - missing heading - incorrect heading level - incorrect heading start text (type-dependent) Will help make note boxes more accessible (linkable via heading id fragment, and note box type not limited to visual differences and div class).
note-box-heading-level
custom rulenote-box-headings
custom rule
Rule converted from heading level to a general note box heading rule. Only the heading level error is practical to fix via a script. |
To follow this new lint rule.
Fix formatting
Point for consideration: Prior staff discussion highlighted the value in accessibility for making note box headings mandatory and including the note box type in the heading. If we land this rule, existing note box headings will need to be converted when they flag the lint error. However, MD051 (the lint rule that checks for valid link fragments) was disabled in #28701. Therefore, any existing links to the old note box heading will be invalid if not also changed, and the lack of MD051 means the linter won't catch the broken link. This would typically occur with links in the Knowledge Check section if they reference a note box. |
Because
As discussed with staff, for better accessibility, note boxes should have headings which will make them click-linkable. These headings should have a consistent heading level enforced. Accessibility can also be improved by including the note box type as part of the heading (e.g. warning boxes with a heading like "Warning: Insert common pitfall here"), as we're currently only differentiating between types via border colour and small icons.
This PR
Issue
N/A
Additional Information
Pull Request Requirements
location of change: brief description of change
format, e.g.Intro to HTML and CSS lesson: Fix link text
Because
section summarizes the reason for this PRThis PR
section has a bullet point list describing the changes in this PRIssue
section