1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
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
`<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."
|
