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.