Theme: Add support for blog posts

== GitHub Actions workflow ==

This commit introduces a soft dependency on the jekyll-archives plugin.
A non-blog site can continue to use Amethyst without it, in which case
any blog-specific page layout might not work correctly.

The jekyll-archive Gem package is a first-party plugin from the Jekyll
community. But, it not included in the github-pages Gem. As such, in
order to use it we have to opt-out from the default Jekyll deployment
that GitHub Pages offers, and instead deploy it as a static site that
we build ourselves from a GitHub Actions worflow (run Jekyll and
commit files to a branch). This is becoming a more common pattern in
the community already, due to github-pages also lagginb behind in
other features (and still on the Jekyll 3.x series).

== 404 ==

I have tried to most URL patterns currently used by WordPress as
configured on blog.jquery.com. But, a few URLs will likely become
404, and I noticed Amethyst did not yet have a custom 404 page.

This commit adds one, so as to ensure the visitor stays within the
site and can use the search feature (instead of ending up on a
generic Nginx or GitHub 404 error page).

== Features ==

* Blog post rendering with semantic HTML, microdata hCard, and other
  aspects that help accessible technology to understand and focus
  on the content, proper display in "Reader Mode" of Firefox and
  Safari, and SEO.

* Basic comment rendering with Gravatar.

* Index by tag.

* Index by year.

* Sidebar modules for tag list, recent posts, and yearly archives.

Not implemented:

* Pagination.

  The WordPress blog rendered full post contents on index pages,
  which made them quite long and difficult to scan.

  In Amethyst, I've rendered only excerpts on index pages, which makes
  them much more scannable I think and for the most part forgoes the
  need for pagination. There is only so much in any given year or
  category.

  For the home page, we list the 10 most recent posts, and then link
  to an even more minimal archive index where all posts are linked with
  only their title and date in a bullet list (not even an excerpt).

* Authors don't have dedicated pages.
  I considered giving authors pages like for tags, but this conflicted
  with jekyll-feed. And the data-based author index that jekyll-feed
  supports doesn't result in dedicated pages. Rather than a messy
  workaround, perhaps it's not something we need, so long as the
  author information itself is preserved.

* Archive indexes by year only, not by month.
  There typically aren't that many posts and it seemed to make for
  rather long and clunky navigation. I have compensated by making
  the archive indexes render the post excerpt only, thus making
  them very scannable.

* Comment authors are plain text (no external link for commenter URL).

* Comment dates have day-level precision (no hours/minutes/seconds).

.github/workflows/github-pages.yaml

@@ -0,0 +1,47 @@
+name: GitHub Pages
+on:
+  push:
+    branches:
+      - main
+
+jobs:
+  deploy:
+    name: Deploy
+    runs-on: ubuntu-20.04
+    env:
+      DEPLOY_DIR: _site/
+      DEPLOY_BRANCH: gh-pages
+    steps:
+      - uses: actions/checkout@v2
+
+      - name: Prepare branch
+        run: |
+          mkdir "${DEPLOY_DIR}"
+          cd "${DEPLOY_DIR}"
+          # Clone and checkout existing branch, or initialise with a new and empty branch
+          git clone --depth 5 --branch "${DEPLOY_BRANCH}" "https://github.com/${GITHUB_REPOSITORY}.git" . || git init -b "${DEPLOY_BRANCH}"
+
+      - uses: ruby/setup-ruby@v1
+        # If your site is in a subdirectory
+        # working-directory: ./
+        with:
+          ruby-version: 2.7
+          bundler-cache: true
+
+      - name: Jekyll build
+        # If your site is in a subdirectory
+        # working-directory: ./
+        run: bundle exec jekyll build
+
+      - name: Push to branch
+        # Inspired by https://github.com/helaili/jekyll-action/blob/2.2.0/entrypoint.sh
+        env:
+          GITHUB_TOKEN: "${{ secrets.GITHUB_TOKEN }}"
+        run: |
+          cd "${DEPLOY_DIR}"
+          touch .nojekyll
+          git config user.name "${GITHUB_ACTOR}" && \
+          git config user.email "${GITHUB_ACTOR}@users.noreply.github.com" && \
+          git add . && \
+          git commit --allow-empty -m "Build commit ${GITHUB_SHA}" && \
+          git push "https://${GITHUB_ACTOR}:${GITHUB_TOKEN}@github.com/${GITHUB_REPOSITORY}.git" "HEAD:${DEPLOY_BRANCH}"

.github/workflows/spider-check.yaml

@@ -21,7 +21,7 @@ jobs:
     steps:
       - uses: actions/checkout@v2
         with:
-          repository: qunitjs/hydra-link-checker
+          repository: jquery/hydra-link-checker
           ref: v1.0.2
 
       - name: Run hydra-link-checker

.gitignore

@@ -1,3 +1,4 @@
+/.jekyll-cache/
 /.sass-cache/
 /_site/
 /Gemfile.lock

404.md

@@ -0,0 +1,9 @@
+---
+layout: page
+title: Page not found
+permalink: /404.html
+amethyst:
+  hero: false
+---
+
+<p class="lead" markdown="1">It seems we can’t find what you’re looking for.</p>

Gemfile

@@ -1,8 +1,17 @@
 source "https://rubygems.org"
 ruby RUBY_VERSION
 
-gem 'github-pages', group: :jekyll_plugins
-gem 'jekyll-algolia', "1.7.0", group: :jekyll_plugins
+gem "jekyll", "~> 4.2.0"
+gem "kramdown-parser-gfm", "1.1.0"
+gem "jekyll-redirect-from", "~> 0.16.0", group: :jekyll_plugins
+gem "jekyll-remote-theme", "~> 0.4.3", group: :jekyll_plugins
 
-# Temporary fix for https://github.com/github/pages-gem/issues/752
+# Blog
+gem "jekyll-feed", "~> 0.15.1", group: :jekyll_plugins
+gem "jekyll-archives", "~> 2.2.1", group: :jekyll_plugins
+
+# Search
+gem "jekyll-algolia", "~> 1.7.0", group: :jekyll_plugins
+
+# Temporary fix until there is a release with https://github.com/jekyll/jekyll/pull/8524/
 gem "webrick", "~> 1.7"

_config.yml

@@ -13,8 +13,11 @@
 # Docs: https://jekyllrb.com/docs/configuration/
 title: Amethyst Demo
 description: "An amazing website."
-permalink: /:title/
+# For pages (not blog posts) this is equivalant to /:title/
+permalink: /:year/:month/:day/:title/
 baseurl: /jekyll-theme-amethyst
+lang: en
+timezone: UTC
 # Disable theme inheritance since this repo contains its own theme top-level theme.
 # This isn't needed for plain Jekyll, but because we use github-pages as basis
 # we otherwise inherit from the 'primer' theme.
@@ -79,3 +82,14 @@ algolia:
   # * 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"
+
+
+# Blog archives
+#
+# Docs: https://github.com/jekyll/jekyll-archives/
+jekyll-archives:
+  enabled:
+    - year
+  layout: posts-year
+  permalinks:
+    year: "/:year/"

_data/sidebar_blog.yml

@@ -0,0 +1,11 @@
+- type: tags
+  title: Tags
+  expand: true
+
+- type: recent
+  title: Recent posts
+  expand: true
+
+- type: archive
+  title: Archives
+  expand: true

_data/sitenav.yml

@@ -5,5 +5,7 @@
       href: /intro/
 - name: Documentation
   href: /api/
+- name: Blog
+  href: /blog/
 - name: About
   href: /about/

_includes/opengraph.html

@@ -1,9 +1,28 @@
+{%- assign feed_page = site.pages | where: 'url', '/feed.xml' | first -%}
+{%- if feed_page -%}
+<link rel="alternate" type="application/rss+xml" href="{{ feed_page.url | relative_url | escape }}" title="{{ site.title | escape }}">
+{% endif -%}
+
+{%- assign page_title = page.title -%}
+{%- if page_title == nil and page.date -%}
+    {%- comment -%}
+    Deal with jekyll-archives refusing to add, or facilitate addition of, a title to archive pages.
+    {%- endcomment -%}
+    {%- if page.type == "year" -%}
+        {%- assign page_title = page.date | date: '%Y' -%}
+    {%- elsif page.type == "month" -%}
+        {%- assign page_title = page.date | date: '%B %Y' -%}
+    {%- endif -%}
+{%- endif -%}
+
+<title>{% if page.url != '/' and page_title %}{{ page_title | escape }} | {% endif %}{{ site.title | escape }}</title>
+
 {%- comment -%}
     See https://ogp.me/
-{%- endcomment -%}
-{% capture meta %}
+{%- endcomment %}
+{% capture opengraph %}
 
-<meta property="og:title" content="{% if page.title %}{{ page.title | escape }} - {% endif %}{{ site.title | escape }}">
+<meta property="og:title" content="{{ page_title | default: site.title | escape }}">
 
 {% if page.excerpt %}
     {%- assign excerpt = page.excerpt %}
@@ -27,4 +46,4 @@
 <meta name="twitter:card" content="summary_large_image">
 
 {% endcapture -%}
-{{ meta | strip_newlines }}
+{{ opengraph | strip_newlines }}

_includes/sidebar.html

@@ -11,6 +11,8 @@
   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.
+  - "archive" to query a list of chronological pages based on their layout.
+  - "tags" to query a list of alphabetical pages based on their layout.
 
 * title: [Default: group_page.title or ""]
   For a "group" block this defaults to the title of the group index page.
