From 3745d05b20c3c38c0163e4b26e2040402e46f651 Mon Sep 17 00:00:00 2001 From: Greg Wilson Date: Mon, 1 Apr 2024 19:48:35 -0400 Subject: [PATCH] feat: syllabus --- docs/bib/index.html | 4 +++- docs/colophon/index.html | 10 +++++++--- docs/conduct/index.html | 4 +++- docs/finale/index.html | 8 +++++++- docs/glossary/index.html | 4 +++- docs/index.html | 4 +++- docs/intro/index.html | 7 ++++++- docs/license/index.html | 4 +++- docs/mccole.css | 6 ++++++ lib/mccole/extensions/filters.py | 24 ++++++++++++++++++++++-- lib/mccole/resources/mccole.css | 6 ++++++ lib/mccole/templates/node.ibis | 2 ++ lib/mccole/templates/prevnext.html | 11 +++++++++++ lib/mccole/templates/title.html | 11 ----------- src/finale/index.md | 4 ++++ src/intro/index.md | 3 +++ 16 files changed, 89 insertions(+), 23 deletions(-) create mode 100644 lib/mccole/templates/prevnext.html diff --git a/docs/bib/index.html b/docs/bib/index.html index b596117..4530b2a 100644 --- a/docs/bib/index.html +++ b/docs/bib/index.html @@ -11,7 +11,8 @@

Bibliography

-
+ +
⇐
@@ -23,6 +24,7 @@

Bibliography

+
Wilson2019
diff --git a/docs/colophon/index.html b/docs/colophon/index.html index fe2d497..c90b616 100644 --- a/docs/colophon/index.html +++ b/docs/colophon/index.html @@ -11,7 +11,8 @@

Colophon

-
+ +
⇐
@@ -23,6 +24,7 @@

Colophon

+

  • The tutorial text uses Atkinson Hyperlegible, @@ -37,8 +39,10 @@

    Colophon

    Diagrams were created with the desktop version of draw.io.

  • -

    The site is built using Ark and hosted on GitHub Pages. - Traffic statistics are collected using plausible.io, +

    The site is built using Ark and hosted on GitHub Pages.

    +
    • +
  • +

    Traffic statistics are collected using plausible.io, which provides a lightweight ethical alternative to surveillance capitalism.

diff --git a/docs/conduct/index.html b/docs/conduct/index.html index c10ecc9..dc48ba8 100644 --- a/docs/conduct/index.html +++ b/docs/conduct/index.html @@ -11,7 +11,8 @@

Code of Conduct

-
+ +
⇐
@@ -23,6 +24,7 @@

Code of Conduct

+

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 index 7165071..9ea986b 100644 --- a/docs/finale/index.html +++ b/docs/finale/index.html @@ -11,7 +11,8 @@

Conclusion

-
+ +
⇐
@@ -23,6 +24,11 @@

Conclusion

+
    +
  • 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 Chapter 1
  • Reference to glossary Appendix D
    • diff --git a/docs/glossary/index.html b/docs/glossary/index.html index 4b1c1cb..b627912 100644 --- a/docs/glossary/index.html +++ b/docs/glossary/index.html @@ -11,7 +11,8 @@

    Glossary

    -
    + +
    ⇐
    @@ -23,6 +24,7 @@

    Glossary

    +
    static site generator (SSG)
    An application that generates HTML pages from templates.
    diff --git a/docs/index.html b/docs/index.html index de0427f..3ee8ef8 100644 --- a/docs/index.html +++ b/docs/index.html @@ -11,7 +11,8 @@

    McCole Template

    -
    + +
    @@ -23,6 +24,7 @@

    McCole Template

    +
    1. Introduction
    2. Conclusion
    1. License
    2. Code of Conduct
    3. Bibliography
    4. Glossary
    5. Colophon
    diff --git a/docs/intro/index.html b/docs/intro/index.html index bdfd466..69bb317 100644 --- a/docs/intro/index.html +++ b/docs/intro/index.html @@ -11,7 +11,8 @@

    Introduction

    -
    + +
    @@ -23,6 +24,10 @@

    Introduction

    +
      +
    • Best way to learn design is through examples.
      • +
    • All material is available under open licenses, and all royalties go to charity.
      • +
    • Reference to conclusion Chapter 2
    • Reference to license Appendix A
      • diff --git a/docs/license/index.html b/docs/license/index.html index 4293e47..08314e0 100644 --- a/docs/license/index.html +++ b/docs/license/index.html @@ -11,7 +11,8 @@

      License

      -
      + +
      ⇐
      @@ -23,6 +24,7 @@

      License

      +

      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.

      diff --git a/docs/mccole.css b/docs/mccole.css index df3a19d..62bc343 100644 --- 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 index e34c2f5..34dbb13 100644 --- 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"
    • {p}
      • " for p in points]) + return f'
        \n{points}\n
      ' + + @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 index df3a19d..62bc343 100644 --- 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 index 8ef20ef..218b826 100644 --- a/lib/mccole/templates/node.ibis +++ b/lib/mccole/templates/node.ibis @@ -6,6 +6,8 @@
      {% include "title.html" %} + {% include "prevnext.html" %} + {{ node | keypoints }} {{ node.html }}
      {% include "foot.html" %} diff --git a/lib/mccole/templates/prevnext.html b/lib/mccole/templates/prevnext.html new file mode 100644 index 0000000..cbc1333 --- /dev/null +++ b/lib/mccole/templates/prevnext.html @@ -0,0 +1,11 @@ +
      +
      + {{node | nav_prev }} +
      +
      + {% if node | is_chapter %}{{ node | tagline }}{% endif %} +
      +
      + {{node | nav_next }} +
      +
      diff --git a/lib/mccole/templates/title.html b/lib/mccole/templates/title.html index 963ac3c..0b5c054 100644 --- a/lib/mccole/templates/title.html +++ b/lib/mccole/templates/title.html @@ -1,12 +1 @@

      {% if node.title %}{{ node.title }}{% else %}{{ site.title }}{% endif %}

      -
      -
      - {{node | nav_prev }} -
      -
      - {% if node | is_chapter %}{{ node | tagline }}{% endif %} -
      -
      - {{node | nav_next }} -
      -
      diff --git a/src/finale/index.md b/src/finale/index.md index d69f049..4a9579f 100644 --- 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 index 26872ce..da46862 100644 --- 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 %]