Revamp docs

[leopiccionia]

The site overhaul addressed two complementary diagnoses. Issue #518 identified that publishing the site by committing the generated build back into master (a leftover from PR #512) was only an intermediate step, mixing site generation with the development flow. Issue #671 identified that the current MkDocs theme had poor branding and lagged behind modern static-site generators. We decided to tackle both together: the generation stack and the publishing architecture.

On the generator, although the comparison in #671 recommended Starlight as the first option, we settled on VitePress for two practical reasons: it required a much smaller migration diff, and it lets us keep the docs/ folder hosting the Markdown sources (recent Starlight versions removed the option to customize the content folder). Familiarity, already expressed in the issue, reinforced the choice. It fully meets the three requirements we set: 100% static output for GitHub Pages, embedded local search with no external service, and branding via CSS variables and theme overrides.

The open question in #518 — whether the future site should remain purely technical documentation or also present the project — was answered with a two-part architecture under a single origin: a React + Vite landing page at the root (jeowp.org) presenting JEO, and the VitePress documentation under /docs/. This separates the editorial purposes without fragmenting the user experience.

For publishing, we implemented exactly the outcome proposed in #518: a dedicated workflow (deploy-site.yml) builds the complete site on every push to master and publishes it to the gh-pages branch — preserving history, guaranteeing .nojekyll + CNAME, with an idempotent orphan fallback. The old workflow (docs-site.yml) was removed, and the generated tree (site/) left the repository entirely (now gitignored). Builds are deterministic (content-hashed assets are stable across builds), which validates serving from CI artifacts.

On the content side, pages remain flat Markdown files in docs/ and docs/dev/, and internal links were standardized as relative .md anchors, turning VitePress's dead-link check into a real build gate. Content migrated essentially 1:1 from MkDocs, as the comparison anticipated.

[leopiccionia]

O tom de verde é inspirado na nova landing page.

Tema claro:

Tema escuro (fundo ligeiramente azul, também inspirado na landing page):