Improve accessibility of the docs (#9338)

Merge pull request 9338

docs/_includes/anchor_links.html

@@ -1,33 +1,33 @@
 <script>
-  var anchorForId = function (id) {
-    var anchor = document.createElement("a");
-    anchor.className = "header-link";
-    anchor.href      = "#" + id;
-    anchor.innerHTML = "<span class=\"sr-only\">Permalink</span><i class=\"fa fa-link\"></i>";
-    anchor.title = "Permalink";
-    return anchor;
-  };
+/* Creates an anchor element with the given ID and link for the permalink*/
+const anchorForId = (id) => {
+  const anchor = document.createElement("a");
+  anchor.className = "header-link";
+  anchor.href = `#${id}`;
+  anchor.innerHTML = `<span class="sr-only">Permalink</span><i class="fa fa-link" aria-hidden="true"></i>`;
+  anchor.title = "Permalink";
+  return anchor;
+};
 
-  var linkifyAnchors = function (level, containingElement) {
-    var headers = containingElement.getElementsByTagName("h" + level);
-    for (var h = 0; h < headers.length; h++) {
-      var header = headers[h];
-
-      if (typeof header.id !== "undefined" && header.id !== "") {
-        header.appendChild(anchorForId(header.id));
-      }
+/* Finds all headers of the specified level within the given element, and adds a permalink to each header*/
+const linkifyAnchors = (level, containingElement) => {
+  const headers = Array.from(containingElement.getElementsByTagName(`h${level}`));
+  headers.forEach((header) => {
+    if (header.id) {
+      header.appendChild(anchorForId(header.id));
     }
-  };
+  });
+};
 
-  document.onreadystatechange = function () {
-    if (this.readyState === "complete") {
-      var contentBlock = document.getElementsByClassName("docs")[0] || document.getElementsByClassName("news")[0];
-      if (!contentBlock) {
-        return;
-      }
-      for (var level = 1; level <= 6; level++) {
-        linkifyAnchors(level, contentBlock);
-      }
+/* Executes the function when the document is ready */
+document.onreadystatechange = () => {
+  if (document.readyState === "complete") {
+    const contentBlock = document.getElementsByClassName("docs")[0]
+      ?? document.getElementsByClassName("news")[0];
+    if (!contentBlock) { return; }
+    for (let level = 1; level <= 6; level++) {
+      linkifyAnchors(level, contentBlock);
     }
-  };
+  }
+};
 </script>

docs/_includes/docs_contents.html

@@ -1,14 +1,17 @@
 <div class="unit one-fifth hide-on-mobiles">
   <aside>
-    {% for section in site.data.docs_nav -%}
+    {% for section in site.data.docs_nav %}
       <h4>{{ section.title }}</h4>
       <ul>
-      {%- for item in section.docs -%}
-        {%- assign p = site.docs | where: "url", item.link | first %}
-        <li {%- if page.url == p.url %} class="current" {%- endif -%}><a href="{{ p.url | relative_url }}">
-          {{- p.menu_name | default: p.title -}}
-        </a></li>
-      {%- endfor %}
+        {%- for item in section.docs -%}
+          {%- assign current_page = site.docs | where: "url", item.link | first -%}
+          {%- capture item_html -%}
+            <a href="{{ current_page.url | relative_url }}">
+              {{ current_page.menu_name | default: current_page.title }}
+            </a>
+          {% endcapture %}
+          <li{%- unless current_page.url != page.url -%} class="current"{%- endunless -%}>{{ item_html }}</li>
+        {% endfor %}
       </ul>
     {% endfor -%}
   </aside>

docs/_includes/docs_contents_mobile.html

@@ -1,15 +1,15 @@
 <div class="docs-nav-mobile unit whole show-on-mobiles">
-  <select onchange="if (this.value) window.location.href=this.value">
+  <select id="doc-nav" onchange="navigateToUrl(this)" aria-label="Select a page from the documentation">
     <option value="">Navigate the docs…</option>
-    {% for section in site.data.docs_nav -%}
-    <optgroup label="{{ section.title }}">
-    {%- for item in section.docs -%}
-      {% assign p = site.docs | where: "url", item.link | first %}
-      <option value="{{ p.url | relative_url }}">
-        {{- p.menu_name | default: p.title -}}
-      </option>
-    {%- endfor %}
-    </optgroup>
-    {% endfor -%}
+    {% for section in site.data.docs_nav %}
+      <optgroup label="{{ section.title }}">
+        {%- for item in section.docs -%}
+          {% assign page = site.docs | where: "url", item.link | first %}
+          <option value="{{ page.url | relative_url }}">
+            {{- page.menu_name | default: page.title -}}
+          </option>
+        {%- endfor %}
+      </optgroup>
+    {% endfor %}
   </select>
-</div>
+</div>

docs/_includes/mobile-nav-items.html

@@ -3,12 +3,12 @@
     {% if p.show_on_mobile -%}
     <li
       {%- if p.link == '/' -%}
-        {%- if page.url == '/' %} class="current" {% endif -%}
+        {%- if page.url == '/' %} class="current" aria-current="page" {% endif -%}
       {% else -%}
-        {%- if page.url contains p.link %} class="current" {% endif -%}
+        {%- if page.url contains p.link %} class="current" aria-current="page" {% endif -%}
       {% endif -%}
     ><a href="{{ p.link | relative_url }}">{{ p.title }}</a></li>
     {% endif -%}
   {% endfor -%}
-  <li><a href="{{ site.repository }}">GitHub</a></li>
-</ul>
+  <li><a href="{{ site.repository }}" target="_blank" rel="noopener">GitHub</a></li>
+</ul>

docs/_includes/news_contents_mobile.html

@@ -1,5 +1,5 @@
 <div class="docs-nav-mobile unit whole show-on-mobiles">
-  <select onchange="if (this.value) window.location.href=this.value">
+  <select id="news-nav" onchange="navigateToUrl(this)" aria-label="Select a post from the blog">
     <option value="">Navigate the blog…</option>
     <option value="{{ '/news/' | relative_url }}">Home</option>
     <optgroup label="posts">
@@ -8,4 +8,4 @@
       {% endfor -%}
     </optgroup>
   </select>
-</div>
+</div>

docs/_includes/news_item.html

@@ -1,5 +1,5 @@
-<article>
-  <h2>
+<article itemscope itemtype="http://schema.org/NewsArticle">
+  <h2 itemprop="headline">
     <a href="{{ post.url | relative_url }}">
       {{- post.title -}}
     </a>
@@ -10,16 +10,16 @@ <h2>
     </span>
   </span>
   <div class="post-meta">
-    <span class="post-date">
+    <span class="post-date" itemprop="datePublished" content="{{ post.date | date: "%Y-%m-%d" }}">
       {{- post.date | date_to_string -}}
     </span>
     {% assign author = post.author -%}
-    <a href="https://github.com/{{ author }}" class="post-author">
+    <a class="post-author" itemprop="author" itemscope itemtype="http://schema.org/Person" target="_blank" href="https://github.com/{{ author }}">
       {% avatar user=author size=24 -%}
-      <span class="author-name">{{ author }}</span>
+      <span class="author-name" itemprop="name">{{ author }}</span>
     </a>
   </div>
-  <div class="post-content">
+  <div class="post-content" itemprop="articleBody">
     {{- post.content -}}
   </div>
 </article>

docs/_includes/news_item_archive.html

@@ -1,4 +1,4 @@
-<article>
+<article itemscope itemtype="http://schema.org/Article">
   <div class="cell-left">
     <span class="post-category">
       <span class="label">
@@ -8,18 +8,18 @@
   </div>
   <div class="cell-right">
     <div class="post-meta">
-      <h2 class="post-title">
-        <a href="{{ post.url | relative_url }}">
+      <h2 class="post-title" itemprop="headline">
+        <a href="{{ post.url | relative_url }}" itemprop="url">
           {{- post.title -}}
         </a>
       </h2>
-      <span class="post-date">
+      <span class="post-date" itemprop="datePublished" content="{{ post.date | date: '%Y-%m-%d' }}">
         {{- post.date | date_to_string -}}
       </span>
       {% assign author = post.author -%}
-      <a href="https://github.com/{{ author }}" class="post-author">
+      <a href="https://github.com/{{ author }}" class="post-author" itemprop="author" itemscope itemtype="http://schema.org/Person">
         {% avatar user=author size=24 -%}
-        <span class="author-name">{{ author }}</span>
+        <span class="author-name" itemprop="name">{{ author }}</span>
       </a>
     </div>
   </div>

docs/_includes/search/input.html

@@ -1 +1 @@
-<input type="text" id="docsearch-input" placeholder="Search the docs…">
+<input type="text" id="docsearch-input" placeholder="Search the docs…" aria-label="Search">

docs/_includes/search/script.html

@@ -1,9 +1,9 @@
-<script src="https://cdn.jsdelivr.net/npm/docsearch.js@2/dist/cdn/docsearch.min.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/docsearch.js@2/dist/cdn/docsearch.min.js" defer></script>
 <script> docsearch({
 apiKey: '50fe39c839958dfad797000f33e2ec17',
 indexName: 'jekyllrb',
 inputSelector: '#docsearch-input',
 enhancedSearchInput: true,
-debug: false // Set debug to true if you want to inspect the dropdown
+debug: false
 });
 </script>

docs/_includes/top.html

@@ -1,5 +1,5 @@
-<!DOCTYPE HTML>
-<html lang="en-US">
+<!DOCTYPE html>
+<html lang="en">
 <head>
   <meta charset="UTF-8">
   <meta name="viewport" content="width=device-width,initial-scale=1">

docs/_includes/tutorials_contents_mobile.html

@@ -1,14 +1,14 @@
 <div class="docs-nav-mobile unit whole show-on-mobiles">
-  <select onchange="if (this.value) window.location.href=this.value">
+  <select id="tutorial-nav" onchange="navigateToUrl(this)" aria-label="Select a tutorial">
     <option value="">Navigate the tutorials…</option>
     {% for section in site.data.tutorials -%}
-    <optgroup label="{{ section.title }}">
-      {% for item in section.tutorials -%}
-        {% assign item_url = item | prepend:"/tutorials/" | append:"/" -%}
-        {% assign tutorial = site.tutorials | where: "url", item_url | first -%}
-        <option value="{{ tutorial.url | relative_url }}">{{ tutorial.title }}</option>
-      {% endfor -%}
-    </optgroup>
+      <optgroup label="{{ section.title }}">
+        {% for item in section.tutorials -%}
+          {% assign item_url = item | prepend:"/tutorials/" | append:"/" -%}
+          {% assign tutorial = site.tutorials | where: "url", item_url | first -%}
+          <option value="{{ tutorial.url | relative_url }}">{{ tutorial.title }}</option>
+        {% endfor -%}
+      </optgroup>
     {% endfor -%}
   </select>
-</div>
+</div>

docs/_layouts/default.html

@@ -9,5 +9,16 @@
   {%- include anchor_links.html -%}
   {%- include analytics.html -%}
   {%- include search/script.html -%}
+
+  <script>
+  {%- comment -%}
+  // This function is called when the user selects an option from a <select> element.
+  // If the selected option has a valid URL, it changes the window location to that URL.
+  {%- endcomment %}
+  const navigateToUrl = (select) => {
+    const url = select.value;
+    url && (window.location.href = url);
+  };
+  </script>
 </body>
 </html>

docs/_layouts/news_item.html

@@ -2,8 +2,8 @@
 layout: news
 ---
 
-<article>
-  <h2>
+<article itemscope itemtype="http://schema.org/Article">
+  <h2 itemprop="headline">
     {{ page.title }}
     <a href="{{ page.url | relative_url }}" class="header-link" title="Permalink">
       <span class="sr-only">Permalink</span>
@@ -16,16 +16,16 @@ <h2>
     </span>
   </span>
   <div class="post-meta">
-    <span class="post-date">
+    <span class="post-date" itemprop="datePublished" content="{{ page.date | date: "%Y-%m-%d" }}">
       {{- page.date | date_to_string -}}
     </span>
     {% assign author = page.author -%}
-    <a href="https://github.com/{{ author }}" class="post-author">
+    <a class="post-author" itemprop="author" itemscope itemtype="http://schema.org/Person" target="_blank" href="https://github.com/{{ author }}">
       {% avatar user=author size=24 -%}
-      <span class="author-name">{{ author }}</span>
+      <span class="author-name" itemprop="name">{{ author }}</span>
     </a>
   </div>
-  <div class="post-content">
+  <div class="post-content" itemprop="articleBody">
     {{ content }}
   </div>
 </article>