diff --git a/README.md b/README.md index 15e2efa..5cfd7a0 100644 --- a/README.md +++ b/README.md @@ -1,11 +1,11 @@ -# closeread +# Closeread -closeread is a Quarto custom format that enables scrollytelling. You can add this extension using: +Closeread is a Quarto custom format that enables scrollytelling. You can add this extension using: ```bash quarto add qmd-lab/closeread ``` -Please see the documentation page linked in the About section in the right sidebar for guidance on how to use it. +The best way to learn to use Closeread is with the [Closeread documentation](https://closeread.dev). This extension is under active development. Please check back regularly for extended functionality and documentation. \ No newline at end of file diff --git a/_extensions/closeread/closeread.css b/_extensions/closeread/closeread.css index e88a3e4..d2dc5f4 100644 --- a/_extensions/closeread/closeread.css +++ b/_extensions/closeread/closeread.css @@ -50,6 +50,9 @@ font-family: var(--cr-poem-font-family); transition: transform 0.8s ease-in-out, font-size 0.8s ease-in-out; } +.cr-section .sticky-col .sticky-col-stack div.sourceCode { + background-color: rgb(233, 236, 239); +} .cr-section .sticky-col .sticky-col-stack .cr-active { opacity: 1; } diff --git a/_extensions/closeread/closeread.css.map b/_extensions/closeread/closeread.css.map index c73ee14..927b89f 100644 --- a/_extensions/closeread/closeread.css.map +++ b/_extensions/closeread/closeread.css.map @@ -1 +1 @@ -{"version":3,"sourceRoot":"","sources":["closeread.scss"],"names":[],"mappings":"AACA;AAGA;AAEA;AAEA;AAAA;AAAA;AAAA;AAAA;AAMA;EACE;EACA;EACA;;AAEA;EACE;EAEA;EACA;;AAEA;EACE;EACA;;AAEA;EAEE;;AAIA;EACE;;AAOR;EACE;;AAIA;EACE;EACA;EACA;EACA;EACA;;AAEA;EACE;EACA;EAGA;EAEA,YACE;;AAMJ;EACE;EACA,YACE;;AAGJ;EACE;EACA,YACE;;AAKJ;EACE;;AAIA;EACE;EAEA,YACE;;AAGF;EACE;EAEA,YACA;;AAMJ;EACE;EAEA;;AAGA;EACE;EAEA;;AAIF;EACE;EAEA;;;AASZ;AACA;EACE;AAAA;AAAA;AAAA;AAAA;IAKE;;EAEA;AAAA;AAAA;AAAA;AAAA;IACE;IACA;IACA;IACA;;EAEA;AAAA;AAAA;AAAA;AAAA;IACE;IACA;IACA;IACA;;EAIJ;AAAA;AAAA;AAAA;AAAA;IACE;;;AAQN;AAAA;AAAA;EAGE;;AAEA;AAAA;AAAA;EACE;EACA;EACA;EACA;EACA;;AAEA;AAAA;AAAA;EACE;EACA;EACA;;AAIJ;AAAA;AAAA;EACE;;;AAMF;EACE;EACA;;;AAIF;EACE;;;AAIF;EACE;EACA;;;AAMJ;EACE;;AAEA;EACE;EACA;EACA;;AAEA;EACE;EACA;;AAIJ;EACE;;;AAGJ;EACE;;AAEA;EACE;EACA;EACA;;AAEA;EACE;EACA;;AAIJ;EACE;;;AAKJ;AAAA;AAAA;AAAA;AAAA;EAKE;;AAEA;AAAA;AAAA;AAAA;AAAA;EACE;EACA;EACA;EACA;EACA;;AAGF;AAAA;AAAA;AAAA;AAAA;EACE;;;AAIJ;AAKE;EACE;EACA;;AAIF;EACE;;AAKA;EACE;EACA;EACA;;AAEA;EACE;;;AAOR;AAII;EACE;EACA;;AAEA;EACE;;;AAOR;AAEA;EACE;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA","file":"closeread.css"} \ No newline at end of file +{"version":3,"sourceRoot":"","sources":["closeread.scss"],"names":[],"mappings":"AACA;AAGA;AAEA;AAEA;AAAA;AAAA;AAAA;AAAA;AAMA;EACE;EACA;EACA;;AAEA;EACE;EAEA;EACA;;AAEA;EACE;EACA;;AAEA;EAEE;;AAIA;EACE;;AAOR;EACE;;AAIA;EACE;EACA;EACA;EACA;EACA;;AAEA;EACE;EACA;EAGA;EAEA,YACE;;AAMJ;EACE;EACA,YACE;;AAGJ;EACE;EACA,YACE;;AAKJ;EACE;;AAIA;EACE;EAEA,YACE;;AAGF;EACE;EAEA,YACA;;AAMJ;EACE;EAEA;;AAGA;EACE;EAEA;;AAIF;EACE;EAEA;;;AASZ;AACA;EACE;AAAA;AAAA;AAAA;AAAA;IAKE;;EAEA;AAAA;AAAA;AAAA;AAAA;IACE;IACA;IACA;IACA;;EAEA;AAAA;AAAA;AAAA;AAAA;IACE;IACA;IACA;IACA;;EAIJ;AAAA;AAAA;AAAA;AAAA;IACE;;;AAQN;AAAA;AAAA;EAGE;;AAEA;AAAA;AAAA;EACE;EACA;EACA;EACA;EACA;;AAEA;AAAA;AAAA;EACE;EACA;EACA;;AAIJ;AAAA;AAAA;EACE;;;AAMF;EACE;EACA;;;AAIF;EACE;;;AAIF;EACE;EACA;;;AAMJ;EACE;;AAEA;EACE;EACA;EACA;;AAEA;EACE;EACA;;AAIJ;EACE;;;AAGJ;EACE;;AAEA;EACE;EACA;EACA;;AAEA;EACE;EACA;;AAIJ;EACE;;;AAKJ;AAAA;AAAA;AAAA;AAAA;EAKE;;AAEA;AAAA;AAAA;AAAA;AAAA;EACE;EACA;EACA;EACA;EACA;;AAGF;AAAA;AAAA;AAAA;AAAA;EACE;;;AAIJ;AAKE;EACE;EACA;;AAIF;EACE;;AAKA;EACE;EACA;EACA;;AAEA;EACE;;;AAOR;AAII;EACE;EACA;;AAEA;EACE;;;AAOR;AAEA;EACE;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA","file":"closeread.css"} diff --git a/_extensions/closeread/closeread.scss b/_extensions/closeread/closeread.scss index 5c22c63..5fd6c70 100644 --- a/_extensions/closeread/closeread.scss +++ b/_extensions/closeread/closeread.scss @@ -80,6 +80,10 @@ font-size .8s ease-in-out; } + div.sourceCode { + background-color: rgba(233, 236, 239, 1); + } + // show active stickies .cr-active { opacity: 1; diff --git a/docs/_quarto.yml b/docs/_quarto.yml index 6c88898..04546f1 100644 --- a/docs/_quarto.yml +++ b/docs/_quarto.yml @@ -4,7 +4,8 @@ project: - './copy_extension.sh' website: - title: "closeread" + title: "Closeread" + page-navigation: true navbar: left: - href: index.qmd @@ -39,7 +40,8 @@ website: - guide/components.qmd - guide/focus-effects.qmd - guide/layouts.qmd - - guide/authoring-tools.qmd + - guide/interactive-graphics.qmd + - guide/styling.qmd page-footer: background: light diff --git a/docs/gallery/demos/ojs-variables/index.qmd b/docs/gallery/demos/ojs-variables/index.qmd index 0c40a08..6227c95 100644 --- a/docs/gallery/demos/ojs-variables/index.qmd +++ b/docs/gallery/demos/ojs-variables/index.qmd @@ -121,16 +121,15 @@ md`(derived) Angle 2: ${angle2.toFixed(1)}°` ``` ::: -As you back and forth over this closeread section, note the values of the all six ojs variables that closeread makes available in ojs code cells: +As you back and forth over this closeread section, note the values of the OJS variables that closeread makes available in OJS code cells: -1. `crActiveSticky`: name of the active sticky -2. `crTriggerIndex`: index of the active trigger -3. `crTriggerProgress`: progress of the active trigger block from 0 to 1 -4. `crDirection`: either `"down"` or `"up"`, depending on the direction a user is scrolling -5. `crProgressBlock`: progress of the active spanning progress block from 0 to 1 - -To demonstrate the use of other ojs variables, we'll recreate the spinning behavior by a more creative mapping of `crTriggerIndex` and `crTriggerProgress` to form `angle2`. [This second globe demonstrates some interesting behavior: `angle2` was actually changing as a result of the two triggers used in making the first globe. ] +1. `crTriggerIndex` is a number representing the index of the currently visible trigger (starting from 0 and going down through the document). +2. `crTriggerProgress` is a number between 0 and 1 representing how far the currently active trigger has progressed through the visible window. +3. `crDirection` is either `"up"` or `"down"`, depending on the direction the user last scrolled. +4. `crActiveSticky` is the name of the currently visible sticky. +5. `crProgressBlock` is a number between 0 and 1 representing how far the currently active progress block has progressed through the visible window (more on progress blocks in [Authoring Tools](/guide/authoring-tools.qmd)). +To demonstrate the use of other OJS variables, we'll recreate the spinning behavior by a more creative mapping of `crTriggerIndex` and `crTriggerProgress` to form `angle2`. [This second globe demonstrates some interesting behavior: `angle2` was actually changing as a result of the two triggers used in making the first globe. ] ::::{.cr-section layout="overlay-center"} diff --git a/docs/guide/_metadata.yml b/docs/guide/_metadata.yml index bc6f610..ff270b2 100644 --- a/docs/guide/_metadata.yml +++ b/docs/guide/_metadata.yml @@ -1,3 +1,5 @@ format: html: - toc: true \ No newline at end of file + toc: true + grid: + body-width: 600px \ No newline at end of file diff --git a/docs/guide/authoring-tools.qmd b/docs/guide/authoring-tools.qmd deleted file mode 100644 index 8a55c98..0000000 --- a/docs/guide/authoring-tools.qmd +++ /dev/null @@ -1,5 +0,0 @@ ---- -title: Authoring Tools ---- - -Coming soon! \ No newline at end of file diff --git a/docs/guide/components.qmd b/docs/guide/components.qmd index c7175a2..f53ce27 100644 --- a/docs/guide/components.qmd +++ b/docs/guide/components.qmd @@ -1,16 +1,17 @@ --- -title: Closeread Components +title: Components of a Closeread Document +subtitle: "Learn the essential building blocks of Closeread: sections, stickies and triggers." --- -Every closeread document consists of three components: +Every Closeread document consists of three components: -1. A section of the document flagged as a closeread section. -2. Within the section, an element flagged to appear in the main column of the closeread section (the "sticky"), and also -3. An element (often a paragraph of text) that will serve to trigger the appearance of the sticky element. +1. A **section** of the document flagged as a Closeread section; +2. Within the section, a **"sticky"** element flagged to appear in the main column of the Closeread section; and +3. An element (often a paragraph of text) that will serve to **trigger** the appearance of the sticky element. -## Closeread Sections +## Sections -To create a closeread section within a document, open up a [fenced div](https://quarto.org/docs/authoring/markdown-basics.html#sec-divs-and-spans) and add the `cr-section` class. +To create a Closeread section within a document, open up a [fenced div](https://quarto.org/docs/authoring/markdown-basics.html#sec-divs-and-spans) and add the `cr-section` class. ```markdown :::{.cr-section} @@ -18,13 +19,16 @@ To create a closeread section within a document, open up a [fenced div](https:// ::: ``` -Elements within a `.cr-section` div will appear as a closeread story while elements outside of a section will appear as a normal Quarto HTML document. This allows you to integrate one or more closeread sections into a conventional HTML document. +Elements within a `.cr-section` div will appear as a Closeread story while elements outside of a section will appear as a normal Quarto HTML document. This allows you to integrate one or more Closeread sections into a conventional HTML document. + +By wrapping your entire document with a `cr-section` div, you can make a 100% Closeread document. By default, all elements with a Closeread section appear as the narrative, scrolling by, unless you've indicated that they should be a sticky. -By wrapping your entire document with a `cr-section` div, you can make a 100% closeread document. By default, all elements with a closeread section appear in the narrative column unless you've indicated that they should be a sticky. ## Stickies -An element of your document that you wish to do a close read of is called a "sticky": as the user scrolls, it will remained pinned in the middle of the main column like a sticky note. To flag an element as a sticky, wrap it in a fenced div and provide an identifier that is prefixed with `cr-`. +An element of your document that you wish to do a close read of is called a "sticky": as the user scrolls, it will remained pinned in the middle of the main column like a sticky note. + +To flag an element as a sticky, wrap it in a [fenced div](https://quarto.org/docs/authoring/markdown-basics.html#sec-divs-and-spans) and provide an identifier that is prefixed with `cr-`. ```markdown :::{#cr-myimage} @@ -41,11 +45,11 @@ hist(rnorm(15)) ``` ::: ```` -All sticky elements are placed in the main column of the closeread section and will be transparent. To make them appear, you need to create a trigger. +Sticky elements are placed in the main column of the Closeread section and will be transparent. To make them appear, you need to create a trigger. ## Triggers -Any elements within a closeread section that are not stickies - usually paragraphs - will be placed in the narrative column. You can set a paragraph to trigger focus on a particular sticky by using Quarto's cross-referencing syntax: `@cr-mysticky`. +Any elements within a Closeread section that are not stickies - usually paragraphs - will be placed in the narrative column. You can set a paragraph to trigger focus on a particular sticky by using Quarto's cross-referencing syntax: `@cr-mysticky`. ````markdown When this paragraph scrolls into view it will reveal a histogram. @cr-myplot @@ -75,7 +79,4 @@ hist(rnorm(15)) ::: ```` -The primary role of triggers is to make a sticky element appear. They can also be used to trigger focus effects by attaching additional attributes to your triggers. Learn more in [Focus Effects](focus-effects.qmd). - - - +The primary role of triggers is to make a sticky element appear. They can also be used to trigger focus effects by attaching additional attributes to your triggers. Learn more in [Focus effects](focus-effects.qmd). diff --git a/docs/guide/focus-effects.qmd b/docs/guide/focus-effects.qmd index 9702e61..dc7d3c6 100644 --- a/docs/guide/focus-effects.qmd +++ b/docs/guide/focus-effects.qmd @@ -1,12 +1,46 @@ --- title: Focus Effects +subtitle: Guide your readers' attention to aspects of your stickies. --- -Focus effects are used to closely guide your readers attention to particular aspects of your stickies. They are all supplied as [attributes](https://quarto.org/docs/authoring/markdown-basics.html#ordering-of-attributes), which follow a `attribute="value"` syntax where the value must be quoted and where `=` separates the value from the attribute with no spaces. +Focus effects are all supplied as [attributes on an inline span](https://quarto.org/docs/authoring/markdown-basics.html#ordering-of-attributes) that is attached to a trigger. Like all Quarto inline spans, they follow a `attribute="value"` syntax: the value must be quoted and `=` separates the value from the attribute with no spaces. -All of these effects will remain on the sticky until there is a new trigger block scrolls into the viewport. You can "reset" the effects on a given sticky by following the focus effect trigger with a trigger without any focus effects. +```markdown +Here's a trigger with no focus effect @cr-content -# Types of Focus Effects +Here's a trigger with a focus effect [@cr-mycontent]{effect="value"} +``` + +All of these effects will remain on the sticky until a new trigger block scrolls into the viewport. You can "reset" the effects on a given sticky by following the focus effect trigger with a trigger without any focus effects. + +# Types of focus effects + +## Scaling + +You can scale a sticky element up or down by using the `scale-by()` attribute and providing a numerical scaling factor. For example: + +- `scale-by=".5"`: shrinks a sticky to 50% its original size +- `scale-by="3"`: triples the size of a sticky. + +`scale-by` accepts a string that corresponds to any of the options in the analogous [`scale()`](https://developer.mozilla.org/en-US/docs/Web/CSS/transform-function/scale) CSS function. + +## Panning + +You can pan across any sticky element (often an image) by using the `pan-to` attribute. It supports several different units: + +- `pan-to="25%,-50%"`: pan the sticky 25% of its width to the right and 50% of its height up. +- `pan-to="-30px, 30px"`: pan the sticky 30 pixels to the left and 30 pixels down. + +`pan-to` accepts a string that corresponds to any of the options in the analogous [`translate()`](https://developer.mozilla.org/en-US/docs/Web/CSS/transform-function/translate) CSS function. + +## Zooming + +When your sticky is a code block or line, you can combine panning and scaling to focus the view on a line number or named span. + +1. `zoom-to="3"`: zoom to line 3 +2. `zoom-to="cr-span1"`: zoom to the line with the span with id `cr-span1` + +Zooming currently only supports a single line or span. When you trigger a zoom to a line, it will zoom such that the line occupies most of the horizontal space in the viewport and is roughly centered vertically. ## Highlighting {#highlighting} @@ -17,9 +51,9 @@ You can highlight parts of the code and text of your sticky using the following 3. `highlight="cr-span1"`: highlight the span with id `cr-span1` 4. `highlight="cr-span1,cr-span2"`: highlight the spans with ids `cr-span1` and `cr-span2` -Line highlighting (1 and 2) works on code cells and line blocks while span highlighting (3 and 4) only works on Line Blocks. +Line highlighting (1 and 2) works on code cells and line blocks while span highlighting (3 and 4) only works on line blocks. -### Code Cell Examples +### Code cell examples This will highlight lines 1 and 2: @@ -57,8 +91,7 @@ penguins |> Highlighting spans of code within a line is currently not possible. - -### Line Block Examples +### Line block examples This will highlight lines 3 and 4. @@ -86,55 +119,26 @@ The end of the first two lines of a Limerick must rhyme. [@cr-limerick]{highligh | to a seat in the uppermost gallery. ```` -Note that closeread extends the native pandoc processing of line blocks. Instead of wrapping line blocks in a fenced divs and providing and id and classes there, you can provide them on the first line of the line block in curly braces as demonstrated above. The functionality is identical; the goal of the feature is to simplify the syntax. +Note that Closeread extends the native Pandoc processing of line blocks. Instead of wrapping line blocks in a fenced divs and providing and id and classes there, you can provide them on the first line of the line block in curly braces as demonstrated above. The functionality is identical; the goal of the feature is to simplify the syntax. - -## Zooming - -You can zoom to parts of the code and text of your sticky using the following syntax. - -1. `zoom-to="3"`: zoom to line 3 -2. `zoom-to="cr-span1"`: zoom to the line with the span with id `cr-span1` - -Zooming works for both code blocks and line blocks but currently only supports a single line or span. When you trigger a zoom to a line, it will zoom such that the line occupies most of the horizontal space in the viewport and is roughly centered vertically. - - -## Panning - -You can pan across any sticky element (often an image) by using the `pan-to` attribute. It supports several different units: - -- `pan-to="25%,-50%: pan the sticky 25% of its width to the right and 50% of its height up. -- `pan-to="-30px, 30px": pan the sticky 30 pixels to the left and 30 pixels down. - -`pan-to` accepts a string that corresponds to any of the options in the analogous [`translate()`](https://developer.mozilla.org/en-US/docs/Web/CSS/transform-function/translate) CSS function. - -## Scaling - -You can scale a sticky element up or down by using the `scale-by()` attribute and providing a numerical scaling factor. For example: - -- `scale-by=".5"`: shrinks a sticky to 50% its original size -- `scale-by="3"`: triples the size of a sticky. - -`scale-by` accepts a string that corresponds to any of the options in the analogous [`scale()`](https://developer.mozilla.org/en-US/docs/Web/CSS/transform-function/scale) CSS function. - -# Combining Focus Effects +# Combining focus effects You can combine multiple focus effects on a single trigger. For example: -- `[@cr-sticky]{pan-to="50%,50%" scale-by="1.5"}`: pan the sticky down and to the right why increasing its size by 50%. +- `[@cr-sticky]{pan-to="50%,50%" scale-by="1.5"}`: pan the sticky down and to the right while increasing its size by 50%. One exception is the `zoom-to` attribute. Since it performs both panning and zooming, it will override those options if they're included on the same trigger. -## Highlight - Zoom +## Highlight and zoom -It is common if want to zoom into a line or span of code or text while also highlighting. There is an additional attribute called `hlz` for this purpose. +It is common to want to zoom into a line or span of code or text while also highlighting. There is an additional attribute called `hlz` for this purpose. -- `hlz="cr-love": highlight the span `cr-love` while zooming in on the line that contains it. +- `hlz="cr-love"`: highlight the span `cr-love` while zooming in on the line that contains it. - `hlz="4"`: highlight line 4 while zooming in on the line that contains it. -Because this focus effect translates into `highlight` and `zoom-to`, the latter constrains it to only working for single spans or lines at the moment. +Because this focus effect translates into `highlight` and `zoom-to`, the latter constrains it to only work for single spans or lines at the moment. -# Other Features +# Other features You can scale a sticky to fill the viewport without distortion or cropping by adding the `scale-to-fill` class. For example: @@ -150,3 +154,5 @@ This is the first limerick ever recorded. @cr-limerick ```` When this sticky is triggered, it will fade in and transform such that it fills the viewport. This class can be applied to a wide range of sticky types. + +Once you've used these tools to write your story, you might want to turn your attention to the [Layout](layout.qmd) of your document. diff --git a/docs/guide/index.qmd b/docs/guide/index.qmd index 390253a..66acfb1 100644 --- a/docs/guide/index.qmd +++ b/docs/guide/index.qmd @@ -1,10 +1,46 @@ --- title: Guide -toc: true +subtitle: Start with the basics of a Closeread document, then learn to master more advanced techniques. --- -Closeread is a Quarto extension that allows you to author scrollytelling HTML documents. To learn how to create your first closeread document, start off by reading about the [Components of a Closeread Document](components.qmd). +If you've never made a Closeread document, copy and paste the following document into a qmd document. + +```{.markdown filename="myfirstcr.qmd"} +--- +title: My First Closeread +format: closeread-html +--- + +Hello World! Please read my closeread story below. + +:::{.cr-section} + +Closeread enables scrollytelling. + +Draw your readers attention with focus effects. @cr-features + +:::{#cr-features} +1. Highlighting +2. Zooming +3. Panning +::: + +::: + +``` + +In the same directory as this qmd file, run the following command to make the Closeread extension available to this document. + +```bash +quarto add qmd-lab/closeread +``` + +Now you can render the document and scroll through your first scrollytelling story. Continue the adventure by reading about the [Components of a Closeread Document](components.qmd). + +When you've finished the Guide, be sure to have a look at the [Gallery](/gallery) for more examples of what you can do with Closeread! * * * -This is an open-source tool built upon other open-source tools. Closeread extends [Quarto](https://github.com/quarto-dev/quarto-cli), a tool for technical publishing sponsored by Posit, PBC. The responsivity to user scrolling is made possible by the [scrollama v3.0](https://github.com/russellsamora/scrollama) javascript library by Russell Samora. Both tools are open-source and distributed under an MIT License. +:::{.text-muted .small} +This is an open-source tool built upon other open-source tools. Closeread extends [Quarto](https://github.com/quarto-dev/quarto-cli), a tool for technical publishing sponsored by Posit, PBC. The responsivity to user scrolling is made possible by the [scrollama v3.0](https://github.com/russellsamora/scrollama) JavaScript library by Russell Samora. Both tools are open-source and distributed under an MIT License. +::: \ No newline at end of file diff --git a/docs/guide/interactive-graphics.qmd b/docs/guide/interactive-graphics.qmd new file mode 100644 index 0000000..7af4537 --- /dev/null +++ b/docs/guide/interactive-graphics.qmd @@ -0,0 +1,42 @@ +--- +title: Interactive Graphics +subtitle: Create graphics that animate as your reader scrolls. +--- + +## Observable JavaScript in Closeread + +Quarto lets you use [Observable JavaScript](https://quarto.org/docs/computations/ojs.html) (OJS) in your documents. Unlike R, Python and Julia, OJS runs continuously as your readers read the document, allowing your documents to react to things they do. + +Closeread makes the following variables available to your OJS code: + +- `crTriggerIndex` is a number representing the index of the currently visible trigger (starting from 0 and going down through the document). +- `crTriggerProgress` is a number between 0 and 1 representing how far the currently active trigger has progressed through the visible window. +- `crDirection` is either `"up"` or `"down"`, depending on the direction the user last scrolled. +- `crActiveSticky` is the name of the currently visible sticky. +- `crProgressBlock` is a number between 0 and 1 representing how far the currently active progress block has progressed through the visible window. (More on progress blocks [below](#progress-blocks)) + +Because OJS is naturally reactive, any code that references these variables will continuously re-run as the reader scrolls. See the [OJS variables demo](/gallery/demos/ojs-variables) for an example of how to use these to make graphics that animate as the reader scrolls. + +### Progress blocks {#progress-blocks} + +If you want to animate a graphic across several triggers, you could manually work out arithmetic that uses both the trigger index and progress. But, due to the way our underlying libraries report progress, this can occasionally lead to hiccups - and the maths can be a little frustrating! + +Progress blocks alleviate this pain by letting you group several triggers and tracking the progress of the group as a whole. + +Using them is as easy as wrapping a series of triggers in a [fenced div](https://quarto.org/docs/authoring/markdown-basics.html#sec-divs-and-spans) and adding the `progress-block` class: + +````html +::::{.cr-section} + +:::{.progress-block} +Check out our graphic @cr-graphic + +We can keep referring to it as several triggers scroll by... @cr-graphic + +... and have OJS code elsewhere in the document to animate it @cr-graphic +::: + +:::: +```` + +Finally, you might want to [style](styling.qmd) your documents to look the way your want. diff --git a/docs/guide/layouts.qmd b/docs/guide/layouts.qmd index 1688e1c..6ce668b 100644 --- a/docs/guide/layouts.qmd +++ b/docs/guide/layouts.qmd @@ -1,8 +1,9 @@ --- title: Layouts +subtitle: Decide where your triggers and stickies lie on the page. --- -The relative positioning of the narrative column and the sticky column determine the *layout*. You can set the layout of a section using the `layout` attribute on the block that defines the section. +The relative positioning of the triggers and the stickies determine the *layout*. You can set the layout of a section using the `layout` attribute on the block that defines the section. ```markdown :::{.cr-section layout="overlay-center"} @@ -10,7 +11,7 @@ The relative positioning of the narrative column and the sticky column determine ::: ``` -## Layout Options +## Layout options Options for `layout` include: @@ -22,9 +23,9 @@ Options for `layout` include: In the overlay layouts, the sticky column occupies the entire screen width and the narrative column scrolls over it. All layouts will automatically revert to `overlay-center` when viewed on a mobile device. -Documents containing multiple closeread sections can use the same layouts or different ones. As an alternative to specifying the layout on the section block, it can also be defined in the document yaml under the `cr-section` key. +Documents containing multiple Closeread sections can use the same layouts or different ones. As an alternative to specifying the layout on the section block, it can also be defined in the document yaml under the `cr-section` key. -```yml +```yaml --- format: closeread-html: @@ -34,18 +35,28 @@ format: ``` If a layout is specified in the document yaml, it will be propagated to all sections in the document. If a section has its own layout specified, that will override the document yaml similar to how code cell execution options work. -## Presentation Mode +## Presentation mode -Closeread documents place special emphasis on the "stickies": the text, images, or code found in the main column that is described in the narrative. This +Closeread documents place special emphasis on the "stickies": the text, images, or code found in the main column that is described in the narrative. -While viewing any closeread document in a browser, you can press `p` on the keyboard to view it in presentation mode. Presentation mode is identical to the `overlay-center` layout except the narrative column is made transparent. You can return to the original layout by pressing `p` again. You can advance to the next trigger using the forward-arrow key and return to the previous trigger using the back-arrow key. +While viewing any Closeread document in a browser, you can press `p` on the keyboard to view it in presentation mode. Presentation mode is identical to the `overlay-center` layout except the narrative column is made transparent. You can return to the original layout by pressing `p` again. You can advance to the next trigger using the forward-arrow key and return to the previous trigger using the back-arrow key. -## Removing Header Space +## Removing header space {#removeheaderspace} -By default, top of any Quarto HTML document, including `closeread-html` will reserve space at the top o the document for the title block. To remove this, you can use the `remove-header-space` option in the document header. +By default, the top of any Quarto HTML document, including `closeread-html`, will reserve space at the top of the document for the title block. To remove this, you can use the `remove-header-space` option in the document header[^1]. ```yaml +--- format: closeread-html: remove-header-space: true +--- ``` + + +[^1]: If you use `remove-header-space`, you might want to add a title of your own! Be aware that the option will also hide other document metadata that is normally printed in the title block. + + +Removing the header space is often a good choice if your entire document is one large Closeread section. If that is the case, you may also want to consider [disabling the Quarto sidebar](https://quarto.org/docs/websites/website-navigation.html#hiding-navigation). + +One of the unique characteristics of a scrollytelling Quarto doc is it allows you to link the animation of a graphic with the scrolling of the user. Read on to learn how to include [interactive graphics](interactive-graphics.qmd)! diff --git a/docs/guide/styling.qmd b/docs/guide/styling.qmd new file mode 100644 index 0000000..efb7325 --- /dev/null +++ b/docs/guide/styling.qmd @@ -0,0 +1,65 @@ +--- +title: Styling +subtitle: Change the way your Closeread documents look. +--- + +Closeread documents will generally follow the [Quarto theme](https://quarto.org/docs/output-formats/html-themes.html) you use. However, you'll likely want to customise the appearance of your Closeread sections. + +# Document frontmatter + +The `cr-style` key provides a number of options for quickly customising your Closeread document. Put them under `format.closeread-html.cr-style`. For example: + +````yaml +--- +title: My document +format: + closeread-html: + cr-style: + narrative-background-color-overlay: darkslategrey + narrative-text-color-overlay: "#e2e2e2" +--- +```` + +Options include: + +- `narrative-background-color-overlay`: the background colour used for narrative text blocks in sidebar layouts +- `narrative-text-color-overlay`: the colour of narrative text in overlay layouts +- `narrative-background-color-sidebar`: the background colour used for the narrative column in sidebar layouts +- `narrative-text-color-sidebar`: the colour of narrative text in sidebar layouts +- `narrative-border-radius`: the border radius of narrative text blocks in overlay layouts +- `narrative-overlay-max-width`: the maximum width of narrative text blocks in overlay layouts +- `narrative-overlay-min-width`: the minimum width of narrative text blocks in overlay layouts + * It's generally best to leave this one alone: setting it can cause mobile layout issues. +- `narrative-outer-margin`: the margin pushing narrative content in from the left (on `overlay-left` layouts) or right edge (on `overlay-right`) +- `narrative-font-family`: the font(s) used for narrative content +- `narrative-font-size`: the font size used for narrative content +- `poem-font-family`: the font(s) used for lineblock poems +- `section-background-color`: the background colour used for Closeread sections +- `narrative-sidebar-width`: the width of the sidebar. Defaults to `1fr`: the sticky content is `2fr` in sidebar layouts, dividing the page 1:2 by default. You can adjust this ratio with a different `fr` value, a fixed value, or a combination of the two using [`minmax()`](https://developer.mozilla.org/en-US/docs/Web/CSS/minmax). + +# (S)CSS customisation + +Users familiar with CSS or SCSS can add a stylesheet to more heavily customise the appearance of Closeread sections. + +Closeread divides the content of sections into two columns: + +1. A `.narrative-col` contains triggers and other non-sticky content; and +2. A `.sticky-col` contains the stickies, stacked on top of each other in a `.sticky-col-stack` + +The hierarchy of elements is as follows. + +```markdown +.cr-section +├ .narrative-col # all non-stickies go in this column +│ ╰ .trigger # wraps each trigger block w/ vert padding +│ ╰ .narrative # visible trigger content +╰ .sticky-col + ╰ .sticky-col-stack # stickies go here + ╰ .sticky # wraps each individual sticky +``` + +You'll most likely want to target the following elements: + +- `.cr-section` if you want to add a background colour to the entire section +- `.narrative-col` if you want to add a background colour to the column containing the triggers (especially in a sidebar layout), or change its width +- `.narrative` to change the appearance of triggers, including their background colour, border radius (for curved or not curved boxes), text colour or font diff --git a/docs/index.qmd b/docs/index.qmd index f5125ec..b29a59e 100644 --- a/docs/index.qmd +++ b/docs/index.qmd @@ -1,5 +1,6 @@ --- title: "Closeread" +subtitle: "Closeread is a custom format for [Quarto](https://quarto.org/) that enables scrollytelling features for HTML documents." format: closeread-html: theme: cosmo @@ -11,6 +12,10 @@ format: narrative-text-color-overlay: "var(\\-\\-bs-light)" --- +[New to Quarto? Get started by working through the [Quarto tutorials](https://quarto.org/docs/get-started/).]{.column-margin} + +## Getting started {#gettingstarted} + ```{=html} ``` -closeread is a custom format for [Quarto](https://quarto.org/) that enables scrollytelling features for html documents. +Closeread is a custom format for [Quarto](https://quarto.org/) that enables scrollytelling features for html documents. Install the extension by running the following command in the directory you wish to use it: @@ -45,11 +50,11 @@ format: closeread-html ::::{.cr-section layout="overlay-center" style="font-size: 1.5em;"} -Get your first closeread doc up and running in four steps. @cr-doc +Get your first Closeread doc up and running in four steps. @cr-doc Step one: create a qmd file and set the format to closeread-html. [@cr-doc]{highlight="3"} -Step two: open up a closeread section. [@cr-doc]{highlight="8-20"} +Step two: open up a Closeread section. [@cr-doc]{highlight="8-20"} Step three: flag an element to become a sticky. [@cr-doc]{highlight="14-18"} @@ -58,7 +63,10 @@ Step four: create a trigger to make the sticky appear. [@cr-doc]{highlight="12"} :::{style="height: 40dvh; visibility: hidden"} ::: +Triggers, like this text, scroll past while the stickies stay "stuck" on the page. [@cr-doc]{highlight=""} + :::{#cr-doc filename="myfirstcr.qmd" .scale-to-fill} + ````markdown --- title: My First Closeread @@ -89,4 +97,31 @@ Draw your readers attention with: @cr-features \ \ -For guidance on how to author closeread documents, read the [Guide](guide/index.qmd). For examples of closeread documents alongside their source, see the [Gallery](gallery/index.qmd). For a catalog of the syntax and yaml options used in the closeread extension, see the [Reference](reference/index.qmd). +## What's next? + +For guidance on how to author Closeread documents, read the [Guide](guide/index.qmd), starting with [Components of a Closeread document](guide/components.qmd). These components are the essential building blocks of scrollytelling with Closeread. Follow the rest of the Guide for ways to add more advanced effects. + +### Publishing + +When you're ready to let the world (or just a few people) see your work, check out the [Quarto publishing section](https://quarto.org/docs/publishing/) of the Guide. Closeread documents follow the same publishing rules as other Quarto documents, so if you've worked with Quarto before, you're already already to go! Likewise, if you've published other static web pages before, you can take the files created by `quarto render` and put them anywhere on the web. + +### Gallery and Reference + +Need some inspiration? For examples of Closeread documents alongside their source, consult the [Gallery](gallery/index.qmd) to see how we made them. The Gallery also has examples that highlight particular features of Closeread. + +If you can't remember a particular option that Closeread uses, see the [Reference](reference/index.qmd). + +### Community + +Need help, or looking for others to connect with around Closeread? Come join us on the [discussion board](https://github.com/qmd-lab/closeread/discussions) or [file an issue](https://github.com/qmd-lab/closeread/issues). + +:::{.callout-note collapse="true"} +You can also install the development version of Closeread. It updates frequently and may break. + +```bash +quarto add qmd-lab/closeread@dev +``` +::: + +For guidance on how to author Closeread documents, read the [Guide](guide/index.qmd). For examples of Closeread documents alongside their source, see the [Gallery](gallery/index.qmd). For a catalog of the syntax and yaml options used in the Closeread extension, see the [Reference](reference/index.qmd). + diff --git a/docs/reference/index.qmd b/docs/reference/index.qmd index e4a2558..348e507 100644 --- a/docs/reference/index.qmd +++ b/docs/reference/index.qmd @@ -45,7 +45,7 @@ Identifiers start with `#`; classes start with `.`, and attributes have a key / ### Section Options -A closeread section is a div with the class `cr-section` that contains stickies and triggers. +A Closeread section is a div with the class `cr-section` that contains stickies and triggers. ::: {#section-options} ::: @@ -66,7 +66,7 @@ A trigger block is a div with the `focus-on` attribute to trigger effects on a p ## Keyboard Hotkeys -While viewing a closeread document in a browser, you can press certain hotkeys to toggle features. +While viewing a Closeread document in a browser, you can press certain hotkeys to toggle features. | Hotkey | Effect | |---------------------------|----------------------------|