Site Guide

This guide describes the current Hugo + PaperMod layout, maintenance scripts, blog generation flow, and publishing behavior.

Source of Truth

• Edit source files in content/.
• public/ is generated output only (hugo --minify).
• Run backup before non-trivial updates:

bash scripts/backup-site.sh

Current Structure

• content/blog/YYYY/*.md → blog post source files grouped by year
• content/about.md → about page
• content/resume.md → resume page
• content/site-guide.md → this guide
• content/search.md → search page (PaperMod Fuse.js)
• content/_index.md → homepage
• content/blog/_index.md → blog section page
• hugo.toml → site configuration (menu, params, taxonomies)
• assets/css/extended/custom.css → theme colour overrides
• assets/css/extended/syntax.css → code syntax token colours
• layouts/ → Hugo template overrides and render hooks
• layouts/_default/_markup/render-link.html → cross-post link rewriter (temporary)
• layouts/_default/_markup/render-codeblock-mermaid.html → Mermaid diagram support
• layouts/partials/extend_head.html → favicon + fonts
• layouts/partials/extend_footer.html → site footer + Mermaid JS
• layouts/404.html → custom 404 page
• archetypes/blog.md → new post template
• static/favicon.svg → site favicon
• static/images/grobauskas-profile-small.jpg → profile avatar
• themes/PaperMod/ → PaperMod theme (git submodule)
• alignment/ → AI writing style alignment (not site content)

Scripts

• Create a new blog post:

hugo new blog/2026/my-post-title.md

This creates a post from archetypes/blog.md with pre-filled front matter and draft: true.

• Local development server (includes drafts):

hugo server -D

• Production build:

hugo --minify

• Backup source:

bash scripts/backup-site.sh

• Audit <!-- more --> excerpt markers across all posts:

python scripts/audit-more-tags.py

• Audit non-ASCII characters:

python scripts/audit-unicode.py [--fix]

Blog Post Requirements

Each post file should include front matter similar to archetypes/blog.md.

Recommended fields:

• title
• description
• author
• date (YYYY-MM-DD)
• updated (YYYY-MM-DD, optional — Hugo reads this as lastmod)
• tags (list)
• draft (true or false)

Behavior:

• draft: true posts are excluded from production builds (visible with hugo server -D).
• Posts are sorted by date descending.
• Excerpt is content above <!-- more --> (Hugo’s native .Summary split).
• If updated is present, Hugo displays it as the last modified date.
• RSS feed generated automatically at /index.xml.
• Tags taxonomy at /tags/.

Route and Link Behavior

• Blog post URLs: /blog/YYYY/post-slug/
• About: /about/
• Resume: /resume/
• Tags: /tags/
• Search: /search/
• RSS: /index.xml

CI / Deploy

• .github/workflows/deploy.yml runs hugo --minify and publishes on every push to main.
• GitHub Pages publishes from public/ via the actions/deploy-pages action.
• PaperMod theme is a git submodule — the workflow checks out submodules automatically.
• CNAME file is copied into public/ during build.
• Enable publishing in the repo under Settings → Pages → Source → GitHub Actions.

Editing Standards

• Keep CSS and theme changes in assets/css/extended/custom.css.
• Keep syntax highlighting in assets/css/extended/syntax.css.
• Preserve accessibility (contrast, readable type, visible focus states).
• Update this guide if structure, scripts, or route behavior changes.

Style Review Sandbox

Use this collapsible block when testing content rendering during style changes.

bash scripts/backup-site.sh
hugo --minify

def hello(name: str) -> str:
    return f"Hello, {name}"

{
  "site": "hugo",
  "theme": "PaperMod"
}

References

• Hugo: https://gohugo.io/
• PaperMod theme: https://github.com/adityatelange/hugo-PaperMod/