Publish the documentation¶

This repository converts Markdown into a bilingual static site and publishes it with GitLab Pages. The documentation pipeline is independent of the pipelines that build the application and infrastructure: it needs no AWS credentials, Google Cloud credentials or Terraform state.

The ZIP contains source files and automation. An actual deployment starts after those files are pushed to a GitLab project with an available runner and Pages enabled; preparing the ZIP does not create that project or a public URL.

Generated output¶

Published path	Contents
`/`	Landing page with an explicit language choice
`/es/`	Spanish documentation and search
`/en/`	English documentation and search
`/es/search/search_index.json`	Spanish search index
`/en/search/search_index.json`	English search index
`/sitemap.xml`	Index of both language sitemaps
`/build-info.json`	Generator versions and documentation commit

These paths are relative to the Pages site root. If GitLab hosts the project under /group/project/, the language sites live at /group/project/es/ and /group/project/en/. The build does not assume that the site occupies the root of a domain.

The language selector preserves the current page path. For example, it switches from es/infrastructure/aws/ to en/infrastructure/aws/. File names match across the two languages; page titles and contents are translated.

Preview locally¶

Requirements: Python 3.12, access to PyPI for the initial installation, and a browser. Run commands from the directory containing mkdocs.yml and .gitlab-ci.yml.

python3 -m venv .venv
.venv/bin/python -m pip install --requirement requirements.txt
.venv/bin/python -m pip check
.venv/bin/python scripts/build_docs.py --serve

Open http://127.0.0.1:8000/. The server includes both translations and the landing page. To see changes, stop it with Ctrl+C and run the last command again: this preview does not provide automatic reload.

In PowerShell, use the Windows virtual environment executable:

py -3.12 -m venv .venv
.\.venv\Scripts\python.exe -m pip install --requirement requirements.txt
.\.venv\Scripts\python.exe scripts\build_docs.py --serve

With GNU Make, the equivalent is:

make install
make serve

To build without starting a server:

.venv/bin/python scripts/build_docs.py

Output is written to public/. .build/ contains temporary copies of language sources and shared assets. Both directories are regenerated and excluded from Git. python scripts/build_docs.py --clean removes only those two directories.

Create the documentation project¶

Create an empty project in the chosen GitLab group. A name such as documentation or cloud-delivery-lab-docs is sufficient. Do not initialize it with a README if you intend to use the bootstrap commands below.
Extract the ZIP and enter the repository directory. .gitlab-ci.yml, .gitignore and .editorconfig belong at its root; do not upload the ZIP as a single file or place the whole repository inside an extra subdirectory.
Confirm that CI/CD and GitLab Pages are available, and that a runner can use python:3.12-slim and download packages from PyPI. Account quotas or policies may affect execution.
Copy the SSH or HTTPS URL of the new documentation project from GitLab.
Initialize and push the sources. Replace the value of DOCS_REMOTE_URL in the example with that URL.

DOCS_REMOTE_URL='PASTE_THE_NEW_PROJECT_URL_HERE'
git init --initial-branch=main
git add .
git commit -m "docs: add bilingual Cloud Delivery Lab documentation"
git remote add origin "$DOCS_REMOTE_URL"
git push --set-upstream origin main

The initial branch can have a different name. The pipeline uses CI_DEFAULT_BRANCH, so it publishes from the default branch configured for the project rather than depending on the name main.

If the project already has content, clone it, create a branch and review a merge request. Integrate existing configuration before adding these files, especially .gitlab-ci.yml; no force push is needed.

Pipeline behavior¶

The configuration uses current GitLab Pages syntax: the deploy-pages job declares pages.publish: public. It targets GitLab.com or GitLab 17.10 and later; older installations require checking syntax and artifact-management differences. Official Pages CI/CD reference.

Event	Validation	Publication
Push to a branch without an open merge request	Yes	Only if it is the default branch
Merge request	Yes	No
Push to a working branch with an open merge request	The merge request pipeline is used to avoid duplicate pipelines	No, except for the applicable default-branch pipeline
Change merged into the default branch	Yes	Automatic, after validation
Tag	No pipeline is created by the included rules	No

validate-docs installs the versions in requirements.txt and runs scripts/build_docs.py. The script:

Checks that every page has a counterpart in both languages and that navigation is complete.
Copies each language source and shared assets into .build/.
Runs strict MkDocs builds for Spanish and English.
Generates the landing page, sitemaps and build manifest.
Checks internal links, anchors, static assets, HTML language and search indices in the generated site.

Any failed check fails the job and prevents publication. The HTML is retained as the public/ artifact for one week so it can be reviewed.

