better CSS formatting and comments

.stylelintrc.js

@@ -1,3 +1,8 @@
 module.exports = {
   extends: ['stylelint-config-spaceninja', 'stylelint-config-prettier'],
+  // 1. This rule doesn't understand some print styles.
+  rules: {
+    'scss/at-rule-no-unknown': null, // 1
+    'selector-pseudo-element-no-unknown': null, // 1
+  },
 };

src/_includes/contents-item.njk

@@ -1,6 +1,6 @@
 <li>
   <span class="toc-item">
-    <span class="toc-title">
+    <span class="toc-item__title">
       <a href="
         {%- if useJumpLinks -%}
           #ch-{{ chapter.data.chapter }}-{{ chapter.data.title | slugify }}
@@ -10,7 +10,7 @@
         {{- chapter.data.title -}}
       </a>
     </span>
-    <span class="toc-page print-only">
+    <span class="toc-item__page print-only">
       <a href="
         {%- if useJumpLinks -%}
           #ch-{{ chapter.data.chapter }}-{{ chapter.data.title | slugify }}

src/_includes/contents.njk

@@ -1,4 +1,4 @@
-<article class="print-page page-toc">
+<article class="new-page page-toc">
   <h2 id="contents">Contents.</h2>
 
   <section>

src/_includes/frontispiece.njk

@@ -1,4 +1,4 @@
-<article class="print-page page-frontispiece">
+<article class="new-page page-frontispiece">
   <figure class="full-page-image">
     <img
       src="/images/frontispiece.png"

src/_includes/layouts/screen.njk

@@ -3,16 +3,14 @@ layout: layouts/base.njk
 ---
 
 {% if showHeader %}
-<header class="header" id="top">
-  <div class="header-content">
-    <em><a href="/">{{ book.title }}</a></em>
-  </div>
+<header class="app-header" id="top">
+  <p><em><a href="/">{{ book.title }}</a></em></p>
 </header>
 {% endif %}
-<main class="primary-content {{ main_class }}">
+<main class="app-main {{ main_class }}">
   {{ content | safe }}
 </main>
-<footer class="footer">
+<footer class="app-footer">
   {% if showNav %}
   <nav class="chapter-nav">
     <div class="chapter-nav__item chapter-nav__prev{% if not prev %} is-disabled{% endif %}">
@@ -33,9 +31,6 @@ layout: layouts/base.njk
       {% endif %}
     </div>
   </nav>
-  <div class="nav-back-to-top">
-    <a class="nav-back-to-top__link" href="#top"><span class="sr-only">Back to Top</span></a>
-  </div>
   {% endif %}
   <div class="footer-content">
     <div class="footer-copyright">

src/_includes/title-page.njk

@@ -1,5 +1,5 @@
-<article class="print-page title-page">
+<article class="new-page title-page">
   <h1 id="a-study-in-scarlet">{{ book.title }}</h1>
-  <p class="credits">By {{ book.author }}</p>
-  <p class="credits">With numerous original engravings by D.H. Friston.</p>
+  <p class="p-initial is-centered">By {{ book.author }}</p>
+  <p class="p-initial is-centered">With numerous original engravings by D.H. Friston.</p>
 </article>

src/_scss/_figures.scss

@@ -0,0 +1,51 @@
+/**
+ * Figures
+ */
+figure {
+  margin: 1em 0;
+
+  ol {
+    margin-top: 0;
+  }
+
+  @media print {
+    page-break-inside: avoid;
+  }
+}
+
+figcaption {
+  font-style: italic;
+  text-align: center;
+  text-wrap: balance;
+}
+
+img {
+  display: block;
+  height: auto;
+  max-width: 100%;
+}
+
+/**
+ * Modifier for figures containing full-page images
+ *
+ * 1. 75% of page height
+ */
+.full-page-image {
+  figcaption {
+    font-size: smaller;
+    margin-top: 1em;
+  }
+
+  @media print {
+    page-break-after: always;
+    page-break-before: always;
+    page-break-inside: avoid;
+
+    img {
+      margin: 0 auto;
+      max-height: 8.333in; // 1
+      page-break-inside: avoid;
+      width: auto;
+    }
+  }
+}

src/_scss/_footnotes.scss

