Blog heading anchors (#979)

* feat: add anchor links to blog post headings

Blog posts are rendered from WordPress HTML and can cover multiple
features in a single article. Add slugified ids and hover-visible
anchor links to every heading so sections can be deep-linked, and
introduce an optional blogFragment field on features so a feature
can point at a specific section of a multi-topic post.

* feat: link features to blog sections and add Network AI Prompts

Wire features 15 (Professional recordings & screenshots) and 28
(Build Insights) to their matching sections in the AI prompts +
recording metadata blog post, and add a new Network AI Prompts
feature entry on the networking page (hidden from the homepage)
that deep-links to the prompt export section.

Author: ngnijland

docs/package-lock.json

@@ -22,6 +22,7 @@
     "aos": "^2.3.4",
     "astro": "^5.16.6",
     "date-fns": "^4.1.0",
+    "github-slugger": "^2.0.0",
     "marked": "^16.4.1",
     "react": "^19.2.3",
     "react-dom": "^19.2.3",

docs/package.json

@@ -0,0 +1,15 @@
+---
+showOnHomepage: false
+name: "Network AI Prompts"
+blogId: 32
+blogFragment: "exporting-network-requests-ai-prompts"
+featurePage: "networking"
+asset:
+  type: "image"
+  path: "../../assets/features/network-ai-prompts.png"
+  alt: "Exported network request prompt showing redacted request and response data, ready to paste into an AI assistant."
+  alignment: "left"
+  columnSpan: 8
+---
+
+Export network requests as **privacy-redacted prompts** you can paste straight into ChatGPT, Claude, or any other AI assistant.

docs/src/assets/features/network-ai-prompts.png

@@ -33,6 +33,7 @@ const feature = defineCollection({
       tagLine: z.string().optional(),
       docPath: z.string().optional(),
       blogId: z.number().optional(),
+      blogFragment: z.string().optional(),
       youtubeLink: z.string().url().optional(),
       featurePage: z
         .enum([

docs/src/collections/feature/31-network-ai-prompts.md

@@ -10,7 +10,7 @@ interface Props {
 }
 
 const {
-  data: { asset, tagLine, name, blogId, youtubeLink },
+  data: { asset, tagLine, name, blogId, blogFragment, youtubeLink },
 } = Astro.props;
 const parsedCaption = asset.caption
   ? marked.parseInline(asset.caption)
@@ -24,7 +24,7 @@ if (blogId) {
     `${blogBaseUrl}/wp-json/wp/v2/posts/${blogId}?_fields=slug`,
   );
   const { slug } = (await res.json()) as { slug: string };
-  blogPath = `/blog/${slug}`;
+  blogPath = `/blog/${slug}${blogFragment ? `#${blogFragment}` : ""}`;
 }
 
 let imageSizes;

docs/src/content.config.ts

@@ -1,5 +1,9 @@
 ---
 import { JSDOM } from "jsdom";
+import GithubSlugger from "github-slugger";
+import { createElement } from "react";
+import { renderToStaticMarkup } from "react-dom/server";
+import { FaLink } from "react-icons/fa6";
 import { Image } from "astro:assets";
 
 import Base from "@/layouts/Base.astro";
@@ -125,6 +129,27 @@ videos.forEach((video) => {
   video.setAttribute("controls", "true");
 });
 
+const slugger = new GithubSlugger();
+const headings = doc.querySelectorAll("h1, h2, h3, h4, h5, h6");
+const linkIconMarkup = renderToStaticMarkup(
+  createElement(FaLink, { "aria-hidden": true }),
+);
+
+headings.forEach((heading) => {
+  const text = heading.textContent?.trim() ?? "";
+  if (!text) return;
+
+  const id = heading.id || slugger.slug(text);
+  heading.id = id;
+
+  const anchor = doc.createElement("a");
+  anchor.setAttribute("href", `#${id}`);
+  anchor.setAttribute("class", "heading-anchor");
+  anchor.setAttribute("aria-label", `Link to section: ${text}`);
+  anchor.innerHTML = linkIconMarkup;
+  heading.insertBefore(anchor, heading.firstChild);
+});
+
 const manipulatedDom = dom.serialize();
 ---
 
@@ -191,3 +216,48 @@ const manipulatedDom = dom.serialize();
     </section>
   </article>
 </Base>
+
+<style>
+  .content :global(h1),
+  .content :global(h2),
+  .content :global(h3),
+  .content :global(h4),
+  .content :global(h5),
+  .content :global(h6) {
+    position: relative;
+
+    scroll-margin-top: 6rem;
+  }
+
+  .content :global(.heading-anchor) {
+    position: absolute;
+    top: 56%;
+    right: calc(100% + 0.5rem);
+
+    display: inline-flex;
+    align-items: center;
+
+    color: inherit;
+    text-decoration: none;
+
+    opacity: 0;
+
+    transform: translateY(-50%);
+    transition: opacity 150ms ease;
+  }
+
+  .content :global(.heading-anchor svg) {
+    width: 0.5em;
+    height: 0.5em;
+  }
+
+  .content :global(h1:hover .heading-anchor),
+  .content :global(h2:hover .heading-anchor),
+  .content :global(h3:hover .heading-anchor),
+  .content :global(h4:hover .heading-anchor),
+  .content :global(h5:hover .heading-anchor),
+  .content :global(h6:hover .heading-anchor),
+  .content :global(.heading-anchor:focus-visible) {
+    opacity: 1;
+  }
+</style>