deploy-pages downloads the exact artifact produced by the preceding job, checks its structure and publishes it. The documentation-pages resource serializes this job. It does not rebuild the pages, run Terraform or deploy the demonstration application.

Serialization prevents concurrent publication jobs, but alone does not guarantee that a slow older pipeline cannot publish after a newer one. In project CI/CD settings, review Prevent outdated deployment jobs to protect the documentation environment from stale jobs. This is a GitLab setting; it requires neither another job nor a manual approval. Deployment ordering.

External links to sources, providers or repositories are not fetched by the validator: validation is local and does not depend on the momentary availability of other services.

Site URL and group renames¶

The script selects the canonical URL in this order:

Priority	Value	Purpose
1	`--site-url`	Explicit command-line test
2	`DOCS_SITE_URL`	Custom domain or deliberate override
3	`CI_PAGES_URL`	Pages URL supplied by GitLab to the job
4	`http://127.0.0.1:8000/`	Default local preview

In GitLab CI, if --site-url, DOCS_SITE_URL and CI_PAGES_URL are all missing, the build fails with an explicit message. The localhost URL is a default only for local execution.

CI_PAGES_URL is read inside the job script, because GitLab makes it available when jobs run. It supplies the applicable Pages destination; the build does not construct a URL by concatenating the group and project names. Predefined variables reference.

To check a URL containing a subpath:

.venv/bin/python scripts/build_docs.py \
  --site-url https://example.gitlab.io/group/documentation/

This validates links and paths; it publishes nothing at that example domain.

For a custom domain configured in GitLab Pages, add the non-sensitive CI/CD variable DOCS_SITE_URL, for example https://docs.example.org/. This variable changes canonical URLs and language links, but does not create the domain, DNS records or TLS certificate. Configure those through Pages settings. Pages custom domains.

Documentation repository links are derived from CI_PROJECT_URL; editing links use CI_DEFAULT_BRANCH. Locally, DOCS_REPO_URL can supply the repository URL. When the new repository URL is unknown, those links are omitted instead of pointing to an invented destination.

After renaming the group or project, rerun the pipeline and check Deploy > Pages. Also update references in application and infrastructure repositories, and source links whose namespace changed. Dynamic site configuration does not modify those other projects.

Verify the first deployment¶

After the pipeline completes:

Open Deploy > Pages and use the URL GitLab shows there; it may be a unique domain.
Check the landing page and both language choices.
Open an inner page, change language and confirm that the topic is preserved.
Try search in both languages and open a result.
Check diagrams and code blocks, including on a narrow screen.
Inspect build-info.json to connect the deployed site with its commit and generator versions.

Site visibility depends on the project's Pages configuration and policies. A downloadable HTML artifact is not evidence that the site has been deployed.

Troubleshoot the documentation site¶

Symptom	Check and action
No pipeline appears	Confirm that `.gitlab-ci.yml` is at the repository root, CI/CD is enabled and the change was pushed to an allowed branch.
Job remains pending	Check runner availability, tags and permissions; this configuration requires no runner tags.
Dependency installation fails	Use Python 3.12 and check PyPI access. Keep the locked dependency set together.
Translation is missing	Add the matching file under `docs/es/` and `docs/en/`, and include both in their navigation.
MkDocs reports a broken link	Correct the reported relative `.md` path or anchor. Do not lower validation severity to hide the issue.
A working branch does not publish	This is expected. Publication runs on the default branch after successful validation.
Pages returns 404	Check the Pages job, the URL under `Deploy > Pages` and the presence of `public/index.html` in the artifact.
Language switching loses a subpath	Review `DOCS_SITE_URL` and `CI_PAGES_URL`. The URL must include the complete site root and its subpath.
A custom domain links to a different domain	Set `DOCS_SITE_URL` to the canonical URL and rebuild.
The build passes but an external source will not open	Check that link and its permissions separately; the offline validator neither authenticates nor verifies external sources.

Files that maintain this service¶

File	Responsibility
`mkdocs.yml`	Shared theme, extensions and validation
`mkdocs.es.yml`, `mkdocs.en.yml`	Language-specific navigation and search
`scripts/build_docs.py`	Both builds, landing page, URLs and shared assets
`scripts/check_docs.py`	Translation and navigation parity
`scripts/check_site.py`	Generated HTML links, anchors and assets
`.gitlab-ci.yml`	Validation and Pages publication
`requirements.in`, `requirements.txt`	Direct dependencies and tested version set
`theme/`	Styling and template adaptations
`third_party/`	Licenses and the bundled Mermaid version

For content changes, see Maintain and translate. To distinguish project evidence from choices made for this documentation, see Sources and review.