3.3 Jekyll (Minimal Mistakes)¶
Jekyll converts Markdown files into static websites using templates and configuration. Paired with Minimal Mistakes theme, it provides a pre-built structure for personal sites, portfolios, and blogs. This comes with sensible defaults for navigation, posts, and layouts. For our purposes, it is likely the most popular and robust Jekyll theme available.
Jekyll runs on many personal academic sites. See the tool comparison table for when to use Jekyll versus MkDocs or JupyterBook.
Jekyll and GitHub Pages
GitHub Pages natively supports Jekyll, so sites build and deploy automatically from your repository with no separate pipeline (e.g. GitHub Actions).
Getting Started with Jekyll and Minimal Mistakes¶
Workshop shortcut
For the hands-on session, fork a ready-made template instead - much faster! See the hands-on tutorial when you are ready to build your website.
The steps below are for those who want to understand how Jekyll works from the ground up, or who need to set up a project independently.
The official Jekyll and Minimal Mistakes documentation are comprehensive. A typical from-scratch workflow can be found on the Minimal Mistakes Documentation and is broadly as follows:
1. Install prerequisites: Ruby and Bundler¶
Jekyll requires Ruby and the Bundler package manager.
On most systems:
On macOS, Ruby is often installed via Homebrew or system tools; on Linux, use your package manager. On Windows, you can work within the Windows Subsystem for Linux, or use RubyInstaller.
2. Install Jekyll¶
Verify installation:
3. Create a new site¶
This creates a basic scaffold including:
_config.yml(global configuration)_posts/(blog posts)index.md(homepage)
4. Add Bundler dependencies¶
Then edit the Gemfile to include Jekyll and Minimal Mistakes:
Install dependencies:
5. Configure Minimal Mistakes¶
Edit _config.yml to enable the theme. There are two ways to do this:
Gem-based (requires local Ruby setup, as above):
Remote theme (simpler — no local Ruby install needed, works directly on GitHub Pages):
The remote theme approach is often the more practical choice if you only plan to edit your site through GitHub's web interface. Either way, also set your site's basic metadata:
title: My Personal Site
description: A short site description
url: "https://yourusername.github.io"
minimal_mistakes_skin: "default"
A full introduction to the _config.yml file can be found here.
Minimal Mistakes supports extensive configuration for navigation, author profiles, and layouts.
A typical navigation structure (i.e. the structure of links in the header bar) is defined in _data/navigation.yml:
main:
- title: "About"
url: /about/
- title: "Posts"
url: /posts/
- title: "Projects"
url: /projects/
6. Add content¶
Content is written in Markdown with YAML front matter.
Example page:
---
title: About
layout: single
permalink: /about/
---
This is a personal website built with Jekyll and Minimal Mistakes.
More information about pages and layouts can be found in the documentation.
If you would like an active blog or news page, this is also possible using Posts. Blog posts go in _posts/ with the naming format YYYY-MM-DD-title.md.
7. Build and preview locally¶
The site will be available at http://localhost:4000. The server rebuilds automatically when files change.
8. Deploy to GitHub Pages¶
Jekyll is natively supported by GitHub Pages. After you push to a repo, simply enable Pages in repository settings and set Deploy from a branch → main. No GitHub Actions workflow required.