nueroplastic til post

2026-02-24 00:37:11 -07:00
parent a47a28e074
commit 60c4ab4137
14 changed files with 293 additions and 136 deletions
@@ -0,0 +1,65 @@
+# 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
+
+```sh
+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
+
+1. **Never manually set `lastmod`** — the pre-commit hook auto-updates it via `scripts/update-lastmod.sh`
+2. **Theme is vendored, NOT a submodule** — edit `themes/gokarna/` files directly
+3. **CSS lives in `themes/gokarna/assets/css/`** — `main.css`, `dark.css`, `syntax.css`. Hugo's asset pipeline handles minification and fingerprinting
+4. **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/`