Jekyll启动器

academic-website-template — Jekyll 启动器模板

作者 sbryngelson

面向学者与研究组的 Jekyll 静态网站模板，提供首页、个人简介、论文列表等页面结构，可替换内容后发布到 GitHub Pages。

打开源站下载源码 ZIP

看看你的网站会是什么样

浏览真实页面截图，比较内容排版与手机效果。点击下方缩略图切换，放大查看整页细节。

3 个预览视图

桌面端首页1 / 3

访问演示网站在新标签页打开

桌面端截图首屏预览

由服务器浏览器实际访问页面后截取。

全部页面与视图 3

截图用于了解视觉与布局，交互效果请以实际项目为准。

采集于 2026-10-02查看来源

值得关注的模板亮点

从已有项目资料中，快速了解它的特点。

基于 Jekyll 的静态站点模板，面向学者个人主页与研究组网站

提供首页、About、Publications 等页面结构，内容以配置和数据文件维护

仓库包含 GitHub Actions 的 deploy.yml 工作流，用于构建与部署

README 分 Quick Start、Customization、Publications、Hosting 等章节说明使用方式

采用 MIT 许可，允许免费使用、修改、商用和分发该版本代码

模板详细介绍

这是一个基于 Jekyll 的静态网站模板，用途是给学者个人或研究组搭建主页。仓库提供可直接使用的页面骨架，使用者填写自己的信息后即可发布，演示站点部署在 GitHub Pages 上。模板以 Jekyll 的目录与数据文件组织内容，README 中给出了 Quick Start、Features、Customization、Publications、Hosting 等章节，说明修改方式集中在配置与内容文件层面。

从 README 看，模板包含首页、About 等内页，并单独说明 Publications 部分的组织方式，适合把论文列表作为独立数据维护。仓库附带 GitHub Actions 的 deploy.yml 工作流，用于构建与部署。README 提到已有 180 多个学者与研究组使用该模板，并列出大量使用者的站点链接。

许可方面，仓库采用 MIT 许可，允许免费使用、修改、商用和分发该版本代码，分发时需保留版权与许可声明。需要注意，MIT 只覆盖仓库代码，演示图片、字体、图标等第三方素材需按各自许可核对；域名、托管等外部服务可能另行收费。模板本身是静态站点，不包含后端或数据库功能。

Jekyll启动器

适合你的项目吗？

适用场景

学者搭建个人学术主页，展示简介、研究方向与论文列表
研究组建立组内网站，集中呈现成员与发表成果
已有 Jekyll 使用经验的人快速替换内容后发布到 GitHub Pages
需要把论文列表作为独立数据文件维护并随站点一起更新的场景

适合人群

高校教师、博士后、研究生等需要个人学术主页的学者
需要统一展示成果与成员信息的研究组或实验室
熟悉或愿意使用 Jekyll 与 GitHub Pages 的用户
希望以静态方式托管、不引入后端服务的站点维护者

上手与定制指南

结合仓库当前版本的说明，按下面的资料检查内容、配置与运行要求。

1
使用前需按 README 的 Quick Start 章节完成本地环境与依赖准备
2
内容修改集中在配置与数据文件，Publications 部分按 README 对应章节组织
3
仓库自带 deploy.yml 工作流，可结合 GitHub Pages 完成构建与部署
4
MIT 许可仅覆盖代码，演示图片、字体、图标等第三方素材需单独核对许可
5
域名与托管等外部服务可能产生费用，需自行确认

查看仓库使用说明

授权与来源资料

使用条件与限制

免费使用 · 保留许可声明

本次收录的是公开仓库中采用 MIT 许可的免费版本；免费范围为该版本代码，不代表外部服务或第三方素材免费。

使用时需要遵守

允许免费使用、修改、商用和分发该版本代码。
分发代码副本或实质性部分时，保留原作者版权声明和完整 MIT 许可声明。
代码按现状提供；担保与责任限制以原许可证及适用法律为准。

额外费用与待核对事项

演示图片、字体、图标及其他第三方素材需按各自许可核对，不能仅凭代码的 MIT 许可判断。
域名、托管、数据库、支付或 AI 等外部服务可能另外收费。
使用自定义域名需自行购买域名并配置 DNS，属于外部付费服务，模板本身不提供域名。
部署到 GitHub Pages 需在仓库设置中手动将 Pages 来源改为 GitHub Actions，否则部署步骤会失败。
自带工作流仅从 source 分支部署，推送到其他分支不会触发站点更新。
本地构建需安装 Ruby 3.2 及以上版本与 Bundler，环境不满足时无法运行。
运行 ./setup.sh --clean 会清空演示数据与示例内容，需确认后再执行，以免误删已有内容。
启用访问统计需接入 Google Analytics、Plausible、Umami 或 GoatCounter 等第三方服务，可能涉及账号与费用。

