Thanwer
9c549acc0a
All checks were successful
Deploy / deploy (push) Successful in 6s
- Deploy section now describes the Gitea Actions workflow rather than the legacy rsync-from-laptop flow. - Fix backwards claim about modern vs deprecated Hugo language keys: locale/label are the deprecated custom params; languageCode/languageName are the canonical ones. - Add a cheat sheet for the Hugo 0.123+ template fields that were removed (site.Locale, .Language.Label, plus the theme's invalid hugo.Data reference) and document each layouts/ override we now ship. - cspell: allow baseof, hreflang, gitea/Gitea. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
89 lines
4.8 KiB
Markdown
89 lines
4.8 KiB
Markdown
# 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
|