Skip to content

Exporting a GitLab Pages documentation snapshot

The GitLab Pages site is a disposable presentation of AndreaWeb's versioned Markdown. It is not part of the production website and does not change the OVH VPS, Nginx, DNS, certificates, application containers, or public-site SEO.

Source-to-export mapping

The export deliberately flattens the documentation for a small standalone GitLab repository:

AndreaWeb source ZIP/GitLab destination
docs/README.md README.md
roadmap.md roadmap.md
docs/*.md, except README.md root *.md files
docs/decisions/ decisions/
deploy/gitlab-pages/.gitlab-ci.yml .gitlab-ci.yml
deploy/gitlab-pages/mkdocs.yml mkdocs.yml
deploy/gitlab-pages/javascripts/ javascripts/

The script rewrites only the relative links affected by flattening, then verifies that every local Markdown target in the export exists. Source documents are never modified.

Create the ZIP

From the authoritative WSL checkout:

cd /home/justin/repos/AndreaWeb
./scripts/export-gitlab-docs.sh

The default result is timestamped under the ignored artifacts/ directory:

artifacts/andreaweb-docs-gitlab-pages-YYYYMMDD-HHMMSS.zip

An optional relative or absolute output path may be supplied:

./scripts/export-gitlab-docs.sh andreaweb-docs-gitlab-pages-manual.zip

Root ZIPs matching andreaweb-docs-gitlab-pages-*.zip are also ignored. The script requires python3 and zip, creates its staging tree under the system temporary directory, validates the snapshot, and removes staging files automatically.

Publish the snapshot

  1. Create or open the separate GitLab documentation project.
  2. Extract the ZIP so its README.md, .gitlab-ci.yml, and mkdocs.yml are at the repository root—not inside an extra enclosing folder.
  3. Upload/commit the extracted files using GitLab's Web IDE or normal Git tooling.
  4. Push or commit to the GitLab project's default branch.
  5. Wait for the pages pipeline and open Deploy → Pages for the generated URL.

The Pages project may be public. It should contain only the exported files, never the AndreaWeb application source, private environment files, credentials, Admin invite tokens, customer data, or production logs.

Export layout

.gitlab-ci.yml
mkdocs.yml
README.md
roadmap.md
architecture.md
seo.md
...other documentation Markdown...
decisions/
  0001-mvp-foundation.md
  0002-product-media-storage.md
javascripts/
  mathjax.js

Material for MkDocs supplies automatic navigation, English/Spanish search, a light/dark architectural palette, and Mermaid rendering. MathJax remains configured for future formulas even though the current documents do not require it.