@@ -52,6 +54,10 @@
 		{%- assign block_contents = site.pages | where: 'groups', block.group | sort_natural: 'title' -%}
 	{%- elsif block_type == "recent" -%}
 		{%- assign block_contents = site.posts | slice: 0, 5 -%}
+	{%- elsif block_type == "archive" -%}
+		{%- assign block_contents = site.pages | where: "layout", "posts-year" | sort_natural: 'date' | reverse  -%}
+	{%- elsif block_type == "tags" -%}
+		{%- assign block_contents = site.pages | where: "layout", "posts-tag" | sort_natural: 'title'  -%}
 	{%- endif -%}
 
 	{%- if block_expand == "active" -%}
@@ -68,7 +74,13 @@
 	<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>
+		<a href="{{ entry.url | relative_url }}">
+			{%- assign entry_title = entry.title -%}
+			{%- if entry.title == nil and entry.date -%}
+				{%- assign entry_title = entry.date | date: '%Y' -%}
+			{%- endif -%}
+			{{- entry_title -}}
+		</a>
 	</li>
 	{%- endfor -%}
 	</ul>

_layouts/page.html

@@ -2,11 +2,16 @@
 layout: wrapper
 ---
 
+{%- unless page.amethyst.hero == false %}
 <section class="hero">
     <div class="wrapper">
         <h1 class="hero-title">{{ page.title }}</h1>
     </div>
 </section>
+{% endunless -%}
 <div class="main wrapper content">
+{%- if page.amethyst.hero == false -%}
+    <h1>{{ page.title }}</h1>
+{%- endif -%}
     {{ content }}
 </div>

_layouts/post.html

@@ -0,0 +1,37 @@
+---
+layout: wrapper
+---
+
+<div class="main main--columns wrapper">
+{% include sidebar.html blocks="sidebar_blog" %}
+<div class="content">
+	<article class="content">
+	<header>
+		<h1>{{ page.title | escape }}</h1>
+		{%- assign date_format = site.amethyst.date_format | default: "%e %B %Y" -%}
+		<p class="post-meta byline">Posted on <time itemprop="pubdate" datetime="{{ page.date | date_to_xmlschema }}">{{ page.date | date: date_format }}</time>{% if page.author %} by <span class="vcard"><span class="fn n" rel="author">{{ page.author | escape }}</span>{% endif %}</p>
+	</header>
+	{{ content }}
+	</article>
+{%- comment -%}
+Support basic read-only rendering of imported comments.
+
+Docs: <https://en.gravatar.com/site/implement/images/>
+{%- endcomment -%}
+{%- if page.amethyst.comments.size > 0 -%}
+<div id="comments" class="comments">
+<h2 id="comments-title">{{ page.amethyst.comments.size }} archived comment{% if page.amethyst.comments.size != 1 %}s{% endif %}</h2>
+<ol class="comment-list">
+	{%- for comment in page.amethyst.comments -%}
+	<li class="comment" id="comment-{{ forloop.index }}">
+		<div class="comment-meta">
+			<img alt="" src="https://gravatar.com/avatar/{{ comment.gravatar | default: 'none' }}?s=68&amp;d=mm&amp;r=g" srcset="https://gravatar.com/avatar/{{ comment.gravatar | default: 'none' }}?s=136&amp;d=mm&amp;r=g 2x" class="comment-avatar" loading="lazy" width="68" height="68">
+			<span class="comment-author">{{ comment.author | escape }}</span> on <a href="#comment-{{ forloop.index }}"><time datetime="{{ comment.date | date_to_xmlschema }}">{{ comment.date | date: date_format }}</time></a> said:</div>
+		<div class="comment-content">{{ comment.content | markdownify }}</div>
+	</li>
+	{%- endfor -%}
+</ol>
+</div>
+{%- endif -%}
+</div>
+</div>

_layouts/posts-archive.html

@@ -0,0 +1,17 @@
+---
+layout: wrapper
+---
+
+<div class="main main--columns wrapper">
+{% include sidebar.html blocks="sidebar_blog" %}
+{%- assign date_format = site.amethyst.date_format | default: "%e %B %Y" -%}
+{%- assign posts = site.posts -%}
+<div class="posts content">
+	<h1>{{ page.title }}</h1>
+	<ul>
+	{% for post in posts -%}
+		<li><a href="{{ post.url | relative_url }}">{{ post.title | escape }}</a>, <time datetime="{{ post.date | date_to_xmlschema }}">{{ post.date | date: date_format }}</time>.</li>
+	{%- endfor -%}
+	</ul>
+</div>
+</div>

_layouts/posts-author.html

