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

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:

    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:

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:

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!