-
-
Notifications
You must be signed in to change notification settings - Fork 14.4k
Add "Skip to main content" link for keyboard navigation in rustdoc #151482
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
Conversation
|
Some changes occurred in HTML/CSS/JS. cc @GuillaumeGomez, @lolbinarycat Some changes occurred in GUI tests. |
This comment has been minimized.
This comment has been minimized.
|
Hey, thanks for the PR. I'll get a review in a day or two :) |
|
Hello, thank you for this PR, but I have a question: Why was the description generated using AI? Secondly, in my understanding, it should be reviewed by @GuillaumeGomez (or other rustdoc member) So... r? GuillaumeGomez |
|
@JayanAXHF why was A-a11y label added here? |
Because the topic addresses an a11y concern. (Skip nav links are for a11y primarily) |
+1 to this question |
| assert: ".skip-main-content" | ||
| assert-css: (".skip-main-content", {"position": "absolute"}) |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
It only checks that its position is absolute, not that it's not visible.
| assert-css: (".skip-main-content", {"position": "absolute"}) | ||
|
|
||
| // The skip link should become visible when focused | ||
| focus: ".skip-main-content" |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Since it's supposed to be focused with the keyboard, wouldn't it make more sense to ensure the first tab selected item is this one instead?
| assert-attribute: (".skip-main-content", {"href": "#main-content"}) | ||
|
|
||
| // Verify main-content section exists | ||
| assert: "#main-content" |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I mean... This item always exists. What should be checked is if it's focused.
| // Pressing Enter on the skip link should navigate to main content | ||
| press-key: "Enter" | ||
| // After navigation, focus should be on or near main content | ||
| assert-document-property: ({"URL": "index.html#main-content"}, ENDS_WITH) |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Would be nice to also check that the element is focused.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I think it's not useful to check that the anchor is present in the URL, checking that the main-content element is focused is enough.
| left: 0; | ||
| z-index: 1000; | ||
| padding: 0.5rem 1rem; | ||
| background-color: var(--main-background-color); |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I would suggest an accented bg color
| border: 1px solid var(--border-color); | ||
| border-radius: var(--button-border-radius); | ||
| text-decoration: none; | ||
| font-weight: 500; |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
nit: Are these styles really necessary?
|
Thank you all for the thorough review! Regarding the AI-generated description question from @Kivooeo and @JayanAXHF: Addressed all review feedback in the latest commit:
Please let me know if any further changes are needed! |
| assert-css: (".skip-main-content:focus", {"top": "0px"}) | ||
|
|
||
| // The link should point to #main-content | ||
| assert-attribute: (".skip-main-content", {"href": "#main-content"}) |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Not useful to check btw.
| outline: 2px solid var(--main-color); | ||
| outline-offset: 2px; |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Considering this element is only visible when focused, I think we can move these two properties into .skip-main-content {} and only keep top: 0 in here.
| outline-offset: 2px; | ||
| } | ||
| /* Hide focus outline on main-content when navigated via skip link */ | ||
| #main-content:focus { |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Wouldn't it be better to just always have outline: none instead of only on :focus?
|
Thanks for the detailed review @GuillaumeGomez! Updated in latest commit:
Regarding I kept this intentionally because it's required for the skip link to work correctly. Without it:
This is a standard accessibility pattern for skip links (see WebAIM skip nav and MDN focus management). Using
Happy to discuss if you have concerns about this approach! |
|
@GuillaumeGomez Good point! Added the initial Test flow now:
|
| top: 0; | ||
| } | ||
| #main-content { | ||
| outline: none; |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Move this property into the existing #main-content {} below.
|
@GuillaumeGomez Applied your suggestion - now checking |
|
Seems all good to me, thanks! @bors r+ rollup |
…r=GuillaumeGomez Add "Skip to main content" link for keyboard navigation in rustdoc ## Summary This PR adds a "Skip to main content" link for keyboard navigation in rustdoc, improving accessibility by allowing users to bypass the sidebar and navigate directly to the main content area. ## Changes - **`src/librustdoc/html/templates/page.html`**: Added a skip link (`<a class="skip-main-content">`) immediately after the `<body>` tag that links to `#main-content` - **`src/librustdoc/html/static/css/rustdoc.css`**: Added CSS styles for the skip link: - Visually hidden by default (`position: absolute; top: -100%`) - Becomes visible when focused via Tab key (`top: 0` on `:focus`) - Styled consistently with rustdoc theme using existing CSS variables - **`tests/rustdoc-gui/skip-navigation.goml`**: Added GUI test to verify the skip link functionality ## WCAG Compliance This addresses **WCAG Success Criterion 2.4.1 (Level A)** - Bypass Blocks: > A mechanism is available to bypass blocks of content that are repeated on multiple web pages. ## Demo When pressing Tab on a rustdoc page, the first focusable element is now the "Skip to main content" link, allowing keyboard users to jump directly to the main content without tabbing through the entire sidebar. ## Future Improvements Based on the discussion in rust-lang#151420, additional skip links could be added between the page summary and module contents sections. This PR provides the foundation, and we can iterate on adding more skip links based on feedback. Fixes rust-lang#151420 r? @JayanAXHF
…r=GuillaumeGomez Add "Skip to main content" link for keyboard navigation in rustdoc ## Summary This PR adds a "Skip to main content" link for keyboard navigation in rustdoc, improving accessibility by allowing users to bypass the sidebar and navigate directly to the main content area. ## Changes - **`src/librustdoc/html/templates/page.html`**: Added a skip link (`<a class="skip-main-content">`) immediately after the `<body>` tag that links to `#main-content` - **`src/librustdoc/html/static/css/rustdoc.css`**: Added CSS styles for the skip link: - Visually hidden by default (`position: absolute; top: -100%`) - Becomes visible when focused via Tab key (`top: 0` on `:focus`) - Styled consistently with rustdoc theme using existing CSS variables - **`tests/rustdoc-gui/skip-navigation.goml`**: Added GUI test to verify the skip link functionality ## WCAG Compliance This addresses **WCAG Success Criterion 2.4.1 (Level A)** - Bypass Blocks: > A mechanism is available to bypass blocks of content that are repeated on multiple web pages. ## Demo When pressing Tab on a rustdoc page, the first focusable element is now the "Skip to main content" link, allowing keyboard users to jump directly to the main content without tabbing through the entire sidebar. ## Future Improvements Based on the discussion in rust-lang#151420, additional skip links could be added between the page summary and module contents sections. This PR provides the foundation, and we can iterate on adding more skip links based on feedback. Fixes rust-lang#151420 r? @JayanAXHF
…r=GuillaumeGomez Add "Skip to main content" link for keyboard navigation in rustdoc ## Summary This PR adds a "Skip to main content" link for keyboard navigation in rustdoc, improving accessibility by allowing users to bypass the sidebar and navigate directly to the main content area. ## Changes - **`src/librustdoc/html/templates/page.html`**: Added a skip link (`<a class="skip-main-content">`) immediately after the `<body>` tag that links to `#main-content` - **`src/librustdoc/html/static/css/rustdoc.css`**: Added CSS styles for the skip link: - Visually hidden by default (`position: absolute; top: -100%`) - Becomes visible when focused via Tab key (`top: 0` on `:focus`) - Styled consistently with rustdoc theme using existing CSS variables - **`tests/rustdoc-gui/skip-navigation.goml`**: Added GUI test to verify the skip link functionality ## WCAG Compliance This addresses **WCAG Success Criterion 2.4.1 (Level A)** - Bypass Blocks: > A mechanism is available to bypass blocks of content that are repeated on multiple web pages. ## Demo When pressing Tab on a rustdoc page, the first focusable element is now the "Skip to main content" link, allowing keyboard users to jump directly to the main content without tabbing through the entire sidebar. ## Future Improvements Based on the discussion in rust-lang#151420, additional skip links could be added between the page summary and module contents sections. This PR provides the foundation, and we can iterate on adding more skip links based on feedback. Fixes rust-lang#151420 r? @JayanAXHF
…uwer Rollup of 7 pull requests Successful merges: - #149848 (Use allocator_shim_contents in allocator_shim_symbols) - #150556 (Add Tier 3 Thumb-mode targets for Armv7-A, Armv7-R and Armv8-R) - #151259 (Fix is_ascii performance regression on AVX-512 CPUs when compiling with -C target-cpu=native) - #151482 (Add "Skip to main content" link for keyboard navigation in rustdoc) - #151505 (Various refactors to the proc_macro bridge) - #151517 (Enable reproducible binary builds with debuginfo on Linux) - #151540 (Tweak bounds check in `DepNodeColorMap.get`) r? @ghost
…r=GuillaumeGomez Add "Skip to main content" link for keyboard navigation in rustdoc ## Summary This PR adds a "Skip to main content" link for keyboard navigation in rustdoc, improving accessibility by allowing users to bypass the sidebar and navigate directly to the main content area. ## Changes - **`src/librustdoc/html/templates/page.html`**: Added a skip link (`<a class="skip-main-content">`) immediately after the `<body>` tag that links to `#main-content` - **`src/librustdoc/html/static/css/rustdoc.css`**: Added CSS styles for the skip link: - Visually hidden by default (`position: absolute; top: -100%`) - Becomes visible when focused via Tab key (`top: 0` on `:focus`) - Styled consistently with rustdoc theme using existing CSS variables - **`tests/rustdoc-gui/skip-navigation.goml`**: Added GUI test to verify the skip link functionality ## WCAG Compliance This addresses **WCAG Success Criterion 2.4.1 (Level A)** - Bypass Blocks: > A mechanism is available to bypass blocks of content that are repeated on multiple web pages. ## Demo When pressing Tab on a rustdoc page, the first focusable element is now the "Skip to main content" link, allowing keyboard users to jump directly to the main content without tabbing through the entire sidebar. ## Future Improvements Based on the discussion in rust-lang#151420, additional skip links could be added between the page summary and module contents sections. This PR provides the foundation, and we can iterate on adding more skip links based on feedback. Fixes rust-lang#151420 r? @JayanAXHF
Rollup of 6 pull requests Successful merges: - #149848 (Use allocator_shim_contents in allocator_shim_symbols) - #150556 (Add Tier 3 Thumb-mode targets for Armv7-A, Armv7-R and Armv8-R) - #151259 (Fix is_ascii performance regression on AVX-512 CPUs when compiling with -C target-cpu=native) - #151482 (Add "Skip to main content" link for keyboard navigation in rustdoc) - #151505 (Various refactors to the proc_macro bridge) - #151517 (Enable reproducible binary builds with debuginfo on Linux) r? @ghost
…r=GuillaumeGomez Add "Skip to main content" link for keyboard navigation in rustdoc ## Summary This PR adds a "Skip to main content" link for keyboard navigation in rustdoc, improving accessibility by allowing users to bypass the sidebar and navigate directly to the main content area. ## Changes - **`src/librustdoc/html/templates/page.html`**: Added a skip link (`<a class="skip-main-content">`) immediately after the `<body>` tag that links to `#main-content` - **`src/librustdoc/html/static/css/rustdoc.css`**: Added CSS styles for the skip link: - Visually hidden by default (`position: absolute; top: -100%`) - Becomes visible when focused via Tab key (`top: 0` on `:focus`) - Styled consistently with rustdoc theme using existing CSS variables - **`tests/rustdoc-gui/skip-navigation.goml`**: Added GUI test to verify the skip link functionality ## WCAG Compliance This addresses **WCAG Success Criterion 2.4.1 (Level A)** - Bypass Blocks: > A mechanism is available to bypass blocks of content that are repeated on multiple web pages. ## Demo When pressing Tab on a rustdoc page, the first focusable element is now the "Skip to main content" link, allowing keyboard users to jump directly to the main content without tabbing through the entire sidebar. ## Future Improvements Based on the discussion in rust-lang#151420, additional skip links could be added between the page summary and module contents sections. This PR provides the foundation, and we can iterate on adding more skip links based on feedback. Fixes rust-lang#151420 r? @JayanAXHF
Rollup of 8 pull requests Successful merges: - #150556 (Add Tier 3 Thumb-mode targets for Armv7-A, Armv7-R and Armv8-R) - #151346 (add `simd_splat` intrinsic) - #151500 (hexagon: Add HVX target features) - #151505 (Various refactors to the proc_macro bridge) - #151517 (Enable reproducible binary builds with debuginfo on Linux) - #151482 (Add "Skip to main content" link for keyboard navigation in rustdoc) - #151489 (constify boolean methods) - #151551 (Don't use default build-script fingerprinting in `test`) r? @ghost
…r=GuillaumeGomez Add "Skip to main content" link for keyboard navigation in rustdoc ## Summary This PR adds a "Skip to main content" link for keyboard navigation in rustdoc, improving accessibility by allowing users to bypass the sidebar and navigate directly to the main content area. ## Changes - **`src/librustdoc/html/templates/page.html`**: Added a skip link (`<a class="skip-main-content">`) immediately after the `<body>` tag that links to `#main-content` - **`src/librustdoc/html/static/css/rustdoc.css`**: Added CSS styles for the skip link: - Visually hidden by default (`position: absolute; top: -100%`) - Becomes visible when focused via Tab key (`top: 0` on `:focus`) - Styled consistently with rustdoc theme using existing CSS variables - **`tests/rustdoc-gui/skip-navigation.goml`**: Added GUI test to verify the skip link functionality ## WCAG Compliance This addresses **WCAG Success Criterion 2.4.1 (Level A)** - Bypass Blocks: > A mechanism is available to bypass blocks of content that are repeated on multiple web pages. ## Demo When pressing Tab on a rustdoc page, the first focusable element is now the "Skip to main content" link, allowing keyboard users to jump directly to the main content without tabbing through the entire sidebar. ## Future Improvements Based on the discussion in rust-lang#151420, additional skip links could be added between the page summary and module contents sections. This PR provides the foundation, and we can iterate on adding more skip links based on feedback. Fixes rust-lang#151420 r? @JayanAXHF
Rollup of 8 pull requests Successful merges: - #150556 (Add Tier 3 Thumb-mode targets for Armv7-A, Armv7-R and Armv8-R) - #151500 (hexagon: Add HVX target features) - #151505 (Various refactors to the proc_macro bridge) - #151517 (Enable reproducible binary builds with debuginfo on Linux) - #151482 (Add "Skip to main content" link for keyboard navigation in rustdoc) - #151489 (constify boolean methods) - #151551 (Don't use default build-script fingerprinting in `test`) - #151555 (Fix compilation of std/src/sys/pal/uefi/tests.rs) r? @ghost
…r=GuillaumeGomez Add "Skip to main content" link for keyboard navigation in rustdoc ## Summary This PR adds a "Skip to main content" link for keyboard navigation in rustdoc, improving accessibility by allowing users to bypass the sidebar and navigate directly to the main content area. ## Changes - **`src/librustdoc/html/templates/page.html`**: Added a skip link (`<a class="skip-main-content">`) immediately after the `<body>` tag that links to `#main-content` - **`src/librustdoc/html/static/css/rustdoc.css`**: Added CSS styles for the skip link: - Visually hidden by default (`position: absolute; top: -100%`) - Becomes visible when focused via Tab key (`top: 0` on `:focus`) - Styled consistently with rustdoc theme using existing CSS variables - **`tests/rustdoc-gui/skip-navigation.goml`**: Added GUI test to verify the skip link functionality ## WCAG Compliance This addresses **WCAG Success Criterion 2.4.1 (Level A)** - Bypass Blocks: > A mechanism is available to bypass blocks of content that are repeated on multiple web pages. ## Demo When pressing Tab on a rustdoc page, the first focusable element is now the "Skip to main content" link, allowing keyboard users to jump directly to the main content without tabbing through the entire sidebar. ## Future Improvements Based on the discussion in rust-lang#151420, additional skip links could be added between the page summary and module contents sections. This PR provides the foundation, and we can iterate on adding more skip links based on feedback. Fixes rust-lang#151420 r? @JayanAXHF
…uwer Rollup of 8 pull requests Successful merges: - #150556 (Add Tier 3 Thumb-mode targets for Armv7-A, Armv7-R and Armv8-R) - #151259 (Fix is_ascii performance regression on AVX-512 CPUs when compiling with -C target-cpu=native) - #151500 (hexagon: Add HVX target features) - #151517 (Enable reproducible binary builds with debuginfo on Linux) - #151482 (Add "Skip to main content" link for keyboard navigation in rustdoc) - #151489 (constify boolean methods) - #151551 (Don't use default build-script fingerprinting in `test`) - #151555 (Fix compilation of std/src/sys/pal/uefi/tests.rs) r? @ghost
Rollup merge of #151482 - ThanhNguyxn:fix/rustdoc-skip-nav, r=GuillaumeGomez Add "Skip to main content" link for keyboard navigation in rustdoc ## Summary This PR adds a "Skip to main content" link for keyboard navigation in rustdoc, improving accessibility by allowing users to bypass the sidebar and navigate directly to the main content area. ## Changes - **`src/librustdoc/html/templates/page.html`**: Added a skip link (`<a class="skip-main-content">`) immediately after the `<body>` tag that links to `#main-content` - **`src/librustdoc/html/static/css/rustdoc.css`**: Added CSS styles for the skip link: - Visually hidden by default (`position: absolute; top: -100%`) - Becomes visible when focused via Tab key (`top: 0` on `:focus`) - Styled consistently with rustdoc theme using existing CSS variables - **`tests/rustdoc-gui/skip-navigation.goml`**: Added GUI test to verify the skip link functionality ## WCAG Compliance This addresses **WCAG Success Criterion 2.4.1 (Level A)** - Bypass Blocks: > A mechanism is available to bypass blocks of content that are repeated on multiple web pages. ## Demo When pressing Tab on a rustdoc page, the first focusable element is now the "Skip to main content" link, allowing keyboard users to jump directly to the main content without tabbing through the entire sidebar. ## Future Improvements Based on the discussion in #151420, additional skip links could be added between the page summary and module contents sections. This PR provides the foundation, and we can iterate on adding more skip links based on feedback. Fixes #151420 r? @JayanAXHF

Summary
This PR adds a "Skip to main content" link for keyboard navigation in rustdoc, improving accessibility by allowing users to bypass the sidebar and navigate directly to the main content area.
Changes
src/librustdoc/html/templates/page.html: Added a skip link (<a class="skip-main-content">) immediately after the<body>tag that links to#main-contentsrc/librustdoc/html/static/css/rustdoc.css: Added CSS styles for the skip link:position: absolute; top: -100%)top: 0on:focus)tests/rustdoc-gui/skip-navigation.goml: Added GUI test to verify the skip link functionalityWCAG Compliance
This addresses WCAG Success Criterion 2.4.1 (Level A) - Bypass Blocks:
Demo
When pressing Tab on a rustdoc page, the first focusable element is now the "Skip to main content" link, allowing keyboard users to jump directly to the main content without tabbing through the entire sidebar.
Future Improvements
Based on the discussion in #151420, additional skip links could be added between the page summary and module contents sections. This PR provides the foundation, and we can iterate on adding more skip links based on feedback.
Fixes #151420
r? @JayanAXHF