Enables KaTeX support on pages with the math: true metadata tag.

russellgordon · russellgordon · Aug 15, 2020 · Aug 15, 2020 · 92a46b6ffa1f62dd529598bfc47c3af7ac33919a
commit 92a46b6ffa1f62dd529598bfc47c3af7ac33919a
diff --git a/Content/teaching/a-peculiar-form-of-torment.md b/Content/teaching/a-peculiar-form-of-torment.md
@@ -3,6 +3,7 @@ date: 2019-08-23 14:20
 title: A Peculiar Form of Torment
 description: Considering ways to approach the study of quadratic relations in Ontario Grade 10 Mathematics.
 tags: quadratics, assessment
+math: true
 ---
 A possible future exchange on a popular TV game show:
 
@@ -24,17 +25,23 @@ Another day of fitting curves to photos of a bridge:
 
 Or learning [one more algebraic procedure](standard-form-to-vertex-form.pdf) to convert a relation in standard form:
 
-<picture>
-	<source srcset="equation-1-dark.png" media="(prefers-color-scheme: dark)">
-	<img src="equation-1.png" loading="lazy" alt="Standard form of a quadratic" style="width:141px;"/> 
-</picture>
+<p>
+	<span class="math display">
+		\[
+		y = ax^2 + bx + c
+		\]
+	</span>
+</p>
 
 ...to its equivalent in vertex form:
 
-<picture>
-	<source srcset="equation-2-dark.png" media="(prefers-color-scheme: dark)">
-	<img src="equation-2.png" loading="lazy" alt="Vertex form of a quadratic" style="width:166px;"/> 
-</picture>
+<p>
+	<span class="math display">
+		\[
+		y = a\left(x-h\right)^2+k
+		\]
+	</span>
+</p>
 
 You might even struggle to make it through, who knows, dressing up some drab review of quadratic relations by [using a *Jeopardy!* template](https://duckduckgo.com/?q=jeopardy+templates&t=osx&ia=web) at the end of a unit of study.
 
@@ -128,7 +135,7 @@ When you set up the ramp to begin the activity, it's a good idea to use a C-clam
 <figure style="width: 55%;">
 <img src="c-clamp.jpg" loading="lazy" alt="A C-clamp is used to secure the ramp to the desk or ladder on which it is placed." width="453">
 <figcaption>
-	<p>It's no fun at all if students carefully take measurements, perform their calculations, prepare to do the final drop, and then someone accidentally bumps the ramp – requiring the entire process to begin anew.</p>
+	<p>It's no fun at all if students carefully take measurements, perform their calculations, prepare to do the final drop, and then someone accidentally bumps the ramp – requiring the entire process to begin anew.</p>
 </figcaption>
 </figure>
 
@@ -152,17 +159,23 @@ A group of twelve works well, with students mostly partnered and assigned specif
 
 After measurements have been taken for the vertex and where the ball hits the ground, students can algebraically determine the missing value in the quadratic relation. I've had groups use both of these forms with success:
 
-<picture>
-	<source srcset="equation-2-dark.png" media="(prefers-color-scheme: dark)">
-	<img src="equation-2.png" loading="lazy" alt="Vertex form of a quadratic" style="width:166px;"/> 
-</picture>
+<p>
+	<span class="math display">
+		\[
+		y = a\left(x-h\right)^2+k
+		\]
+	</span>
+</p>
 
 Or:
 
-<picture>
-	<source srcset="equation-3-dark.png" media="(prefers-color-scheme: dark)">
-	<img src="equation-3.png" loading="lazy" alt="Intercepts form of a quadratic" style="width:183px;"/> 
-</picture>
+<p>
+	<span class="math display">
+		\[
+		y = a\left(x-r\right)\left(x-s\right)
+		\]
+	</span>
+</p>
 
 It's a good conversation to hear students decide on which equation to work with, and how that connects to the physical apparatus of the task.
 
@@ -256,4 +269,4 @@ The *Ball in a Can Challenge* takes time to set up, but the payoff for your stud
 <li id="fn:2">The Greer conference at PEA deserves to be explicated in its own article. Here's the short version: if you're a math teacher, go. Find a way. You won't regret it.
  <a class="footnote-return" href="#fnref:2">^</a></li>
 </ol>
-</div>
+</div>
diff --git a/Sources/RussellGordon/Theme+GordonSedate.swift b/Sources/RussellGordon/Theme+GordonSedate.swift
@@ -81,9 +81,11 @@ private struct GordonSedateHTMLFactory: HTMLFactory {
 
     func makeItemHTML(for item: Item<RussellGordon>,
                       context: PublishingContext<RussellGordon>) throws -> HTML {
+
         HTML(
+
             .lang(context.site.language),
-            .head(for: item, on: context.site, stylesheetPaths: stylesheetNameWithVersion),
+            .if(item.metadata.math ?? false == true, .headWithMath(for: item, on: context.site, stylesheetPaths: stylesheetNameWithVersion), else: .head(for: item, on: context.site, stylesheetPaths: stylesheetNameWithVersion)),
             .body(
                 .class("item-page"),
                 .header(for: context, selectedSection: item.sectionID),
@@ -99,13 +101,14 @@ private struct GordonSedateHTMLFactory: HTMLFactory {
                             .div(
                                 .tagList(for: item, on: context.site)
                             ),
-                        .contentBody(item.body)
+                            .contentBody(item.body)
                         )
                     )
                 ),
                 .footer(for: context.site)
             )
         )
+
     }
 
     func makePageHTML(for page: Page,
@@ -259,4 +262,78 @@ private extension Node where Context == HTML.BodyContext {
     }
 }
 
