Add sidenote examples, related posts and giscus to distill posts (#3103)

This PR adds a few stylistic improvements to the distill-style blog
posts:

- Update distill blog post example to showcase sidenotes as an
alternative to styles in PR #3077
- Showcase equations in sidenotes (closes #1242)
- Add `overrides.js` to match footnotes and citation styles with global
theme styling
- Add "related posts" sections if enabled to distill style posts
- Add "giscus" section if enabled to distill style posts



https://github.com/user-attachments/assets/b19a9cd9-779d-4d89-a4fb-eb14fb384480

_includes/distill_scripts.liquid

@@ -13,6 +13,9 @@
   crossorigin="anonymous"
 ></script>
 
+<!-- Custom overrides -->
+<script src="{{ '/assets/js/distillpub/overrides.js' | relative_url }}"></script>
+
 {% if page.mermaid and page.mermaid.enabled %}
   <!-- Mermaid and D3 -->
   <script

_includes/giscus.liquid

@@ -1,4 +1,13 @@
-<div id="giscus_thread" style="max-width: {{ site.max_width }}; margin: 0 auto;">
+<div
+  id="giscus_thread"
+  {% if page.layout == 'post' %}
+    style="max-width: {{ site.max_width }}; margin: 0 auto;"
+  {% endif %}
+>
+  {% if page.layout == 'post' %}
+    <br>
+  {% endif %}
+
   {% if site.giscus.repo %}
     <script>
       let giscusTheme = determineComputedTheme();

_includes/related_posts.liquid

@@ -2,13 +2,18 @@
 {% for post in site.related_posts | limit: site.related_blog_posts.max_related %}
   {% unless have_related_posts %}
     {% assign have_related_posts = true %}
-    <br>
+    {% if page.layout == 'post' %}
-    <hr>
+      <br>
-    <br>
+      <hr>
-    <ul class="list-disc pl-8"></ul>
+      <br>
+      <ul class="list-disc pl-8"></ul>
+
+      <!-- Adds related posts to the end of an article -->
+      <h2 class="text-3xl font-semibold mb-4 mt-12">Enjoy Reading This Article?</h2>
+    {% else %}
+      <h2 class="text-3xl font-semibold mb-4 mt-12">Enjoy Reading This Article?</h2>
+    {% endif %}
 
-    <!-- Adds related posts to the end of an article -->
-    <h2 class="text-3xl font-semibold mb-4 mt-12">Enjoy Reading This Article?</h2>
     <p class="mb-2">Here are some more articles you might like to read next:</p>
   {% endunless %}
 

_layouts/distill.liquid

@@ -98,10 +98,19 @@
 
       <d-bibliography src="{{ page.bibliography | prepend: '/assets/bibliography/' | relative_url }}"></d-bibliography>
 
-      {% if site.disqus_shortname and page.disqus_comments %}{% include disqus.liquid %}{% endif %}
+      <d-article>
-      {% if site.giscus.repo and page.giscus_comments %}
+        {% if site.related_blog_posts and site.related_blog_posts.enabled %}
-        {% include giscus.liquid %}
+          {% if page.related_posts == null or page.related_posts %}
-      {% endif %}
+            {% include related_posts.liquid %}
+          {% endif %}
+        {% endif %}
+        <br>
+        <br>
+        {% if site.disqus_shortname and page.disqus_comments %}{% include disqus.liquid %}{% endif %}
+        {% if site.giscus.repo and page.giscus_comments %}
+          {% include giscus.liquid %}
+        {% endif %}
+      </d-article>
     </div>
 
     <!-- Footer -->

_posts/2018-12-22-distill.md

@@ -1224,9 +1224,9 @@ The rendered output shows a clean and simple bar chart with a hover effect：
 
     \draw[dashed, color=gray] (1.5,1.5) -- (1.5,0) node[below, black] {$\cos \theta$};
     \draw[dashed, color=gray] (1.5,1.5) -- (0,1.5) node[left, black] {$\sin \theta$};
-    \node at (2.2, 0) [below] {1}; 
+    \node at (2.2, 0) [below] {1};
-    \node at (0, 2.2) [left] {$i$}; 
+    \node at (0, 2.2) [left] {$i$};
-    \node at (1.5,1.5) [above right, color=blue] {$(\cos \theta \, \sin \theta)$}; 
+    \node at (1.5,1.5) [above right, color=blue] {$(\cos \theta \, \sin \theta)$};
 \end{tikzpicture}
 </script>
 ```
@@ -1248,9 +1248,9 @@ The rendered output is shown below, displayed as a vector graphic：
 
     \draw[dashed, color=gray] (1.5,1.5) -- (1.5,0) node[below, black] {$\cos \theta$};
     \draw[dashed, color=gray] (1.5,1.5) -- (0,1.5) node[left, black] {$\sin \theta$};
-    \node at (2.2, 0) [below] {1}; 
+    \node at (2.2, 0) [below] {1};
-    \node at (0, 2.2) [left] {$i$}; 
+    \node at (0, 2.2) [left] {$i$};
-    \node at (1.5,1.5) [above right, color=blue] {$(\cos \theta \, \sin \theta)$}; 
+    \node at (1.5,1.5) [above right, color=blue] {$(\cos \theta \, \sin \theta)$};
 \end{tikzpicture}
 </script>
 
@@ -1334,6 +1334,65 @@ It does not interrupt the normal flow of `.l-body` sized text except on mobile s
 
 ---
 
+## Sidenotes
+
+Distill supports sidenotes, which are like footnotes but placed in the margin of the page.
+They are useful for providing additional context or references without interrupting the flow of the main text.
+
+There are two main ways to create a sidenote:
+
+**Using the `<aside>` tag:**
+
+The following code creates a sidenote with **_distill's styling_** in the margin:
+
+```html
+<aside><p>This is a sidenote using aside tag.</p></aside>
+```
+
+<aside><p> This is a sidenote using `&lt;aside&gt;` tag</p> </aside>
+
+We can also add images to sidenotes (click on the image to zoom in for a larger version):
+{% raw %}
+
+```html
+<aside>
+  {% include figure.liquid loading="eager" path="assets/img/rhino.png" class="img-fluid rounded z-depth-1" zoomable=true %}
+  <p>
+    F.J. Cole, “The History of Albrecht Dürer’s Rhinoceros in Zoological Literature,” Science, Medicine, and History: Essays on the Evolution of
+    Scientific Thought and Medical Practice (London, 1953), ed. E. Ashworth Underwood, 337-356. From page 71 of Edward Tufte’s Visual Explanations.
+  </p>
+</aside>
+```
+
+{% endraw %}
+
+<aside>
+  {% include figure.liquid loading="eager" path="assets/img/rhino.png" class="img-fluid rounded z-depth-1" zoomable=true %}
+  <p>F.J. Cole, “The History of Albrecht Dürer’s Rhinoceros in Zoological Literature,” Science, Medicine, and History: Essays on the Evolution of Scientific Thought and Medical Practice (London, 1953), ed. E. Ashworth Underwood, 337-356. From page 71 of Edward Tufte’s Visual Explanations.</p>
+</aside>
+
+Sidenotes can also contain equations and links:
+
+In physics, mass–energy equivalence is the relationship between mass and energy in a system's rest frame. The two differ only by a multiplicative constant and the units of measurement.
+
+<aside>
+  <p>This principle is defined by Einstein's famous equation: $E = mc^2$ <a href="https://en.wikipedia.org/wiki/Mass%E2%80%93energy_equivalence" target="_blank">(Source: Wikipedia)</a></p>
+</aside>
+
+**Using the `l-gutter` class:**
+
+The following code creates a sidenote with **_al-folio's styling_** in the margin:
+
+```html
+<div class="l-gutter"><p>This is a sidenote using l-gutter class.</p></div>
+```
+
+<div class="l-gutter">
+  <p> This is a sidenote using `l-gutter` class. </p>
+</div>
+
+---
+
 ## Other Typography?
 
 Emphasis, aka italics, with _asterisks_ (`*asterisks*`) or _underscores_ (`_underscores_`).

assets/js/distillpub/overrides.js

@@ -0,0 +1,27 @@
+$(window).on("load", function () {
+  document.querySelectorAll("d-footnote").forEach(function (footnote) {
+    footnote.shadowRoot.querySelector("sup > span").setAttribute("style", "color: var(--global-theme-color);");
+    footnote.shadowRoot
+      .querySelector("d-hover-box")
+      .shadowRoot.querySelector("style")
+      .sheet.insertRule(".panel {background-color: var(--global-bg-color) !important;}");
+    footnote.shadowRoot
+      .querySelector("d-hover-box")
+      .shadowRoot.querySelector("style")
+      .sheet.insertRule(".panel {border-color: var(--global-divider-color) !important;}");
+  });
+  // Override styles of the citations.
+  document.querySelectorAll("d-cite").forEach(function (cite) {
+    cite.shadowRoot.querySelector("div > span").setAttribute("style", "color: var(--global-theme-color);");
+    cite.shadowRoot.querySelector("style").sheet.insertRule("ul li a {color: var(--global-text-color) !important; text-decoration: none;}");
+    cite.shadowRoot.querySelector("style").sheet.insertRule("ul li a:hover {color: var(--global-theme-color) !important;}");
+    cite.shadowRoot
+      .querySelector("d-hover-box")
+      .shadowRoot.querySelector("style")
+      .sheet.insertRule(".panel {background-color: var(--global-bg-color) !important;}");
+    cite.shadowRoot
+      .querySelector("d-hover-box")
+      .shadowRoot.querySelector("style")
+      .sheet.insertRule(".panel {border-color: var(--global-divider-color) !important;}");
+  });
+});