---
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
`<picture>` and `<figure>` elements in order to support [progressive
enhancement][].

The generated [HTML][] has been modified to:

- add support `go-import` 
- add a [Mastodon][] `<link rel='me' ...>` tag.
- remove all unnecessary tags 
- to combine and [minify][] and [JavaScript][] and [CSS][] assets.
- to add `integrity` attributes to `<link>` and `<script>` tags.

### Bulma Configuration

**TODO:**

- bulma modified to remove all unnecessary components
  - show `style.css`
- added chroma styles
- added dark mode

### Apache Configuration

**TODO:**

- security headers (see next section)
- `static/files/articles/site-backend/pablotron.org.conf.txt` (config w/ garbage removed)
- mod deflate
- mod rewrite for old links
- aggressive caching
- http2
- letsencrypt
- tls config (1.2 or newer, remove garbage algos)

## HTTP Security Headers

TODO

## Validation

I periodically verify the following manually:

- Developer console: Page load time, cached and uncached page size.
- [Lighthouse][]: Accessibility, desktop score, and mobile score.
- security headers
- tls configuration
- manual verification in the desktop and mobile versions of chrome and
  firefox

## Other

- content served minified, cached, and compressed.
(more stuff from `TODO.md`)

```apache
# TODO: include annotated files/articles/site-backend/pablotron.org.conf.txt
```

[hugo]: https://gohugo.io/
  "Hugo static site generator."
[bulma]: https://bulma.io/
  "Bulma minimal CSS framework."