+public extension Node where Context == HTML.HeadContext {
+
+    /// Return header information required to enable KaTeX includes
+    static func katex() -> Node {
+        .raw(#"""
+        <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/katex@0.12.0/dist/katex.min.css" integrity="sha384-AfEj0r4/OFrOo5t7NnNe46zW/tFgW6x/bCJG8FqQCEo3+Aro6EYUG4+cU+KJWu/X" crossorigin="anonymous">
+
+                <!-- The loading of KaTeX is deferred to speed up page rendering -->
+                <script defer src="https://cdn.jsdelivr.net/npm/katex@0.12.0/dist/katex.min.js" integrity="sha384-g7c+Jr9ZivxKLnZTDUhnkOnsh30B4H0rpLUpJ4jAIKs4fnJI+sEnkvrMWph2EDg4" crossorigin="anonymous"></script>
 
+                <!-- To automatically render math in text elements, include the auto-render extension: -->
+                <script defer src="https://cdn.jsdelivr.net/npm/katex@0.12.0/dist/contrib/auto-render.min.js" integrity="sha384-mll67QQFJfxn0IYznZYonOWZ644AWYC+Pt2cHqMaRhXVrursRwvLnLaebdGIlYNa" crossorigin="anonymous"
+                    onload="renderMathInElement(document.body);"></script>
+        """#)
+    }
+}
+
+public extension Node where Context == HTML.DocumentContext {
+
+    /// Add an HTML `<head>` tag within the current context, based
+    /// on inferred information from the current location and `Website`
+    /// implementation.
+    /// - parameter location: The location to generate a `<head>` tag for.
+    /// - parameter site: The website on which the location is located.
+    /// - parameter titleSeparator: Any string to use to separate the location's
+    ///   title from the name of the website. Default: `" | "`.
+    /// - parameter stylesheetPaths: The paths to any stylesheets to add to
+    ///   the resulting HTML page. Default: `styles.css`.
+    /// - parameter rssFeedPath: The path to any RSS feed to associate with the
+    ///   resulting HTML page. Default: `feed.rss`.
+    /// - parameter rssFeedTitle: An optional title for the page's RSS feed.
+    static func headWithMath<T: Website>(
+        for location: Location,
+        on site: T,
+        titleSeparator: String = " | ",
+        stylesheetPaths: [Path] = ["/styles.css"],
+        rssFeedPath: Path? = .defaultForRSSFeed,
+        rssFeedTitle: String? = nil
+    ) -> Node {
+        var title = location.title
+
+        if title.isEmpty {
+            title = site.name
+        } else {
+            title.append(titleSeparator + site.name)
+        }
+
+        var description = location.description
+
+        if description.isEmpty {
+            description = site.description
+        }
+
+        return .head(
+            .encoding(.utf8),
+            .siteName(site.name),
+            .url(site.url(for: location)),
+            .title(title),
+            .description(description),
+            .twitterCardType(location.imagePath == nil ? .summary : .summaryLargeImage),
+            .forEach(stylesheetPaths, { .stylesheet($0) }),
+            .viewport(.accordingToDevice),
+            .unwrap(site.favicon, { .favicon($0) }),
+            .unwrap(rssFeedPath, { path in
+                let title = rssFeedTitle ?? "Subscribe to \(site.name)"
+                return .rssFeedLink(path.absoluteString, title: title)
+            }),
+            .unwrap(location.imagePath ?? site.imagePath, { path in
+                let url = site.url(for: path)
+                return .socialImageLink(url)
+            }),
+            .katex()
+        )
+    }
+}
diff --git a/Sources/RussellGordon/main.swift b/Sources/RussellGordon/main.swift
@@ -18,6 +18,7 @@ struct RussellGordon: Website {
 
     struct ItemMetadata: WebsiteItemMetadata {
         // Add any site-specific metadata that you want to use here.
+        var math: Bool?
     }
 
     // Update these properties to configure your website: