Set up documentation website generation and deployment

.github/workflows/deploy-website.yaml

@@ -8,7 +8,7 @@ permissions:
   pages: write
   id-token: write
 concurrency:
-  group: "pages"
+  group: pages
   cancel-in-progress: true
 jobs:
   build:
@@ -19,13 +19,13 @@ jobs:
       - name: Configure Github Pages
         uses: actions/configure-pages@v2.1.1
       - name: Generate documentation
-        run: bash ./generate-docs.sh
+        run: ./generate-docs.sh
       - name: Build website with Jekyll
         uses: actions/jekyll-build-pages@v1.0.5
         with:
           source: website/
           destination: ./_site
-      - name: Validating HTML output
+      - name: Validate HTML output
         uses: anishathalye/proof-html@v1.4.1
         with:
           directory: ./_site
@@ -34,11 +34,11 @@ jobs:
         uses: actions/upload-pages-artifact@v1.0.4
   deploy:
     if: github.ref == format('refs/heads/{0}', github.event.repository.default_branch)
+    needs: build
+    runs-on: ubuntu-22.04
     environment:
       name: github-pages
       url: ${{ steps.deployment.outputs.page_url }}
-    runs-on: ubuntu-22.04
-    needs: build
     steps:
       - name: Deploy to GitHub Pages
         id: deployment

generate-docs.sh

@@ -1,5 +1,7 @@
 #!/usr/bin/env bash
 
+set -e -u -o pipefail
+
 WEBSITE_FOLDER="website"
 HOMEPAGE="${WEBSITE_FOLDER}/index.md"
 

website/.gitignore

@@ -1,14 +1,12 @@
-### Jekyll ###
-_site/
-.sass-cache/
+# Generated by Bundler and Jekyll.
+.bundle/
+Gemfile.lock
 .jekyll-cache/
 .jekyll-metadata
-Gemfile.lock
-
-# Ignore folders generated by Bundler
-.bundle/
+.sass-cache/
+_site/
 vendor/
 
-# Generated content
+# Generated by `../generate-docs.sh`.
 *.bak
 index.md

website/Gemfile

@@ -1,5 +1,4 @@
 source "https://rubygems.org"
-gem "github-pages", "~> 227"
-gem "rake", "~> 13.0" # Required for "just-the-docs" theme.
-gem "jekyll-sitemap", "~> 1.4"
-gem "html-proofer", "~> 4.4"
+gem "github-pages", "227"
+gem "html-proofer", "4.4.1"
+gem "just-the-docs", "0.4.0.rc2"

website/README.md

@@ -15,16 +15,10 @@ bundle install
 ```
 
 The website will now be [available][localhost-port-4000] on port 4000. Source
-code modifications will automatically be reflected. (An exception is
-`_config.yml`: changes to this file require a server restart.) Subsequent
-server restarts do not require running `bundle install`, unless `Gemfile` has
-been updated in the interim.
-
-Documentation can be regenerated whist jekyll is running, by executing:
-
-```sh
-../generate-docs.sh
-```
+code modifications (including the result of rerunning `../generate-docs.sh`)
+will automatically be reflected. (An exception is `_config.yml`: changes to
+this file require a server restart.) Subsequent server restarts do not require
+running `bundle install`, unless `Gemfile` has been updated in the interim.
 
 If you are not familiar with Jekyll, be sure to check out its
 [documentation][jekyll-docs]. It is recommended to follow the provided

website/_config.yml

@@ -3,39 +3,36 @@ title: Error Prone Support
 logo: assets/images/favicon.svg
 url: https://error-prone.picnic.tech
 description: >-
-  Error Prone extensions: extra bug checkers and a large battery of Refaster templates.
+  Error Prone extensions: extra bug checkers and a large battery of Refaster
+  templates.
 
-remote_theme: just-the-docs/just-the-docs
+theme: just-the-docs
 plugins:
-- jekyll-remote-theme
-- jekyll-sitemap
+  - jekyll-sitemap
 
-# Do not deploy these files and folders through GitHub pages.
+# Files and directories not to be deployed through GitHub pages.
 exclude:
   - Gemfile
   - Gemfile.lock
   - README.md
   - vendor
 
-permalink: pretty # Use /doc/ instead of /doc.html.
-
-# Theme configuration.
-search_enabled: true
-heading_anchors: true
+# See https://jekyllrb.com/docs/permalinks/#built-in-formats.
+permalink: pretty
 
+# See https://just-the-docs.github.io/just-the-docs/docs/navigation-structure/#external-navigation-links.
 nav_external_links:
   - title: Error Prone Support on GitHub
     url: https://github.com/PicnicSupermarket/error-prone-support
     hide_icon: false
 
-# Author configuration.
-twitter:
-  username: picnic
-  card: summary
-
+# See https://jekyll.github.io/jekyll-seo-tag/usage/.
 social:
   name: Picnic
   links:
     - https://github.com/PicnicSupermarket
     - https://twitter.com/picnic
     - https://www.linkedin.com/company/picnictechnologies
+twitter:
+  username: picnic
+  card: summary

website/_sass/custom/custom.scss

@@ -17,6 +17,7 @@
     vertical-align: text-bottom;
 }
 
+// Center and shrink the footer logo.
 footer > img#logo {
     width: 2rem;
     margin: 0 auto;