Introduce taxonomy equivalent of menu map

This produces the same view (sharing code to do so), but allows using a
taxonomy instead of a list of menus. The benefit here is a taxonomy
gives you a place (the taxonomy term page) to define metadata that may
be useful in presenting each term (e.g. attaching a description to each
term).

The equivalences between menu and taxonomy maps are:

| Concept                                                       | Menu concept     | Taxonomy concept      |
|---------------------------------------------------------------|------------------|-----------------------|
| A category (e.g. a column to display in the default map view) | A menu           | A term                |
| A value in the category (e.g. a a card to show in the column) | A page in a menu | A value within a term |

There are some interesting compatibility questions in here which I will
comment on in the PR I'm raising for this.

Note: This currently doesn't actually define any interesting metadata
(other than weight) for each term in the tracks taxonomy - I will send
this through as a follow-up PR, to separate out "the idea of a taxonomy
map" from "the details of this particular taxonomy".

common-docs/content/_index.md

@@ -1,6 +1,6 @@
 +++
 title="Help us doc!"
 description="This is a [🅷🆄🅶🅾](https://gohugo.io/)-based platform called [🌱common](https://github.com/CodeYourFuture/curriculum/tree/main/common-theme)"
-map=["theme", "content", "community"]
+menus_to_map=["theme", "content", "community"]
 menu=["syllabus"]
 +++

common-docs/content/common-theme/front-matter/_index.md

@@ -20,8 +20,11 @@ src="common-theme/front-matter/blocks/blocks"
 name="Emoji"
 src="common-theme/front-matter/blocks/emoji"
 [[blocks]]
-name="Map"
-src="common-theme/front-matter/blocks/map"
+name="Taxonomy map"
+src="common-theme/front-matter/blocks/taxonomy-map"
+[[blocks]]
+name="Menu map"
+src="common-theme/front-matter/blocks/menu-map"
 [[blocks]]
 name="Menus, menu_level"
 src="common-theme/front-matter/blocks/menu"

common-docs/content/common-theme/front-matter/blocks/map/index.md

@@ -1,17 +0,0 @@
-+++
-title = 'Map'
-time = 2
-emoji= '🗺️'
-[build]
-  render = 'never'
-  list = 'local'
-  publishResources = false
-+++
-
-A map is an ordered slice of menus. It's to show a "map" view of the syllabus, broken down into grouped modules. As with everything in this design, the point is to clarify what happens and in what order.
-
-It's just for the index page, and the front matter is a list of the menu names that should be included in the map, in the order they should appear.
-
-```toml
-map = ["menuName", "menuName"]
-```

common-docs/content/common-theme/front-matter/blocks/menu-map/index.md

@@ -0,0 +1,19 @@
++++
+title = 'Menu map'
+time = 2
+emoji= '🗺️'
+[build]
+  render = 'never'
+  list = 'local'
+  publishResources = false
++++
+
+A menu map is an ordered slice of menus. It's to show a "map" view of the syllabus, broken down into grouped modules. As with everything in this design, the point is to clarify what happens and in what order.
+
+It's just for the index page, and the front matter is a list of the menu names that should be included in the map, in the order they should appear.
+
+If you want to attach metadata to each menu item (e.g. to add a description), you probably want a Taxonomy map.
+
+```toml
+menus_to_map = ["menuName", "menuName"]
+```

common-docs/content/common-theme/front-matter/blocks/taxonomy-map/index.md

@@ -0,0 +1,17 @@
++++
+title = 'Taxonomy map'
+time = 2
+emoji= '🗺️'
+[build]
+  render = 'never'
+  list = 'local'
+  publishResources = false
++++
+
+A taxonomy map is an ordered slice of terms within a taxonomy. It's to show a "map" view of the syllabus, broken down into grouped modules, with extra per-module metadata attached to the term. As with everything in this design, the point is to clarify what happens and in what order.
+
+It's just for the index page, and the front matter is a list of the menu names that should be included in the map, in the order they should appear.
+
+```toml
+taxonomy_to_map = "modules"
+```

common-theme/layouts/index.html

@@ -9,8 +9,12 @@
         {{ . }}
       </section>
     {{ end }}
-    {{ if .Params.map }}
+    {{ if .Params.menus_to_map }}
+      {{ partial "map-menu.html" .Params.menus_to_map }}
+    {{ else if .Params.map }}
       {{ partial "map.html" . }}
+    {{ else if .Params.taxonomy_to_map }}
+      {{ partial "map-taxonomy.html" .Params.taxonomy_to_map }}
     {{ else }}
       <ol class="c-timeline c-timeline--card">
         {{- range site.Menus.syllabus }}

common-theme/layouts/partials/card.html

@@ -1,5 +1,5 @@
 {{ $BaseURL := .Page.Parent.Permalink }}
