CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

About

Personal academic website for Mingze Gao (mingze-gao.com), built with Quarto and published to GitHub Pages by pushing the rendered _site/ output to master.

Commands

When working on a file, only render/preview that specific file — never the full site:

quarto render path/to/file.qmd
quarto preview path/to/file.qmd

A full quarto render is very costly and requires local data (e.g. ga-key.json). Do not run it unless explicitly asked.

Install Python dependencies:

pip install -r requirements.txt
pip install jupyter

Architecture

  • _quarto.yml — root project config: site metadata, navbar, sidebar, HTML theme, bibliography (references.bib), and a post-render hook (scripts/post-render.py).
  • _brand.yml — Macquarie University brand colors (charcoal, red, sand-light) applied via the brand theme layer.
  • scripts/post-render.py — runs after a full render; copies specurve/, data/, utils/, apps/ directories and favicon.ico into _site/. Only runs on full project renders (checks QUARTO_PROJECT_RENDER_ALL).
  • _extensions/mgao6767/mq/ — custom Quarto extension providing the mq-revealjs format (Macquarie-branded Reveal.js theme). Used by all lecture/workshop .qmd files via format: mq-revealjs.
  • _freeze/ and .quarto/_freeze/ — Quarto computation freeze cache. Frozen outputs avoid re-executing Python code on every render.

Content Structure

  • index.qmd — homepage with Google Analytics data visualisation (requires ga-key.json service account key, which is not committed).
  • cv/index.qmd, research/index.qmd, posts/, teaching/ — main site sections matching the navbar.
  • teaching/AFIN8003/<semester>/Week<N>/ — lecture and workshop materials per week. Each lecture index.qmd uses format: mq-revealjs + format: pdf (outputs WeekN.pdf). The custom pdf-name field in YAML front matter is used by the teaching listing template (teaching/teaching.ejs) to link PDF downloads.
  • posts/ — blog posts; posts/_metadata.yml sets shared defaults.

Deployment

The site is rendered locally and published by running quarto publish gh-pages --no-render. Do not rely on CI to render — always render locally first.

Notes

  • The homepage (index.qmd) will fail to render without ga-key.json (Google Analytics service account). This file is intentionally excluded from the repo.
  • Lecture slides are dual-format: mq-revealjs for HTML presentation and pdf for a printable handout, rendered from the same .qmd source.
  • The teaching/teaching.ejs template drives the Teaching page listings, filtering lectures vs. workshops based on the pdf-name field in YAML front matter.
Back to top