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 — runs the zensical CLI (pre-installed in the docs-tools image via pipx — no runtime install, no per-repo lockfile), 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 zensical build --clean (CLI baked into the image), moves site/ → public/.
pages Publishes the public/ artifact via GitLab Pages (pages: true).

Inputs

Input Type Default Description
image_version string "v0.1.0" docs-tools image tag (provides the baked zensical toolchain).
stage string pages GitLab CI stage for both jobs.
working_directory string "." Directory the build runs from. Must contain zensical.toml.
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.
changes array ["docs/**/*", "zensical.toml", ".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