2) Introduction

I would like to use this module to give you an introduction to the main components of the Closeread framework. The goal is to help you understand the anatomy of a basic Closeread document.

Closeread Components

Because Closeread is a quarto extension, the type of file we need to work with is, surprise-surprise, a quarto document or qmd file for short. For instance, say we have a document.qmd file with a few lines of text, as shown in the figure below.

Figure 2.1: Quarto document and its rendered HTML document

When the output format is html, rendering this file gives you an output in the form of an HTML document (as in the right hand side of the above figure). There is nothing particularly special about this output. As you can tell there is the title, followed by three paragraphs, followed by a numbered list with three items.

Now, what if we are interested in turning the current document into a scrollytelling story, albeit a very short and simple one?

To make document.qmd into a Closeread document, we need to make some changes, namely:

Change the format output in the yaml header to closeread-html.
```
---
title: Hello Closeread
format: closeread-html
---
```

Specify what part of the content will constitute a Closeread section, using a fenced div and a cr-section class, which will have the following appearance:
```
::::{.cr-section} 
  <content>
::::
```

Indicate what elements (e.g. text, images, code) will become the sticky item (i.e. the component that will get stuck as we scroll through the page). You do this by wrapping the element(s) in a fenced div and provide an identifier that is prefixed with cr-, for example:
```
:::{#cr-photo}
![](path-to-photo.jpg)
:::
```

Include a trigger among the narrative to cause the sticky to appear. The way you do this is by using Quarto’s cross-referencing syntax: @cr-sticky.
```
Narrative with trigger @cr-sticky
```

Here’s an example of what document.qmd would look like if we adapt its content with the necessary building blocks of a Closeread document. Notice the colored text associated with the four components listed above.

Let’s disect all the main components one by one.

YAML header format

The first thing to notice involves the yaml header. To be more precise, the specified format of the qmd document must be declared as closeread-html. As you would expect, this is what allows quarto to render the qmd file as a special type of HTML document using the Closeread scrollytelling framework.

Closeread Section

The next thing to notice is the closeread section. Simply put, a cr-section is what Closeread uses to do its magic. Think of this section as setting the boundaries for the content (e.g. text, code, images) that Closeread will take care of.

As you can tell, a closeread section, or cr-section for short, is started with an opening div, in this example ::::{.cr-section}, and is finished with a closing div of ::::

By the way, when defining a section you can also use three consecutive colons ::: instead of four. But because there will be other parts of a closeread section that employ other fenced elements, I prefer using :::: to specify the sections.

Every section needs a name, for instance: {.cr-section1} or {.cr-my-section} or {.cr-introduction}. The important thing is the use of { }, the prefix .cr- and the individual (and unique) name of the section.

Sticky Element

Inside a section you define one or more sticky components, or stickies in Closeread parlance. They also need to be surrounded by a fenced div of ::: and a label or name such as {#cr-sticky} or {#cr-components} like in our working example.

A sticky, as the name indicates, is the element (e.g. text, code, image) that will get stuck as you scroll through the HTML document.

Important

Do not confuse the syntax for naming a cr-section with the syntax for naming a sticky.

This is the syntax of a section: {.cr-section}
This is the syntax of a sticky: {#cr-sticky}

Trigger

The next major component is a trigger. This type of component is part of the narrative and it is defined with the syntax @cr-sticky. In other words, a trigger refers to a sticky by pre-appending @ to the name of the sticky. Note that the trigger is not wrapped inside curly braces.

What is the role of a trigger? A trigger is what Closeread uses to decide what to do with a sticky. In this example, as you scroll through the HTML document, the sticky component will appear the moment you hit the text of the trigger. In turn, the sticky will remain stuck until you reach the end of the HTML document or until another trigger calls a different sticky element.

To summarize, here’s a figure highlighting all the components discussed so far:

When we render document.qmd, an HTML document will be created with the following appearance (see figure below). As you can tell, the background is split into what it seems to be two different areas: white background at the top and at the bottom, and gray background in the middle.

The text that is not part of the section, such as the title and the first paragraph, will appear at the top in the white background region.

The area with a gray background is actually formed of two parts which are impossible distinguish with the naked eye. What we are able to distinguish, though, is some text on the left, and some text on the right.

The lines of text on the left hand side are the narrative elements. In turn, the area on the right hand side is the area for the sticky components. Recall that both the narrative and the sticky are part of the section. As you scroll down the document, the moment you hit the trigger, the sticky will appear on the screen.