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
    permissions:
      contents: write
    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 paths and git add accordingly:

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

and

          git add [PATH TO SITE]/nav.yml [PATH TO SITE]/search.json

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 paths and for section in 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
    permissions:
      contents: write
    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 all sections
        run: |
          for section in docs legal learning reception sysadmin; 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"
          for section in [DIRECTORY2] [DIRECTORY2] [DIRECTORY3] [DIRECTORY4]; do
            git add $section/nav.yml $section/search.json
          done
          git diff --staged --quiet || git commit -m "Build: update nav.yml and search.json"
          git push

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!