AGENTS.md — fosscat.com Hugo Site

What This Is

Hugo static site (fosscat.com). Personal blog + projects. Custom vendored Gokarna theme with Kimber base16 color palette and Maple Mono font.

Essential Commands

hugo server          # Dev server with live reload
hugo                 # Build to public/
hugo new posts/my-post.md       # New blog post
hugo new projects/my-project.md # New project

No Makefile, no package.json, no CI. Nix flake + direnv auto-loads all tools on directory entry.

Verify Changes

Run hugo server and check localhost:1313. Hugo reports template/config errors on build. No test suite — visual verification only.

Key Files

File	Purpose
`config.toml`	Hugo config (theme, nav, params, syntax highlighting)
`flake.nix`	Nix dev environment (hugo, marksman, prettier, markdownlint, aspell)
`archetypes/default.md`	Post front matter template
`archetypes/projects.md`	Project front matter template (includes status color reference)
`.markdownlint.jsonc`	Markdownlint config
`.aspell.en.pws`	Personal spell check dictionary

Content

Posts (content/posts/*.md): Front matter fields: title, date, lastmod, description, tags, type: "post", showTableOfContents, image, image_alt, image_caption, draft.

Projects (content/projects/*.md): Same as posts plus status (string) and statusColor (hex). Colors: green #99c899, blue #537c9c, yellow #d8b56d, red #704f4f, grey #c3c3b4, pink #c88c8c.

Homepage about: content/index-about.md (loaded by layouts/index.html via readFile).

Layout Overrides (`layouts/`)

Root layouts/ overrides take precedence over themes/gokarna/layouts/. Current overrides:

index.html — 2-column home grid: recent posts + project updates card with status badges
partials/post.html — featured image support
partials/page.html — date/lastmod display logic
_default/term.html — custom taxonomy page
projects/list.html — project listing with status badges
projects/single.html — single project page
shortcodes/baseurl.html — outputs site base URL

Critical Rules

Never manually set lastmod — the pre-commit hook auto-updates it via scripts/update-lastmod.sh
Theme is vendored, NOT a submodule — edit themes/gokarna/ files directly
CSS lives in themes/gokarna/assets/css/ — main.css, dark.css, syntax.css. Hugo's asset pipeline handles minification and fingerprinting
Pre-commit hook runs on .md files: lastmod update, markdownlint, aspell spell check, link validation. See .githooks/pre-commit

Git Hooks & Scripts

Pre-commit hook auto-installed by scripts/install_hooks.sh (runs on nix shell entry). Scripts in scripts/:

update-lastmod.sh — updates lastmod front matter (RFC3339)
check-links.sh — curl-based dead link checker
install_hooks.sh — symlinks .githooks/* into .git/hooks/

2.9 KiB Raw Blame History