CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

What this is

Source for the LaBGAS (Laboratory for Brain-Gut Axis Studies, KU Leuven / TARGID) website at https://labgas.github.io. A Jekyll site on the Minimal Mistakes theme, pulled in at build time via remote_theme: mmistakes/minimal-mistakes@4.27.1 — there is no committed theme copy and no local build step in CI. GitHub Pages builds and deploys on every push to main.

The custom skin is _sass/minimal-mistakes/skins/labgas, selected by minimal_mistakes_skin: "labgas" in _config.yml.

README.md is the authoritative guide and is written for two audiences in one file: lab members editing their own entry in the browser (no git, no install), and whoever maintains the site. Do not duplicate its content here — send people there.

The one rule that matters: generated vs editorial

Several data files are generated by scripts and must not be hand-edited; others are editorial and scripts must never touch them. Getting this backwards silently destroys work.

File Status Written by
_data/dependencies.yml generated scripts/refresh_dependencies.py, fetching from GitHub
_data/repos.yml — pushed, language generated scripts/refresh_repos.py, daily via Actions
_data/repos.yml — category, desc editorial, never touched by the script humans
_data/team.yml, projects.yml editorial, now the source of truth humans, in the browser
_data/publications.yml editorial, refreshable from PubMed scripts/enrich_publications.py

Scripts

  • refresh_repos.py — repo index (last-push date, language) from the GitHub API. Scheduled daily by .github/workflows/refresh-repo-index.yml, the only workflow here. Also reports what it cannot fix alone: a new org repository with no entry, an entry whose repo is gone, and any LaBGAScore script name cited in _docs//_pages/ that no longer exists upstream.
  • refresh_dependencies.py — fetches, does not build. See the ordering trap below.
  • enrich_publications.py — reads PubMed; unaffected by the KU Leuven site retirement.
  • fetch_team_bios.py, fetch_project_details.py — do not run these. They harvested gbiomed.kuleuven.be, which is being retired, and they rewrite bio/projects/detail wholesale while reporting per-person errors rather than failing outright. Against a dead source they would replace good content with nothing. Kept only as a record of provenance.
  • prepare_images.py — photo resizing/cropping for assets/images/.
  • validate_site.py — broken internal links, missing photos, malformed front matter. Necessary, not sufficient: a navigation chip pointing at a non-existent heading still renders and scrolls nowhere, and this does not catch it.

The ordering trap: dependency data

_data/dependencies.yml backs the Dependencies page. It cannot be built here — deriving it means parsing MATLAB source and resolving names against an index of installed toolboxes, which needs MATLAB, and GitHub Actions has none. So:

  1. Regenerate in the source repo with LaBGAScore_dep_report (LaBGAScore clean/).
  2. Commit and push that repo. refresh_dependencies.py reads the GitHub API, not your local clone — an uncommitted regeneration is invisible to it. This is the step people skip.
  3. Only then run python scripts/refresh_dependencies.py here.

Sources: LaBGAScore (root, main) and CANlab_help_examples (Second_level_analysis_template_scripts/, master — that folder’s 20 maintained scripts, not the ~113 present). The collected: date at the top of the file says when it last ran; if it predates a change in a source repo, the page is behind.

Content layout

  • _docs/00-setup.md … 11-dependencies.md — the numbered workflow documentation, one page per analysis stage. These are orientations that point at the repositories, not replacements for them; the authoritative guides are LaBGAS_fMRI_analysis_workflow.md and the READMEs in LaBGAScore and the CANlab_help_examples fork. Keep it that way — a duplicated procedure here is a procedure that will drift.
  • _pages/ — team, publications, research, tools, news, join, docs index, search, 404.
  • _posts/ — news items, YYYY-MM-DD-slug.md.
  • _data/navigation.yml — the nav. validate_site.py DOES check these against known permalinks and fails on an unknown one, so a broken nav link is caught; what it cannot catch is a link to a page that exists but to an anchor within it that does not.
  • _includes/, _sass/, assets/ — theme overrides, the labgas skin, images.

Relationship to the analysis repos

This site documents, and links to, the two MATLAB repositories it does not contain: LaBGAScore (/data/master_github_repos/LaBGAScore) and the LaBGAS fork of CANlab_help_examples. When a script is renamed or removed there, refresh_repos.py flags any citation of it in _docs//_pages/ — read the workflow run summary on the Actions tab rather than assuming the docs still resolve.

Conventions

  • Front matter on every page in _docs/ and _pages/: title, permalink, excerpt. Permalinks are stable URLs — renaming one breaks inbound links and the nav.
  • Prefer editing through the GitHub web UI for content changes; that is the workflow lab members are told to use, and it keeps this repo free of local build artefacts.
  • Preview locally with Jekyll only when changing layout or the skin; content changes do not need it. README.md has the commands.