Theme: Add layouts for API-sites

This upstreams layouts and style overrides from `qunitjs/qunit.git:/doc`
(api.qunitjs.com).

* Move padding-top in `.main` to padding-bottom on `.hero`
  so that pages without hero don't have odd spacing.

Also:

* Move theme config documentation to a separate Markdown file for easier reference.

* Introduce `site.amethyst.home_href` option so that qunitjs.com
  and api.qunitjs.com can both have the logo link to the same central
  home page. This will also help with the blog later.
  Ref #1.

* Omit page.title from wrapper `<title>` in HTML head when on the
  index page. When using the "home" layout, this isn't an issue, but
  if a site uses a different layout as its home page, then one should
  be able to set "title" in the front matter and still have it be
  excluded from the document title to avoid confusion/redundancy.

Closes #3.

.github/workflows/doc-search.yaml

@@ -13,10 +13,12 @@ jobs:
 
       # https://github.com/ruby/setup-ruby
       - uses: ruby/setup-ruby@v1
+        # working-directory: ./
         with:
           ruby-version: 2.7
           bundler-cache: true
 
       - run: bundle exec jekyll algolia
+        # working-directory: ./
         env:
           ALGOLIA_API_KEY: "${{ secrets.ALGOLIA_API_KEY }}"

_config.yml

@@ -1,6 +1,16 @@
+# Configuration for the Amethyst development site
+#
+# DO NOT COPY
+#
+# To create your own site with this theme, use the example branch as
+# your clean and minimal starting point:
+# https://github.com/qunitjs/jekyll-theme-amethyst/tree/example
+#
+# -------
+
 # Site settings
 #
-# https://jekyllrb.com/docs/configuration/
+# Docs: https://jekyllrb.com/docs/configuration/
 title: Amethyst Demo
 description: "An amazing website."
 permalink: /:title/
@@ -12,93 +22,60 @@ baseurl: /jekyll-theme-amethyst
 # - https://github.com/jekyll/jekyll/issues/7426
 # - https://github.com/jekyll/jekyll/issues/4268
 # - https://github.com/sindresorhus/gulp-ruby-sass/issues/232
-# Workaround. – https://github.com/github/pages-gem/issues/613
+# – Workaround: https://github.com/github/pages-gem/issues/613
 theme: null
+# Files that will not be converted or published
+exclude:
+  # Exclude repo docs from site output and search index
+  - docs
+  # Avoid the following on GitHub CI:
+  # > Error: could not read file
+  # > vendor/jekyll/lib/site_template/_posts/0000-00-00-welcome-to-jekyll.markdown.erb:
+  # > Invalid date '<%= Time.now.strftime('%Y-%m-%d %H:%M:%S %z') %>':
+  # > Document does not have a valid date in the YAML front matter.
+  - vendor
+
 
 # Theme settings
 #
-# https://github.com/qunitjs/jekyll-theme-amethyst
+# Amethyst theme options are documented at:
+# https://github.com/qunitjs/jekyll-theme-amethyst/blob/main/docs/config.md
+#
 amethyst:
-  # Base URI for "Edit this page" links.
-  # When set, this is combined with the relative path to the Markdown file in the repo.
   edituri_base: https://github.com/qunitjs/jekyll-theme-amethyst/blob/main/
-  # Defaults to "/favicon.svg"
-  favicon:
-  header_logo:
-    src:
-    width:
-    height:
-  # Mastodon account URL (e.g. "https://mastodon.technology/@qunitjs")
-  mastodon:
-  # Twitter.com username (without "@")
-  twitter:
-  # GitHub.com organisation or username
+  release_base: https://github.com/qunitjs/qunit/releases/tag/
   github: qunitjs
-  # Gitter.im room (e.g. "qunitjs/qunit")
   gitter: qunitjs/qunit
-  # Frontend search powered by Algolia
+  # https://github.com/qunitjs/jekyll-theme-amethyst/blob/main/docs/getting-started.md#enable-algolia-search
   algolia:
-    # Key for client-side search queries (required)
     search_only_api_key: f37678e47d7730bbf340e904a81fbbbd
 
-    # Defaults to `algolia.application_id`.
-    application_id:
-
-    # Defaults to "on" in accordance with the terms of the
-    # Community and Free Plan, <https://www.algolia.com/press/?section=brand-guidelines>.
-    # When set to "none", branding is omitted.
-    branding:
 
-    # Which indexes to use as autocomplete source
-    # For example, to support multiple sources:
-    #
-    # ```
-    # sources:
-    #  - index: qunitjs-api
-    #    base: https://api.qunitjs.com
-    #  - index: qunitjs
-    # ```
-    #
-    # Defaults to a single source based on `algolia.index_name`.
-
-# Conversion
+# Conversion settings
+#
 highlighter: rouge
 markdown: kramdown
 kramdown:
   input: GFM
   toc_levels: "1,2"
 