@@ -0,0 +1,21 @@
+---
+layout: wrapper
+---
+
+<div class="main main--columns wrapper">
+{% include sidebar.html blocks="sidebar_blog" %}
+{%- assign date_format = site.amethyst.date_format | default: "%e %B %Y" -%}
+{%- assign posts = site.posts | where: 'author', page.author -%}
+<div class="posts content">
+	<h1>Author: {{ page.title | escape }}</h1>
+	{%- for post in posts -%}
+	<div class="post-row">
+		<h2><a href="{{ post.url | relative_url }}">{{ post.title | escape }}</a></h2>
+		<p class="post-meta">Posted on <time datetime="{{ post.date | date_to_xmlschema }}">{{ post.date | date: date_format }}</time></p>
+		<div class="post">
+			{{- post.excerpt -}}
+		</div>
+	</div>
+	{%- endfor -%}
+</div>
+</div>

_layouts/posts-tag.html

@@ -0,0 +1,24 @@
+---
+layout: wrapper
+---
+
+<div class="main main--columns wrapper">
+{% include sidebar.html blocks="sidebar_blog" %}
+{%- assign date_format = site.amethyst.date_format | default: "%e %B %Y" -%}
+{%- assign posts = site.tags[page.tag] -%}
+<div class="posts content">
+	<h1>Tag: {{ page.title | escape }}</h1>
+	{%- for post in posts -%}
+	<div class="post-row">
+		<h2><a href="{{ post.url | relative_url }}">{{ post.title | escape }}</a></h2>
+		<p class="post-meta">Posted on <time datetime="{{ post.date | date_to_xmlschema }}">{{ post.date | date: date_format }}</time>{% if post.author %} by {{ post.author | escape }}{% endif %}</p>
+		<div class="post">
+			{{- post.excerpt -}}
+			{%- if post.excerpt != post.content %}
+			<a class="screen-reader-text" href="{{ post.url | relative_url }}">Continue reading "{{ post.title | escape }}".</a>
+			{%- endif -%}
+		</div>
+	</div>
+	{%- endfor -%}
+</div>
+</div>

_layouts/posts-year.html

@@ -0,0 +1,24 @@
+---
+layout: wrapper
+---
+
+<div class="main main--columns wrapper">
+{% include sidebar.html blocks="sidebar_blog" %}
+{%- assign date_format = site.amethyst.date_format | default: "%e %B %Y" -%}
+{%- assign posts = page.posts -%}
+<div class="posts content">
+	<h1>Archive: {{ page.date | date: '%Y' }}</h1>
+	{%- for post in posts -%}
+	<div class="post-row">
+		<h2><a href="{{ post.url | relative_url }}">{{ post.title | escape }}</a></h2>
+		<p class="post-meta">Posted on <time datetime="{{ post.date | date_to_xmlschema }}">{{ post.date | date: date_format }}</time>{% if post.author %} by {{ post.author | escape }}{% endif %}</p>
+		<div class="post">
+			{{- post.excerpt -}}
+			{%- if post.excerpt != post.content %}
+			<a class="screen-reader-text" href="{{ post.url | relative_url }}">Continue reading "{{ post.title | escape }}".</a>
+			{%- endif -%}
+		</div>
+	</div>
+	{%- endfor -%}
+</div>
+</div>

_layouts/posts.html

@@ -0,0 +1,28 @@
+---
+layout: wrapper
+---
+
+<div class="main main--columns wrapper">
+{% include sidebar.html blocks="sidebar_blog" %}
+{%- assign date_format = site.amethyst.date_format | default: "%e %B %Y" -%}
+{%- assign posts = site.posts | slice: 0, 10 -%}
+<div class="posts content">
+	<h1>{{ page.title }}</h1>
+	{% for post in posts -%}
+	<div class="post-row">
+		<h2><a href="{{ post.url | relative_url }}">{{ post.title | escape }}</a></h2>
+		<p class="post-meta">Posted on <time datetime="{{ post.date | date_to_xmlschema }}">{{ post.date | date: date_format }}</time>{% if post.author %} by {{ post.author | escape }}{% endif %}</p>
+		<div class="post">
+			{{- post.excerpt -}}
+			{%- if post.excerpt != post.content %}
+			<a class="screen-reader-text" href="{{ post.url | relative_url }}">Continue reading "{{ post.title | escape }}".</a>
+			{%- endif -%}
+		</div>
+	</div>
+	{%- endfor -%}
+	{%- assign archive_page = site.pages | where: "layout", "posts-archive" | first -%}
+	{%- if site.posts.size > 10 and archive_page %}
+		<a href="{{ archive_page.url | relative_url }}">Older posts</a>
+	{%- endif -%}
+</div>
+</div>

_layouts/wrapper.html

@@ -1,7 +1,6 @@
 <!DOCTYPE html>
 <html lang="en">
 <meta charset="utf-8">
-<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">