仓库文件说明
这个仓库是一个基于 Academic Pages 的 Jekyll 静态网站。Jekyll 会读取 _config.yml、_data/、_pages/、各个 collection 目录和模板文件，构建成最终发布到 GitHub Pages 的静态 HTML/CSS/JS。
说明：仓库里包含不少第三方样式库、字体、示例图片和生成文件。下面会尽量按文件说明；对于同一类第三方/vendor 文件，会按目录归并说明，避免把重复的库内部文件写成没有意义的长表。
根目录文件
| 文件 | 作用 |
|---|
_config.yml | Jekyll 主配置文件。控制站点标题、作者信息、导航行为、collections、插件、URL、主题等。 |
_config_docker.yml | Docker 本地运行时追加的配置，目前内容很少，用于配合 docker-compose.yaml。 |
.gitignore | Git 忽略规则，例如 _site/、node_modules/、Gemfile.lock、.bundle/ 等。 |
Gemfile | Ruby/Jekyll 依赖声明，GitHub Pages/Jekyll 构建会用到这里的 gems。 |
Dockerfile | 构建本地 Jekyll 开发容器的镜像定义。 |
docker-compose.yaml | 用 Docker Compose 启动 Jekyll 本地预览服务，默认映射到 localhost:4000。 |
package.json | 前端 JS 构建脚本和 npm 依赖，主要用于压缩生成 assets/js/main.min.js。 |
README.md | Academic Pages 模板说明和本地运行说明。 |
LICENSE | 项目许可证。 |
talkmap.py | 根据 _talks/ 中的地点生成 talk 地图数据和 HTML。 |
talkmap.ipynb | talkmap.py 的 Notebook 版本。 |
talkmap_out.ipynb | 执行 talkmap.ipynb 后生成的输出 Notebook。 |
GitHub 与开发环境
| 文件 | 作用 |
|---|
.devcontainer/devcontainer.json | VS Code Dev Container 配置，指定使用 Docker Compose 中的 jekyll-site 服务。 |
.github/CONTRIBUTING.md | 模板项目的贡献说明。 |
.github/PULL_REQUEST_TEMPLATE.md | Pull Request 模板。 |
.github/ISSUE_TEMPLATE/bug_report.md | Bug report issue 模板。 |
.github/ISSUE_TEMPLATE/feature_request.md | Feature request issue 模板。 |
.github/workflows/bad-pr.yml | 自动关闭不合规 PR 的模板工作流，继承自 Academic Pages。 |
.github/workflows/pages.yml | 当前站点的 GitHub Pages 部署工作流。push 到 master 后构建并部署 Jekyll 站点。 |
.github/workflows/scrape_talks.yml | 当 talks 相关文件变化时，运行 talkmap.py 重新生成 talk map。 |
_data/ 数据文件
| 文件 | 作用 |
|---|
_data/authors.yml | 作者数据，模板可从这里读取作者 profile 信息。 |
_data/navigation.yml | 顶部导航菜单配置，例如 About、Publications、Talks 等入口。 |
_data/ui-text.yml | 多语言/界面文案配置，按钮、标签、提示语等来自这里。 |
_data/cv.json | JSON 格式简历数据，供 CV 页面模板读取。 |
_data/comments/** | 示例评论数据，按文章 slug 分组，用于 Staticman/comments 示例。 |
_pages/ 独立页面
| 文件 | 作用 |
|---|
_pages/about.md | 首页/个人简介页，通常是最常改的个人主页内容。 |
_pages/404.md | 404 页面。 |
_pages/archive-layout-with-content.md | 带内容区的归档布局示例页。 |
_pages/category-archive.html | 分类归档页。 |
_pages/collection-archive.html | Collection 归档页。 |
_pages/cv.md | Markdown/CV 页面入口。 |
_pages/cv-json.md | 使用 _data/cv.json 渲染的 CV 页面入口。 |
_pages/markdown.md | Markdown 语法示例页。 |
_pages/non-menu-page.md | 不放进导航菜单的示例页面。 |
_pages/page-archive.html | 普通页面归档。 |
_pages/portfolio.html | Portfolio 列表页。 |
_pages/publications.html | Publications 列表页。 |
_pages/sitemap.md | 网站地图页面。 |
_pages/tag-archive.html | 标签归档页。 |
_pages/talkmap.html | Talk 地图页面。 |
_pages/talks.html | Talks 列表页。 |
_pages/teaching.html | Teaching 列表页。 |
_pages/terms.md | Terms/条款页面。 |
_pages/year-archive.html | 按年份归档的文章列表页。 |
内容 collection
| 目录/文件 | 作用 |
|---|
_posts/*.md | 博客文章。文件名格式通常是 YYYY-MM-DD-title.md。 |
_posts/2199-01-01-future-post.md | 未来日期文章示例。 |
_publications/*.md | 论文/出版物条目，会被 Publications 页面汇总。 |
_portfolio/portfolio-1.md | Portfolio 示例条目。 |
_portfolio/portfolio-2.html | HTML 格式的 Portfolio 示例条目。 |
_talks/*.md | Talk/演讲条目，会被 Talks 页面和 talkmap 使用。 |
_teaching/*.md | Teaching/课程条目，会被 Teaching 页面汇总。 |
_drafts/post-draft.md | 草稿文章，不会像正式 _posts 一样默认发布。 |
_layouts/ 页面布局模板
| 文件 | 作用 |
|---|
_layouts/default.html | 基础页面布局，通常包含 head、header、footer、scripts。 |
_layouts/single.html | 单篇文章/单个 collection 条目的常用布局。 |
_layouts/archive.html | 归档列表布局。 |
_layouts/archive-taxonomy.html | 分类/标签归档布局。 |
_layouts/compress.html | HTML 压缩布局包装器。 |
_layouts/cv-layout.html | CV 页面专用布局。 |
_layouts/splash.html | Splash/落地页式布局。 |
_layouts/talk.html | Talk 条目专用布局。 |
_includes/ 可复用模板片段
| 文件/目录 | 作用 |
|---|
_includes/head.html | HTML <head> 区域的基础模板。 |
_includes/head/custom.html | 自定义 head 内容插入点。 |
_includes/footer.html | 页脚。 |
_includes/footer/custom.html | 自定义页脚内容插入点。 |
_includes/masthead.html | 顶部导航栏。 |
_includes/sidebar.html | 侧边栏。 |
_includes/author-profile.html | 作者头像、姓名、社交链接等侧边栏资料。 |
_includes/seo.html | SEO/meta 标签模板。 |
_includes/scripts.html | 页面底部 JS 引入模板。 |
_includes/analytics.html | 分析统计入口，根据配置选择 provider。 |
_includes/analytics-providers/*.html | Google/custom 等分析统计代码片段。 |
_includes/comments.html | 评论区入口。 |
_includes/comments-providers/*.html | Disqus、Discourse、Facebook、Staticman 等评论 provider。 |
_includes/archive-single*.html | 归档列表中单个条目的渲染片段。 |
_includes/breadcrumbs.html | 面包屑导航。 |
_includes/browser-upgrade.html | 老浏览器升级提示。 |
_includes/category-list.html | 分类列表渲染。 |
_includes/tag-list.html | 标签列表渲染。 |
_includes/comment.html | 单条评论渲染。 |
_includes/cv-template.html | JSON CV 的具体渲染模板。 |
_includes/page__hero.html | 页面 hero 区域。 |
_includes/page__taxonomy.html | 页面分类/标签 taxonomy 区域。 |
_includes/paginator.html | 分页控件。 |
_includes/post_pagination.html | 上一篇/下一篇文章导航。 |
_includes/read-time.html | 阅读时间计算展示。 |
_includes/social-share.html | 社交分享按钮。 |
_includes/base_path | 计算站点 base path 的 Liquid 片段。 |
_includes/feature_row | Feature row 组件。 |
_includes/gallery | 图片 gallery 组件。 |
_includes/group-by-array | Liquid 数组分组工具。 |
_includes/nav_list | 导航列表组件。 |
_includes/toc | 目录/table of contents 组件。 |
_sass/ 样式源码
| 文件/目录 | 作用 |
|---|
_sass/_syntax.scss | 代码高亮样式。 |
_sass/_themes.scss | 主题入口和主题变量组织。 |
_sass/include/_mixins.scss | Sass mixins。 |
_sass/include/_utilities.scss | 通用工具类。 |
_sass/layout/*.scss | 站点布局样式，例如导航、侧边栏、按钮、表格、页脚、页面主体等。 |
_sass/theme/*.scss | 不同主题的明暗色配置，例如 default、air、mint、sunrise、contrast、dirt。 |
_sass/vendor/breakpoint/** | 第三方 Breakpoint Sass 响应式断点库。 |
_sass/vendor/font-awesome/** | Font Awesome Sass 源码和变量。 |
_sass/vendor/susy/** | 第三方 Susy grid/layout Sass 库。 |
assets/ 前端静态资源
| 文件/目录 | 作用 |
|---|
assets/css/main.scss | Jekyll 编译主样式入口。 |
assets/css/fontawesome.scss | Font Awesome 样式入口。 |
assets/css/academicons.css | Academicons 图标字体样式。 |
assets/css/academicons.min.css | Academicons 压缩版样式。 |
assets/js/_main.js | 站点主 JS 源文件。 |
assets/js/theme.js | 主题切换相关 JS。 |
assets/js/plugins/jquery.greedy-navigation.js | 导航栏自适应折叠插件。 |
assets/js/main.min.js | 压缩后的前端 JS，发布时实际使用。 |
assets/fonts/academicons.* | Academicons 字体文件。 |
assets/webfonts/fa-* | Font Awesome 字体文件。 |
images/ 图片资源
| 文件/目录 | 作用 |
|---|
images/profile.png | 默认作者头像，_config.yml 中 author.avatar 指向它。 |
images/bio-photo.jpg、images/bio-photo-2.jpg | 示例个人照片。 |
images/favicon.*、images/apple-touch-icon-180x180.png、images/manifest.json | 网站图标和 PWA/浏览器图标配置。 |
images/500x300.png | 示例占位图。 |
images/editing-talk.png | README/文档中的示例截图。 |
images/themes/*.png | Academic Pages 各主题预览图。 |
images/wiki/plotly_example.png | Plotly 示例图片。 |
files/ 可下载附件
| 文件 | 作用 |
|---|
files/paper1.pdf、files/paper2.pdf、files/paper3.pdf | 示例论文 PDF。 |
files/slides1.pdf、files/slides2.pdf、files/slides3.pdf | 示例演示文稿 PDF。 |
files/bibtex1.bib | 示例 BibTeX 引用文件。 |
markdown_generator/ 内容生成工具
| 文件 | 作用 |
|---|
markdown_generator/README.md | 内容生成工具说明。 |
markdown_generator/publications.py | 从表格数据生成 publication markdown 的脚本。 |
markdown_generator/pubsFromBib.py | 从 BibTeX 生成 publication markdown 的脚本。 |
markdown_generator/talks.py | 从表格数据生成 talk markdown 的脚本。 |
markdown_generator/publications.csv | publication 示例 CSV 数据。 |
markdown_generator/publications.tsv | publication 示例 TSV 数据。 |
markdown_generator/talks.tsv | talks 示例 TSV 数据。 |
markdown_generator/publications.ipynb | publication 生成 Notebook。 |
markdown_generator/PubsFromBib.ipynb | BibTeX 转 publication 的 Notebook。 |
markdown_generator/OrcidToBib.ipynb | 从 ORCID 获取/转换 BibTeX 的 Notebook。 |
markdown_generator/talks.ipynb | talks 生成 Notebook。 |
scripts/ 辅助脚本
| 文件 | 作用 |
|---|
scripts/cv_markdown_to_json.py | 将 Markdown 简历内容转换为 JSON 数据。 |
scripts/update_cv_json.sh | 更新 _data/cv.json 的 shell 脚本。 |
talkmap/ 地图输出
| 文件/目录 | 作用 |
|---|
talkmap/map.html | talk 地图生成后的 HTML 页面。 |
talkmap/org-locations.js | talk 地点坐标数据。 |
talkmap/leaflet_dist/leaflet.markercluster.js | Leaflet marker cluster 插件。 |
talkmap/leaflet_dist/leaflet.markercluster-src.js | Leaflet marker cluster 源码版。 |
talkmap/leaflet_dist/MarkerCluster.css | marker cluster 基础样式。 |
talkmap/leaflet_dist/MarkerCluster.Default.css | marker cluster 默认主题样式。 |
talkmap/leaflet_dist/screen.css | talkmap 页面样式。 |
常见修改入口
| 想做的事 | 改哪里 |
|---|
| 修改网站标题、作者、头像、社交链接 | _config.yml |
| 修改顶部导航 | _data/navigation.yml |
| 修改首页/个人简介 | _pages/about.md |
| 添加博客文章 | _posts/ |
| 添加论文 | _publications/ |
| 添加项目展示 | _portfolio/ |
| 添加课程经历 | _teaching/ |
| 添加或删除 Talks | _talks/、_pages/talks.html、_data/navigation.yml |
| 修改页面整体布局 | _layouts/ 和 _includes/ |
| 修改样式 | _sass/、assets/css/main.scss |
| 修改部署流程 | .github/workflows/pages.yml |
| 本地 Docker 预览 | Dockerfile、docker-compose.yaml、.devcontainer/devcontainer.json |
