How Do I Fix Permalink Issues in Jekyll Themes on GitHub Pages

Why Are My Jekyll Links Returning 404 Errors

One of the most common and frustrating problems in deploying a Jekyll site to GitHub Pages is broken internal links. You click on a blog post or a category archive, and instead of seeing your content, you get a 404 error.

Understanding Permalinks in Jekyll

In Jekyll, the permalink determines the URL structure for your content. For blog posts, Jekyll uses a default format of:

/year/month/day/post-title.html

This is fine for many themes, but themes like Mediumish often customize permalinks to create cleaner, SEO-friendly URLs such as:

/category/post-title/

Where Things Go Wrong on GitHub Pages

When this permalink structure is combined with incorrect filenames, missing front matter, or misconfigured baseurl, it can result in:

• 404 errors when accessing blog posts
• Navigation menus linking to nowhere
• Discrepancies between local and GitHub deployment behavior

How to Structure Your Jekyll Posts Correctly

To make sure your posts align with your theme’s permalink expectations, follow this format for filenames:

_posts/2025-06-19-how-to-customize-mediumish-theme.md

Inside the file, make sure the front matter includes:

---
title: "How to Customize Mediumish Theme"
date: 2025-06-19
categories: blog
---

Choosing the Right Permalink Style

Update your _config.yml to reflect your preferred permalink style. For Mediumish and similar themes, use:

permalink: /:categories/:title/

Other Permalink Options

• /blog/:year/:month/:title/ — chronological blog layout
• /:title.html — flat structure with HTML files
• /posts/:title/ — customized folder-style URLs

Be sure the permalink format aligns with the layout and link structures inside your theme’s _includes and _layouts folders.

Fixing Category-Based Permalink Issues

Mediumish and other themes often rely on category slugs in URLs. But if your post lacks a proper categories field in the front matter, or uses the wrong format, the URLs won’t match and links will break.

Correct Usage:

categories: [blog]

Incorrect Usage:

category: blog 
categories: blog 

Deploying with Clean URLs on GitHub Pages

To ensure your URLs are rendered as clean folders (not ending in .html), make sure GitHub Pages is set to build the content into clean directory format. Jekyll does this by default when permalinks end with a trailing slash.

For example, this permalink:

/blog/my-first-post/

Will be built as:

_site/blog/my-first-post/index.html

This is perfect for static hosting, and GitHub Pages will serve it correctly. But this only works if your internal links also use the same structure.

Testing Your Permalinks Locally

Before pushing to GitHub, always test your permalink structure by running Jekyll locally:

bundle exec jekyll serve --baseurl "/your-repo-name"

Then visit http://localhost:4000/your-repo-name/ and click through your blog. If links work locally, they should also work on GitHub Pages—as long as your baseurl and permalink settings match.

Using Relative URLs in Your Templates

Don’t hardcode links in your layout files. Instead, use Liquid to dynamically generate URLs:

{{ site.baseurl }}{{ post.url }}

This ensures that whether your site is deployed at root or in a subdirectory, the links will always resolve correctly.

How to Diagnose a Broken Link

If a link doesn’t work, do this:

1. Check the page source on GitHub Pages and look at the href or src path
2. Compare it to the path generated locally
3. Verify the post or page exists and has the correct date/filename
4. Ensure permalink and baseurl are configured correctly

Permalink Best Practices

• Always use trailing slashes for clean URLs
• Use category-based permalinks only if your front matter includes categories as a list
• Test permalink changes locally before deploying
• Use Liquid tags to generate URLs dynamically

Conclusion

Broken links in your Jekyll blog on GitHub Pages often come down to mismatched permalink settings, improperly formatted post metadata, or inconsistent use of baseurl. By carefully structuring your permalinks, front matter, and asset references, you can ensure your blog works perfectly—both locally and when deployed to GitHub.

If you’re using a theme like Mediumish, take extra care with how categories and slugs are handled. A few small changes can make the difference between a professional-looking blog and a frustrating user experience.

How Do You Install the Mediumish Jekyll Theme on GitHub Pages

Why Choose the Mediumish Theme for Jekyll on GitHub Pages

Mediumish is one of the most popular minimalist themes built for Jekyll, inspired by Medium’s aesthetic. It's ideal for bloggers who want a clean, readable layout with integrated social features and SEO optimization. The theme is fully responsive and compatible with GitHub Pages, making it perfect for developers and non-tech users alike.

