This folder contains the reusable “scrolly” system used to build interactive scrollytelling pages in this repo. The system is designed to separate narrative content (MDX) from technical visualization data (TypeScript/JSON).
Think of a scrollytelling page as four distinct layers:
- Narrative (MDX): Located in
src/posts/scrolly/*.mdx. This is where you write your story using Markdown. It uses aconfigIdto link to its technical data. - Configuration (Data): Located in
src/scrolly/data/*.ts. These are standalone TypeScript files that export the visualization datasets, hero stats, and metadata. - Layout (Astro): The
src/layouts/ScrollyLayout.astrocomponent. It acts as the "glue"—fetching the data, merging it with MDX frontmatter (including optionalthemeoverrides), and rendering the sidecar structure. - Engine (Runtime): The
src/scrolly/scrolly-runtime.ts. This script tracks the user's scroll position and dynamically initializes/switches the visualizations on the right column.
You can provide a theme object in the MDX frontmatter to override default colors:
theme:
accent: "#4DE1FF"
paper: "#070A12"
# ... see docs/scrollytelling.md for more- User visits a route (e.g.,
/scrolly/test-scrolly). [slug].astrorenders the MDX file.ScrollyLayout.astroreads theconfigIdfrom MDX frontmatter.- The Layout dynamically imports the matching file from
src/scrolly/data/. - The Layout renders the Hero, the Markdown content (left), and the Viz Panels (right).
scrolly-runtime.tsactivates, tracking the.scroll-sectionelements and updating the.viz-panelstates.
scrolly-entry.ts: The browser entry point that waits for DOM ready.scrolly-runtime.ts: The core logic for scroll tracking and viz management.viz/: D3/SVG visualization modules (e.g.,scatter.ts,timeline.ts).data/: Configuration files for each story.
src/layouts/ScrollyLayout.astro: The primary layout.src/components/scrolly/ScrollySection.astro: The wrapper for Markdown sections.