r0ssing · Sep 26, 2026 · May 20, 2025 · May 20, 2025 · May 20, 2025 · May 20, 2025
diff --git a/.github/CICD.md b/.github/CICD.md
@@ -187,6 +187,29 @@ This ensures:
 - Each APK is built against the exact assets produced in the same run
 - Formplayer build outputs do not pollute git history
 
+### Documentation Site
+
+**Workflow**: `.github/workflows/docs.yml`
+
+Builds and publishes the Docusaurus site in [`docs/`](../docs/) to [opendataensemble.org](https://opendataensemble.org/) via GitHub Pages.
+
+#### Triggers
+
+| Event | Result |
+|-------|--------|
+| Pull request to `main` or `dev` touching `docs/**` | Validate and build only |
+| Push to `main` touching `docs/**` | Validate, build, and deploy |
+| `workflow_dispatch` | Validate and build |
+
+#### Notes
+
+- The deployed branch is main, so the published docs track the released version of ODE. Changes on dev and pull requests are validated by CI but are not deployed.
+- The site is an independent **npm** project inside the pnpm monorepo: `cache-dependency-path` points at `docs/package-lock.json`, which is force-included in the root `.gitignore` so `npm ci` is reproducible.
+- `docs/docs/` is the Docusaurus content root. URLs are unchanged from the previous standalone `OpenDataEnsemble/docs` repository — `routeBasePath` is still `/docs`.
+- `actions/upload-pages-artifact@v4` is used deliberately: v5 excludes dotfiles by default, which would drop `static/.nojekyll` and `static/CNAME` from the artifact.
+- The upload path is `docs/build` (repo-root relative). `defaults.run.working-directory` does not apply to `uses:` steps.
+- No secrets are required. The deploy job needs `contents: read`, `pages: write`, and `id-token: write`.
+
 ### SBOM (CycloneDX) on releases
 
 **Workflow**: `.github/workflows/sbom-release.yml`

diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
@@ -0,0 +1,102 @@
+name: Docs
+
+on:
+  pull_request:
+    branches: [main, dev]
+    paths:
+      - 'docs/**'
+      - '.github/workflows/docs.yml'
+  push:
+    branches: [main, dev]
+    paths:
+      - 'docs/**'
+      - '.github/workflows/docs.yml'
+  workflow_dispatch:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  # Do not cancel an in-flight production deploy when another push lands.
+  cancel-in-progress: ${{ github.event_name != 'push' }}
+
+permissions:
+  contents: read
+
+env:
+  NODE_VERSION: '24'
+
+jobs:
+  validate:
+    name: Validate
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: docs
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
+        with:
+          fetch-depth: 0
+
+      - name: Set up Node.js
+        uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
+        with:
+          node-version: ${{ env.NODE_VERSION }}
+          cache: npm
+          cache-dependency-path: docs/package-lock.json
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Check links and doc IDs
+        run: npm run test
+
+      - name: Build site
+        env:
+          CI: true
+        run: npm run build
+
+  deploy:
+    name: Deploy to GitHub Pages
+    needs: validate
+    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+    runs-on: ubuntu-latest
+
+    permissions:
+      contents: read # checkout (job permissions replace the workflow defaults)
+      pages: write # to deploy to Pages
+      id-token: write # to verify the deployment originates from an appropriate source
+
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+
+    defaults:
+      run:
+        working-directory: docs
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
+
+      - name: Set up Node.js
+        uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
+        with:
+          node-version: ${{ env.NODE_VERSION }}
+          cache: npm
+          cache-dependency-path: docs/package-lock.json
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Build site
+        run: npm run build
+
+      - name: Upload Pages artifact
+        uses: actions/upload-pages-artifact@7b1f4a764d45c48632c6b24a0339c27f5614fb0b # v4
+        with:
+          # Action paths are relative to the repo root, not defaults.run.working-directory.
+          path: docs/build
+
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@d6db90164ac5ed86f2b6aed7e0febac5b3c0c03e # v4
diff --git a/.gitignore b/.gitignore
@@ -11,6 +11,8 @@ package-lock.json
 **/package-lock.json
 # F-Droid builds use npm ci / install --build-from-source in formulus/
 !formulus/package-lock.json
+# Documentation site deploys with npm ci, so its lockfile must be committed
+!docs/package-lock.json
 
 # Generated credentials
 **/credentials.txt

diff --git a/AGENTS.md b/AGENTS.md
@@ -57,6 +57,7 @@ Do not assume custom app authors have local checkouts of **ODE** or internal exa
 | [packages/tokens](packages/tokens/) | Design tokens (`@ode/tokens`) | Style Dictionary | [packages/tokens/AGENTS.md](packages/tokens/AGENTS.md) |
 | [packages/components](packages/components/) | Shared UI (`@ode/components`) | React | [packages/components/AGENTS.md](packages/components/AGENTS.md) |
 | [desktop](desktop/) | Data management + Forms / app workbench (Tauri) | React, Rust | [desktop/AGENTS.md](desktop/AGENTS.md) |
+| [docs](docs/) | Documentation site (published at [opendataensemble.org](https://opendataensemble.org/)) | Docusaurus, MDX | [docs/README.md](docs/README.md) |
 
 ---
 

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -64,6 +64,7 @@ This is a monorepo, so the setup depends on the project you're touching. The ful
 - **synkronus-cli** - Go command-line client. See `synkronus-cli/README.md`; pre-flight is `cd synkronus-cli && go build ./cmd/synkronus`.
 - **synkronus-portal** - web admin UI (React). See `synkronus-portal/README.md` for both Docker and Dockerless setups.
 - **desktop** - Tauri app. See `desktop/README.md` (Quick start).
+- **docs** - public Docusaurus site under `docs/`. It is an independent **npm** project (`cd docs && npm install && npm start`); do not use pnpm there. See `docs/README.md`.
 - **packages/tokens** and **packages/components** - see `packages/tokens/CONTRIBUTING.md` and `packages/components/CONTRIBUTING.md`.
 
 The quickest cheat sheet for any package is its `AGENTS.md` file - it lists the day-to-day commands and exactly what to run before a pull request.

diff --git a/FORM_LOCALIZATION_GUIDE.md b/FORM_LOCALIZATION_GUIDE.md
@@ -233,7 +233,7 @@ Behavioral config (`maxStars`, filters, …) stays in **`schema.json`** (`config
 | UI locale preference (host) | `formulus/src/lib/locale.ts`, Settings → Language |
 | Linked child specs for sub-obs columns | `FormInitData.linkedFormSpecs` (built in Formulus / ODE Desktop) |
 
-When changing merge rules or label resolution, update **`applyFormUiTranslations.test.ts`**, affected renderers, and the [published form translations guide](https://opendataensemble.org/docs/guides/form-translations) in **ode-docs**.
+When changing merge rules or label resolution, update **`applyFormUiTranslations.test.ts`**, affected renderers, and the [published form translations guide](https://opendataensemble.org/docs/guides/form-translations) in **`docs/docs/guides/form-translations.md`**.
 
 ---
 

diff --git a/README.md b/README.md
@@ -7,6 +7,7 @@
 [![Formulus Android](https://github.com/OpenDataEnsemble/ode/actions/workflows/formulus-android.yml/badge.svg?branch=main)](https://github.com/OpenDataEnsemble/ode/actions/workflows/formulus-android.yml)
 [![ODE Desktop](https://github.com/OpenDataEnsemble/ode/actions/workflows/ode-desktop.yml/badge.svg?branch=main)](https://github.com/OpenDataEnsemble/ode/actions/workflows/ode-desktop.yml)
 [![E2E attachments](https://github.com/OpenDataEnsemble/ode/actions/workflows/e2e-attachments.yml/badge.svg?branch=main)](https://github.com/OpenDataEnsemble/ode/actions/workflows/e2e-attachments.yml)
+[![Docs](https://github.com/OpenDataEnsemble/ode/actions/workflows/docs.yml/badge.svg?branch=dev)](https://github.com/OpenDataEnsemble/ode/actions/workflows/docs.yml)
 
 <!-- Release & distribution -->
 [![Latest release](https://img.shields.io/github/v/release/OpenDataEnsemble/ode?include_prereleases&sort=semver)](https://github.com/OpenDataEnsemble/ode/releases)
@@ -26,7 +27,7 @@ ODE is a monorepo containing all the core components in the ODE universe - the e
 
 ## Architecture
 
-This repository houses four main components:
+This repository houses the core components plus the public documentation site:
 
 ### **formulus**
 A React Native project containing the code for Android and iOS apps. This is your mobile data collection companion, designed for field work and offline-first data gathering.
@@ -58,6 +59,9 @@ curl -fsSL https://raw.githubusercontent.com/OpenDataEnsemble/ode/main/scripts/i
 ### **synkronus-portal**
 A web-based version of the the **synkronus-cli**
 
+### **docs**
+The public documentation site (Docusaurus), published at [opendataensemble.org](https://opendataensemble.org/). It is an independent npm project inside this monorepo — see [docs/README.md](docs/README.md).
+
 ## We're Young & Fresh! 🌱🌱🌱
 
 ODE is a **young and vibrant open-source project**, and we're incredibly welcoming to contributors of all experience levels and interests! Whether you're passionate about:
@@ -89,6 +93,7 @@ This monorepo uses GitHub Actions for CI/CD. For details (trigger conditions, ta
 
 - Synkronus Docker build & publish: `.github/workflows/synkronus-docker.yml`
 - Formulus Android build (includes Formplayer asset build): `.github/workflows/formulus-android.yml`
+- Documentation site: `.github/workflows/docs.yml` (validates PRs; deploys from `dev`)
 - Synkronus deployment docs: `synkronus/DOCKER.md`, `synkronus/DEPLOYMENT.md`
 
 ## Code Quality: Linting & Formatting 

diff --git a/docs/.gitignore b/docs/.gitignore
@@ -0,0 +1,44 @@
+# Dependencies
+node_modules/
+
+# Production build
+build/
+.docusaurus/
+.cache-loader/
+
+# Generated files
+.docusaurus/
+.cache/
+
+# Misc
+.DS_Store
+.env
+.env.local
+.env.development.local
+.env.test.local
+.env.production.local
+
+# Logs
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+lerna-debug.log*
+devserver.log
+devserver.err.log
+devserver.pid
+
+# Editor directories and files
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+.project
+.classpath
+.settings/
+*.sublime-workspace
+
+# OS
+.DS_Store
+Thumbs.db
+
diff --git a/docs/README.md b/docs/README.md
@@ -0,0 +1,54 @@
+# ODE Documentation Site
+
+The ODE documentation site, built with [Docusaurus](https://docusaurus.io/) and published at [opendataensemble.org](https://opendataensemble.org/).
+
+This site lives in the [`OpenDataEnsemble/ode`](https://github.com/OpenDataEnsemble/ode) monorepo under `docs/`. It is an independent **npm** project — the rest of the monorepo uses **pnpm**, so run npm commands from this directory.
+
+## Layout
+
+| Path | Purpose |
+|------|---------|
+| `docs/docs/` | Documentation content (Markdown/MDX). One folder per section: `getting-started/`, `guides/`, `using/`, `reference/`, `community/`, … |
+| `docs/static/` | Assets copied verbatim to the site root (`img/`, `fonts/`, `diagrams/`), plus `CNAME` and `.nojekyll` |
+| `docusaurus.config.ts` | Site config: navbar, footer, routing, plugins |
+| `sidebars.ts` | Sidebar structure (persona-based: For Data Collectors / For Implementers / For Developers) |
+| `plugins/` | Remark/rehype link fixups |
+| `scripts/validate-docs.ts` | Fast validation run by `npm run test` |
+| `src/` | Custom React components, theme overrides, and the `/downloads` page |
+
+## Local development
+
+```bash
+npm install
+npm start
+```
+
+Starts a dev server with hot reload. The site is served at `/`, documentation under `/docs`.
+
+## Validation
+
+Run these before opening a PR — the CI workflow runs the same commands.
+
+```bash
+npm run test      # fast: docId references, internal links, config paths
+npm run build     # full: compiles every page, fails on broken links
+npm run validate  # both of the above
+```
+
+`npm run build` is the real gate: the site is configured with `onBrokenLinks: 'throw'`, so a broken internal link fails the build rather than shipping.
+
+## Deployment
+
+[`docs.yml`](../.github/workflows/docs.yml) publishes the site to GitHub Pages:
+
+| Trigger | Result |
+|---------|--------|
+| Pull request to `main` or `dev` touching `docs/**` | Validate and build only |
+| Push to `dev` touching `docs/**` | Validate, build, and deploy |
+| Manual (`workflow_dispatch`) | Validate and build |
+
+The deployed branch is **`dev`**, so the site reflects the latest merged work rather than the last release. Deploys run with `actions/deploy-pages` and require no secrets.
+
+:::note Versioning
+Docusaurus versioning is currently **disabled** (`disableVersioning: true` in `docusaurus.config.ts`, and `versions.json` is empty). There is no version dropdown: every visitor sees the current docs.
+:::
diff --git a/docs/babel.config.js b/docs/babel.config.js
@@ -0,0 +1,4 @@
+module.exports = {
+  presets: [require.resolve('@docusaurus/core/lib/babel/preset')],
+};
+