404 Error - Second Repo not displaying Github Pages

I have read the theme’s documentation and gone over the Jekyll documentation. I have confirmed this is not a theme related issue. Github Pages documentation also isn’t helping overcome this specific issue.

I think my trouble is with how I’ve setup my Github repos to publish more than one Jekyll site.
Note: The repos I’m talking about are public.
Repo 1: anilgeorge04/minimal-cave
Repo 2: anilgeorge04/firststep

My Issue

My Repo 1 which uses the Minimal Mistakes theme to build a Jekyll site. I am getting a 404 error while accessing a Github Page outside of Repo 1.
I have also setup Github Pages to publish from the main branch on Repo 2.

The page seems to be loading fine according to Github Pages with a valid URL.

But the page throws me a 404 error. The link was working just fine at the start, until I configured my 404.md page on Repo 1.
To troubleshoot, I added a _config.yml file in Repo 2 based on the discussion on similar topics at Github Community. But, it continues to show up my 404 page configured on Repo 1.

More Details

My custom domain minimalcave.com is mapped (using CNAME) with Repo 1.

My Query

I think I’m missing something obvious here perhaps.
How can I successfully continue to host my other Github Pages, from other repos, using my custom domain followed by repo-name, without throwing up a 404 error?
Is there any exclusion in the _config file I can add? Or any inclusions in the front matter for my 404 page? Do I have to make any changes to either of the Github repo settings?

I’m learning Jekyll and web programming along the way, so I’m finding it difficult to troubleshoot further. Thanks for taking the time.

Can you summarize your problem in a line?

Or looks like you want to serve GH Page sites on

Which means they both need a CName setup and that might even conflict fighting for the root path, regardless of whether they have a sub path as a GH Pages site.

I don’t know what happens across two repos on the same custom domain.

Having 3 sites like this on github io domain is not a problem. Each will needs it’s own 404.html in the repo.


Hey @anilgeorge04 - welcome to the community.

Tacking on to @MichaelCurrin’s response…

There are probably a few different ways to accomplish what you want to do, but here’s the method I use:

  1. Repo 1 is set up as a User Page (docs)
    This means the repo name MUST be named <yourusername>.github.io.
    Add your CNAME in this repo and this repo only.
    Set up the custom domain in the repo’s settings on Github.com.

  2. Repo 2 is a Project Page
    The repo name can be anything you want really, just know that by default it will appear at the path customdomain.com/repo1name/.
    Your Jekyll _config.yml will have:

baseurl: /repo1name 
url: https://www.customdomain.com

If you want a live example, here are links to my production repos:
User Page: https://github.com/grantmakers/grantmakers.github.io
Project Page: https://github.com/grantmakers/profiles

Hope that helps steer you in the right direction!


Thanks for sharing. It looks like it is possible but you have to name the first repo as a user website.

Here are the two links I worked out from above. The second one I didn’t see actually listed at the top repo unfortunately so I had to infer it


Thanks @MichaelCurrin. Summarizing the problem in a line:

Can I publish a site with GitHub Pages from repo-n on https://customdomain.com/repo-n if my customdomain.com is published from a project site <username>/sample-repo and not from the <username>.github.io repo?

Thanks @ckruse for the welcome, the detailed response with examples and pointing me to the vocabulary on user site and project site.

So if I understand this correctly, I must add my CNAME only to the user site repo <username>.github.io and not in a project site repo if I want my other project sites to work at the path customdomain.com/repo-n/.

Separate, but related query to confirm my understanding is right
If I want to publish another site from another-repo to anothercustomdomain.com and not to customdomain.com/another-repo/ (assuming user site is configured):

  • I create another-repo and add CNAME anothercustomdomain.com here and setup the _config.yml file to take url: https://www.anothercustomdomain.com
  • This project site will be published on anothercustomdomain.com
  • If I do not add this CNAME file here, it will publish my default at customdomain.com/another-repo/

Thats exactly right @anilgeorge04.

Another way to think about it is to consider the default paths:

User site: username.github.io
Project site 1: username.github.io/repo1name
Project site 2: username.github.io/repo2name

If you want to use a custom domain instead of the default username.github.io you add a CNAME to the User site and Github Pages uses behind-the-scenes magic to change all subsequent Project sites to automatically use the custom domain.

But there’s nothing preventing you from adding a CNAME to an individual Project site to change the custom domain for that specific Project site.

Just be mindful of the Prohibited Uses section of the docs:

GitHub Pages is not intended for or allowed to be used as a free web hosting service to run your online business, e-commerce site, or any other website that is primarily directed at either facilitating commercial transactions or providing commercial software as a service (SaaS).

1 Like

I made the changes to both my repos and now the user site and project site work fine.
Also, I used another domain on a test project site repo and it worked.

Thanks @ckruse. The working is clear to me now.

1 Like