Nested documentation with GitHub Pages possible?

[fredahrens]

HI,

until recently we used our own server for publishing documentation. We now moved our main documentation to GitHub pages as it is just more convenient to get documentation changes published.

Additional documentation was published to subfolders of the main documentation (/tutorials, /releasenotes) - all maintained in separate Retype project repositories. Unfortunately, GitHub Pages doesn’t support this approach, publishing content from different repositories to the same domain (AFAIK).

Is there a solution for the following scenarios?

Scenario A - merging all projects into one repository

If we merge the different documentations into one GitHub repository, having tutorials and releasenotes in subfolders as separate Retype projects, how do I need to adjust the GitHub action for getting the separate projects in the subfolder built before getting them published via to GitHub Pages? Is this even possible? (btw I'm an absolute GitHub Actions noob and I'm still wondering how I managed to get a single project published in the first place)

Scenario B - publish from different repositories to the same GitHub Pages domain

Is there any non-documented trick to get separate repositories published to the same GitHub Pages domain to different subfolders?

Would it be possible to let Retype send its output to another repository's retype branch before it gets published from there to GitHub Pages?

[fredahrens]

I just went back using a normal web server. Each Retype project repository has now its own upload action that transfers the documentation built by retype-action.yml to dedicated folders on the web server via FTP.

GitHub Pages publishing of repositories to subfolders is no longer available after assigning a custom domain. This seems to work only if you keep using the default <user>.github.io domain for making your documentation accessible.

[geoffreymcgill]

You can have multiple retype-action.yml files that each build a separate Retype project within one GitHub repository, but as far as I know, GitHub Pages only supports hosting one website at a time.

What I think would be possible is to run multiple retype-action.yml files that each use the action-github-pages action and output to a different directory.

Then if you have multiple Retype projects, the hub setting could link each back to a main website or a custom documentation landing page.

I think it would be possible to have docs.example.com/tutorials and docs.example.com/releasenotes as two separate Retype projects all running from one GitHub repo and running in one GitHub Pages instance. Both projects could then each use the following project config to link back to the main domain:

hub:
  link: https://example.com/

If you are FTP'ing the Retype built files to another web server, maybe the Retype action-git-ftp can help.

Hope this helps.