feat: syllabus

juananpe · Apr 1, 2024 · 3745d05 · 3745d05
1 parent 7931531
commit 3745d05
Show file tree

Hide file tree

Showing 16 changed files with 89 additions and 23 deletions.
diff --git a/docs/bib/index.html b/docs/bib/index.html
@@ -11,7 +11,8 @@
   <body>
     <main>
       <h1>Bibliography</h1>
-<div class="row notex">
+
+      <div class="row notex">
   <div class="col-1 left">
     <a href="../conduct/">&lArr;</a>
   </div>
@@ -23,6 +24,7 @@ <h1>Bibliography</h1>
   </div>
 </div>
 
+
       <dl class="bibliography">
 
 <dt id="Wilson2019">Wilson2019</dt>

diff --git a/docs/colophon/index.html b/docs/colophon/index.html
@@ -11,7 +11,8 @@
   <body>
     <main>
       <h1>Colophon</h1>
-<div class="row notex">
+
+      <div class="row notex">
   <div class="col-1 left">
     <a href="../glossary/">&lArr;</a>
   </div>
@@ -23,6 +24,7 @@ <h1>Colophon</h1>
   </div>
 </div>
 
+
       <ul>
 <li>
 <p>The tutorial text uses <a href="https://brailleinstitute.org/freefont">Atkinson Hyperlegible</a>,
@@ -37,8 +39,10 @@ <h1>Colophon</h1>
 <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>,
+<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>.</p>
+</li>
+<li>
+<p>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>

diff --git a/docs/conduct/index.html b/docs/conduct/index.html
@@ -11,7 +11,8 @@
   <body>
     <main>
       <h1>Code of Conduct</h1>
-<div class="row notex">
+
+      <div class="row notex">
   <div class="col-1 left">
     <a href="../license/">&lArr;</a>
   </div>
@@ -23,6 +24,7 @@ <h1>Code of Conduct</h1>
   </div>
 </div>
 
+
       <p>In the interest of fostering an open and welcoming environment, we as
 contributors and maintainers pledge to making participation in our project and
 our community a harassment-free experience for everyone, regardless of age, body

diff --git a/docs/finale/index.html b/docs/finale/index.html
@@ -11,7 +11,8 @@
   <body>
     <main>
       <h1>Conclusion</h1>
-<div class="row notex">
+
+      <div class="row notex">
   <div class="col-1 left">
     <a href="../intro/">&lArr;</a>
   </div>
@@ -23,6 +24,11 @@ <h1>Conclusion</h1>
   </div>
 </div>
 
+      <ul class="keypoints">
+<li>Well-designed software is easy to build and maintain as well as easy to use.</li>
+<li>We hope this is the start of your journey, not its end.</li>
+<li>Start where you are, use what you have, help who you can.</li>
+</ul>
       <ul>
 <li>Reference to introduction <a href="../intro/">Chapter&nbsp;1</a></li>
 <li>Reference to glossary <a href="../glossary/">Appendix&nbsp;D</a></li>

diff --git a/docs/glossary/index.html b/docs/glossary/index.html
@@ -11,7 +11,8 @@
   <body>
     <main>
       <h1>Glossary</h1>
-<div class="row notex">
+
+      <div class="row notex">
   <div class="col-1 left">
     <a href="../bib/">&lArr;</a>
   </div>
@@ -23,6 +24,7 @@ <h1>Glossary</h1>
   </div>
 </div>
 
+
       <dl class="glossary">
 <dt id="g:ssg">static site generator (SSG)</dt><dd>An application that generates HTML pages from templates.</dd>
 </dl>

diff --git a/docs/index.html b/docs/index.html
@@ -11,7 +11,8 @@
   <body>
     <main>
       <h1>McCole Template</h1>
-<div class="row notex">
+
+      <div class="row notex">
   <div class="col-1 left">
 
   </div>
@@ -23,6 +24,7 @@ <h1>McCole Template</h1>
   </div>
 </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><li><a href="colophon/">Colophon</a></li></ol>
 

diff --git a/docs/intro/index.html b/docs/intro/index.html
@@ -11,7 +11,8 @@
   <body>
     <main>
       <h1>Introduction</h1>
-<div class="row notex">
+
+      <div class="row notex">
   <div class="col-1 left">
 
   </div>
@@ -23,6 +24,10 @@ <h1>Introduction</h1>
   </div>
 </div>
 
+      <ul class="keypoints">
+<li>Best way to learn design is through examples.</li>
+<li>All material is available under open licenses, and all royalties go to charity.</li>
+</ul>
       <ul>
 <li>Reference to conclusion <a href="../finale/">Chapter&nbsp;2</a></li>
 <li>Reference to license <a href="../license/">Appendix&nbsp;A</a></li>

diff --git a/docs/license/index.html b/docs/license/index.html
@@ -11,7 +11,8 @@
   <body>
     <main>
       <h1>License</h1>
-<div class="row notex">
+
+      <div class="row notex">
   <div class="col-1 left">
     <a href="../finale/">&lArr;</a>
   </div>
