Migrate to GitHub Pages

[vpetersson]

The setup should be fairly straight forward:

• Create a GitHub Actions flow that builds the Docsify static pages
• Serve them over GitHub Pages. They will be served on https://nebraltd.github.io/Helium-Guides/ for now, but we will switch the domain over later.

After we're done, we need to make sure that no links changed from the old vs new setup.

References

• Easy way to create your Documentation site with Docsify and GitHub Pages
• How to create a documentation site with Docsify and GitHub Pages
• Old GitHub Pages issue

[vpetersson]

@salmanfarisvp Feel free to take a stab at this. Don't think it will be too complicated to be honest.

[salmanfarisvp]

@vpetersson Right now the https://nebraltd.github.io/Helium-Guides/ page is served from the pages branch, right? So I should modify that and make it work and check the URL first right?

Thanks for the resource!

[vpetersson]

No, I changed it to 'main':

[shawaj]

The only things we really need to do is add some redirects and some auto cache purging that is now possible with our Cloudflare enterprise account

[shawaj]

Added cache purging https://github.com/NebraLtd/Helium-Guides/commit/06b95889604b3e1d2554f99315a8ec44f6897698

Now just need to add redirects from the old domain structure to the new one. Can probably be done with a Cloudflare page rule I think

[shawaj]

FYI @vpetersson docsify is not a true static page generator. This is why the current setup does not work properly on pages.

What we need to do, after we have set up the page redirects, is change the setup back to hash routing: https://github.com/NebraLtd/Helium-Guides/blob/5211ebebaad4b89a4053e96e6d734188ae33fa19/docs/index.html#L57

This will allow it to work on pages

Alternative is to move to a true static site generator but that is probably one for the future IMO (unless there is a way to build docsify statically...but i don't think there is)

[shawaj]

Looks like static is on their roadmap for v5 https://github.com/docsifyjs/docsify/issues/1061

[shawaj]

For reference https://docsify.js.org/#/deploy?id=github-pages

[shawaj]

i just need to add the redirects and then we should be ready to switch over

You can see it at https://nebraltd.github.io/Helium-Guides/#/ (building from pages branch for testing so we dont break the production version)

Essentially we need to:

• [x] add auto cache purging
• [x] check how we are generating PDFs (https://github.com/NebraLtd/Helium-Guides/pull/230)
• [ ] add redirects to cloudflare
• [ ] merge #228
• [ ] change github pages settings to build from main branch
• [ ] add helium.nebra.com in github pages settings
• [ ] update DNS on cloudflare to point helium.nebra.com to github pages

[shawaj]

@vpetersson actually - the one thing i am not sure of with GH Pages is serving the PDFs.

Need to check how we are currently doing this on the VPS

[vpetersson]

@vpetersson actually - the one thing i am not sure of with GH Pages is serving the PDFs.

Need to check how we are currently doing this on the VPS

This is done using this script. That should be easy enough to incorporate in GitHub Actions.

[shawaj]

Ah ok thanks @vpetersson will try and get a github action set up for that 👍

[vpetersson]

Ah ok thanks @vpetersson will try and get a github action set up for that 👍

Let @salmanfarisvp take a stab at that instead.

[shawaj]

For reference https://github.com/pandoc/pandoc-action-example

[shawaj]

having trouble setting up the redirects...

[shawaj]

Been experimenting also with cloudflare pages https://646ee11a.helium-guides.pages.dev/ (doesn't seem to work very well either with docsify)

[salmanfarisvp]

@shawaj Did you switch the GitHub page serving to "page" branch? I'm testing the links now and I can see a few of them are broken and I'll fix it.

[shawaj]

@salmanfarisvp Yeah I changed it to pages branch just for testing so as not to break the existing site before switchover

If you have found links that aren't working, best thing is probably to create a draft PR to main branch with the updates which we can just merge when we switch over to Github pages

[shawaj]

In fact @salmanfarisvp maybe just add them to the PR #228 on pages branch

[salmanfarisvp]

@shawaj Internal and external links are checked and working fine.

[shawaj]

Fixed in https://github.com/NebraLtd/Helium-Guides/commit/9c26c8e8cf2ea9ca84fc4d219a556f28d791ea90