Skip to content

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.

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

Merged
rust-bors merged 1 commit into from
Jan 24, 2026
Merged

Add "Skip to main content" link for keyboard navigation in rustdoc #151482

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
19 changes: 19 additions & 0 deletions src/librustdoc/html/static/css/rustdoc.css
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -210,6 +210,24 @@ body {
color: var(--main-color);
}

/* Skip navigation link for keyboard users (WCAG 2.4.1) */
.skip-main-content {
position: absolute;
left: 0;
top: -100%;
z-index: 1000;
padding: 0.5rem 1rem;
background-color: var(--main-background-color);
color: var(--main-color);
text-decoration: none;
font-weight: 500;
Copy link
Member

@JayanAXHF JayanAXHF Jan 22, 2026

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?

border-bottom-right-radius: 4px;
outline: 2px solid var(--search-input-focused-border-color);
}
.skip-main-content:focus {
top: 0;
}

h1 {
font-size: 1.5rem; /* 24px */
}
Expand Down Expand Up @@ -1114,6 +1132,7 @@ pre, .rustdoc.src .example-wrap, .example-wrap .src-line-numbers {

#main-content {
position: relative;
outline: none;
}

.docblock table {
Expand Down
3 changes: 2 additions & 1 deletion src/librustdoc/html/templates/page.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -66,6 +66,7 @@
{{ layout.external_html.in_header|safe }}
</head> {# #}
<body class="rustdoc {{+page.css_class}}"> {# #}
<a class="skip-main-content" href="#main-content">Skip to main content</a> {# #}
<!--[if lte IE 11]> {# #}
<div class="warning"> {# #}
This old browser is unsupported and will most likely display funky things. {# #}
Expand Down Expand Up @@ -109,7 +110,7 @@ <h2>Files</h2> {# #}
<div class="sidebar-resizer" title="Drag to resize sidebar"></div> {# #}
<main>
{% if page.css_class != "src" %}<div class="width-limiter">{% endif %}
<section id="main-content" class="content">{{ content|safe }}</section>
<section id="main-content" class="content" tabindex="-1">{{ content|safe }}</section>
{% if page.css_class != "src" %}</div>{% endif %}
</main>
{{ layout.external_html.after_content|safe }}
Expand Down
19 changes: 19 additions & 0 deletions tests/rustdoc-gui/skip-navigation.goml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,19 @@
// This test ensures that the "Skip to main content" link works correctly
// for keyboard navigation (WCAG 2.4.1 compliance).
go-to: "file://" + |DOC_PATH| + "/test_docs/index.html"

// The skip link should be hidden initially (positioned off-screen above viewport)
store-position: (".skip-main-content", {"y": y_before})
store-size: (".skip-main-content", {"height": height_before})
assert: |y_before| + |height_before| < 0

// The skip link should be the first focusable element when pressing Tab
press-key: "Tab"
wait-for: ".skip-main-content:focus"

// When focused, the link should be visible (top: 0px)
assert-css: (".skip-main-content:focus", {"top": "0px"})

// Pressing Enter on the skip link should move focus to main content
press-key: "Enter"
wait-for: "#main-content:focus"
Loading