个人博客使用指南

基于 Jekyll Academic Pages 模板的个人学术主页，托管在 GitHub Pages 上。

环境搭建

方式一：Docker（推荐）

# 构建镜像
docker build -t academic-pages .

# 运行容器
docker run -p 4000:4000 -v $(pwd):/usr/src/app academic-pages

方式二：本地安装

# 1. 安装依赖（Ubuntu/Debian）
sudo apt install ruby-full build-essential zlib1g-dev nodejs

# 2. 配置环境变量（添加到 ~/.bashrc）
export GEM_HOME="$HOME/gems"
export PATH="$HOME/gems/bin:$PATH"

# 3. 安装 Bundler 和依赖
gem install bundler
bundle install

本地预览

# 启动本地服务器（带热重载）
bundle exec jekyll serve --livereload

# 访问 http://localhost:4000

项目结构

├── _config.yml              # 全局配置文件
├── _data/
│   └── navigation.yml       # 导航栏配置
├── _includes/               # 模板组件
├── _layouts/                # 页面布局模板
├── _pages/                  # 页面文件
├── _posts/                  # 博客文章
├── _projects/               # 项目展示
├── _publications/           # 论文列表
├── _gallery/                # 相册
├── images/                  # 图片资源
│   ├── avatar.png           # 头像
│   └── gallery/             # 相册照片
└── USE.md                   # 本文件

内容管理

修改个人信息

编辑 _config.yml 中的 author 部分：

author:
  avatar           : "avatar.png"           # 头像（放在 images/ 目录）
  name             : "你的姓名"
  bio              : "个人简介"
  employer         : "单位/学校"
  email            : "your@email.com"
  github           : "your-github-username"
  # ... 其他社交媒体链接（留空则不显示）

添加博客文章

在 _posts/ 目录创建 Markdown 文件，文件名格式：YYYY-MM-DD-title.md

---
title: "文章标题"
date: 2024-01-15
permalink: /posts/2024/01/15/title.html
categories: [类别1, 类别2]
tags: [标签1, 标签2]
author_profile: true
---

文章正文内容...

支持 Markdown 语法、LaTeX 公式、代码高亮等。

添加项目

在 _projects/ 目录创建 Markdown 文件：

---
title: "项目名称"
excerpt: "项目简介"
header:
  teaser: /images/project-preview.png    # 项目预览图
sidebar:
  - title: "GitHub"
    text: "[链接](https://github.com/...)"
  - title: "技术栈"
    text: "Python, PyTorch, CUDA"
---

## 项目概述

详细介绍...

## 核心功能

- 功能 1
- 功能 2

添加论文

在 _publications/ 目录创建 Markdown 文件：

---
title: "论文标题"
collection: publications
permalink: /publication/paper-title
date: 2024-01-15
venue: '会议/期刊名称'
paperurl: 'https://arxiv.org/abs/xxxx'
citation: '作者. (2024). "论文标题." <i>会议名称</i>.'
---

论文摘要和详细信息...

添加相册

第一步： 将照片放入 images/gallery/ 目录

第二步： 在 _gallery/ 目录创建相册文件：

---
title: "相册标题"
excerpt: "相册描述"
layout: gallery
author_profile: true
images:
  - url: /images/gallery/photo1.jpg
    title: 照片标题
    description: 照片描述
    date: 2024-01-15
    category: 分类标签
  - url: /images/gallery/photo2.jpg
    title: 照片标题 2
    description: 照片描述 2
    date: 2024-02-20
    category: 分类标签
---

相册的详细介绍...

相册功能说明：

支持瀑布流布局
支持分类标签筛选
点击照片可放大查看（Lightbox）
支持键盘左右箭头切换照片

部署上线

推送到 GitHub

git add .
git commit -m "更新内容"
git push origin master

GitHub Pages 配置

进入仓库 Settings → Pages
Source 选择 Deploy from a branch
Branch 选择 master 和 / (root)
保存后等待 1-5 分钟即可访问

访问地址

https://lancegan.github.io

常见问题

Q: 本地预览时样式不对？

# 清除缓存并重新构建
rm -rf _site .jekyll-cache
bundle exec jekyll serve --livereload

Q: 推送后网站没有更新？

检查 GitHub Actions 是否有构建错误
等待 1-5 分钟（GitHub Pages 构建需要时间）
清除浏览器缓存（Ctrl + Shift + R）

Q: 如何添加新的导航栏页面？

编辑 _data/navigation.yml：

main:
  - title: "页面名称"
    url: /页面路径/

Q: 如何修改主题颜色？

编辑 _sass/ 目录下的 SCSS 文件。

Q: 图片不显示？

确认图片路径正确
确认图片已提交到仓库
图片路径使用绝对路径：/images/xxx.png

参考链接

如有问题，欢迎提 Issue 或联系我：lancegan@163.com

Ruijie Gan(甘瑞杰)