@@ -23,6 +24,7 @@ <h1>License</h1>
   </div>
 </div>
 
+
       <p>All of the written material is made available under the Creative
 Commons - Attribution - NonCommercial 4.0 International license (CC-BY-NC-4.0),
 while the software is made available under the Hippocratic License.</p>

diff --git a/docs/mccole.css b/docs/mccole.css
@@ -132,3 +132,9 @@ th, td {
     vertical-align: top;
     border: solid var(--border-thin) var(--gray-light);
 }
+
+/* Key points listing at chapter start. */
+ul.keypoints {
+    background-color: var(--gray-light);
+    border: var(--border-medium) var(--gray-dark) solid;
+}
diff --git a/lib/mccole/extensions/filters.py b/lib/mccole/extensions/filters.py
@@ -12,6 +12,25 @@ def is_chapter(node):
     return node.slug and node.slug in ark.site.config["chapters"]
 
 
+@ibis.filters.register("keypoints")
+def keypoints(node):
+    """Construct key points listing for chapter."""
+    if (not node.slug) or (node.slug not in ark.site.config["chapters"]):
+        return ""
+    metadata = ark.site.config["_meta_"]
+    util.require(
+        node.slug in metadata,
+        f"Slug {node.slug} not in metadata",
+    )
+    util.require(
+        "syllabus" in metadata[node.slug],
+        f"No syllabus for {node.slug} in metadata",
+    )
+    points = [util.markdownify(p) for p in metadata[node.slug]["syllabus"]]
+    points = "\n".join([f"<li>{p}</li>" for p in points])
+    return f'<ul class="keypoints">\n{points}\n</ul>'
+
+
 @ibis.filters.register("nav_next")
 def nav_next(node):
     """Create next-page link."""
@@ -31,11 +50,12 @@ def tagline(node):
         node.slug in ark.site.config["chapters"],
         f"bad tagline request: {node.path} is not a chapter",
     )
+    metadata = ark.site.config["_meta_"]
     util.require(
-        node.slug in ark.site.config["_meta_"],
+        node.slug in metadata,
         f"no metadata for {node.path}",
     )
-    return util.markdownify(ark.site.config["_meta_"][node.slug].get("tagline"))
+    return util.markdownify(metadata[node.slug].get("tagline"))
 
 
 def _nav_link(node, kind):

diff --git a/lib/mccole/resources/mccole.css b/lib/mccole/resources/mccole.css
@@ -132,3 +132,9 @@ th, td {
     vertical-align: top;
     border: solid var(--border-thin) var(--gray-light);
 }
+
+/* Key points listing at chapter start. */
+ul.keypoints {
+    background-color: var(--gray-light);
+    border: var(--border-medium) var(--gray-dark) solid;
+}
diff --git a/lib/mccole/templates/node.ibis b/lib/mccole/templates/node.ibis
@@ -6,6 +6,8 @@
   <body>
     <main>
       {% include "title.html" %}
+      {% include "prevnext.html" %}
+      {{ node | keypoints }}
       {{ node.html }}
     </main>
     {% include "foot.html" %}

diff --git a/lib/mccole/templates/prevnext.html b/lib/mccole/templates/prevnext.html
@@ -0,0 +1,11 @@
+<div class="row notex">
+  <div class="col-1 left">
+    {{node | nav_prev }}
+  </div>
+  <div class="col-10 center">
+    {% if node | is_chapter %}<span class="tagline">{{ node | tagline }}</span>{% endif %}
+  </div>
+  <div class="col-1 right">
+    {{node | nav_next }}
+  </div>
+</div>
diff --git a/lib/mccole/templates/title.html b/lib/mccole/templates/title.html
@@ -1,12 +1 @@
 <h1>{% if node.title %}{{ node.title }}{% else %}{{ site.title }}{% endif %}</h1>
-<div class="row notex">
-  <div class="col-1 left">
-    {{node | nav_prev }}
-  </div>
-  <div class="col-10 center">
-    {% if node | is_chapter %}<span class="tagline">{{ node | tagline }}</span>{% endif %}
-  </div>
-  <div class="col-1 right">
-    {{node | nav_next }}
-  </div>
-</div>
diff --git a/src/finale/index.md b/src/finale/index.md
@@ -1,6 +1,10 @@
 ---
 title: "Conclusion"
 tagline: "What we've covered and where you might go next."
+syllabus:
+-   "Well-designed software is easy to build and maintain as well as easy to use."
+-   "We hope this is the start of your journey, not its end."
+-   "Start where you are, use what you have, help who you can."
 ---
 
 -   Reference to introduction [%x intro %]

diff --git a/src/intro/index.md b/src/intro/index.md
@@ -1,6 +1,9 @@
 ---
 title: "Introduction"
 tagline: "Where we're going and why."
+syllabus:
+-   "Best way to learn design is through examples."
+-   "All material is available under open licenses, and all royalties go to charity."
 ---
 
 -   Reference to conclusion [%x finale %]