李永航

李永航

Academic Pages GitHub Repository

Academic Pages GitHub Repository

Project Overview

This is a GitHub Pages template for personal and professional portfolio-oriented websites called Academic Pages. It’s a Jekyll-based static site generator template designed specifically for academic and professional portfolios. The template was originally forked from the Minimal Mistakes Jekyll Theme by Stuart Geiger and is currently maintained by Robert Zupko and other contributors.

The template provides a complete framework for creating an academic portfolio website with sections for publications, talks, teaching, portfolio items, and CV display. It’s designed to be deployed via GitHub Pages but can also be run locally using Jekyll, Docker, or VS Code DevContainers.

Technologies Used

  • Jekyll - Static site generator
  • Ruby - Backend language for Jekyll
  • Liquid - Template language
  • HTML/CSS/SCSS - Markup and styling
  • JavaScript/JQuery - Interactive functionality
  • Docker - Containerized local development environment
  • GitHub Pages - Hosting platform

Project Structure

The repository is organized as follows:

├── _config.yml             # Main Jekyll configuration file
├── _config_docker.yml      # Docker-specific configuration override
├── _data/                  # YAML/JSON data files (navigation, authors, CV)
├── _drafts/                # Draft posts (not published)
├── _includes/              # Reusable HTML components
├── _layouts/               # Page layout templates
├── _pages/                 # Static pages (about, CV, publications, etc.)
├── _portfolio/             # Portfolio project entries
├── _posts/                 # Blog posts
├── _sass/                  # SCSS styling files
├── assets/                 # Static assets (CSS, JS, images)
├── files/                  # Additional files to be served
├── images/                 # Image assets
├── docker-compose.yaml     # Docker configuration
├── Dockerfile              # Docker image definition
├── Gemfile                 # Ruby dependencies
├── package.json            # Node.js dependencies

Building and Running

Local Development with Jekyll:

  1. Install prerequisites:
    sudo apt install ruby-dev ruby-bundler nodejs build-essential gcc make
# OR on macOS:
brew install ruby node
gem install bundler
  2. Install Ruby dependencies:
    bundle install
# If you encounter permission errors:
bundle config set --local path 'vendor/bundle'
bundle install
  3. Serve the site locally:
    jekyll serve -l -H localhost
# Or to ensure using local dependencies:
bundle exec jekyll serve -l -H localhost
  4. Visit http://localhost:4000

Using Docker:

  1. Make sure Docker is installed
  2. Run the container:
    chmod -R 777 .
docker compose up
  3. Visit http://localhost:4000

Using VS Code DevContainer:

  1. Open the repository in VS Code
  2. VS Code will detect the DevContainer configuration and prompt to reopen in container
  3. Or use F1 -> DevContainer: Reopen in Container
  4. The site will be automatically served at http://localhost:4000

Key Features

  • Responsive design optimized for various screen sizes
  • Multiple content collections: posts, teaching, publications, portfolio, and talks
  • SEO optimization with schema.org markup
  • Social media integration and sharing
  • Site search functionality
  • Comment systems integration (Disqus, Facebook, Staticman)
  • Customizable author profile with academic web links
  • Archive pages by category and tag
  • Sitemap generation

Configuration

The site is configured primarily through _config.yml which includes:

  • Site-wide settings (title, description, URL)
  • Author profile information
  • Social media links
  • Publication category definitions
  • Jekyll build settings
  • SEO and analytics settings

Content Management

Content is organized into different collections:

  • Posts (_posts/): Regular blog posts, organized by date
  • Pages (_pages/): Static pages like About, CV, Publications
  • Portfolio (_portfolio/): Portfolio project entries
  • Teaching (_teaching/): Teaching materials and courses (directory not in default template)
  • Publications (_publications/): Academic publications (directory not in default template)
  • Talks (_talks/): Academic talks and presentations (directory not in default template)

There are also Jupyter notebooks and Python scripts available in the markdown_generator folder to generate markdown files for publications and talks from TSV files.

Development Conventions

  • Uses Jekyll’s Liquid templating system
  • Follows GitHub Pages compatible Jekyll practices
  • SCSS for styling with modular organization
  • Responsive design using CSS media queries
  • YAML frontmatter to define page/post metadata
  • Semantic HTML5 markup
  • SEO best practices built-in

Maintenance

  • Bug reports and feature requests: https://github.com/academicpages/academicpages.github.io/issues
  • Discussions: https://github.com/academicpages/academicpages.github.io/discussions
  • The template was forked from Minimal Mistakes Jekyll Theme and is released under the MIT License

Deployment

The site is designed for GitHub Pages deployment:

  1. Create a repository named [your GitHub username].github.io
  2. Push this template to the repository
  3. Enable GitHub Pages in repository settings
  4. Site will be available at https://[your GitHub username].github.io