diff --git a/docs/install.md b/docs/install.md
new file mode 100644
index 0000000..294ccf6
--- /dev/null
+++ b/docs/install.md
@@ -0,0 +1,161 @@
+# Setting up mdcms for your site
+
+This guide walks through installing mdcms, registering your site, and setting up automatic builds on GitHub so that `nav.yml` and `search.json` are always up to date when you push content.
+
+## 1. Install mdcms
+
+Choose one method:
+
+**Standalone binary (no Python required — recommended for most users)**
+
+Download the binary for your platform from the [latest release](https://github.com/kbenestad/mdcms/releases/latest):
+
+- **Linux:** `mdcms-linux-amd64` → move to `/usr/local/bin/mdcms` and `chmod +x`
+- **Linux (deb):** `mdcms_<version>_amd64.deb` → `sudo dpkg -i mdcms_<version>_amd64.deb`
+- **macOS:** `mdcms-macos-arm64` → move to `/usr/local/bin/mdcms` and `chmod +x`
+- **Windows:** `mdcms-windows-amd64.exe` → rename to `mdcms.exe` and place it somewhere on your PATH
+
+**Via pipx (Python users)**
+```bash
+pipx install mdcms
+```
+
+Verify the installation:
+```bash
+mdcms --version
+```
+
+---
+
+## 2. Register your site
+
+Navigate to your site directory (where `index.html` lives) and register it:
+
+```bash
+cd /path/to/your/site
+mdcms register mysite
+```
+
+Or pass the path explicitly:
+```bash
+mdcms register mysite /path/to/your/site
+```
+
+**If no mdcms site exists at that path**, mdcms will download the starter template from GitHub automatically — `index.html`, `config.yml`, `pages/`, `posts/`, and `assets/` will be created for you.
+
+**If a site already exists** (you cloned an existing mdcms repo), mdcms will detect the version marker in `config.yml` and register it as-is.
+
+---
+
+## 3. Edit your config
+
+Open `config.yml` in your site directory and set at minimum:
+
+```yaml
+sitename: Your Site Name
+navigation: topbar    # or: sidebar
+```
+
+---
+
+## 4. Build locally
+
+Run a build to generate `nav.yml` and `search.json` from your content:
+
+```bash
+mdcms build mysite
+```
+
+Check your site by starting a local server:
+```bash
+cd /path/to/your/site
+python3 -m http.server 8800
+```
+
+Then open `http://localhost:8800` in your browser.
+
+---
+
+## 5. Set up automatic builds on GitHub
+
+When you push new pages or posts to GitHub, you'll want `nav.yml` and `search.json` rebuilt automatically. This is done with a simple GitHub Actions workflow.
+
+### One-time GitHub setup
+
+1. Go to your site repository on GitHub
+2. **Settings → Actions → General**
+3. Under **Workflow permissions**, select **Read and write permissions**
+4. Click **Save**
+
+This allows the workflow to commit the rebuilt files back to your repository.
+
+### Add the workflow file
+
+Create `.github/workflows/build.yml` in your site repository with this content:
+
+```yaml
+name: Build
+
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - "pages/**"
+      - "posts/**"
+      - "config.yml"
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install mdcms
+        run: pip install mdcms
+
+      - name: Build
+        run: mdcms build
+
+      - name: Commit updated files
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git add nav.yml search.json
+          git diff --staged --quiet || git commit -m "Build: update nav.yml and search.json"
+          git push
+```
+
+Commit and push this file to your repository. From that point on, every push that touches `pages/`, `posts/`, or `config.yml` will automatically rebuild and commit `nav.yml` and `search.json`.
+
+> The workflow only commits if the files actually changed — `git diff --staged --quiet` skips the commit if nothing is different.
+
+---
+
+## Day-to-day workflow
+
+1. Write or edit a page in `pages/` or a post in `posts/`
+2. Commit and push to `main`
+3. GitHub Actions rebuilds `nav.yml` and `search.json` automatically (~30 seconds)
+4. Your deployed site picks up the changes immediately
+
+To build locally at any time (without pushing):
+```bash
+mdcms build mysite
+```
+
+---
+
+## Useful commands
+
+```bash
+mdcms view                  # list all registered sites
+mdcms view mysite           # show details for a site
+mdcms build mysite          # build nav.yml + search.json
+mdcms build --path .        # build from current directory (no registry needed)
+mdcms delete mysite         # remove a site from the local registry
+```