Architecture Documentation

This document describes the architecture of the rocasta.com static site. Technology Stack Static Site Generator: Hugo (Extended) v0.164+ Theme: PaperMod Content Format: AsciiDoc (processed by Asciidoctor) Deployment: GitHub Pages via GitHub Actions Local Development: Hugo development server with live reload Directory Structure Path Purpose content/posts/ Blog posts in AsciiDoc content/arch/ Architecture and build documentation content/about.md About page static/images/ Static images served at /images/ themes/PaperMod/ Git submodule for theme public/ Built site output (gitignored) ...

This document explains the design decisions behind the site. Why Hugo over Jekyll The site was originally built with Jekyll 4.4.1 + Chirpy theme. It was migrated to Hugo + PaperMod for the following reasons: Ruby Version Incompatibility Jekyll’s dependency chain (specifically the jekyll-theme-chirpy gem) requires Ruby ~> 3.1. Modern systems ship with Ruby 4.x, requiring a version manager (chruby, rbenv) to build locally. Hugo is a single Go binary with no runtime dependencies. ...

Step-by-step instructions to build and maintain a Hugo + PaperMod + AsciiDoc static site on GitHub Pages. Prerequisites Homebrew (macOS) or equivalent package manager Git Hugo Extended (installed via Homebrew) brew install hugo hugo version Verify the output includes extended: hugo v0.164.0+extended ... Asciidoctor Hugo requires asciidoctor to process .adoc files: brew install asciidoctor gem install asciidoctor Verify: asciidoctor --version Project Setup Create a New Site hugo new site my-site cd my-site ...