查看原文依据

Permission is hereby granted, free of charge
许可证原文

Purchase a domain, enter it under **Settings > Pages > Custom domain**, and configure DNS; the workflow picks up the new URL automatically.
README 原文

One-time setup: go to your repo's **Settings > Pages > Source** and select **GitHub Actions** instead of "Deploy from a branch".
README 原文

Push to the `source` branch; the workflow only deploys from there.
README 原文

You need Ruby (3.2 or newer; the deploy workflow uses 4.0) and Bundler.
README 原文

`--clean` asks for confirmation, then empties the data files (keeping their field comments), `assets/ref.bib`, `_posts/`, `papers/`, the demo team and research images, and the Feynman prose in `home.md`, `research.md`, and `team.md`, and points `photo` at a placeholder avatar.
README 原文

Analytics, your choice** — Google Analytics, Plausible, Umami, or GoatCounter, each a one-line setting
README 原文

https://github.com/sbryngelson/academic-website-template/blob/source/LICENSE https://github.com/sbryngelson/academic-website-template/blob/source/README.md

DeepSeek 根据仓库许可证和 README 整理 ·2026-10-04。结果仅覆盖已读取资料，依赖、图片、字体及后续条款变更以各自原文为准。

项目核对记录与介绍依据

模板资料

来源平台: GitHub
资料与维护参考分: 资料较完整 · 91 / 100
技术栈: Jekyll
网站类型: 启动器

这个分数如何计算

本站按许可资料（最高30分）、演示链接（12分）、预览图（10分）、Star数（15分）、记录的维护时间（15分）、描述完整度（8分）、功能记录（5分）和分类资料（5分）计算。它不是代码、安全或性能测试，也不是 Google 评分；有链接不代表已实测可用。

这个项目需要核对什么

记录的仓库更新时间: 2026-10-01
截图检查日期: 2026-10-04

已收录演示链接。请用你的内容与屏幕尺寸检查；有演示不代表表单、认证或支付已经可用。

目录记录的主要技术栈是 Jekyll。请通过依赖清单和锁文件核对实际版本与托管要求。这些说明基于收录资料，不代表代码审计或部署实测。

查看具体选型方法 →

介绍的制作与核对状态

介绍由 AI 辅助整理目录与仓库资料。仓库作者不等于这篇介绍的审核者。

审核声明: [email protected] · 2026-10-04

查看当时使用的来源资料

SHA-256: 4fb7e46553c202f870bfffb2590fdeaae6467d70da03417c94d2511951cc7623

2026-10-04T08:38:57.239Z

来源文件 / 仓库

# A website template for academics

<p align="center">
  <img src="images/screenshots/home-hero.webp" alt="Home page in light and dark mode" width="900">
</p>

<p align="center">
  <strong>A beautiful, production-ready Jekyll website for academics and research groups.</strong><br>
  Use the template. Fill in your info. Publish.
</p>

<p align="center">
  <a href="https://github.com/sbryngelson/academic-website-template/actions/workflows/deploy.yml"><img src="https://github.com/sbryngelson/academic-website-template/actions/workflows/deploy.yml/badge.svg" alt="Build and Deploy"></a>
  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="MIT license"></a>
</p>

<h3 align="center">
  <a href="https://sbryngelson.github.io/academic-website-template/">See the live demo &rarr;</a>
</h3>

<p align="center">
  <a href="#quick-start">Quick Start</a> &middot;
  <a href="#features">Features</a> &middot;
  <a href="#customization">Customization</a> &middot;
  <a href="#publications">Publications</a> &middot;
  <a href="#hosting">Hosting</a>
</p>

### Used by 180+ academics and research groups

