ronnieops

RonnieOps — Hugo Blog

A static IT/tech blog built with Hugo and the hugo-theme-stack theme, deployed on Cloudflare Workers Static Assets with a Worker wrapper for security headers and per-request nonce CSP.

Prerequisites

• Hugo Extended ≥ v0.160.1 (install guide)
• Dart Sass ≥ v1.99.0 (required for SCSS compilation)
• Git ≥ 2.x
• Node.js ≥ 18 (for markdownlint)

Quick Start

# Initialize theme submodule (first checkout only)
git submodule update --init --recursive

# Start the dev server with draft posts visible
hugo server -D

# Full production build (Hugo + Dart Sass)
bash build.sh

# Preview the production build locally
npx wrangler dev

The dev server runs at http://localhost:1313/ by default.

Content Creation

# Create a new blog post (uses archetypes/posts.md)
hugo new content posts/my-new-post-slug.md

New content files are created as drafts (draft: true). Edit the front matter and body, then set draft: false to publish.

Post Front Matter

---
title: "Post Title"
date: 2026-05-19
draft: false
description: "Short description for SEO and Open Graph"
image: "/img/posts/my-post-cover.png"
tags: ["tag1", "tag2"]
categories: ["category1"]
series: ["series-name"]
keywords: ["keyword1"]
math: false
comments: false
license: false
---

See archetypes/posts.md for the full template with all available fields.

Project Structure

.
├── archetypes/
│   ├── default.md                # Default content template
│   └── posts.md                  # Blog post template (TOML front matter)
├── assets/
│   ├── scss/
│   │   ├── custom.scss           # Brand overrides + terminal chrome system
│   │   └── _fonts.scss           # Self-hosted Inter @font-face declarations
│   └── ts/
│       └── mermaid.ts            # Mermaid diagram module (theme asset)
├── content/
│   ├── _index.md                 # Homepage content (rendered below terminal chrome)
│   ├── about.md                  # About page
│   ├── page/
│   │   ├── archives/index.md     # Archives page
│   │   └── search/index.md       # Search page
│   ├── posts/                    # Blog posts
│   ├── categories/_index.md      # Categories taxonomy
│   ├── tags/_index.md            # Tags taxonomy
│   └── series/_index.md          # Series taxonomy
├── layouts/
│   ├── home.html                 # Homepage override (terminal chrome + _index.md content)
│   ├── single.html               # Single post override (includes series navigation)
│   ├── posts/list.html           # Posts list (standard Stack compact list)
│   ├── _markup/
│   │   └── render-codeblock-mermaid.html  # Mermaid diagram render hook
│   └── _partials/
│       ├── article-list/tile.html         # Tile card (CSP-compliant data-* attrs)
│       ├── article/components/
│       │   ├── details.html               # Article details
│       │   ├── mermaid.html               # Mermaid partial override (self-hosted)
│       │   └── series-nav.html            # Series prev/next navigation
│       ├── comments/include.html          # Comments (consent-gated, disabled)
│       ├── head/custom.html               # Custom head (JS, JSON-LD structured data)
│       ├── head/custom-font.html          # Font loading (empty — Inter via SCSS)
│       ├── head/style.html                # Dart Sass config (silenceDeprecations)
│       └── sidebar/left.html              # Sidebar with logo + terminal dots
├── scripts/
│   ├── generate-assets.js         # SVG → PNG asset generation
│   └── validate-csp-hashes.sh    # CSP nonce validation (runs in CI)
├── src/
│   └── entry.js                  # Cloudflare Worker (nonce CSP, security headers)
├── static/
│   ├── fonts/                    # Self-hosted Inter WOFF2 (7 subsets)
│   ├── img/                      # Brand assets (SVG source + PNG rendered)
│   └── js/
│       ├── inline-styles.js      # CSP-compliant dynamic styles
│       └── mermaid.min.js        # Self-hosted Mermaid v11.4.0
├── themes/stack/                  # Theme (git submodule)
├── .github/workflows/deploy.yml  # CI/CD (lint → build → deploy)
├── hugo.toml                     # Hugo configuration
├── wrangler.jsonc                # Cloudflare Workers config
└── build.sh                      # Production build script

Features

Core

• Terminal chrome brand — traffic-light dots, >_ prompt, blinking cursor, scanlines, grid overlay, R badge
• Dark cyber aesthetic via hugo-theme-stack with custom purple brand system
• Inter sans-serif font (self-hosted, no CDN) — 7 WOFF2 subsets
• Syntax highlighting with Hugo built-in Chroma (dracula theme)
• Dark/light mode toggle with prefers-color-scheme auto-detection
• Mermaid diagrams — self-hosted v11.4.0, expand/modal UI
• Series navigation — prev/next links for multi-part tutorials
• Taxonomies: categories, tags, series

Search

• Built-in theme search at /page/search — JSON index, client-side

Security

• Per-request nonce CSP — Worker generates cryptographic nonce per request, injects into <script> tags. No static hashes, no unsafe-inline.
• Self-hosted fonts — no Google Fonts CDN
• Security headers — HSTS, X-Frame-Options, X-Content-Type-Options, Referrer-Policy, Permissions-Policy
• CSP validation in CI — scripts/validate-csp-hashes.sh checks nonce setup

Deployment

• Cloudflare Workers Static Assets — Worker serves assets, injects nonce + security headers
• GitHub Actions CI/CD — lint → Hugo build → CSP validate → wrangler deploy
• run_worker_first: true — all requests go through Worker (headers guaranteed)

Brand Assets

Brand assets are in static/img/:

File	Format	Size	Purpose
favicon.svg / favicon.png	SVG / PNG 32×32	Browser tab icon
apple-touch-icon.svg / .png	SVG / PNG 180×180	iOS home screen
logo.svg / logo.png	SVG / PNG 512×512	Sidebar avatar
banner.svg / banner.png	SVG / PNG 1200×630	OG / social sharing

Regenerate PNGs from SVG sources: node scripts/generate-assets.js

Full brand spec: BRAND_IDENTITY.md

Documentation

File	Purpose
BRAND_IDENTITY.md	Visual identity spec (colors, motifs, asset specs)
SOCIAL_BRANDING.md	Social media bio templates
docs/CONTENT-AUTHORING.md	Content writing guide
docs/HSTS-FIX.md	HSTS configuration notes

Key Versions

Component	Version
Hugo	v0.160.1
Dart Sass	v1.99.0
Stack theme	git submodule (CaiJimmy/hugo-theme-stack)
Mermaid	v11.4.0 (self-hosted)
Wrangler	v3

License

All rights reserved.