Skip to content

Docs Platform (How this site works)

This page explains how the Sitios documentation site is authored, deployed, and protected.

TL;DR

  • Repo: Sitios-Agencia-Digital/docs
  • Authoring: Markdown in docs/ + navigation in mkdocs.yml
  • Site generator: MkDocs + Material theme
  • Hosting: Cloudflare Pages (serves the static site/ output)
  • Auth: Cloudflare Access using GitHub login (restricted to the Sitios GitHub org/team)
  • Why not GitHub Pages: it would make the site publicly reachable at the Pages URL, which is not acceptable for internal runbooks/ops docs and would probably expose all the vulnerabilities in our bad architecture lol

Repo layout

mkdocs.yml            # MkDocs config (nav/theme)
requirements.txt      # MkDocs dependencies
docs/                 # Markdown content + static assets
  index.md            # Home page
  assets/             # Images, favicon, etc.

Local development

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
mkdocs serve

Cloudflare Pages deployment

Cloudflare Pages builds the site on each push to the production branch (currently master) and publishes the static output.

Recommended Pages build settings:

  • Build command: pip install -r requirements.txt && mkdocs build
  • Build output directory: site
  • Root directory: /
  • Custom domain: docs.sitios.uy

MkDocs writes the final static website to site/ (HTML/CSS/JS). Cloudflare Pages serves that directory.

Authentication (Cloudflare Access + GitHub)

We protect docs.sitios.uy with Cloudflare Access.

High-level setup:

  • Zero Trust → Settings → Authentication: enable GitHub as a login method
  • Zero Trust → Access → Applications: create a Self-hosted app for docs.sitios.uy
  • Policies: add an Allow policy that only permits GitHub users in the Sitios org/team

We intentionally disable other login methods (e.g. one-time PIN/email) to avoid accidental access paths.