-# Sass
-# https://jekyllrb.com/docs/assets/#sassscss
+
+# Sass settings
+#
+# Docs: https://jekyllrb.com/docs/assets/#sassscss
 sass:
   style: compressed
   sourcemap: never
 
-# Backend search index
-#
-# This applies to the 'jekyll algolia' command.
-# Requires the ALGOLIA_API_KEY secret environment variable.
-# For an example, see <https://github.com/qunitjs/qunitjs.com>.
+
+# Backend search settings
 #
-# See <https://github.com/algolia/jekyll-algolia>.
+# Docs: https://github.com/algolia/jekyll-algolia
 algolia:
   application_id: 4HMKKPGKKN
-  # Which index to submit content to
   index_name: amethyst-demo
   # By default only HTML paragraphs are indexed (and headings, albeit through a different mechanism).
   # * Include list items (similar to paragraphs).
   # * Include tables (index per row for better excerpts).
   # * Include <pre> (typically code examples, omit if it "poisons" results too much).
-  nodes_to_index: 'p,li,tr,pre'
-  # Which markdown pages to ignore
-  files_to_exclude:
-
-# Input files
-exclude:
-    # Exclude repo docs from site output and search index
-    - docs
-    # Avoid the following on GitHub CI:
-    # > Error: could not read file vendor/bundle/ruby/2.7.0/gems/jekyll-3.9.0/lib/site_template/_posts/0000-00-00-welcome-to-jekyll.markdown.erb:
-    # > Invalid date '<%= Time.now.strftime('%Y-%m-%d %H:%M:%S %z') %>':
-    # > Document does not have a valid date in the YAML front matter.
-    - vendor
+  nodes_to_index: "p,li,tr,pre"

_data/sidebar_api.yml

@@ -0,0 +1,13 @@
+- group: foo
+  expand: true
+
+- group: lorem
+
+- type: list
+  title: Other
+  expand: true
+  list:
+    - url: /api/deprecated/
+      title: Deprecated
+    - url: /api/removed/
+      title: Removed

_data/sitenav.yml

@@ -4,6 +4,6 @@
     - name: Getting Started
       href: /intro/
 - name: Documentation
-  href: https://api.qunitjs.com
+  href: /api/
 - name: About
   href: /about/

_includes/sidebar.html

@@ -0,0 +1,77 @@
+{%- comment -%}
+
+Parameters:
+
+* blocks:
+  Key in `site.data` corresponding to a `_data/*.yml` file.
+
+Block data:
+
+* type: [Default: "group"]
+  What type of block to add to the sidebar.
+  - "group" to query a list of pages from a page group.
+  - "list" to specify your own custom list.
+
+* title: [Default: group_page.title or ""]
+  For a "group" block this defaults to the title of the group index page.
+  For a custom "list" block, this is required.
+
+* url: [Default: group_page.url or null]
+  For a "group" block this defaults to the URL of the group index page.
+  If null, the block title will not be linked.
+
+* group:
+  When using a "group" block, the ID of the group to query for.
+
+* list:
+  When using a "list" block, an array of objects with "title"
+  and "url" properties.
+
+* expand: [Default: active]
+  Whether a block should be expanded.
+  - true: Always expanded.
+  - false: Never expanded.
+  - active: Expand when the current page is in the list.
+
+{%- endcomment -%}
+<section class="sidebar">
+{% for block in site.data[include.blocks] -%}
+	{%- assign block_type = block.type | default: "group" -%}
+	{%- assign block_title = block.title -%}
+	{%- assign block_url = block.url -%}
+	{%- assign block_contents = block.list -%}
+	{%- assign block_expand = block.expand -%}
+	{%- if block_expand != true and block_expand != false -%}
+		{%- assign block_expand = "active" -%}
+	{%- endif -%}
+
+	{%- if block_type == "group" -%}
+		{%- assign group_page = site.pages | where: "layout", "group" | where: "group", block.group | first -%}
+		{%- assign block_title = block.title | default: group_page.title | default: block.group -%}
+		{%- assign block_url = block.url | default: group_page.url -%}
+		{%- assign block_contents = site.pages | where: 'groups', block.group | sort_natural: 'title' -%}
+	{%- elsif block_type == "recent" -%}
+		{%- assign block_contents = site.posts | slice: 0, 5 -%}
+	{%- endif -%}
+
+	{%- if block_expand == "active" -%}
+		{%- assign self_in_contents = block_contents | where: 'url', page.url | size -%}
+		{%- if page.url == block_url or self_in_contents > 0 -%}
+			{%- assign block_expand = true -%}
+		{%- else -%}
+			{%- assign block_expand = false -%}
+		{%- endif -%}
+	{%- endif %}
+
+	<h4{% if block_expand %} class="sidebar-title-open"{% endif %}>{% if block_url %}<a href="{{ block_url | relative_url }}">{{ block_title }}</a>{% else %}{{ block_title }}{% endif %}</h4>
+	{%- if block_expand -%}
+	<ul class="sidebar-list">
+	{%- for entry in block_contents %}
+	<li class="sidebar-item{% if page.url == entry.url %} sidebar-item-active{% endif %}">
+		<a href="{{ entry.url | relative_url }}">{{ entry.title }}</a>
+	</li>
+	{%- endfor -%}
+	</ul>
+	{%- endif -%}
+{% endfor %}
+</section>

