-
Notifications
You must be signed in to change notification settings - Fork 317
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
Fix landmarks #1454
Fix landmarks #1454
Changes from 6 commits
eeb9191
3c1fc72
2405b5d
bf611d0
4760d6e
1e461b7
e6b5bd3
d1b4622
346cb87
6fc4807
b13a1b6
a5f1f8e
87db857
52b968d
bd26466
dfa1a26
3bb86f2
fc12dbc
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,5 +1,6 @@ | ||
<nav class="sidebar-indices-items"> | ||
<p class="sidebar-indices-items__title" role="heading" aria-level="1">{{ _("Indices") }}</p> | ||
{#- TODO use unique html id generator since components can be included in multiple places -#} | ||
<nav class="sidebar-indices-items" aria-labelledby="pst-indices-navigation-heading"> | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. The TODO comments are because of #1425 |
||
<p id="pst-indices-navigation-heading" class="sidebar-indices-items__title" role="heading" aria-level="1">{{ _("Indices") }}</p> | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. We may have too many navigation landmarks in the theme. Online guides say to use landmarks sparingly. But I decided to punt on that question for now and just try to improve the existing landmarks and only remove landmarks when they were actually bugs (nav inside nav, two mains, etc.) |
||
<ul class="indices-link"> | ||
{%- for rellink in rellinks %} | ||
{%- if rellink[0] == 'genindex' %} | ||
|
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,9 +1,12 @@ | ||
{% set page_toc = generate_toc_html() %} | ||
{%- if page_toc | length >= 1 %} | ||
<div class="page-toc tocsection onthispage"> | ||
{#- TODO use unique html id generator since components can be included in multiple places #} | ||
<div | ||
id="pst-page-navigation-heading" | ||
class="page-toc tocsection onthispage"> | ||
<i class="fa-solid fa-list"></i> {{ _("On this page") }} | ||
</div> | ||
<nav class="bd-toc-nav page-toc"> | ||
<nav class="bd-toc-nav page-toc" aria-labelledby="pst-page-navigation-heading"> | ||
{{ page_toc }} | ||
</nav> | ||
{%- endif %} |
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,5 +1,6 @@ | ||
{#- TODO use unique html id generator since components can be included in multiple places -#} | ||
<nav class="bd-docs-nav bd-links" | ||
aria-label="{{ _('Section Navigation') }}"> | ||
<p class="bd-links__title" role="heading" aria-level="1">{{ _("Section Navigation") }}</p> | ||
aria-labelledby="pst-section-navigation-heading"> | ||
<p id="pst-section-navigation-heading" class="bd-links__title" role="heading" aria-level="1">{{ _("In this section") }}</p> | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. I needed to change the label on the nav because it was noisy, causing screen readers to say "Section Navigation navigation." I also thought that "Section Navigation" as a label/header was a bit ambiguous. Section of what? section of the site? section of the page? My first instinct was to change the heading to "Pages," which means it would be announced by screen readers as "Pages navigation." But then I noticed that the navigation for sections of the page was called "On this page," so I thought maybe it makes sense to call this nav group "In this section," leading to the screen reader announcements "On this page navigation" and "In this section navigation," respectively. Taken all together, this means that with this PR the PST site has the following navigation landmarks:
What do folks think? Should it perhaps be "Pages in this section navigation?" There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. just a note that changing translated strings (strings inside "section" here means "section of the site", refers to the top-level menu item (user guide is a section, contributor guide is another section, etc). So I think your choice of "in this section" makes sense here. There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Indeed. I'm already regretting my decision. It's complicating my PR 😭 |
||
<div class="bd-toc-item navbar-nav">{{ sidebar_nav_html }}</div> | ||
</nav> |
Original file line number | Diff line number | Diff line change |
---|---|---|
|
@@ -81,14 +81,18 @@ | |
<div class="search-button__overlay"></div> | ||
<div class="search-button__search-container">{% include "../components/search-field.html" %}</div> | ||
</div> | ||
|
||
<header> | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. This also had to do with All page content should be contained by landmarks. Note that this PR does not fix all instances of this error everywhere in the theme. (For example, the Read The Docs switcher violates this rule.) |
||
{%- if theme_announcement -%} | ||
{% include "sections/announcement.html" %} | ||
{%- endif %} | ||
{% block docs_navbar %} | ||
<nav class="bd-header navbar navbar-expand-lg bd-navbar"> | ||
<div class="bd-header navbar navbar-expand-lg bd-navbar"> | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. The This outer nav contains the logo, the version switcher, the list of header links, the search bar, the theme switcher, and the icon links to Twitter, GitHub, PyPI and PyData. The inner nav contains the list of header links, so I think it better matches the nav element semantics. Furthermore, on mobile this outer nav changes so that it only shows the left hamburger (site and section navigation), the logo, the search, and the right hamburger (page navigation). Whereas the inner nav (based on the Jinja navbar-nav.html component), contains the same content on desktop and mobile. On mobile, the semantics become very clear. On mobile the sidebar contains two navigation sections: one for the site, one for the section of the site that you're in: So I think the inner nav should keep the nav semantics, whereas the nav semantics here on this line should be removed. There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. As an aside, there's something that feels not quite right to me about putting external links under a heading that says "Site Navigation" but maybe that's an issue for another day. There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
yes let's punt on that. Users like to do it (have external links in the main topbar nav) and would be mad if we removed the ability to do that. There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Right. But maybe the heading should be "Main Navigation" or something like that instead of "Site Navigation"? Or maybe we get rid of the visible heading altogether and set aria-label="Main" on the nav tag. There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. I'm OK with "Main navigation" instead of "Site navigation" There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. After thinking about this some more, may I make an argument to simply remove the heading?
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. can you open a new issue to discuss further the idea of removing the "Site navigation" title? There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. #1588 :) |
||
{%- include "sections/header.html" %} | ||
</nav> | ||
</div> | ||
{% endblock docs_navbar %} | ||
</header> | ||
|
||
<div class="bd-container"> | ||
<div class="bd-container__inner bd-page-width"> | ||
{# Primary sidebar #} | ||
|
@@ -107,7 +111,7 @@ | |
{% block docs_body %} | ||
{# This is empty and only shows up if text has been highlighted by the URL #} | ||
{% include "components/searchbox.html" %} | ||
<article class="bd-article" role="main"> | ||
<article class="bd-article"> | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Duplicate main landmark (there should only be one on the page). If you look just a few lines above, you'll find a I think this was an oversight of #1019. |
||
{% block body %}{% endblock %} | ||
</article> | ||
{% endblock docs_body %} | ||
|
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.
All page content should be contained by landmarks
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.
One other thing to think about. We currently make this version warning very visually prominent. If we are making it this prominent for sighted users, should we also make it prominent for blind users by wrapping it in its own landmark, possibly with the
<aside>
tag?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.
yes
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.
Done! 😊
Note: don't worry about the black outline around the version warning banner in the above screen shot; it's added by VoiceOver.