Repository Guidelines
Project Structure & Content Organization
- Root markdown pages (
index.md,about.md,research.md,news.md,software.md,people.md) render through_layouts/page.html. _posts/supports dated news items, whileNews/stores long-form PDFs; pair new PDFs with a short_postsentry so updates surface in the feed.peoplepages/holds individual bios thatpeople.mdaggregates; name filesFirst_Last.mdand store matching headshots inimages/People_Images/._data/people.ymldrives both the current roster and alumni listings—setstatus: current(default) orstatus: alumnito move cards between pages without editing markdown._data/alumni.ymlkeeps the historical grad/postdoc lists in sync with the new card layout; edit categories there when you need to add cohorts predating the data file._data/publications.ymland_data/lab_authors.ymlare the single source for publications and lab-member aliases; never hand-editpapers.mddirectly.- Styling lives in
_sass/partials with the compiled entry instyle.scss; shared HTML snippets belong in_includes/.
Build, Test, and Development Commands
bundle installinstalls the GitHub Pages plug-in set defined inGemfile; rerun when Ruby dependencies change.bundle exec jekyll serve --livereloadwatches markdown, HTML, and Sass changes and serves the site athttp://127.0.0.1:4000.bundle exec jekyll serve --drafts --futurepreviews embargoed announcements without publishing.bundle exec jekyll buildproduces the static_site/output and surfaces Liquid or front-matter errors earlier than GitHub Pages.bundle exec jekyll doctorreports broken links, missing permalinks, and configuration issues before you push.npm installpulls in tooling for image optimization; rerun only whenpackage.jsonchanges.python scripts/review_lab_authors.py > docs/lab_authors_review.txtaudits alias coverage and flags unmatched bolded authors before shipping publication updates.
Coding Style & Naming Conventions
- Markdown and HTML use two-space indentation; replace tabs when you encounter them and wrap lines at ~100 characters for readability.
- Keep YAML front matter minimal and ordered as
layout,title,permalink,categories,tags; example:--- layout: page title: "Lab Members" permalink: /people/ --- - Posts follow
YYYY-MM-DD-slug.md; prefer lowercase slugs with hyphens (2024-05-15-field-day.md). - Use descriptive alt text for images and compress photos below ~500 KB before committing.
Testing & Review Practices
- After content edits, load the affected page via
jekyll serveand check navigation links, anchors, and image paths. - When adding assets, verify they load under
_site/and that relative URLs match the deployed permalink structure. - Run
jekyll buildbefore opening a pull request; resolve Liquid warnings so GitHub Pages builds remain green. - For larger structural changes, capture a quick screenshot or screen recording to demonstrate the rendered result.
- Whenever you touch publication data, commit the regenerated
docs/lab_authors_review.txtso reviewers can see the before/after diff, and mention any helper scripts used.
Assets & Media
- Store new photography in
images/and keep widths ≤ 1800px to avoid layout shifts; runnpm run optimize:image -- path/to/image.jpgto recompress heavy assets withsharp. - Reference hero imagery from
images/Front_Page_Images/and people portraits fromimages/People_Images/; update_data/people.ymlwhen you add a new headshot. - Optimized derivatives that ship with the site live under
images/optimized/; regenerate them withpython scripts/build_optimized_images.pyafter adding or updating source photos. - Large data downloads, PDFs, or slide decks belong in
News/orPubs/; link to them from a short markdown summary so they surface in the news feed.
Publications Workflow
- Follow the schema in
docs/publications-data-spec.mdwhen editing_data/publications.yml; keep entries sorted by year and ensure each lab author carries the correctmember_idfrom_data/lab_authors.yml. - Add or update aliases in
_data/lab_authors.ymlwhenever a new spelling appears; the optionalscripts/build_lab_authors.pyhelper can reseed from roster data, but expected edits should be manual and reviewed. - Use the planned helper page at
/tools/bibtex-to-yaml(or the spec’s examples until that page lands) to convert BibTeX into the required YAML structure. - After making changes, run
python scripts/review_lab_authors.pyfor alias validation andbundle exec jekyll buildto confirm the Liquid templates still render.
Commit & Pull Request Guidelines
- Use concise, imperative commit messages (e.g.,
Add Deniz profileorRefresh maize phenotyping copy) and group related edits together. - Reference the touched page or asset in the first line of the PR description and include a local preview link (
http://127.0.0.1:4000/path/) plus screenshots when visual changes matter. - Call out new dependencies (Ruby or Node), data sources, or manual follow-up steps so downstream maintainers know what to expect.