-<a class="c-card" href="{{ relURL .URL }}">
+<a class="c-card" href="{{ relURL .Page.RelPermalink }}">
   <h3 class="c-card__title">{{ .Name }}</h3>
   {{ with .Page.Description }}
     <p class="c-card__description">{{ . }}</p>

common-theme/layouts/partials/map-common.html

@@ -0,0 +1,34 @@
+{{/*
+Expects a slice[dict] param containing an ordered list of dicts with the following keys, one per section in the map to render:
+* title (string) - The heading to display for the section.
+* values (slice[Page]) - A slice of Pages, one per page in the section which should be listed.
+*/}}
+
+<div class="c-map">
+<h1 class="e-heading c-map__start is-none--lt-container">👉🏾</h1>
+{{ range $i, $section := index . "sections" }}
+  {{ $sectionTitle := index $section "title" }}
+  {{ $sectionValues := index $section "values" }}
+  <section class="c-map__block">
+    <h2 class="e-heading c-map__title">
+      📍{{ $i }}:
+      {{ $sectionTitle }}
+    </h2>
+    <ol class="c-map__timeline">
+      {{/* Check if a menu for the current map section exists */}}
+      {{ if $sectionValues }}
+        {{/* Range over the items in the menu */}}
+        {{ range $iterator, $module := $sectionValues }}
+          <li
+            class="c-map__stop"
+            style="--layer:{{ sub (len $sectionValues) (add $iterator 1) }}">
+              {{ partial "card.html" $module }}
+          </li>
+        {{ end }}
+      {{ else }}
+        <li>No items found for {{ $sectionTitle }}</li>
+      {{ end }}
+    </ol>
+  </section>
+{{ end }}
+</div>

common-theme/layouts/partials/map-menu.html

@@ -0,0 +1,12 @@
+{{/* Expects slice[string] param which is the name of the menus to render as sections. */}}
+
+{{ $sections := slice }}
+
+{{ range $menuName := . }}
+  {{ $section := dict "title" $menuName "values" (index site.Menus $menuName) }}
+  {{ $sections = append $section $sections }}
+{{ end }}
+
+{{ $params := dict "sections" $sections }}
+
+{{ partial "map-common.html" $params }}

common-theme/layouts/partials/map-taxonomy.html

@@ -0,0 +1,20 @@
+{{/* Expects string param which is the (plural) name of the taxonomy to render. */}}
+
+{{ $taxonomy_to_map := . }}
+
+{{ $sections := slice }}
+
+{{/* You can't ask for a taxonomy to be sorted by weight, so we need to get weights and iterate ourselves - see https://discourse.gohugo.io/t/list-custom-taxonomy-terms-in-a-specific-order-not-alphabetical/18145/5 */}}
+{{ $terms := site.GetPage (printf "/%s" $taxonomy_to_map) }}
+{{ range $termPage := $terms.Pages.ByWeight }}
+  {{ $termID := path.BaseName $termPage.Path }}
+  {{ $termTitle := $termPage.Title }}
+  {{ $values := index (index site.Taxonomies $taxonomy_to_map) $termID }}
+
+  {{ $section := dict "title" $termTitle "values" $values }}
+  {{ $sections = append $section $sections }}
+{{ end }}
+
+{{ $params := dict "sections" $sections }}
+
+{{ partial "map-common.html" $params }}

common-theme/layouts/partials/map.html

@@ -1,29 +1,5 @@
-{{ with .Params.map }}
-  <div class="c-map">
-    <h1 class="e-heading c-map__start is-none--lt-container">👉🏾</h1>
-    {{ range $i, $currentMapSectionName := . }}
-      {{ $currentMapSectionModules := index site.Menus $currentMapSectionName }}
-      <section class="c-map__block">
-        <h2 class="e-heading c-map__title">
-          📍{{ $i }}:
-          {{ $currentMapSectionName }}
-        </h2>
-        <ol class="c-map__timeline">
-          {{/* Check if a menu for the current map section exists */}}
-          {{ if $currentMapSectionModules }}
-            {{/* Range over the items in the menu */}}
-            {{ range $iterator, $module := $currentMapSectionModules }}
-              <li
-                class="c-map__stop"
-                style="--layer:{{ sub (len $currentMapSectionModules) (add $iterator 1) }}">
-                {{ partial "card.html" $module }}
-              </li>
-            {{ end }}
-          {{ else }}
-            <li>No items found for {{ $currentMapSectionName }}</li>
-          {{ end }}
-        </ol>
-      </section>
-    {{ end }}
-  </div>
-{{ end }}
+{{/* Expects Page as a param, and that the page will have a .Params.map which contains a slice[string] of menus to render as sections. */}}
+
+{{/* This is legacy support which we will deprecate at some point. */}}
+{{ warnf "Using the map param is deprecated - rename this param to menus_to_map" }}
+{{ partial "map-menu.html" .Params.map }}

org-cyf-guides/content/_index.md

@@ -4,5 +4,5 @@ description = 'A collection of guides, references, resources that do not belong
 emoji= '📚'
 menu=["syllabus"]
 weight=1
-map=['volunteers', 'learners', 'everyone']
+menus_to_map=['volunteers', 'learners', 'everyone']
 +++

org-cyf-itd/content/_index.md

@@ -2,5 +2,5 @@
 title="Intro to Digital"
 description="How to participate in the Intro to Digital programme as a learner or teacher"
 menu="main"
-map=['start here', 'steps', 'workshops']
+menus_to_map=['start here', 'steps', 'workshops']
 +++

org-cyf-itp/content/_index.md

@@ -1,6 +1,6 @@
 +++
 title="Intro to Programming"
-map=["start here", "programming", "next steps"]
+menus_to_map=["start here", "programming", "next steps"]
 description="New? Lost? [Quickstart](how-this-works/prep/#overview)"
 emoji= "🧑🏿‍🏫"
 +++

org-cyf-piscine/content/_index.md

@@ -4,5 +4,5 @@ description = 'In teams and on your own, build working software with tests. Expl
 layout = 'module'
 emoji= '🐠'
 menu = ['syllabus', 'next steps']
-map=['entry', 'sprints', 'assessment']
+menus_to_map=['entry', 'sprints', 'assessment']
 +++

org-cyf-sdc/content/_index.md

@@ -1,6 +1,6 @@
 +++
 title="Software Development Course"
-map=["start here", "SDC", "tracks"]
+menus_to_map=["start here", "SDC", "tracks"]
 description="Alert: this course is not yet available. Content is incomplete."
 emoji= "🧑🏾‍🔧" 
 +++

org-cyf-tracks/content/_index.md

@@ -1,6 +1,6 @@
 +++
 title="Tracks"
-map=["start here", "from itp", "from sdc"]
+taxonomy_to_map = "track_kinds"
 description="Short, focused courses walking you towards specific careers"
 emoji= "👣"
 +++

org-cyf-tracks/content/cloud/_index.md

@@ -3,5 +3,5 @@ title = 'Cloud'
 description = 'Deploy and manage cloud infrastructure; explore containers, pipelines, load balancing, traffic, integration and security; define infrastructure as code'
 layout = 'module'
 emoji= '☁️'
-menu = 'from sdc'
+track_kinds = ["jobs-after-sdc"]
 +++

org-cyf-tracks/content/coming-soon/_index.md

@@ -3,7 +3,7 @@ title = 'Coming Soon'
 description = 'ITP tracks are coming soon...'
 layout = 'module'
 emoji= '👷🏽‍♀️'
-menu = "from itp"
+track_kinds = ["jobs-after-itp"]
 +++
 
 ## In development:

org-cyf-tracks/content/portfolio/_index.md

@@ -3,5 +3,5 @@ title = 'Portfolio'
 description = 'Build great projects; work in teams; polish our profiles; get great jobs in tech'
 layout = 'module'
 emoji= '🧑🏾‍🚀'
-menu = 'from sdc'
+track_kinds = ["jobs-after-sdc"]
 +++

org-cyf-tracks/content/react/_index.md

@@ -3,6 +3,6 @@ title = 'React'
 description = 'Explore frameworks, libraries, and declarative programming with React; Develop unit testing with Testing Library; Build a dynamic web application in an Agile team'
 layout = 'module'
 emoji= '🪄'
-menu = 'from sdc'
+track_kinds = ["self-study"]
 weight='6'
 +++

org-cyf-tracks/content/track_kinds/jobs-after-itp/_index.md

@@ -0,0 +1,4 @@
++++
+title = "Jobs after ITP"
+weight = 2
++++

org-cyf-tracks/content/track_kinds/jobs-after-sdc/_index.md

@@ -0,0 +1,4 @@
++++
+title = "Jobs after SDC"
+weight = 3
++++

org-cyf-tracks/content/track_kinds/self-study/_index.md

@@ -0,0 +1,4 @@
++++
+title = "Self-study"
+weight = 1
++++

org-cyf-tracks/hugo.toml

@@ -20,3 +20,6 @@ baseURL = "https://tracks.codeyourfuture.io/"
     [[module.imports.mounts]]
       source = "content"
       target = "content/how-this-works"
+
+[taxonomies]
+  track_kind = "track_kinds"

org-cyf/content/_index.md

@@ -1,6 +1,6 @@
 +++
 title="Our Courses"
-map=["start here", "selection", "trainees", "fellowships"]
+menus_to_map=["start here", "selection", "trainees", "fellowships"]
 description="Free training for good jobs in tech [📅 2024/25](https://docs.google.com/spreadsheets/d/1qNxf44_vbNKU1KeFozGX7Kt1QxmTtU6Bf9tOh1sTUuc/edit?gid=1346767713#gid=1346767713)"
 emoji= "🧑🏿‍🏫👨🏽‍🎓"
 +++