---
interface PageHeadings {
  /** The text value within the heading tag; stripped of HTML. */
  text: string;
  /** A generated slug value based on the text. */
  slug: string;
  /** Depth indicates headings H1-H6. */
  depth: number;
}

/** The generated list of page headings, slugs, and depth. */
const headings: PageHeadings[] = [
  { text: 'Real World Example', slug: 'real-world-example', depth: 1 },
  { text: 'Semantic Markup', slug: 'semantic-markup', depth: 1 },
  { text: 'Utilities', slug: 'utilities', depth: 1 },
  { text: 'Grid', slug: 'grid', depth: 2 },
  { text: 'Alignment', slug: 'alignment', depth: 2 },
  { text: 'Responsive Design', slug: 'responsive-design', depth: 2 },
  { text: 'In Conclusion', slug: 'in-conclusion', depth: 1 }
];

/** Provide a padding-left class based on the depth. */
function setIndentationClass(depth: number) {
  // prettier-ignore
  switch(depth) {
    case(6): return 'pl-12';
    case(5): return 'pl-10';
    case(4): return 'pl-8';
    case(3): return 'pl-6';
    case(2): return 'pl-4';
    case(1): return 'pl-2';
    default: return 'pl-0';
  }
}
---

<nav class="card bg-surface-100-900 p-4">
  <!-- Table of Contents -->
  <div class="type-scale-2 space-y-2">
    <!-- Label -->
    <span class="font-bold">On This Page</span>
    <!-- Links -->
    <ul class="space-y-2">
      <!-- Consider a fixed scroll position at the top of your page layouts. -->
      <li><a href={`#_top`} class="anchor block">Overview</a></li>
      <!-- Loop through the available headings. -->
      {
        headings.map((heading: PageHeadings) => (
          <li>
            {/* Apply a indentation class based on the depth. */}
            <a href={`#${heading.slug}`} class="anchor block" class:list={setIndentationClass(heading.depth)}>
              {heading.text}
            </a>
          </li>
        ))
      }
    </ul>
  </div>
</nav>

Deep Linking

Browsers allow you to deep link to any element via the ID. This is accomplished with an anchor tag and hashed (#) href value. When interacting with these anchors, the viewport will automatically attempt to scroll the <body> element and bring the element into view.

<h2 class="#some-example-slug">Some Example Heading<h2>

<a href="#real-world-example" class="anchor">Some Example Heading</a>

TIP: If you abstract scrolling away from the <body> element, this will not work.

Scroll Behavior

You may optionally choose to implement a smooth scroll behavior using CSS.

<body class="smooth-scroll">

body { scroll-behavior: smooth; }

Generate a Slug

The following provides a barebones implementation for generating a slug based on a heading text value.

function generateSlug(text: string, prefix?: string = '', suffix?: string = '') {
  // Format the slug from the text value.
  const slug = text
    .toLowerCase()
    .replaceAll(/[^a-zA-Z0-9 ]/g, '')
    .replaceAll(' ', '-')
    .toLowerCase();
  // Note that you can optionally apply a prefix/suffix.
  return `${prefix}${slug}${suffix}`;
}

// Usage
generateSlug('An Example Header'); // result: an-example-header
generateSlug('An Example Header', 'skeleton-'); // result: skeleton-an-example-header
generateSlug('An Example Header', '', '-skeleton'); // result: an-example-header-skeleton

Guides

Specific instructions for generating headings will differ based on your meta-framework and your application architecture. Below are a few suggestions, but this is neither a definitive or exhaustive list of all available options.

Astro - enables you to automatically generate headings using built-in MDX features.
Svelte - Melt UI provides a headless component solution for Svelte.
Next.js - Nextra provides a headless component solution for Next.js + MDX.
Rehype Plugin - a general purpose Rehype plugin for generating a table of contents.