Skip to content

Commit 47b982b

Browse files
abhileshabhilesh
authored
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
1 parent 2247ec3 commit 47b982b

File tree

7 files changed

+129
-17
lines changed

7 files changed

+129
-17
lines changed

‎_includes/distill_scripts.liquid

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,9 @@
1313
crossorigin="anonymous"
1414
></script>
1515

16+
<!-- Custom overrides -->
17+
<script src="{{ '/assets/js/distillpub/overrides.js' | relative_url }}"></script>
18+
1619
{% if page.mermaid and page.mermaid.enabled %}
1720
<!-- Mermaid and D3 -->
1821
<script

‎_includes/giscus.liquid

Lines changed: 10 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,13 @@
1-
<div id="giscus_thread" style="max-width: {{ site.max_width }}; margin: 0 auto;">
1+
<div
2+
id="giscus_thread"
3+
{% if page.layout == 'post' %}
4+
style="max-width: {{ site.max_width }}; margin: 0 auto;"
5+
{% endif %}
6+
>
7+
{% if page.layout == 'post' %}
8+
<br>
9+
{% endif %}
10+
211
{% if site.giscus.repo %}
312
<script>
413
let giscusTheme = determineComputedTheme();

‎_includes/related_posts.liquid

Lines changed: 11 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -2,13 +2,18 @@
22
{% for post in site.related_posts | limit: site.related_blog_posts.max_related %}
33
{% unless have_related_posts %}
44
{% assign have_related_posts = true %}
5-
<br>
6-
<hr>
7-
<br>
8-
<ul class="list-disc pl-8"></ul>
5+
{% if page.layout == 'post' %}
6+
<br>
7+
<hr>
8+
<br>
9+
<ul class="list-disc pl-8"></ul>
10+
11+
<!-- Adds related posts to the end of an article -->
12+
<h2 class="text-3xl font-semibold mb-4 mt-12">Enjoy Reading This Article?</h2>
13+
{% else %}
14+
<h2 class="text-3xl font-semibold mb-4 mt-12">Enjoy Reading This Article?</h2>
15+
{% endif %}
916

10-
<!-- Adds related posts to the end of an article -->
11-
<h2 class="text-3xl font-semibold mb-4 mt-12">Enjoy Reading This Article?</h2>
1217
<p class="mb-2">Here are some more articles you might like to read next:</p>
1318
{% endunless %}
1419

‎_layouts/distill.liquid

Lines changed: 13 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -98,10 +98,19 @@
9898

9999
<d-bibliography src="{{ page.bibliography | prepend: '/assets/bibliography/' | relative_url }}"></d-bibliography>
100100

101-
{% if site.disqus_shortname and page.disqus_comments %}{% include disqus.liquid %}{% endif %}
102-
{% if site.giscus.repo and page.giscus_comments %}
103-
{% include giscus.liquid %}
104-
{% endif %}
101+
<d-article>
102+
{% if site.related_blog_posts and site.related_blog_posts.enabled %}
103+
{% if page.related_posts == null or page.related_posts %}
104+
{% include related_posts.liquid %}
105+
{% endif %}
106+
{% endif %}
107+
<br>
108+
<br>
109+
{% if site.disqus_shortname and page.disqus_comments %}{% include disqus.liquid %}{% endif %}
110+
{% if site.giscus.repo and page.giscus_comments %}
111+
{% include giscus.liquid %}
112+
{% endif %}
113+
</d-article>
105114
</div>
106115

107116
<!-- Footer -->

‎_posts/2018-12-22-distill.md

Lines changed: 65 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1224,9 +1224,9 @@ The rendered output shows a clean and simple bar chart with a hover effect：
12241224

