Margin footnotes convention & cleanup (#244)

* Testing footnotes options

* More fiddling

* Prettified example options

* Slight update to testing instructions

* Adjusted testing structure

* Tested unnumbered footnotes

* Archived footnotes tests

* Fixed footnotes -workflows & -style guide

* Fixed footnotes in workflows docs

* Style guide footnotes

* Edited style guide for margin footnotes

* Fixed broken links

* Edit 2 footnotes on style guide + mobile breakpoint

* No margin footnotes on mobile

* Playing with announcement options

* Yassified the nav links

* More link & announement tweaks

* Final announcement tweaks

* 1st pass of modified footnotes

* 2nd pass of modified footnotes

* Final pass of margin footnotes

* Quick edit to link hover thickness and announcement banner

* Rendering site

Author: validbeck

README.md

@@ -77,6 +77,7 @@ These directories may have sub-directories depending on their size and grouped s
 #### Supporting `site` directories
 - `_site` — This is where static files rendered by `quarto render` get placed.
 - `assets` — This is where general shared assets live (stylesheets, promotional images, etc.).
+- `internal` — For internal testing only.
 - `notebooks` — This is where notebooks retrieved from the [`developer-framework` repo](https://github.com/validmind/developer-framework) live.
 - `tests` — This is where test descriptions generated from the Python source in the [developer-framework repo](https://github.com/validmind/developer-framework) live.
 - `wip` — Work in progress files should live here, and have [the `search` flag set to `false`](https://quarto.org/docs/websites/website-search.html#disabling-search).

site-unused/testing/footnotes/footnotes.qmd

@@ -0,0 +1,73 @@
+---
+title: "Footnotes"
+subtitle: "Example styling"
+search: false
+reference-location: margin
+footnotes-hover: true
+listing: 
+  - id: footnotes
+    type: grid
+    grid-columns: 2
+    max-description-length: 250
+    sort: false
+    fields: [title, description]
+    contents:
+    - hover-only.qmd
+    - margin-only.qmd
+    - margin-hover.qmd
+    - text-notes.qmd
+---
+
+> For **[SC-5288](https://app.shortcut.com/validmind/story/5288/explore-alternative-footnotes-options-for-inline-links)**:
+
+- All footnotes go in the bottom section of the source page, instead of haphazardly stuck in between things as we author!
+- Footnotes can't involve `include` files, unfortunately, so we can't single-source definitions.
+- However, footnotes **can** be hyperlinks, which is handy for our inline instructional asides.
+- The numbering of footnotes is still manual, but at least they are collated in one section so we can tell how many there are at a glance.
+
+### Defining styles
+- Footnote styling can be defined globally (via `_quarto.yml`) or individually in each file's YAML header.
+- While Quarto provides several places footnotes can live, `margin` is the only one that might work well for us as the others place them at the end of section/block/document etc. again taking readers away from the instructional text.
+
+#### Syntax
+
+```markdown
+Here is a footnote reference,[^1] and another.[^longnote]
+
+[^1]: Here is the footnote.
+
+[^longnote]: Here's one with multiple blocks.
+
+    Subsequent paragraphs are indented to show that they belong to the previous footnote.
+
+        { some.code }
+
+    The whole paragraph can be indented, or just the first line. 
+    In this way, multi-paragraph footnotes work like multi-paragraph list items.
+
+This paragraph won't be part of the note, because it isn't indented.
+```
+
+Output
+: Here is a footnote reference,[^1] and another.[^longnote]
+
+[^1]: Here is the footnote.
+
+[^longnote]: Here's one with multiple blocks.
+
+    Subsequent paragraphs are indented to show that they belong to the previous footnote.
+
+        { some.code }
+
+    The whole paragraph can be indented, or just the first line. 
+    In this way, multi-paragraph footnotes work like multi-paragraph list items.
+
+This paragraph won't be part of the note, because it isn't indented.
+
+## Footnote examples
+
+Please vote on your favourite!
+
+:::{#footnotes}
+:::
+

site-unused/testing/footnotes/hover-only.qmd

@@ -0,0 +1,50 @@
+---
+title: "Hover only"
+subtitle: "Footnotes"
+search: false
+reference-location: document
+footnotes-hover: true
+---
+
+Hover only footnotes.
+
+## Beowulf: I
+
+Lesslie Hall translation[^1]:
+
+> Lo! the Spear-Danes'[^2] glory through splendid achievements
+>
+> The folk-kings' former fame we have heard of,
+> 
+> How princes displayed then their prowess-in-battle.
+> 
+> Oft Scyld the Scefing from scathers in numbers
+>
+> From many a people their mead-benches[^3] tore.
+
+Vivamus faucibus sed lorem vel dignissim. Duis ullamcorper, lorem ut cursus rutrum, elit orci lacinia nulla, in gravida lacus mauris ut sem. Vivamus urna erat, vulputate ut ex eu, pharetra lacinia velit. Quisque vehicula dolor ultricies nulla condimentum, eget auctor diam malesuada. Nullam ac nunc ultricies ligula luctus mattis. Etiam blandit, metus ac rhoncus molestie, ipsum tortor ultrices turpis, sed eleifend mauris diam ac velit. Orci varius natoque penatibus et magnis dis parturient montes, nascetur ridiculus mus. Nullam in lorem nec felis iaculis tincidunt vitae quis lorem. Nunc sed mauris rhoncus, lacinia nunc molestie, semper orci. Morbi consequat ipsum sed diam molestie, eget facilisis lorem efficitur. Donec lorem ligula, sollicitudin quis congue eu, commodo vel ipsum. Integer tortor tortor, varius ullamcorper mattis a, ultrices ac felis. Vivamus vitae orci eget odio lobortis lacinia vitae eu purus. Fusce et feugiat ligula. Etiam orci nisl, dictum in eleifend non, iaculis in sapien.
+
+Ut at ipsum lectus. Fusce nec vulputate urna. Quisque luctus metus enim, sed pulvinar augue fringilla non. Duis egestas eget ipsum eget rutrum. Cras vel nisl sit amet enim fringilla malesuada. Curabitur enim justo, ornare sit amet lacus vel, dictum auctor risus. Aenean ullamcorper eros sodales, pharetra diam non, condimentum enim.
+
+Cras eu sapien aliquet, accumsan massa eget, hendrerit ante. Nullam aliquam interdum nisl[^4], vel tristique lorem convallis a. Sed tristique nisi libero, egestas lobortis enim luctus sit amet. Integer sit amet lectus dui. Vestibulum interdum mi eget fermentum hendrerit. Maecenas ac augue accumsan, faucibus tellus vitae, aliquam elit. Quisque in varius urna. Mauris eget elementum diam, nec vehicula augue. Ut id ante sed massa fermentum pulvinar id vitae nulla. Mauris ac magna et massa maximus tempor a nec neque. Maecenas ligula turpis, mattis eget sodales eget, scelerisque a diam. Praesent gravida lacus quis sapien lacinia ullamcorper. Vestibulum nec pellentesque sem.
+
+::: {.callout}
+As you can see, this is a much cleaner experience overall both for the reader and the author.
+:::
+
+
+<!-- FOOTNOTES -->
+
+[^1]: [The Life and Death of Scyld](https://www.owleyes.org/text/beowulf/read/i#root-23)
+
+[^2]: The Danes are the residents of Denmark. The Hrothgar, Hrothulf, and Scylding dynasty of kings mentioned are actually spoken of in other Danish and Germanic sources (such as [the poem Widsith](https://en.wikipedia.org/wiki/Widsith)). <br></br>
+    
+    Some believe that Heorot, the hall of the Danes mentioned in Beowulf, was located on the island of Sjaelland, near the modern-day city of Roskilde, Denmark. 
+
+[^3]: These mead-benches came from mead-halls, which were fortresses and gathering places for medieval Norse and Germanic tribes. Members of society gathered there in safety under the king's protection so that they could feast, share stories, and receive gifts. <br></br>
+    
+    It is also notable that Valhalla and [Folkvang](https://en.wikipedia.org/wiki/F%C3%B3lkvangr), two divine mead-halls from Scandinavian mythology, are the places where dead souls go in the afterlife. The mead-hall is the center of society, making any attack on the hall, therefore, an assault upon the fabric of society itself.
+
+[^4]: Random note!
+
+

site-unused/testing/footnotes/margin-hover.qmd

@@ -0,0 +1,48 @@
+---
+title: "Margin & hover"
+subtitle: "Footnotes"
+search: false
+reference-location: margin
+footnotes-hover: true
+---
+
+Footnotes in the margin and with hover!
+
+## Beowulf: I
+
+Lesslie Hall translation[^1]:
+
+> Lo! the Spear-Danes'[^2] glory through splendid achievements
+>
+> The folk-kings' former fame we have heard of,
+> 
+> How princes displayed then their prowess-in-battle.
+> 
+> Oft Scyld the Scefing from scathers in numbers
+>
+> From many a people their mead-benches[^3] tore.
+
+Vivamus faucibus sed lorem vel dignissim. Duis ullamcorper, lorem ut cursus rutrum, elit orci lacinia nulla, in gravida lacus mauris ut sem. Vivamus urna erat, vulputate ut ex eu, pharetra lacinia velit. Quisque vehicula dolor ultricies nulla condimentum, eget auctor diam malesuada. Nullam ac nunc ultricies ligula luctus mattis. Etiam blandit, metus ac rhoncus molestie, ipsum tortor ultrices turpis, sed eleifend mauris diam ac velit. Orci varius natoque penatibus et magnis dis parturient montes, nascetur ridiculus mus. Nullam in lorem nec felis iaculis tincidunt vitae quis lorem. Nunc sed mauris rhoncus, lacinia nunc molestie, semper orci. Morbi consequat ipsum sed diam molestie, eget facilisis lorem efficitur. Donec lorem ligula, sollicitudin quis congue eu, commodo vel ipsum. Integer tortor tortor, varius ullamcorper mattis a, ultrices ac felis. Vivamus vitae orci eget odio lobortis lacinia vitae eu purus. Fusce et feugiat ligula. Etiam orci nisl, dictum in eleifend non, iaculis in sapien.
+
+Ut at ipsum lectus. Fusce nec vulputate urna. Quisque luctus metus enim, sed pulvinar augue fringilla non. Duis egestas eget ipsum eget rutrum. Cras vel nisl sit amet enim fringilla malesuada. Curabitur enim justo, ornare sit amet lacus vel, dictum auctor risus. Aenean ullamcorper eros sodales, pharetra diam non, condimentum enim.
+
+Cras eu sapien aliquet, accumsan massa eget, hendrerit ante. Nullam aliquam interdum nisl[^4], vel tristique lorem convallis a. Sed tristique nisi libero, egestas lobortis enim luctus sit amet. Integer sit amet lectus dui. Vestibulum interdum mi eget fermentum hendrerit. Maecenas ac augue accumsan, faucibus tellus vitae, aliquam elit. Quisque in varius urna. Mauris eget elementum diam, nec vehicula augue. Ut id ante sed massa fermentum pulvinar id vitae nulla. Mauris ac magna et massa maximus tempor a nec neque. Maecenas ligula turpis, mattis eget sodales eget, scelerisque a diam. Praesent gravida lacus quis sapien lacinia ullamcorper. Vestibulum nec pellentesque sem.
+
+::: {.callout}
+As you can see, this is a much cleaner experience and the notes auto-align with the section it references!
+:::
+
+
+<!-- FOOTNOTES -->
+
+[^1]: [The Life and Death of Scyld](https://www.owleyes.org/text/beowulf/read/i#root-23)
+
+[^2]: The Danes are the residents of Denmark. The Hrothgar, Hrothulf, and Scylding dynasty of kings mentioned are actually spoken of in other Danish and Germanic sources (such as [the poem Widsith](https://en.wikipedia.org/wiki/Widsith)). <br></br>
+    
+    Some believe that Heorot, the hall of the Danes mentioned in Beowulf, was located on the island of Sjaelland, near the modern-day city of Roskilde, Denmark. 
+
+[^3]: These mead-benches came from mead-halls, which were fortresses and gathering places for medieval Norse and Germanic tribes. Members of society gathered there in safety under the king's protection so that they could feast, share stories, and receive gifts. <br></br>
+    
+    It is also notable that Valhalla and [Folkvang](https://en.wikipedia.org/wiki/F%C3%B3lkvangr), two divine mead-halls from Scandinavian mythology, are the places where dead souls go in the afterlife. The mead-hall is the center of society, making any attack on the hall, therefore, an assault upon the fabric of society itself.
+
+[^4]: Random note!

site-unused/testing/footnotes/margin-only.qmd

@@ -0,0 +1,48 @@
+---
+title: "Margin only"
+subtitle: "Footnotes"
+search: false
+reference-location: margin
+footnotes-hover: false
+---
+
+Footnotes in the margin only, with no hover.
+
+## Beowulf: I
+
+Lesslie Hall translation[^1]:
+
+> Lo! the Spear-Danes'[^2] glory through splendid achievements
+>
+> The folk-kings' former fame we have heard of,
+> 
+> How princes displayed then their prowess-in-battle.
+> 
+> Oft Scyld the Scefing from scathers in numbers
+>
+> From many a people their mead-benches[^3] tore.
+
+Vivamus faucibus sed lorem vel dignissim. Duis ullamcorper, lorem ut cursus rutrum, elit orci lacinia nulla, in gravida lacus mauris ut sem. Vivamus urna erat, vulputate ut ex eu, pharetra lacinia velit. Quisque vehicula dolor ultricies nulla condimentum, eget auctor diam malesuada. Nullam ac nunc ultricies ligula luctus mattis. Etiam blandit, metus ac rhoncus molestie, ipsum tortor ultrices turpis, sed eleifend mauris diam ac velit. Orci varius natoque penatibus et magnis dis parturient montes, nascetur ridiculus mus. Nullam in lorem nec felis iaculis tincidunt vitae quis lorem. Nunc sed mauris rhoncus, lacinia nunc molestie, semper orci. Morbi consequat ipsum sed diam molestie, eget facilisis lorem efficitur. Donec lorem ligula, sollicitudin quis congue eu, commodo vel ipsum. Integer tortor tortor, varius ullamcorper mattis a, ultrices ac felis. Vivamus vitae orci eget odio lobortis lacinia vitae eu purus. Fusce et feugiat ligula. Etiam orci nisl, dictum in eleifend non, iaculis in sapien.
+
+Ut at ipsum lectus. Fusce nec vulputate urna. Quisque luctus metus enim, sed pulvinar augue fringilla non. Duis egestas eget ipsum eget rutrum. Cras vel nisl sit amet enim fringilla malesuada. Curabitur enim justo, ornare sit amet lacus vel, dictum auctor risus. Aenean ullamcorper eros sodales, pharetra diam non, condimentum enim.
+
+Cras eu sapien aliquet, accumsan massa eget, hendrerit ante. Nullam aliquam interdum nisl[^4], vel tristique lorem convallis a. Sed tristique nisi libero, egestas lobortis enim luctus sit amet. Integer sit amet lectus dui. Vestibulum interdum mi eget fermentum hendrerit. Maecenas ac augue accumsan, faucibus tellus vitae, aliquam elit. Quisque in varius urna. Mauris eget elementum diam, nec vehicula augue. Ut id ante sed massa fermentum pulvinar id vitae nulla. Mauris ac magna et massa maximus tempor a nec neque. Maecenas ligula turpis, mattis eget sodales eget, scelerisque a diam. Praesent gravida lacus quis sapien lacinia ullamcorper. Vestibulum nec pellentesque sem.
+
+::: {.callout}
+As you can see, this is a much cleaner experience and the notes auto-align with the section it references!
+:::
+
+
+<!-- FOOTNOTES -->
+
+[^1]: [The Life and Death of Scyld](https://www.owleyes.org/text/beowulf/read/i#root-23)
+
+[^2]: The Danes are the residents of Denmark. The Hrothgar, Hrothulf, and Scylding dynasty of kings mentioned are actually spoken of in other Danish and Germanic sources (such as [the poem Widsith](https://en.wikipedia.org/wiki/Widsith)). <br></br>
+    
+    Some believe that Heorot, the hall of the Danes mentioned in Beowulf, was located on the island of Sjaelland, near the modern-day city of Roskilde, Denmark. 
+
+[^3]: These mead-benches came from mead-halls, which were fortresses and gathering places for medieval Norse and Germanic tribes. Members of society gathered there in safety under the king's protection so that they could feast, share stories, and receive gifts. <br></br>
+    
+    It is also notable that Valhalla and [Folkvang](https://en.wikipedia.org/wiki/F%C3%B3lkvangr), two divine mead-halls from Scandinavian mythology, are the places where dead souls go in the afterlife. The mead-hall is the center of society, making any attack on the hall, therefore, an assault upon the fabric of society itself.
+
+[^4]: Random note!

site-unused/testing/footnotes/text-notes.qmd

@@ -0,0 +1,34 @@
+---
+title: "Text only, no numbering"
+subtitle: "Margin & hover"
+search: false
+reference-location: margin
+footnotes-hover: true
+---
+
+Margin and with hover (with no numbering)!
+
+## Beowulf: I
+
+Lesslie Hall translation^[[The Life and Death of Scyld](https://www.owleyes.org/text/beowulf/read/i#root-23)]:
+
+> Lo! the Spear-Danes'^[The Danes are the residents of Denmark. The Hrothgar, Hrothulf, and Scylding dynasty of kings mentioned are actually spoken of in other Danish and Germanic sources (such as [the poem Widsith](https://en.wikipedia.org/wiki/Widsith)).<br></br>Some believe that Heorot, the hall of the Danes mentioned in Beowulf, was located on the island of Sjaelland, near the modern-day city of Roskilde, Denmark.] glory through splendid achievements
+>
+> The folk-kings' former fame we have heard of,
+> 
+> How princes displayed then their prowess-in-battle.
+> 
+> Oft Scyld the Scefing from scathers in numbers
+>
+> From many a people their mead-benches^[These mead-benches came from mead-halls, which were fortresses and gathering places for medieval Norse and Germanic tribes. Members of society gathered there in safety under the king's protection so that they could feast, share stories, and receive gifts. <br></br>It is also notable that Valhalla and [Folkvang](https://en.wikipedia.org/wiki/F%C3%B3lkvangr), two divine mead-halls from Scandinavian mythology, are the places where dead souls go in the afterlife. The mead-hall is the center of society, making any attack on the hall, therefore, an assault upon the fabric of society itself.] tore.
+
+Vivamus faucibus sed lorem vel dignissim. Duis ullamcorper, lorem ut cursus rutrum, elit orci lacinia nulla, in gravida lacus mauris ut sem. Vivamus urna erat, vulputate ut ex eu, pharetra lacinia velit. Quisque vehicula dolor ultricies nulla condimentum, eget auctor diam malesuada. Nullam ac nunc ultricies ligula luctus mattis. Etiam blandit, metus ac rhoncus molestie, ipsum tortor ultrices turpis, sed eleifend mauris diam ac velit. Orci varius natoque penatibus et magnis dis parturient montes, nascetur ridiculus mus. Nullam in lorem nec felis iaculis tincidunt vitae quis lorem. Nunc sed mauris rhoncus, lacinia nunc molestie, semper orci. Morbi consequat ipsum sed diam molestie, eget facilisis lorem efficitur. Donec lorem ligula, sollicitudin quis congue eu, commodo vel ipsum. Integer tortor tortor, varius ullamcorper mattis a, ultrices ac felis. Vivamus vitae orci eget odio lobortis lacinia vitae eu purus. Fusce et feugiat ligula. Etiam orci nisl, dictum in eleifend non, iaculis in sapien.
+
+Ut at ipsum lectus. Fusce nec vulputate urna. Quisque luctus metus enim, sed pulvinar augue fringilla non. Duis egestas eget ipsum eget rutrum. Cras vel nisl sit amet enim fringilla malesuada. Curabitur enim justo, ornare sit amet lacus vel, dictum auctor risus. Aenean ullamcorper eros sodales, pharetra diam non, condimentum enim.
+
+Cras eu sapien aliquet, accumsan massa eget, hendrerit ante. Nullam aliquam interdum nisl^[Random note!], vel tristique lorem convallis a. Sed tristique nisi libero, egestas lobortis enim luctus sit amet. Integer sit amet lectus dui. Vestibulum interdum mi eget fermentum hendrerit. Maecenas ac augue accumsan, faucibus tellus vitae, aliquam elit. Quisque in varius urna. Mauris eget elementum diam, nec vehicula augue. Ut id ante sed massa fermentum pulvinar id vitae nulla. Mauris ac magna et massa maximus tempor a nec neque. Maecenas ligula turpis, mattis eget sodales eget, scelerisque a diam. Praesent gravida lacus quis sapien lacinia ullamcorper. Vestibulum nec pellentesque sem.
+
+::: {.callout}
+This is not as clean of an authoring experience, as now the footnotes are bungled up within the body text instead of being neatly bunched down at the bottom (and searchable by number).
+:::
+

site/_quarto.yml

@@ -2,6 +2,9 @@ project:
   type: website
   post-render: make python-docs
 website:
+  announcement: 
+    content: "[**{{< fa graduation-cap >}} ValidMind Academy**](/training/training-overview.qmd) — Gain hands-on experience and explore what ValidMind has to offer with our training environment." 
+    position: below-navbar 
   favicon: validmind.png
   title: "ValidMind"
   cookie-consent:
@@ -20,6 +23,7 @@ website:
   repo-actions: [edit, issue]
 
   navbar:
+    collapse-below: xl
     logo: about/ValidMind-logo-color.svg
     background: white
     title: false
@@ -66,6 +70,10 @@ website:
         file: https://validmind.com/
         target: _blank
 
+#  COMMENT THIS OUT WHEN DONE TESTING
+#       - text: "{{< fa flask >}} Testing"
+#         file: internal/testing.qmd
+
   sidebar: 
     - title: "Home"
       style: docked
@@ -276,6 +284,19 @@ website:
         - text: "---"
         - support/troubleshooting.qmd
 
+# COMMENT THIS OUT WHEN DONE TESTING
+#     - title: "Testing"
+#       contents:
+#         - internal/testing.qmd
+#         - text: "---"
+#         - text: "EXPERIMENTS"
+#         - file: internal/footnotes/footnotes.qmd
+#           contents:
+#             - internal/footnotes/hover-only.qmd
+#             - internal/footnotes/margin-only.qmd
+#             - internal/footnotes/margin-hover.qmd
+#             - internal/footnotes/text-notes.qmd
+
   page-footer:
     background: "#DE257E"
     left: "© Copyright 2023-2024 ValidMind Inc. All Rights Reserved."
@@ -294,6 +315,8 @@ website:
 
 format:
   html:
+    footnotes-hover: true
+    reference-location: margin
     include-in-header: 
       - heap-production.html
     code-overflow: wrap