AGENTS.md

This repository is Jin Ma’s personal academic website, built on the Academic Pages Jekyll template. Your job is to help maintain and improve the site while preserving Jin’s voice, content accuracy, and the site’s existing structure.

Mission

• Keep the website accurate, professional, and easy to maintain.
• Prefer small, reversible edits over broad template churn.
• Treat factual content such as publications, affiliations, dates, and contact details as high-sensitivity content.
• When making assumptions, keep them conservative and call them out in your handoff.

Repository Shape

The site is a Jekyll repository with the usual Academic Pages layout.

• _config.yml: site-wide settings, author profile, collections, metadata, and build behavior.
• _data/navigation.yml: top navigation links and ordering.
• _pages/: main site pages such as About, Publications, Teaching, Service, and archive pages.
• _publications/: publication entries in Markdown.
• _teaching/: teaching entries in Markdown.
• _talks/: talk entries in Markdown.
• _portfolio/: portfolio-style entries, currently not emphasized in navigation.
• _posts/: blog posts.
• images/: profile photos, logos, favicons, and page imagery.
• assets/: downloadable files such as the CV, certificates, fonts, CSS, and JavaScript.
• _includes/, _layouts/, _sass/: shared theme templates and styling.
• markdown_generator/: helper scripts and notebooks for generating publication or talk Markdown from TSV or Bib inputs.

Site-Specific Notes

• The homepage content currently lives in _pages/about.md.
• The top navigation currently exposes About, Publications, Teaching, Service, and CV.
• The CV in navigation points to assets/cv.pdf.
• Certificates are already stored under assets/certificates/.
• Publication categories are configured in _config.yml as conferences, journals, workshops, and manuscripts.

Working Style

• Preserve the existing Academic Pages structure unless the task clearly calls for a deeper redesign.
• Keep copy concise, polished, and academic in tone.
• Do not invent publications, awards, affiliations, collaborators, links, or dates.
• Be careful with tense and chronology. This is a living academic profile, so outdated wording should be tightened when clearly supported by the repo.
• When editing content pages, prefer improving clarity and correctness over making the writing sound generic or over-produced.

Common Maintenance Tasks

Add or update a publication

1. Create or edit a Markdown file in _publications/.
2. Follow the repo’s existing naming patterns.
3. Include accurate front matter such as:
   • title
   • collection: publications
   • category
   • permalink when the local pattern uses one
   • date
   • venue
   • paperurl when available
   • citation
4. Keep the citation and venue text consistent with nearby entries.

Update the About page

• Edit _pages/about.md.
• Preserve first-person voice unless the page already uses another style.
• Pay attention to current status details such as year in program, institution, research interests, and internship availability.

Update navigation

• Edit _data/navigation.yml.
• Keep the top nav short; add links only when they clearly improve the site.
• For PDFs or external links, verify whether they should open in a new tab.

Update CV or certificates

• Place files in assets/ or assets/certificates/ as appropriate.
• Update the corresponding page or link after adding the file.
• Do not rename or move existing files unless the task requires it, because links may already point at them.

Adjust styling or templates

• Prefer the smallest possible change in _sass/, _includes/, or _layouts/.
• Respect the current visual language of Academic Pages.
• Avoid introducing new frontend tooling unless explicitly requested.

Validation Checklist

After making changes, verify what matters for the task:

• The edited Markdown front matter is valid.
• Internal links and asset paths still point to real files.
• Navigation changes match the intended labels and URLs.
• Dates, venues, names, and affiliations are consistent with the source material in the repo.
• If you modify shared layout or styling, check for obvious regressions in related pages.

Build and Local Preview

Useful commands for this repository:

• bundle install
• bundle exec jekyll serve -l -H localhost
• npm run build:js

Use npm run build:js when changing JavaScript under assets/js/. Jekyll config changes in _config.yml usually require restarting the local server.

Guardrails

• Do not remove user-authored content just to make the page shorter.
• Do not replace specific research descriptions with vague buzzwords.
• Do not change scholarly metadata unless the requested edit or repository evidence supports it.
• Flag factual ambiguities clearly when handing work back.

Default Posture

Assume future tasks in this repository are about maintaining Jin Ma’s personal website: updating content, refining copy, adding publications or certificates, adjusting navigation, and making small template or styling fixes that support the site without changing its identity.