add mod categories

.github/workflows/jekyll.yml

@@ -121,6 +121,33 @@ jobs:
         uv run ./_validate_pyproject.py git_changed
         $(git merge-base ${{ github.event.pull_request.base.sha }} ${{ github.event.pull_request.head.sha }})
 
+  validate_categories:
+    runs-on: ubuntu-latest
+    if: >
+      github.event_name == 'pull_request'
+      || (github.ref == 'refs/heads/master'
+          && github.repository == 'bl-sdk/bl-sdk.github.io')
+
+    steps:
+    - name: Checkout repository
+      uses: actions/checkout@v6
+
+    - name: Install uv
+      uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0
+      with:
+        cache-dependency-glob: |
+          **/*requirements*.txt
+          **/*requirements*.in
+          **/*constraints*.txt
+          **/*constraints*.in
+          **/pyproject.toml
+          **/uv.lock
+          **/*.py.lock
+          _validate_categories.py
+
+    - name: Validate mod categories
+      run: uv run ./_validate_categories.py
+
   # Deployment job
   deploy:
     environment:

_config.yml

@@ -28,6 +28,16 @@ defaults:
       type: willow2_mods
     values:
       layout: mod
+  - scope:
+      path: ""
+      type: category_index
+    values:
+      layout: category_index
+  - scope:
+      path: ""
+      type: category_list
+    values:
+      layout: category_list
   - scope:
       path: ""
     values:

_config_oak.yml

@@ -10,6 +10,10 @@ collections:
     permalink: /oak-mod-db/mods/:name/
     output: true
 
+category_index:
+  enabled: true
+  url: /oak-mod-db/categories/
+
 game_selector:
   collection: oak_mods
   games:

_config_oak2.yml

@@ -10,6 +10,10 @@ collections:
     permalink: /oak2-mod-db/mods/:name/
     output: true
 
+category_index:
+  enabled: true
+  url: /oak2-mod-db/categories/
+
 just_the_docs:
   collections:
     oak2_mods:

_config_willow1.yml

@@ -10,6 +10,10 @@ collections:
     permalink: /willow1-mod-db/mods/:name/
     output: true
 
+category_index:
+  enabled: true
+  url: /willow1-mod-db/categories/
+
 game_selector:
   collection: willow1_mods
   games:

_config_willow2.yml

@@ -10,6 +10,10 @@ collections:
     permalink: /willow2-mod-db/mods/:name/
     output: true
 
+category_index:
+  enabled: true
+  url: /willow2-mod-db/categories/
+
 game_selector:
   collection: willow2_mods
   games:

_data/categories.yml

@@ -0,0 +1,14 @@
+# This file lists the categories we accept.
+# The top level keys are what you add to your mod file. All keys are lowercase, and use dashes in
+# place of spaces multiple words.
+# Each value can then have a custom 'title', to fix spaces and/or capitalization, and a custom
+# 'description', which is used in the category list.
+
+lorem:
+  title: Lorem Ipsum
+  description: >
+   Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut
+   labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris
+   nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate
+   velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non
+   proident, sunt in culpa qui officia deserunt mollit anim id est laborum.

_includes/components/nav/links.html

@@ -8,20 +8,11 @@
   {%- for node in include.pages -%}
   {%- if include.all == true or node.nav_exclude != true -%}
 
-  {%- if site.game_selector.collection and node.collection == site.game_selector.collection -%}
-    {%- assign game_select_classes = "game-any" -%}
-    {%- include filter_games.html page=node -%}
-    {%- for game in filtered_games -%}
-      {%- assign game_class = " game-" | append: game | downcase -%}
-      {%- assign game_select_classes = game_select_classes | append: game_class -%}
-    {%- endfor -%}
-  {%- else -%}
-    {%- assign game_select_classes = "" -%}
-  {%- endif -%}
+  {%- include mod_filter_classes.html page=node -%}
 
   {%- if include.ancestors contains node.title -%}
 
-    <li class="nav-list-item {{ game_select_classes }}">
+    <li class="nav-list-item {{ mod_filter_classes | join: " " }}">
       <a href="{{ node.url | relative_url }}" class="nav-list-link"> ∞ </a>
     </li>
     {%- capture nav_error_report -%}
@@ -36,7 +27,7 @@
 
     {%- include components/nav/children.html node=node ancestors=include.ancestors all=include.all -%}
 
-    <li class="nav-list-item {{ game_select_classes }}">
+    <li class="nav-list-item {{ mod_filter_classes | join: " " }}">
       {%- if nav_children.size >= 1 -%}
       <button class="nav-list-expander btn-reset" aria-label="{{ node.title }} submenu" aria-expanded="false">
         <svg viewBox="0 0 24 24" aria-hidden="true"><use xlink:href="#svg-arrow-right"></use></svg>

_includes/mod_filter_classes.html

@@ -0,0 +1,18 @@
+{%- comment -%}
+Gets the list of classes used to implement the mod filtering.
+
+Args:
+    page: The mod page to filter.
+Return:
+    Sets the 'mod_filter_classes' variable to an array of css classes.
+{%- endcomment -%}
+
+{%- assign mod_filter_classes = "" | split: "" -%}
+{%- if site.game_selector.collection and include.page.collection == site.game_selector.collection -%}
+  {%- assign mod_filter_classes = mod_filter_classes | push: "game-any" -%}
+  {%- include filter_games.html page=include.page -%}
+  {%- for game in filtered_games -%}
+    {%- assign game_class = "game-" | append: game | downcase -%}
+    {%- assign mod_filter_classes = mod_filter_classes | push: game_class -%}
+  {%- endfor -%}
+{%- endif -%}

_layouts/category_index.html

@@ -0,0 +1,24 @@
+---
+layout: default
+---
+{%- assign category = site.data.categories[page.mod_category] -%}
+<h1>{{ page.title }}</h1>
+{%- if category.description -%}
+    {{- category.description -}}
+    <br>
+    <br>
+{%- endif -%}
+<ul>
+{%- comment -%} Important: *not* using sort natural, to match the sidebar {%- endcomment -%}
+{%- assign sorted_mods = page.mods | sort: "title" -%}
+{%- for mod in sorted_mods -%}
+    {%- include mod_filter_classes.html page=mod -%}
+    <li class="{{ mod_filter_classes | join: " " }}">
+        <b><a href="{{ mod.url | relative_url }}">{{ mod.title }}</a></b>
+        {%- if mod.excerpt -%}
+            <br>
+            {{- mod.excerpt -}}
+        {%- endif -%}
+    </li>
+{%- endfor -%}
+</ul>

_layouts/category_list.html

@@ -0,0 +1,17 @@
+---
+layout: default
+---
+<h1>{{- page.title -}}</h1>
+<ul>
+{%- assign sorted_categories = page.all_categories | sort_natural -%}
+{%- for raw_category in sorted_categories -%}
+    <li>
+        <b><a href="{{- site.category_index.url | append: raw_category | relative-url -}}">
+            {%- assign category = site.data.categories[raw_category] -%}
+            {{- category.title | default: raw_category -}}
+        </a></b>
+        <br>
+        {{- category.description | markdownify -}}
+    </li>
+{%- endfor -%}
+</ul>

_layouts/mod.html

@@ -7,6 +7,18 @@
 </span>
 {%- endunless -%}
 <h1 id="title">{{ page.title }}</h1>
+{%- if site.category_index.enabled -%}
+    {%- assign categories = page.mod_categories | split: " " | sort_natural -%}
+    {%- for raw_category in categories -%}
+        <a href="{{- site.category_index.url | append: raw_category | relative-url -}}">
+            {%- assign category = site.data.categories[raw_category] -%}
+            {{- category.title | default: raw_category -}}
+        </a>
+        {%- unless forloop.last -%}
+            {{- ", " -}}
+        {%- endunless -%}
+    {%- endfor -%}
+{%- endif -%}
 <dl class="mod-desc">
     <dt>By</dt>
     {%- assign pyproject_authors = page.pyproject.project.authors

_plugins/mod-category-gen.rb

@@ -0,0 +1,81 @@
+class CategoryPageGenerator < Jekyll::Generator
+  safe true
+
+  def generate(site)
+    if !(site.config["category_index"] || {})["enabled"] then
+      return
+    end
+
+    # It turns out the normal tag/category system only applies to *posts*, not all pages
+    # Instead, we have to reimplement its logic, but do it for everything
+    @mod_categories = Hash.new { |hash, key| hash[key] = [] }
+
+    site.collections.each_value do |collection|
+      collection.docs.each do |document|
+        collect_categories(document)
+      end
+    end
+    site.pages.flatten.each do |page|
+      collect_categories(page)
+    end
+
+    if @mod_categories.empty? then
+      return
+    end
+
+    site.pages << CategoryList.new(site, @mod_categories.keys())
+    @mod_categories.each do |category, pages|
+      site.pages << CategoryIndex.new(site, category, pages)
+    end
+  end
+
+  def collect_categories(page)
+    (page.data["mod_categories"] || "").split().reject { |cat| cat.empty? }.each do |cat|
+      @mod_categories[cat.downcase] << page
+    end
+  end
+end
+
+CATEGORY_LIST_TITLE = "Browse Mod Categories"
+
+class CategoryList < Jekyll::Page
+  def initialize(site, categories)
+    @site     = site
+    @base     = site.source
+    @dir      = site.config["category_index"]["url"]
+    @basename = "index"
+    @ext      = ".html"
+    @name     = "index.html"
+    @data = {
+      "all_categories" => categories,
+      # Get it to appear at the bottom of the sidebar
+      "title" => CATEGORY_LIST_TITLE,
+      "nav_order" => 999,
+    }
+    data.default_proc = proc do |_, key|
+      site.frontmatter_defaults.find(relative_path, :category_list, key)
+    end
+  end
+end
+
+class CategoryIndex < Jekyll::Page
+  def initialize(site, category, pages)
+    @site     = site
+    @base     = site.source
+    @dir      = site.config["category_index"]["url"] + category
+    @basename = "index"
+    @ext      = ".html"
+    @name     = "index.html"
+    @data = {
+      "mod_category" => category,
+      "mods" => pages,
+      # Make it appear in the sidebar, under the root
+      "title" => site.data["categories"].fetch(category, {})["title"] || category,
+      "parent" => CATEGORY_LIST_TITLE,
+    }
+    data.default_proc = proc do |_, key|
+      site.frontmatter_defaults.find(relative_path, :category_index, key)
+    end
+  end
+end
+