Jianlei Yang's Homepage

Jianlei Yang 个人学术主页代码库，基于 Jekyll + Academic Pages / Minimal Mistakes 构建，用于维护个人简介、研究方向、论文列表、项目、代码、教学和新闻页面。

网站是静态站点，没有后端服务、数据库或前端框架。源码主要位于 _pages/、_teaching/、_layouts/、_includes/、_sass/、assets/ 和 images/，构建结果输出到 _site/。

项目结构

.
|-- _config.yml              # Jekyll、站点信息、作者信息、插件和集合配置
|-- _data/                   # 导航、界面文案和页面结构化数据
|-- _pages/                  # About、Research、Publications、Projects、Code、News 等页面
|-- _teaching/               # Teaching 集合内容
|-- _layouts/                # 页面布局模板
|-- _includes/               # 头部、导航、侧栏、SEO、页脚等片段
|-- _sass/                   # 主题样式与自定义 SCSS
|-- assets/                  # CSS、JS、字体和前端资源
|-- images/                  # 头像、favicon、研究和项目插图
|-- scripts/                 # 论文页面生成脚本
|-- _site/                   # Jekyll 生成结果，不要手工编辑
|-- preview.sh               # 本地后台预览辅助脚本
|-- build.sh                 # 生产构建与检查脚本
|-- CODEX.md                 # 维护者/开发者详细说明
`-- CHECK.md                 # 当前代码库体检报告

环境要求

• Ruby 与 Bundler
• Jekyll / GitHub Pages 相关 gems，通过 Gemfile 安装
• Node.js / npm，仅在修改 assets/js/_main.js 后重新构建压缩 JS 时需要
• Git，用于拉取、提交和同步代码

Windows 用户建议使用 WSL 作为本地开发环境。也就是说，在 Windows 上安装 VS Code，但在 WSL/Linux 终端中运行 Ruby、Bundler、Jekyll、Git 和本项目脚本。

Windows 本地开发环境

推荐工具：

• Visual Studio Code
• WSL 2，建议安装 Ubuntu
• Git
• Ruby、Bundler
• Node.js / npm
• VS Code 扩展：WSL、Markdown All in One、YAML
• 可选：Codex 或其他 AI coding 工具，用于辅助阅读、修改、检查和构建

1. 安装 VS Code

可以在 Windows 中使用安装包安装 VS Code，也可以在 PowerShell 或 Windows Terminal 中使用 winget：

winget install Microsoft.VisualStudioCode

建议安装这些 VS Code 扩展：

• WSL
• Markdown All in One
• YAML

2. 安装 WSL

在 Windows PowerShell 或 Windows Terminal 中运行：

wsl --install

安装完成后重启电脑，并按提示创建 Ubuntu 用户。之后进入 WSL：

wsl

更新 Ubuntu 软件源：

sudo apt update
sudo apt upgrade

3. 安装 Git、Ruby 和 Bundler

在 WSL 中安装基础工具：

sudo apt install git ruby-full build-essential zlib1g-dev
gem install bundler

配置 Git 用户信息：

git config --global user.name "Your Name"
git config --global user.email "your.email@example.com"

确认版本：

ruby --version
bundle --version

4. 克隆代码库

建议把代码放在 WSL 的 Linux 文件系统中，例如 ~/projects/，不要放在 /mnt/c/ 下，以获得更好的文件监听和构建性能。

mkdir -p ~/projects
cd ~/projects
git clone <repo-url> dogrush.github.io
cd dogrush.github.io

5. 安装依赖

bundle install

如果需要修改并重新压缩 JavaScript，再安装 npm 依赖：

npm install

6. 用 VS Code 打开项目

在 WSL 的项目目录中运行：

code .

VS Code 会通过 WSL 扩展打开当前 Linux 环境中的项目。后续终端、Git、Jekyll 构建都建议在 VS Code 的 WSL 终端中执行。

7. 使用 AI coding 工具协作

可以在 VS Code 或终端中使用 Codex 等 AI coding 工具辅助维护本项目。建议流程：

1. 先阅读 README.md、CODEX.md、CHECK.md，了解项目结构和当前风险。
2. 让 AI 工具先分析相关文件，再提出或执行修改。
3. 修改 Markdown、布局、样式或图片后，运行 ./build.sh 验证。
4. 涉及页面视觉效果时，运行本地预览并用浏览器检查。
5. 提交前查看 git status 和 git diff，确认没有混入无关改动。

适合交给 AI coding 工具处理的任务：

• 新增或修改个人简介、研究方向、项目、代码、教学和新闻内容
• 从 _pages/papers.json 重新生成论文页面
• 梳理 Jekyll 构建错误、Liquid 模板错误或 Markdown 格式问题
• 更新 CODEX.md、CHECK.md、README.md 等维护文档

仍建议人工最终确认的任务：

• 论文、新闻、课程、项目名称和外部链接等事实信息
• 头像、研究插图和项目图标的视觉效果
• 发布前的最终 git diff

本地预览

首次使用先安装 gems：

bundle install

直接启动 Jekyll：

bundle exec jekyll serve -l -H localhost

默认地址：

http://localhost:4000/

也可以使用后台管理脚本：

./preview.sh start
./preview.sh status
./preview.sh logs
./preview.sh stop

常见问题：

• 修改 _config.yml 后需要重启 Jekyll。
• Markdown、布局和样式通常会自动重新生成。
• 如果 4000 端口被占用，可用 PORT=4001 ./preview.sh start 或手动指定 bundle exec jekyll serve -P 4001。
• 不要手工修改 _site/，它是生成结果。

生产构建

推荐使用生产构建脚本生成并检查 _site/：

./build.sh

脚本会回显并确认关键设置：

• SITE_URL：生产 URL，默认 https://dogrush.github.io
• BASEURL：站点子路径，默认空
• BUILD_DESTINATION：输出目录，默认 _site
• CLEAN_DESTINATION：构建前清理，默认 1
• STRICT：构建后检查，默认 1
• JEKYLL_ENV：默认 production
• EXTRA_JEKYLL_ARGS：传给 jekyll build 的额外参数

示例：

SITE_URL=https://dogrush.github.io BASEURL= ./build.sh
BUILD_DESTINATION=/tmp/dogrush-build CLEAN_DESTINATION=0 ./build.sh
EXTRA_JEKYLL_ARGS="--future" ./build.sh

也可以直接调用 Jekyll 构建静态文件到 _site/：

bundle exec jekyll build

GitHub Pages 发布时会按仓库配置生成静态站点；本地提交前优先以 ./build.sh 为准。

内容维护

站点信息和导航

站点标题、作者侧栏、社交链接、插件、集合和排除规则在：

_config.yml

顶部导航在：

_data/navigation.yml

当前导航包括 About、Research、Publications、Projects、Code、Teaching 和 News。

页面

主要页面位于：

_pages/

常用页面：

• _pages/about.md
• _pages/research.md
• _pages/publications.md
• _pages/project.md
• _pages/code.md
• _pages/news.md
• _pages/teaching.html

页面地址由 front matter 中的 permalink 控制。多数页面使用 author_profile: true 显示左侧作者信息。

论文

论文数据源为：

_pages/papers.json

生成论文页面：

python3 scripts/generate_publications_md.py

生成结果写入：

_pages/publications.md

注意：当前 _pages/publications.md 已经过人工整理，包含 Google Scholar 和 DBLP 链接。重新生成后请检查 diff，避免覆盖人工优化内容。

教学

教学内容位于：

_teaching/

_config.yml 中定义了 teaching collection：

collections:
  teaching:
    output: true
    permalink: /:collection/:path/

教学索引页面为：

_pages/teaching.html

图片与资源

头像、favicon、研究插图和项目图标位于：

images/

样式和脚本位于：

assets/

修改 assets/js/_main.js 后，运行：

npm run build:js

生成结果为：

assets/js/main.min.js

部署

本仓库适合 GitHub Pages 工作流。通常只需要提交源码，GitHub Pages 会根据 Jekyll 配置生成站点。

发布前建议：

./build.sh
git status
git diff

请不要把 _site/ 当作源码维护；它是本地生成结果，排查问题时可以查看，但修改应回到 _pages/、_teaching/、_includes/、_layouts/、_sass/、assets/ 或 images/。

维护文档

更详细的工程说明见：

• CODEX.md：项目结构、构建逻辑、内容维护和调试说明
• CHECK.md：最近一次代码库体检报告、已验证项目、剩余风险和建议

协作开发时，建议先读本 README，再查看 CODEX.md 中与当前任务相关的部分。