Skip to content
calaosPublic

About

Calaos website repo

Resources

Stars

2 stars

Watchers

7 watching

Forks

Repository files navigation

Calaos website

Source of calaos.fr, built with Hugo extended 0.154.5 and a custom template. No theme, no Node.

Preview

With the dev container: open the repository in VS Code, reopen it in the container, then run

hugo server --bind 0.0.0.0

and open http://localhost:1313/fr/. Port 1313 is forwarded.

With Docker only:

docker run --rm -it -u "$(id -u):$(id -g)" -e HOME=/tmp -v "$PWD:/src" -w /src -p 1313:1313 \
  --entrypoint hugo hugomods/hugo:exts-0.154.5 server --bind 0.0.0.0

The Umami statistics script only loads in a production build, so previews are not counted.

Edit the content

Everything a visitor can read is outside the template. Edit one file and rebuild, no HTML involved.

To change Edit
A sentence, a card, a step, a list, an image of the home page content/_index.fr.md (English: content/_index.en.md)
The menu and the footer links config/_default/menus.fr.toml, menus.en.toml
Short interface labels (skip link, buttons, footer titles) i18n/fr.yaml, i18n/en.yaml
PayPal link and Bitcoin address data/donate.yaml
Contact address, Umami script and id, giscus comments config/_default/params.toml
News articles content/news/ (see News below)

In the content file, **text** highlights a part of a heading. Each section is a block in the front matter, in page order. Every block except hero and kiosk has an id: (required, the build fails without it): it is the anchor targeted by the menu, the hero button and skip_to, so changing it means updating those, and it is not translated lightly since links to the page depend on it. Blocks of a list (rows, tabs, cards, items…) can be added, removed or reordered freely.

Images go in static/media/ and are referenced as media/name.jpg, with their size and, when they carry meaning, an alt text.

Each language has its own content/_index.<lang>.md, i18n/<lang>.yaml and config/_default/menus.<lang>.toml.

The template is in layouts/: baseof.html for the shell shared by every page, _partials/ for the header, footer and home sections. A new section only needs content/<section>/ and its layouts, which fill the main block with a <main id="content">; it gets an RSS feed automatically.

News

Articles are in content/news/, one folder per article with index.fr.md and index.en.md (same folder = translations of each other). Start one with hugo new content news/2026-12-my-topic/index.fr.md: set title, slug (the URL, /fr/actualites/<slug>/, /en/news/<slug>/), summary (list and RSS), description (meta description and link previews, 120 to 160 characters, not a copy of the summary), then remove draft: true to publish. The list shows the newest first, 10 per page, and has its RSS feed.

Comments use giscus (GitHub Discussions) and stay off while any value of [giscus] in config/_default/params.toml is empty. To turn them on: enable Discussions on the GitHub repository, install the giscus app on it, choose an announcement-type category on giscus.app, and copy repo, repoId, category and categoryId from the snippet it shows. Each article is its own discussion (fr/<folder>, en/<folder>), so do not rename an article folder once it has comments. Nothing from giscus or GitHub loads before the visitor clicks « Afficher les commentaires », except on the way back from GitHub sign-in: the address then carries ?giscus=<session>, and comments load at once so that giscus takes the token out of it (Umami is set to leave the query string out). That return path only applies in a tab where the button was clicked (comments-ok flag in sessionStorage, cleared by that return, so a second sign-in return needs a new click); a ?giscus= link alone shows the button as usual. Once signed in, giscus keeps giscus-session in the localStorage of calaos.fr. If the server sends a Content-Security-Policy, it must allow https://giscus.app in script-src and frame-src.

Search engines and link previews