12251225
\draw[dashed, color=gray] (1.5,1.5) -- (1.5,0) node[below, black] {$\cos \theta$};
12261226
\draw[dashed, color=gray] (1.5,1.5) -- (0,1.5) node[left, black] {$\sin \theta$};
1227-
\node at (2.2, 0) [below] {1};
1228-
\node at (0, 2.2) [left] {$i$};
1229-
\node at (1.5,1.5) [above right, color=blue] {$(\cos \theta \, \sin \theta)$};
1227+
\node at (2.2, 0) [below] {1};
1228+
\node at (0, 2.2) [left] {$i$};
1229+
\node at (1.5,1.5) [above right, color=blue] {$(\cos \theta \, \sin \theta)$};
12301230
\end{tikzpicture}
12311231
</script>
12321232
```
@@ -1248,9 +1248,9 @@ The rendered output is shown below, displayed as a vector graphic：
12481248

12491249
\draw[dashed, color=gray] (1.5,1.5) -- (1.5,0) node[below, black] {$\cos \theta$};
12501250
\draw[dashed, color=gray] (1.5,1.5) -- (0,1.5) node[left, black] {$\sin \theta$};
1251-
\node at (2.2, 0) [below] {1};
1252-
\node at (0, 2.2) [left] {$i$};
1253-
\node at (1.5,1.5) [above right, color=blue] {$(\cos \theta \, \sin \theta)$};
1251+
\node at (2.2, 0) [below] {1};
1252+
\node at (0, 2.2) [left] {$i$};
1253+
\node at (1.5,1.5) [above right, color=blue] {$(\cos \theta \, \sin \theta)$};
12541254
\end{tikzpicture}
12551255
</script>
12561256

@@ -1334,6 +1334,65 @@ It does not interrupt the normal flow of `.l-body` sized text except on mobile s
13341334

13351335
---
13361336

1337+
## Sidenotes
1338+
1339+
Distill supports sidenotes, which are like footnotes but placed in the margin of the page.
1340+
They are useful for providing additional context or references without interrupting the flow of the main text.
1341+
1342+
There are two main ways to create a sidenote:
1343+
1344+
**Using the `<aside>` tag:**
1345+
1346+
The following code creates a sidenote with **_distill's styling_** in the margin:
1347+
1348+
```html
1349+
<aside><p>This is a sidenote using aside tag.</p></aside>
1350+
```
1351+
1352+
<aside><p> This is a sidenote using `&lt;aside&gt;` tag</p> </aside>
1353+
1354+
We can also add images to sidenotes (click on the image to zoom in for a larger version):
1355+
{% raw %}
1356+
1357+
```html
1358+
<aside>
1359+
{% include figure.liquid loading="eager" path="assets/img/rhino.png" class="img-fluid rounded z-depth-1" zoomable=true %}
1360+
<p>
1361+
F.J. Cole, “The History of Albrecht Dürer’s Rhinoceros in Zoological Literature,” Science, Medicine, and History: Essays on the Evolution of
1362+
Scientific Thought and Medical Practice (London, 1953), ed. E. Ashworth Underwood, 337-356. From page 71 of Edward Tufte’s Visual Explanations.
1363+
</p>
1364+
</aside>
1365+
```
1366+
1367+
{% endraw %}
1368+
1369+
<aside>
1370+
{% include figure.liquid loading="eager" path="assets/img/rhino.png" class="img-fluid rounded z-depth-1" zoomable=true %}
1371+
<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>
1372+
</aside>
1373+
1374+
Sidenotes can also contain equations and links:
1375+
1376+
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.
1377+
1378+
<aside>
1379+
<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>
1380+
</aside>
1381+
1382+
**Using the `l-gutter` class:**
1383+
1384+
The following code creates a sidenote with **_al-folio's styling_** in the margin:
1385+
1386+
```html
1387+
<div class="l-gutter"><p>This is a sidenote using l-gutter class.</p></div>
1388+
```
1389+
1390+
<div class="l-gutter">
1391+
<p> This is a sidenote using `l-gutter` class. </p>
1392+
</div>
1393+
1394+
---
1395+
13371396
## Other Typography?
13381397

13391398
Emphasis, aka italics, with _asterisks_ (`*asterisks*`) or _underscores_ (`_underscores_`).

‎assets/img/rhino.png

1.57 MB
Loading

‎assets/js/distillpub/overrides.js

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
$(window).on("load", function () {
2+
document.querySelectorAll("d-footnote").forEach(function (footnote) {
3+
footnote.shadowRoot.querySelector("sup > span").setAttribute("style", "color: var(--global-theme-color);");
4+
footnote.shadowRoot
5+
.querySelector("d-hover-box")
6+
.shadowRoot.querySelector("style")
7+
.sheet.insertRule(".panel {background-color: var(--global-bg-color) !important;}");
8+
footnote.shadowRoot
9+
.querySelector("d-hover-box")
10+
.shadowRoot.querySelector("style")
11+
.sheet.insertRule(".panel {border-color: var(--global-divider-color) !important;}");
12+
});
13+
// Override styles of the citations.
14+
document.querySelectorAll("d-cite").forEach(function (cite) {
15+
cite.shadowRoot.querySelector("div > span").setAttribute("style", "color: var(--global-theme-color);");
16+
cite.shadowRoot.querySelector("style").sheet.insertRule("ul li a {color: var(--global-text-color) !important; text-decoration: none;}");
17+
cite.shadowRoot.querySelector("style").sheet.insertRule("ul li a:hover {color: var(--global-theme-color) !important;}");
18+
cite.shadowRoot
19+
.querySelector("d-hover-box")
20+
.shadowRoot.querySelector("style")
21+
.sheet.insertRule(".panel {background-color: var(--global-bg-color) !important;}");
22+
cite.shadowRoot
23+
.querySelector("d-hover-box")
24+
.shadowRoot.querySelector("style")
25+
.sheet.insertRule(".panel {border-color: var(--global-divider-color) !important;}");
26+
});
27+
});

0 commit comments

Comments
 (0)