Logo Questions Linux Laravel Mysql Ubuntu Git Menu
 

Github Pages - Maintaining Multiple versions

I need to host the documentation of multiple versions of my project (say 1.0, 2.0 and 3.0) and all are active (documentation)branches and we shall keep on adding improvements to all of these. Is it possible to use GitHub pages for this purpose?

Appreciate any help on this.

like image 662
Kasun Indrasiri Avatar asked Dec 04 '17 23:12

Kasun Indrasiri


People also ask

Can GitHub Pages be dynamic?

GitHub Pages doesn't support dynamic websites or anything requiring a backend or secret data. There are other sites that provide this kind of hosting, such as Netlify and Heroku, along with many others.

Can I have multiple GitHub Pages on one?

For each registered GitHub account (representing a user or an organization) you can register one User Page, but an unlimited Project pages. This User Page is a website that will have the domain name http://username.github.io or http://username.github.com where username is replaced by your GitHub username.


2 Answers

This is feasible using Github Actions along with a static site generator (SSG) of your choice such as VuePress, Gatsby, Jekyll etc.

In its simplest form, create a GH action to generate the static site folder of the branch/release, then push the folder to corresponding folder in the branch pointed to by GH pages, say gh-pages. One of the branches/releases should be pushed to root. GitHub Pages Deploy Action can be helpful. Lastly add a dropdown list of versions to your static website pointing to the matching folder. The list of items can be statically maintained or dynamically populated using GitHub API. The selected item depends on the current URL path.

Example:

To provide multi-version docs for a software product named NotifyBC,

  • input - docs folder of the product created by VuePress
  • output - gh-pages branch
  • GitHub action, with main branch pushed to root of gh-pages branch and releases pushed to version folder
  • dynamically populated dropdown list implemented in Vue component
  • rendered site powered by GH pages
like image 116
abbr Avatar answered Sep 22 '22 17:09

abbr


You can have a look at gh-pages-multi.

It is a small nodejs tool I wrote to push different versions of docs to subdirectories in a gh-pages branch. It also generates a index.html file listing those subdirectories.

It is fairly easy to integrate in a CI workflow if you want to automate building and pushing the docs.

Also note the "--no-history" option that will prevent bloating the git repo if your docs contain some built files or binary assets.

like image 37
Alban Mouton Avatar answered Sep 22 '22 17:09

Alban Mouton