From 8bff1c7a01a0c9b873121317de1cb70ffb4ee4c1 Mon Sep 17 00:00:00 2001
From: Dylan Gormley <dylan.j.gormley@gmail.com>
Date: Mon, 28 Sep 2026 23:10:15 -0500
Subject: [PATCH] docs: restore standalone GitHub Pages build

---
 README.md        | 16 ++++++++++++++++
 docs/commands.md |  2 +-
 docs/index.md    |  2 +-
 mkdocs-site.yml  | 37 +++++++++++++++++++++++++++++++++++++
 4 files changed, 55 insertions(+), 2 deletions(-)
 create mode 100644 mkdocs-site.yml

diff --git a/README.md b/README.md
index 75ff3e9..c46d74b 100644
--- a/README.md
+++ b/README.md
@@ -85,3 +85,19 @@ datatrail config init --site chime
 # Ensure valid CADC Certificate exists
 cadc-get-cert -u [username]
 ```
+
+## Building the documentation
+
+From the repository root, install the locked documentation dependencies with
+[uv](https://docs.astral.sh/uv/), then build the standalone public site:
+
+```shell
+uv sync --locked --group docs
+uv run --no-sync mkdocs build --strict --config-file mkdocs-site.yml
+```
+
+The site is written to `site/`. To preview it locally, run
+`uv run --no-sync mkdocs serve --config-file mkdocs-site.yml`.
+The installed checkout supplies the generated CLI reference. `mkdocs-site.yml`
+adds the public site's theme and rendering extensions while inheriting the
+navigation from `mkdocs.yml`, which remains the handbook configuration.
diff --git a/docs/commands.md b/docs/commands.md
index 35edcb4..9104b3d 100644
--- a/docs/commands.md
+++ b/docs/commands.md
@@ -27,4 +27,4 @@ The commands available to you are:
 - `version`: List the CLI and server version.
 
 Detailed information on all of the CLI commands can be found on the
-[Reference](cli) page.
+[Reference](cli.md) page.
diff --git a/docs/index.md b/docs/index.md
index e1f8d5e..018a52a 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -9,7 +9,7 @@ comments: true
 <h1 align="center">Datatrail CLI</h1>
 
 <h4 align="center">
-  <a src="https://github.com/CHIMEFRB/datatrail-cli/install/">Install</a>
+  <a href="install/">Install</a>
   ·
   <a href="https://chimefrb.github.io/datatrail-cli/">Docs</a>
 </h4>
diff --git a/mkdocs-site.yml b/mkdocs-site.yml
new file mode 100644
index 0000000..52672a9
--- /dev/null
+++ b/mkdocs-site.yml
@@ -0,0 +1,37 @@
+# Standalone public site; mkdocs.yml remains the handbook navigation source.
+INHERIT: mkdocs.yml
+
+site_name: Datatrail CLI
+site_url: https://chimefrb.github.io/datatrail-cli/
+repo_name: CHIMEFRB/datatrail-cli
+repo_url: https://github.com/CHIMEFRB/datatrail-cli
+
+theme:
+  name: material
+  palette:
+    scheme: slate
+    primary: deep purple
+    accent: yellow
+  features:
+    - navigation.expand
+    - navigation.top
+    - navigation.tabs
+    - navigation.tabs.sticky
+    - content.code.copy
+
+plugins:
+  - search
+  - termynal
+
+markdown_extensions:
+  - admonition
+  - attr_list
+  - mkdocs-click
+  - toc:
+      permalink: true
+  - pymdownx.details
+  - pymdownx.highlight
+  - pymdownx.inlinehilite
+  - pymdownx.superfences
+  - pymdownx.tabbed:
+      alternate_style: true