<a href="https://i-vesseg.github.io/" target="_blank">★</a>
<a href="https://bczheng.com/" target="_blank">★</a>
<a href="https://bazilinskyy.github.io/" target="_blank">★</a>
<a href="https://www.coreytcallaghan.com/" target="_blank">★</a>
<a href="https://minseoksong.github.io/" target="_blank">★</a>
<a href="https://acme-group-cmu.github.io/" target="_blank">★</a>
<a href="https://adisun94.github.io/" target="_blank">★</a>
<a href="https://comp-physics.group" target="_blank">★</a>
<a href="https://spike.doc.ic.ac.uk/" target="_blank">★</a>
<a href="https://mashadab.github.io/" target="_blank">★</a>
<a href="https://home.iitk.ac.in/~lalit/" target="_blank">★</a>
<a href="https://ethan-pickering.github.io/" target="_blank">★</a>
<a href="https://pedro-dm-gomes.github.io/" target="_blank">★</a>
<a href="https://3tbk.github.io/3tbk/" target="_blank">★</a>
<a href="https://felipesua.github.io/" target="_blank">★</a>
<a href="https://shivvrat.github.io/" target="_blank">★</a>
<a href="https://ritamraha.github.io/" target="_blank">★</a>
<a href="https://matsesseldeurs.github.io/" target="_blank">★</a>
<a href="https://michelleblom.github.io/" target="_blank">★</a>
<a href="https://sahatulika15.github.io" target="_blank">★</a>
<a href="https://mzhanglab.github.io" target="_blank">★</a>
<a href="https://soar-lab.github.io" target="_blank">★</a>
<a href="https://azharghafoor.github.io/" target="_blank">★</a>
<a href="https://hyunwoo.info/" target="_blank">★</a>
<a href="https://computervision0.github.io/" target="_blank">★</a>
<a href="https://vaibhavb007.github.io/" target="_blank">★</a>
<a href="https://gabry993.github.io/" target="_blank">★</a>
<a href="https://shantnuu.github.io/" target="_blank">★</a>
<a href="https://efstathia-soufleri.github.io/" target="_blank">★</a>
<a href="https://zchoffin.github.io/" target="_blank">★</a>
<a href="https://albertgassol1.github.io/" target="_blank">★</a>
<a href="https://seanpark05.github.io/" target="_blank">★</a>
<a href="https://miki998.github.io/" target="_blank">★</a>
<a href="https://wilfonba.github.io/" target="_blank">★</a>
<a href="https://mvmacfarlane.github.io/" target="_blank">★</a>
<a href="https://saharnaz.org/" target="_blank">★</a>
<a href="https://www.isnicholas.com/" target="_blank">★</a>
<a href="https://zhiyu7.github.io/" target="_blank">★</a>
<a href="https://awen-li.github.io/" target="_blank">★</a>
<a href="https://yukiiwong.github.io/" target="_blank">★</a>
<a href="https://joeyleehk.github.io/" target="_blank">★</a>
<a href="https://fabayocbocjr.github.io/" target="_blank">★</a>
<a href="https://adityanandy.github.io/" target="_blank">★</a>
<a href="https://jlastro.github.io/" target="_blank">★</a>
<a href="https://xia-hu.github.io/" target="_blank">★</a>
<a href="https://p-bajpai.github.io/" target="_blank">★</a>
<a href="https://AdityaSinghDevs.github.io/" target="_blank">★</a>
<a href="https://aipsita.github.io/" target="_blank">★</a>
<a href="https://anedelin.github.io/" target="_blank">★</a>
<a href="https://avibagchi.github.io/" target="_blank">★</a>
<a href="https://binbin-xie.github.io/" target="_blank">★</a>
<a href="https://BiomedLabUGgt.github.io/" target="_blank">★</a>
<a href="https://emilyvansyoc.github.io/" target="_blank">★</a>
<a href="https://Erd-ling.github.io/" target="_blank">★</a>
<a href="https://estimation-control-learning-laboratory.github.io/" target="_blank">★</a>
<a href="https://EthanJ666.github.io/" target="_blank">★</a>
<a href="https://f-farhan.github.io/" target="_blank">★</a>
<a href="https://gcg-helsinki.github.io/" target="_blank">★</a>
<a href="https://Grupo-MATE.github.io/" target="_blank">★</a>
<a href="https://guancai.github.io/" target="_blank">★</a>
<a href="https://haochey.github.io/" target="_blank">★</a>
<a href="https://hrositi.github.io/" target="_blank">★</a>
<a href="https://Khris-VI.github.io/" target="_blank">★</a>
<a href="https://KieuTruong.github.io/" target="_blank">★</a>
<a href="https://kwakkyoleen.github.io/" target="_blank">★</a>
<a href="https://martinezach.github.io/" target="_blank">★</a>
<a href="https://msstate-athena.github.io/" target="_blank">★</a>
<a href="https://mvanwyngarden.github.io/" target="_blank">★</a>
<a href="https://Naeele.github.io/" target="_blank">★</a>
<a href="https://NickJi98.github.io/" target="_blank">★</a>
<a href="https://qianhuimen.github.io/" target="_blank">★</a>
<a href="https://saorisakaue.github.io/" target="_blank">★</a>
<a href="https://victorolaiya.github.io/" target="_blank">★</a>
<a href="https://wjin4.github.io/" target="_blank">★</a>
<a href="https://yasserfarouk.github.io/" target="_blank">★</a>
<a href="https://yuminglab.github.io/" target="_blank">★</a>
<a href="https://zeyuD.github.io/" target="_blank">★</a>
<a href="https://nderus.github.io" target="_blank">★</a>
<a href="https://1781950192.github.io/zjgsu.lch/" target="_blank">★</a>
<a href="https://9laurence.github.io/" target="_blank">★</a>
<a href="https://abhilekhborah.github.io/abhilekhborah123.github.io/" target="_blank">★</a>
<a href="https://AGB-Shargh.github.io/" target="_blank">★</a>
<a href="https://aidanrm.com/" target="_blank">★</a>
<a href="https://albertopadovan.github.io/apgroup/" target="_blank">★</a>
<a href="https://ali-ayati.com/" target="_blank">★</a>
<a href="https://AliciaNegre.github.io/" target="_blank">★</a>
<a href="https://Amanita19.github.io/" target="_blank">★</a>
<a href="https://aniksh.github.io/" target="_blank">★</a>
<a href="https://AyahHelal.github.io/" target="_blank">★</a>
<a href="https://b-mahato.github.io/" target="_blank">★</a>
<a href="https://bcolmey.github.io/" target="_blank">★</a>
<a href="https://braden-kennedy.github.io/bkennedyportfolio/" target="_blank">★</a>
<a href="https://bwangair.github.io/" target="_blank">★</a>
<a href="https://C-3PE.github.io/" target="_blank">★</a>
<a href="https://carmenreal.github.io/" target="_blank">★</a>
<a href="https://chlookaburra.github.io/" target="_blank">★</a>
<a href="https://chris-hzc.github.io/" target="_blank">★</a>
<a href="https://chz05.github.io/" target="_blank">★</a>
<a href="https://DanielEWeeks.github.io/Daniel_E_Weeks/" target="_blank">★</a>
<a href="https://www.danieljvickers.com/" target="_blank">★</a>
<a href="https://deepaktatachar.github.io/" target="_blank">★</a>
<a href="https://DGonzalezPicos.github.io/" target="_blank">★</a>
<a href="https://dmebr.com/" target="_blank">★</a>
<a href="https://DominikSlomma.github.io/" target="_blank">★</a>
<a href="https://ecsicl.github.io/" target="_blank">★</a>
<a href="https://egl49.github.io/" target="_blank">★</a>
<a href="https://eletoo.github.io/" target="_blank">★</a>
<a href="https://ericmanley.github.io/" target="_blank">★</a>
<a href="https://Fanerst.github.io/" target="_blank">★</a>
<a href="https://www.fintanhealy.co.uk/" target="_blank">★</a>
<a href="https://flampouris.com/" target="_blank">★</a>
<a href="https://gabriel-correa.com/" target="_blank">★</a>
<a href="https://Gaby-253.github.io/" target="_blank">★</a>
<a href="https://HaiboLi99.github.io/" target="_blank">★</a>
<a href="https://HC-teemo.github.io/grapheco.github.io/" target="_blank">★</a>
<a href="https://hcfun.github.io/" target="_blank">★</a>
<a href="https://hikari-NYU.github.io/" target="_blank">★</a>
<a href="https://hildaadwubiosei.github.io/hildaosei/" target="_blank">★</a>
<a href="https://IlianaXn.github.io/" target="_blank">★</a>
<a href="https://jadededaj.github.io/" target="_blank">★</a>
<a href="https://jessestraat.github.io/" target="_blank">★</a>
<a href="https://jiaenwu.github.io/jiaenwu/" target="_blank">★</a>
<a href="https://JialiangTang.github.io/homepage/" target="_blank">★</a>
<a href="https://Jill0099.github.io/" target="_blank">★</a>
<a href="https://JohanSGV.github.io/" target="_blank">★</a>
<a href="https://juang.id/" target="_blank">★</a>
<a href="https://julianklix.github.io/" target="_blank">★</a>
<a href="https://Julien-Co.github.io/" target="_blank">★</a>
<a href="https://JWM-CU.github.io/mmc3/" target="_blank">★</a>
<a href="https://kacf24.github.io/" target="_blank">★</a>
<a href="https://kalfton.github.io/" target="_blank">★</a>
<a href="https://Kilomaroon.github.io/" target="_blank">★</a>
<a href="https://LHCb-Cincinnati.github.io/" target="_blank">★</a>
<a href="https://lorenzoghiro.com/" target="_blank">★</a>
<a href="https://Lspor.github.io/Lauren_Spor/" target="_blank">★</a>
<a href="https://lucasSaavedra123.github.io/" target="_blank">★</a>
<a href="https://lukasztychoniec.github.io/" target="_blank">★</a>
<a href="https://majinwakeup.github.io/" target="_blank">★</a>
<a href="https://margaretmurakami.github.io/" target="_blank">★</a>
<a href="https://MaxDYF.github.io/" target="_blank">★</a>
<a href="https://mekhiito.github.io/" target="_blank">★</a>
<a href="https://mgoldberg10.github.io/" target="_blank">★</a>
<a href="https://MosesStewart.github.io/" target="_blank">★</a>
<a href="https://mxyao.github.io/" target="_blank">★</a>
<a href="https://NaokiItsui.github.io/" target="_blank">★</a>
<a href="https://owenarden.github.io/home/" target="_blank">★</a>
<a href="https://pinakisar.github.io/" target="_blank">★</a>
<a href="https://pponzio.github.io/" target="_blank">★</a>
<a href="https://www.quant-minds.com/" target="_blank">★</a>
<a href="https://Qxjyqzw.github.io/" target="_blank">★</a>
<a href="https://rajmadan96.github.io/website/" target="_blank">★</a>
<a href="https://rgrinnovatellc.github.io/" target="_blank">★</a>
<a href="https://richardhchen.com/" target="_blank">★</a>
<a href="https://riqx-code.github.io/rithi/" target="_blank">★</a>
<a href="https://riveralab.org/" target="_blank">★</a>
<a href="https://robotcodelab.com/" target="_blank">★</a>
<a href="https://rosalab.github.io/" target="_blank">★</a>
<a href="https://s-shailja.github.io/website/" target="_blank">★</a>
<a href="https://saauan.github.io/" target="_blank">★</a>
<a href="https://Saif2098.github.io/" target="_blank">★</a>
<a href="https://SarveshVGharat.github.io/" target="_blank">★</a>
<a href="https://sliao7.github.io/home/" target="_blank">★</a>
<a href="https://sms-lab.github.io/" target="_blank">★</a>
<a href="https://snapcoalition.org/" target="_blank">★</a>
<a href="https://speciation-genomics.github.io/" target="_blank">★</a>
<a href="https://stephanbickel.com/" target="_blank">★</a>
<a href="https://suruoxin.github.io/" target="_blank">★</a>
<a href="https://sxswz213.github.io/" target="_blank">★</a>
<a href="https://t3humphries.github.io/" target="_blank">★</a>
<a href="https://tadeuszrudek.github.io/" target="_blank">★</a>
<a href="https://Takumi-Kijima.github.io/" target="_blank">★</a>
<a href="https://tic173.github.io/TianyiChu/" target="_blank">★</a>
<a href="https://umbertomuratori.github.io/" target="_blank">★</a>
<a href="https://USTC-Xu-Group.github.io/" target="_blank">★</a>
<a href="https://vinkoyang.github.io/VinkoYang/" target="_blank">★</a>
<a href="https://voilalab.github.io/" target="_blank">★</a>
<a href="https://wakandaai.github.io/" target="_blank">★</a>
<a href="https://WenbinLuomath.github.io/wenbinluo/" target="_blank">★</a>
<a href="https://xietian1.github.io/snms-lab-web/" target="_blank">★</a>
<a href="https://xiuquan0418.github.io/" target="_blank">★</a>
<a href="https://xuguangning1218.github.io/" target="_blank">★</a>
<a href="https://xzzhouxi.github.io/xzzhouxi.github.com/" target="_blank">★</a>
<a href="https://YongPeng25.github.io/WaveLens/" target="_blank">★</a>
<a href="https://YueGroup.github.io/" target="_blank">★</a>
<a href="https://zcy26.github.io/" target="_blank">★</a>