_includes/version.html

@@ -0,0 +1,28 @@
+{%- comment -%}
+
+Parameters:
+
+* version:
+  Like "1.0", "2.2", or "unreleased".
+
+* label:
+  Like "version added".
+
+{%- endcomment -%}
+
+{%- comment -%}
+    These releases have original release notes published under a v-prefixed tag.
+{%- endcomment -%}
+{%- assign _old_releases = " v1.9.0 v1.10.0 v1.11.0 v1.12.0 " -%}
+
+{%- assign _full_version = include.version -%}
+{%- assign _old_version = _full_version | prepend: "v" -%}
+{%- if _old_releases contains _old_version -%}
+    {%- assign _full_version = _old_version -%}
+{%- endif -%}
+
+{%- if include.version == "unreleased" -%}
+not yet released
+{%- 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 %}
+{%- endif -%}

_layouts/group.html

@@ -0,0 +1,14 @@
+---
+layout: page-api
+---
+{{ content }}
+
+{%- assign pages = site.pages | where: 'groups', page.group | sort_natural: 'title' -%}
+{% for page in pages %}
+<h2 id="{{ page.title | slugify }}"><a href="{{ page.url | relative_url }}">{{ page.title }}</a></h2>
+<p>
+	{%- if page.version_removed %}<strong>REMOVED</strong> {% endif -%}
+	{%- if page.version_removed == nil and page.version_deprecated %}<strong>DEPRECATED</strong> {% endif -%}
+	{{ page.excerpt -}}
+</p>
+{% endfor -%}

_layouts/home.html

@@ -20,6 +20,6 @@ <h2 class="hero-description">{{ page.home_description | default: site.descriptio
         {% endif -%}
     </div>
 </section>
-<div class="main wrapper layout-home">
+<div class="main wrapper content layout-home">
     {{ content }}
 </div>

_layouts/page-api.html

@@ -0,0 +1,32 @@
+---
+layout: wrapper
+---
+
+<div class="main main--columns wrapper">
+{% include sidebar.html blocks="sidebar_api" %}
+<div class="content" role="main">
+    <h1>{{ page.title }}</h1>
+    {%- 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>
+    {%- endif %}
+    {{- content }}
+</div>
+</div>

_layouts/page.html

@@ -7,6 +7,6 @@
         <h1 class="hero-title">{{ page.title }}</h1>
     </div>
 </section>
-<div class="main wrapper">
+<div class="main wrapper content">
     {{ content }}
 </div>

_layouts/wrapper.html

@@ -1,15 +1,15 @@
 <!DOCTYPE html>
 <html lang="en">
 <meta charset="utf-8">
-<title>{% if page.title %}{{ page.title | escape }} | {% endif %}{{ site.title | escape }}</title>
+<title>{% if page.url != '/' and page.title %}{{ page.title | escape }} | {% endif %}{{ site.title | escape }}</title>
 <meta name="viewport" content="width=device-width, initial-scale=1.0">
 <link rel="icon" href="{{ site.amethyst.favicon | default: '/favicon.svg' | relative_url }}">
 <link rel="stylesheet" href="{{ '/assets/styles.css' | relative_url }}" media="screen">
 {% include opengraph.html -%}
 <body>
     <header class="site-header" role="banner">
         <div class="site-header-wrapper wrapper">
-            <a class="site-logo" href="{{ '/' | relative_url }}">
+            <a class="site-logo" href="{{ site.amethyst.home_href | default: '/' | relative_url }}">
                 {%- if site.amethyst.header_logo.src -%}
                 <img src="{{ site.amethyst.header_logo.src | relative_url | escape }}" alt="{{ site.title | escape }}" width="{{ site.amethyst.header_logo.width | escape }}" height="{{ site.amethyst.header_logo.height | escape }}">
                 {%- else -%}