https://www.rocasta.com/arch/Recent content in Architecture Documentation on Rocasta Dot ComHugoenTue, 07 Jul 2026 00:00:00 +0000https://www.rocasta.com/arch/architecture/Tue, 07 Jul 2026 00:00:00 +0000https://www.rocasta.com/arch/architecture/<div class="paragraph"> <p>This document describes the architecture of the rocasta.com static site.</p> </div> <div class="sect1"> <h2 id="_technology_stack"><a class="anchor" href="#_technology_stack"></a>Technology Stack</h2> <div class="sectionbody"> <div class="ulist"> <ul> <li> <p><strong>Static Site Generator:</strong> Hugo (Extended) v0.164+</p> </li> <li> <p><strong>Theme:</strong> PaperMod</p> </li> <li> <p><strong>Content Format:</strong> AsciiDoc (processed by Asciidoctor)</p> </li> <li> <p><strong>Deployment:</strong> GitHub Pages via GitHub Actions</p> </li> <li> <p><strong>Local Development:</strong> Hugo development server with live reload</p> </li> </ul> </div> </div> </div> <div class="sect1"> <h2 id="_directory_structure"><a class="anchor" href="#_directory_structure"></a>Directory Structure</h2> <div class="sectionbody"> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 50%;"/> <col style="width: 50%;"/> </colgroup> <thead> <tr> <th class="tableblock halign-left valign-top">Path</th> <th class="tableblock halign-left valign-top">Purpose</th> </tr> </thead> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>content/posts/</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Blog posts in AsciiDoc</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>content/arch/</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Architecture and build documentation</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>content/about.md</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">About page</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>static/images/</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Static images served at <code>/images/</code></p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>themes/PaperMod/</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Git submodule for theme</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>public/</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Built site output (gitignored)</p></td> </tr> </tbody> </table> </div>https://www.rocasta.com/arch/design-guide/Tue, 07 Jul 2026 00:00:00 +0000https://www.rocasta.com/arch/design-guide/<div class="paragraph"> <p>This document explains the design decisions behind the site.</p> </div> <div class="sect1"> <h2 id="_why_hugo_over_jekyll"><a class="anchor" href="#_why_hugo_over_jekyll"></a>Why Hugo over Jekyll</h2> <div class="sectionbody"> <div class="paragraph"> <p>The site was originally built with Jekyll 4.4.1 + Chirpy theme. It was migrated to Hugo + PaperMod for the following reasons:</p> </div> <div class="sect2"> <h3 id="_ruby_version_incompatibility"><a class="anchor" href="#_ruby_version_incompatibility"></a>Ruby Version Incompatibility</h3> <div class="paragraph"> <p>Jekyll’s dependency chain (specifically the <code>jekyll-theme-chirpy</code> gem) requires Ruby <code>~&gt; 3.1</code>. Modern systems ship with Ruby 4.x, requiring a version manager (<code>chruby</code>, <code>rbenv</code>) to build locally. Hugo is a single Go binary with no runtime dependencies.</p> </div>https://www.rocasta.com/arch/build-guide/Tue, 07 Jul 2026 00:00:00 +0000https://www.rocasta.com/arch/build-guide/<div class="paragraph"> <p>Step-by-step instructions to build and maintain a Hugo + PaperMod + AsciiDoc static site on GitHub Pages.</p> </div> <div class="sect1"> <h2 id="_prerequisites"><a class="anchor" href="#_prerequisites"></a>Prerequisites</h2> <div class="sectionbody"> <div class="ulist"> <ul> <li> <p>Homebrew (macOS) or equivalent package manager</p> </li> <li> <p>Git</p> </li> <li> <p>Hugo Extended (installed via Homebrew)</p> </li> </ul> </div> <div class="listingblock"> <div class="content"> <pre class="rouge highlight"><code data-lang="sh">brew <span class="nb">install </span>hugo hugo version</code></pre> </div> </div> <div class="paragraph"> <p>Verify the output includes <code>extended</code>:</p> </div> <div class="literalblock"> <div class="content"> <pre>hugo v0.164.0+extended ...</pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_asciidoctor"><a class="anchor" href="#_asciidoctor"></a>Asciidoctor</h2> <div class="sectionbody"> <div class="paragraph"> <p>Hugo requires <code>asciidoctor</code> to process <code>.adoc</code> files:</p> </div> <div class="listingblock"> <div class="content"> <pre class="rouge highlight"><code data-lang="sh">brew <span class="nb">install </span>asciidoctor gem <span class="nb">install </span>asciidoctor</code></pre> </div> </div> <div class="paragraph"> <p>Verify:</p> </div> <div class="literalblock"> <div class="content"> <pre>asciidoctor --version</pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_project_setup"><a class="anchor" href="#_project_setup"></a>Project Setup</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_create_a_new_site"><a class="anchor" href="#_create_a_new_site"></a>Create a New Site</h3> <div class="listingblock"> <div class="content"> <pre class="rouge highlight"><code data-lang="sh">hugo new site my-site <span class="nb">cd </span>my-site</code></pre> </div>