Pages with custom subdomain and path

Hi

I am planning to use the Github pages for my products documentation.
I have seen that is possible to use my own domain or subdomain.

The way i am thinking it is:

  1. The subdomain docs.mysite.com will be the docs entry page, with links to the documentation for every product.
  2. A product will have a url such as docs.mysite.com/product1
  3. Each product has a github repo with a docs folder, that includes the documentation.

Questions:
Is it possible to host docs.mysite.com in my own server( just for the shake of the entry page) and use Github pages for each product’s docs i.e. docs.mysite.com/product1?

In that case, how should i configure the custom domains?
Any alternative approach is welcome.

Kind regards,
Sakis

Hello and welcome here!

The scenario you are describing will function just right if you let Pages handle traffic over your landing page too.

Now if you want to keep the landing page on your side you are going to be a bit on your own. It may be possible but is not something Pages was designed for and as such any solutions could be fragile and potentially break or come with few quirks. It is not something I would recommend.

First, Pages will not let you have docs.mysite.com/product1, docs.mysite.com/product2 and so on unless you also have a user/org Pages site setup with docs.mysite.com as a custom domain. But then in order for your product Pages sites to route properly, you would need to get your DNS to point at GitHub Pages and not your server.

If your own server supports reverse proxy, I suggest using this feature. You could keep your individual products Pages site on the github.io domain and just configure a reverse proxy to route on the subdomains of your server. We won’t be able to help you with individual server configurations, but here is how that would be done with NGINX (a popular server): NGINX Docs | NGINX Reverse Proxy.

Thanks for the reply.

I can accept having the entry page in 1 of the product/docs repo.
Though is it possible to have several repos pointing to the same subdomain ( docs.mysite.com) ?
In that case, can i set a unique path for each of them e.g docs.mysite.com/product1?

Thanks

Kind regards,
Sakis

If you create a user/org Pages site and associate it with the custom domain: docs.mysite.com, then all your other (public) Pages sites will route on that domain under the path: /repo-name.

1 Like