# AGENTS.md — Thanwer's Blog

## Project

Hugo blog (multilingual EN + PT-BR) using the **anubis2** theme as a git submodule (`themes/anubis2`, v1.6.0).

## Repository

- Primary: `ssh://git@git.thanwer.com:2222/thanwer/blog.git` (self-hosted Gitea)
- GitHub mirror is being retired; if you still see `origin` pointing at GitHub it's intentionally kept for transition.

## Deploy

Pushes to `main` trigger `.gitea/workflows/deploy.yml` on the shinobi gitea-runner: it builds Hugo and writes directly into the host's `/srv/www/blog` via a bind-mounted volume — Caddy on the same host serves from there. No SSH/rsync round-trip.

`deploy.sh` (legacy rsync-from-laptop) is kept as a manual fallback only.

## Commands

```bash
hugo server                # dev server at localhost:1313
hugo                       # build to ./public/ (no minify)
git push                   # → triggers Gitea Actions deploy
pre-commit run --all-files # quality check (lint, spell, links)
./deploy.sh                # fallback: pre-commit → hugo --minify → rsync from laptop
```

## Quality toolchain

- **pre-commit** — runs on `./deploy.sh` or manually via `pre-commit run --all-files`. Includes: YAML/TOML/JSON check, EOF fixer, trailing whitespace, large file check, markdownlint, cspell (EN + PT-BR), lychee (link checker).
- **markdownlint** — config: `.markdownlintrc`. MD013 (line-length) disabled.
- **cspell** — config: `.cspell.config.yaml`. Adds `@cspell/dict-pt-br` via `additional_dependencies`. Custom word list for technical terms.
- **lychee** — config: `.lychee.toml`. Run locally with `--root-dir static` to resolve `/images/...` links. Excludes social media domains and `sshaudit.com`.

All quality tooling must pass before deploy. No separate test framework.

## Content conventions

- **Posts**: `content/posts/<slug>.md` (EN), `content/posts/<slug>.pt.md` (PT-BR)
- **Images**: `static/images/<filename>` — referenced as `/images/<filename>` in markdown
- **PT translations** set `canonical = "/posts/<en-slug>"` in frontmatter
- **`lastmod`** must use bare TOML datetime (no quotes): `lastmod = 2026-05-09T00:00:00Z`.
- **Archetype**: `hugo new posts/<slug>.md` → `archetypes/default.md`
- **Tags** only (no categories): `tags = ["GNU/Linux", "Tools"]`

## Configuration quirks

- Theme requires **all lowercase keys** under `params.anubis2`: `colortheme`, `enablecolorthemeswitcher`, `readnextposts`, `socialicons`, etc. See `themes/anubis2/PARAMS.md`.
- `[params.anubis2.services.umami]` keys are lowercase: `id`, `url`.
- Analytics inject only in production (`hugo.IsProduction`). Test locally: `hugo server --environment production`.
- Per-language `locale` and `label` are **deprecated custom params** at the language top level (deprecated in Hugo 0.112, will be removed). Modern canonical keys are `languageCode` and `languageName`. Current `hugo.toml` still uses the old form for historical reasons — Hugo emits a warning at build time but still honours them. Migrate at some point.
- `enableGitInfo = true` — `.Lastmod` derives from git; template prefers `.Params.lastmod` when set. The Gitea deploy workflow uses `fetch-depth: 0` so the runner has the full history.

## Frontmatter reference

```toml
date = 2024-10-26T16:59:23-03:00
lastmod = 2026-05-09T00:00:00Z
title = 'Post Title'
description = "One-line summary for SEO and RSS"
tags = ["tag1", "tag2"]
canonical = "/posts/original-post"   # PT translations only
```

## Hugo template fields — what works in 0.151+

These template fields were **removed** in Hugo 0.123 / 0.124 and broke on the first CI run after migration. Use the replacements:

| Removed | Use instead |
| --- | --- |
| `site.Locale`, `site.Language.Locale` | `site.LanguageCode` |
| `.Language.Label` (display name) | `.Language.LanguageName` |
| `.Language.Label` (in `hreflang`) | `.Language.LanguageCode` |
| `hugo.Data.*` (theme data files) | `site.Data.*` |

`hugo.<field>` is for build info only (`hugo.Version`, `hugo.IsProduction`, `hugo.CommitHash`); it never had a `.Data` namespace — the theme had a bug.

## Theme overrides (`layouts/` shadows theme)

- `layouts/_default/baseof.html` — patched to use `site.LanguageCode` instead of removed `site.Language.Locale`
- `layouts/_default/sitemap.xml` — `hreflang` uses `.Language.LanguageCode`
- `layouts/_default/rss.xml` — `<language>` uses `.Site.LanguageCode`
- `layouts/partials/head.html` — canonical from `Params.canonical`, Umami analytics (prod only)
- `layouts/partials/head/social-icons.html` — fixes theme bug: `hugo.Data` → `site.Data`
- `layouts/partials/language-switcher.html` — `.Language.LanguageName` for display
- `layouts/partials/post-info.html` — prefers `.Params.lastmod`, shows "[Last modified]" when different from date
- `layouts/partials/footer-extra.html` — Ko-fi widget
- `layouts/robots.txt` — custom sitemap for both languages