Guidance for AI coding agents working in this repository.
- Public website for Wdes SAS (https://wdes.fr).
- Static site built with Hugo extended (currently
0.169.0, pinned inMakefile). - Single-binary build, no Node/npm. SCSS is compiled by Hugo (
css.Sass). - Deployed to GitHub Pages on the
gh-pagesbranch via the workflow at.github/workflows/publish.ymlwhenevermainis updated.
.
├── Makefile # docker-based wrappers around Hugo
├── .github/workflows/ # publish workflow (gh-pages)
└── wdes.fr/ # the Hugo site (root for Hugo commands)
├── config.toml
├── archetypes/
├── assets/ # SCSS, JS, vendor SCSS bundled & fingerprinted by Hugo
├── content/ # _index.md (home), legal.{fr,en}.md, app-privacy-policy.fr.md
├── i18n/ # fr.toml, en.toml — all UI strings live here
├── layouts/_default/ # index.html (home), legal.html, app-privacy-policy.html
├── static/ # served as-is (favicon, robots.txt, /static/assets/{img,logo})
└── public/ # build output (gitignored)
defaultContentLanguage = "fr",defaultContentLanguageInSubdir = true.- Both languages live under
/fr/and/en/. - Root
/is served as a meta-refresh redirect to/fr/(Hugo-generated alias). - Languages are configured with
locale(en/fr) andlabel(English/Français); the oldlanguageCode/languageNamekeys are deprecated. - Translations:
*.fr.md/*.en.mdcontent files;_index.md(no language code) is shared by both languages. - All user-visible strings come from
i18n/{en,fr}.tomlvia{{ i18n "key" }}. When you add a string, add it to both files.
- The site uses pretty URLs (
/fr/,/fr/legal/, …). Do not re-enableuglyURLs = trueinconfig.toml— see "Known traps" below. - Internal links must be language-aware. Use
relLangURLinstead of hardcoded paths:Avoid<a href="{{ "/" | relLangURL }}">…</a> <a href="{{ "/legal/" | relLangURL }}">…</a>
{{ .Site.BaseURL }}{{ .Site.Language.Lang }}/legal.html— it hardcodes both language and the.htmlsuffix.
uglyURLs = true+defaultContentLanguageInSubdir = truecauses an infinite redirect loop on the FR home page. Hugo generates two aliases for the default-language home, and the second one is written to the same path as the rendered page (/fr/index.html), overwriting the real content with a meta-refresh that points back to itself. Keep pretty URLs.disableKindsmust not containtaxonomyTerm(usetaxonomy); the legacy spelling is deprecated since Hugo 0.150 and was removed from the config.content/**files must be.md, not.html. Since Hugo 0.169,text/htmlcontent is rejected bysecurity.allowContentand the build fails withaccess denied: "text/html" is not whitelisted.css.Sasslogs a libsass is deprecated warning (Hugo ≥ 0.153). Harmless for now; switching todart-sassneeds the Dart Sass binary in the build image plus a CSS-output review (Bootstrap 5.0 SCSS renders differently).
Always use make — never call docker run directly. The Hugo version is
pinned in the Makefile and all volume mounts / port bindings are configured
there. Running Docker by hand risks using the wrong image, wrong working
directory, or wrong flags.
make serve # hugo serve on http://localhost:8111 (binds 0.0.0.0)
make build # writes wdes.fr/public/
make version # print Hugo version
make fix-perms # chmod public/ after a containerized build (777/666)make serve and make build share the same Docker container name (wdes.fr).
You cannot run both at the same time. When make serve is running, do NOT stop
it to run make build — the dev server watches files and rebuilds automatically
on every change. Only use make build when no dev server is running (e.g. in CI
or for a final check).
The CI workflow runs make build, then copies wdes.fr/public/* onto the
gh-pages branch with a CNAME (wdes.fr) and .nojekyll. Pushes to
gh-pages are signed (GPG key from secrets).
layouts/_default/index.htmlis the home page. It embeds Bootstrap, AOS, Material Design Icons and font-mfizz, all compiled fromassets/vendor/**viacss.Sass | minify | fingerprint "sha512"and emitted with SRI hashes.- The
<!--sse-->…<!--/sse-->fences mark blocks that are stripped from search-engine indexing by some crawlers. Keep contact info and personal data inside them. - Matomo analytics tag is hardcoded in the home template (
analytics.wdes.eu,siteId=2).
- Add a page:
content/<slug>.<lang>.mdwith front matter:Then add--- layout: <layout-name> ---
layouts/_default/<layout-name>.html. - Home page front matter is in
content/_index.md(layout: index). - New translation strings → both
i18n/en.tomlandi18n/fr.toml.
- Don't commit
wdes.fr/public/(gitignored). Thegh-pagesbranch is managed by CI; never push to it manually. - Never run
docker rundirectly — always usemake build,make serve, etc. The Makefile pins the correct Hugo image, volume mounts, and flags. Running Docker by hand risks version mismatches and wrong build output. - Don't use
--no-verifyor skip the GPG signing ongh-pages(CI does it with secrets; local devs should not push there). - Don't reintroduce
uglyURLs = true(see "Known traps").