diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
index 3141fe2..b3aa99d 100644
--- a/.github/workflows/docs.yml
+++ b/.github/workflows/docs.yml
@@ -5,7 +5,7 @@ on:
     branches: [master]
     paths:
       - "docs/**"
-      - "scripts/build-docs.sh"
+      - "Makefile"
       - ".github/workflows/docs.yml"
   workflow_dispatch:
 
@@ -28,7 +28,7 @@ jobs:
         run: sudo apt-get update && sudo apt-get install -y pandoc
 
       - name: Build site
-        run: ./scripts/build-docs.sh
+        run: make docs
 
       - uses: actions/upload-pages-artifact@v3
         with:
diff --git a/Makefile b/Makefile
index 33e1688..8b3fa41 100644
--- a/Makefile
+++ b/Makefile
@@ -11,6 +11,10 @@ SIDECAR_EMBED := internal/sidecar/assets/sidecar-all.jar
 SDK_AAR := sdk/android/build/outputs/aar/sdk-android-release.aar
 UATU_BIN := bin/uatu
 
+DOCS_SRC := $(shell find docs -type f -name '*.md' -not -path 'docs/_*')
+DOCS_OUT := $(patsubst docs/%.md,build/site/%.html,$(DOCS_SRC))
+DOCS_TEMPLATE := docs/_template/page.html
+
 .PHONY: bootstrap proto sidecar sdk-android sdk-android-publish uatu test test-go test-kotlin test-spec-api docs clean release-cli release-android-local release-npm-dry
 
 bootstrap:
@@ -52,8 +56,20 @@ test-kotlin:
 test-spec-api:
 	cd pkg/spec-api && npm test --silent
 
-docs:
-	./scripts/build-docs.sh
+docs: $(DOCS_OUT) build/site/_assets
+	@echo "built $(words $(DOCS_OUT)) pages to build/site"
+
+build/site/_assets: docs/_assets
+	@mkdir -p build/site
+	@rm -rf $@
+	@cp -R $< $@
+
+build/site/%.html: docs/%.md $(DOCS_TEMPLATE)
+	@mkdir -p $(dir $@)
+	@pandoc $< --from=gfm --to=html5 --standalone \
+	  --highlight-style=tango --template=$(DOCS_TEMPLATE) -o $@
+	@rel=$$(echo $(patsubst build/site/%,%,$@) | awk -F/ '{for(i=1;i<NF;i++)printf "../"}'); \
+	  sed -i.bak "s|__ROOT__|$$rel|g" $@ && rm $@.bak
 
 clean:
 	$(GO) clean
diff --git a/scripts/build-docs.sh b/scripts/build-docs.sh
deleted file mode 100755
index 37b807d..0000000
--- a/scripts/build-docs.sh
+++ /dev/null
@@ -1,52 +0,0 @@
-#!/usr/bin/env bash
-# Build the uatu docs site using pandoc.
-# Outputs static HTML to build/site/ ready for GitHub Pages.
-set -euo pipefail
-
-REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
-SRC="$REPO_ROOT/docs"
-OUT="$REPO_ROOT/build/site"
-TEMPLATE="$SRC/_template/page.html"
-ASSETS="$SRC/_assets"
-
-if ! command -v pandoc >/dev/null 2>&1; then
-  echo "pandoc not found on PATH. Install from https://pandoc.org/ or 'brew install pandoc'." >&2
-  exit 1
-fi
-
-rm -rf "$OUT"
-mkdir -p "$OUT/_assets"
-cp -R "$ASSETS"/. "$OUT/_assets/"
-
-build_one() {
-  local src="$1"
-  local rel="${src#$SRC/}"
-  local out="$OUT/${rel%.md}.html"
-  local dir; dir=$(dirname "$rel")
-
-  local root=""
-  if [ "$dir" != "." ]; then
-    local depth; depth=$(awk -F/ '{print NF}' <<< "$dir")
-    for ((i = 0; i < depth; i++)); do root="../$root"; done
-  fi
-
-  mkdir -p "$(dirname "$out")"
-  pandoc "$src" \
-    --from=gfm \
-    --to=html5 \
-    --standalone \
-    --highlight-style=tango \
-    --template="$TEMPLATE" \
-    -o "$out"
-
-  # macOS sed and GNU sed both accept `-i.bak + rm`; avoids `-i ''` portability issues.
-  sed -i.bak "s|__ROOT__|$root|g" "$out" && rm "$out.bak"
-}
-
-count=0
-while IFS= read -r -d '' f; do
-  build_one "$f"
-  count=$((count + 1))
-done < <(find "$SRC" -type f -name '*.md' -not -path "$SRC/_*" -print0)
-
-echo "built $count pages to $OUT"