mirror of
https://github.com/kbenestad/mdcms.git
synced 2026-06-18 15:24:32 +00:00
138 lines
3.7 KiB
Markdown
138 lines
3.7 KiB
Markdown
# 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
|
|
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:
|
|
|
|
```bash
|
|
paths:
|
|
- "[PATH TO SITE]/pages/**"
|
|
- "[PATH TO SITE]/posts/**"
|
|
- "[PATH TO SITE]/config.yml"
|
|
```
|
|
|
|
and
|
|
|
|
```bash
|
|
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:
|
|
|
|
```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
|
|
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!
|