feat: add TOC, related posts, and reading progress bar

Assisted by Claude Code

Signed-off-by: Avinal Kumar <avinal.xlvii@gmail.com>

src/components/RelatedPosts.astro

@@ -0,0 +1,157 @@
+---
+import type { CollectionEntry } from "astro:content";
+
+interface Props {
+  posts: CollectionEntry<"posts">[];
+}
+
+const { posts } = Astro.props;
+
+const fmtDate = (d: Date) =>
+  d.toLocaleDateString("en-US", {
+    year: "numeric",
+    month: "short",
+    day: "numeric",
+  });
+---
+
+<aside class="related" aria-label="Related posts">
+  <h2 class="related-heading">Related Posts</h2>
+  <ul class="related-list">
+    {posts.map((post) => (
+      <li class="related-item">
+        <a href={`/posts/${post.id}/`} class="related-link">
+          <div class="related-thumb">
+            {post.data.image ? (
+              <img src={post.data.image} alt={post.data.title} class="thumb-img" loading="lazy" decoding="async" />
+            ) : (
+              <span class="thumb-placeholder">{post.data.title.charAt(0)}</span>
+            )}
+          </div>
+          <div class="related-info">
+            <div class="related-meta">
+              <span class="badge">{post.data.category}</span>
+              <span class="text-muted text-xs">{fmtDate(post.data.date)}</span>
+            </div>
+            <strong class="related-title">{post.data.title}</strong>
+            {post.data.description && (
+              <p class="related-desc">{post.data.description}</p>
+            )}
+          </div>
+        </a>
+      </li>
+    ))}
+  </ul>
+</aside>
+
+<style>
+  .related {
+    border-top: 1px solid var(--border);
+    padding-top: var(--space-8);
+    margin-top: var(--space-10);
+  }
+
+  .related-heading {
+    font-size: var(--text-lg);
+    margin-bottom: var(--space-4);
+  }
+
+  .related-list {
+    display: flex;
+    flex-direction: column;
+    gap: 1px;
+  }
+
+  .related-item {
+    border-top: 1px solid var(--border);
+  }
+
+  .related-item:first-child {
+    border-top: none;
+  }
+
+  .related-link {
+    display: grid;
+    grid-template-columns: 140px 1fr;
+    gap: var(--space-4);
+    padding: var(--space-3) var(--space-2);
+    text-decoration: none;
+    color: inherit;
+    transition: background-color var(--duration-fast) var(--ease-out);
+  }
+
+  .related-link:hover {
+    background-color: var(--bg-surface-hover);
+  }
+
+  .related-thumb {
+    aspect-ratio: 3 / 2;
+    overflow: hidden;
+    background-color: var(--bg-surface-hover);
+  }
+
+  .thumb-img {
+    width: 100%;
+    height: 100%;
+    object-fit: cover;
+    filter: grayscale(100%);
+    transition: filter var(--duration-normal) var(--ease-out);
+  }
+
+  .related-link:hover .thumb-img {
+    filter: grayscale(0%);
+  }
+
+  .thumb-placeholder {
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    width: 100%;
+    height: 100%;
+    font-size: var(--text-lg);
+    font-weight: 700;
+    color: var(--text-muted);
+    opacity: 0.3;
+  }
+
+  .related-info {
+    min-width: 0;
+    display: flex;
+    flex-direction: column;
+    justify-content: center;
+  }
+
+  .related-meta {
+    display: flex;
+    align-items: center;
+    gap: var(--space-3);
+    margin-bottom: var(--space-2);
+  }
+
+  .related-title {
+    font-size: var(--text-base);
+    color: var(--text);
+    display: block;
+  }
+
+  .related-desc {
+    font-size: var(--text-sm);
+    color: var(--text-muted);
+    margin-top: var(--space-1);
+    display: -webkit-box;
+    -webkit-line-clamp: 1;
+    -webkit-box-orient: vertical;
+    overflow: hidden;
+  }
+
+  @media (max-width: 600px) {
+    .related-link {
+      grid-template-columns: 1fr;
+      gap: var(--space-3);
+    }
+
+    .related-thumb {
+      aspect-ratio: 16 / 9;
+    }
+  }
+</style>

src/components/TableOfContents.astro

@@ -0,0 +1,88 @@
+---
+interface Props {
+  headings: { depth: number; slug: string; text: string }[];
+}
+
+const { headings } = Astro.props;
+---
+
+<details class="toc">
+  <summary class="toc-toggle">
+    <span class="toc-label">Table of Contents</span>
+    <svg class="toc-chevron" width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><polyline points="6 9 12 15 18 9"/></svg>
+  </summary>
+  <nav class="toc-nav" aria-label="Table of contents">
+    <ol class="toc-list">
+      {headings.map((h) => (
+        <li class:list={[`toc-depth-${h.depth}`]}>
+          <a href={`#${h.slug}`} class="toc-link">{h.text}</a>
+        </li>
+      ))}
+    </ol>
+  </nav>
+</details>
+
+<style>
+  .toc {
+    border: 1px solid var(--border);
+    padding: var(--space-4) var(--space-5);
+    margin-bottom: var(--space-8);
+    background-color: var(--bg-surface);
+  }
+
+  .toc-toggle {
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    cursor: pointer;
+    list-style: none;
+    font-size: var(--text-sm);
+    font-weight: 600;
+    text-transform: uppercase;
+    letter-spacing: 0.08em;
+    color: var(--accent);
+  }
+
+  .toc-toggle::-webkit-details-marker {
+    display: none;
+  }
+
+  .toc-chevron {
+    transform: rotate(-90deg);
+    transition: transform var(--duration-fast) var(--ease-out);
+  }
+
+  .toc[open] .toc-chevron {
+    transform: rotate(0deg);
+  }
+
+  .toc-nav {
+    margin-top: var(--space-3);
+    padding-top: var(--space-3);
+    border-top: 1px solid var(--border);
+  }
+
+  .toc-list {
+    list-style: none;
+    padding: 0;
+  }
+
+  .toc-list li {
+    padding: var(--space-1) 0;
+  }
+
+  .toc-depth-3 {
+    padding-left: var(--space-4);
+  }
+
+  .toc-link {
+    font-size: var(--text-sm);
+    color: var(--text-secondary);
+    text-decoration: none;
+    transition: color var(--duration-fast) var(--ease-out);
+  }
+
+  .toc-link:hover {
+    color: var(--accent);
+  }
+</style>

