From 9c4f3a57e3616b42764e1c934ac76c0bb8157a29 Mon Sep 17 00:00:00 2001 From: Paul Duncan Date: Thu, 30 May 2024 04:19:28 -0400 Subject: add content/articles/site-backend.md (draft) --- content/articles/site-backend.md | 178 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 178 insertions(+) create mode 100644 content/articles/site-backend.md (limited to 'content') diff --git a/content/articles/site-backend.md b/content/articles/site-backend.md new file mode 100644 index 0000000..6bfa592 --- /dev/null +++ b/content/articles/site-backend.md @@ -0,0 +1,178 @@ +--- +slug: "site-backend" +title: "Site Backend" + +# date (optional for articles) +date: "2023-09-08T05:07:47-04:00" + +# draft articles are not visible on live site +draft: true + +# show on articles page +show: true + +# uncomment to show table of contents +toc: true +--- +## Overview + +This site is statically generated by [Hugo][] and themed with a +stripped-down version of [Bulma][]. Both have been heavily customized; +see the [Configuration](#configuration) section for details. + +The goals of this setup are: + +- Size +- Speed +- Security +- Mobile Support +- Accessibility +- Simplicity (for me) + +## History + +From 1998 to 2019 this site was generated by a custom [PHP][] backend, +written by me. In 2019 I resurrected the site after a several year +hiatus and migrated the site from the custom [PHP][] backend to +[Jekyll][]. In 2021 I switched from [Jekyll][] to [Hugo][]. + +## Content + +### HTML + +I create and edit site content with [vim][] in [Markdown][] format and +preview the results locally with `hugo serve -D ...`. Articles and blog +posts are saved as drafts and committed to the [Git][] repository so I +can work on them as time permits. + +The content and site layout is designed with accessibility and mobile in +mind. This means: + +- links, and table components have `title`, `aria-label` attributes +- images have captions, fallback formats, `title` and `alt` attributes. +- images scale gracefully to thumbnails on mobile +- the site honors users' [color scheme preference][] and has a manual + theme override +- The page menu bar collapes to a hamburger menu on mobile. + +### Images + +Images are created as follows: + +- Mathematical content is created using [Mathy][], saved as [SVG][], + and minified using [minify][]. +- Charts are created with [Matplotlib][], saved as [SVG][], and minified + using [minify][]. +- Lossless images (e.g. screenshots) are scaled and cropped with + [GraphicsMagick][] and served as a lossless [WebP][] + with a [PNG][] fallback. The fallback is compressed with + [pngquant][]. +- Lossy images are [GraphicsMagick][] and served as a lossy [WebP][] + with a [JPEG][] fallback. +- Menubar icons are borrowed from [Bootstrap Icons][]. +- The animated site logo is generated by [this Ruby script][logo-script]. + +### JavaScript + +There is almost no [JavaScript][], by design. The one script that is +used is minimal, [deferred][], used for two things: + +1. to handle the [theme toggle][]. +2. to toggle the mobile site menu. + +## Deployment + +Once I am ready to apply any outstanding changes to the public web site, +I push the outstanding commits to a remote [Git][] repository. This +triggers a [`post-receive` hook][], which sends an authenticated `POST` +request to a [web hook][] exposed on a TLS endpoint on the web server. + +The [web hook][] runs a [deployment script (`deploy.rb`)][] which does +the following: + +1. Verifies the authenticated timestamp (to prevent replay attacks). +2. Clones the upstream repository. +3. Executes [Hugo][] (`hugo --minify -d ...`) to build the site minified + in a unique output directory. +4. Updates the `htdocs` symlink for the public web site to point at + the output directory from the previous step. +5. Removes any stale builds. + +## Configuration + +This section discusses the configuration for [Hugo][], [Bulma][] and +[Apache][]. + +### Hugo Configuration + +[Hugo][] is configured to use [Chroma syntax higlighting][] with inline +styles disabled (e.g., `class` attributes only, no `style`) in order to +support the restrictive `Content-Security-Policy` header (see "HTTP +Headers"). + +The formatted tables in the pages site are generated via [my +`hugo-shortcode-table` shortcode][], because the native table generator +for [Hugo][] uses inline styles. + +I have also written a couple of custom [shortcodes][] to generate +`` and `
` elements in order to support [progressive +enhancement][]. + +The generated [HTML][] has been modified to: + +- add support `go-import` +- add a [Mastodon][] `` tag. +- remove all unnecessary tags +- to combine and [minify][] and [JavaScript][] and [CSS][] assets. +- to add `integrity` attributes to `` and `