What is the Difference Between User and Project Sites on GitHub Pages

Understanding GitHub Pages Deployment Models

When using GitHub Pages for hosting static sites built with Jekyll, the first fundamental decision you must make is whether to build a User Site or a Project Site. This choice significantly impacts how your URLs are structured, how your repository is named, and how you deploy themes like Mediumish.

Why This Distinction Matters

If you're trying to set up a blog using the Mediumish theme on GitHub Pages and wondering why it's not displaying properly or why the layout is broken, chances are you’ve misunderstood the difference between a user site and a project site. These two approaches use different repositories, folder structures, and base URLs.

What Is a User Site on GitHub Pages

A user site is a personal or organizational homepage that lives at a specific domain based on your GitHub username. For example:

• https://yourusername.github.io

To create a user site, you must name your repository exactly as yourusername.github.io.

Main Characteristics of User Sites

• Repository Name: Must be username.github.io.
• Branch: You typically use the main branch for publishing.
• URL Path: The website will be served directly from the root URL.
• No Base URL Needed: All site assets (CSS, images, JS) are referenced without a base path.

Benefits of User Sites

User sites are excellent for personal portfolios or blogs where you want the root domain to be clean and directly accessible.

Limitations of User Sites

• You can only have one user site per GitHub account.
• You need to be extra careful with relative paths if migrating themes like Mediumish that expect assets to reside in a subfolder.

What Is a Project Site on GitHub Pages

In contrast, a project site is associated with a specific GitHub repository and is hosted under your user site with a subpath URL. For example:

• https://yourusername.github.io/project-name

Main Characteristics of Project Sites

• Repository Name: Can be anything, such as my-blog or jekyll-mediumish.
• Branch: You often publish from gh-pages or docs branch, unless you're using GitHub Actions.
• URL Path: Your site is served from /project-name/ subdirectory.
• Base URL Required: Must configure baseurl in _config.yml to match the repo name.

Benefits of Project Sites

Project sites are ideal when you want to host multiple sites or demo apps from one GitHub account. It gives you freedom to create separate repositories with isolated deployments.

Limitations of Project Sites

• All links and assets need to account for the /project-name/ base path.
• You must remember to update baseurl and ensure that all internal links and assets are relative to it.

How This Affects Using the Jekyll Mediumish Theme

Now that you understand the structural differences between user and project sites, here’s how it affects your setup when deploying the Jekyll Mediumish Theme:

If You're Using a User Site

• Clone the Mediumish theme into username.github.io.
• Remove or leave baseurl as empty in _config.yml.
• Access the blog via https://username.github.io.

If You're Using a Project Site

• Clone the theme into a repo like jekyll-mediumish.
• Set baseurl: "/jekyll-mediumish" in your config.
• Use {{ site.baseurl }} consistently in your theme’s links and assets.

Common Mistakes and How to Fix Them

1. Missing or Incorrect Baseurl

This is one of the most frequent problems. If your CSS or images are broken on a project site, it’s likely due to a missing baseurl.

Solution:

Set baseurl: "/your-project-name" in your _config.yml and ensure all links use Liquid templates like {{ site.baseurl }}/assets/image.jpg.

2. Wrong Repository Naming for User Sites

Many beginners create a repo like blog expecting it to render as a user site. It doesn’t work that way.

Solution:

Rename the repository to match your GitHub Pages URL exactly, e.g., yourusername.github.io.

3. Publishing from the Wrong Branch

GitHub Pages serves different branches based on the site type. User sites require publishing from main, while project sites can use gh-pages.

Solution:

Set the correct branch in the GitHub Pages settings under your repository’s Settings → Pages.

How to Decide Which Type You Need

If you're unsure which one to use, here’s a simple rule of thumb:

• Choose a user site if you're creating a single personal or portfolio site, blog, or homepage.
• Choose a project site if you plan to build multiple separate projects or demos.

Example Scenario: Hosting Multiple Jekyll Blogs

Let’s say you want to host two blogs, each using the Jekyll Mediumish theme with their own content and identity. You cannot do this with just a user site, because you only get one root-level domain.

Solution:

Create two project repositories like blog-tech and blog-life, and deploy them with base URLs like:

• https://username.github.io/blog-tech
• https://username.github.io/blog-life

Final Recommendations for Mediumish Theme Users

• Always verify if the theme supports baseurl substitution for all links. Mediumish typically does.
• Use relative paths and Liquid templates wherever possible.
• Test both user and project deployment locally using bundle exec jekyll serve --baseurl "/project-name".

Conclusion

Choosing between a user site and a project site on GitHub Pages isn’t just a technical formality—it directly influences how your blog functions, appears, and scales. If you're deploying the Jekyll Mediumish theme, understanding the nuances of each deployment type ensures a smoother setup process and a polished final site.

Mastering these differences early will save you hours of debugging and help you create a seamless blogging experience with GitHub Pages and Jekyll themes.