Style rst directives: figure, quote, section headings (#130)

* Adjust styling of some rst directives * Use MyST directives * Move figure and quote styling into their own files Co-authored-by: Storm Heg <[email protected]>
wagtail · Apr 7, 2022 · 12002f1 · 12002f1
1 parent 7398907
commit 12002f1
Show file tree

Hide file tree

Showing 8 changed files with 76 additions and 316 deletions.
diff --git a/docs/examples/images.md b/docs/examples/images.md
@@ -3,11 +3,33 @@
 Images are hard to keep up-to-date as documentation evolves, but can be worthwhile nonetheless. Here are guidelines when adding images:
 
 
+## Plain Images
+
 - All images should have meaningful [alt text](https://axesslab.com/alt-texts/) unless they are decorative.
 - Images are served as-is – pick the correct format, and losslessly compress all images.
 - Use absolute paths for image files so they are more portable.
 
 ![A wagtail standing on the ground](/img/wagtail.jpg)
 
 Images should be responsive.
-This is something we should handle in the styling. 
+This is something we should handle in the styling.
+
+## Figures
+
+Figures are images which contain captions. Use figures to annotate what is
+happening in the image to the reader. Figures and their captions have some
+slight styling to help them stand out from surrounding text --- this is
+especially useful for screenshots which can easily blend in to the page.
+
+```{figure} /img/wagtail.jpg
+---
+alt: A wagtail standing on the ground
+---
+
+(This is the caption) Wagtails are a group of passerine birds that form the
+genus Motacilla in the family Motacillidae. Here we observe a wagtail in its
+natural habitat, standing on the ground.
+```
+
+You can see that the caption helps further illuminate and provides a link to the
+image.
diff --git a/docs/examples/index.md b/docs/examples/index.md
@@ -21,6 +21,7 @@ lists
 nesting/index
 paragraphs
 progressive-disclosure
+quotes
 rst-page
 tables
 tables-of-content

diff --git a/docs/examples/quotes.md b/docs/examples/quotes.md
@@ -0,0 +1,22 @@
+# Quotes
+
+Quotes, also known as blockquotes or pull-quotes, should stand out:
+
+> Lorem Ipsum is simply dummy text of the printing and typesetting industry.
+> Lorem Ipsum has been the industry's standard dummy text ever since the 1500s,
+> when an unknown printer took a galley of type and scrambled it to make a type
+> specimen book.
+
+
+RST has `epigraph`, `highlights`, and `pull-quote` which all create a quote.
+Adding the double dash line at the bottom properly attributes an author.
+
+```{epigraph}
+
+Lorem Ipsum is simply dummy text of the printing and typesetting industry.
+Lorem Ipsum has been the industry's standard dummy text ever since the 1500s,
+when an unknown printer took a galley of type and scrambled it to make a type
+specimen book.
+
+-- lipsum.com
+```
diff --git a/sass/_component_docutils.scss b/sass/_component_docutils.scss
@@ -5,15 +5,6 @@
     clear: both;
 }
 
-/**
-* Sections
-*/
-.section {
-    @include clearfix;
-    margin-top: ($spacer * 2.5);
-    margin-bottom: ($spacer * 2.5);
-}
-
 /**
 * Headerlink
 */
@@ -62,3 +53,10 @@ table.docutils {
     }
     margin-bottom: $spacer;
 }
+
+// Add ample spacing between sub-headings within the doc.
+main {
+    h2, h3, h4, h5, h6 {
+        margin-top: $headings-margin-bottom * 3;
+    }
+}
diff --git a/sass/_component_figure.scss b/sass/_component_figure.scss
@@ -0,0 +1,12 @@
+// Figures
+.figure {
+    img {
+        border-radius: $border-radius;
+        box-shadow: $box-shadow-sm;
+        margin-bottom: $paragraph-margin-bottom / 2;
+    }
+    .caption {
+        color: $text-muted;
+        font-style: italic;
+    }
+}
diff --git a/sass/_component_quotes.scss b/sass/_component_quotes.scss
@@ -0,0 +1,9 @@
+// Quotes
+blockquote {
+    border-left: 4px solid $gray-100;
+    padding-left: $spacer;
+    margin: ($paragraph-margin-bottom * 2) 0;
+    .attribution {
+        color: $blockquote-small-color;
+    }
+}