omegaUp Documentation Site

The source for omegaUp's contributor and architecture documentation, published at docs.omegaup.com. It is a static site built with Zensical (the successor to Material for MkDocs, from the same team) and ships in four languages: English (en, the source of truth), Spanish (es), Portuguese (pt), and Brazilian Portuguese (pt-BR).

New here? Read QUICKSTART.md for the two commands that get you a local preview, then come back for the details.

How this repository is organized

English is authored by hand; the other three languages are generated from it by scripts/translate_docs.py. That single rule drives the whole workflow:

• Edit docs/en/ only. Never hand-edit docs/es/, docs/pt/, or docs/pt-BR/ — your changes there are overwritten on the next translation run.
• Each language has its own zensical.<lang>.toml config (its docs_dir, site_dir, language, and navigation labels). The navigation structure — the file paths — is identical across all four; only the visible section titles are localized.
• When you add, rename, or remove a page, update the nav in all four zensical*.toml files so every language builds cleanly. scripts/verify_docs_nav.py (run automatically by build_all.py) fails the build if any .md file is missing from its nav, and scripts/verify_docs_rendered.py fails if any page produced no HTML.

Local development

Zensical is a Python package. Everything below assumes Python 3.10+.

1. Install

python3 -m venv .venv
source .venv/bin/activate          # Windows: .venv\Scripts\activate
pip install zensical

If the zensical console command isn't on your PATH (e.g. a global install), use python3 -m zensical … instead — build_all.py already does this for you.

2. Build all languages

python3 build_all.py

This cleans site/, verifies every page is in nav, builds /en/, /es/, /pt/, and /pt-BR/, verifies every page rendered, and writes a root redirect from / to /en/.

To build a single language while iterating:

python3 -m zensical build --clean --config-file zensical.toml        # English
python3 -m zensical build --clean --config-file zensical.es.toml     # Spanish

3. Serve locally

python3 serve_multilang.py          # http://localhost:8000/ (redirects to /en/)

Use this rather than zensical serve — the multi-language server maps /en/, /es/, /pt/, and /pt-BR/ correctly so the language switcher works. zensical serve only knows about one language directory and 404s on the others.

4. Regenerate translations (do this last)

Only after the English tree is finalized and reviewed:

python3 scripts/translate_docs.py                    # all languages, all files
python3 scripts/translate_docs.py --langs pt         # one language
python3 scripts/translate_docs.py --only getting-started   # a subset, for testing

Running the translator before English is final wastes effort and creates drift, because it overwrites es/pt/pt-BR wholesale.

Deployment

Pushing to main triggers .github/workflows/deploy.yml, which builds all four languages and publishes to GitHub Pages. The workflow is self-configuring — you do not edit site_url by hand for a deploy:

• It computes site_url at build time from the repository owner/name (https://<owner>.github.io/<repo>/, or the apex form when the repo is named after the owner), rewriting every zensical*.toml before building. The site_url committed in the toml files is only a placeholder for local builds.
• It authenticates GitHub Pages with secrets.PAGES_DEPLOY_TOKEN, falling back to the default github.token. The token is required for the omegaup org repository — the default token can't enable Pages on an org repo.
• After building it rewrites asset paths for the Pages base path, forces the omegaUp favicon, adds .nojekyll, and writes the / → /en/ redirect.

For a custom domain (docs.omegaup.com), set the CNAME in the Pages settings; the computed site_url still applies for path resolution.

Project structure

ou-documentation/
├── .github/workflows/deploy.yml   # Build + GitHub Pages deploy (self-configuring)
├── docs/
│   ├── en/                        # English — the source of truth (edit here)
│   ├── es/  pt/  pt-BR/           # Generated by scripts/translate_docs.py — do not edit
│   └── <lang>/{assets,stylesheets,javascripts}/
├── overrides/                     # Theme customizations (nav partial + custom icons)
├── scripts/
│   ├── translate_docs.py          # Generate es/pt/pt-BR from en
│   ├── verify_docs_nav.py         # Fail build if a page is missing from nav
│   ├── verify_docs_rendered.py    # Fail build if a page produced no HTML
│   └── generate-gsoc-pages.py     # Build GSoC pages from community/gsoc/_data
├── zensical.toml                  # English config (+ .es / .pt / .pt-BR siblings)
├── build_all.py                   # Build every language + verify + root redirect
├── serve_multilang.py             # Local multi-language dev server (port 8000)
├── QUICKSTART.md                  # Fast path for new contributors
└── README.md                      # This file

site/, .cache/, and .venv/ are generated and gitignored.