Enhanced Heading Hierarchy and Table of Contents

Summary

Improved heading styles across all levels (h1-h6), enhanced table of contents nesting, and added a custom 404 error page to ensure consistent visual hierarchy, navigation, and error handling.

Why Care

Proper heading hierarchy is crucial for both visual organization and accessibility. These changes ensure that all heading levels are properly styled and nested in the table of contents, making content more scannable and navigable for all users. Additionally, a custom 404 page provides a better user experience when encountering missing pages.

Implementation

Changes Made

  • Updated heading styles in site/src/components/articles/OneArticleOnPage.astro:
    • Implemented consistent decreasing font sizes from h1 to h6
    • Standardized color using var(--clr-lossless-accent--brightest)
    • Removed special text styling from h6 for consistency
    • Added responsive mobile adjustments
  • Enhanced table of contents in site/src/components/markdown/TableOfContents.astro:
    • Added distinct styling for depth-6 headings
    • Implemented progressive indentation for all heading levels
    • Added mobile-specific padding adjustments
    • Fixed nesting behavior for deep heading levels
  • Added custom 404 error handling:
    • Created engaging not-found page with random humorous messages
    • Added ASCII art and animated elements for better user experience
    • Implemented dual-file approach with 404.astro and not-found.astro
    • Ensured proper error page display in both development and production

Technical Details

Heading Size Hierarchy

css 
h1: 2.75rem
h2: 2.25rem
h3: 1.875rem
h4: 1.5rem
h5: 1.25rem
h6: 1.125rem
  • Removed attempted runtime OpenGraph title modification via URL parameters
  • Reverted to static OpenGraph tags generated at build time
  • Future enhancement planned to research proper heading-level sharing:
    • Will investigate SSR/hybrid rendering options
    • Need to ensure social preview cards can show specific section titles
    • Must maintain build-time generation for optimal performance

TOC Indentation Progression

css 
depth-0: 1rem
depth-1: 2rem
depth-2: 3rem
depth-3: 4rem
depth-4: 5rem
depth-5: 6rem
depth-6: 7rem

/* Mobile adjustments */
depth-0: 0.75rem
depth-1: 1.5rem
depth-2: 2.25rem
depth-3: 3rem
depth-4: 3.75rem
depth-5: 4.5rem
depth-6: 5.25rem

404 Page Features

typescript 
// Random message selection
const funnyMessages = [
  "Looks like this page took 'lossless innovation' too literally and disappeared!",
  "Our AI assistant is still learning directories... and comedy apparently.",
  "This page is practicing social distancing from our server.",
  "Even with all our tools, we couldn't find this one!",
  "Error 404: Page went to get coffee, might be back later.",
];

Integration Points

  • The heading styles in OneArticleOnPage.astro work in conjunction with the copy link button component for each heading
  • Table of contents nesting levels align with the visual hierarchy of the headings
  • Mobile responsiveness is coordinated between both components
  • 404 error handling works seamlessly between local development and Vercel deployment

Documentation

  • Heading styles are globally applied through the .prose class in OneArticleOnPage.astro
  • Table of contents depth styling uses the .toc-depth-{n} classes for consistent nesting
  • All heading levels maintain WCAG color contrast requirements using the accent color variable
  • Error pages use a dual-file approach for maximum compatibility:
    • not-found.astro contains the main error page content
    • 404.astro provides a redirect fallback for systems that expect this filename