Make article headings linkable (#52) (#69)

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>

Author: psjamesp

themes/powershell-community/layouts/_default/baseof.html

@@ -111,7 +111,8 @@
     {{- $asyncCSS := slice
         "https://cdnjs.cloudflare.com/ajax/libs/prism/1.24.1/themes/prism-tomorrow.min.css"
         "/css/alerts.css"
-        "/css/code-copy.css" -}}
+        "/css/code-copy.css"
+        "/css/heading-anchors.css" -}}
     {{- with .Site.Params.algolia }}{{ $asyncCSS = $asyncCSS | append "https://cdn.jsdelivr.net/npm/@algolia/algoliasearch-netlify-frontend@1/dist/algoliasearchNetlify.css" }}{{ end -}}
     {{ range $asyncCSS }}
     <link rel="stylesheet" href="{{ . }}" media="print" onload="this.media='all'">

themes/powershell-community/layouts/_default/single.html

@@ -207,13 +207,16 @@ <h4 class="text-lg font-semibold text-gray-900 mb-3 line-clamp-2">
         });
     }
 
-    // Smooth scrolling for anchor links within the article
+    // Smooth scrolling for anchor links within the article. Also update the
+    // URL hash so a linked section is shareable/copyable from the address bar.
     document.querySelectorAll('.prose a[href^="#"]').forEach(anchor => {
         anchor.addEventListener('click', function (e) {
-            e.preventDefault();
-            const target = document.querySelector(this.getAttribute('href'));
+            const hash = this.getAttribute('href');
+            const target = document.querySelector(hash);
             if (target) {
+                e.preventDefault();
                 target.scrollIntoView({ behavior: 'smooth', block: 'start' });
+                history.pushState(null, '', hash);
             }
         });
     });

themes/powershell-community/layouts/_markup/render-heading.html

@@ -0,0 +1,14 @@
+{{- /* Heading render hook: makes article headings directly linkable.
+        Renders the heading with its auto-generated id (from .Anchor, i.e.
+        Goldmark's autoHeadingID) plus a hover-revealed anchor link, so any
+        section can be linked to and shared. Because the id still comes from
+        .Anchor, pre-existing `#section` links keep resolving unchanged.
+        The `{.class}` attribute authors add (e.g. .wp-block-heading) is
+        preserved. Styling lives in static/css/heading-anchors.css. */ -}}
+{{- $id := .Anchor -}}
+{{- $class := "ps-heading" -}}
+{{- with .Attributes.class }}{{ $class = printf "%s %s" $class . }}{{ end -}}
+<h{{ .Level }} id="{{ $id }}" class="{{ $class }}">
+  {{- .Text | safeHTML -}}
+  <a class="ps-heading-anchor" href="#{{ $id }}" aria-label="Link to this section" title="Link to this section"><i class="fas fa-link" aria-hidden="true"></i></a>
+</h{{ .Level }}>

themes/powershell-community/static/css/heading-anchors.css

@@ -0,0 +1,35 @@
+/* Linkable article headings — a hover-revealed anchor link next to each
+   heading. Rendered by layouts/_markup/render-heading.html. */
+
+.ps-heading {
+  position: relative;
+  /* Clear the sticky site header (bg-white shadow-lg sticky top-0) when
+     jumping to an anchor so the heading isn't hidden underneath it. */
+  scroll-margin-top: 5.5rem;
+}
+
+.ps-heading-anchor {
+  opacity: 0;
+  margin-left: 0.4em;
+  font-size: 0.7em;
+  color: #9ca3af;
+  text-decoration: none;
+  vertical-align: middle;
+  transition: opacity 0.15s ease, color 0.15s ease;
+}
+
+.ps-heading:hover .ps-heading-anchor,
+.ps-heading-anchor:focus-visible {
+  opacity: 1;
+}
+
+.ps-heading-anchor:hover {
+  color: #2563eb;
+}
+
+/* Touch devices can't hover — keep the anchor discoverable but subtle. */
+@media (hover: none) {
+  .ps-heading-anchor {
+    opacity: 0.5;
+  }
+}