academic-homepage-cv-sync

Imported from kw1jjang/academic-homepage-cv-sync (AGENTS.md). Install upstream with npx skills add kw1jjang/academic-homepage-cv-sync. Copyright stays with the author.

Project Notes

What this repo is

An academic homepage (Jekyll → GitHub Pages) and a LaTeX CV generated from one set of YAML files, so the two can't drift apart.

This repo ships with placeholder data. Until someone replaces it, every paper, talk, person, award, and photo belongs to "Bokdol Lee" — a Maltese from South Korea with three PhDs (Philosophy, Math, Kinesiology) who is now a student at the "International School for Elite Gifted Dogs", and who studies the purpose of life, the golden ratio of food/exercise/sleep, and the biomechanics of running and jumping. The persona is deliberately absurd so it can never be mistaken for a real user's data, and it exercises every supported field, so it doubles as documentation.

If the data still describes a dog, the user's first request is almost certainly "make this mine" — that means replacing the placeholder content, not appending to it. See Personalizing a fresh copy. Don't leave a half-Bokdol/half-user site behind.

Prerequisites

• Python 3.10+ with pyyaml (pip install pyyaml) — required.
• A TeX distribution with pdflatex — required only for the PDF. Without it, run python sync.py --no-compile and tell the user the PDF wasn't rebuilt; don't silently skip it.

Run sync.py from the repo root — its paths are relative.

CV ↔ Website Sync

Workflow

1. Edit YAML files in _data/ (add/update papers, talks, people, etc.)
2. Run python sync.py (or python sync.py --no-compile to skip the PDF)
3. Both index.md and cv/CV.tex are updated between SYNC: markers
4. The CV is compiled and copied to CV.pdf at the repo root
5. Commit the regenerated files — see GitHub Pages

sync.py exits non-zero and writes nothing when it finds a data problem, and names the offending entry. Trust it: if it exits 0 and prints Sync complete!, the CV really did compile. Never paper over a non-zero exit — read the message.

Generated vs. hand-written

Editing inside the markers is pointless — the next sync.py overwrites it. Edit the YAML instead. Deleting a marker is worse: sync.py now refuses to run rather than freezing that section silently, but you still have to restore the pair by hand.

When YAML can't express it

Not everything on the site or in the CV comes from _data/. Some things have no field, and some have no section. Pick the smallest tier that actually fits — and say which one you used, because tiers 2 and 3 change files the user may not expect you to touch.

Tier 1 — data (default). It's another paper, talk, person, award, grant, course, service entry, or job. Edit the YAML, run sync.py, done. If you find yourself reaching for tier 2 or 3 to add one of those, re-read the file's schema header first — the field usually exists.

Tier 2 — hand-written prose, edited directly in index.md / cv/CV.tex. Content that is specific to this one person and will never repeat belongs outside the SYNC markers, where sync.py will never touch it:

• Rewording the bio, hero header, email, or profile links (index.md)
• Research Interests, \name{}, \address{}, pdfauthor, the webpage/Scholar list after \begin{document} (cv/CV.tex)
• A whole new CV section. A \begin{rSection}{Patents}…\end{rSection} block placed outside every marker pair survives every future sync.py run. This is the escape hatch for one-off sections (patents, press, a mentoring statement, a teaching philosophy) that no YAML schema covers.
• Long-form-only material: wrap it in \extended{…} and it appears only when the preamble says \setboolean{extended}{true}

Inventing a new marker pair does nothing on its own — sync.py only fills the names listed in main() (PUBLICATIONS, TALKS, PEOPLE, AWARDS, SERVICE, GRANTS, TEACHING, BACKGROUND, TECH_REPORTS). Unrecognized markers are inert comments. That's tier 3.

Tier 3 — change sync.py itself. Correct when the shape of the output is wrong, not the content: a YAML field the generator ignores, a new publication type or talk subsection, a new person role, a new CV section that should be generated from data. Editing the generator is expected and fine — it is part of the template, not a black box. When you do:

