Skip to content

zensical-pages

Builds a Zensical microsite and deploys it to GitLab Pages. This very site is built by this component — see its self-include in this repo's root .gitlab-ci.yml.

Two jobs:

  • zensical-build — pip-installs Zensical from the consumer's python_lock file at job runtime, builds the site, and moves the produced site/ to $CI_PROJECT_DIR/public (Zensical's CLI has no --site-dir flag and reads zensical.toml from the working directory). Runs everywhere via an explicit when: on_success rule — a rule-less job is skipped on merge-request pipelines.
  • pages — consumes the build artifact, deploys on deploy_branch only.

Change-detected by default — both jobs run only when a matching file changes, so a code-only MR doesn't rebuild the docs site. Build and deploy share the same changes filter, so they skip or run together (a deploy never runs without its build artifact).

Jobs

Job What it runs
zensical-build pip install -r $[[ inputs.python_lock ]], zensical build --clean, moves site/ → public/.
pages Publishes the public/ artifact via GitLab Pages (pages: true).

Inputs

Input Type Default Description
image_version string "v0.3.0" infra-tools image tag (provides python3 + pip + venv).
stage string pages GitLab CI stage for both jobs.
working_directory string "." Directory the build runs from. Must contain zensical.toml and the python lockfile.
docs_path string "docs" Path to the Zensical docs source, relative to working_directory. Echoed in logs; Zensical reads zensical.toml for the canonical path.
deploy_branch string "main" Branch whose pipelines deploy Pages. Other branches still build, for visibility.
python_lock string "requirements-lock.txt" Path to the consumer's pip-compile-style lockfile.
changes array ["docs/**/*", "zensical.toml", "requirements-lock.txt", ".gitlab-ci.yml"] Change-detection paths shared by both jobs. Set ["**/*"] to always run.

Usage

include:
  - component: gitlab.com/phpboyscout/cicd/[email protected]

See also