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:

• 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)

pipx install mdcms

Verify the installation:

mdcms --version

---

2. Register your site

Navigate to your site directory (where index.html lives) and register it:

cd /path/to/your/site
mdcms register mysite

Or pass the path explicitly:

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:

sitename: Your Site Name
navigation: topbar    # or: sidebar

---

4. Build locally

Run a build to generate nav.yml and search.json from your content:

mdcms build mysite

Check your site by starting a local server:

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:

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):

mdcms build mysite

---

Useful commands

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