Hugo generates, with no extra step:

  • sitemap.xml (index) and /fr/sitemap.xml, /en/sitemap.xml, with the hreflang alternates of every page, the legal pages and the news included.
  • robots.txt: everything allowed, and a Sitemap: line with the absolute production URL built from baseURL.
  • Open Graph and Twitter Card tags, og:locale and its alternate, and JSON-LD (Organization, WebSite and SoftwareApplication on the home page, BlogPosting on articles; the organization is the author, no person is named).
  • static/media/logo.png: 512×512 transparent 32-bit PNG (the touch icon cut out of the Calaos logo, reflection removed), used as the logo of the JSON-LD Organization and as the page icon.
  • static/apple-touch-icon.png: 180×180, opaque #171717 background, logo centered at about 80 % (iOS fills transparency with black and applies its own rounded mask, so the square is full-bleed). Made with magick static/media/logo.png -resize 144x144 -background '#171717' -gravity center -extent 180x180 -alpha remove -alpha off static/apple-touch-icon.png. static/favicon.ico is committed, made from the same file with ImageMagick (magick static/media/logo.png -define icon:auto-resize=48,32,16 static/favicon.ico): Hugo cannot write ICO.

The social image of an article is its image front matter, a path under static/media/ (image: media/my-photo.jpg), cropped by Hugo to 1200×630; without it every page uses the hero photo. A wrong path fails the build.

Submitting https://calaos.fr/sitemap.xml in Google Search Console is a manual step.

404 page and nginx

Hugo writes /fr/404.html and /en/404.html (noindex, links to both home pages). The server must serve them with the 404 status. Nginx server block for calaos.fr, as it runs in production (not part of this repository):

server {
        listen 80 default_server;
        listen [::]:80 default_server;
        root /var/www/static;
        index index.html;
        server_name calaos.fr;
        absolute_redirect off;
        error_page 404 /en/404.html;
        location = / {
                add_header Vary Accept-Language;
                return 302 $calaos_lang;
        }
        location ~* "\.[0-9a-f]{32,}\.(css|js)$" {
                add_header Cache-Control "public, max-age=31536000, immutable";
                try_files $uri =404;
        }
        location /fr/ {
                error_page 404 /fr/404.html;
                try_files $uri $uri/ =404;
        }
        location / {
                try_files $uri $uri/ =404;
        }
}

The map that sets $calaos_lang from Accept-Language is defined at the http level, outside this block. An add_header inside a location replaces every header inherited from the server level; repeat there any header that must also apply.

Missing URLs get the English 404 page, except under /fr/ which gets the French one. Fingerprinted CSS and JS (/css/*.min.<hash>.css, /js/*.min.<hash>.js) never change under the same name, so they are cached for a year.

Reverse proxy (haproxy) in front of nginx:

  • TLS is terminated by the proxy, hence nginx listens on port 80 only.
  • The proxy rewrites the Host header to calaos.fr, so the 301 from www to the apex must be done in the proxy; a server_name www.calaos.fr block in nginx would never match. Only the apex is indexed. Example: http-request redirect prefix https://calaos.fr code 301 if { hdr(host) -i www.calaos.fr }.
  • A Cache-Control set globally by the proxy overwrites the one from nginx, which defeats the one-year cache above. Set it only when the backend sends none, for example: http-response set-header Cache-Control "no-store, no-cache, must-revalidate" unless { res.hdr(Cache-Control) -m found }.

Build

hugo --minify

The site is written to public/, which is not committed. CSS and JS come from assets/ and are minified and fingerprinted at build time. Fonts and images are served as is from static/.

Every push and pull request to master runs this same build (.github/workflows/build.yml). It does not deploy.

Deploy

Deployment is manual only. Run the Deploy workflow (.github/workflows/deploy.yml) from the Actions tab, on master: the job is skipped on any other ref. That check only prevents a mistake; the boundary is the branch rule of the deploy environment (Settings, Environments, Deployment branches: master only, admin bypass off). It builds the site with hugo --minify, packs public/ into a tar.zst archive and POSTs it (multipart, fields key and file) to the URL set in DEPLOY_URL at the top of the file. Nothing deploys on push or pull request.

The upload key is the secret WWW_UPLOAD_KEY of the deploy environment, which the job references. Any answer other than 2xx (redirects included, none is followed) fails the job; the answer body is not printed.

About

Calaos website repo

Resources

Stars

2 stars

Watchers

7 watching

Forks

Releases

Packages

Contributors

Languages