feat: heading links

Author: duanwilliam

website/src/layout/components/ContentContainer/styles.module.scss

@@ -8,12 +8,8 @@ $sidebar-width: sidebar.$desktop-sidebar-width;
 $toc-width: toc.$desktop-toc-width;
 
 .contentContainer {
-  padding: 1rem;
+  padding: 2rem;
   margin: 0 auto;
   width: calc(100% - #{$toc-width});
   max-width: 1200px; // TODO: pick less arbitrary value
-
-  @include mixins.desktop() {
-    padding: 1rem 2rem;
-  }
 }

website/src/mdx/Heading/index.tsx

@@ -0,0 +1,41 @@
+import c from "clsx";
+
+import { linkIconSize } from "./styles.export.module.scss";
+import { heading, anchor, svg, path } from "./styles.module.scss"
+
+import type { HTMLAttributes } from "react"
+import type { HeadingLevel } from "@/lib/unified/toc/types"
+
+interface HeadingProps extends HTMLAttributes<HTMLHeadingElement> {
+  as: `h${HeadingLevel}`
+}
+
+export default function Heading ({
+  as: Tag,
+  className,
+  children,
+  ...props
+}: HeadingProps) {
+  return (
+    <Tag className={c(heading, className)} {...props}>
+      <span>{children}</span>
+      {!props.id ? null : (
+        <a
+          className={anchor}
+          href={`#${props.id}`}
+          title="Direct link to heading"
+        >
+          {/* link icon */}
+          <svg className={svg} width={linkIconSize} height={linkIconSize} viewBox="0 0 24 24">
+            <path className={path} d="M3.9 12c0-1.71 1.39-3.1 3.1-3.1h4V7H7c-2.76 0-5 2.24-5 5s2.24 5 5 5h4v-1.9H7c-1.71 0-3.1-1.39-3.1-3.1zM8 13h8v-2H8v2zm9-6h-4v1.9h4c1.71 0 3.1 1.39 3.1 3.1s-1.39 3.1-3.1 3.1h-4V17h4c2.76 0 5-2.24 5-5s-2.24-5-5-5z" />
+          </svg>
+        </a>
+      )}
+    </Tag>
+  )
+}
+
+export const getHeading = (as: `h${HeadingLevel}`) => (
+  (props: HTMLAttributes<HTMLHeadingElement>) => <Heading as={as} {...props} />
+)
+

website/src/mdx/Heading/styles.export.module.scss

@@ -0,0 +1,6 @@
+@use "@/styles/utils";
+@use "./styles.module.scss" as *;
+
+:export {
+  linkIconSize: utils.strip-units($link-icon-size);
+};

website/src/mdx/Heading/styles.export.module.scss.d.ts

@@ -0,0 +1,14 @@
+// AUTOGENERATED FILE -- DO NOT EDIT DIRECTLY
+declare namespace StylesExportModuleScssNamespace {
+  export interface IStylesExportModuleScss {
+    anchor: string;
+    heading: string;
+    linkIconSize: string;
+    path: string;
+    svg: string;
+  }
+}
+
+declare const StylesExportModuleScssModule: StylesExportModuleScssNamespace.IStylesExportModuleScss;
+
+export = StylesExportModuleScssModule;

website/src/mdx/Heading/styles.module.scss

@@ -0,0 +1,35 @@
+@use "@/styles/colors";
+
+$link-icon-size: 16px;
+
+$link-padding: 0.5rem;
+
+.heading {
+  position: relative;
+}
+
+.anchor {
+  position: absolute;
+  left: calc(-1 * (#{$link-icon-size} + #{2 * $link-padding}));
+  height: 100%;
+  padding: $link-padding;
+  display: inline-flex;
+  align-items: center;
+  user-select: none;
+  
+  opacity: 0;
+  transition: opacity 200ms;
+
+  .heading:hover &, &:hover {
+    opacity: 1;
+  }
+  
+  &:hover .path {
+    fill: colors.$red;
+  }
+
+  .svg {
+    width: $link-icon-size;
+    height: $link-icon-size;
+  }
+}

website/src/mdx/Heading/styles.module.scss.d.ts

@@ -0,0 +1,13 @@
+// AUTOGENERATED FILE -- DO NOT EDIT DIRECTLY
+declare namespace StylesModuleScssNamespace {
+  export interface IStylesModuleScss {
+    anchor: string;
+    heading: string;
+    path: string;
+    svg: string;
+  }
+}
+
+declare const StylesModuleScssModule: StylesModuleScssNamespace.IStylesModuleScss;
+
+export = StylesModuleScssModule;

website/src/mdx/components.tsx

@@ -11,6 +11,7 @@ import Link from 'next/link';
 import CodeBlock from './CodeBlock';
 
 import type { ComponentMap } from "mdx-bundler/client";
+import Heading, { getHeading } from './Heading';
 
 const MDXComponents: ComponentMap = {
   code: (props: any) => {
@@ -48,7 +49,13 @@ const MDXComponents: ComponentMap = {
           : {...props}))}
       />
     );
-  }
+  },
+  h1: getHeading('h1'),
+  h2: getHeading('h2'),
+  h3: getHeading('h3'),
+  h4: getHeading('h4'),
+  h5: getHeading('h5'),
+  h6: getHeading('h6'),
 }
 
 export default MDXComponents;

website/src/mdx/markdown.module.scss

@@ -32,6 +32,18 @@
 
   /* apply these styles only in markdown "content" (i.e. articles) */ 
   &.content {
+
+    // heading margins
+    h1, h2, h3, h4, h5, h6 {
+      margin: 2em 0 1em;
+    }
+
+    // don't add margin to first child (the whole markdown container has top margin already)
+    > *:first-child {
+      margin-top: 0;
+    }
+
+    // block margins
     > * {
       margin-bottom: 1rem;
     }