Add links to headings

Author: mcecode

astro.config.ts

@@ -1,6 +1,7 @@
 import type { RehypePlugin } from "@astrojs/markdown-remark";
 import type { AstroIntegration, AstroUserConfig } from "astro";
-import type { Options } from "rehype-class-names";
+import type { Options as AutolinkHeadingsOptions } from "rehype-autolink-headings";
+import type { Options as ClassNamesOptions } from "rehype-class-names";
 import type {
   LegacyAsyncImporter,
   LegacySharedOptions,
@@ -15,21 +16,23 @@ import path from "node:path";
 import nodeUrl from "node:url";
 import util from "node:util";
 
+import { rehypeHeadingIds } from "@astrojs/markdown-remark";
 import mdx from "@astrojs/mdx";
-// @ts-expect-error There's no type declaration but it exists.
+// @ts-expect-error - There's no type declaration but it exists.
 import remarkA11yEmoji from "@fec/remark-a11y-emoji";
 import { addExtension, createFilter, dataToEsm } from "@rollup/pluginutils";
 import compress from "astro-compress";
 import { walk } from "estree-walker";
 import findCacheDirectory from "find-cache-dir";
 import gifsicle from "gifsicle";
 import { customAlphabet } from "nanoid";
+import rehypeAutolinkHeadings from "rehype-autolink-headings";
 import rehypeClassNames from "rehype-class-names";
 import sharp from "sharp";
 sharp.cache(false);
 
 //==================================================
-// Astro - Shiki and rehype
+// Astro - Markdown transformers and plugins
 //==================================================
 
 const classNamesTransformer: ShikiTransformer = {
@@ -41,7 +44,7 @@ const classNamesTransformer: ShikiTransformer = {
     node.properties.class = "block-code-token";
   }
 };
-const classNamesPlugin: [RehypePlugin, Options] = [
+const classNamesPlugin: [RehypePlugin, ClassNamesOptions] = [
   rehypeClassNames,
   { ":not(pre) > code": "inline-code" }
 ];
@@ -103,6 +106,11 @@ const themeTransformer: ShikiTransformer = {
   }
 };
 
+const autolinkHeadingsPlugin: [RehypePlugin, AutolinkHeadingsOptions] = [
+  rehypeAutolinkHeadings,
+  { behavior: "wrap" }
+];
+
 //==================================================
 // Astro - Integrations
 //==================================================
@@ -402,7 +410,7 @@ export default <AstroUserConfig>{
       transformers: [classNamesTransformer, themeTransformer]
     },
     remarkPlugins: [remarkA11yEmoji],
-    rehypePlugins: [classNamesPlugin]
+    rehypePlugins: [classNamesPlugin, rehypeHeadingIds, autolinkHeadingsPlugin]
   },
   integrations: [mdx(), optimizeImagesIntegration, compress({ Image: false })],
   vite: { css: { preprocessorOptions: { scss } }, plugins: [generateIdsPlugin] }

package-lock.json

@@ -17,6 +17,7 @@
     "find-cache-dir": "^5.0.0",
     "gifsicle": "^7.0.1",
     "nanoid": "^5.0.6",
+    "rehype-autolink-headings": "^7.1.0",
     "rehype-class-names": "^2.0.0",
     "sass": "^1.62.1",
     "sharp": "^0.33.2"

package.json

@@ -1,3 +1,28 @@
+// Inspired from MDN's heading link styles
+h2 a {
+  text-decoration: none;
+
+  &::before {
+    $hashSize: v-size(3, "em");
+
+    content: "#";
+    display: inline-block;
+    width: $hashSize;
+    margin-left: -#{$hashSize};
+    color: var(--c-accent-1);
+    font-size: $hashSize;
+    visibility: hidden;
+  }
+
+  &:hover {
+    text-decoration: underline solid;
+
+    &::before {
+      visibility: visible;
+    }
+  }
+}
+
 article {
   padding-bottom: v-size(10);
 
@@ -12,6 +37,7 @@ article {
     list-style: circle inside;
   }
 
+  // Inspired from GitHub's inline code styles
   .inline-code {
     padding: 0.2em 0.4em;
     border-radius: 6px;