src/layouts/PostLayout.astro

@@ -1,5 +1,8 @@
 ---
 import BaseLayout from "./BaseLayout.astro";
+import TableOfContents from "@/components/TableOfContents.astro";
+import RelatedPosts from "@/components/RelatedPosts.astro";
+import type { CollectionEntry } from "astro:content";
 
 interface Props {
   title: string;
@@ -10,6 +13,8 @@ interface Props {
   tags?: string[];
   image?: string;
   readingTime: string;
+  headings?: { depth: number; slug: string; text: string }[];
+  relatedPosts?: CollectionEntry<"posts">[];
 }
 
 const {
@@ -21,6 +26,8 @@ const {
   tags = [],
   image,
   readingTime,
+  headings = [],
+  relatedPosts = [],
 } = Astro.props;
 
 const fmtDate = (d: Date) =>
@@ -49,6 +56,7 @@ const blogPostingLd = {
 ---
 
 <BaseLayout title={title} description={description} ogImage={image || undefined} jsonLd={blogPostingLd}>
+  <div class="reading-progress" aria-hidden="true"></div>
   <article class="post-page">
     {image && (
       <div class="post-hero-img">
@@ -83,9 +91,13 @@ const blogPostingLd = {
       )}
     </header>
 
+    {headings.length > 0 && <TableOfContents headings={headings} />}
+
     <div class="prose">
       <slot />
     </div>
+
+    {relatedPosts.length > 0 && <RelatedPosts posts={relatedPosts} />}
   </article>
 </BaseLayout>
 
@@ -114,6 +126,7 @@ const blogPostingLd = {
     margin-bottom: var(--space-10);
     padding-bottom: var(--space-6);
     border-bottom: 1px solid var(--border);
+    text-align: center;
   }
 
   .post-category {
@@ -136,6 +149,7 @@ const blogPostingLd = {
   .post-meta-row {
     display: flex;
     align-items: center;
+    justify-content: center;
     flex-wrap: wrap;
     gap: var(--space-2);
     font-size: var(--text-sm);
@@ -153,6 +167,7 @@ const blogPostingLd = {
   .post-tags {
     display: flex;
     flex-wrap: wrap;
+    justify-content: center;
     gap: var(--space-2);
     margin-top: var(--space-3);
   }
@@ -165,4 +180,30 @@ const blogPostingLd = {
     border-radius: var(--radius-sm);
     border: 1px solid var(--border);
   }
+
+  .reading-progress {
+    position: fixed;
+    top: 0;
+    left: 0;
+    height: 3px;
+    width: 0%;
+    background-color: var(--accent);
+    z-index: 200;
+    pointer-events: none;
+  }
 </style>
+
+<script>
+  const bar = document.querySelector<HTMLElement>('.reading-progress');
+  const article = document.querySelector('.post-page');
+  if (bar && article) {
+    const update = () => {
+      const total = article.scrollHeight - window.innerHeight;
+      const scrolled = window.scrollY - (article as HTMLElement).offsetTop;
+      const pct = Math.min(100, Math.max(0, (scrolled / total) * 100));
+      bar.style.width = `${pct}%`;
+    };
+    window.addEventListener('scroll', update, { passive: true });
+    update();
+  }
+</script>

src/pages/posts/[...slug].astro

@@ -11,11 +11,26 @@ export async function getStaticPaths() {
 }
 
 const { post } = Astro.props;
-const { Content } = await render(post);
+const { Content, headings } = await render(post);
+const tocHeadings = headings.filter((h) => h.depth === 2 || h.depth === 3);
 
 const wordCount = post.body?.split(/\s+/).length ?? 0;
 const minutes = Math.max(1, Math.round(wordCount / 220));
 const readingTime = `${minutes} min read`;
+
+const allPosts = await getCollection("posts", ({ data }) => !data.draft);
+const relatedPosts = allPosts
+  .filter((p) => p.id !== post.id)
+  .map((p) => {
+    let score = 0;
+    if (p.data.category === post.data.category) score += 10;
+    score += p.data.tags.filter((t) => post.data.tags.includes(t)).length * 3;
+    return { post: p, score };
+  })
+  .filter((s) => s.score > 0)
+  .sort((a, b) => b.score - a.score || b.post.data.date.getTime() - a.post.data.date.getTime())
+  .slice(0, 3)
+  .map((s) => s.post);
 ---
 
 <PostLayout
@@ -27,6 +42,8 @@ const readingTime = `${minutes} min read`;
   tags={post.data.tags}
   image={post.data.image}
   readingTime={readingTime}
+  headings={tocHeadings}
+  relatedPosts={relatedPosts}
 >
   <Content />
 </PostLayout>