mdcms/docs/github-workflow.md

# Automatic generation of `nav.yml` and `search.json`
This document covers

## Enable GitHub Actions
Before you can set up the automation workflow you need to ensure that it has write access:

1. Go to your repository on GitHub
2. Go to **Settings → Actions → General**
3. Scroll to **Workflow permissions**
4. Select **Read and write permissions**
5. Click **Save**

That's the only setup required. No secrets, no tokens, no third-party services.

## Enable workflow on single site
Create  `.github/workflows/build.yml` in your repository.

Assuming that the MD-CMS site is hosted at the repository root, you just need to paste the following into `build.yml`

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

If your MD-CMS instance is served from a directory within the repository (e.g., `docs`), you need to adjust the following paths accordingly:

```bash
    paths:
      - "[PATH TO SITE]/pages/**"
      - "[PATH TO SITE]/posts/**"
      - "[PATH TO SITE]/config.yml"
```

## Enable workflow on multisites
If you serve multiple MD-CMS instances from the same repository, you need to use a customised version of the script.

Create `.github/workflows/build.yml` in your repository.

Review the script below. It has been set up with four different directories (`DIRECTORY`, `DIRECTORY2`, `DIRECTORY3`, and `DIRECTORY4`). Change the paths to your own directories:

```bash
name: Build

on:
  push:
    branches:
      - main
    paths:
      - "[DIRECTORY1]/pages/**"
      - "[DIRECTORY1]/posts/**"
      - "[DIRECTORY1]/config.yml"
      - "[DIRECTORY2]/pages/**"
      - "[DIRECTORY2]/posts/**"
      - "[DIRECTORY2]/config.yml"
      - "[DIRECTORY3]/pages/**"
      - "[DIRECTORY3]/posts/**"
      - "[DIRECTORY3]/config.yml"
      - "[DIRECTORY4]/pages/**"
      - "[DIRECTORY4]/posts/**"
      - "[DIRECTORY4]/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 all sections
        run: |
          for section in [DIRECTORY1] [DIRECTORY2] [DIRECTORY3] [DIRECTORY4]; do
            cd $section
            mdcms build
            cd ..
          done

      - 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 docs/nav.yml docs/search.json legal/nav.yml legal/search.json learning/nav.yml learning/search.json sysadmin/nav.yml sysadmin/search.json
          git diff --staged --quiet || git commit -m "Build: update nav.yml and search.json"
          git push
```

**IMPORTANT:** Please take note of the `run` part, where each directory is listed:

```bash
for section in [DIRECTORY1] [DIRECTORY2] [DIRECTORY3] [DIRECTORY4]; do
```

This is different from the single site workflow. If you move from single site to multisite you need to updated the entire script -- it is not sufficient to just list the paths!