Main Benefits of Mediumish

• Clean, mobile-friendly layout
• Pre-built structure for blog posts and home page
• Integrated Disqus comments and SEO meta tags
• Simple setup with Jekyll and GitHub Pages

Where Can You Get the Official Mediumish Theme

The Mediumish theme is available on GitHub and supported by multiple forks and versions. The original version is maintained by wowthemesnet.

Steps to Download the Mediumish Jekyll Theme

1. Visit the official repository: Mediumish GitHub Repo
2. Click the green Code button
3. Select Download ZIP or clone using Git

Using Git is recommended if you plan to update the theme in the future.

How to Install the Mediumish Theme in Your GitHub Repository

Once you have the Mediumish theme files, you need to install them into the repository you created earlier. This can be done in three main ways:

Method 1: Upload ZIP Files Manually

1. Extract the downloaded ZIP on your computer
2. Delete the existing .git folder from the extracted files
3. Zip everything again (excluding the .git directory)
4. Go to your GitHub repository
5. Click Upload files and drag the contents
6. Commit the changes

Method 2: Use Git Command Line (Recommended)

git clone https://github.com/wowthemesnet/mediumish-theme-jekyll.git
cd mediumish-theme-jekyll
rm -rf .git
git init
git remote add origin https://github.com/yourusername/yourrepo.git
git add .
git commit -m "Initial commit with Mediumish theme"
git push -u origin main

This method gives you full Git control, which is helpful for continuous updates and versioning.

What to Do After Uploading the Theme Files

After the files are in your repository, you must confirm the following before the blog renders properly:

• Ensure _config.yml is present
• Make sure there’s an index.html or home.html in the root
• Remove any redundant files like Gemfile.lock if not using local development

How to Edit Your Configuration File

The _config.yml file controls your blog’s identity and global settings.

title: Your Blog Title
email: [email protected]
description: >-
  A blog powered by Mediumish theme and GitHub Pages.
url: "https://yourusername.github.io"
baseurl: "/yourrepo" # if not deploying to root
author:
  name: Your Name
  bio: Your short bio
  location: Your City
social:
  twitter: yourhandle
  github: yourusername
  linkedin: yourprofile

Don’t forget to match the baseurl to your repo name if it's not your main user site.

How to Customize the Homepage and Navigation

Mediumish uses structured layouts with Liquid tags. You can modify the homepage layout in index.html or the _layouts/home.html file depending on the version.

To Edit Navigation Menus

Modify the navigation in the _data/navigation.yml file. Example:

- text: Home
  url: /
- text: About
  url: /about/
- text: Contact
  url: /contact/

Where Should You Add Your First Blog Posts

Mediumish stores blog posts in the _posts/ directory using a specific naming convention:

_posts/2025-01-01-my-first-post.md

Minimum Front Matter for a Blog Post

---
layout: post
title: "My First Blog Post"
author: yourname
categories: [jekyll, blogging]
description: "This is the first post on my Mediumish-powered blog."
image: /assets/images/yourimage.jpg
---

Don’t forget to write your content in Markdown after the front matter.

How to Check If the Theme Renders Correctly on GitHub Pages

After pushing or uploading the theme, go to your repository’s Settings → Pages and confirm that:

• Source is set to main and root
• Build does not fail (check under Actions)
• The live URL is generated and loads without 404

Troubleshooting Common Errors

• Theme not loading? Check your _config.yml for baseurl issues
• 404 errors? Make sure index.html exists in the root
• CSS broken? Revisit folder structure for assets

Do You Need to Install Ruby or Jekyll Locally

No, not if you're using GitHub Pages. GitHub automatically builds your Jekyll site. But if you want to preview or develop locally, then yes.

Optional: How to Install Locally (Mac/Linux)

gem install bundler jekyll
bundle install
bundle exec jekyll serve

This runs your blog at http://localhost:4000.

Conclusion

Installing the Mediumish Jekyll theme on GitHub Pages is a straightforward process if you follow the correct steps: get the theme files, configure your repository, and ensure your paths and URLs are correctly defined. With a clean install, your blog is immediately production-ready, mobile-optimized, and fully customizable. In the next phase, you can begin tweaking layouts, writing articles, or integrating third-party tools like Disqus and Google Analytics.