Why Is My Jekyll Theme Broken on GitHub Pages

Common Reasons Jekyll Themes Fail on GitHub Pages

You’ve installed a Jekyll theme like Mediumish, committed it to your GitHub repository, and enabled GitHub Pages—only to see a broken layout, missing styles, and 404 errors. This is a common frustration that new users experience when working with GitHub Pages.

Understanding the Root Causes

The most common reasons for a broken Jekyll theme on GitHub Pages boil down to:

• Incorrect baseurl configuration
• Wrong asset paths (CSS, JS, images)
• Theme assets not included or not found
• Missing plugin support (GitHub Pages safe mode restrictions)
• Using a custom domain without path adjustments

The Role of Baseurl in Project Sites

When deploying a Jekyll site as a project site (not a user site), your site will live in a subdirectory like /your-repo-name. Every asset must therefore be prepended with that subdirectory path using baseurl.

Symptoms of Incorrect Baseurl

• Your homepage loads, but no CSS styling is applied.
• Links to blog posts or pages return 404 errors.
• Images appear broken or not at all.

Solution:

Edit your _config.yml file and add:

baseurl: "/your-repo-name"
url: "https://yourusername.github.io"

In your layout and includes, always use:

<link rel="stylesheet" href="{{ site.baseurl }}/assets/css/main.css">

Why Themes Like Mediumish Break Easily Without Adjustments

The Mediumish theme, like many Jekyll themes, assumes a base path of `/`, meaning it works perfectly only in user sites unless modified. This becomes an issue when deployed as a project site.

Checklist for Making Mediumish Theme Work on GitHub Pages

• Set baseurl in _config.yml
• Update all asset links to include {{ site.baseurl }}
• Use {{ site.url }}{{ site.baseurl }} for absolute URLs in meta tags
• Do not use hardcoded paths like /assets/

Asset Path Troubleshooting

If your fonts, logos, images, or stylesheets don’t show up, double check your theme files for hardcoded asset paths.

How to Fix Them

Replace all occurrences of paths like:

/assets/css/style.css

With:

{{ site.baseurl }}/assets/css/style.css

Using Themes with GitHub Pages-Safe Plugins

GitHub Pages runs Jekyll in a “safe mode,” which means certain plugins won’t work unless you're building the site locally and pushing the compiled site.

What This Means

• Custom plugins like pagination or tag generators may not run
• You must pre-build locally with bundle exec jekyll build
• Then push the _site folder to a separate branch like gh-pages

Alternative:

Use GitHub Actions to build the site on push. This allows full plugin support and a cleaner CI/CD workflow.

How to Verify Your Theme Build Locally

Always test your site locally with the correct baseurl before pushing to GitHub:

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

This emulates the GitHub Pages environment for a project site. Navigate to http://localhost:4000/your-repo-name/ to check if all links and styles work correctly.

How GitHub Pages Deployment Branch Affects Output

Make sure you are deploying the correct branch. For user sites, this is usually main. For project sites, you can choose main, gh-pages, or even /docs folder.

How to Set It

Go to your repository → Settings → Pages and configure:

• Source: main or gh-pages
• Folder: / (root) or /docs

Using Mediumish Without Breaking URLs

Many Mediumish users experience broken links because of hardcoded slugs or incorrect permalink structures. Double check your permalink settings in _config.yml:

permalink: /:categories/:title/

Also verify that your post filenames are in this format:

YYYY-MM-DD-title.md

Recap: Steps to Fix a Broken Jekyll Theme on GitHub Pages

1. Set baseurl Properly

Use the correct baseurl value in _config.yml and apply it in all links, assets, and internal paths.

2. Replace Hardcoded Paths

Search your theme’s layout and include files for paths that start with a slash and replace them with {{ site.baseurl }}/.

3. Test Locally with Baseurl

Use the --baseurl flag to simulate deployment behavior before pushing to GitHub.

4. Set the Correct Deployment Branch

For project sites, choose either the gh-pages branch or the /docs folder, then verify the result.

5. Use GitHub Actions for Full Plugin Support

If your theme uses unsupported plugins, set up GitHub Actions to build and deploy the site automatically.

Conclusion

If your Jekyll theme looks broken on GitHub Pages, it’s almost always due to misconfigured baseurl, broken paths, or GitHub’s plugin limitations. Understanding how GitHub Pages works and how your theme expects to be deployed makes all the difference between a broken blog and a beautiful one.

With the right setup, you can take full advantage of modern Jekyll themes like Mediumish and enjoy a free, elegant blogging experience powered by GitHub Pages.