mdcms/docs/install.md

# 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 pip (from GitHub)**
```bash
pip install git+https://github.com/kbenestad/mdcms.git
```

**Via pipx (from GitHub)**
```bash
pipx install git+https://github.com/kbenestad/mdcms.git
```

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"

env:
  FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true

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 git+https://github.com/kbenestad/mdcms.git

      - 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
```