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

user_2436109 0
Viewed 315

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.

github-pages github
2 Answers

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.

user_87008090

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:

Pages Settings of the umbrella Organisation Site

  1. 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'
  2. 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).
  3. 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:

Pages Settings 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:

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?

user_7079840
Related