1. Update the schema comment at the top of the affected _data/*.yml. That header is the documentation the next agent reads; a field that works but isn't documented there will be deleted by someone who thinks it's a typo.
2. Change both generators, or neither. Website output comes from gen_web_*, the CV from gen_cv_*. Adding a field to one and not the other recreates the exact drift this repo exists to prevent. If a field is deliberately one-sided (cv_only on awards, enrollment numbers on courses), say so in the schema comment.
3. Add a validate() check if a bad or missing value would degrade quietly — a dropped entry, an empty role, a ?'25 margin label. The rule here is that data mistakes fail loudly before anything is written, rather than shipping a half-wrong PDF. A silent fallback is a bug, not politeness.
4. Keep the config-block tuples in step with the branches you add: TALK_TOPICS, CV_AWARD_TYPES, PEOPLE_ROLES. PEOPLE_ROLES mirrors the branches in gen_web_people/gen_cv_people — adding a name there without adding the branch just moves the silent failure.
5. Re-run and check both outputs, not just the one you were asked about. git diff index.md cv/CV.tex and read it; for the PDF, pdftotext CV.pdf -.

A useful test for tier 2 vs. tier 3: will this recur? "Add a patents section listing my two patents" is prose — tier 2. "Every patent should render with its number and filing date" is a schema — tier 3, with a patents.yml, a gen_web_patents/gen_cv_patents pair, a marker pair in both files, and a replace_section call for each.

Never edit index.md or cv/CV.tex inside the markers, in any tier. If the generated text is wrong, the generator or the data is wrong.

Data files (_data/)

Each YAML file begins with a comment documenting its full schema — read it before adding an entry. It gives the accepted values, not just the field names.

Configuration block in sync.py

Lines ~20–48, and it needs editing per user — it is not just a script to invoke:

Common tasks

• Add a paper: add to publications.yml (selected: true to feature it), run python sync.py
• Add a talk: add to talks.yml with a topic from TALK_TOPICS, run python sync.py
• Add a tech report: add to tech_reports.yml, run python sync.py
• Add a lab member: add to people.yml (current members before alumni) with a photo in assets/images/members/, run python sync.py

Personalizing a fresh copy

All seven of these still say "Bokdol Lee" in a fresh clone:

1. _config.yml — title, description, url, baseurl (see below)
2. index.md — the front-matter description:, the hero header above the first SYNC marker, and the ## Bokdol Lab @ … heading. Keep the {: .people-list} line under that heading — it's the styling hook
3. cv/CV.tex — pdfauthor, \name{}, \address{}, and the webpage/Scholar list right after \begin{document}
4. sync.py — the configuration block above, PI_NAME first
5. _data/*.yml — replace the placeholder entries
6. assets/images/profile.png and assets/images/members/placeholder-*.png
7. Run python sync.py, then commit

CV

• Source is cv/CV.tex; sync.py compiles it with pdflatex (two passes)
• Both CV.pdf (root, published) and cv/CV.pdf are tracked — commit both
• \setboolean{extended}{true} in the preamble includes the \extended{…} sections (media coverage, detailed grants) for a long-form CV
• Paper titles, author lists, people names, and grant titles reach the CV as raw LaTeX — deliberately, so a title can contain math like $O(n^2)$. That means a literal %, #, _, $, or & in one of those fields must be escaped in the YAML (50\%, Chain\_of\_Thought). The build fails loudly rather than shipping a stale PDF, but the fix is yours.
• Do not pre-escape & in venue, venue_full, venue_tex, course, institution, company, or award fields — sync.py escapes those itself, so writing \& there double-escapes and breaks the build

Website

• Jekyll site using the Just-the-Docs theme, vendored in-repo (_layouts/, _includes/, _sass/). There is no theme gem and no remote_theme — don't add one, and don't assume upstream just-the-docs docs apply to files here.
• Single-page layout: all content in index.md, sidebar hidden via CSS
• Custom JS is inlined in index.md (theme doesn't auto-load _includes/js/custom.js)
• Custom styles in _sass/custom/custom.scss
• bundle exec jekyll serve to preview locally (optional; needs Ruby)
• Known cosmetic gap: website talks are grouped by year but not sorted within a year — they appear in file order. Reorder talks.yml, not index.md

How this repo becomes a live site (GitHub Pages)

This is a classic Pages site: GitHub runs Jekyll server-side on push.

_data/*.yml ──► python sync.py ──► index.md + cv/CV.tex + CV.pdf   [locally, by you]
                                          │
                                     git push
                                          ▼
                              GitHub runs jekyll build ──► live site

• sync.py never runs on GitHub. Its output (index.md, cv/CV.tex, CV.pdf, cv/CV.pdf) is committed generated code. After editing _data/, always run sync.py and commit the regenerated files, or the live site won't change.
• GitHub ignores the Gemfile and builds with its own pinned toolchain. The Gemfile/Dockerfile exist only for local preview. Any plugin added to _config.yml must be on the GitHub Pages allowlist — currently only jekyll-seo-tag is used.
• baseurl in _config.yml must match where the site is served. "" for a user site (<user>.github.io), "/<repo>" for a project site (<user>.github.io/<repo>). Asset URLs go through Jekyll's relative_url filter, so baseurl is the only knob — but a wrong value silently 404s every stylesheet, icon font, and photo while the page itself still loads.
• Never hard-code root-absolute asset paths (/assets/...) in index.md, _includes/, or in strings emitted by sync.py. Pipe them through relative_url instead (see the member-icon images in sync.py for the pattern). A local build with an empty baseurl will not catch this mistake.
• _config.yml's exclude: list keeps repo-only files (sync.py, cv/, AGENTS.md, Docker files, …) out of the published site. CV.pdf at the repo root is published; cv/ (the LaTeX source) is not.
• Build failures appear in the repo's Actions tab and are emailed by GitHub; there is no workflow file to inspect in this repo.