Github Pages with single custom subdomain for multiple repositories (using paths)

Question

I have multiple Github Repositories. By all of them gh-pages are enabled, and the repositories are accessible via paths for example:

• username.github.io/repository1,
• username.github.io/repository2,
• ...

Now I'm trying to create a custom subdomain docs.foo.tld and to have all my repositories gh-pages to be accessible via

• docs.foo.tld/repository1
• docs.foo.tld/repository2
• ...

I have created a CNAME entry docs.foo.tld to username.github.io

But when I'm adding this custom domain (docs.foo.tld) in repository1 repository settings on github, the gh-pages are directly accessible via docs.foo.tld, not via docs.foo.tld/repository1

How I use all this repositories in the path segments /repository1, /repository2 when using same custom subdomain for all of them.

Also to note, when I try to add this custom subdomain to repository2, I get the exception as the CNAME is already taken.

Nisan

Strange, for me this just works, though I do get those warning emails. – Heredes

Answer 1

The CNAME and setting the custom domain should only be done in the .github.io repo.

Other repos should not contain a CNAME and you should not set the custom domain in the other repositories. Those settings are inherited from .github.io repo and setting them in the other repositories is overwriting the root site.

Just delete the CNAME records from the project repos, and remove the custom domain from the settings of the project repos. You may need to add the custom domain name back to the .github.io repo, but after that you should be all setup like you wish.

Lymphadenitis

Which one is the ".github.io" repo? Is this any of projects repositiories, e.g. project1. Or should this be some other separate repository. With some specific repository name, or content inside? – Nisan

Indeed, I have create a repositiory with the name foo.github.io in our organization foo, activated pages with CNAME docs.foo.tld, and now all the repositories are accessible via docs.foo.tld/repository1, .... Thanks – Nisan

This answer is correct. However, it's pretty hard to recognize it as such until you end up with the solution. My answer below https://mcmap.net/q/1615931/-github-pages-with-single-custom-subdomain-for-multiple-repositories-using-paths tells basically the same, with more details and pictures. – Conidium

Answer 2

I had the exact same problem, but with the root account being an Organisation, not a User site (but this makes no difference). The solution is surprisingly simple (I had many trials and errors):

1. If not yet done, create the special Organisation/User "umbrella" Site as per the doc by creating a git repository called myorg.github.io.
2. In the Settings of that repo, under the "Pages" tab, choose your custom domain docs.mydomain.com. See picture:

3. The content of this repo is up to you. Personally I use VitePress with a small script which deploys at the root of the gh-pages branch. The script includes the creation of a CNAME file at the project root, with the content `docs.mydomain.com'
4. Configure your DNS zone with your Internet Provider by adding a CNAME entry pointing to myorg.github.io. (note the trailing dot – your IP may or may not add it automatically for you).
5. Return to the Pages Settings of your GitHub umbrella repo, and check that the subdomain is validated (it may take a few minutes).

That's all for the umbrella docs site, whose content contains links to docs.mydomain.com/project1, docs.mydomain.com/project2 etc.

Now, here is the trick: there is no trick. In all of your real projects, simply deploy your documentation. You can do so in the docs subfolder or not, in either branch, that is, in the master or gh-pages one, it doesn't seem to matter.

If any, the docs/ part of the url will be replaced by project1/ etc. There is no need for a CNAME, and no need for another custom subdomain.

Here is the config of one my project:

See how GitHub indicates under which URL the site is published.

Here is my GitHub organisation and its umbrella site

and the results:

• https://docs.arcsecond.io
• https://docs.arcsecond.io/cli
• https://docs.arcsecond.io/oort

Bonus. If by any chance you configure your projects to have sub-subdomains (that's what I tried before finding the solution) – such as https://project1.docs.mydomain.com, the above configuration will also "work". That is, navigating to https://docs.mydomain.com/project1 will redirect you to https://project1.docs.mydomain.com

Internet is kind of amazing, isn't it?

Conidium

It is worth noting that this works for PUBLIC GitHub Pages. Seems it doesn't work for PRIVATE GitHub Pages at this time (June 2023). Each private GitHub Page can have a custom domain, but you can't have this nice generic approach with private pages (hope they change / fix soon)! – Huambo

Correct. In that context, given the documentation I produce is going public, it makes sense to have documentation-only public repos. But for mixed repos, if you don't want to expose everything, this wouldn't work. – Conidium