Development Guide

This document provides instructions for setting up and developing the academic personal website.

Prerequisites

Ruby (>= 2.6.0)
Node.js (>= 14.0.0)
Git

Quick Start

Option 1: Using Make (Recommended)

# Install dependencies and start development server
make dev

# Or run commands individually
make install  # Install dependencies
make serve    # Start development server
make build    # Build for production
make clean    # Clean build artifacts

Option 2: Using Docker

# Start development server with Docker
docker-compose up

# Build static files
docker-compose --profile build up build

Option 3: Manual Setup

Install Ruby dependencies:
```
bundle install
```
Install Node.js dependencies:
```
npm install
```

Start development server:

bundle exec jekyll serve --config _config.yml,_config.dev.yml --livereload

Development Workflow

File Structure

├── _config.yml          # Main configuration
├── _config.dev.yml      # Development overrides
├── _data/               # Site data files
├── _includes/           # Jekyll includes
├── _layouts/            # Jekyll layouts
├── _pages/              # Static pages
├── _posts/              # Blog posts
├── _publications/       # Publication entries
├── _talks/              # Talk entries
├── _portfolio/          # Portfolio items
├── _teaching/           # Teaching entries
├── assets/              # CSS, JS, images
├── images/              # Site images
└── files/               # Public files

Adding Content

Blog Posts: Add markdown files to _posts/ with YAML front matter
Publications: Add entries to _publications/ or use the markdown generator
Talks: Add entries to _talks/ or use the markdown generator
Pages: Add markdown files to _pages/

Using the Markdown Generator

The markdown_generator/ directory contains tools for generating content from TSV files:

# Generate publications from TSV
python markdown_generator/publication_generator.py

# Generate talks from TSV
python markdown_generator/talk_generator.py

Customization

Site Configuration: Edit _config.yml
Styling: Modify files in _sass/ and assets/css/
Layouts: Customize files in _layouts/
Includes: Modify files in _includes/

Build and Deploy

Local Build

# Build for production
make build

# Or manually
bundle exec jekyll build
npm run build:js

GitHub Pages Deployment

The site is automatically deployed to GitHub Pages when changes are pushed to the main branch.

Manual Deployment

# Build the site
make build

# Deploy to GitHub Pages
git add .
git commit -m "Update site"
git push origin main

Troubleshooting

Common Issues

Bundle install fails:

# Delete Gemfile.lock and try again
rm Gemfile.lock
bundle install

Jekyll serve fails:

# Check Jekyll installation
bundle exec jekyll doctor

Node.js dependencies issues:

# Clear npm cache and reinstall
npm cache clean --force
rm -rf node_modules package-lock.json
npm install

Development Tips

Live Reload: The development server includes live reload for automatic browser refresh
Drafts: Use _drafts/ directory for unpublished posts
Future Posts: Set future: true in _config.dev.yml to see scheduled posts
Analytics: Disabled in development mode to avoid tracking local development

Contributing

Fork the repository
Create a feature branch
Make your changes
Test locally with make serve
Submit a pull request

License

This project is licensed under the MIT License - see the LICENSE file for details.

付乃锋 (Naifeng Fu)