feat: standard links on all pages

juananpe · Apr 1, 2024 · 7931531 · 7931531
1 parent 4218aef
commit 7931531
Show file tree

Hide file tree

Showing 9 changed files with 146 additions and 2 deletions.
diff --git a/README.md b/README.md
@@ -88,5 +88,11 @@ A template for [Ark][ark]-based tutorials.
     1.  Add flex grid to `lib/mccole/resources/mccole.css`.
     1.  Modify `src/license/index.md` and `src/conduct/index.md` to strip inherited title of root pages.
 
+1.  Add links to pages.
+    1.  Add `info/links.yml` with link definitions.
+    1.  Add `ensure_links` function to `lib/mccole/extensions/util.py` to load and format links.
+    1.  Add `_append_links` function to `lib/mccole/extensions/batch.py` to append link text to files.
+    1.  Add `src/colophon/index.md` to display credits.
+
 [ark]: https://www.dmulholl.com/docs/ark/main/
 [glosario]: https://glosario.carpentries.org/
diff --git a/config.py b/config.py
@@ -18,6 +18,7 @@
     "conduct",
     "bib",
     "glossary",
+    "colophon",
 ]
 
 # What to copy.

diff --git a/docs/colophon/index.html b/docs/colophon/index.html
@@ -0,0 +1,55 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8">
+<meta name="viewport" content="width=device-width, initial-scale=1.0">
+<link rel="icon" href="../logo.svg">
+<link rel="stylesheet" href="../mccole.css" type="text/css">
+<title>McCole Template &middot; Colophon</title>
+
+  </head>
+  <body>
+    <main>
+      <h1>Colophon</h1>
+<div class="row notex">
+  <div class="col-1 left">
+    <a href="../glossary/">&lArr;</a>
+  </div>
+  <div class="col-10 center">
+
+  </div>
+  <div class="col-1 right">
+
+  </div>
+</div>
+
+      <ul>
+<li>
+<p>The tutorial text uses <a href="https://brailleinstitute.org/freefont">Atkinson Hyperlegible</a>,
+    which was designed to be easy for people with impaired vision to read.
+    Code uses Source Code Pro and diagrams use Helvetica.</p>
+</li>
+<li>
+<p>The CSS files used to style code were obtained from <a href="https://numist.github.io/highlight-css/">highlight-css</a>;
+    legibility was checked using <a href="https://wave.webaim.org/">WebAIM WAVE</a>.</p>
+</li>
+<li>
+<p>Diagrams were created with the desktop version of <a href="https://www.drawio.com/">draw.io</a>.</p>
+</li>
+<li>
+<p>The site is built using <a href="https://www.dmulholl.com/docs/ark/main/">Ark</a> and hosted on <a href="https://pages.github.com/">GitHub Pages</a>.
+    Traffic statistics are collected using <a href="https://plausible.io/">plausible.io</a>,
+    which provides a lightweight ethical alternative to surveillance capitalism.</p>
+</li>
+</ul>
+    </main>
+    <footer>
+  © 2024 <a href="https://third-bit.com/">Greg Wilson</a>
+  &middot;
+  <a href="https://github.com/gvwilson/mccole">repository</a>
+  &middot;
+  <a href="../license/">license</a>
+</footer>
+
+  </body>
+</html>
diff --git a/docs/glossary/index.html b/docs/glossary/index.html
@@ -19,7 +19,7 @@ <h1>Glossary</h1>
 
   </div>
   <div class="col-1 right">
-
+    <a href="../colophon/">&rArr;</a>
   </div>
 </div>
 

diff --git a/docs/index.html b/docs/index.html
@@ -24,7 +24,7 @@ <h1>McCole Template</h1>
 </div>
 
       <ol class="toc-chapters"><li><a href="intro/">Introduction</a></li><li><a href="finale/">Conclusion</a></li></ol>
-<ol class="toc-appendices"><li><a href="license/">License</a></li><li><a href="conduct/">Code of Conduct</a></li><li><a href="bib/">Bibliography</a></li><li><a href="glossary/">Glossary</a></li></ol>
+<ol class="toc-appendices"><li><a href="license/">License</a></li><li><a href="conduct/">Code of Conduct</a></li><li><a href="bib/">Bibliography</a></li><li><a href="glossary/">Glossary</a></li><li><a href="colophon/">Colophon</a></li></ol>
 
 <ul>
 <li>Glossary reference: <a class="gl-ref" href="glossary/#gl:ssg" markdown="1">static site generator text</a></li>

