Scrollytelling with Closeread: The Super Low-Code Way to Bring Your Data Project to the Web!

Introduction

What is Scrollytelling?

Scrollytelling is a dynamic, interactive storytelling technique often used in web-based formats, that reveals insights, visuals, and narrative elements as the user scrolls down the page. It allows data stories to unfold gradually, guiding the reader through a structured narrative in a way that feels both natural and engaging.

Why Scrollytelling Is Effective for Data Communication

Scrollytelling is a powerful way to communicate data because it helps reduce information overload, boosts user engagement, and makes insights easier to digest. Rather than overwhelming users with dense dashboards or complex visuals all at once, it guides them through your story step by step—just by scrolling.

Scrollytelling is not a replacement for other presentation methods such as dashboards and static pdf reports. Instead, it works best when there’s a need to communicate stories or data insights to a broad audience with varying levels of data literacy. It allows you to wrap each insight in meaningful context and empowers you to control the pacing and structure of your narrative while keeping readers engaged through suspense and sequential reveals. This results in a smoother, more intuitive experience, especially for readers who need guidance or are less data-savvy. This level of engagement is often difficult to achieve with other traditional methods of presentation. As a dynamic and versatile technique, scrollytelling supports various content formats such as text, charts, maps, GIFs, images and more.

The Challenge

Despite its many advantages, scrollytelling has traditionally required web development skills—something many dataviz professionals don’t typically have. In the past, even large media houses with dedicated teams would spend significant time and effort building a scrollytelling project. The tradeoffs were high, making it a less viable option for time-sensitive or resource-constrained projects.

For smaller teams or solo practitioners, this barrier has often made web-based storytelling feel out of reach. But that changes today. Thanks to the many developer communities, the barriers have been so significantly lowered that you can put up your scrollytelling project in a few hours, many of the times, without even needing to code!

What You’ll Learn in This Tutorial

By the end of this tutorial, you’ll be able to build and deploy a fully functional scrollytelling project that takes your insights beyond dashboards and onto the web! Specifically, you’ll be able to:

• Set up your environment and craft your data story using the scrollytelling technique
• Build your project locally and deploy it to the web for free using GitHub and Vercel (or any other deployment platform that supports dynamic webpages)

Don’t worry—we’ll walk through everything step by step, from scratch. Whether you’re an absolute beginner or just looking to sharpen your skills, this tutorial will help you build your first scrollytelling project from the ground up!

One more thing: This tutorial is designed to be hands-on, so as you follow along, feel free to copy each line of code and paste it into your Closeread document to see it in action.

Tools we’ll be using

For this project, we’ll use the Closeread extension to create our data scrollytelling experience. Closeread is a Quarto extension designed specifically for building interactive, scroll-based narratives. To use Closeread, you’ll need two key tools:

1. Quarto: an open-source publishing system that supports Python, R, Julia, and ObservableJS. It allows you to create dynamic, multi-format documents using Markdown, Jupyter Notebooks, or your preferred editor. Since Closeread is built on top of Quarto, installing Quarto is a necessary first step.
2. A Code Editor: This is where you’ll write and manage your project files. We’ll be using Visual Studio Code (VS Code) in this tutorial, but feel free to use alternatives like RStudio, Atom, or any editor that supports Quarto projects.

To get started, install the Quarto command line tool from the official Quarto website. Follow the standard installation process for your operating system. Since I’m using Windows, I downloaded it as shown below.

We’ll also be using GitHub for version control and Vercel to deploy the final project to the web.

Once you’ve installed Quarto, you’re ready to install the Closeread extension. We’ll cover that in the next section.

Set up your project environment

Step 1: Set Up Your Project Directory

Start by creating a folder named closeread_tutorial. You can place this folder anywhere you’d like your project to live. Personally, I prefer to keep it on my Desktop, so my directory structure looks like this:

C:\Users\USER\Desktop\closeread_tutorial

Next, open a terminal and navigate to the folder you just created. An easy way to do this is by copying the full path to the folder.

If you’re on Windows, press Windows Key + R, type cmd, and hit Enter to open the Command Prompt.

Then, run the following command (update the path to match your own folder location if different):

cd "C:\Users\USER\Desktop\closeread_tutorial"

