feat: titles and navigation links

twitwi · Apr 1, 2024 · a514560 · a514560
1 parent ee164d3
commit a514560
Show file tree

Hide file tree

Showing 18 changed files with 255 additions and 4 deletions.
diff --git a/README.md b/README.md
@@ -80,5 +80,13 @@ A template for [Ark][ark]-based tutorials.
     1.  Add examples of figures and tables (and references) to `src/intro/index.md` and `src/finale/index.md`.
     1.  Move localization into `lib/mccole/extensions/util.py`.
 
+1.  Add navigation links and a proper title.
+    1.  Collect all metadata in `lib/mccole/extensions/batch.py`.
+    1.  Add `lib/mccole/templates/title.html` to format title and prev/next navigation links.
+    1.  Include `title.html` in `lib/mccole/templates/node.ibis`.
+    1.  Add `lib/mccole/extensions/filters.py` with various filters required by template additions.
+    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.
+
 [ark]: https://www.dmulholl.com/docs/ark/main/
 [glosario]: https://glosario.carpentries.org/
diff --git a/docs/bib/index.html b/docs/bib/index.html
@@ -10,6 +10,19 @@
   </head>
   <body>
     <main>
+      <h1>Bibliography</h1>
+<div class="row notex">
+  <div class="col-1 left">
+    <a href="../conduct/">&lArr;</a>
+  </div>
+  <div class="col-10 center">
+
+  </div>
+  <div class="col-1 right">
+    <a href="../glossary/">&rArr;</a>
+  </div>
+</div>
+
       <dl class="bibliography">
 
 <dt id="Wilson2019">Wilson2019</dt>

diff --git a/docs/conduct/index.html b/docs/conduct/index.html
@@ -11,7 +11,19 @@
   <body>
     <main>
       <h1>Code of Conduct</h1>
-<p>In the interest of fostering an open and welcoming environment, we as
+<div class="row notex">
+  <div class="col-1 left">
+    <a href="../license/">&lArr;</a>
+  </div>
+  <div class="col-10 center">
+
+  </div>
+  <div class="col-1 right">
+    <a href="../bib/">&rArr;</a>
+  </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
 size, disability, ethnicity, gender identity and expression, level of

diff --git a/docs/finale/index.html b/docs/finale/index.html
@@ -10,6 +10,19 @@
   </head>
   <body>
     <main>
+      <h1>Conclusion</h1>
+<div class="row notex">
+  <div class="col-1 left">
+    <a href="../intro/">&lArr;</a>
+  </div>
+  <div class="col-10 center">
+    <span class="tagline">What we&rsquo;ve covered and where you might go next.</span>
+  </div>
+  <div class="col-1 right">
+    <a href="../license/">&rArr;</a>
+  </div>
+</div>
+
       <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
@@ -10,6 +10,19 @@
   </head>
   <body>
     <main>
+      <h1>Glossary</h1>
+<div class="row notex">
+  <div class="col-1 left">
+    <a href="../bib/">&lArr;</a>
+  </div>
+  <div class="col-10 center">
+
+  </div>
+  <div class="col-1 right">
+
+  </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
@@ -10,6 +10,19 @@
   </head>
   <body>
     <main>
+      <h1>McCole Template</h1>
+<div class="row notex">
+  <div class="col-1 left">
+
+  </div>
+  <div class="col-10 center">
+
+  </div>
+  <div class="col-1 right">
+
+  </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></ol>
 

diff --git a/docs/intro/index.html b/docs/intro/index.html
@@ -10,6 +10,19 @@
   </head>
   <body>
     <main>
+      <h1>Introduction</h1>
+<div class="row notex">
+  <div class="col-1 left">
+
+  </div>
+  <div class="col-10 center">
+    <span class="tagline">Where we&rsquo;re going and why.</span>
+  </div>
+  <div class="col-1 right">
+    <a href="../finale/">&rArr;</a>
+  </div>
+</div>
+
       <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,19 @@
   <body>
     <main>
       <h1>License</h1>
-<p>All of the written material is made available under the Creative
+<div class="row notex">
+  <div class="col-1 left">
+    <a href="../finale/">&lArr;</a>
+  </div>
+  <div class="col-10 center">
+
+  </div>
+  <div class="col-1 right">
+    <a href="../conduct/">&rArr;</a>
+  </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>
 <h2>Writing</h2>

diff --git a/docs/mccole.css b/docs/mccole.css
@@ -27,6 +27,39 @@
     --spacing-large: 1rem;
 }
 
