From ad665bcc8d90d2243bc3de387131ea88c36b47d7 Mon Sep 17 00:00:00 2001 From: James Goldie Date: Thu, 24 Oct 2024 08:31:00 +1100 Subject: [PATCH 01/28] Capitalise Closeread in plain text --- README.md | 6 +++--- docs/_quarto.yml | 2 +- docs/guide/components.qmd | 16 ++++++++-------- docs/guide/focus-effects.qmd | 2 +- docs/guide/index.qmd | 2 +- docs/guide/layouts.qmd | 4 ++-- docs/index.qmd | 6 +++--- docs/reference/index.qmd | 4 ++-- 8 files changed, 21 insertions(+), 21 deletions(-) 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/docs/_quarto.yml b/docs/_quarto.yml index 6c88898..52f4ed8 100644 --- a/docs/_quarto.yml +++ b/docs/_quarto.yml @@ -4,7 +4,7 @@ project: - './copy_extension.sh' website: - title: "closeread" + title: "Closeread" navbar: left: - href: index.qmd diff --git a/docs/guide/components.qmd b/docs/guide/components.qmd index c7175a2..9904903 100644 --- a/docs/guide/components.qmd +++ b/docs/guide/components.qmd @@ -2,15 +2,15 @@ title: Closeread Components --- -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 +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. ## Closeread 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,9 +18,9 @@ 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 in the narrative column 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 @@ -41,11 +41,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. +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. ## 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 diff --git a/docs/guide/focus-effects.qmd b/docs/guide/focus-effects.qmd index 9702e61..21710e3 100644 --- a/docs/guide/focus-effects.qmd +++ b/docs/guide/focus-effects.qmd @@ -86,7 +86,7 @@ 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 diff --git a/docs/guide/index.qmd b/docs/guide/index.qmd index 390253a..abfbfcc 100644 --- a/docs/guide/index.qmd +++ b/docs/guide/index.qmd @@ -3,7 +3,7 @@ title: Guide toc: true --- -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). +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). * * * diff --git a/docs/guide/layouts.qmd b/docs/guide/layouts.qmd index 1688e1c..73d0e96 100644 --- a/docs/guide/layouts.qmd +++ b/docs/guide/layouts.qmd @@ -22,7 +22,7 @@ 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 --- @@ -38,7 +38,7 @@ If a layout is specified in the document yaml, it will be propagated to all sect 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 -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 diff --git a/docs/index.qmd b/docs/index.qmd index 9da9849..66f6a45 100644 --- a/docs/index.qmd +++ b/docs/index.qmd @@ -6,7 +6,7 @@ format: css: index-styles.css --- -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: @@ -28,11 +28,11 @@ format: closeread-html ::::{.cr-section layout="overlay-center" style="font-size: 1.5em; background-color: rgba(39, 128, 227, 0.2);"} -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"} 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 | |---------------------------|----------------------------| From 498d37b6ed4652ef58141c87dbad4646bd01ad77 Mon Sep 17 00:00:00 2001 From: James Goldie Date: Thu, 24 Oct 2024 08:51:57 +1100 Subject: [PATCH 02/28] Elaborate home page what's next section --- docs/index.qmd | 29 ++++++++++++++++++++++++++++- 1 file changed, 28 insertions(+), 1 deletion(-) diff --git a/docs/index.qmd b/docs/index.qmd index 66f6a45..f3c8a44 100644 --- a/docs/index.qmd +++ b/docs/index.qmd @@ -8,12 +8,24 @@ format: Closeread is a custom format for [Quarto](https://quarto.org/) that enables scrollytelling features for html documents. +Quarto first-timer? Get up and running with your first Closeread document. + +## Getting started {#gettingstarted} + Install the extension by running the following command in the directory you wish to use it: ```bash quarto add qmd-lab/closeread ``` +:::{.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 +``` +::: + With the extension installed, you can author documents using the `closeread-html` format: ```yaml @@ -71,5 +83,20 @@ 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). From d81955c5fe7eedfcd85bafdf47533f08f88deed0 Mon Sep 17 00:00:00 2001 From: James Goldie Date: Thu, 24 Oct 2024 09:31:13 +1100 Subject: [PATCH 03/28] Elaborate Guide index page --- docs/guide/index.qmd | 17 +++++++++++++++-- 1 file changed, 15 insertions(+), 2 deletions(-) diff --git a/docs/guide/index.qmd b/docs/guide/index.qmd index abfbfcc..6481334 100644 --- a/docs/guide/index.qmd +++ b/docs/guide/index.qmd @@ -1,10 +1,23 @@ --- title: Guide +subtitle: Start with the basics of a Closeread document, then learn to master more advanced techniques. toc: true --- -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, start with the very minimal example on the [home page](/), then come back here! + +[Components of a Closeread document](components.qmd) teaches you the essential parts of a Closeread document: sections, stickies and triggers. + +[Focus Effects](focus-effects.qmd) let you guide your readers to parts of your content by highlighting text and code, or zooming in on parts of an image or text. You can also ensure that content scales responsively, no matter what devices your readers use. + +[Layouts](layouts.qmd) teaches you how to customise the layouts of your Closeread sections - that is, where the stickies and triggers sit - as well as other useful tools that change the structure of the page. + +[Authoring tools](authoring-tools.qmd) covers other useful tools to help you generate scrollytelling content, including ways to use [Observable JavaScript](https://quarto.org/docs/computations/ojs.html) to make animated graphics with Closeread. + +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 From 1162dcaaec142fc77d18597221ebca4b1853acbf Mon Sep 17 00:00:00 2001 From: James Goldie Date: Thu, 24 Oct 2024 09:31:31 +1100 Subject: [PATCH 04/28] Move home page lead to subtitle --- docs/index.qmd | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/index.qmd b/docs/index.qmd index f3c8a44..9aa4073 100644 --- a/docs/index.qmd +++ b/docs/index.qmd @@ -1,13 +1,12 @@ --- 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 css: index-styles.css --- -Closeread is a custom format for [Quarto](https://quarto.org/) that enables scrollytelling features for html documents. - Quarto first-timer? Get up and running with your first Closeread document. ## Getting started {#gettingstarted} From a0fc1ea721664d427acdb7d675f23150b14068d0 Mon Sep 17 00:00:00 2001 From: James Goldie Date: Thu, 24 Oct 2024 09:31:37 +1100 Subject: [PATCH 05/28] Add authoring tools page --- docs/gallery/demos/ojs-variables/index.qmd | 15 ++++----- docs/guide/authoring-tools.qmd | 39 +++++++++++++++++++++- 2 files changed, 45 insertions(+), 9 deletions(-) diff --git a/docs/gallery/demos/ojs-variables/index.qmd b/docs/gallery/demos/ojs-variables/index.qmd index 7316500..b132b3c 100644 --- a/docs/gallery/demos/ojs-variables/index.qmd +++ b/docs/gallery/demos/ojs-variables/index.qmd @@ -116,16 +116,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/authoring-tools.qmd b/docs/guide/authoring-tools.qmd index 8a55c98..db6f1c2 100644 --- a/docs/guide/authoring-tools.qmd +++ b/docs/guide/authoring-tools.qmd @@ -1,5 +1,42 @@ --- title: Authoring Tools +subtitle: Other tools to help you create scrollytelling content. --- -Coming soon! \ No newline at end of file +## 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 Pandoc div with `.progress-block`: + +````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 +::: + +:::: +```` From 2812d53c5555109f797e8fce9535d8ab9dddcb52 Mon Sep 17 00:00:00 2001 From: James Goldie Date: Thu, 24 Oct 2024 09:42:23 +1100 Subject: [PATCH 06/28] Align language on layout page I've tried to push us toward using 'triggers' and 'stickies' here, since the only place you really need to know about the narrative column and sticky column are when customising with CSS (which I'll add soon). --- docs/guide/layouts.qmd | 18 ++++++++++++------ 1 file changed, 12 insertions(+), 6 deletions(-) diff --git a/docs/guide/layouts.qmd b/docs/guide/layouts.qmd index 73d0e96..50e9ad4 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: @@ -34,18 +35,23 @@ 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. -## Removing Header Space +## Removing header space -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. ```yaml format: closeread-html: remove-header-space: true ``` + +:::{.callout-note appearance="simple"} +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. +::: + From e9c6eae4c11b1e360d359f2f6d30f2323f7a7e73 Mon Sep 17 00:00:00 2001 From: James Goldie Date: Thu, 24 Oct 2024 09:52:14 +1100 Subject: [PATCH 07/28] Add step to myfirstcr.qmd to explain triggers and stickies --- docs/index.qmd | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/index.qmd b/docs/index.qmd index 9aa4073..a5716eb 100644 --- a/docs/index.qmd +++ b/docs/index.qmd @@ -51,6 +51,8 @@ Step three: flag an element to become a sticky. [@cr-doc]{highlight="14-18"} Step four: create a trigger to make the sticky appear. [@cr-doc]{highlight="12"} ::: +Triggers, like this text, scroll past while the stickies stay "stuck" on the page. [@cr-doc]{highlight=""} + :::{#cr-doc filename="myfirstcr.qmd"} ````markdown --- From ba6ed41ef41ab4ba51bed22da9638a9e58790b12 Mon Sep 17 00:00:00 2001 From: James Goldie Date: Thu, 24 Oct 2024 09:55:20 +1100 Subject: [PATCH 08/28] Tweaks to Components section of guide --- docs/guide/components.qmd | 28 ++++++++++++++++------------ 1 file changed, 16 insertions(+), 12 deletions(-) diff --git a/docs/guide/components.qmd b/docs/guide/components.qmd index 9904903..731ea90 100644 --- a/docs/guide/components.qmd +++ b/docs/guide/components.qmd @@ -1,14 +1,15 @@ --- -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: -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. @@ -20,11 +21,17 @@ 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. -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. +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 with the triggers, scrolling by, unless you've indicated that they should be a sticky. + +:::{.callout-tip appearance="simple"} +If your whole document is a Closeread section, you might want to consider [removing the title block](layouts.qmd##removeheaderspace) and [disabling the Quarto sidebar](https://quarto.org/docs/websites/website-navigation.html#hiding-navigation). +::: ## 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,7 +48,7 @@ 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 @@ -75,7 +82,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). From 886e240fe65f13554179eaa8c5f7a9add1584d17 Mon Sep 17 00:00:00 2001 From: James Goldie Date: Thu, 24 Oct 2024 09:55:29 +1100 Subject: [PATCH 09/28] Add fenced div link to authoring tools --- docs/guide/authoring-tools.qmd | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/guide/authoring-tools.qmd b/docs/guide/authoring-tools.qmd index db6f1c2..60059c6 100644 --- a/docs/guide/authoring-tools.qmd +++ b/docs/guide/authoring-tools.qmd @@ -25,7 +25,7 @@ If you want to animate a graphic across several triggers, you could manually wor 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 Pandoc div with `.progress-block`: +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} From 1500f1f268d9614182b1d8224c465bf258ad7036 Mon Sep 17 00:00:00 2001 From: James Goldie Date: Thu, 24 Oct 2024 09:55:52 +1100 Subject: [PATCH 10/28] Add ID to remove header space section --- docs/guide/layouts.qmd | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/guide/layouts.qmd b/docs/guide/layouts.qmd index 50e9ad4..6bc37f5 100644 --- a/docs/guide/layouts.qmd +++ b/docs/guide/layouts.qmd @@ -25,7 +25,7 @@ In the overlay layouts, the sticky column occupies the entire screen width and t 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 +``` --- format: closeread-html: @@ -41,7 +41,7 @@ Closeread documents place special emphasis on the "stickies": the text, images, 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, 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. From 91a0d4f30b2c4f27afe322ed13735e54187102fd Mon Sep 17 00:00:00 2001 From: James Goldie Date: Thu, 24 Oct 2024 10:09:32 +1100 Subject: [PATCH 11/28] Shuffle focus effects to position zoom as pan + scale combo --- docs/guide/focus-effects.qmd | 88 ++++++++++++++++++++---------------- 1 file changed, 48 insertions(+), 40 deletions(-) diff --git a/docs/guide/focus-effects.qmd b/docs/guide/focus-effects.qmd index 21710e3..d22a7ba 100644 --- a/docs/guide/focus-effects.qmd +++ b/docs/guide/focus-effects.qmd @@ -1,12 +1,50 @@ --- -title: Focus Effects +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. + +:::{.callout-tip appearance="simple"} +Like all Quarto inline spans, focus effects follow a `attribute="value"` syntax: the value must be quoted and `=` separates the value from the attribute with no spaces. +::: + +```markdown +Here's a trigger with no focus effect @cr-content + +Here's a trigger with a focus effect [@cr-mycontent]{effect="value"} +``` 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. -# Types of 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} @@ -19,7 +57,7 @@ You can highlight parts of the code and text of your sticky using the following 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 +95,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,38 +123,9 @@ 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. - - -## 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. +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. -# Combining Focus Effects +# Combining focus effects You can combine multiple focus effects on a single trigger. For example: @@ -125,16 +133,16 @@ You can combine multiple focus effects on a single trigger. For example: 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="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. -# 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: From 69d81f5c7e4cd5a6f5422fdc43a33df464d482f1 Mon Sep 17 00:00:00 2001 From: James Goldie Date: Thu, 24 Oct 2024 10:26:59 +1100 Subject: [PATCH 12/28] Tweak case on authoring tools title --- docs/guide/authoring-tools.qmd | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/guide/authoring-tools.qmd b/docs/guide/authoring-tools.qmd index 60059c6..b9c22c9 100644 --- a/docs/guide/authoring-tools.qmd +++ b/docs/guide/authoring-tools.qmd @@ -1,5 +1,5 @@ --- -title: Authoring Tools +title: Authoring tools subtitle: Other tools to help you create scrollytelling content. --- From c52ddecf6b0e4b5eec87f54781c25a96a87c1026 Mon Sep 17 00:00:00 2001 From: James Goldie Date: Thu, 24 Oct 2024 10:27:05 +1100 Subject: [PATCH 13/28] Add styling guide --- docs/_quarto.yml | 1 + docs/guide/index.qmd | 2 ++ docs/guide/styling.qmd | 33 +++++++++++++++++++++++++++++++++ 3 files changed, 36 insertions(+) create mode 100644 docs/guide/styling.qmd diff --git a/docs/_quarto.yml b/docs/_quarto.yml index 52f4ed8..1746f27 100644 --- a/docs/_quarto.yml +++ b/docs/_quarto.yml @@ -40,6 +40,7 @@ website: - guide/focus-effects.qmd - guide/layouts.qmd - guide/authoring-tools.qmd + - guide/styling.qmd page-footer: background: light diff --git a/docs/guide/index.qmd b/docs/guide/index.qmd index 6481334..0a222b5 100644 --- a/docs/guide/index.qmd +++ b/docs/guide/index.qmd @@ -14,6 +14,8 @@ If you've never made a Closeread document, start with the very minimal example o [Authoring tools](authoring-tools.qmd) covers other useful tools to help you generate scrollytelling content, including ways to use [Observable JavaScript](https://quarto.org/docs/computations/ojs.html) to make animated graphics with Closeread. +[Styling](styling.qmd) shows you how to change the appearance of your documents from the default Quarto theme. + 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! * * * diff --git a/docs/guide/styling.qmd b/docs/guide/styling.qmd new file mode 100644 index 0000000..d7e30cf --- /dev/null +++ b/docs/guide/styling.qmd @@ -0,0 +1,33 @@ +--- +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. + +# (S)CSS customisation + +Users familiar with CSS or SCSS can add a stylesheet to tweak 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 From c25aaef16a7e9c021b5999856f804bf08f43cd25 Mon Sep 17 00:00:00 2001 From: James Goldie Date: Thu, 24 Oct 2024 10:29:54 +1100 Subject: [PATCH 14/28] Add links to connect guide docs --- docs/guide/authoring-tools.qmd | 2 ++ docs/guide/focus-effects.qmd | 2 ++ docs/guide/layouts.qmd | 1 + 3 files changed, 5 insertions(+) diff --git a/docs/guide/authoring-tools.qmd b/docs/guide/authoring-tools.qmd index b9c22c9..72c937b 100644 --- a/docs/guide/authoring-tools.qmd +++ b/docs/guide/authoring-tools.qmd @@ -40,3 +40,5 @@ We can keep referring to it as several triggers scroll by... @cr-graphic :::: ```` + +Finally, you might want to [style](styling.qmd) your documents to look the way your want. diff --git a/docs/guide/focus-effects.qmd b/docs/guide/focus-effects.qmd index d22a7ba..8136c88 100644 --- a/docs/guide/focus-effects.qmd +++ b/docs/guide/focus-effects.qmd @@ -158,3 +158,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/layouts.qmd b/docs/guide/layouts.qmd index 6bc37f5..801aeea 100644 --- a/docs/guide/layouts.qmd +++ b/docs/guide/layouts.qmd @@ -55,3 +55,4 @@ format: 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. ::: +Closeread has a few [other tools](authoring-tools.qmd) you can use to enhance your documents! You might also want to [style](styling.qmd) your documents to look the way your want. From 579494bd9627eb4aae72494a72db379bba616bb5 Mon Sep 17 00:00:00 2001 From: andrewpbray Date: Thu, 24 Oct 2024 16:49:09 -0700 Subject: [PATCH 15/28] simplify look at the top of doc --- docs/index.qmd | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/docs/index.qmd b/docs/index.qmd index a5716eb..c23a3c5 100644 --- a/docs/index.qmd +++ b/docs/index.qmd @@ -7,7 +7,7 @@ format: css: index-styles.css --- -Quarto first-timer? Get up and running with your first Closeread document. +[New to Quarto? Get started by working through the [Quarto tutorials](https://quarto.org/docs/get-started/).]{.column-margin} ## Getting started {#gettingstarted} @@ -17,14 +17,6 @@ Install the extension by running the following command in the directory you wish quarto add qmd-lab/closeread ``` -:::{.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 -``` -::: - With the extension installed, you can author documents using the `closeread-html` format: ```yaml @@ -101,3 +93,11 @@ If you can't remember a particular option that Closeread uses, see the [Referenc ### 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 +``` +::: From 575f3bfe9ad7f80700ce7994f54440edcc22fe2d Mon Sep 17 00:00:00 2001 From: andrewpbray Date: Thu, 24 Oct 2024 17:34:14 -0700 Subject: [PATCH 16/28] add text of hello-world document into guide --- docs/guide/index.qmd | 41 ++++++++++++++++++++++++++++++++++------- 1 file changed, 34 insertions(+), 7 deletions(-) diff --git a/docs/guide/index.qmd b/docs/guide/index.qmd index 0a222b5..457729d 100644 --- a/docs/guide/index.qmd +++ b/docs/guide/index.qmd @@ -1,20 +1,47 @@ --- title: Guide subtitle: Start with the basics of a Closeread document, then learn to master more advanced techniques. -toc: true --- -If you've never made a Closeread document, start with the very minimal example on the [home page](/), then come back here! +If you've never made a Closeread document, copy and paste the following document into a qmd document. -[Components of a Closeread document](components.qmd) teaches you the essential parts of a Closeread document: sections, stickies and triggers. +```{.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 +::: + +::: + +``` -[Focus Effects](focus-effects.qmd) let you guide your readers to parts of your content by highlighting text and code, or zooming in on parts of an image or text. You can also ensure that content scales responsively, no matter what devices your readers use. +In the same directory as this qmd file, run the following command to make the Closeread extension available to this document. -[Layouts](layouts.qmd) teaches you how to customise the layouts of your Closeread sections - that is, where the stickies and triggers sit - as well as other useful tools that change the structure of the page. +```bash +quarto add qmd-lab/closeread +``` -[Authoring tools](authoring-tools.qmd) covers other useful tools to help you generate scrollytelling content, including ways to use [Observable JavaScript](https://quarto.org/docs/computations/ojs.html) to make animated graphics with Closeread. +Now you can render the document and scroll through your first scrollytelling story. Continue the adventure by reading this Guide: -[Styling](styling.qmd) shows you how to change the appearance of your documents from the default Quarto theme. +- [Components of a Closeread Document](components.qmd) teaches you the essential parts of a Closeread document: sections, stickies and triggers. +- [Focus Effects](focus-effects.qmd) let you guide your readers to parts of your content by highlighting text and code, or zooming in on parts of an image or text. You can also ensure that content scales responsively, no matter what devices your readers use. +- [Layouts](layouts.qmd) teaches you how to customise the layouts of your Closeread sections - that is, where the stickies and triggers sit - as well as other useful tools that change the structure of the page. +- [Interactive Graphics](authoring-tools.qmd) shows you how use [Observable JavaScript](https://quarto.org/docs/computations/ojs.html) to make graphics that animate as your user scrolls. +- [Styling](styling.qmd) teaches you how to change the appearance of your documents from the default Quarto theme. 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! From 1af676fb83a1ba5db601a14055efb8c7891cfb47 Mon Sep 17 00:00:00 2001 From: andrewpbray Date: Thu, 24 Oct 2024 17:34:25 -0700 Subject: [PATCH 17/28] add page navigation --- docs/_quarto.yml | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/_quarto.yml b/docs/_quarto.yml index 1746f27..3650fcc 100644 --- a/docs/_quarto.yml +++ b/docs/_quarto.yml @@ -5,6 +5,7 @@ project: website: title: "Closeread" + page-navigation: true navbar: left: - href: index.qmd From 80fc68b9a767758e3c7d6f870dd6385c2b80ffdc Mon Sep 17 00:00:00 2001 From: andrewpbray Date: Thu, 24 Oct 2024 17:34:37 -0700 Subject: [PATCH 18/28] narrow the body width of the guide so its easier to read --- docs/guide/_metadata.yml | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) 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 From 0a1f0c00cc1e9db46ce3983ecde420250cc9b2b2 Mon Sep 17 00:00:00 2001 From: andrewpbray Date: Thu, 24 Oct 2024 17:50:21 -0700 Subject: [PATCH 19/28] remove linked sentences. --- docs/guide/index.qmd | 8 +------- 1 file changed, 1 insertion(+), 7 deletions(-) diff --git a/docs/guide/index.qmd b/docs/guide/index.qmd index 457729d..66acfb1 100644 --- a/docs/guide/index.qmd +++ b/docs/guide/index.qmd @@ -35,13 +35,7 @@ In the same directory as this qmd file, run the following command to make the Cl quarto add qmd-lab/closeread ``` -Now you can render the document and scroll through your first scrollytelling story. Continue the adventure by reading this Guide: - -- [Components of a Closeread Document](components.qmd) teaches you the essential parts of a Closeread document: sections, stickies and triggers. -- [Focus Effects](focus-effects.qmd) let you guide your readers to parts of your content by highlighting text and code, or zooming in on parts of an image or text. You can also ensure that content scales responsively, no matter what devices your readers use. -- [Layouts](layouts.qmd) teaches you how to customise the layouts of your Closeread sections - that is, where the stickies and triggers sit - as well as other useful tools that change the structure of the page. -- [Interactive Graphics](authoring-tools.qmd) shows you how use [Observable JavaScript](https://quarto.org/docs/computations/ojs.html) to make graphics that animate as your user scrolls. -- [Styling](styling.qmd) teaches you how to change the appearance of your documents from the default Quarto theme. +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! From 06381749cf8c0e45149eefc8835e324c28758996 Mon Sep 17 00:00:00 2001 From: andrewpbray Date: Thu, 24 Oct 2024 18:00:39 -0700 Subject: [PATCH 20/28] change title --- docs/_quarto.yml | 2 +- docs/guide/{authoring-tools.qmd => interactive-graphics.qmd} | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) rename docs/guide/{authoring-tools.qmd => interactive-graphics.qmd} (96%) diff --git a/docs/_quarto.yml b/docs/_quarto.yml index 3650fcc..04546f1 100644 --- a/docs/_quarto.yml +++ b/docs/_quarto.yml @@ -40,7 +40,7 @@ website: - guide/components.qmd - guide/focus-effects.qmd - guide/layouts.qmd - - guide/authoring-tools.qmd + - guide/interactive-graphics.qmd - guide/styling.qmd page-footer: diff --git a/docs/guide/authoring-tools.qmd b/docs/guide/interactive-graphics.qmd similarity index 96% rename from docs/guide/authoring-tools.qmd rename to docs/guide/interactive-graphics.qmd index 72c937b..8e6f7bb 100644 --- a/docs/guide/authoring-tools.qmd +++ b/docs/guide/interactive-graphics.qmd @@ -1,6 +1,6 @@ --- -title: Authoring tools -subtitle: Other tools to help you create scrollytelling content. +title: Interactive Graphics +subtitle: Creating graphics that animate as your reader scrolls. --- ## Observable JavaScript in Closeread From 1fdc3b7fdbf432d73121afc5d7bf3529fbebbc5f Mon Sep 17 00:00:00 2001 From: andrewpbray Date: Thu, 24 Oct 2024 18:05:07 -0700 Subject: [PATCH 21/28] switch to title case (a la quarto guide) --- docs/guide/components.qmd | 2 +- docs/guide/focus-effects.qmd | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/guide/components.qmd b/docs/guide/components.qmd index 731ea90..4249181 100644 --- a/docs/guide/components.qmd +++ b/docs/guide/components.qmd @@ -1,5 +1,5 @@ --- -title: Components of a Closeread document +title: Components of a Closeread Document subtitle: "Learn the essential building blocks of Closeread: sections, stickies and triggers." --- diff --git a/docs/guide/focus-effects.qmd b/docs/guide/focus-effects.qmd index 8136c88..7cfdf42 100644 --- a/docs/guide/focus-effects.qmd +++ b/docs/guide/focus-effects.qmd @@ -1,5 +1,5 @@ --- -title: Focus effects +title: Focus Fffects subtitle: Guide your readers' attention to aspects of your stickies. --- From edeb2b505ca56437e0e5c317322ba11556605246 Mon Sep 17 00:00:00 2001 From: andrewpbray Date: Thu, 24 Oct 2024 18:16:43 -0700 Subject: [PATCH 22/28] fix typo --- docs/guide/focus-effects.qmd | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/guide/focus-effects.qmd b/docs/guide/focus-effects.qmd index 7cfdf42..d175d19 100644 --- a/docs/guide/focus-effects.qmd +++ b/docs/guide/focus-effects.qmd @@ -1,5 +1,5 @@ --- -title: Focus Fffects +title: Focus Effects subtitle: Guide your readers' attention to aspects of your stickies. --- From 3e3de2fc15b7ad704d13554a160893e55ecd354a Mon Sep 17 00:00:00 2001 From: andrewpbray Date: Thu, 24 Oct 2024 20:16:43 -0700 Subject: [PATCH 23/28] move comment to layout doc --- docs/guide/components.qmd | 5 +---- 1 file changed, 1 insertion(+), 4 deletions(-) diff --git a/docs/guide/components.qmd b/docs/guide/components.qmd index 4249181..f53ce27 100644 --- a/docs/guide/components.qmd +++ b/docs/guide/components.qmd @@ -21,11 +21,8 @@ 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. -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 with the triggers, 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 as the narrative, scrolling by, unless you've indicated that they should be a sticky. -:::{.callout-tip appearance="simple"} -If your whole document is a Closeread section, you might want to consider [removing the title block](layouts.qmd##removeheaderspace) and [disabling the Quarto sidebar](https://quarto.org/docs/websites/website-navigation.html#hiding-navigation). -::: ## Stickies From 4aa666cb635653b00f22bda4af2f9b9e9d6aa24a Mon Sep 17 00:00:00 2001 From: andrewpbray Date: Thu, 24 Oct 2024 20:25:20 -0700 Subject: [PATCH 24/28] fix typos --- docs/guide/focus-effects.qmd | 20 ++++++++------------ 1 file changed, 8 insertions(+), 12 deletions(-) diff --git a/docs/guide/focus-effects.qmd b/docs/guide/focus-effects.qmd index d175d19..dc7d3c6 100644 --- a/docs/guide/focus-effects.qmd +++ b/docs/guide/focus-effects.qmd @@ -3,11 +3,7 @@ title: Focus Effects subtitle: Guide your readers' attention to aspects of your stickies. --- -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. - -:::{.callout-tip appearance="simple"} -Like all Quarto inline spans, focus effects follow a `attribute="value"` syntax: the value must be quoted and `=` 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. ```markdown Here's a trigger with no focus effect @cr-content @@ -15,7 +11,7 @@ Here's a trigger with no focus effect @cr-content Here's a trigger with a focus effect [@cr-mycontent]{effect="value"} ``` -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. +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 @@ -32,8 +28,8 @@ You can scale a sticky element up or down by using the `scale-by()` attribute an 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="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. @@ -55,7 +51,7 @@ 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 @@ -129,7 +125,7 @@ Note that Closeread extends the native Pandoc processing of line blocks. Instead 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. @@ -137,10 +133,10 @@ One exception is the `zoom-to` attribute. Since it performs both panning and zoo 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 From f26607c70fc4a3ae307a3fdc0504e1ac7bbf85c3 Mon Sep 17 00:00:00 2001 From: andrewpbray Date: Thu, 24 Oct 2024 20:31:13 -0700 Subject: [PATCH 25/28] small formatting stuff --- docs/guide/layouts.qmd | 16 ++++++++++------ 1 file changed, 10 insertions(+), 6 deletions(-) diff --git a/docs/guide/layouts.qmd b/docs/guide/layouts.qmd index 801aeea..6ce668b 100644 --- a/docs/guide/layouts.qmd +++ b/docs/guide/layouts.qmd @@ -25,7 +25,7 @@ In the overlay layouts, the sticky column occupies the entire screen width and t 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. -``` +```yaml --- format: closeread-html: @@ -43,16 +43,20 @@ While viewing any Closeread document in a browser, you can press `p` on the key ## Removing header space {#removeheaderspace} -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. +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 +--- ``` -:::{.callout-note appearance="simple"} -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. -::: -Closeread has a few [other tools](authoring-tools.qmd) you can use to enhance your documents! You might also want to [style](styling.qmd) your documents to look the way your want. +[^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)! From 74c165da27d94a6b30327b2f5f04e8fc02081a1b Mon Sep 17 00:00:00 2001 From: andrewpbray Date: Thu, 24 Oct 2024 20:33:01 -0700 Subject: [PATCH 26/28] fix typo --- docs/guide/interactive-graphics.qmd | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/docs/guide/interactive-graphics.qmd b/docs/guide/interactive-graphics.qmd index 8e6f7bb..7af4537 100644 --- a/docs/guide/interactive-graphics.qmd +++ b/docs/guide/interactive-graphics.qmd @@ -1,13 +1,11 @@ --- title: Interactive Graphics -subtitle: Creating graphics that animate as your reader scrolls. +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. +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: From 8bb89cccc862ebcd6b7ae8ec6a4416b90d3767e9 Mon Sep 17 00:00:00 2001 From: James Goldie Date: Tue, 29 Oct 2024 22:40:44 +1100 Subject: [PATCH 27/28] Add YAML styling options to dcos --- docs/guide/styling.qmd | 34 +++++++++++++++++++++++++++++++++- 1 file changed, 33 insertions(+), 1 deletion(-) diff --git a/docs/guide/styling.qmd b/docs/guide/styling.qmd index d7e30cf..efb7325 100644 --- a/docs/guide/styling.qmd +++ b/docs/guide/styling.qmd @@ -5,9 +5,41 @@ 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 tweak the appearance of Closeread sections. +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: From deea515352f6f79707cebf7fec5bf50036c116bb Mon Sep 17 00:00:00 2001 From: James Goldie Date: Tue, 29 Oct 2024 22:50:31 +1100 Subject: [PATCH 28/28] Make code blocks in cr-sections fully opaque --- _extensions/closeread/closeread.css | 3 +++ _extensions/closeread/closeread.css.map | 2 +- _extensions/closeread/closeread.scss | 4 ++++ 3 files changed, 8 insertions(+), 1 deletion(-) diff --git a/_extensions/closeread/closeread.css b/_extensions/closeread/closeread.css index e0d36a9..25957e5 100644 --- a/_extensions/closeread/closeread.css +++ b/_extensions/closeread/closeread.css @@ -42,6 +42,9 @@ .cr-section .sticky-col .sticky-col-stack .sticky.cr-poem2 { 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 2179284..b81cdcb 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;;AAEA;EACE;;AAEA;EACE;EACA;;AAEA;EACE;;AAKN;EACE;;AAIA;EACE;EACA;EACA;EACA;EACA;;AAEA;EACE;EACA;EAGA;EAEA,YACE;;AAMJ;EACE,YACE;;AAGJ;EACE,YACE;;AAKJ;EACE;;AAIA;EACE;EAEA,YACE;;AAGF;EACE;EAEA,YACA;;AAMJ;EACE;EAEA;;AAGA;EACE;EAEA;;AAIF;EACE;EAEA;;;AASZ;AAEA;EACE;AAAA;AAAA;AAAA;AAAA;IAKE;;EAEA;AAAA;AAAA;AAAA;AAAA;IACE;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;;AAEA;AAAA;AAAA;EACE;EACA;EACA;EACA;;AAIJ;AAAA;AAAA;EACE;;;AAMF;EACE;EACA;;;AAIF;EACE;;;AAIF;EACE;EACA;;;AAMJ;EACE;;AAEA;EACE;EACA;;AAGF;EACE;;;AAGJ;EACE;;AAEA;EACE;EACA;;AAGF;EACE;;;AAKJ;AAAA;AAAA;AAAA;AAAA;EAKE;;AAEA;AAAA;AAAA;AAAA;AAAA;EACE;EACA;EACA;EACA;EACA;;AAGF;AAAA;AAAA;AAAA;AAAA;EACE;;;AAKJ;AAEA;EAEE;AAEA;AAAA;EAEA;EACA;EAEA;EACA;EAGA;;AAGA;EACE;;AAGF;EACE;;;AAIJ;EAEE;EAGA;EACA;EAGA;EAEA;EACA;EAGA;;AAGA;EACE;EAEA;;AAGF;EACE;;;AAKJ;AAKE;EACE;EACA;;AAIF;EACE;;AAKA;EACE;EACA;EACA;;AAEA;EACE;;;AAOR;AAII;EACE;EACA;;AAEA;EACE","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;;AAEA;EACE;;AAEA;EACE;EACA;;AAEA;EACE;;AAKN;EACE;;AAIA;EACE;EACA;EACA;EACA;EACA;;AAEA;EACE;EACA;EAGA;EAEA,YACE;;AAMJ;EACE,YACE;;AAGJ;EACE,YACE;;AAIJ;EACE;;AAIF;EACE;;AAIA;EACE;EAEA,YACE;;AAGF;EACE;EAEA,YACA;;AAMJ;EACE;EAEA;;AAGA;EACE;EAEA;;AAIF;EACE;EAEA;;;AASZ;AAEA;EACE;AAAA;AAAA;AAAA;AAAA;IAKE;;EAEA;AAAA;AAAA;AAAA;AAAA;IACE;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;;AAEA;AAAA;AAAA;EACE;EACA;EACA;EACA;;AAIJ;AAAA;AAAA;EACE;;;AAMF;EACE;EACA;;;AAIF;EACE;;;AAIF;EACE;EACA;;;AAMJ;EACE;;AAEA;EACE;EACA;;AAGF;EACE;;;AAGJ;EACE;;AAEA;EACE;EACA;;AAGF;EACE;;;AAKJ;AAAA;AAAA;AAAA;AAAA;EAKE;;AAEA;AAAA;AAAA;AAAA;AAAA;EACE;EACA;EACA;EACA;EACA;;AAGF;AAAA;AAAA;AAAA;AAAA;EACE;;;AAKJ;AAEA;EAEE;AAEA;AAAA;EAEA;EACA;EAEA;EACA;EAGA;;AAGA;EACE;;AAGF;EACE;;;AAIJ;EAEE;EAGA;EACA;EAGA;EAEA;EACA;EAGA;;AAGA;EACE;EAEA;;AAGF;EACE;;;AAKJ;AAKE;EACE;EACA;;AAIF;EACE;;AAKA;EACE;EACA;EACA;;AAEA;EACE;;;AAOR;AAII;EACE;EACA;;AAEA;EACE","file":"closeread.css"} \ No newline at end of file diff --git a/_extensions/closeread/closeread.scss b/_extensions/closeread/closeread.scss index dda101d..dfa66a8 100644 --- a/_extensions/closeread/closeread.scss +++ b/_extensions/closeread/closeread.scss @@ -66,6 +66,10 @@ font-size .8s ease-in-out; } + div.sourceCode { + background-color: rgba(233, 236, 239, 1); + } + // show active stickies .cr-active { opacity: 1;