nebari-dev · kcpevey · Jun 19, 2026 · Jun 19, 2026
diff --git a/.github/workflows/deploy-docs.yml b/.github/workflows/deploy-docs.yml
@@ -0,0 +1,55 @@
+name: Deploy docs to GitHub Pages
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+
+jobs:
+  build:
+    name: Build
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: npm
+          cache-dependency-path: docs/package-lock.json
+
+      - name: Install dependencies
+        run: npm ci
+        working-directory: docs
+
+      - name: Type check
+        run: npm run typecheck
+        working-directory: docs
+
+      - name: Build website
+        run: npm run build
+        working-directory: docs
+
+      - name: Upload build artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: docs/build
+
+  deploy:
+    name: Deploy to GitHub Pages
+    needs: build
+    if: github.ref == 'refs/heads/main'
+    permissions:
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4
diff --git a/docs/README.md b/docs/README.md
@@ -1,149 +1,49 @@
-# Nebari MLflow Pack
+# Nebari MLflow Pack Documentation
 
-# Contributing to the documentation 📝
+This directory contains the [Docusaurus](https://docusaurus.io/) site for the Nebari MLflow Pack. The site is written in TypeScript.
 
-Nebari's documentation is built with [Docusaurus 2](https://docusaurus.io/), a modern static website generator.
+## Prerequisites
 
-- [Contributing to the documentation 📝](#contributing-to-the-documentation-)
-  - [Setting your local development environment](#setting-your-local-development-environment)
-    - [Prerequisites](#prerequisites)
-    - [Installing docs dependencies](#installing-docs-dependencies)
-    - [Pre-commit hooks](#pre-commit-hooks)
-    - [Working on the docs](#working-on-the-docs)
-    - [Building the site locally](#building-the-site-locally)
-  - [Adding a New Dependency](#adding-a-new-dependency)
-  - [Deployment](#deployment)
-  - [Linting](#linting)
+- Node.js `>= 20` (enforced by the `engines` field in `package.json`).
+- npm (bundled with Node.js).
 
-## Setting your local development environment
-
-1. Make a fork of the [`Nebari- MLflow pack` repository][nebari-mlflow-repo] to your GitHub account
-2. Clone the forked repository to your local machine:
-
-   ```bash
-   git clone https://github.com/<your-username>/nebari-mlflow-pack.git
-   ```
-
-### Prerequisites
-
-To build the site you will need to have Node.js installed. To see if you already have Node.js installed, type the following command into your local command line terminal:
-
-```console
-$ node -v
-v14.17.0
-```
-
-If you see a version number, such as `v14.17.0` printed, you have Node.js installed. If you get a `command not found` error (or similar phrasing), please install Node.js before continuing.
-
-To install node visit [nodejs.org](https://nodejs.org/en/download/) or check any of these handy tutorials for [Ubuntu](https://www.digitalocean.com/community/tutorials/how-to-install-node-js-on-ubuntu-20-04), [Debian](https://www.digitalocean.com/community/tutorials/how-to-install-node-js-on-debian-10), or [macOS](https://www.digitalocean.com/community/tutorials/how-to-install-node-js-and-create-a-local-development-environment-on-macos).
-
-Once you have Node.js installed you can proceed to install Yarn. Yarn has a unique way of installing and running itself in your JavaScript projects. First you install the yarn command globally, then you use the global yarn command to install a specific local version of Yarn into your project directory.
-
-The Yarn maintainers recommend installing Yarn globally by using the `NPM` package manager, which is included by default with all Node.js installations.
-Use the `-g` flag with `npm` install to do this:
+## Install
 
 ```bash
-npm install -g yarn
+cd docs
+npm install
 ```
 
-After the package installs, have the yarn command print its own version number. This will let you verify it was installed properly:
-
-```console
-$ yarn --version
-1.22.11
-```
-
-### Installing docs dependencies
-
-1. First make sure to be in the `/docs` directory:
-
-   ```bash
-   cd docs
-   ```
-
-2. Install the necessary dependencies:
-
-   ```bash
-   yarn install
-   ```
-
-### Pre-commit hooks
-
-This repository uses a number of [pre-commit hooks](https://pre-commit.com/) to standardize our YAML and markdown structure.
-**Note** - You will need to have Python>= 3.7 installed in your local machine.
-
-1. Before you can run the hooks, you need to install the pre-commit package manager:
-
-   ```bash
-   # using pip
-   pip install pre-commit
-
-   # if you prefer using conda
-   conda install -c conda-forge pre-commit
-   ```
-
-2. From the root of this project, install the git hook scripts:
-
-   ```bash
-   # install the pre-commit hooks
-   pre-commit install
-   ```
-
-3. Optional- run the hooks against the files in this repository
-
-   ```bash
-   # run the pre-commit hooks
-   pre-commit run --all-files
-   ```
-
-Once installed, the pre-commit hooks will run automatically when you make a commit in version control.
-
-### Working on the docs
-
-Once you have the pre-commits and the dependencies installed, you can get started with the documentation.
-To see a live local version of the docs run the following command:
+## Local development
 
 ```bash
-yarn start
+npm start
 ```
 
-This command starts a local development server and opens up a browser window.
-Most changes are reflected live without having to restart the server.
-
-> **Note**
-> By default, this will load your site at <http://localhost:3000/>.
+Starts the Docusaurus dev server with hot reload on http://localhost:3000/.
 
-### Building the site locally
-
-To build the static files of the documentation, run:
+## Production build
 
 ```bash
-yarn build
+npm run build
 ```
 
-This command generates static content into the `docs/build` directory and can be served using any static contents hosting service.
-You can check the new build site with the following command:
+Emits static files to `docs/build/`. The search index is generated as part of the production build.
+
+## Preview the production build
 
 ```bash
-yarn run serve
+npm run serve
 ```
 
-> **Note**
-> By default, this will load your site at <http://localhost:3000/>.
+Serves the contents of `docs/build/` locally so you can verify the production output, including search.
 
-## Adding a New Dependency
-
-Use the `add` sub command to add new dependencies:
+## Type checking
 
 ```bash
-yarn add package-name
+npm run typecheck
 ```
 
-## Linting
-
-Before opening a PR, run the docs linter and formatter to ensure code consistency. From the `docs` directory, run:
+## CI
 
-```bash
-yarn run lint
-yarn run format
-```
+The [`Deploy docs to GitHub Pages` workflow](../.github/workflows/deploy-docs.yml) builds the site for every pull request and push to `main`.
diff --git a/docs/babel.config.js b/docs/babel.config.js
diff --git a/docs/auth-flow.md → docs/docs/auth-flow.md b/docs/auth-flow.md → docs/docs/auth-flow.md
@@ -1,3 +1,9 @@
+---
+title: Authentication Flow
+description: How OIDC authentication works for Nebari Software Packs.
+sidebar_position: 2
+---
+
 # Authentication Flow
 
 Detailed explanation of how OIDC authentication works for Nebari Software Packs.

diff --git a/docs/docs/introduction.md b/docs/docs/introduction.md
diff --git a/docs/docs/introduction.mdx b/docs/docs/introduction.mdx
@@ -0,0 +1,17 @@
+---
+title: Introduction
+description: Documentation for the Nebari MLflow Pack, a Helm chart that deploys MLflow on Nebari with Keycloak authentication, PostgreSQL, and TLS.
+slug: /
+sidebar_position: 1
+last_update:
+  date: 2026-06-19
+---
+
+# Nebari MLflow Pack
+
+Deploy MLflow on Nebari with Keycloak authentication, PostgreSQL, and TLS.
+
+## Additional documentation
+
+- [Authentication Flow](./auth-flow) — how OIDC authentication works for Nebari Software Packs
+- [NebariApp CRD Reference](./nebariapp-crd-reference) — complete field-by-field reference for the NebariApp custom resource
diff --git a/docs/nebariapp-crd-reference.md → docs/docs/nebariapp-crd-reference.md b/docs/nebariapp-crd-reference.md → docs/docs/nebariapp-crd-reference.md
@@ -1,3 +1,9 @@
+---
+title: NebariApp CRD Reference
+description: Complete field-by-field reference for the NebariApp custom resource.
+sidebar_position: 3
+---
+
 # NebariApp CRD Reference
 
 Complete field-by-field reference for the NebariApp custom resource.