Each star is a live site built from this template. The list is re-checked now and then; sites that go offline or move to another template are removed.

__Using this template? Share your site and I'll add it here!__

---

## Features

### Design
- **Source Serif 4 + DM Sans** typography — elegant serif headings paired with a clean geometric sans body, self-hosted (no Google Fonts requests)
- **Warm parchment palette** with subtle noise texture for depth, not flat generic whites
- **Dark mode** — toggle in navbar, auto-detects system preference, persists across visits
- **Frosted glass navbar** with backdrop blur, active page indicator, and scroll shadow
- **Dynamic favicon** — SVG generated from your initials + accent color; ICO and Apple touch icon rasterized from it at deploy time
- **Responsive** — CSS Grid layouts that adapt from desktop to tablet to mobile
- **Print stylesheet** — printing or saving a page as PDF gives white paper, no navigation, and references with their DOI/arXiv URLs spelled out

### Interactions
- **Site-wide search** — press `Cmd+K` (or `Ctrl+K`) to instantly search all pages
- **Copy BibTeX** — hover any bibtex block to reveal a one-click copy button
- **Animated link underlines** — smooth gradient underlines that grow on hover
- **Card hover effects** — lift + shadow on team cards, research cards, and profile photo
- **Image zoom** — subtle scale on hover for team photos, research thumbnails, and the banner
- **Back-to-top button** — appears on scroll, smooth scrolls up
- **Smooth expand/collapse** — CSS transitions on publication abstracts and BibTeX entries

### Publications
- **Auto-generated from BibTeX** via Jekyll Scholar — just edit `assets/ref.bib`
- **Search bar** — filter publications by title, author, or year
- **Year badges** — small accent-colored pills for quick scanning
- **Pill buttons** — PDF, DOI, arXiv, Link, Code, Slides, Video, Poster, Data, BIB, Abstract, all driven by BibTeX fields
- **Selected publications** on the home page — add `selected={true}` to an entry

### For New Users
- **Interactive setup script** — `./setup.sh` fills in your name, title, and institution; `./setup.sh --clean` also strips the demo content
- **Talks, teaching, and software as data** — edit a YAML list, not HTML
- **5-step `_config.yml`** — numbered sections with inline comments guide you through setup
- **Well-commented data files** — every field in `_data/*.yml` is explained with examples
- **Analytics, your choice** — Google Analytics, Plausible, Umami, or GoatCounter, each a one-line setting
- **Smart link handling** — empty links in config are automatically hidden (no broken icons)

### Technical
- **Modular SASS** — organized into `base/`, `components/`, `layouts/`, `utilities/`
- **No third-party requests** — fonts and icons are served from your own site; the only external script is MathJax, and only on pages that opt in
- **Selective Bootstrap 5.3.8 SCSS** — navbar, reboot and utilities only; no Bootstrap JavaScript, no jQuery
- **Single dependency-free JS file** — dark mode, search, toggles, scroll effects, copy button
- **Auto-generated sitemap** via `jekyll-sitemap`
- **Reproducible builds** — `Gemfile.lock` is committed, so your site builds the same way next year
- **CI on pull requests** — every PR is built and its internal links are checked
- **Open Graph + Twitter Cards** — links look good when shared on social media
- **MathJax 4** — add `math: true` to a page or post (or set it site-wide in `_config.yml`)

## Screenshots

| | |
|:---:|:---:|
| ![Publications](images/screenshots/publications.webp) | ![Team](images/screenshots/team.webp) |
| Publications: filter box, year badges, buttons from BibTeX fields | Team page with card grid (dark mode) |
| ![Search](images/screenshots/search.webp) | |
| Site-wide search (Cmd+K) | |

## Quick Start

1. Click **[Use this template](https://github.com/sbryngelson/academic-website-template/generate)** and name the new repository `YOUR_USERNAME.github.io`
   (prefer this over forking: you get a clean history, no upstream baggage, and the option to keep it private)
2. **Install** Ruby and Bundler ([Jekyll's guide](https://jekyllrb.com/docs/installation/) covers it), then run `bundle install`
3. **Configure** your site:
   ```bash
   ./setup.sh --clean  # remove the demo content and fill in your details, or
   ./setup.sh          # keep the demo content as examples, or
   vim _config.yml     # edit Steps 1-5 directly
   ```
4. **Add your publications** to `assets/ref.bib`
5. **Customize** data files in `_data/` (team members, news, awards, etc.)
6. **Preview** your site:
   ```bash
   bundle exec jekyll serve
   # open http://localhost:4000
   ```
7. **Deploy**: push to GitHub, then once, in your repo, set **Settings > Pages > Source** to **GitHub Actions**. Every later push deploys automatically.

## Detailed How-To Guide

### Step 1: Create Your Repository

Click **[Use this template](https://github.com/sbryngelson/academic-website-template/generate)** on GitHub and name the new repository `YOUR_USERNAME.github.io`. Then clone it:

```bash
git clone https://github.com/YOUR_USERNAME/YOUR_USERNAME.github.io.git
cd YOUR_USERNAME.github.io
```


### Step 2: Install Dependencies

You need Ruby (3.2 or newer; the deploy workflow uses 4.0) and Bundler. See [Jekyll's installation guide](https://jekyllrb.com/docs/installation/).

```bash
bundle install
```

### Step 3: Configure Your Identity

Open `_config.yml` and fill in your information. The file is organized into numbered steps:

```yaml
# STEP 1: Your Identity
name: "Jane Smith"
title: "Assistant Professor of Computer Science"
institution: "Stanford University"
email: [email protected]
photo: headshot.jpg   # place your photo in images/
```

Or run the interactive setup script:

```bash
./setup.sh          # prompts for name, title, institution, email
./setup.sh --clean  # same, after removing the demo content
```

`--clean` asks for confirmation, then empties the data files (keeping their field comments), `assets/ref.bib`, `_posts/`, `papers/`, the demo team and research images, and the Feynman prose in `home.md`, `research.md`, and `team.md`, and points `photo` at a placeholder avatar.

### Step 4: Add Your Links

Still in `_config.yml`, add your academic profiles. Leave blank (or delete) any you don't use:

```yaml
# STEP 2: Your Links
links:
  google_scholar: "https://scholar.google.com/citations?user=YOUR_ID"
  github: "https://github.com/yourusername"
  orcid: "https://orcid.org/0000-0000-0000-0000"
  cv: "papers/cv.pdf"        # place your CV in the papers/ directory
  twitter: ""                # leave blank to hide
  linkedin: ""
```

### Step 5: Add Your Photo

Place your profile photo in the `images/` directory. Update the `photo` field in `_config.yml` to match the filename.

### Step 6: Add Publications

Edit `assets/ref.bib` with your BibTeX entries. The publications page is auto-generated. Example:

```bibtex
@article{smith2024,
  author = {Smith, Jane and Doe, John},
  title = {A Novel Approach to Machine Learning},
  journal = {Nature},
  year = {2024},
  volume = {42},
  pages = {1--10},
  doi = {10.1234/example},
  arxiv = {2401.01234},
  code = {https://github.com/jsmith/novel-approach},
  file = {smith2024.pdf},       % place PDF in papers/
  selected = {true},            % also show on the home page
  abstract = {We present...}
}
```

Every link is a BibTeX field; use the ones you have:

| Field | Button |
|-------|--------|
| `file` | PDF (file in `papers/`) |
| `doi`, `arxiv`, `url` | DOI, arXiv, Link |
| `code`, `slides`, `video`, `poster`, `data` | Code, Slides, Video, Poster, Data |
| `abstract` | Abstract (expandable) |
| `selected = {true}` | Listed under "Selected publications" on the home page |

Your name is bolded automatically in the publication list. Set it in `_config.yml` exactly as it appears in the rendered list (`Last, F. M.`), longest form first:

```yaml
scholar:
  last_name: Smith
  first_name: ["J. A.", "J."]
```

### Step 7: Add Team Members

Edit `_data/team_members.yml`:

```yaml
- name: Alice Johnson
  photo: alice.jpg          # place in images/ or images/team/
  info: PhD Student, started Fall 2023
  email: [email protected]
  website: https://alice.dev
  github: https://github.com/alice
```

### Step 8: Add News

Edit `_data/news.yml` (newest first):

```yaml
- date: 15 March, 2024
  headline: "Our paper on X was accepted to NeurIPS!"

- date: 1 January, 2024
  headline: "Welcome to new PhD student Alice Johnson"
```

### Step 9: Customize Pages

Each page in `_pages/` is a Markdown file. Edit the content directly:

- `home.md` — your welcome text and bio (see [Home page building blocks](#home-page-building-blocks))
- `research.md` — describe your research areas
- `about.md` — optional sections (grants, awards, sponsors) driven by `_data/`
- `team.md` — the openings note and administrative contact

Talks, teaching, and software are lists in `_data/` (see below); their pages need no editing.

To remove a page from the navbar, comment it out in `_config.yml`:

```yaml
nav_pages:
  - name: about
  - name: publications
    label: Papers        # optional: navbar text (URL stays /publications)
  # - name: talks        # hidden from navbar
  - name: research
```

Blog posts live in `_posts/` and are published at `/blog/<year>/<title>/`.

### Step 10: Preview and Deploy

```bash
# Preview locally
bundle exec jekyll serve
# Visit http://localhost:4000

# When ready, push to GitHub
git add -A
git commit -m "My academic website"
git push
```

A GitHub Actions workflow automatically builds and deploys your site on every push. Make sure to go to **Settings > Pages > Source** in your repo and select **GitHub Actions**.

Your site will be live at `https://YOUR_USERNAME.github.io` within a few minutes.

---

## Customization

### _config.yml

The config file is organized into 5 numbered steps:

| Step | Section | What to fill in |
|------|---------|-----------------|
| 1 | **Your Identity** | Name, title, institution, email, photo |
| 2 | **Your Links** | Google Scholar, GitHub, ORCID, Twitter, LinkedIn, CV |
| 3 | **Site Settings** | Accent color, dark mode, math, analytics (GA4, Plausible, Umami, GoatCounter) |
| 4 | **Your Pages** | Comment out any pages you don't need |
| 5 | **Publications** | Your name (for bolding) and Jekyll Scholar options |

### Data Files

| File | Purpose |
|------|---------|
| `_data/team_members.yml` | Current students and postdocs |
| `_data/alumni.yml` | Former lab members |
| `_data/news.yml` | News items (3 most recent shown on home) |
| `_data/awards.yml` | Awards and honors |
| `_data/grants.yml` | Grants and funding |
| `_data/funders.yml` | Funder logos |
| `_data/talks.yml` | Invited and contributed talks |
| `_data/teaching.yml` | Courses |
| `_data/software.yml` | Software projects |
| `_data/pi.yml` | Optional: detailed education for About page |

Each file has inline comments explaining every field. Entries marked `# EXAMPLE` should be replaced or deleted.

### Pages

All pages are in `_pages/`. Edit the Markdown content directly. Pages use the `page` layout; blog posts use `post`.

### Accent Color & Dark Mode

Set `accent_color` in `_config.yml` to change the theme color across the entire site (links, buttons, highlights, favicon). Light and dark mode variants are derived from it automatically. Set `dark_mode: false` to disable dark mode entirely.

### CSS & JS Customization

The site uses modular SASS in `_sass/`:

```
_sass/
  base/          # variables, fonts, typography, icons, reset
  components/    # card, chips, navbar, buttons, footer, profile, publication, search
  layouts/       # home grid, team grid, research grid
  utilities/     # dark mode, animations, print
```

For JavaScript, edit `assets/js/site.js` directly. There is no build step.

### Home page building blocks

`home.md` uses three optional blocks you can copy, reorder, or delete:

```html
<!-- Research-area chips (link to /research) -->
<div class="chip-container" markdown="0">
<a href="{{ '/research' | relative_url }}" class="chip">Quantum Electrodynamics</a>
<a href="{{ '/research' | relative_url }}" class="chip">Superfluidity</a>
</div>

<!-- Callout box: callout-success, callout-warning, or callout-info -->
<div class="callout callout-success" markdown="0">
<div class="callout-title">{% include icon.html name="award" class="callout-icon" %} Nobel Prize in Physics, 1965</div>
<p>One or two sentences.</p>
</div>

<!-- Banner image with caption; place the image in images/ -->
<div class="banner-frame" markdown="0">
<img src="{{ '/images/banner.webp' | relative_url }}" alt="Describe the image" width="1400" height="449" loading="lazy">
<div class="banner-caption">Caption text</div>
</div>
```

### Search

Every page and blog post is indexed for the Cmd+K search at build time. Add `search: false` to a page's front matter to leave it out.

### Icons

Icons are inline SVG symbols in `_includes/icons.svg` (Simple Icons, Lucide, Bootstrap Icons). Use one with:

```liquid
{% include icon.html name="github" %}
```

To add an icon, paste its path data into a new `<symbol id="icon-NAME" viewBox="...">` in that file.

### Math

MathJax is loaded only where it is needed. Add `math: true` to the front matter of any page or post that contains LaTeX, or set `math: true` in `_config.yml` to load it everywhere.

## Publications

Publications are generated from `assets/ref.bib` by [Jekyll Scholar](https://github.com/inukshuk/jekyll-scholar); see [Step 6](#step-6-add-publications) for the supported fields and name bolding.

## Hosting

### GitHub Pages

Create your repo from this template as `your_username.github.io` and push. A **GitHub Actions workflow** is included (`.github/workflows/deploy.yml`) that automatically builds the site with Jekyll Scholar and deploys to GitHub Pages on every push to `source`.

One-time setup: go to your repo's **Settings > Pages > Source** and select **GitHub Actions** instead of "Deploy from a branch". (GitHub does not let a workflow enable Pages on its own; until you do this, the deploy step will fail with a message saying so.)

### Custom Domain

Purchase a domain, enter it under **Settings > Pages > Custom domain**, and configure DNS; the workflow picks up the new URL automatically. See [GitHub's guide](https://docs.github.com/en/pages/configuring-a-custom-domain-for-your-github-pages-site). (Sites deployed with GitHub Actions configure the domain in Settings, not with a `CNAME` file.)

### Self-Hosting

Set `url` (and `baseurl` if the site lives in a sub-path) in `_config.yml`, build with `JEKYLL_ENV=production bundle exec jekyll build`, and upload `_site/` to your server.

## Troubleshooting

| Symptom | Cause and fix |
|---|---|
| The deploy workflow fails at "Configure Pages" | Pages is not enabled for GitHub Actions yet. Settings > Pages > Source > **GitHub Actions** (one time). |
| Site builds locally but pages 404 on GitHub | Push to the `source` branch; the workflow only deploys from there. Check the Actions tab for the run. |
| My name is not bold in the publication list | `scholar.first_name` must match the rendered initials exactly, e.g. `["J. A.", "J."]`, longest form first. |
| `bundle install` fails on macOS | The system Ruby is too old or read-only. Install Ruby 3.2+ with Homebrew, rbenv, or mise, then rerun. |
| A page is missing from Cmd+K search | Pages need a `title` in their front matter; `search: false` excludes a page on purpose. |
| Equations do not render | Add `math: true` to that page's front matter, or `math: true` in `_config.yml`. |

## Upgrading

Coming from the previous version? See [UPGRADING.md](UPGRADING.md).

## Alternatives

* [al-folio](https://github.com/alshedivat/al-folio)
* [academicpages](https://academicpages.github.io/)
* [Minimal Mistakes](https://mmistakes.github.io/minimal-mistakes/)

## License

MIT

反馈内容错误