Docs: Docusaurus site + Pages deploy

[flyingrobots]

[coderabbitai]

Warning

Rate limit exceeded

@flyingrobots has exceeded the limit for the number of commits or files that can be reviewed per hour. Please wait 3 minutes and 12 seconds before requesting another review.

⌛ How to resolve this issue?

After the wait time has elapsed, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout.

Please see our FAQ for further information.

📥 Commits

Reviewing files that changed from the base of the PR and between 8159193 and 10b2f8c.

📒 Files selected for processing (3)

• .github/workflows/docs-site.yml (1 hunks)
• website/docusaurus.config.js (1 hunks)
• website/src/pages/index.md (1 hunks)

Summary by CodeRabbit

• New Features

  • Launched a new documentation site with automatic deployment to GitHub Pages on every update.
  • Added support for technical diagrams in documentation.
  • Created a documentation homepage with centralized navigation to roadmap, issues, and docs.

• Chores

  • Consolidated legacy planning documentation.
  • Configured continuous integration for automated documentation builds and deployment.

Walkthrough

Introduces a complete documentation site infrastructure using Docusaurus with GitHub Pages deployment. Adds a GitHub Actions workflow for automated builds and deployments, Docusaurus configuration, website scaffolding with Mermaid support, and removes legacy planning files from the docs directory.

Changes

Cohort / File(s)	Summary
GitHub Actions Workflow .github/workflows/docs-site.yml	New CI/CD pipeline for building and deploying documentation site to GitHub Pages; triggers on main branch changes to website/docs and manual dispatch; build job runs Node.js 20 build, deploy job publishes artifacts.
Docusaurus Configuration website/docusaurus.config.js, website/sidebars.js	Site metadata configuration (title, URL, baseUrl), navbar/footer setup with Docs/Roadmap/GitHub links, classic preset pointing to ../docs, autogenerated sidebars from all docs, and Mermaid plugin integration.
Package Management website/package.json	Docusaurus project manifest with core dependencies (@docusaurus/core, preset-classic, theme-mermaid), npm scripts (start, build, serve, clear), React/ReactDOM, and supporting utilities.
Styling & Content website/src/css/custom.css, website/src/pages/index.md	Custom CSS root color palette variables and homepage markdown with project intro, docs link, roadmap reference, and issues board navigation.
Documentation Index docs/index.md	New docs landing page with YAML front matter and Welcome section with links to ROADMAP-DAG, ISSUES, and DRIFT_REPORT.
Deprecated Files docs/ISSUE-BREAKDOWN.md ↓, docs/ISSUE-DRAFTS.md ↓, docs/PROJECT-PLAN.md ↓	Legacy planning documents removed; consolidated references to docs/ISSUES.md pointer.

Sequence Diagram(s)

sequenceDiagram
    participant GH as GitHub
    participant WF as Workflow<br/>(docs-site.yml)
    participant Build as Build Job
    participant Deploy as Deploy Job
    participant Pages as GitHub Pages

    GH->>WF: Push to main or manual dispatch
    WF->>Build: Trigger build job
    Build->>Build: Checkout, setup Node.js 20
    Build->>Build: npm install & build site
    Build->>GH: Upload artifact
    WF->>Deploy: Trigger deploy job (depends: build)
    Deploy->>Deploy: Download artifact
    Deploy->>Pages: Deploy to GitHub Pages
    Pages-->>GH: Publish live site

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

• website/docusaurus.config.js: Verify all URLs, baseUrl, and Mermaid plugin configuration are production-ready; confirm docs path resolution (../docs) is correct relative to website directory
• website/sidebars.js: Autogenerated sidebar with dirName: '.' will traverse entire docs tree—confirm this scope is intentional and won't surface unintended files
• .github/workflows/docs-site.yml: Validate concurrency group behavior, artifact retention, permissions scope, and Node.js version pinning; confirm Pages deployment secrets/environment variables are configured
• website/package.json: Verify dependency versions are compatible; Docusaurus v3+ and theme-mermaid integration should be tested locally
• docs/index.md & website/src/pages/index.md: Both serve similar landing functions—clarify which is primary; potential confusion between docs/ root and website homepage

Possibly related PRs

• Docs/Issues: remove legacy planning files, add index, AC sweep #75: Coordinates removal of legacy planning documents (ISSUE-BREAKDOWN.md, ISSUE-DRAFTS.md, PROJECT-PLAN.md) and consolidation to docs/ISSUES.md pointer—directly overlaps with this PR's docs cleanup.

Poem

📚✨ Docs take flight, Docusaurus in sight,
Mermaid diagrams dance, pages deploy at night,
GitHub Actions hum, sidebars autogenerate—
A documentation kingdom, finally ornate! 🚀

Pre-merge checks and finishing touches

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Description Check	⚠️ Warning	The pull request description is essentially empty, containing only a single dash character. The repository template requires a structured description with multiple sections: a Summary linking the primary issue and milestone, Testing checkboxes for build and deployment verification, Deployment/Release Impact assessment, and a Reviewer Checklist. This PR provides none of these required sections, making it impossible to understand the context, testing performed, or deployment implications of the changes.	The description must be completed according to the repository template. Add a Summary section that briefly describes the Docusaurus documentation site addition and links any related issue(s), complete the Testing section by checking appropriate build and test commands, specify the Deployment/Release Impact (documenting that this adds infrastructure without breaking changes), and verify the Reviewer Checklist items are satisfied. At minimum, include an issue link and description of what was tested.

✅ Passed checks (1 passed)

Check name	Status	Explanation
Title Check	✅ Passed	The pull request title "Docs: Docusaurus site + Pages deploy" is directly aligned with the primary changes in this changeset. The raw summary confirms that the PR introduces a new Docusaurus documentation site infrastructure under the website/ directory and adds a GitHub Actions workflow for automated deployment to GitHub Pages. The title is concise, specific, and avoids vague terminology—a developer scanning the commit history would immediately understand that this change establishes documentation infrastructure with automated deployment.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 12

📜 Review details

Configuration used: CodeRabbit UI

Review profile: ASSERTIVE

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between cd62b3d and 8159193.

📒 Files selected for processing (8)

• .github/workflows/docs-site.yml (1 hunks)
• ACTIVITY.log.jsonl (1 hunks)
• docs/index.md (1 hunks)
• website/docusaurus.config.js (1 hunks)
• website/package.json (1 hunks)
• website/sidebars.js (1 hunks)
• website/src/css/custom.css (1 hunks)
• website/src/pages/index.md (1 hunks)

🧰 Additional context used

🪛 YAMLlint (1.37.1)

.github/workflows/docs-site.yml

[warning] 3-3: truthy value should be one of [false, true]

(truthy)

---

[error] 5-5: too many spaces inside brackets

(brackets)

---

[error] 5-5: too many spaces inside brackets

(brackets)

---

[error] 56-56: too many blank lines (1 > 0)

(empty-lines)

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (3)

• GitHub Check: Clang 18 (Ubuntu 24.04)
• GitHub Check: Freestanding (Linux, CRT shim)
• GitHub Check: GCC 14 (Ubuntu 24.04)