blog/AGENTS.md

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

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

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