More comments in Gitlab-CI config

.gitlab-ci.yml

 # From template at https://gitlab.com/pages/hugo
 
+# Runner configuration
 default:
+  # The `hugo_extended` image is required because our theme needs SCSS compilation
+  # (see https://gohugo.io/installation/linux/#editions)
+  # The image is pinned to an explicit version number to avoid bugs introduced
+  # by an automatic upgrade
   image: "${CI_TEMPLATE_REGISTRY_HOST}/pages/hugo/hugo_extended:0.128.1"
 
 variables:
   GIT_SUBMODULE_STRATEGY: recursive  # include Hugo themes
-  GIT_SUBMODULE_FORCE_HTTPS: true
+  GIT_SUBMODULE_FORCE_HTTPS: true  # the GitLab runner doesn't have SSH to clone
   HUGO_ENV: production
 
+# Jobs configuration
+# In this project, the Hugo directory (with `hugo.toml`, `content/` etc...) is
+# not the Git root dir, but a subfolder `macao`. This requires a bit of extra
+# config for some jobs.
+
 test:
+  # The `test` job just tries to build the site, runs on all branches except
+  # the default
   script:
-    - cd macao
+    - cd macao  # move to the hugo dir
     - hugo
   rules:
     - if: $CI_COMMIT_BRANCH != $CI_DEFAULT_BRANCH
 
 pages:
+  # The `pages` job builds the site to the `public` dir for Pages to publish,
+  # runs only on the default branch
   script:
     - cd macao
     - hugo
+  # Declare an artifact, the job's output
   artifacts:
     paths:
       - macao/public
+  # Config for Pages: directory to serve (default is 'public')
   publish: macao/public
   rules:
     - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH