CLAUDE.md — tyrealq.github.io

Owner & Site Identity

• Q = Dr. Yizhou (Tyreal) Qian 钱亦舟, Assistant Professor at Indiana University Bloomington
• Site title: “Dr. Q”
• Author display: “Yizhou (Tyreal) Qian” with Chinese name 钱亦舟
• Email: tyqian@iu.edu
• Research focus: sport management, esports, NLP/AI, computer vision, datasets, agent skills
• Academic profiles: Google Scholar, ORCID, GitHub, YouTube, LinkedIn
• Avatar: images/Ty.png

Build & Serve

# Local development (requires Ruby + Bundler)
bundle install
bundle exec jekyll serve -l -H localhost

# Docker alternative
docker build -t academic-pages .
docker run -p 4000:4000 -v $(pwd):/usr/src/app academic-pages

# Rebuild JS assets (requires Node.js)
npm install
npm run build:js        # one-time bundle
npm run watch:js        # watch mode

Site serves at http://localhost:4000. Changes to _config.yml require a server restart.

The system Ruby (2.6) cannot resolve the github-pages gem (it needs Ruby 3); install Homebrew Ruby first (brew install ruby, put /opt/homebrew/opt/ruby/bin first on PATH, then bundle install). A production check is JEKYLL_ENV=production bundle exec jekyll build; the production config sets the absolute site url, so a local build loads the live stylesheet unless url is overridden.

Homebrew now installs Ruby 4, and github-pages still pins Jekyll 3.9 and Liquid 4.0.3, so a local build needs two workarounds kept outside the repo: a separate Gemfile (selected with BUNDLE_GEMFILE) that runs eval_gemfile on the repo Gemfile and adds csv, base64, bigdecimal, logger, and ostruct, which Ruby 4 no longer bundles; and a small Ruby file loaded through RUBYOPT=-r<path> that defines Object#tainted?, taint, and untaint as no-ops, since Liquid 4.0.3 calls methods Ruby removed. Never commit either to the repo; GitHub Pages builds with its own Ruby.

Architecture

Collections (defined in _config.yml)

Key Directories

• .claude/ — Claude Code project config: settings.json (SessionStart hook), hooks/session-note.sh (session dashboard)
• _pages/ — Static pages (about, cv, archive pages); explicitly included via _config.yml
• _includes/ — Reusable HTML partials (author profile, header, footer)
• _layouts/ — Page templates (single, talk, etc.)
• _sass/ — SCSS stylesheets (compressed output); _dark.scss holds the dark-theme override layer
• _data/navigation.yml — Header navigation links and order
• _drafts/ — Unpublished content
• images/ — Site images
• files/ — Downloadable files (PDFs), self-hosted standalone HTML pages (SMQ_timeline.html and SMQ_cited_works.html, each iframed from its own talk entry), and files/greeting/ (the rendered homepage greeting video: greeting.mp4, greeting.webm, poster.jpg, plus portrait.jpg for the HTML end card) and files/journey/ (the rendered career-path video with its music, embedded with sound by _portfolio/01_Journey.md: journey.mp4, journey.webm, poster.jpg; source in ~/Dropbox/1CV/Brands_Qian/animation/journey/, never edited here)
• assets/js/ — JavaScript; main.min.js is the bundled output

Dark Mode

The site supports a light/dark theme toggle (sun/moon button in the masthead, right side):

