Website

1. How to develop the documentation page?

The documentation is build with hugo and Docsy as template.
There is a container for building or starting a hugo server for easy development of the documentation.

The Setups between Docker or Podman is a little bit different.

2. Where is the content?

The pages of the documentation are not copied into website/. hugo reads them directly from the repository:

Source Page

doc/.adoc, doc/guides/.adoc, doc/*.md

Guides, features and development

roles/*/README.md

One page per role (generated by ansible-doctor)

website/content/

Start page, About and the introduction of each section (_index.md)

website/hugo.yaml mounts doc/ and roles/ below assets/. The content adapter website/content/docs/_content.gotmpl creates the pages from them:

  • The first heading of a file is used as the page title, unless a title is set in $settings of the content adapter.

  • Relative links (AsciiDoc link: macro or Markdown link) are rewritten to the pages of the website. Links to files without a page point to GitHub.

  • The "Edit this page" link points to the source file below doc/ or roles/.

  • "Last modified" shows the last commit of the source file. scripts/gitinfo.py writes it to website/data/gitinfo.json before each build (hugo would show the commit of the content adapter instead).

  • A new file in doc/guides/ appears automatically. New files in other directories need a rule in $rules of the content adapter.

Important
 Do not use include:: in files below doc/. hugo passes the content to asciidoctor by stdin and GitHub does not render includes either. Use a link instead.

3. Tasks

website/Taskfile.yml contains the commands for building and testing the page. task is part of the nix-shell of ansible-oracle.

cd ansible-oracle/website
task                # list all tasks
task serve          # live server on http://localhost:1313
task build          # build the page into public/
task test           # build + check internal links
task test:a11y      # build + accessibility check (WCAG 2 AA) of all pages
task publish        # build + commit in the clone of the website repository
task publish:push   # build + commit + push => GitHub Pages publishes the website
task publish:pr     # build + commit + pull request in the website repository

The tasks can be started from the root of the repository with prefix website:, e.g. task website:test.

4. Publishing

The website is published with GitHub Pages from the directory docs/ in the branch main of Rendanic/ansible-oracle-website.

The publish tasks call tools/release/build_website.sh:

  • The sources in website/, doc/, roles/ and docker/hugo/ must be committed.

  • The legal notice must be published (no draft: true).

  • The website repository is cloned to ~/.cache/ansible-oracle-website with gh.

  • docs/ is replaced by the new build, CNAME is kept and .nojekyll is added (GitHub Pages ignores directories with a leading _ like _print/ without it).

Options of the script are passed after --, e.g. task publish — -a for an additional accessibility check or task publish — -f to ignore uncommitted changes and a missing legal notice (for tests only).

Podman is used with task build COMPOSE=podman-compose COMPOSE_USER=root.

The checks run in containers:

  • check:links uses lychee for all links in public/.

  • check:a11y uses pa11y-ci with the runners axe and HTML_CodeSniffer for all pages in sitemap.xml. The settings are in website/.pa11yci.json. The axe rule color-contrast is ignored: axe cannot determine the background below the fixed navbar and sidebar and reports hundreds of false positives. The contrast is still checked by HTML_CodeSniffer.

5. Colors and contrast

The whole site uses one polarity: dark text on a light background. Docsy’s dark navbar, cover blocks and footer are replaced in

  • website/layouts/partials/navbar.html (copy of Docsy with data-bs-theme="light")

  • website/assets/scss/_styles_project.scss (navbar, footer, buttons, links and Prism token colors)

All colors have a contrast ratio of at least 4.5:1 (WCAG 2 AA). Use blocks/lead or blocks/section with color="white" on new pages, not blocks/cover. Code blocks are highlighted by Prism (light theme), Chroma is disabled for Markdown code fences in hugo.yaml.

6. Updates of hugo and Docsy

File Version Updated by

docker/hugo/Dockerfile

hugo and asciidoctor (base image floryn90/hugo)

renovate

website/hugo.yaml

module.hugoVersion.min

manual

website/go.mod, website/go.sum

Docsy (github.com/google/docsy)

renovate (group docsy)

website/Taskfile.yml

lychee, puppeteer, pa11y-ci, http-server (# renovate: comments)

renovate

The image of the hugo container is tagged with the tag of the base image, e.g. rendanic/hugo:0.169.0-ext-ubuntu. A new version in the Dockerfile builds a new image automatically with the next task build.

renovate updates only website/go.mod and website/go.sum. go from shell.nix is needed for go.sum. The steps below are still manual, the Pull-Request of renovate (group docsy) lists them as a note. There is no github workflow which builds the website, so a Docsy Pull-Request is green even when the website is broken.

Steps for an update of Docsy:

  1. Read the release notes of Docsy (minimum version of hugo, breaking changes). Docsy 0.16 and later is a different Hugo module (github.com/docsy/docsy/theme) with Bootstrap and Font Awesome from npm. renovate.json allows only versions below 0.16.

  2. Update website/go.mod and website/go.sum. Run task clean:all afterwards: an old module in website/.cache/modules can remain as empty directories and is not downloaded again (error File to import not found or unknown output format).

  3. task docsy:diff shows the differences between the copied templates in website/layouts/ and the new Docsy version. Apply the changes of Docsy to the copies.

  4. Check website/assets/scss/_styles_project.scss: it uses the Docsy classes .td-navbar, .td-footer, .td-box and .td-content.

  5. task test:all and a look at the start page, a guide and a role page.

Note
 security.exec.osEnv in website/hugo.yaml passes GEM_HOME to asciidoctor. Without it, asciidoctor does not find its gem in the base image.
Note
 Since hugo 0.170, the SCSS of Docsy is compiled with Dart Sass (sass in the base image), libsass was removed. security.exec.allow in website/hugo.yaml must contain ^sass$. The deprecation warnings of Dart Sass come from Docsy and Bootstrap.

7. Container Setup

The setup of Docker or Podman is described in the Development Guide.

The Dockerfile and docker-compose.yaml of the hugo container are in docker/hugo/. The image is built automatically on the first task build or with task hugo:build in docker/.

8. hugo with Docker

8.1. hugo live server

Important
 This only works when current uid in shell is same as ubuntu(1000) inside the container. 
cd ansible-oracle/docker/hugo
docker compose run --rm -u ubuntu site -s /src/website server

8.2. Building the public page

Important
 This only works when current uid in shell is same as ubuntu(1000) inside the container. 
cd ansible-oracle/docker/hugo
docker compose run --rm -u ubuntu site -s /src/website

9. hugo with Podman

9.1. hugo live server

The default user inside the container is hugo with a different uid then the nonroot user of the podman Container.
This results in a permission denied when the uid of nonroot podman user is different then the uid of hugo inside the container while reading volume data. Starting with --user=root starts all processes in the same namespace as the nonroot user which allows access to the volume data.

Start hugo server with Podman
cd ansible-oracle/docker/hugo
~/venv/podman/bin/podman-compose run --rm --user=root site -s /src/website server --bind 0.0.0.0

9.2. Building the public page

cd ansible-oracle/docker/hugo
~/venv/podman/bin/podman-compose run --rm --user=root site -s /src/website
Last modified November 14, 2026: website: build with hugo 0.170 (Dart Sass) (7b26f0b2)