Merge pull request #109 from qmd-lab/jimjam-slam/issue77

Enhance docs

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.

_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;

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

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"}
 

docs/guide/_metadata.yml

@@ -1,3 +1,5 @@
 format:
   html:
-    toc: true
+    toc: true
+    grid:
+      body-width: 600px

docs/guide/components.qmd

@@ -1,30 +1,34 @@
 ---
-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}
 < add paragraphs, images, code cells, etc. >
 :::
 ```
 
-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).

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.