LI JUNZHE

TPMAM Website Architecture

This repository is being refactored into a two-track personal website system:

  1. Academic track: a Hugo Blox Academic site generated from Markdown/YAML profile data.
  2. Personal track: the existing handcrafted personal UI, preserved visually, but rendered through Hugo and backed by the same profile data.

The old design philosophy and visual rules were recovered into DESIGN.md. Do not lose that file; it is the visual contract for the personal version of the site.

Current Routing Model

After Hugo builds the site:

The previous hand-written academic root page has been removed:

The legacy static personal/section pages still exist at repo root for reference:

The canonical Hugo personal page is now site/content/personal/index.md plus site/layouts/personal/single.html.

Repository Structure

TPMAM/
  assets/                         # PDFs and images, mounted into Hugo as /assets/...
  profile-data/                   # Human-editable source of truth
    README.md                     # How to edit profile data
    bib/publications.bib          # Consolidated BibTeX
    hugo-content/                 # Mounted into Hugo content/
      _index.md                   # Academic homepage landing sections
      experience.md               # Academic experience page
      blog/                       # News updates
      projects/                   # Research project pages
      publications/               # Publication page bundles + cite.bib
    hugo-data/                    # Mounted into Hugo data/
      authors/me.yaml             # Hugo Blox author/CV profile
      profile.yaml                # Shared personal-page copy and asset paths
      links.yaml                  # Shared links
      education.yaml              # Structured education data
      experience.yaml             # Structured experience data
      skills.yaml                 # Structured skills/languages data
  site/                           # Hugo Blox Academic source site
    config/_default/              # Hugo/Hugo Blox config
    content/personal/index.md     # /personal/ route
    layouts/personal/single.html  # Preserved personal UI template
    static/styles.css             # Copied personal UI CSS, visual contract
    static/script.js              # Copied personal UI JS, visual contract
    go.mod                        # Hugo module dependencies
    package.json                  # Tailwind/Pagefind dependencies
  .github/workflows/deploy.yml    # GitHub Pages build/deploy workflow
  DESIGN.md                       # Restored original design and aesthetic spec
  AGENTS.md                       # Instructions for future coding agents

Source Of Truth

The site content should be edited in profile-data/, not directly in generated output.

Use these files first:

Hugo mounts these folders through site/config/_default/module.yaml:

mounts:
  - source: ../profile-data/hugo-content
    target: content
  - source: ../profile-data/hugo-data
    target: data
  - source: ../assets
    target: static/assets

This is the key architecture decision: Markdown/YAML controls the academic site and the preserved personal page.

Hugo Blox Setup

The Hugo source is in site/ and follows the Hugo Blox Academic CV template structure.

Important files:

The selected template direction is Hugo Blox Academic, not al-folio and not the Jon Barron HTML template.

Reason:

Personal UI Contract

The personal page UI is not to be redesigned casually.

The visual and interaction contract lives in:

Rules:

The template site/layouts/personal/single.html reads from:

Those data objects come from profile-data/hugo-data/profile.yaml and profile-data/hugo-data/links.yaml.

Academic Content Model

Publications use Hugo page bundles:

profile-data/hugo-content/publications/<slug>/
  index.md
  cite.bib

The index.md should include front matter such as:

title: "Paper Title"
authors:
  - me
  - Coauthor Name
date: 2025-10-01T00:00:00Z
publication_types: ["paper-conference"]
publication: "Accepted at *Venue*"
featured: true
links:
  - type: pdf
    url: /assets/example.pdf
projects:
  - related-project-slug

Projects live in:

profile-data/hugo-content/projects/<slug>/index.md

News lives in:

profile-data/hugo-content/blog/<slug>/index.md

The homepage section layout is controlled by:

profile-data/hugo-content/_index.md

Mac Development Instructions

On a Mac, install the toolchain outside this repository. Do not commit local toolchains.

Recommended setup:

brew install hugo go node
corepack enable
npm install -g pnpm

Then build locally:

cd site
pnpm install
hugo --minify

For development preview:

cd site
hugo server --disableFastRender

If the Homebrew Hugo version is incompatible with Hugo Blox, install Hugo Extended 0.161.1 from the official Hugo release and use that binary for this project.

Expected generated output:

site/public/

That output is ignored by Git.

GitHub Pages Deployment

Deployment is configured in:

.github/workflows/deploy.yml

The workflow:

  1. Checks out the repo.
  2. Installs Node.js.
  3. Installs pnpm.
  4. Installs Go for Hugo modules.
  5. Installs Hugo Extended 0.161.1.
  6. Runs dependency install in site/.
  7. Builds Hugo from site/.
  8. Uploads site/public to GitHub Pages.

This means a local Hugo/Go install is not required in the current Windows workspace, but a Mac agent should still run a local build before making large changes.

Current Verification Status

Done:

Not done:

A Mac follow-up should start with:

git status --short
cd site
pnpm install
hugo --minify
hugo server --disableFastRender

Then inspect:

Known Follow-Ups