[Docs] moved to docusaurus for the docs migration (#37)

Author: Dhruv-Mehndhiratta-Centml

.github/workflows/deploy.yml

@@ -0,0 +1,43 @@
+name: Deploy Docs
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: true
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: npm
+
+      - run: npm ci
+      - run: npm run build
+
+      - uses: actions/upload-pages-artifact@v3
+        with:
+          path: build
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - id: deployment
+        uses: actions/deploy-pages@v4

.gitignore

@@ -5,3 +5,13 @@
 
 # Context files (local only)
 .context/
+
+# Node dependencies
+node_modules/
+
+# This project uses npm (package-lock.json); reject yarn lockfiles
+yarn.lock
+
+# Docusaurus generated files
+.docusaurus/
+build/

AGENTS.md

@@ -1,65 +1,126 @@
 # AGENTS.md
 
-This repository is a Mintlify documentation site for NVIDIA CCluster. Future agents should optimize for safe documentation edits, fast local preview, and minimal assumptions about unpublished content.
+This repository is a Docusaurus 3 documentation site for NVIDIA CCluster. Agents should optimize for safe documentation edits, correct CSS overrides, and working builds.
 
 ## Quick Orientation
 
-- The docs site is configured by [docs.json](docs.json).
-- Most content is written as `.mdx` files under [home/](home), [apps/](apps), [clients/](clients), [resources/](resources), and [examples/](examples).
-- Shared MDX helpers currently live in [snippets/components.mdx](snippets/components.mdx).
-- Static assets live in [images/](images).
-- The local preview environment is containerized via [Dockerfile](Dockerfile) and [docker-compose.yml](docker-compose.yml).
+- **Framework:** Docusaurus 3 with `@docusaurus/preset-classic`
+- **Config:** [docusaurus.config.js](docusaurus.config.js) (site settings, navbar, footer)
+- **Sidebar:** [sidebars.js](sidebars.js) (page order, icons, grouping)
+- **Custom CSS:** [src/css/docs.css](src/css/docs.css) (all Infima/layout overrides)
+- **Icons:** [src/theme/DocSidebarItem/Link/icons.js](src/theme/DocSidebarItem/Link/icons.js) (lucide-react icon map)
+- **Content:** MDX files in [docs/](docs/) with `routeBasePath: '/'`
+- **Static assets:** [static/](static/) (images, CNAME, favicon)
+- **Deployment:** GitHub Pages via [.github/workflows/deploy.yml](.github/workflows/deploy.yml)
 
-## Known Good Local Setup
-
-- The Dockerfile pins the Mintlify CLI to `mint@4.2.516`.
-- Preferred preview command:
+## Local Development
 
 ```bash
-docker compose up --build
+npm start                    # dev server with hot-reload
+docker compose up            # containerized dev server
+npm run build                # production build → build/
+npx docusaurus serve         # serve production build locally
 ```
 
-- Direct local CLI is acceptable, but keep it on the same version:
+## Repo Shape
+
+- [docs/home/](docs/home/) — getting started pages (introduction, quickstart)
+- [docs/deployments/](docs/deployments/) — LLM serving, inference, compute
+- [docs/clients/](docs/clients/) — SDK/client usage docs
+- [docs/resources/](docs/resources/) — operational and supporting guides
+- [docs/examples/](docs/examples/) — example pages and nested example groups
+- [src/theme/](src/theme/) — swizzled Docusaurus components
+- [src/css/](src/css/) — custom CSS overrides
+
+## CSS Architecture
+
+### Layout hierarchy
 
-```bash
-npm install -g mint@4.2.516
-mint dev
+```
+body
+  └── .navbar (padding zeroed; .navbar__inner handles gutters)
+      └── .navbar__inner (max-width: 1440px, margin: auto, padding: 0 2rem)
+  └── .main-wrapper (width: 100%, max-width: 1440px, margin: auto, padding: 0 2rem)
+      └── [docSidebarContainer] (width: 220px, margin-right: 2rem)
+      └── .row
+          └── .col [docItemCol] (main content)
+          └── .col.col--3 (TOC column)
 ```
 
-## Repo Shape
+### Critical CSS variable
+
+```css
+:root { --doc-sidebar-width: 252px; }
+```
+
+This syncs Docusaurus's internal layout calculation with actual sidebar width (220px + 32px margin). Without it, dead space appears beside the content.
+
+### Key rules and why they exist
+
+| Rule | Reason |
+|------|--------|
+| `.main-wrapper { width: 100% }` | Parent is flex with shrink:0; without this, content sets wrapper width → horizontal overflow |
+| `.navbar { padding-left: 0; padding-right: 0 }` | Zeroes Infima default so `.navbar__inner` padding aligns logo with sidebar |
+| `[class*='docItemCol'] { min-width: 0 }` | Flex items default to `min-width: auto`, preventing shrink below content size |
+| `.markdown { overflow-wrap: anywhere }` | Prevents long inline code from causing horizontal scroll |
+| `.table-of-contents:has(> li:only-child) { visibility: hidden }` | Hides TOC when only one heading (mirrors old Mintlify behavior), preserves column space |
+
+### Fixing horizontal overflow
+
+1. Ensure `.main-wrapper` has `width: 100%`
+2. Ensure `[class*='docItemCol']` has `min-width: 0`
+3. Ensure `.markdown` has `overflow-wrap: anywhere`
+4. For specific overflowing elements: `max-width: 100%; overflow-x: auto`
+
+### Changing sidebar width
+
+Update both values together:
+```css
+[class*='docSidebarContainer'] { width: Xpx; min-width: Xpx; }
+:root { --doc-sidebar-width: calc(Xpx + 32px); }
+```
+
+## Sidebar Icons
+
+- `sidebars.js` assigns icon names via `customProps: { icon: 'icon-name' }`
+- `src/theme/DocSidebarItem/Link/index.js` — swizzled component rendering sidebar links
+- `src/theme/DocSidebarItem/Link/icons.js` — maps icon names → lucide-react components
+
+To add a new icon: import from `lucide-react`, add to `ICON_MAP` with key matching `customProps.icon`.
+
+## Content Editing
 
-- [home/](home): entry-point pages
-- [apps/](apps): product capability pages
-- [clients/](clients): SDK/client usage docs
-- [resources/](resources): operational and supporting guides
-- [examples/](examples): example pages and nested example groups
-- [endpoints/](endpoints): API-related files not currently exposed in navigation
+- Frontmatter: `title`, `description`, optional `sidebar_label`
+- Images: wrap in `<Frame>` component for bordered screenshots
+- Image paths: `/images/filename.png` (stored in `static/images/`)
+- For tall images, add inline style: `maxHeight: '360px', width: 'auto', margin: '0 auto'`
+- Hero card image height: controlled by `.ccluster-docs-hero-card__img { aspect-ratio: 5/2 }` in CSS
 
-## Editing Rules Of Thumb
+## Deployment
 
-- Treat [docs.json](docs.json) as the source of truth for page order and visibility.
-- A file existing on disk does not mean it is published in the nav.
-- Prefer local image references like `/images/file.png` for assets stored in this repo.
-- Preserve existing MDX style and frontmatter keys such as `title`, `description`, `icon`, and optional `sidebarTitle` or `mode`.
-- Reuse shared snippet components before introducing one-off duplicated UI blocks.
-- Keep docs changes scoped; this repo does not appear to include general application code.
+- **Production:** GitHub Pages, triggered on push to `main`
+- **Custom domain:** `docs.centml.ai` (configured via `static/CNAME`)
+- **TLS:** automatic via GitHub (Let's Encrypt)
+- **Workflow:** `.github/workflows/deploy.yml` runs `npm ci` → `npm run build` → deploy-pages
 
-## Validation
+## Build Warnings to Expect
 
-- Primary validation is a working Mintlify preview.
-- There is no obvious test or lint command checked into the repository today.
-- For navigation changes, verify both the rendered page and the sidebar placement.
-- For image changes, verify the asset path and rendering in preview.
+- `onBrokenMarkdownLinks` deprecation warning (harmless, Docusaurus v4 migration path)
+- Broken links to `/resources/cli` and `/resources/sdk` (pages not yet created)
 
-## Things That May Surprise You
+## Editing Rules
 
-- The current [README.md](README.md) is repo-specific and should stay aligned with the repository’s Mintlify workflow.
-- The repository contains some content and assets that are not currently referenced from navigation.
-- There is a local `node_modules/` directory in the working tree environment, but it is not tracked by git and should not be relied on as repository metadata.
+- `sidebars.js` is the source of truth for page order and visibility
+- A file existing on disk does not mean it is in the nav
+- Prefer local image references `/images/file.png`
+- Preserve existing MDX style and frontmatter keys
+- Keep docs changes scoped; this repo is docs-only, no application code
+- Test with `npm run build` before pushing — catches broken links and build errors
 
 ## Good First Checks For Any Task
 
-1. Read [README.md](README.md) and [docs.json](docs.json).
-2. Inspect the target page and any shared snippet it imports.
-3. Confirm whether the page is navigation-backed or just present in the repo.
-4. Use the Docker preview if anything about Mintlify versioning seems uncertain.
+1. Read this file and [docusaurus.config.js](docusaurus.config.js)
+2. Run `npm run build` to verify nothing is broken
+3. Inspect the target page's MDX and any component it uses
+4. Confirm whether the page is in `sidebars.js` or just exists on disk
+5. Check `src/css/docs.css` before adding new style rules — the override may already exist

Dockerfile

@@ -1,27 +1,12 @@
-# Use Node.js official image
+# Development-only Dockerfile for local preview
 FROM node:20-alpine
 
-# Set working directory
 WORKDIR /app
 
-# Install Mintlify CLI (pinned to a verified working version)
-RUN npm install -g mint@4.2.516
+COPY package.json package-lock.json* ./
+RUN npm ci
 
-# Create a user and group with specific UID and GID so kubernetes knows
-# it's not a root user. Alpine images ship with /bin/sh by default.
-RUN addgroup -g 1001 centml && adduser -D -s /bin/sh -u 1001 -G centml centml
-
-# Copy all documentation files
 COPY . .
 
-# Change ownership of the app directory to centml user
-RUN chown -R centml:centml /app
-
-# Switch to non-root user
-USER 1001:1001
-
-# Expose port 3000 (default Mintlify dev port)
 EXPOSE 3000
-
-# Command to run Mintlify dev server
-CMD ["mint", "dev"]
+CMD ["npm", "start"]