[accessibility] Document order

banaanihillo commented

2024-01-13 10:49:48 +01:00

Contributor

All pages under https://docs.codeberg.org/ have a document order (natural tab index) that makes it difficult to navigate with a keyboard.

Currently, to navigate onto the main section of a document page, the user has to:

Tab over the modal that is not visible
Tab over all the navigation links, whether or not the navigation bar itself is visible (on larger screens) or not (on narrow screens and/or with considerable zoom)

Ideally, the initial keyboard focus should be on the "main" section of the page, which is currently a div.content-wrapper (side note, it should probably be a <main> element instead) - where the main heading and the text itself start.
If that is difficult to implement for now, a "skip navigation" link as the first element of the page would probably suffice.

I am not familiar with eleventy nor the .njk file(s), but I'd be glad to help if I can.

All pages under https://docs.codeberg.org/ have a document order (natural tab index) that makes it difficult to navigate with a keyboard. Currently, to navigate onto the main section of a document page, the user has to: 1. Tab over the modal that is not visible 2. Tab over all the navigation links, whether or not the navigation bar itself is visible (on larger screens) or not (on narrow screens and/or with considerable zoom) Ideally, the initial keyboard focus should be on the "main" section of the page, which is currently a `div.content-wrapper` (side note, it should probably be a `<main>` element instead) - where the main heading and the text itself start. If that is difficult to implement for now, a "skip navigation" link as the first element of the page would probably suffice. I am not familiar with eleventy nor the `.njk` file(s), but I'd be glad to help if I can.

👍 1

fnetX commented

2024-03-09 23:53:25 +01:00

Owner

@banaanihillo thank you for the hint. It would be great if you could take a look at this. If you follow the setup instructions and get a successful local build, you can probably modify this file https://codeberg.org/Codeberg/Documentation/src/branch/main/content/_includes/default_layout.njk and it should apply the structure locally. As far as I can see, you don't have to care about any other files, but you can do modifications directly in the site.

Alternatively, you could save the page as a static local file and do the modifications in the resulting HTML dom, then send us the difference. I am sure someone can apply this back to the template.

Let us know if we can be of any assistance.

@banaanihillo thank you for the hint. It would be great if you could take a look at this. If you follow the setup instructions and get a successful local build, you can probably modify this file https://codeberg.org/Codeberg/Documentation/src/branch/main/content/_includes/default_layout.njk and it should apply the structure locally. As far as I can see, you don't have to care about any other files, but you can do modifications directly in the site. Alternatively, you could save the page as a static local file and do the modifications in the resulting HTML dom, then send us the difference. I am sure someone can apply this back to the template. Let us know if we can be of any assistance.

banaanihillo commented

2024-03-10 12:28:59 +01:00

Author

Contributor

Thanks for the instructions! I took a closer look at the default layout and played around with a couple different approaches, and I think the most simple one for now would be:

Add a <a href="#main-content">Skip to main content</a> link onto the top navigation (crude example shown in the screenshot), and add said id="main-content" attribute onto the "main content" container
Move the {% include 'license.njk' %} line further down the document order, since the hidden modal has a side effect of conflicting with the top navigation bar and the sidebar navigation

I noticed the two existing links within the top navigation bar (View History and View Source) have a more intricate design to them, so I did not quite create a pull request yet until I have a chance to figure out how they work.
Side note one: I tried to add a screenshot of the crude design but I was unable to do so with the default editor, so I tried the other editor using the button with the two arrows, but now I am stuck with that editor with which I can not even access the toolbar.
Side note two: I disabled GNU LibreJS to try to add that screenshot, but had to re-enable it to even write this comment since the other editor has an elaborate focus trap with no escape hatch (had to use F6 on a Gecko-like browser to escape). I think I'm in the wrong repository to discuss that issue further, but just wanted to give a heads-up.

Here's a git diff of the above:

diff --git a/content/_includes/default_layout.njk b/content/_includes/default_layout.njk
index 419cc5c..42dc463 100644
--- a/content/_includes/default_layout.njk
+++ b/content/_includes/default_layout.njk
@@ -64,7 +64,6 @@
     </head>
 
     <body data-set-preferred-mode-onload="true">
-        {% include 'license.njk' %}
         <div class="page-wrapper with-sidebar with-navbar with-transitions" data-sidebar-type="overlayed-sm-and-down">
             <div class="sidebar-overlay" onclick="halfmoon.toggleSidebar()"></div>
             <nav class="navbar">
@@ -80,6 +79,7 @@
                 </a>
                 <!-- Navbar nav -->
                 <ul class="navbar-nav ml-auto d-none d-md-flex">
+                    <a href="#main-content">Skip to main content</a>
                     <li class="nav-item">
                         <a href="{{ urls.commitHistoryMaster }}/{{ page.inputPath }}" class="nav-link" target="_blank" rel="noreferrer">
                             {% fas_icon "history" %} &nbsp; View History
@@ -153,7 +153,7 @@
                 </div>
             </div>
 
-            <div class="content-wrapper">
+            <div class="content-wrapper" id="main-content">
                 <div class="container-fluid">
                     <div class="row">
                         <div class="content col-xl-8" data-pagefind-body>
@@ -178,5 +178,6 @@
                 </div>
             </div>
         </div>
+        {% include 'license.njk' %}
     </body>
 </html>

