posit-dev · edavidaja · Jul 1, 2026 · Jul 1, 2026 · Jul 1, 2026 · Jul 1, 2026
diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml
@@ -123,12 +123,13 @@ jobs:
       with:
         version: ">=0.9.0"
     - uses: extractions/setup-just@v3
+    - uses: quarto-dev/quarto-actions/setup@v2
     - name: build docs
       run: just docs
     - uses: actions/upload-artifact@v5
       with:
         name: docs
-        path: site/
+        path: great-docs/_site/
     - uses: aws-actions/configure-aws-credentials@v4
       id: creds
       with:

diff --git a/.github/workflows/preview-docs.yml b/.github/workflows/preview-docs.yml
@@ -24,11 +24,13 @@ jobs:
 
       - uses: extractions/setup-just@v3
 
+      - uses: quarto-dev/quarto-actions/setup@v2
+
       - name: Install and Build
         if: github.event.action != 'closed' # skip the build if the PR has been closed
         run: just docs
 
       - name: Deploy preview
         uses: rossjrw/pr-preview-action@v1
         with:
-          source-dir: ./site/
+          source-dir: ./great-docs/_site/
diff --git a/.gitignore b/.gitignore
@@ -36,3 +36,7 @@ vetiver-testing/rsconnect_api_keys.json
 # license files should not be commited to this repository
 *.lic
 /site/
+
+# great-docs managed build output and docs venv
+/great-docs/
+.venv-docs/
diff --git a/CLAUDE.md b/CLAUDE.md
@@ -54,6 +54,14 @@ just docs
 just docs-serve
 ```
 
+Docs are built with [great-docs](https://github.com/posit-dev/great-docs) (Quarto-based), not
+mkdocs. Requires the **Quarto CLI** to be installed. `just docs` provisions an isolated
+`.venv-docs` (Python 3.12) with `uv venv`/`uv pip install`, then runs `great-docs build` inside
+that venv — it does **not** use `uv run --with`, because Quarto's post-render hook must execute
+under the same interpreter that has `great_docs`/`pygments` importable. Output is written to
+`great-docs/_site/` (git-ignored, along with `.venv-docs/`). Narrative pages live in
+`user_guide/*.qmd`; CLI reference pages are auto-generated from `rsconnect.main`.
+
 ### Building Distribution
 ```bash
 # Build wheel distribution
@@ -184,7 +192,14 @@ The app mode determines how Connect runs the content. Manifests must specify the
 
 - Version is a static field in `pyproject.toml`, managed with `uv version`.
 - `main` carries a `.dev` version (e.g. `1.29.1.dev0`).
-- Update CHANGELOG.md before each release (even betas).
+- Release notes are now authored directly in the GitHub Release for each tag — that's the source
+  of truth for the published changelog (great-docs renders it into the docs changelog page).
+  `docs/CHANGELOG.md` only retains the `Unreleased` section for in-flight work; update it before
+  cutting a release, then clear it back to an empty `Unreleased` section afterward.
+- `scripts/backfill_release_notes.py` is the one-time migration that ported historical
+  `docs/CHANGELOG.md` entries into existing GitHub Releases. Run it dry-run first
+  (`uv run scripts/backfill_release_notes.py`) to review the plan, then `--apply` to write it.
+  It should not need to run again once history is migrated.
 - Cut a release: `uv version --bump stable`, commit, `git tag -a 1.2.3 -m 'Release 1.2.3'`, push the tag.
 - The `distributions` CI job asserts the tag matches the `pyproject.toml` version, then builds and publishes to PyPI.
 - After releasing, bump `main` back to the next `.dev` version with `uv version <next>.dev0`.

diff --git a/Justfile b/Justfile
@@ -42,17 +42,27 @@ install:
 version:
     uv version --short
 
-# Build the documentation site
+# Build the documentation site (great-docs / Quarto). Requires the Quarto CLI.
 docs:
-    VERSION=$(uv version --short) uv run --group docs mkdocs build
+    #!/usr/bin/env bash
+    set -euo pipefail
+    uv venv --python 3.12 --allow-existing .venv-docs
+    uv pip install --python .venv-docs --quiet great-docs pygments .
+    source .venv-docs/bin/activate
+    great-docs build
 
 # Serve the documentation with live reload
 docs-serve:
-    VERSION=$(uv version --short) uv run --group docs mkdocs serve
+    #!/usr/bin/env bash
+    set -euo pipefail
+    uv venv --python 3.12 --allow-existing .venv-docs
+    uv pip install --python .venv-docs --quiet great-docs pygments .
+    source .venv-docs/bin/activate
+    great-docs preview
 
 # Remove build/test artifacts
 clean:
-    rm -rf .coverage .pytest_cache build dist htmlcov rsconnect_python.egg-info rsconnect.egg-info site
+    rm -rf .coverage .pytest_cache build dist htmlcov rsconnect_python.egg-info rsconnect.egg-info great-docs
 
 # Remove local rsconnect store directories
 clean-stores:
@@ -74,8 +84,8 @@ dev-stop:
 
 # Sync latest docs to S3 (CI)
 sync-latest-docs-to-s3:
-    aws s3 sync --acl bucket-owner-full-control --cache-control max-age=0 site/ s3://rstudio-connect-downloads/connect/rsconnect-python/latest/docs/
+    aws s3 sync --acl bucket-owner-full-control --cache-control max-age=0 great-docs/_site/ s3://rstudio-connect-downloads/connect/rsconnect-python/latest/docs/
 
 # Promote docs in S3 (CI)
 promote-docs-in-s3:
-    aws s3 sync --delete --acl bucket-owner-full-control --cache-control max-age=300 site/ s3://docs.rstudio.com/rsconnect-python/
+    aws s3 sync --delete --acl bucket-owner-full-control --cache-control max-age=300 great-docs/_site/ s3://docs.rstudio.com/rsconnect-python/
diff --git a/assets/favicon.ico b/assets/favicon.ico
diff --git a/assets/iconPositConnect.svg b/assets/iconPositConnect.svg
diff --git a/docs/.gitignore b/docs/.gitignore
diff --git a/docs/commands/add.md b/docs/commands/add.md
diff --git a/docs/commands/bootstrap.md b/docs/commands/bootstrap.md
diff --git a/docs/commands/content.md b/docs/commands/content.md
diff --git a/docs/commands/deploy.md b/docs/commands/deploy.md
diff --git a/docs/commands/details.md b/docs/commands/details.md
diff --git a/docs/commands/environment.md b/docs/commands/environment.md
diff --git a/docs/commands/info.md b/docs/commands/info.md
diff --git a/docs/commands/integration.md b/docs/commands/integration.md
diff --git a/docs/commands/list.md b/docs/commands/list.md
diff --git a/docs/commands/login.md b/docs/commands/login.md
diff --git a/docs/commands/logout.md b/docs/commands/logout.md
diff --git a/docs/commands/quickstart.md b/docs/commands/quickstart.md
diff --git a/docs/commands/remove.md b/docs/commands/remove.md
diff --git a/docs/commands/system.md b/docs/commands/system.md
diff --git a/docs/commands/version.md b/docs/commands/version.md
diff --git a/docs/commands/write-manifest.md b/docs/commands/write-manifest.md