• _includes/head.html — inline script applies the saved theme before paint; light is the default, and data-theme="dark" is set on <html> only when the visitor previously chose dark
• _includes/masthead.html — #theme-toggle button
• _includes/scripts.html — inline handler flips data-theme, persists the choice to localStorage (theme), and swaps the icon
• _sass/_dark.scss — [data-theme="dark"] override layer, imported last in assets/css/main.scss; it also recolors the sidebar GitHub icon to the dark text color, since GitHub’s near-black brand color (#171516) disappears on the dark background

Greeting Animation

The homepage plays a short code-rendered greeting video (about 30 s, muted, 16:9) directly under the welcome paragraph, then shows an HTML end card with the real links. It follows the same pattern as the theme toggle: markup in an include, a guarded vanilla IIFE in _includes/scripts.html, an SCSS partial, no build step. Both renders carry BT.709 limited-range color tags (--color-space bt709) so the stage matches the HTML end card in every browser.

• Source: ~/Dropbox/1CV/Brands_Qian/animation/greeting/ (a Remotion project documented in its README.md). The site repo holds only the rendered outputs and the embed. Never edit the video here.
• Outputs: files/greeting/greeting.mp4, files/greeting/greeting.webm, files/greeting/poster.jpg (poster is the 7.5 s frame, since nothing has entered at frame 0); files/greeting/portrait.jpg is the square studio portrait used by the HTML end card
• _includes/greeting.html: .greeting wrapper: a 16:9 box (aspect-ratio: 16 / 9, so the page never shifts) holding the <video> (MP4 then WebM sources; H.264 first because every browser decodes it in hardware, muted playsinline preload="metadata", no autoplay attribute) and the replay button, plus the end card .greeting__end (white card, portrait with crimson ring, Dr. Q and 钱亦舟, crimson rule, affiliation caption, Explore., two rows of pill links: CV, Research Highlights, Featured Talks, Fun Stuff; GitHub, Hugging Face, OSF, YouTube). about.md places it with `<div class="greeting">

</div> `.

• _includes/scripts.html: the IIFE exits when .greeting is absent. On every page load it calls video.play() (muted autoplay; the user wants it to play on each visit, so there is no once-per-session flag). If prefers-reduced-motion: reduce matches, or play() rejects, it shows the end card and does not play. On ended it reveals the end card with a short fade (class greeting--ended). The replay button hides the card, seeks to 0, and plays again. The code carries no explanatory comments; any comment added to this script must be /* */, because production compress_html breaks // comments.
• _sass/_greeting.scss: imported in assets/css/main.scss immediately before _dark.scss. At 600 px and wider the end card is an overlay inside the box, sized in container query units (cqw) from the 1920 px frame with the frame’s own margins (5 % top and bottom, 10 % left and right) and the corner Dr. Q mark; below 600 px it renders as a block directly under the video with fixed sizes and wrapping pills, and only the replay control stays in the box corner. _dark.scss recolors only the frame border; the video and end card keep their light colors by design.
• Update: re-render in the source project (npx remotion render there), then copy the three files into files/greeting/. Edit copy, timing, or links in the source project’s story.ts; the end-card link labels and URLs in greeting.html must match its last take.

Content Generation Pipeline

markdown_generator/ contains Python scripts and Jupyter notebooks that convert TSV data into Markdown collection files:

• publications.tsv → publications.py / publications.ipynb → _publications/*.md
• talks.tsv → talks.py / talks.ipynb → _talks/*.md
• PubsFromBib.ipynb / OrcidToBib.ipynb — Import from BibTeX/ORCID

Session Dashboard

.claude/hooks/session-note.sh runs at session start (registered in .claude/settings.json) and prints a summary of the site’s work streams: the last three commits and how long ago they were, uncommitted or unpushed changes (deploy status), content counts with the most recent date per collection, any future-dated items that Jekyll will not render yet, drafts, and project skills. Every figure is computed from the folder and git history at run time, so the dashboard never needs editing. Publication dates in “Month YYYY” format are normalized to ISO for sorting and comparison.

Site Navigation

Header links (defined in _data/navigation.yml):

Homepage: _pages/about.md (permalink: /)

The homepage, CV, Resources & Publications, and Outreach & Presentations pages all use the default single layout (no layout: line), so they share one design and each ## section heading gets the layout’s underline. Sections are separated by that underline alone; do not add --- dividers between them. _sass/_archive.scss removes the right-side padding of .list__item inside .page__content, so the publication and talk listings use the full column. Published Research lists journal articles and then conference papers (the order of publication_category in _config.yml) with no category headings. The talks page has two ## sections written into the page, Public Outreach and then Academic Presentations, each listing the talks with that category newest first.

Content Inventory

Publications (_publications/) — 10 files, ALL ACTIVE

Publication categories in _config.yml: Books, Journal Articles (manuscripts), Conference Papers (conferences).

Talks (_talks/) — 18 files, ALL ACTIVE

Each talk’s category front matter places it in one of the two sections of the talks page: outreach (Public Outreach) or presentations (Academic Presentations).

Public Outreach (13): podcast episodes (YouTube video discussions of Q’s research), QLearning tutorials, and self-hosted interactive figures.

Podcast episodes (7):

QLearning tutorials and interactive figures (6):

Academic Presentations (5): conference presentations, workshops, and symposium talks.

Portfolio (_portfolio/) — 8 files, ALL ACTIVE

AI-generated art and creative projects. The gallery (_pages/portfolio.html) lists entries in filename order, so each file starts with a two-digit number that sets its place; the web address comes from each file’s permalink, so renumbering does not change it.

Teaching (_teaching/) — 2 files, PLACEHOLDER (theme template)

Blog Posts (_posts/) — 5 files, PLACEHOLDER (theme template)

Pages (_pages/) — 18 files

Active pages:

| File | Permalink | Purpose | |—|—|—| | about.md | / | Homepage — bio, greeting animation (`<div class="greeting">

Dr. Q 钱亦舟

School of Public Health · Indiana University Bloomington Explore.

</div> ` under the welcome paragraph), “Join Our Team” PhD recruiting section (lab members, a paragraph on assistantship funding, teaching, resources, and publication expectations, and five questions for prospective students), visitor map under its own “Visitors Around the World” header (MapMyVisitors script at the end of the page) | | cv.md | /cv/ | Academic CV — appointments, education, work in progress, skills | | publications.html | /publications/ | “Resources & Publications” page (menu label: Research Highlights): an “Open Resources” section (five research areas, each technique or task linked inline to a research resource: a GitHub repo, a Hugging Face dataset, a paper, or a q-skills subskill; teaching materials are linked only where the text is about teaching; written in markdown inside a Liquid capture passed through markdownify), then “Published Research” (Google Scholar link and the listing) | | talks.html | /talks/ | “Outreach & Presentations” page (menu label: Featured Talks): “Public Outreach” and “Academic Presentations” sections | | portfolio.html | /portfolio/ | Portfolio gallery | | teaching.html | /teaching/ | Teaching listing | | 404.md | /404.html | Custom 404 page | | sitemap.md | /sitemap/ | HTML sitemap | | terms.md | /terms/ | Terms and privacy |

Archive generators:

Template / unused:

Images Directory

All images live in images/. Grouped by purpose:

Research infographics (used in publications):

• B50.png, B50_INFO.jpeg — Break 50 / Trump golf
• WG_INFO.jpeg — Winter Olympics / Games
• ESPORTS_INFO.jpg — Esports spectator motivation
• ESPORTS_GAMIFICATION_INFO.jpg — Gamification in esports
• EXP_INFO.jpeg — Stadium experience / LLM
• TS_INFO.png — Taylor Swift & NFL
• TWITCH_SPORTS_INFO.jpg — Twitch co-streaming

Teaching demo thumbnails:

• LLM101.png — LLM 101 tutorial
• NLP4ALL.png — NLP4ALL workshop
• QLearning101.png — QLearning series

Portfolio / portraits:

• Q.png — Tyreal football portrait
• Tracy_cute1.png — Tracy portrait
• XL.png — Xiaoli portrait
• SP8.png — Siping portrait
• Ty_Q_EN.jpeg, Ty_Q_CN.jpeg — Stickers (English/Chinese)

Brand logos:

• Logo_Q.png, Logo_Q_B.png, Logo_Q_Horizontal.png, Logo_Q_OB.png, Logo_Q_SB.png, Logo_Q_W.png

City weather visualizations:

• SM_FJ.jpeg (Sanming), XM_FJ.jpeg (Xiamen), SH.jpeg (Shanghai), Athens_GA.jpeg, BR_LA.jpeg (Baton Rouge), Bloomington_IN.jpeg

Site assets (theme defaults):

• Ty.png — Author avatar (sidebar)
• bio-photo.jpg, bio-photo-2.jpg, profile.jpg — Stock/theme bios
• site-logo.png, homepage.png — Site branding
• favicon.ico, safari-pinned-tab.svg, browserconfig.xml, manifest.json, mstile-*.png — Favicon/PWA
• 500x300.png — Default teaser
• Other theme stock images: foo-bar-identity*.jpg, editing-talk.png, paragraph-*.png, image-alignment-*.jpg, 3953273590_704e3899d5_m.jpg

Configuration Files

Content Workflow

Add a new publication:

1. Create _publications/<slug>.md with YAML front matter: title, collection: publications, category (manuscripts/conferences/books), permalink, excerpt, date, venue, optionally paperurl
2. Add an infographic image to images/ if needed, reference with <img src='/images/...'>
3. Or: add a row to markdown_generator/publications.tsv and run publications.py

Add a new talk (podcast, teaching demo, or interactive demo):

1. Create _talks/<Podcast_or_Teaching>_<slug>.md with front matter: title, collection: talks, category (outreach or presentations; a talk without it does not appear on the talks page), excerpt, type: "Talk", permalink, date
2. Embed YouTube iframe or Canva slides in the body
3. For a self-hosted interactive page: put the self-contained HTML in files/ with no front matter (Jekyll copies it verbatim; front matter would trigger Liquid and layouts), then embed it with a fixed-height iframe (height: 85vh; min-height: 640px) plus an “open in a new tab” link. fitvids only wraps YouTube/Vimeo, so the iframe carries its own sizing. The SMQ pages are copied from the SMA25 project (~/Dropbox/2026 Fall/SMA25, manuscript/figures/<name>/) with the outreach rewording recorded in that project’s outreach/README.md; edit them there and re-copy, never here

Add a portfolio item:

1. Create _portfolio/<slug>.md with front matter: title, excerpt (include thumbnail img tag), collection: portfolio, permalink
2. Add images to images/, reference in body

Update the homepage greeting video:

1. Edit and re-render in ~/Dropbox/1CV/Brands_Qian/animation/greeting/ (see Greeting Animation above); never edit the video in this repo
2. Copy outputs/greeting.mp4, outputs/greeting.webm, and outputs/poster.jpg from that project into files/greeting/
3. If the end card’s links or labels changed, update _includes/greeting.html to match

Deployment

Push to master branch. GitHub Pages builds and deploys automatically.