Skip to content

feat(blog): reading progress outline with mobile table of contents - #69

Merged
ayuthmang merged 3 commits into
mainfrom
claude/sharp-ramanujan-m4nzbr
Nov 18, 2026
Merged

ayuthmang merged 3 commits into
mainfrom
claude/sharp-ramanujan-m4nzbr

Conversation

@ayuthmang

Copy link
Copy Markdown
Owner

Summary

Replaces the plain "On this page" list on local MDX posts with a reading-progress outline styled to match the site: the cyan → blue → indigo gradient from the AYUTH wordmark, Maven Pro headings, and the same spring easing as the header's social-links pill.

  • Desktop sidebar: next to the outline runs a vertical rail that fills with the gradient as you read. A marker moves down it, easing between items in proportion to how far through each section you are. Above it: a progress ring and percentage. Below it: N min read, then N min left, then All done 🎉, plus a back-to-top link.
  • Mobile: a gradient progress bar under the header, plus a floating pill at the bottom showing the progress ring and the current section. Tapping it opens the same outline in a bottom sheet (Radix Dialog). The pill hides while scrolling down and comes back on scroll up.
  • Current-section tracking: now runs off scroll position, recalculated at most once per frame, instead of IntersectionObserver. The old observer only reacted when a heading entered view from below, so the highlight went stale when scrolling up, and a short final section could never become active.
  • Clicking an item: smooth-scrolls to the heading (instant if the reader has turned on reduce motion). The clicked item stays highlighted until the reader scrolls again by hand, because near the bottom of a page the browser can't bring a late heading to the top.
  • Headings: get scroll-mt-24, so they no longer land under the fixed header.

Bug fix: TOC links to emoji headings were broken

slugify() in src/lib/headings.ts trimmed trailing hyphens and dropped non-ASCII characters, but rehype-slug (github-slugger) keeps both. So "FIRE Lights Me 🔥" rendered as id="fire-lights-me-" while the TOC linked to #fire-lights-me, and those links did nothing on the live site. A Thai heading would have lost every Thai character. Heading ids now come from github-slugger directly, including -1/-2 suffixes for duplicate headings. The old slugify tests asserted the mismatched behavior, so they are updated, and new tests cover emoji, Thai and duplicate headings.

Notes

  • New dependency: github-slugger@^2.0.0. It was already in the lockfile through rehype-slug, so nothing new is downloaded. pnpm-lock.yaml may conflict with chore(deps): bump next from 16.3.3 to 16.4.5 (ayuthmang/ayuthmang.dev#67), whichever merges second.
  • Squash-merge recommended: the first commit is an early claude.dev-style version that the later commits replace.
  • Medium posts: imported posts are unchanged. They have no extracted headings, and their layout never had a TOC.
  • Code layout: the component is split into outline.tsx (rail, list, ring, footer), use-reading-state.ts (scroll hooks), mobile-outline.tsx (pill + sheet), and pure position math in table-of-contents.utils.ts.

Test plan

  • pnpm lint, tsc --noEmit and pnpm test --run pass: 141 tests, including new ones for progress, the reading line, section lookup, rail position and slug parity.
  • pnpm build passes. Its warnings were already present on main: fs tracing in posts.ts, the Edge runtime notice, and Medium returning 429 in CI-like sandboxes.
  • Checked in Chromium with Playwright on both local posts, in light and dark:
    • Desktop at 1400×900: progress reads 0 → ~30 → ~72 → 100%, every outline link lands its heading 96px from the top and highlights it, and the click-hold releases on the next scroll.
    • iPhone 13 emulation: the pill hides on scroll down and shows on scroll up, the sheet opens with focus on the close button, tapping a section closes the sheet and scrolls to the heading, scrolling works again afterwards, and Escape closes the sheet.
    • No console errors.

Generated by Claude Code

- Tree-style outline that highlights the current section as you scroll
  (rAF-throttled scroll math instead of the IntersectionObserver that
  got stuck when scrolling up or on short final sections)
- Dithered progress bar with percentage and minutes-left countdown
- Hairline progress bar on small screens where the outline is hidden
- Smooth-scroll on click (respects reduced motion) and scroll-margin on
  headings so they no longer hide under the fixed header

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01LuN2c8JfmswopfnL9kDVWe
Replace the claude.dev-style monospace tree with a design built from
this site's language:

- Vertical rail in the brand cyan→blue→indigo gradient that fills as you
  read; a marker travels down it, easing between items in proportion to
  how far through each section you are
- Gradient progress ring + percentage, "N min left" countdown, and a
  back-to-top link once you've started
- Active item nudges in with the same spring curve as the header's
  social-links pill
- Gradient progress bar under the header on small screens
- Clicked item stays highlighted until the reader scrolls again (the page
  can't always bring late headings to the top)

fix(headings): generate ids with github-slugger to match rehype-slug

The hand-rolled slugify trimmed trailing hyphens and dropped non-ASCII
letters, so TOC links to headings like "FIRE Lights Me 🔥" (rendered as
#fire-lights-me-) pointed nowhere, and Thai headings would have produced
empty ids. Duplicate headings now get -1/-2 suffixes like rehype-slug.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01LuN2c8JfmswopfnL9kDVWe
Small screens previously only had a progress hairline; the outline itself
was unreachable. Now a pill at the bottom shows the progress ring and the
current section, and tapping it opens the full outline (same gradient
rail) in a bottom sheet built on Radix Dialog.

- Pill hides while scrolling down and returns on scroll up, at the end of
  the article, or right as reading starts so it's discoverable
- Sheet rows are 40px tall for easy tapping; picking a section or "Back to
  top" closes the sheet first, then scrolls once the scroll lock is gone
- Respects iOS safe-area insets and reduced motion

Refactor: split the outline into shared pieces (outline.tsx,
use-reading-state.ts) so the sidebar and sheet render the same thing.

fix: the active item's nudge never animated. Tailwind v4's translate-x-*
sets the CSS `translate` property, not `transform`, so the transition
list now names `translate`.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01LuN2c8JfmswopfnL9kDVWe
@vercel

vercel Bot commented Nov 18, 2026

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated
ayuthmang-dev Ready Ready Preview Nov 18, 2026 4:10pm UTC

@chatgpt-codex-connector

Copy link
Copy Markdown
Codex Review Summary: ❌ Failed

This comment shows the latest Codex review activity on this pull request.

Review Status Commit Review trigger
📝 Code Review ❌ Failed 2026-11-18T16:10:39.228187Z
We couldn’t complete this review. Comment @codex review to try again.
898d968 PR opened
ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

@chatgpt-codex-connector

Copy link
Copy Markdown

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.

@ayuthmang
ayuthmang merged commit 5f92971 into main Nov 18, 2026
3 checks passed

This branch was successfully deployed

1 active deployment
Preview — 898d9689 Deployed Nov 18, 2026 by vercel[bot]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants