Build and publish these docs¶
The site uses MkDocs Material. The GitLab Pages pipeline builds the site from this repository; no provider credentials are required to build the documentation.
Local preview¶
Install the documentation dependencies in an isolated Python environment if preferred:
python3 -m venv .venv-docs
. .venv-docs/bin/activate
python -m pip install -r requirements-docs.txt
mkdocs serve
Open the local URL printed by MkDocs (with the checked-in site_url, this is http://127.0.0.1:8000/identity-made-easy/). MkDocs watches the Markdown files and reloads the preview when they change.
Strict build¶
Run the same validation used in CI:
The generated public/ directory is a build artifact and should not be committed. The repository ignores it.
GitLab Pages publishing¶
The pages job in .gitlab-ci.yml runs on the default branch when documentation, capability contracts, the MkDocs configuration/dependencies, or the pipeline definition changes. It installs requirements-docs.txt, replaces site_url with the project URL supplied by GitLab as CI_PAGES_URL, and runs a strict build. The public/ artifact is then published by GitLab Pages.
GitLab can assign either a project-path URL or a per-project subdomain. The pipeline reads CI_PAGES_URL and overwrites MkDocs' site_url, so root-relative links follow GitLab's assigned URL. Find it under Deploy → Pages after the first successful Pages pipeline. Enable Pages for the project if GitLab requires that setting.
This checkout currently has no Git remote configured. To publish these changes, use the GitLab project at https://gitlab.com/Alphabalex/identity-made-easy, push the intended branch using your normal workflow, and merge the documentation changes into the default branch. No push or deployment is performed by this documentation task.