Minimal Mistakes Jekyll Theme: Hosting on GitHub & Using Liquid Archive Method

Step 1: Setting Up the RepositoryPermalink

Step 1.1: Create a GitHub RepositoryPermalink

Go to GitHub and set up a new repository with the format username.github.io (e.g., mattlifetech.github.io).

Step 1.2: Clone the Repository to Your PCPermalink

On your PC, download and install GitHub Desktop. Open GitHub Desktop and clone your newly created repository (username.github.io).

Step 1.3: Create a GemfilePermalink

Inside the cloned repository folder (username.github.io), create a file named Gemfile.

Open the Gemfile with Notepad and paste the following content:

source "https://rubygems.org"

gem "github-pages", group: :jekyll_plugins
gem "jekyll-include-cache", group: :jekyll_plugins

Then, run the following command in the terminal (Command Prompt, PowerShell, or Git Bash) inside the username.github.io directory:

bundle install

File structure to expect:Permalink

|-- .git  
|-- assets # Manual create
    |-- css  
        |-- main.scss  # Thumbnail setting for post
    |-- images  # Stores images used on websites
|-- CNAME  # (If using a custom domain)
|-- Gemfile  # File copy/ created for first powershell command run
|-- Gemfile.lock  # Auto created
|-- index.html  # Manual create/ copy + entries_layout: grid
|-- _config.yml  # Manual create/ copy & start edit
|-- _data  
    |-- navigation.yml  # Top of page category setting
    |-- ui-text.yml  # UI text customization
|-- _includes  
    |-- archive-single.html  # Template for archive (categories) pages
    |-- head.html  # HTML head section & browser tab logo link
|-- _pages  
    |-- about.md  # About page
    |-- home.md  # Custom home page + entries_layout: grid
    |-- year-archive.md  # Yearly archive page
|-- _posts  
    |-- 2025-02-21-template.md  # Example post to create
|-- _site  # Auto created & refresh
    |-- assets  
        |-- css  
        |-- images  # Auto create = DONT NOT put website image here

Step 1.4: Download _config.yml from Minimal Mistakes ThemePermalink

Go to the Minimal Mistakes GitHub repository and download the _config.yml file.

Place this file inside your username.github.io directory.

Step 2: Setting Up the Minimal Mistakes ThemePermalink

Step 2.1: Modify _config.ymlPermalink

Make sure _config.yml includes:

remote_theme: "mmistakes/minimal-mistakes@4.26.2"
plugins:
  - jekyll-include-cache

Step 2.2: Add Category and Tag Archive PagesPermalink

Create two new files in the root folder:

categories.md

---
layout: archive
title: "Categories"
permalink: /categories/
author_profile: true
---

tags.md

---
layout: archive
title: "Tags"
permalink: /tags/
author_profile: true
---

Step 2.3: Enable Liquid Archive Method in _config.ymlPermalink

Ensure these lines exist in _config.yml:

category_archive:
  type: liquid
  path: /categories/
tag_archive:
  type: liquid
  path: /tags/

Step 2.4: Set Up NavigationPermalink

Modify _data/navigation.yml to include category and tag pages:

main:
  - title: "Home"
    url: /
  - title: "Categories"
    url: /categories/
  - title: "Tags"
    url: /tags/
  - title: "About"
    url: /about/

Step 2.5: Create a Home Page for Grid LayoutPermalink

Create _pages/home.md and add:

---
layout: home
title: "Welcome to My Blog"
permalink: /
author_profile: true
header:
  overlay_image: /assets/images/header.webp
  caption: "Welcome to My Blog"
entries_layout: grid
---

Step 2.6: Create an index.html File for Grid LayoutPermalink

Create index.html in the root directory:

---
layout: home
title: "Welcome to My Site"
author_profile: true
entries_layout: grid
---

Step 2.7: Add Styling for Post Thumbnails & Grid LayoutPermalink

Create or modify assets/css/main.scss:

.post-description {
  font-size: 1.2rem;
  color: #666;
  font-style: italic;
  margin-top: -10px;
  margin-bottom: 20px;
}

.post-thumbnail {
  width: 100%;
  height: auto;
  max-height: 150px;
  object-fit: cover;
  border-radius: 8px;
}

.archive {
  display: grid;
  grid-template-columns: repeat(auto-fit, minmax(300px, 1fr));
  gap: 20px;
}

.archive__item-teaser img {
  width: 100%;
  height: auto;
  max-height: 150px;
  object-fit: cover;
  border-radius: 8px;
}

Step 2.8: Create a Sample PostPermalink

Inside _posts/, create a sample Markdown file 2025-02-21-sample-post.md:

---
title: "My First Blog Post"
layout: single
excerpt: "This is a sample post using the Minimal Mistakes theme."
date: 2025-02-21
header:
  overlay_image: /assets/images/sample-header.webp
  teaser: /assets/images/sample-thumbnail.webp
categories: [Blog]
tags: [Sample, Jekyll]
---

Welcome to my first blog post!

Important - “teaser: ” is the thumbnail picturePermalink

Step 3: Test the Site LocallyPermalink

Before pushing changes, test your site locally by running:

bundle exec jekyll serve

Visit http://localhost:4000 in your browser to check if everything works as expected.

Step 4: Push Changes to GitHubPermalink

Once all the files are in place and the site is working locally, use GitHub Desktop to commit your changes and push them to GitHub.

Your website should now be live at https://username.github.io!

GitHub Repo in case you need to download the filesPermalink

https://github.com/mattlifetech/mmistakegithub

CreditsPermalink

This guide is based on the Minimal Mistakes Jekyll theme by Michael Rose. Special thanks to the open-source community for maintaining this great theme.