From 41b66d8ceb030ee7ea2f038bc5710137cbb1426d Mon Sep 17 00:00:00 2001
From: Rohan Kumar <seirdy@seirdy.one>
Date: Sat, 9 Apr 2022 08:51:10 -0700
Subject: [PATCH] Put TOC heading inside the TOC <nav>

Putting the heading in the navigation element makes the structure more
logical and matches the behavior of most other websites.

Move it before the introduction in my web best practices post.
---
 content/posts/website-best-practices.md | 2 +-
 layouts/partials/processed-content.html | 9 ++++++++-
 layouts/shortcodes/toc.html             | 3 +--
 3 files changed, 10 insertions(+), 4 deletions(-)

diff --git a/content/posts/website-best-practices.md b/content/posts/website-best-practices.md
index 1647982..702b527 100644
--- a/content/posts/website-best-practices.md
+++ b/content/posts/website-best-practices.md
@@ -930,7 +930,7 @@ There's an ideal range somewhere between "cramped" and "spaced-apart" content. F
 
 Excessive indentation can [make reading difficult](#indented-elements) for narrow viewports, but preserving some indentation is still useful.
 
-For now, I've decided to keep the indents on list elements (`<ol>`, `<dl>`, `<ul>`) since I often fill them with links (see this article's [table of contents](#toc) for an example). This indentation provides important non-interactive negative space. Readers with hand tremors [depend on this space](https://axesslab.com/hand-tremors/) to scroll without accidentally selecting an interactive element. Readers who double-tap to jump or zoom can't do so if there's no screen region that's "safe to tap".
+For now, I've decided to keep the indents on list elements (`<ol>`, `<dl>`, `<ul>`) since I often fill them with links (see this article's [table of contents](#TableOfContents) for an example). This indentation provides important non-interactive negative space. Readers with hand tremors [depend on this space](https://axesslab.com/hand-tremors/) to scroll without accidentally selecting an interactive element. Readers who double-tap to jump or zoom can't do so if there's no screen region that's "safe to tap".
 
 <figure>
 {{<picture name="touch_targets" alt="Phone screen with three \"touch target\" rectangles on top of each other, separated by blank sections labeled \"space\"">}}
diff --git a/layouts/partials/processed-content.html b/layouts/partials/processed-content.html
index 302efde..9510d09 100644
--- a/layouts/partials/processed-content.html
+++ b/layouts/partials/processed-content.html
@@ -1,18 +1,25 @@
 {{ if .Params.footnote_heading -}}
 
+<!--Add heading to footnotes-->
 {{ $references    := `(<section class="footnotes" role="doc-endnotes">
 <hr>)` -}}
 {{ $heading :=  .Params.footnote_heading -}}
 {{ $referencesWithHeading := printf `<section role="doc-endnotes" aria-labelledby="note-hd">
 <h2 id="note-hd">%s</h2>` ($heading) -}}
 
+<!--Remove deprecated DPUB-ARIA role-->
 {{ $endnote := `(role="doc-endnote")` }}
 {{ $noEndnote := printf "" }}
 
+<!--Add tabindex to all <pre> elements, inc. those that aren't generated by Goldmark-->
 {{ $preWithoutTabIndex := `<pre>` }}
 {{ $preWithTabIndex := `<pre tabindex="0">` }}
 
-{{ .Content | replaceRE $references $referencesWithHeading | replaceRE $endnote $noEndnote | replaceRE $preWithoutTabIndex $preWithTabIndex | safeHTML -}}
+<!--Move the Table of Contents heading *inside* the <nav> element-->
+{{ $tocHeadingOutside := `<h2>Table of Contents</h2><nav id="TableOfContents">` }}
+{{ $tocHeadingInside := `<nav id=TableOfContents><h2>Table of Contents</h2>` }}
+
+{{ .Content | replaceRE $references $referencesWithHeading | replaceRE $endnote $noEndnote | replaceRE $preWithoutTabIndex $preWithTabIndex | replaceRE $tocHeadingOutside $tocHeadingInside | safeHTML -}}
 {{ else -}}
 {{ .Content -}}
 {{ end -}}
diff --git a/layouts/shortcodes/toc.html b/layouts/shortcodes/toc.html
index a42d5ef..c762bbc 100644
--- a/layouts/shortcodes/toc.html
+++ b/layouts/shortcodes/toc.html
@@ -1,6 +1,5 @@
 <aside>
 <section role="doc-toc">
-<h2 id="toc">Table of Contents</h2>
-{{.Page.TableOfContents}}
+<h2>Table of Contents</h2>{{.Page.TableOfContents}}
 </section>
 </aside>