+/* Flex grid */
+.row {
+    display: flex;
+    flex-flow: row wrap;
+    width: 100%
+}
+.row > * {
+  flex: 1; /* allow children to grow when space available */
+}
+.col-1 { flex-basis: 8.33%; }
+.col-2 { flex-basis: 16.66%; }
+.col-3 { flex-basis: 25%; }
+.col-4 { flex-basis: 33.33%; }
+.col-5 { flex-basis: 41.66%; }
+.col-6 { flex-basis: 50%; }
+.col-7 { flex-basis: 58.33%; }
+.col-8 { flex-basis: 66.66%; }
+.col-9 { flex-basis: 75%; }
+.col-10 { flex-basis: 83.33%; }
+.col-11 { flex-basis: 91.66%; }
+.col-12 { flex-basis: 100%; }
+
+/* Generic positioning */
+.left {
+    text-align: left;
+}
+.right {
+    text-align: right;
+}
+.center {
+    text-align: center;
+}
+
 /* Overall document body */
 body {
     max-width: var(--width-page);

diff --git a/lib/mccole/extensions/batch.py b/lib/mccole/extensions/batch.py
@@ -14,6 +14,7 @@ def init_build():
     """Launch startup tasks in order."""
     _init_date()
     _number_contents()
+    _collect_metadata()
     _collect_titles()
     _collect_targets()
 
@@ -32,6 +33,19 @@ def filter_files(value, filepath):
     return result
 
 
+def _collect_metadata():
+    """Collect all metadata from nodes."""
+
+    metadata = {}
+
+    def _visitor(node):
+        slug = node.slug if node.slug else "@root"
+        metadata[slug] = node.meta
+
+    ark.nodes.root().walk(_visitor)
+    ark.site.config["_meta_"] = metadata
+
+
 def _collect_targets():
     """Collect targets of numbered cross-references."""
 

diff --git a/lib/mccole/extensions/filters.py b/lib/mccole/extensions/filters.py
@@ -0,0 +1,59 @@
+"""Page elements."""
+
+import ark
+import ibis
+
+import util
+
+
+@ibis.filters.register("is_chapter")
+def is_chapter(node):
+    """Is this a chapter node (vs. appendix)?"""
+    return node.slug and node.slug in ark.site.config["chapters"]
+
+
+@ibis.filters.register("nav_next")
+def nav_next(node):
+    """Create next-page link."""
+    return _nav_link(node, "next")
+
+
+@ibis.filters.register("nav_prev")
+def nav_prev(node):
+    """Create previous-page link."""
+    return _nav_link(node, "prev")
+
+
+@ibis.filters.register("tagline")
+def tagline(node):
+    """Insert chapter tagline (must exist)."""
+    util.require(
+        node.slug in ark.site.config["chapters"],
+        f"bad tagline request: {node.path} is not a chapter",
+    )
+    util.require(
+        node.slug in ark.site.config["_meta_"],
+        f"no metadata for {node.path}",
+    )
+    return util.markdownify(ark.site.config["_meta_"][node.slug].get("tagline"))
+
+
+def _nav_link(node, kind):
+    """Generate previous/next page links."""
+    if not node.slug:
+        return ""
+    contents = ark.site.config["chapters"] + ark.site.config["appendices"]
+    try:
+        where = contents.index(node.slug)
+    except ValueError:
+        util.fail(f"unknown slug {node.slug} in {node.path}")
+    if kind == "prev":
+        if where == 0:
+            return ""
+        return f'<a href="@root/{contents[where - 1]}/">&lArr;</a>'
+    elif kind == "next":
+        if where == (len(contents) - 1):
+            return ""
+        return f'<a href="@root/{contents[where + 1]}/">&rArr;</a>'
+    else:
+        util.fail(f"Unknown nav link type '{kind}' in {node.path}")
diff --git a/lib/mccole/resources/mccole.css b/lib/mccole/resources/mccole.css
@@ -27,6 +27,39 @@
     --spacing-large: 1rem;
 }
 
+/* Flex grid */
+.row {
+    display: flex;
+    flex-flow: row wrap;
+    width: 100%
+}
+.row > * {
+  flex: 1; /* allow children to grow when space available */
+}
+.col-1 { flex-basis: 8.33%; }
+.col-2 { flex-basis: 16.66%; }
+.col-3 { flex-basis: 25%; }
+.col-4 { flex-basis: 33.33%; }
+.col-5 { flex-basis: 41.66%; }
+.col-6 { flex-basis: 50%; }
+.col-7 { flex-basis: 58.33%; }
+.col-8 { flex-basis: 66.66%; }
+.col-9 { flex-basis: 75%; }
+.col-10 { flex-basis: 83.33%; }
+.col-11 { flex-basis: 91.66%; }
+.col-12 { flex-basis: 100%; }
+
+/* Generic positioning */
+.left {
+    text-align: left;
+}
+.right {
+    text-align: right;
+}
+.center {
+    text-align: center;
+}
+
 /* Overall document body */
 body {
     max-width: var(--width-page);

diff --git a/lib/mccole/templates/node.ibis b/lib/mccole/templates/node.ibis
@@ -5,6 +5,7 @@
   </head>
   <body>
     <main>
+      {% include "title.html" %}
       {{ node.html }}
     </main>
     {% include "foot.html" %}

diff --git a/lib/mccole/templates/title.html b/lib/mccole/templates/title.html
@@ -0,0 +1,12 @@
+<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/conduct/index.md b/src/conduct/index.md
@@ -2,4 +2,4 @@
 title: "Code of Conduct"
 ---
 
-[% rootfile "CODE_OF_CONDUCT.md" strip=False %]
+[% rootfile "CODE_OF_CONDUCT.md" %]
diff --git a/src/finale/index.md b/src/finale/index.md
@@ -1,5 +1,6 @@
 ---
 title: "Conclusion"
+tagline: "What we've covered and where you might go next."
 ---
 
 -   Reference to introduction [%x intro %]

diff --git a/src/intro/index.md b/src/intro/index.md
@@ -1,5 +1,6 @@
 ---
 title: "Introduction"
+tagline: "Where we're going and why."
 ---
 
 -   Reference to conclusion [%x finale %]

diff --git a/src/license/index.md b/src/license/index.md
@@ -2,4 +2,4 @@
 title: "License"
 ---
 
-[% rootfile "LICENSE.md" strip=False %]
+[% rootfile "LICENSE.md" %]
-Original file line number
+Diff line change
@@ Expand Up / @@ -5,6 +5,7 @@ @@
       </head>
       <body>
         <main>
+          {% include "title.html" %}
           {{ node.html }}
         </main>
         {% include "foot.html" %}
@@ Expand Down @@