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.

How to Create a GitHub Account and Set Up a New Repository

Why Do You Need a GitHub Repository for a Jekyll Site?

GitHub is not only a version control system but also a free hosting platform for static websites using GitHub Pages. If you're building a Jekyll site, especially using the Mediumish theme, your journey begins with creating a GitHub repository. It becomes your workspace and deployment point. Without it, your Jekyll site won’t be online.

Understanding the Relationship Between GitHub and Jekyll

GitHub Pages is deeply integrated with Jekyll, allowing you to run Jekyll-based blogs or documentation sites directly from a GitHub repository. It processes the Jekyll files and renders them as a website. This integration simplifies publishing and eliminates the need for external web hosting or FTP uploads.

How to Create a GitHub Account

If you're new to GitHub, the first step is to sign up for an account. Here’s how to do it quickly and securely:

Step-by-Step Guide to Register on GitHub

• Go to https://github.com
• Click “Sign up” in the upper-right corner
• Enter a unique username, email, and password
• Verify your email address via the email GitHub sends
• Choose your plan — start with the free plan
• Complete the setup by answering a few onboarding questions or skip them

Security Tips for Your GitHub Account

Since your repository will be public or contain important files, follow these security practices:

• Enable two-factor authentication (2FA)
• Do not share your GitHub token or credentials with others
• Keep your email and password private

How to Set Up a New Repository for Your Jekyll Site

Once your GitHub account is ready, the next essential step is to create a repository. This is where all your Jekyll files — layout, content, theme, configuration — will live. Let’s walk through the process.

Creating a New GitHub Repository

• Click on your profile picture (top-right) and go to Your repositories
• Click “New” to start creating a new repo
• Repository name: Use a clear, lowercase name like my-mediumish-site
• Description: (Optional) something like “My personal blog using Jekyll Mediumish theme”
• Choose Public or Private: For GitHub Pages, public is preferred
• Initialize repository with a README — check this box
• Click Create repository

Naming Rules for GitHub Pages

If you want the repository to serve as your personal website, name it like this: username.github.io. If you plan to host it as a project site, you can name it whatever you want, like jekyll-mediumish-blog.

Example:

If your GitHub username is alexdoe, and you name the repo alexdoe.github.io, GitHub will automatically treat it as a personal site. Otherwise, the site will be accessible via https://alexdoe.github.io/repo-name/.

What Should You Add to Your Repository?

Before your site can be live, you need to add the Jekyll files. If you’re using the Mediumish theme, you can:

• Fork an existing Mediumish Jekyll template
• Clone it locally and push it to your repository
• Or manually upload files via GitHub’s interface

Recommended Folder Structure

Your repository should include these standard Jekyll components:

• _config.yml — configuration settings
• _posts/ — your blog articles
• _layouts/ — HTML layout templates
• _includes/ — reusable HTML snippets
• assets/ — CSS, JS, images
• index.html — homepage content

How to Connect Your Repository to GitHub Pages

After your repository has the necessary files, you can enable GitHub Pages:

Steps to Enable GitHub Pages

• Go to Settings of your repository
• Scroll down to “Pages” section
• Select the branch (usually main or master)
• Choose the root folder (leave as / or select /docs if you placed files there)
• Click Save

GitHub will display your site’s URL after a few seconds. Visit the link and check if your Mediumish Jekyll site loads properly.

Common Issues and How to Fix Them

Site Not Loading?

Check if:

• _config.yml exists and has the correct baseurl (for project sites)
• All folders and filenames follow Jekyll’s naming conventions
• You haven’t added unsupported plugins (GitHub Pages has limits)

Theme Not Displaying Properly?

Possible causes:

• You didn’t include the full Mediumish theme assets
• Missing or misconfigured assets/ or _includes/ folders
• Incorrect paths in index.html or layout files

How to Keep Your Repository Updated

Maintaining a Jekyll blog isn’t just about setup. You must regularly commit changes — new posts, config tweaks, or layout improvements. Here’s how:

Updating Directly via GitHub

You can:

• Edit or upload files directly via the web interface
• Use GitHub Desktop to sync local files with the repo
• Use Git from your terminal to push updates

Best Practices for Commits

• Use clear commit messages (e.g., “Add new blog post about SEO basics”)
• Push changes frequently to keep your live site updated
• Don’t edit config files unless necessary — test locally if possible

What’s Next After Setting Up the Repository?

Now that your GitHub repository is live and connected to GitHub Pages, you're ready to dive into customizing the Mediumish Jekyll theme. This includes editing the layout, writing blog posts, updating metadata, and optimizing for SEO — all of which we’ll cover in the next articles of this series.

Next Steps You Should Take

• Customize the theme's colors and branding
• Add content to the _posts folder
• Configure SEO fields in _config.yml
• Test the site responsiveness across devices

Final Thoughts

Setting up a GitHub account and creating your first repository is the gateway to publishing your own static website for free using Jekyll and GitHub Pages. This foundation allows you to build a professional blog or portfolio, and when combined with the Mediumish theme, you get a polished, modern layout with minimal setup. With this solid base, you’re ready to evolve your project into a fully functional, content-rich website.