Exporting a GitLab Pages documentation snapshot¶

The documentation site at https://docs.andreazambrano.co/ is a disposable presentation of AndreaWeb's versioned Markdown. It is an independently hosted production property, not part of the portfolio/storefront runtime. Publishing a new snapshot does not change the OVH VPS, its Nginx, application containers, or VPS certificate.

Its GitLab project is AndreaWeb Docs, with default branch main. The project is private; Pages is publicly readable. Updating main runs the Pages pipeline and publishes the exported snapshot. Repository access alone is not authorization to publish a new snapshot.

The docs CNAME sends visitors directly to GitLab Pages, which serves the static Material for MkDocs output and manages a separate Let's Encrypt certificate for the custom hostname. The canonical site_url is stored in the exported mkdocs.yml. Relative Markdown links remain relative after the export's deliberate path rewrite and therefore continue to work on the custom domain.

Publishing architecture¶

flowchart LR
    Source[AndreaWeb repository<br/>docs, roadmap, Pages templates]
    Export[export-gitlab-docs.sh<br/>flatten and validate links]
    Zip[Versioned snapshot ZIP]
    DocsRepo[(Separate GitLab Docs project)]
    CI[GitLab CI]
    MkDocs[Material for MkDocs build<br/>navigation, search, Mermaid]
    Pages[GitLab Pages<br/>static hosting and TLS]
    Domain[docs.andreazambrano.co]

    Source --> Export --> Zip
    Zip -->|extract, review, commit| DocsRepo
    DocsRepo --> CI --> MkDocs --> Pages --> Domain

AndreaWeb remains the authoritative source for these documents. The separate Docs project and its Pages artifact are derived copies. The Journal is not included in this ZIP; its Astro source and editorial content live in its own GitLab project.

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/`
`docs/assets/`	`assets/`, then `workspace/assets/` for MkDocs
`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.

The application repository's root README.md, AGENTS.md, source code, operational scripts, Compose/Nginx runtime files, ignored work/ or artifacts/, environment files and private backups are not exported. The root README in the snapshot comes from docs/README.md. Review exported Markdown and screenshots for sensitive content too: this is a file allowlist, not a secret scanner.

The Andrea redesign navigation topic begins at redesign.md; dated handoffs are grouped as implementation records. Navigation is edited in this source repository's MkDocs template, not maintained independently in GitLab.

Create the ZIP¶

From the authoritative WSL checkout:

cd /home/justin/repos/AndreaWeb
bash 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:

bash 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¶

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

The custom domain, its ownership-verification TXT record, primary-domain setting, and GitLab-managed certificate belong to the GitLab project configuration. Replacing the repository snapshot and rerunning the pipeline does not require recreating them.

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
  0003-production-resource-and-retention.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.