Agent Summary — KaraZhang Lab Quarto Site

Quick orientation for an AI coding agent working in this repo. A converted-from-MyST Quarto lab website, built static and deployed to Vercel.

What this is

A lab website for the KaraZhang Lab (First Affiliated Hospital, Chongqing Medical University; co-PIs Yiyao Zhang & Mursel Karadas). Research themes: (1) sensory coding & perception (olfactory model circuit), (2) neuromodulation & network dynamics (acetylcholine / hippocampus).

The private/ area is lab-internal documentation, password-protected at the HTTP layer (Vercel middleware).

Layout (the folder is contents/, NOT content/)

_quarto.yml           main config: metadata, navbar, big Private sidebar, theme
index.qmd             home page
custom.css            branding (magenta, counters)
hover-preview.html    post-card hover preview (include-after-body)
vercel.json           {"outputDirectory": "_site"}
middleware.js         Vercel middleware for the password-protected /private
contents/
  publications.qmd, funding.qmd, contact.qmd
  our-team/current-members.qmd
  our-team/members/<name>.qmd       one page per member
  projects/projindex.qmd            grid hub (auto-generated listing)
  projects/<project>.qmd            one .qmd per project
  blog/index.qmd                    blog hub (two auto-generated listings)
  blog/posts/<Post>.qmd             blog posts
  blog/notebooks/*.ipynb            methodology notebooks
  private/                          password-protected internal docs (see below)
_site/                          build output (git-ignored-ish; deploy target)

private/ sections (each = index.qmd + sub-pages, wired into the navbar/sidebar in _quarto.yml)

  • ephys/ — workshop docs, slides, MATLAB preprocessing code
  • brain-rhythms/ — theta, gamma, SWR, up/down states, spindles, replay, place cells, detection methods
  • population-dynamics/ — JumpLVM, PV autocorrelation, synthetic validation, interpreting continuity
  • ephys-pipeline/ — acquisition → preprocessing → spike-sorting → analysis → troubleshooting + changelog
  • behavior-system/ — hardware, software, code structure, protocols, state-machine, sync-data
  • imaging-system/ — optics, acquisition, processing, calibration-maintenance
  • kilosort/, ripple-lab/, sleep-scoring/, glance-neuro/ — individual tools
  • knowledge-base/ — large literature KB (regions, behaviors, frameworks, methods); glob-included in the sidebar

Hard conventions (do not break these)

  1. All content files are .qmd. Quarto listings only pick up .qmd. A .md post will NOT appear on the blog grid. (Known exception: contents/blog/posts/FiberPhotometry.md — a legacy file.)
  2. Project & blog grids are auto-generated from listing: blocks in contents/projects/projindex.qmd and contents/blog/index.qmd. To add a card, just drop a .qmd in the right folder with frontmatter. Do NOT add cards by hand; do NOT reintroduce a generator script (the old generate_bloglist.py was deleted).
  3. Frontmatter fields the grids read: image, title, description, date, author, categories.
  4. MyST→Quarto syntax already in use (match it, don’t mix MyST):
    • figure: ![caption](path){#fig-id width=Xpx}
    • image: ![](path){width=Xpx}
    • callout: ::: {.callout-note} / {.callout-important} / {.callout-tip}
    • grid: ::: {.grid} with ::: {.g-col-12 .g-col-md-6} items
    • card: ::: {.card}
    • badge: [text]{.badge-primary}
    • icon: (FontAwesome extension)
  5. Images use relative paths from the file location (e.g. ../../img/..., imgs/..., ephys/docs/assets/img/...).

Adding content — recipes

  • New project: create contents/projects/<slug>.qmd with title, image (drop into contents/projects/imgs/), description. It appears on the grid automatically (projindex excludes only projindex.qmd).
  • New blog post: create contents/blog/posts/<Title>.qmd with title, image, description, date, optional categories/author. Must be .qmd.
  • New member: copy contents/our-team/members/murselkaradas.qmd, rename, add photo to contents/img/members/, add a row to current-members.qmd.
  • New private doc-set: create the folder + index.qmd, then register the pages in the website:sidebar block in _quarto.yml (the Private sidebar) and link it from contents/private/index.qmd.

Build & deploy (Vercel)

Vercel does NOT run Quarto — render locally first.

quarto render      # writes _site/
vercel --prod      # uploads _site/ as-is (project already linked: "karazhang")

Local preview: quarto preview. Per-page PDF: quarto render <file.qmd> --to typst (or format: typst: default). If the folder is re-cloned/unlinked, run vercel link before deploying.

Gotchas / open items

  • site-url in _quarto.yml is https://karazhang.vercel.app — keep it in sync with the live domain (used for sitemap/SEO).
  • .env.local and .vercel/ are git-ignored (auth secret) — never commit.
  • _site/ and .DS_Store are NOT yet git-ignored; add if this becomes a repo.
  • contents/blog/_metadata.yml is empty/unused (kept for future per-post defaults).
  • Theme is light: flatly, dark: darkly; CSS in custom.css.