Skip to content

Maintaining the Page

Jump to bottom
Alexander Refsum Jensenius edited this page Jun 21, 2026 · 3 revisions

Day-to-day maintenance runbook for mishmash.no.

Stack

Component Details
Generator Jekyll 4.x, Cayman remote theme
Source site/ (see _config.yml source: site)
Hosting GitHub Pages → mishmash.no
CI .github/workflows/web-tests.yml
Deploy .github/workflows/pages.yml on push to main
Nightly sync .github/workflows/enrich-directory-people.yml

Local setup

bundle install
bundle exec jekyll serve --livereload
# → http://127.0.0.1:4000

python3 -m venv venv && source venv/bin/activate
pip install -r scripts/requirements.txt

Content map

What Where
Front page site/index.md, site/no/index.md
About & organisation site/about/, site/no/about/
Work packages site/wp1/ … site/wp7/, site/internal/wp*/
Events site/_events/
News site/_news/
People site/_directory/people/ (117 entries)
Institutions site/_directory/institutions/ (36 entries)
Projects site/_directory/projects/ (22 entries)
Vacancies site/vacancies/index.md
Results data site/_data/mishmash_results.yml
WP leader list site/_data/work_packages.yml
UI strings site/_data/translations.yml
Layouts & CSS site/_layouts/, site/_includes/, site/assets/css/

Routine checklist

  1. Branch from main
  2. Edit the right collection or data file
  3. Build and validate locally
  4. Open PR, wait for Web Quality Checks
  5. Merge and confirm Pages deployment

Local quality checks

bundle exec jekyll build --trace
bundle exec htmlproofer ./_site --disable-external --no-enforce-https
python3 scripts/validate_directory.py

The directory validator prints errors (fix before merge) and warnings (deprecated roles, missing NVA/ORCID, path-style slug lists, WP leader role mismatches).

Optional accessibility (matches CI):

python3 -m http.server 4000 --directory _site &
npx --yes wait-on@7 http://127.0.0.1:4000/
npx --yes pa11y-ci@3 --config .pa11yci.json

After NVA sync

The nightly workflow (05:00 UTC) runs in order:

  1. enrich_directory_from_nva.py — refresh people from NVA/ORCID
  2. sync_results_from_nva.py — update mishmash_results.yml
  3. sync_directory_reciprocity.py — fix bidirectional cross-links
  4. merge_tags.py — apply config/tag_merge_map.yml
  5. validate_directory.py — sanity check
  6. Commit and push to main if anything changed

To run the same steps locally:

python3 scripts/enrich_directory_from_nva.py --discover-nva --discover-nva-loose --max-works 10
python3 scripts/sync_results_from_nva.py
python3 scripts/sync_directory_reciprocity.py
python3 scripts/merge_tags.py
python3 scripts/validate_directory.py

Audit tag variants before adding new merge mappings:

python3 scripts/merge_tags.py --report
python3 scripts/merge_tags.py --dry-run

Directory conventions

  • Use slug references in cross-link lists, not /people/… paths
  • Use canonical roles (Member, Work package leader, Board member, …) — see Directory
  • WP leaders must appear in both site/_data/work_packages.yml and person roles

Password-protected internal pages

Internal WP pages use internal_password_hash in root _config.yml.

Rotate password:

echo -n 'newpassword' | sha256sum

Replace the hash value and redeploy.

Common pitfalls

  • Use absolute asset paths (/assets/...) in shared includes
  • future: true publishes future-dated events immediately
  • Directory cross-links must be reciprocal — run validate_directory.py
  • Do not hand-edit mishmash_results.yml unless you know why; use sync_results_from_nva.py
  • Never commit config/nva-credentials*.json or venv/
  • NVA sync overwrites tags on profiles with urls.nva — tag merge runs nightly to normalise variants

More detail

Clone this wiki locally