66 lines
2.9 KiB
Markdown
66 lines
2.9 KiB
Markdown
# 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/`
|