From 4fd6cfe668e8aaf3f92817379fc8e123a6caf24f Mon Sep 17 00:00:00 2001
From: Caleb Jasik <calebjasik@jasik.xyz>
Date: Thu, 22 Jul 2021 19:12:37 -0500
Subject: [PATCH] =?UTF-8?q?=F0=9F=93=98=20DOC:=20improve=20a11y=20(#806)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* Add `tabindex="0"` to `<pre>` so that they are navigable by keyboard users if they overflow.

* Landmark elements should have unique names https://dequeuniversity.com/rules/axe/4.3/landmark-unique

* Page must have one main landmark https://dequeuniversity.com/rules/axe/4.3/landmark-one-main

- Main landmark must not be contained by another landmark https://dequeuniversity.com/rules/axe/4.3/landmark-main-is-top-level

* Heading level cannot increase by more than one

* Ensure that links with the same accessible name serve a similar purpose

https://dequeuniversity.com/rules/axe/4.3/identical-links-same-purpose

* Just update the accessible name and require context for the visible link name

* Fix CSS from the removal of the second <main>

* Revert heading level change
---
 docs/public/index.css                         | 14 +++++++-------
 docs/public/make-scrollable-code-focusable.js |  3 +++
 docs/src/components/DocSidebar.tsx            |  2 +-
 docs/src/components/SiteSidebar.astro         |  2 +-
 docs/src/layouts/Main.astro                   | 19 ++++++++++---------
 docs/src/pages/core-concepts/astro-pages.md   |  2 +-
 docs/src/pages/guides/data-fetching.md        |  4 ++--
 docs/src/pages/guides/styling.md              |  4 ++--
 .../src/pages/reference/renderer-reference.md |  2 --
 9 files changed, 27 insertions(+), 25 deletions(-)
 create mode 100644 docs/public/make-scrollable-code-focusable.js

diff --git a/docs/public/index.css b/docs/public/index.css
index e60e0bec4..f33c7c2eb 100644
--- a/docs/public/index.css
+++ b/docs/public/index.css
@@ -35,11 +35,11 @@ nav ul {
   padding: 0;
 }
 
-.content main > * + * {
+.content > section > * + * {
   margin-top: 1rem;
 }
 
-.content main > :first-child {
+.content > section > :first-child {
   margin-top: 0;
 }
 
@@ -110,24 +110,24 @@ a {
   gap: 0.5rem;
 }
 
-article main :is(ul, ol) > * + * {
+article > section :is(ul, ol) > * + * {
   margin-top: 0.75rem;
 }
 
-article main li > :is(p, pre, blockquote):not(:first-child) {
+article > section li > :is(p, pre, blockquote):not(:first-child) {
   margin-top: 1rem;
 }
 
-article main :is(ul, ol) {
+article > section :is(ul, ol) {
   padding-left: 1em;
 }
 
-article main ::marker {
+article > section ::marker {
   font-weight: bold;
   color: var(--theme-text-light);
 }
 
-article main iframe {
+article > section iframe {
   width: 100%;
   height: auto;
   aspect-ratio: 16 / 9;
diff --git a/docs/public/make-scrollable-code-focusable.js b/docs/public/make-scrollable-code-focusable.js
new file mode 100644
index 000000000..6fbf1eebe
--- /dev/null
+++ b/docs/public/make-scrollable-code-focusable.js
@@ -0,0 +1,3 @@
+Array.from(document.getElementsByTagName("pre")).forEach((element) => {
+  element.setAttribute("tabindex", "0");
+});
diff --git a/docs/src/components/DocSidebar.tsx b/docs/src/components/DocSidebar.tsx
index 6aacb3860..92f34ff61 100644
--- a/docs/src/components/DocSidebar.tsx
+++ b/docs/src/components/DocSidebar.tsx
@@ -28,7 +28,7 @@ const DocSidebar: FunctionalComponent<{ headers: any[]; editHref: string }> = ({
   }, []);
 
   return (
-    <nav class="sidebar-nav">
+    <nav class="sidebar-nav" aria-labelledby="sidebar-content">
       <div class="sidebar-nav-inner">
         <h2 class="heading">On this page</h2>
         <ul>
diff --git a/docs/src/components/SiteSidebar.astro b/docs/src/components/SiteSidebar.astro
index 05779e882..6503c0414 100644
--- a/docs/src/components/SiteSidebar.astro
+++ b/docs/src/components/SiteSidebar.astro
@@ -3,7 +3,7 @@ import { sidebar } from '../config.ts';
 const {currentPage} = Astro.props;
 ---
 
-<nav>
+<nav aria-labelledby="sidebar-site">
   <ul class="nav-groups">  
     {sidebar.map(category => (
       <li>
diff --git a/docs/src/layouts/Main.astro b/docs/src/layouts/Main.astro
index ad2dc34f1..90b19dfcf 100644
--- a/docs/src/layouts/Main.astro
+++ b/docs/src/layouts/Main.astro
@@ -132,7 +132,7 @@ if (currentPage) {
         height: 100%;
       }
 
-      .layout.centered #article main {
+      .layout.centered #article > article > section {
         display: flex;
         flex-direction: column;
         margin: auto;
@@ -143,11 +143,11 @@ if (currentPage) {
         text-align: center;
       }
 
-      .layout.centered #article main :global(> *) {
+      .layout.centered #article > article > section :global(> *) {
         margin: 0;
       }
 
-      .layout.centered #article main h1 {
+      .layout.centered #article > article > section h1 {
         font-size: 5rem;
       }
 
@@ -160,7 +160,7 @@ if (currentPage) {
         flex-direction: column;
       }
 
-      .content > main {
+      .content > section {
         margin-bottom: 4rem;
       }
 
@@ -256,7 +256,7 @@ if (currentPage) {
 
   <body>
     <header>
-      <nav class="nav-wrapper">
+      <nav class="nav-wrapper" title="Top Navigation">
         <div class="menu-toggle">
             <MenuToggle client:idle/>
         </div>
@@ -291,24 +291,25 @@ if (currentPage) {
     </header>
 
     <main class={centered ? "layout centered" : "layout"}>
-      <aside class="sidebar" id="sidebar-site">
+      <aside class="sidebar" id="sidebar-site" title="Documentation Sections">
         <SiteSidebar currentPage={currentPage?.slice(1) ?? ''} />
       </aside>
       <div id="article">
         <article class="content">
-          <main>
+          <section>
             <h1 class="content-title" id="overview">{content?.title}</h1>
             <slot />
-          </main>
+          </section>
           {currentPage && <ArticleFooter path={currentFile} />}
         </article>
       </div>
-      <aside class="sidebar" id="sidebar-content">
+      <aside class="sidebar" id="sidebar-content" title="Table of Contents">
         {currentPage && <DocSidebar client:idle headers={headers} editHref={githubEditUrl} />}
       </aside>
     </main>
 
     <script type="module" src="/nav.js" />
+    <script type="module" src="/make-scrollable-code-focusable.js" />
 
     <!-- Global site tag (gtag.js) - Google Analytics -->
     <script async src="https://www.googletagmanager.com/gtag/js?id=G-TEL60V1WM9"></script>
diff --git a/docs/src/pages/core-concepts/astro-pages.md b/docs/src/pages/core-concepts/astro-pages.md
index 0aedca4bf..87157c5b1 100644
--- a/docs/src/pages/core-concepts/astro-pages.md
+++ b/docs/src/pages/core-concepts/astro-pages.md
@@ -23,7 +23,7 @@ src/pages/posts/1.md        -> mysite.com/posts/1
 
 ## Page Templating
 
-All Astro components are responsible for returning HTML. Astro Pages return HTML as well, but have the unique responsibility of returning a full `<html>...</html>` page response, including `<head>` ([MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/head)) and `<body>` ([MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/body)).
+All Astro components are responsible for returning HTML. Astro Pages return HTML as well, but have the unique responsibility of returning a full `<html>...</html>` page response, including `<head>` ([MDN<span class="sr-only">- head</span>](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/head)) and `<body>` ([MDN<span class="sr-only">- body</span>](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/body)).
 
 `<!doctype html>` is optional, and will be added automatically.
 
diff --git a/docs/src/pages/guides/data-fetching.md b/docs/src/pages/guides/data-fetching.md
index 7b28bedb4..c3e033405 100644
--- a/docs/src/pages/guides/data-fetching.md
+++ b/docs/src/pages/guides/data-fetching.md
@@ -7,7 +7,7 @@ Astro components and pages can fetch remote data to help generate your pages. As
 
 ## `fetch()`
 
-Astro pages have access to the global `fetch()` function in their setup script. `fetch()` is a native JavaScript API ([MDN](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API/Using_Fetch)) that lets you make HTTP requests for things like APIs and resources.
+Astro pages have access to the global `fetch()` function in their setup script. `fetch()` is a native JavaScript API ([MDN<span class="sr-only">- fetch</span>](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API/Using_Fetch)) that lets you make HTTP requests for things like APIs and resources.
 
 Even though Astro component scripts run inside of Node.js (and not in the browser) Astro provides this native API so that you can fetch data at page build time.
 
@@ -25,7 +25,7 @@ console.log(data);
 
 ## Top-level await
 
-`await` is another native JavaScript feature that lets you await the response of some asynchronous promise ([MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/await)). Astro supports `await` in the top-level of your component script.
+`await` is another native JavaScript feature that lets you await the response of some asynchronous promise ([MDN<span class="sr-only">- await</span>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/await)). Astro supports `await` in the top-level of your component script.
 
 **Important:** These are not yet available inside of non-page Astro components. Instead, do all of your data loading inside of your pages, and then pass them to your components as props.
 
diff --git a/docs/src/pages/guides/styling.md b/docs/src/pages/guides/styling.md
index 1c8bb0dfb..d6a3691a2 100644
--- a/docs/src/pages/guides/styling.md
+++ b/docs/src/pages/guides/styling.md
@@ -70,8 +70,8 @@ import Styles from './styles.module.css'; // Use CSS Modules (must end in `.modu
 
 Vue in Astro supports the same methods as `vue-loader` does:
 
-- [Scoped CSS][vue-scoped]
-- [CSS Modules][vue-css-modules]
+- [vue-loader - Scoped CSS][vue-scoped]
+- [vue-loader - CSS Modules][vue-css-modules]
 
 ### 📕 Svelte
 
diff --git a/docs/src/pages/reference/renderer-reference.md b/docs/src/pages/reference/renderer-reference.md
index 1a56e7639..1433b7814 100644
--- a/docs/src/pages/reference/renderer-reference.md
+++ b/docs/src/pages/reference/renderer-reference.md
@@ -110,8 +110,6 @@ export interface JSXTransformOptions {
 }
 ```
 
-####
-
 ### Server Entrypoint (`server.js`)
 
 The server entrypoint of a renderer is responsible for checking if a component should use this renderer, and if so, how that component should be rendered to a string of static HTML.