From 809fed4308b1e2a9bbbd8623a7ecf9ea6dd6116c Mon Sep 17 00:00:00 2001
From: Rohan Kumar <seirdy@seirdy.one>
Date: Thu, 19 May 2022 13:21:10 -0700
Subject: [PATCH] Accessible in-page heading anchors!

Bit the bullet and decided to make anchors that look great to
terminal/textual browsers, ARIA + screen reader combos, and a regular
browser.
---
 assets/css/dark.css                          | 11 ++++--
 assets/css/main.css                          | 17 +++++++--
 layouts/_default/_markup/render-heading.html | 38 ++++++--------------
 3 files changed, 32 insertions(+), 34 deletions(-)

diff --git a/assets/css/dark.css b/assets/css/dark.css
index 52be18f..f90cebd 100644
--- a/assets/css/dark.css
+++ b/assets/css/dark.css
@@ -16,7 +16,7 @@
 
 	/* Small text needs higher contrast */
 	sup {
-		background-color: #0b0b0b;
+		background-color: #000;
 	}
 
 	/* Only color <a> if it's a link; if href is empty, let it be. */
@@ -24,12 +24,17 @@
 		color: #f1e7b2;
 	}
 
+	a:active {
+		color: #b93;
+	}
+
 	a:visited {
 		color: #fdf;
 	}
 
-	a:active {
-		color: #b93;
+	/* Small text needs higher contrast */
+	sup a:visited {
+		color: #ffe3ff;
 	}
 
 	/* stylelint-disable -- hasn't heard of "prefers-contrast" yet */
diff --git a/assets/css/main.css b/assets/css/main.css
index 52731e3..a879ac3 100644
--- a/assets/css/main.css
+++ b/assets/css/main.css
@@ -77,11 +77,16 @@ html {
 
 	/* Compensate for misalignment and wasted space caused by padding
 	 * and margin adjustments in nav children made to meet SC 2.5.5 */
+	header > nav,
+	footer > nav,
+	h2 + a {
+		margin-left: -.25em;
+	}
 	header > nav {
-		margin: 0 0 -.75em -.25em;
+		margin-bottom: -.75em;
 	}
 	footer > nav {
-		margin: -.75em 0 0 -.25em;
+		margin-top: -.75em;
 	}
 
 	summary {
@@ -107,8 +112,14 @@ html {
 		padding: 1em 0;
 	}
 
-	/* SC 2.5.5, Google a11y: Increase tap target size a bit */
+	/* SC 2.5.5, Google a11y: Increase tap target size a bit
+	 * - Summary is a tappable button
+	 * - standalone links in lists are usually parts of collections of
+	 *   links that should be easy to fat-finger
+	 * - links that directly follow h2 without being contained in a
+	 *   paragraph are section permalinks. */
 	summary,
+	h2 + a,
 	li > a {
 		padding: .875em .25em;
 	}
diff --git a/layouts/_default/_markup/render-heading.html b/layouts/_default/_markup/render-heading.html
index e57b7ea..8919bb9 100644
--- a/layouts/_default/_markup/render-heading.html
+++ b/layouts/_default/_markup/render-heading.html
@@ -1,29 +1,11 @@
-<!--
-	For now, make the anchor link invisible to screen readers.
-		1. The anchor would need an accessible name, but aria-labels don't
-		   translate well with machine translation. It would need to be
-			 labelledby another element hidden by CSS, which would crowd the
-			 page for non-CSS users.
-		2. Screen reader users don't depend on visually identifying heading
-		   levels and can easily jump between headings without scrolling to
-			 the table of contents, so these anchor links are slightly less
-			 useful to them.
-		3. These links don't expose new functionality, since users could
-		   already copy heading anchor links in the TOC. This just makes some
-			 existing functionality slightly more easily. So it's less of a big
-			 deal
-		4. This reliably hides them from certain reading-mode implementations
-		   (e.g. Readability)
-	Yeah I know, the situation isn't optimal.
--->{{- with . -}}
-<h{{ .Level }} id="{{ .Anchor | safeURL }}">{{ .Text | safeHTML -}}
-{{- if and (gt .Level 1) (eq .Page.Section "posts") -}}
-	<span aria-hidden="true"> <!--Wrap in a span so the whitespace before the link is also hidden-->
-		<a href="#{{ .Anchor | safeURL }}" tabindex="-1">
-			{{- $octothorpes := sub .Level 1 -}}
-			{{- range $i, $sequence := (seq $octothorpes) -}}
-			{{- print `#` -}}
-			{{- end -}}
-		</a></span>
+{{- if and (eq .Level 2) (eq .Page.Section "posts") }}
+<h{{ .Level }} id="{{ .Anchor | safeURL }}-hd">{{ .Text | safeHTML -}}</h{{ .Level }}>
+<a
+	id="{{ .Anchor | safeURL }}" href="#{{ .Anchor | safeURL }}"
+	aria-labelledby="{{ .Anchor | safeURL }}-prefix {{ .Anchor | safeURL }}-hd">
+	<span id="{{ .Anchor | safeURL }}-prefix">Permalink to section</span>
+</a>
+{{- else }}
+{{- with . -}}
+<h{{ .Level }} id="{{ .Anchor | safeURL }}">{{ .Text | safeHTML -}}</h{{ .Level }}>{{ end -}}
 {{- end }}
-</h{{ .Level }}>{{ end }}