This sets your working directory to the project folder. You can confirm it’s successful by checking that the command prompt now matches the folder path you copied earlier.

Install the Closeread Extension

To install the Closeread extension, run the following command in your command prompt:

quarto add qmd-lab/closeread

Make sure you’re connected to the internet, as this command will fetch the extension from an online repository. You may receive a few prompts asking whether Quarto extensions should be allowed to execute code during document rendering. Simply type Yes for each prompt to proceed with the installation.

Your command prompt should now look similar to this:

The message highlighted in red confirms that Closeread has been successfully installed. You can also verify this by refreshing your project folder. You’ll notice that a new folder named _extensions has been added to it.

Congratulations! 🎉 You’re now all set to create your first Closeread project.

Let’s dive in!

Create a basic Closeread project

Now, inside your project folder, create a new file named index.qmd. Open the file in your code editor and paste the following lines of code:

---
title: My First Closeread
format: closeread-html

---

Hello World! Please read my Closeread story below.

:::{.cr-section}

Closeread enables scrollytelling.

Draw your reader's attention with focus effects. @cr-features

:::{#cr-features}
1. Highlighting  
2. Zooming  
3. Panning  
:::

:::

You’ve just created your first Quarto document! 🎉

Now, let’s render and preview it to see your Closeread project in action. Go to your terminal and run this quarto command:

quarto render index.qmd

This should render your project.

After rendering, you’ll notice that new file and folder have been added to your project directory:

• A folder containing the necessary libraries and assets used by your Closeread project.
• An HTML file generated from your base Quarto document, which serves as the interactive output.

These confirm that your project has successfully compiled and is ready for further development.

To preview the project you just created, open the index.html file in your browser—and voila! Your first Closeread project is live!

We will dedicate the next section to understanding the building blocks of a Closeread project. Let’s ride on 🔥

Understand the building blocks of Closeread

A Closeread project is built as a section within a Quarto document, defined using fenced divs. At its core, a Closeread section consists of three main components: Section, Sticky, and Trigger.

1. Section

A Closeread section is created using opening and closing fenced divs with the .cr-section class. This defines the scrollytelling block.

Here’s what the simplest Closeread section looks like:

:::{.cr-section}
This is a Closeread section
:::

This section can be enhanced with stickies (content that remains fixed while the user scrolls) and triggers (content that activates the sticky as the user scrolls). We’ll explore those next.

💡 Pro Tip: If you wrap your entire Quarto document in a fenced div with the .cr-section class, the whole thing becomes a Closeread document. 😉 This means everything in your document becomes part of the scrollytelling experience—great for fully immersive data stories!

2. Stickies

A sticky is an element within a Closeread section. It could be a block of text, an image, a video, or any element that can be rendered in the browser. It’s the element you want to perform closeread on. This means you can set it to stick to the screen as the reader scrolls through the page.

Stickies can also be made invisible by default, and only appear when the viewer scrolls to the point where the trigger is activated.To declare an element as a sticky, wrap it within a fenced div and assign it an identifier prefixed with cr-, as shown below:

:::{#cr-identifier}
This block of text is a sticky!
:::

Since the sticky must be enclosed within a section, the full code would look like this:

:::{.cr-section}
This is a Closeread section

:::{#cr-identifier}
This block of text is a sticky within the Closeread section!
:::

:::

3. Triggers

As you might already know, a trigger is the element that activates a sticky in a Closeread document.

Remember the cr-identifier we assigned to the sticky above? The one prefixed with cr-? That’s the element we’ll use to trigger the sticky.

Here’s how triggering works:

• Identify the point in your document where you want the sticky to be activated.
• At that point, reference the sticky’s identifier—just replace the cr- prefix with @.

So, cr-identifier becomes @identifier.

Let’s update our full code to include a trigger:

:::{.cr-section}
This is a Closeread section

I want my sticky to appear here ➡️ @cr-identifier

:::{#cr-identifier}
This block of text is a sticky within the Closeread section!
:::

:::

Simple, right? When a reader scrolls to the trigger (@identifier), the sticky pops into view!

Updated code:

Now, copy the updated code and paste it into your index.qmd file, replacing everything after the line that says:

Hello World! Please read my Closeread story below.

Your document should look like this:

---
title: My First Closeread
format: closeread-html

---

Hello World! Please read my Closeread story below.

:::{.cr-section}
This is a Closeread section

I want my sticky to appear here @identifier

:::{#cr-identifier}
This block of text is a sticky within the Closeread section!
:::

:::

Re-render the project:

Once you’ve updated your index.qmd file with the new code, open your terminal and run the quarto render command just like before:

quarto render index.qmd

Refresh your browser tab to see the updated Closeread project. As you scroll, your sticky will appear at the specified trigger point!

Celebrate this milestone so far. If yours is not as shown in the screenshot below, take some time to review your code and ensure that it is similar to the one above.

Adding styling and interactivity to your Closeread document

Closeread offers several options for styling your project—ranging from prebuilt effects to full-fledged themes. What’s more, you can even extend your project’s styling using an external CSS stylesheet. The Closeread styling documentation provides a detailed guide on how to style your document. You can declare the styling template in the YAML configuration section of your document. For this project, let’s apply some of these techniques to further customize our document, starting with the basics: focus effects.

Focus Effects

Focus effects are prebuilt functions within Closeread that add interactivity and dynamism to your Closeread projects. As described in the Closeread documentation, these features “guide your readers’ attention to aspects of your stickies.” A summary of these effects is provided in the table below:

Effect	Description	Syntax Example
Scaling	Magnifies or reduces the size of an element by a given factor.	scale-by=”3″: Triples the size of a sticky.
Panning	Moves the view to a specified section of the sticky (e.g., top-left corner).	pan-to”-30px,30px”: Pans 30 pixels left and 30 pixels down.
Zooming	Enlarges a specific portion of the context to focus the reader’s attention	zoom-to=”3″: Zooms into line 3.
Highlighting	Visually emphasizes a span of text or a line by changing its style or color.	highlight=”2-3″: Highlights lines 2 to 3.

Focus Effects in Action

The purpose of this section is to demonstrate some of these focus effects. The next few lines contain short narratives along with their corresponding Closeread commands. We’ll use some images and text blocks as stickies and apply these effects to them.

NOTE: I’ve taken a conversational approach to explain the purpose of each feature. This is to keep things engaging. But don’t forget, the narratives also form part of the text you’ll copy into your Closeread document!

Now, back to our updated code. Quickly read through the following lines to get a sense of the flow. Afterwards, download these two images: grid.jpg and grid-highlighted.jpg. Create a folder named images directly inside your main project folder (where your index.qmd file is), and paste the two images you just downloaded into this folder. Then, copy the code block below into your Closeread document to see the effects in action:

Below is another block of text we'll be working with: @cr-highlighted
First, let's scale this block of text by two:
Scale this block of text by two [@cr-highlighted]{scale-by="2"}

Next, we’ll highlight lines 2 and 3 while keeping the same scale:
Lines 2 and 3 are scaled and highlighted [@cr-highlighted]{scale-by="2" highlight="2-3"}

Now, let’s bring in an image:
Loads an image @cr-image

It’s a bit large at first as it takes up the full screen. Let’s scale it down:
Image has been scaled down [@cr-image]{scale-by="0.5"}

Finally, we’ll pan to the portion highlighted in red:
Pan the image to the section highlighted in red [@cr-image2]{pan-to="-75%,75%" scale-by="1.5"}

:::{#cr-highlighted}
| 1️⃣ This is the first line.
| 2️⃣ This is the second line.
| 3️⃣ This is the third line.
| 4️⃣ And this is the fourth line.
:::

:::{#cr-image}
![](images/grid.jpg)
:::

:::{#cr-image2}
![](images/grid-highlighted.jpg)
:::

💡Pro tip: When you pan and scale at the same time, you end up zooming! (pun intended 😉)

Note: Panning can be a bit unintuitive at first. You might need to experiment with the position values to get the result you want. A bit of trial and error helps here.

Applying Additional Styling

Up to this point, the YAML configuration section of our project looks like this:

---
title: My First Closeread
format: closeread-html

---

Update it to apply the following styling:

---
title: "Understanding Tree Diagrams"
theme: "superhero"
fontsize: 16px
format: 
    closeread-html:
        cr-section:
            layout: "sidebar-left"
        cr-style:
            section-background-color: "#08508a"
            narrative-background-color-overlay: "#08508a"
            narrative-text-color-overlay: "#08508a"
            narrative-border-radius: 5px
            narrative-overlay-max-width: 60%

---

What we just did: Modified the YAML configuration to include some additional styling, such as:

• Setting the layout to sidebar-effect
• Defining the background color under cr-style
• Setting the theme to super-hero
• Adjusting the font size, and more

Each of these would have required more complex CSS code, but Closeread simplifies the process—you can simply call a named section and apply the style directly.

Applying custom CSS

If you’d like to further customize your Closeread project using an external .css stylesheet, you can follow the standard approach used in regular web development: by assigning styles directly to elements. All you need to do is link your Closeread document to the external stylesheet—and you’ll do this in the YAML section of the document (the part enclosed by triple dashes).

In this example, let’s change the color of the text in the narrative section of our Closeread project. The narrative section is the part of your story that delivers the main content. By default, the text appears black on desktop. We want to change it to white.

Steps:

• Within the root of your project directory, create a new empty file and name it style.css.

Paste the following lines of code into the file and save it:

.narrative {
color: white;
}

• Next, reference the external CSS file in your Closeread document. You can do this by navigating to the YAML configuration section of your document and pasting the following line:

css: style.css

Your YAML section should now look like this:

---
title: "Understanding Tree Diagrams"
theme: "superhero"
fontsize: 16px
format: 
    closeread-html:
        cr-section:
            layout: "sidebar-left"
        cr-style:
            section-background-color: "#08508a"
            narrative-background-color-overlay: "#08508a"
            narrative-text-color-overlay: "#08508a"
            narrative-border-radius: 5px
            narrative-overlay-max-width: 60%
css: style.css

---

Take note of the indentation!

Publish and deploy

You’ve made it this far—well done! You’ve built your first Closeread project. But a project this good shouldn’t live only on your computer. It’s time to publish it to the web and share it with the world!You’ll use GitHub to store your project online, and Vercel to host and publish it for free.

Step 1: Create Your GitHub & Vercel Accounts

• Go to github.com → Click Sign Up and follow the steps to create your account.
• Then, visit vercel.com → Click Start for Free and sign up using your GitHub account. This allows Vercel to access your repositories for deployment.

Step 2: Upload Your Project to GitHub (No Code Required)

1. On GitHub, click the + icon at the top-right → Select “New repository”.
2. Give your repository a name like closeread-project, and click Create repository.
3. On the next page, click “Uploading an existing file”.
4. Locate your Closeread project folder on your computer.
5. Drag and drop everything inside the project folder into the GitHub upload area.
6. Scroll down, add a commit message like Initial upload, and click Commit changes.

Great! Your web story is now on GitHub.

Step 3: Deploy with Vercel

1. On the Vercel dashboard, click “Add New” > “Project”.
2. You’ll be prompted to choose your preferred Git provider. Select Continue with GitHub
3. You’ll see a list of your GitHub repositories. Select the one you just uploaded.
4. Configure your settings:
   • Framework Preset: Choose Other or Static Site
   • Output Directory: leave the default option (root)
5. Click Deploy.

Vercel will build and deploy your project in seconds.

Step 4: View & Share Your Live Story

Once deployment is complete, you’ll get a live URL with which you can access your project live on the web. e.g https://closeread-tutorial.vercel.app/

Click the link to view your published Closeread story—fully interactive and hosted online!

Conclusion

If you’ve followed this tutorial up to this point, you should now be familiar with how to build a scrollytelling project from scratch using Closeread. You’ve learned the core building blocks of a Closeread project—such as sections, stickies, and triggers. You’ve also explored how to style your project using both built-in options and external CSS files. Finally, you now know how to host your project on GitHub and deploy it with Vercel, so your story can go live and be shared with the world.

This gives you a solid foundation for taking your data storytelling skills to the next level.

Up next is a second project I’ve included to give you a more hands-on experience. You’ll find a script and an image folder linked here. Your task is simple: follow the script, insert the appropriate images, and apply the relevant Closeread effects to bring the story to life—just like in the completed version here.

This practical exercise is designed to help you reinforce everything you’ve just learned and give you the space to experiment further with Closeread’s effects and features. Once you’re done, feel free to share your completed project with your network on social media—and don’t forget to tag me. I’d love to see what you come up with!

---

This project is also available on GitHub.