From 937f7ee259c6a3c20136ed2e72a600c86203f79f Mon Sep 17 00:00:00 2001 From: Paul Duncan Date: Fri, 31 May 2024 15:11:42 -0400 Subject: content/articles/site-backend.md: add remaining content, mark as published --- content/articles/site-backend.md | 278 ++++++++++++++++++++++++++++----------- 1 file changed, 200 insertions(+), 78 deletions(-) diff --git a/content/articles/site-backend.md b/content/articles/site-backend.md index 5fb750b..ca36b2d 100644 --- a/content/articles/site-backend.md +++ b/content/articles/site-backend.md @@ -5,9 +5,6 @@ title: "Site Backend" # date (optional for articles) date: "2024-05-31T03:57:18-04:00" -# draft articles are not visible on live site -draft: true - # show on articles page show: true @@ -46,6 +43,11 @@ Site content is managed as [Markdown][] files stored in a [Git][] repository. The theme is a modified version of [Bulma][]. The site is statically generated by [Hugo][]. +I create and edit site content with [Vim][] 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. + [{{< pe-figure "editing" >}}][editing-this-article] ## History @@ -57,47 +59,44 @@ hiatus and migrated the site from the custom [PHP][] backend to ## Goals -The goals of this site backend are: +The content and layout of this site should be: - Small - Fast - Secure -- Mobile-friendly - Accessible -- Simple (for me) - -Static generation neatly addresses the first three goals: - -- The site is small because the [Hugo][] can be configured to - aggressively pack and minify content and assets. Images are - also compressed and served in multiple formats (see [Hugo - Configuration](#hugo-configurationi "Hugo Configuration") and [Images](#images - "Images")). -- The site is fast because web servers can serve static content - extremely quickly, and because static content can be cached. Caching - and compression are enabled in [Apache][] (see [Apache - Configuration](#apache-configuration "Apache Configuration")). -- The site is secure because the content is static; there is no - web-accessible endpoint which can upload files or modify content. - Additional security measures are discussed in several of the following - sections. - -Explanations of how I keep the site mobile-friendly and accessible are -available in the [HTML](#html "HTML") and [Hugo -Configuration](#hugo-configuration "Hugo Configuration") sections below. - -**TODO:** discuss simplicity +- Mobile-friendly + +These goals are addressed as follows: + +- Small: [Hugo][] is configured to aggressively pack content and minify + assets. Images are compressed and served in multiple formats. [HTTP + compression][http compression] is enabled (with caution). See + [Hugo Configuration][s-hugo-configuration], [Images][s-images] and + [Apache Configuration][s-apache-configuration]. +- Fast: Static content can be served quickly. Assets are fingerprinted + and browser caching is enabled. See [Hugo + Configuration][s-hugo-configuration] and [Apache + Configuration][s-apache-configuration]. +- Secure: Static content; no web-accessible endpoint which can make + changes. Additional security measures are discussed in + [Deployment][s-deployment], [Apache + Configuration][s-apache-configuration], and [Other][s-other]. +- Accessible: Addressed when creating content and with custom + [shortcodes][shortcode]. See [HTML][s-html] and [Hugo + Configuration][s-hugo-configuration]. +- Mobile-friendly: Addressed when creating content and with the site + theme. See [HTML][s-html] and [Bulma + Configuration][s-bulma-configuration]. ## Content -### HTML +This section describes how content is created for this site. -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. +### HTML -The content and layout is designed to be accessible and mobile-friendly: +The site content and layout is designed to be accessible and +mobile-friendly: - links and table components have `title` and `aria-label` attributes - images have captions, fallback formats, and `title` and `alt` attributes @@ -107,6 +106,12 @@ The content and layout is designed to be accessible and mobile-friendly: and has a [manual theme switcher][post-theme-switcher] - The menu bar collapes to a hamburger menu on mobile. +Here are a few articles which cover guidelines that I follow: + +- [Progressive Enhancement][] +- [Why your website should be under 14kB in size][14kb] +- [5 things you don't need JavaScript for][you-dont-need-js] + ### Images Images are created as follows: @@ -130,6 +135,23 @@ Other notes: - Menubar icons are borrowed from [Bootstrap Icons][]. - I reviewed several [PNG][] compressors in [this post][post-png-compressors]. +Managing images manually helps to keep the site small and fast. Here +are a couple common [GraphicsMagick][] commands: + +```sh +# scale with antialiasing and convert from png to webp +gm convert -antialias -scale 1024x1024 some-image.{png,webp} + +# get image dimensions +gm identify some-image.png + +# convert from png to webp (lossless) +gm convert -quality 100 -define webp:lossless=true some-image.{png,webp} + +# crop image to 256x256 +gm convert -crop 256x256 some-image{,-cropped}.png +``` + ### JavaScript This site has almost no [JavaScript][], by design. The [JavaScript][] @@ -137,7 +159,7 @@ that is used is minimal, [modern][es2015], [deferred][], and only used for the [theme switcher][post-theme-switcher] and burger menu. Below is the unminified `script.js` for this site with some notes -removed. It is 777 bytes minified and 586 bytes minified and +removed. It is served as 777 bytes minified and 586 bytes minified and compressed: ```js @@ -207,21 +229,20 @@ This section discusses the configuration for [Apache][], [Bulma][], ### Apache Configuration -This section disusses the [Apache][] configuration for this site. I -have broken this section into three sub-sections to make them easier to -digest. +This section disusses the [Apache][] configuration for this site. The +information is divided into several sub-sections in order to make it +easier to digest. -The [Apache][] configuration relies on the following modules: +This site relies on the following [Apache][] modules: -- [mod\_deflate][mod-deflate] (see note below) -- [mod\_http2][mod-http2] -- [mod\_macro][mod-macro] -- [mod\_proxy][mod-proxy] -- [mod\_rewrite][mod-rewrite] - -Note: It is safe for this site to enable [mod\_deflate][mod-deflate] -because it does not use [cookies][] and is not vulnerable to [BREACH][]. -and does not use [cookies][]. +- [mod\_deflate][mod-deflate]: Enable [HTTP compression][]. +- [mod\_http2][mod-http2]: Enable [HTTP/2][]. +- [mod\_macro][mod-macro]: Simplify common configuration. +- [mod\_proxy][mod-proxy]: Proxy [web hook][] requests to internal + [webhook][] daemon. +- [mod\_rewrite][mod-rewrite]: Unconditionally redirect from [HTTP][] to + [HTTPS][], strip `www.` from the path hostname, and redirect from legacy + [URLs][url]. #### Virtual Host Configuration @@ -230,7 +251,8 @@ The [Apache][] virtual host configuration is modified as follows: - Unconditionally redirect from [HTTP][] to [HTTPS][] - Unconditionally redirect to strip the `www.` hostname prefix - Enable [HTTP/2][] -- Set security headers (discussed in [Security Headers](#security-headers)) +- Set security headers (discussed in [Security + Headers][s-security-headers]) - Enable aggressive caching of image, script, and style assets Below is the [Apache][] virtual host configuration for this site with @@ -285,6 +307,17 @@ redirects removed: [Download][apache-vhost.conf] +#### HTTP Compression + +[HTTP compression][] is supported via [mod\_deflate][mod-deflate]. + +It is safe for this site to enable [mod\_deflate][mod-deflate] because +it does not use [cookies][] and is not vulnerable to [BREACH][]. + +In 2022 I tried [mod\_brotli][mod-brotli], but the improvement over +[mod\_deflate][mod-deflate] was minimal (deflate: 125k, brotli: 117k) so +I abandoned it. + #### Security Headers This site uses a strict [Content-Security-Policy][] header; it rejects @@ -427,28 +460,30 @@ minified and compressed. ### 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"). +[Hugo][] is configured to use [Chroma syntax higlighting][chroma] with +inline styles disabled in order to support the strict +[Content-Security-Policy][]. See [Security Headers][s-security-headers] +for details. -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. +Tables are are generated by [a custom table +shortcode][hugo-shortcode-table], because the [Hugo's][hugo] native +[Markdown][] table generator in [Hugo][] uses inline styles. -I have also written a couple of custom [shortcodes][] to generate -`` and `
` elements in order to support [progressive -enhancement][]. +I have also written a couple of custom [shortcodes][shortcode] to +generate `` and `
` elements in order to support +[progressive enhancement][]. -The generated [HTML][] has been modified to: +Custom archetypes have been added for the [Archives][] section, blog +posts, articles, and projects. -**TODO:** +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 `