Consider consistent header anchors
Everyone can contribute. Help move this issue forward while earning points, leveling up and collecting rewards.
Purpose
Consider a consistent behavior for indicating and going to a linked markdown heading. There are multiple methods currently used and there are also known accessibility problems (see linked issues).
| Property | Example |
|---|---|
| GitLab.com |  |
| Pajamas |  |
| Handbook |  |
| Docs |  |
Current state
Indicator placement
- Before heading:
- Positioned in the margin to the left of the heading.
- Can be cropped by other elements (like sidebar navigation) or the viewport in narrow views.
- After heading:
- Positioned to the right of the last character in the heading.
- Wraps with text, but can create a blank line below the heading when only the indicator would wrap and appear on a new line.
Indicator element
- Link icon to represent a link: 3/4 use a link icon, however, none are using the link icon from GitLab SVGs.
- Hash character (#) to represent the hash appended to the URL: 1/4 use a hash character that uses the related heading styles.
Proposal
Indicator placement
- TBD
Indicator element
- If link icon is used, it should be the link icon from GitLab SVGs and always at 16px.
- TBD
Expected behavior
- Indicator appears when hovering over the heading.
- Indicator appears when focused (similar to how a skip link works before the navigation).
- Indicator for touch modality: TBD
- Link is announced correctly for assistive technology.
- Before heading: After hovering the heading, a mouse user moves backwards (left) to access the control.
- After heading: After hovering the heading, a mouse user moves forward (right) in the reading order to access the control.
- RTL languages: TBD
- Indicator should neither overlap or be clipped by other content or constraints.
Other options
The heading text itself could be a link (<h2><a></a></h2>) as mentioned here. The popular site, MDN Web Docs uses this approach.
Resources
Edited by 🤖 GitLab Bot 🤖