Skip to content

docs: migrate the documentation site into the monorepo - #939

Merged
r0ssing merged 150 commits into
devfrom
docs/migrate-documentation-site
Sep 26, 2026
Merged

r0ssing merged 150 commits into
devfrom
docs/migrate-documentation-site

Conversation

@najuna-brian

@najuna-brian najuna-brian commented Sep 26, 2026 •

Copy link
Copy Markdown
Member

What

Moves the Docusaurus site from the standalone OpenDataEnsemble/docs repository into this monorepo at docs/, so documentation changes ship in the same PR as the code they describe.

The docs repository history is preserved: the site was imported with git subtree add --prefix=docs, so all 140 commits from OpenDataEnsemble/docs are ancestors of this branch. git log HEAD~3^2 -- docusaurus.config.ts walks the original docs history.

Layout

docs/                     Docusaurus site root (independent npm project)
docs/docs/                content root: getting-started, using, guides, reference, community, ...
docs/static/              assets + CNAME + .nojekyll
docs/src/                 custom components, theme overrides, /downloads page
.github/workflows/docs.yml

No URL changes

url, baseUrl: '/' and routeBasePath: '/docs' are unchanged, so https://opendataensemble.org/docs/... keeps working. The site stays an independent npm project (the rest of the monorepo uses pnpm); docs/package-lock.json is committed via a .gitignore exception.

Fixes made along the way

  • editUrl pointed at a non-existent ode-docs/ directory; it now resolves to ode/tree/dev/docs/docs/<page>.
  • projectName / organizationName now identify OpenDataEnsemble/ode.
  • The repo-root docs/custom-question-types.md becomes a published page, docs/docs/guides/custom-question-types.md, linked from Custom Extensions.
  • Contributor docs updated: repo URLs, dev as the default branch, community forum links, and the site README's incorrect versioning notes (versioning is disabled, versions.json is empty).
  • Dropped files the site never used: a nested workflow, create-placeholders.sh, an unreferenced sidebars-api.ts, and a stale copy of the Synkronus OpenAPI document.
  • CNAME moved into static/, where Docusaurus actually publishes it.

CI

.github/workflows/docs.yml runs npm ci, npm run test and npm run build (with onBrokenLinks: 'throw') on pull requests touching docs/**, and deploys to GitHub Pages on pushes to dev. Locally verified: 104 pages build, build/CNAME is opendataensemble.org, .nojekyll present.

⚠️ Cutover required after merge

OpenDataEnsemble/docs currently owns the opendataensemble.org custom domain, and only one Pages site can hold a domain. The deploy will fail until that domain is moved to this repository. Plan:

  1. Disable the old repo's Documentation CI & Deploy workflow.
  2. Merge this PR; the first deploy publishes to the github.io fallback URL, proving the pipeline.
  3. Release opendataensemble.org from OpenDataEnsemble/docs and assign it to OpenDataEnsemble/ode.

najuna-brian and others added 19 commits August 19, 2026 18:21
git-subtree-dir: docs
git-subtree-mainline: 53286d7
git-subtree-split: 17700bd
The standalone docs repository carried a nested GitHub Actions workflow, a
placeholder generator, an unreferenced sidebar fragment, and a stale copy of
the Synkronus OpenAPI document (v1.0.3, behind synkronus/openapi/synkronus.yaml).
None of them are used by the Docusaurus build. The root-level CNAME is not
served by Docusaurus, so it moves into static/ where it is published.
- point organizationName/projectName at OpenDataEnsemble/ode
- fix the edit URL, which pointed at a non-existent ode-docs directory
- publish the custom question types guide that lived at the repo root and
  link it from Custom Extensions
- update contributor docs: repo URLs, dev as the default branch, forum links
- rewrite the site README for its new home and correct the versioning notes
  (versioning is disabled; versions.json is empty)
Adds .github/workflows/docs.yml, which validates the Docusaurus site on pull
requests and deploys it to GitHub Pages from dev. Registers docs/ in the
monorepo map and contributor guides.
The docs repository marked scripts/validate-docs.ts as executable because of
its shebang, but it is only ever run through npm run test.
r0ssing
r0ssing previously approved these changes Sep 26, 2026

@r0ssing r0ssing left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looks great! I suggest we update to deploy from 'main' (I added code suggestions where needed). If you agree, please feel free to accept those and merge the PR 🦖

Then we can update the repo settings together afterwards....

Comment thread .github/workflows/docs.yml Outdated
Comment thread .github/workflows/docs.yml Outdated
Comment thread .github/CICD.md Outdated
Comment thread .github/CICD.md Outdated
Co-authored-by: Emil Rossing <emil@rossing.org>
najuna-brian and others added 3 commits September 26, 2026 19:19
Co-authored-by: Emil Rossing <emil@rossing.org>
Co-authored-by: Emil Rossing <emil@rossing.org>
Co-authored-by: Emil Rossing <emil@rossing.org>
@r0ssing
r0ssing merged commit c7f334a into dev Sep 26, 2026
10 checks passed
@r0ssing
r0ssing deleted the docs/migrate-documentation-site branch September 26, 2026 16:25
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

6 participants