diff --git a/info/links.yml b/info/links.yml
@@ -0,0 +1,39 @@
+# A
+
+- key: "ark"
+  url: "https://www.dmulholl.com/docs/ark/main/"
+  title: "Ark static site generator"
+
+- key: "atkinson"
+  url: "https://brailleinstitute.org/freefont"
+  title: "Atkinson Hyperlegible font"
+
+# D
+
+- key: "draw_io"
+  url: "https://www.drawio.com/"
+  title: "draw.io"
+
+# G
+
+- key: "ghp"
+  url: "https://pages.github.com/"
+  title: "GitHub Pages"
+
+# H
+
+- key: "highlight_css"
+  url: "https://numist.github.io/highlight-css/"
+  title: "highlight-css"
+
+# P
+
+- key: "plausible"
+  url: "https://plausible.io/"
+  title: "Plausible"
+
+# W
+
+- key: "wave"
+  url: "https://wave.webaim.org/"
+  title: "WebAIM WAVE"
diff --git a/lib/mccole/extensions/batch.py b/lib/mccole/extensions/batch.py
@@ -16,6 +16,7 @@ def init_build():
     _collect_metadata()
     _decorate_metadata()
     _collect_targets()
+    _append_links()
 
 
 @ark.events.register(ark.events.Event.EXIT_BUILD)
@@ -31,6 +32,18 @@ def filter_files(value, filepath):
     return result
 
 
+def _append_links():
+    """Add links to node text."""
+    util.ensure_links()
+    links_block = ark.site.config["_links_block_"]
+
+    def _visitor(node):
+        if (node.ext == "md"):
+            node.text += "\n\n" + links_block
+
+    ark.nodes.root().walk(_visitor)
+
+
 def _collect_metadata():
     """Collect all metadata from nodes."""
     metadata = {}

diff --git a/lib/mccole/extensions/util.py b/lib/mccole/extensions/util.py
@@ -5,6 +5,7 @@
 from pathlib import Path
 import re
 import sys
+import yaml
 
 
 # Names of parts.
@@ -32,6 +33,18 @@ def allowed(kwargs, allowed):
     return set(kwargs.keys()).issubset(allowed)
 
 
+def ensure_links():
+    """Load links and create appendable text."""
+    if "_links_" in ark.site.config:
+        return
+    filepath = Path(ark.site.home(), "info", "links.yml")
+    links = yaml.safe_load(filepath.read_text()) or []
+    ark.site.config["_links_"] = {lnk["key"]: lnk for lnk in links}
+    ark.site.config["_links_block_"] = "\n".join(
+        f"[{key}]: {value['url']}" for key, value in ark.site.config["_links_"].items()
+    )
+
+
 def fail(msg):
     """Fail unilaterally."""
     print(msg, file=sys.stderr)

diff --git a/src/colophon/index.md b/src/colophon/index.md
@@ -0,0 +1,17 @@
+---
+title: Colophon
+---
+
+-   The tutorial text uses [Atkinson Hyperlegible][atkinson],
+    which was designed to be easy for people with impaired vision to read.
+    Code uses Source Code Pro and diagrams use Helvetica.
+
+-   The CSS files used to style code were obtained from [highlight-css][highlight_css];
+    legibility was checked using [WebAIM WAVE][wave].
+
+-   Diagrams were created with the desktop version of [draw.io][draw_io].
+
+-   The site is built using [Ark][ark] and hosted on [GitHub Pages][ghp].
+
+-   Traffic statistics are collected using [plausible.io][plausible],
+    which provides a lightweight ethical alternative to surveillance capitalism.
-Original file line number
+Diff line change
@@ Expand Up / @@ -19,7 +19,7 @@ <h1>Glossary</h1> @@
       </div>
       <div class="col-1 right">
+        <a href="../colophon/">&rArr;</a>
       </div>
     </div>
@@ Expand Down @@