image structure

Author: ttuff

.github/workflows/gh-pages.yml

@@ -31,6 +31,9 @@ jobs:
       - name: Install Python dependencies
         run: pip install -r requirements.txt
 
+      - name: Generate image slot references
+        run: python scripts/generate_image_slots.py
+
       - name: Generate site health report
         run: python scripts/site_health.py
 

PROMPT_ACTION_LOG.md

@@ -32,3 +32,38 @@ Verification
 Open questions and follow-up
 
 * Decide later whether to keep scripts/check_template.py as a local-only helper or retire it.
+
+2026-04-23
+
+Prompt
+
+User asked: "Reorganize the Working Group OASIS homepage around the repository plus website workflow, clarify how the repo is organized, and add a simple image-slot system for homepage visuals."
+
+Files and folders inspected
+
+* docs/
+* docs/stylesheets/
+* mkdocs.yml
+* README.md
+* scripts/
+* .github/workflows/
+
+Actions taken
+
+* Rewrote the homepage to explain the repository side, website side, and GitHub bridge with a clearer start path.
+* Added homepage edit affordances and enabled MkDocs Material edit actions.
+* Clarified the repository structure in the root README and MkDocs comments.
+* Added semantic image slot folders, slot documentation, and a pre-build generator for stable image references.
+* Extended the site health report and GitHub Pages workflow to cover the new image-slot system.
+
+Verification
+
+* Ran `python3 scripts/generate_image_slots.py`.
+* Ran `python3 scripts/site_health.py`.
+* Ran `python3 scripts/check_template.py`.
+* Ran `.venv/bin/mkdocs build --strict --clean`.
+* Verified the built homepage in a local browser against `site/index.html`, including the visible edit affordance and GitHub edit-mode URL for `docs/index.md`.
+
+Open questions and follow-up
+
+* Consider whether future template iterations should add dedicated README files for scientific working folders once those folders become part of the base template.

README.md

@@ -2,16 +2,70 @@
 
 This repository is a template for ESIIL Working Groups.
 
-The website is built from the docs/ folder using MkDocs.
+This template is designed as one connected system:
+
+- The repository is where the science happens.
+- The website is where the science is shared.
+- GitHub connects them through commits, version history, and publishing.
+
+## How this repository is organized
+
+The repository has two connected layers. Top-level files configure the project and its automation. The `docs/` folder contains the website content. `mkdocs.yml` tells MkDocs how to turn that content into the public site. Analysis folders hold the working scientific materials that generate the results shown on the website.
+
+```text
+.
+├── README.md              # Repository overview and setup notes
+├── mkdocs.yml             # Website navigation, theme, plugins, and edit links
+├── docs/                  # Markdown source for the public website
+├── scripts/               # Build helpers and site health checks
+├── templates/             # Reusable meeting-note templates
+├── containers/            # Optional runtime and environment setup
+└── other working folders  # Add data, notebooks, scripts, workflows, outputs, or figures here as the group's science grows
+```
+
+Use these rules of thumb when deciding where to put something:
+
+- Top-level files and folders are for project configuration, automation, contribution guidance, licensing, environment setup, and repo-wide metadata.
+- `docs/` is for public website pages and assets. Markdown files here become website pages through MkDocs.
+- `mkdocs.yml` controls how the website is rendered, including navigation, theme settings, plugins, and GitHub edit links.
+- Scientific working materials belong in working folders such as data, notebooks, scripts, workflows, outputs, and figure directories.
+
+## Common places to edit
+
+- `docs/index.md` is the homepage for the public site.
+- `docs/work-plan.md` is where the group can track milestones, meetings, and active work.
+- `docs/resources.md` is where datasets, references, and code links can be collected.
+- `docs/community-care.md` is where collaboration expectations and group care guidance live.
+- `docs/assets/images/slots/` contains named image slots for the homepage and other shared visuals.
 
 ## Preview locally
 
-pip install mkdocs-material  
+```bash
+pip install -r requirements.txt
+python scripts/generate_image_slots.py
+python scripts/site_health.py
 mkdocs serve
+```
 
 ## Build site
 
+```bash
+python scripts/generate_image_slots.py
+python scripts/site_health.py
 mkdocs build --strict --clean
+```
+
+## Swapping homepage images
+
+The homepage uses semantic image slots so Working Group members do not need to edit Markdown links every time an image changes.
+
+1. Open the relevant folder in `docs/assets/images/slots/`.
+2. Delete the old image file.
+3. Add one new `.png`, `.jpg`, `.jpeg`, `.webp`, or `.svg` file.
+4. Run `python scripts/generate_image_slots.py`.
+5. Commit the image change and the regenerated slot references.
+
+If a slot folder contains multiple images, the generator prefers the first non-placeholder file alphabetically and the site health report will warn you to clean it up.
 
 ## Site Health
 

docs/_generated/image_slots.md

@@ -0,0 +1,8 @@
+<!-- This file is generated by scripts/generate_image_slots.py. -->
+
+[slot-hero]: assets/images/slots/hero/placeholder.svg
+[slot-repository-side]: assets/images/slots/repository-side/placeholder.svg
+[slot-website-side]: assets/images/slots/website-side/placeholder.svg
+[slot-analysis]: assets/images/slots/analysis/placeholder.svg
+[slot-data]: assets/images/slots/data/placeholder.svg
+[slot-outputs]: assets/images/slots/outputs/placeholder.svg

docs/_site_health.md

@@ -4,8 +4,6 @@ Site Health
 
 ⚠ Placeholder detected: generic placeholder link in docs/index.md
 
-⚠ Placeholder detected: homepage description placeholder in docs/index.md
-
 ⚠ Placeholder detected: people table placeholder in docs/index.md
 
 ⚠ Placeholder detected: generic placeholder link in docs/resources.md

docs/assets/images/slots/README.md

@@ -0,0 +1,15 @@
+# Image Slots
+
+This folder contains semantic image slots for the website.
+
+Each subfolder controls one purpose-driven image location, such as the homepage hero image or the repository-side illustration.
+
+To swap an image:
+
+1. Open the relevant slot folder.
+2. Delete the old image.
+3. Add one new `.png`, `.jpg`, `.jpeg`, `.webp`, or `.svg` file.
+4. Run `python scripts/generate_image_slots.py`.
+5. Commit the image and the regenerated slot references.
+
+Use one image per slot folder. If multiple images are present, the site generator prefers the first non-placeholder file alphabetically and the site health report will warn you to clean the folder up.

docs/assets/images/slots/analysis/README.md

@@ -0,0 +1,7 @@
+# Analysis Image Slot
+
+This folder is reserved for an analysis-related image used elsewhere on the site.
+
+To change it, delete the current image and add one new `.png`, `.jpg`, `.jpeg`, `.webp`, or `.svg` file. The website will use the image in this folder automatically if a page references the `analysis` slot.
+
+Use one image only. Figures showing models, workflows, notebooks, or code snapshots work well here.

docs/assets/images/slots/analysis/placeholder.svg

@@ -0,0 +1,7 @@
+# Data Image Slot
+
+This folder is reserved for a data-related image used elsewhere on the site.
+
+To change it, delete the current image and add one new `.png`, `.jpg`, `.jpeg`, `.webp`, or `.svg` file. The website will use the image in this folder automatically if a page references the `data` slot.
+
+Use one image only. Screenshots of data catalogs, field sites, sample records, or metadata views work well here.