@@ -0,0 +1,41 @@
+/**
+ * Footnotes
+ *
+ * 1. For print, we need the footnote to appear inline with the text, so it
+ *    can be positioned at the bottom of the current page. For screen, we
+ *    want to treat footnotes as endnotes, appearing at the end of the chapter.
+ * 2. Position the footnote at the bottom of the page it appears on.
+ * 3. Docraptor tries to automatically add the footnote numbers, but we
+ *    also need the numbers for web display, so we're adding them manually,
+ *    and disabling the automatic ones.
+ *
+ * @see https://docraptor.com/documentation/article/1067570-adding-footnotes
+ */
+main {
+  @media screen {
+    display: flex; // 1
+    flex-direction: column; // 1
+  }
+}
+
+.footnote {
+  font-size: smaller;
+  font-style: italic;
+
+  @media screen {
+    margin-top: 2em;
+    order: 1; // 1
+  }
+
+  @media print {
+    float: footnote; // 2
+
+    &::footnote-call {
+      content: none; // 3
+    }
+
+    &::footnote-marker {
+      content: none; // 3
+    }
+  }
+}

src/_scss/_layout.scss

@@ -0,0 +1,46 @@
+html {
+  box-sizing: border-box;
+}
+
+*,
+*::after,
+*::before {
+  box-sizing: inherit;
+}
+
+body {
+  margin: 1em;
+}
+
+main {
+  margin: 0 auto;
+  margin-bottom: 2em;
+  max-width: 60ch;
+}
+
+.app-header {
+  text-align: center;
+}
+
+.app-footer {
+  border-top: 1px solid currentcolor;
+  padding-top: 1em;
+}
+
+/**
+ * Chapter Navigation
+ */
+.chapter-nav {
+  display: flex;
+  gap: 1em;
+  justify-content: space-between;
+  margin-bottom: 1em;
+}
+
+.chapter-nav__toc {
+  text-align: center;
+}
+
+.chapter-nav__next {
+  text-align: right;
+}

src/_scss/_print-layout.scss

@@ -1,41 +1,49 @@
-/* this rule doesn't understand some print styles */
-/* stylelint-disable scss/at-rule-no-unknown */
-/* stylelint-disable selector-pseudo-element-no-unknown */
-
 @media print {
-  /*
-		This is to ensure that each "page" in the CMS breaks to a new page in
-		the PDF. What markup element it targets may need to change and it may
-		belong in the pattern library.
-	*/
-  .print-page {
+  // Utility class to force a page break
+  .new-page {
     page-break-before: always;
   }
 
-  /* reduce default margins to more closely match source pdf */
+  /**
+   * Standard Page Layout
+   *
+   * 1. We're using some special DocRaptor CSS to inject page numbers
+   *
+   * @see https://docraptor.com/documentation/article/1067094-headers-footers-for-pdfs
+   * @see https://docraptor.com/documentation/article/1082618-page-numbers
+   */
   @page {
     margin: 0.75in;
     padding: 0;
-  }
 
-  /* add page numbers to footer, aligned to match source pdf */
-  @page {
+    // Add book title to page header
     @top {
       content: 'A Study in Scarlet';
       font-family: Merriweather, serif;
       font-size: smaller;
       font-style: italic;
       margin-top: 1em;
     }
+
+    // Add page numbers to page footer
     @bottom {
-      content: counter(page);
+      content: counter(page); // 1
       font-family: Merriweather, serif;
       font-size: smaller;
       margin-bottom: 1em;
     }
   }
 
-  /* named pages */
+  /**
+   * Named Pages with Modified Layouts
+   *
+   * 1. Set table of contents to page 0, so successive page numbers are correct
+   * 2. Remove page header and footer
+   */
+  .page-toc {
+    page: toc;
+  }
+
   .title-page {
     page: title_page;
   }
@@ -44,37 +52,50 @@
     page: frontispiece;
   }
 
-  .page-toc {
-    page: toc;
-  }
-
-  /* set TOC to page 0, so successive page numbers are correct */
   @page toc {
-    counter-reset: page -1;
+    counter-reset: page -1; // 1
     @top {
-      content: none;
+      content: none; // 2
     }
     @bottom {
-      content: none;
+      content: none; // 2
     }
   }
 
-  /* remove page numbers */
   @page title_page {
     @top {
-      content: none;
+      content: none; // 2
     }
     @bottom {
-      content: none;
+      content: none; // 2
     }
   }
 
   @page frontispiece {
     @top {
-      content: none;
+      content: none; // 2
     }
     @bottom {
-      content: none;
+      content: none; // 2
     }
   }
 }
+
+/**
+ * Utility classes to hide elements from the screen, but show them when printed
+ */
+.print-only {
+  display: none;
+
+  @media print {
+    display: block;
+  }
+}
+
+.print-only-inline {
+  display: none;
+
+  @media print {
+    display: inline;
+  }
+}