Colophon

A colophon is a living reference document about how a site is built. Unlike my How This Blog Works post (a snapshot in time), this page stays current as the site evolves. It's documentation for my future self and a source of ideas for other developers building their own blogs.

Framework & Build

  • Astro 5 static site generator with TypeScript
  • Content Collections with Zod schema validation for blog posts
  • Zero client-side JavaScript by default
  • Shiki syntax highlighting with dual light/dark themes
  • Custom rehype plugin for collapsible code blocks
  • Satori + resvg for build-time OG image generation
  • Mermaid diagram support via CDN with theme-aware rendering using MutationObserver

Styling & Theme

  • Vanilla CSS with 30+ semantic custom properties
  • Light/dark/system theme selector with localStorage persistence and prefers-color-scheme detection
  • CSS checkbox hack for responsive hamburger nav (no JavaScript)
  • Print stylesheet included
  • System font stack — no web fonts loaded

Deployment & Infrastructure

  • Static files hosted on Amazon S3 at www.bstjohn.net
  • AWS OIDC authentication — no long-lived credentials stored in CI
  • Self-hosted GitHub Actions runners
  • PR preview deploys to /preview/PR-{N}-{sha}/ with automatic cleanup on merge/close

CI/CD Pipeline

  • ESLint, Prettier, and markdownlint for code and prose formatting
  • Vale prose linter for writing style
  • astro check for TypeScript and template type checking
  • html-validate for HTML correctness
  • lychee for link checking
  • Lighthouse CI with ≥ 0.9 thresholds for performance, accessibility, best practices, and SEO
  • RSS and JSON Feed validation

Bluesky Integration

  • Optional blueskyPostUri frontmatter field on posts
  • Auto-posting workflow after deploy (scripts/post-to-bluesky.mjs) with link card embeds and hashtag facets
  • Comment section fetching reply threads from the Bluesky API (app.bsky.feed.getPostThread, depth 6)
  • Comments lazy-loaded via IntersectionObserver
  • Build-time moderation allowlist

IndieWeb & Feeds

Analytics

  • Plausible Analytics — cookie-free, GDPR/CCPA compliant, no consent banner required
  • Injected in production builds only

Content Security Policy

  • default-src 'none' deny-by-default policy
  • Specific allowances for scripts, styles, images, fonts, and API connections (Bluesky, Plausible, webmention.io)

Changelog

April 2026
Added colophon page
Bluesky auto-posting and comment integration
Added dark mode and theme selector
January 2025
Launched with home lab posts on Flux CD and Let's Encrypt