Thanks for the instructions! I took a closer look at the default layout and played around with a couple different approaches, and I think the most simple one for now would be: 1. Add a `<a href="#main-content">Skip to main content</a>` link onto the top navigation (crude example shown in the screenshot), and add said ` id="main-content"` attribute onto the "main content" container 2. Move the `{% include 'license.njk' %}` line further down the document order, since the hidden modal has a side effect of conflicting with the top navigation bar and the sidebar navigation I noticed the two existing links within the top navigation bar (View History and View Source) have a more intricate design to them, so I did not quite create a pull request yet until I have a chance to figure out how they work. Side note one: I tried to add a screenshot of the crude design but I was unable to do so with the default editor, so I tried the other editor using the button with the two arrows, but now I am stuck with that editor with which I can not even access the toolbar. Side note two: I disabled GNU LibreJS to try to add that screenshot, but had to re-enable it to even write this comment since the other editor has an elaborate focus trap with no escape hatch (had to use F6 on a Gecko-like browser to escape). I think I'm in the wrong repository to discuss that issue further, but just wanted to give a heads-up. Here's a `git diff` of the above: ``` diff --git a/content/_includes/default_layout.njk b/content/_includes/default_layout.njk index 419cc5c..42dc463 100644 --- a/content/_includes/default_layout.njk +++ b/content/_includes/default_layout.njk @@ -64,7 +64,6 @@ </head> <body data-set-preferred-mode-onload="true"> - {% include 'license.njk' %} <div class="page-wrapper with-sidebar with-navbar with-transitions" data-sidebar-type="overlayed-sm-and-down"> <div class="sidebar-overlay" onclick="halfmoon.toggleSidebar()"></div> <nav class="navbar"> @@ -80,6 +79,7 @@ </a>  <ul class="navbar-nav ml-auto d-none d-md-flex"> + <a href="#main-content">Skip to main content</a> <li class="nav-item"> <a href="{{ urls.commitHistoryMaster }}/{{ page.inputPath }}" class="nav-link" target="_blank" rel="noreferrer"> {% fas_icon "history" %}   View History @@ -153,7 +153,7 @@ </div> </div> - <div class="content-wrapper"> + <div class="content-wrapper" id="main-content"> <div class="container-fluid"> <div class="row"> <div class="content col-xl-8" data-pagefind-body> @@ -178,5 +178,6 @@ </div> </div> </div> + {% include 'license.njk' %} </body> </html> ```

banaanihillo commented

2024-03-10 13:08:51 +01:00

Author

Contributor

Right, figured out where to change back to the default editor. Had to remove the local storage item with browser developer tools since I could not find that setting within my account preferences or such.
Crude design screenshot uploaded onto another issue since I could not find how to add it here.

Just as I was about to add this comment, I noticed where to upload files. So here's another screenshot of the crude design.

Right, figured out where to change back to the default editor. Had to remove the local storage item with browser developer tools since I could not find that setting within my account preferences or such. [Crude design screenshot](https://codeberg.org/attachments/b53c270c-1764-4d9e-9cb4-a63e681f9110) uploaded onto another issue since I could not find how to add it here. Just as I was about to add this comment, I noticed where to upload files. So here's another screenshot of the crude design.

Screenshot from 2024-03-10 13-10-18.png

243 KiB

❤️ 1

banaanihillo commented

2024-03-17 11:07:04 +01:00

Author

Contributor

Some miscellaneous notes about this issue and a couple related things:

The navigation sidebar is always open by default. We could perhaps add a local storage item or cookie with which to persist its open/closed state between page loads.
Upon toggling the sidebar from closed to open, the user would expect the navigation links to be next in the document order. Currently, the View History and View Source links come next, and then the navigation links.
Toggling the sidebar from open to closed should allow the user to skip over the navigation links within the sidebar. Currently, the links remain tabbable while the sidebar itself is hidden.
The top navigation bar and the main content are two distinct elements, so the user can not scroll the page up and down while on the navigation bar element (which is also the element in focus on page load)

I'll take a closer look at note 4 since that would mostly solve the issue I was thinking of when creating this ticket.
I am unsure about note 3 since I have no practical experience of screen readers, so I'd rather not dive right into it before hearing some more opinions on how it should be implemented instead.

Some miscellaneous notes about this issue and a couple related things: 1) The navigation sidebar is always open by default. We could perhaps add a local storage item or cookie with which to persist its open/closed state between page loads. 2) Upon toggling the sidebar from _closed_ to _open_, the user would expect the navigation links to be next in the document order. Currently, the _View History_ and _View Source_ links come next, and then the navigation links. 3) Toggling the sidebar from _open_ to _closed_ should allow the user to skip over the navigation links within the sidebar. Currently, the links remain [tabbable](https://en.wiktionary.org/wiki/tabbable) while the sidebar itself is hidden. 4) The top navigation bar and the main content are two distinct elements, so the user can not scroll the page up and down while on the navigation bar element (which is also the element in focus on page load) I'll take a closer look at note 4 since that would mostly solve the issue I was thinking of when creating this ticket. I am unsure about note 3 since I have no practical experience of screen readers, so I'd rather not dive right into it before hearing some more opinions on how it should be implemented instead.

banaanihillo referenced this issue

2024-06-23 17:27:49 +02:00

Arrow keys don't work by default #441

Rows
Columns

[accessibility] Document order #385