From a0c8775cae4c9b78984a1e77a321b80c124364c6 Mon Sep 17 00:00:00 2001
From: Timo Tijhof <krinkle@fastmail.com>
Date: Sun, 7 May 2023 22:46:18 +0100
Subject: [PATCH] Theme: Display categories atop each API page

This improves mobile browsing, where we hide the sidebar.

Previously, the sidebar was the only way to know (by eye) which category
the current page belong to, and the only way to browse the other
pages in the same category.

Now, with the "Categories" output, the categories are mentioned
explicitly, and on mobile people can click those to browe the
category tree and navigate to other nearby pages.

This is also helps with Typesense, which this way has an easy way
to find what the name of the category is for the current page.

This is inspired by the jQuery API docs which have had this kind of
category indication since 2015, and is indexed by Algolia using
the same mechanism.
---
 _data/sidebar_api.yml  | 12 ++++++++----
 _includes/version.html |  4 ++--
 _layouts/page-api.html | 43 +++++++++++++++++++++++++-----------------
 _layouts/post.html     |  6 +++---
 _sass/amethyst.scss    |  9 ++++++++-
 5 files changed, 47 insertions(+), 27 deletions(-)

diff --git a/_data/sidebar_api.yml b/_data/sidebar_api.yml
index ed42a7e..d30b744 100644
--- a/_data/sidebar_api.yml
+++ b/_data/sidebar_api.yml
@@ -4,10 +4,14 @@
 
 - group: lorem
 
-- type: link
-  url: /api/deprecated/
+- group: deprecated
+  expand: false
   title: Deprecated
 
-- type: link
-  url: /api/removed/
+- group: removed
+  expand: false
   title: Removed
+
+- type: link
+  url: /api/foo/quux/
+  title: Quux
diff --git a/_includes/version.html b/_includes/version.html
index 24077fb..d1f9bd0 100644
--- a/_includes/version.html
+++ b/_includes/version.html
@@ -22,7 +22,7 @@
 {%- endif -%}
 
 {%- if include.version == "unreleased" -%}
-not yet released
+not yet released<span class="sep">.</span>
 {%- else -%}
-{{ include.label }}: {% if site.amethyst.release_base %}<a href="{{ site.amethyst.release_base }}{{ _full_version | escape }}">{{ include.version | escape }}</a>{% else %}{{ include.version | escape }}{% endif %}
+{{ include.label }}: {% if site.amethyst.release_base %}<a href="{{ site.amethyst.release_base }}{{ _full_version | escape }}">{{ include.version | escape }}</a>{% else %}{{ include.version | escape }}{% endif %}<span class="sep">.</span>
 {%- endif -%}
diff --git a/_layouts/page-api.html b/_layouts/page-api.html
index cadf07b..a8c59e8 100644
--- a/_layouts/page-api.html
+++ b/_layouts/page-api.html
@@ -27,29 +27,38 @@ <h2 id="description" class="screen-reader-text h-api-desc">Description</h2>
 {%- endunless -%}
 <div class="main main--columns wrapper">
 <div class="content" role="main">
+<article>
+    <header>
     <h1>{{ page.title }}</h1>
-    {%- if page.version_added or page.version_deprecated -%}
+    {% if page.groups -%}
+    <p class="post-meta">Categories: {% comment %} space {% endcomment -%}
+        {%- for group in page.groups -%}
+            {%- if page.groups.first != group %}, {% endif -%}
+            {%- assign group_page = site.pages | where: "layout", "group" | where: "group", group | first -%}
+            <a class="category" href="{{ group_page.url | relative_url }}">{{ group_page.title | escape }}</a>
+        {%- endfor -%}
+    .</p>
+    {%- endif %}
+    </header>
+    {% if page.version_added or page.version_deprecated -%}
         {%- assign warning = false -%}
         {%- if page.version_added == "unreleased" or page.version_deprecated or page.version_removed -%}
             {%- assign warning = true -%}
         {%- endif -%}
-
-    <p class="version-details{% if warning %} note--warning{% endif %}">
-        {%- capture lines -%}
-            {%- if page.version_added %}
-                {% include version.html version=page.version_added label="version added" %}
-            {%- endif -%}
-            {%- if page.version_deprecated %}
-                {% include version.html version=page.version_deprecated label="deprecated" %}
-            {%- endif -%}
-            {%- if page.version_removed %}
-                {% include version.html version=page.version_removed label="removed" %}
-            {%- endif -%}
-        {%- endcapture -%}
-        {{ lines | strip | newline_to_br }}
-    </p>
+        <p class="version-details">
+        {%- if page.version_added %}
+            {% include version.html version=page.version_added label="version added" %}
+        {%- endif -%}
+        {%- if page.version_deprecated %}
+            {% include version.html version=page.version_deprecated label="deprecated" %}
+        {%- endif -%}
+        {%- if page.version_removed %}
+            {% include version.html version=page.version_removed label="removed" %}
+        {%- endif -%}
+        </p>
     {%- endif %}
-    {{- content }}
+    {{ content }}
+</article>
 </div>
 {%- assign toc = true -%}
 {%- if layout.amethyst.toc == false -%}
diff --git a/_layouts/post.html b/_layouts/post.html
index 16047e8..e917285 100644
--- a/_layouts/post.html
+++ b/_layouts/post.html
@@ -3,15 +3,15 @@
 ---
 
 <div class="main main--columns wrapper">
-<div class="content">
-	<article class="content">
+<div class="content" role="main">
+<article>
 	<header>
 		<h1>{{ page.title | escape }}</h1>
 		{%- assign date_format = site.amethyst.date_format | default: "%e %B %Y" -%}
 		<p class="post-meta byline">Posted on <a href="{{ page.url | relative_url }}" rel="bookmark"><time itemprop="pubdate" datetime="{{ page.date | date_to_xmlschema }}">{{ page.date | date: date_format }}</time></a>{% if page.author %} by <span class="vcard"><span class="fn n" rel="author">{{ page.author | escape }}</span></span>{% endif %}</p>
 	</header>
 	{{ content }}
-	</article>
+</article>
 {%- comment -%}
 Support basic read-only rendering of imported comments.
 
diff --git a/_sass/amethyst.scss b/_sass/amethyst.scss
index bb249a4..8d66910 100644
--- a/_sass/amethyst.scss
+++ b/_sass/amethyst.scss
@@ -826,9 +826,16 @@ table {
         text-align: left;
         border-width: 1px;
         border-style: solid;
+
+        .sep {
+            display: block;
+            width: 0px;
+            height: 0px;
+            overflow: hidden;
+        }
     }
 }
-.version-details:not(.note--warning) {
+.version-details {
     background: $color-light;
     border-color: $color-off-white;
 }