GitHub Pages

Below are instructions on multiple ways in which a GitHub page can be set up.

Static Pages

This is the simplest approach if you have some static files in your repo like:

/[repo]
  - index.html
  - styles.css

On your repo's top nav, go to Settings > Pages
- Set source branch to master (or main, or whatever your root branch is)
- Make sure the source folder is set to /(root)
- Click Save
- You'll see a message appear at the top in blue, stating that Your site is published. This is partially true, it's actually in the process of being published. If you go to provided link while the message is blue, you'll get stuck on a 404 page. Refresh the page until the message is green. Once it's green, then you can go to the provided link.

Build and deploy via an Action

The below will outline how to wire up an action that'll build and deploy code to a GH page

At the root of your repo run mkdir -p .github/workflows
Create the config file in that folder touch .github/workflows/gh-pages.yml

Contents of config

name: Build and Deploy GH Pages
on: [push, workflow_dispatch]
jobs:
  build-and-deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/[email protected]

      - name: Install and Build
        run: |
          npm install
          npm run build

      - name: Deploy
        uses: JamesIves/[email protected]
        with:
          branch: gh-pages
          folder: dist

Push up your changes
On the repo's top nav Actions > Workflows
- Your new workflow should now be available. On push or via a User manually triggering the build - it'll now install all modules, and build the dist. Then it'll deploy dist to the gh-pages branch.
Follow the settings instructions, but change the source branch to gh-pages.

Build and deploy versioned content via an Action

At the root of your repo run mkdir -p .github/workflows
Create the config file in that folder touch .github/workflows/versioned-gh-pages.yml

Contents of config

name: Versioned GH Pages
on:
  push:
    branches:
      - master
  workflow_dispatch:
    branches:
      - master
    inputs:
      version:
        description: 'Version (ex. "v1")'
jobs:
  deploy:
    runs-on: ubuntu-latest
    env:
      REPO_NAME: "${{ github.event.repository.name }}"
      # NOTE: The fallback version value (v<NUMBER>) should be updated only when
      # breaking changes occur. Changes like directory refactors, or functional
      # API changes.
      VERSION: "${{ github.event.inputs.version || 'v1' }}"
    steps:
      # https://github.com/actions/checkout
      - name: 🛎️ Checkout
        uses: actions/[email protected]

      # - Copy code over to a versioned folder
      # - Create a dynamic redirect file that points to the newest versioned folder
      # NOTE: Pages have a `max-age` of `600 (10 minutes)`
      - name: ⚙️ Build
        run: |
          mkdir -p "./dist/${VERSION}"
          rsync -av ./src/ "./dist/${VERSION}"
          echo "<head><meta http-equiv=\"Refresh\" content=\"0; url=/${REPO_NAME}/${VERSION}\" /></head>" > "./dist/index.html"

      # https://github.com/JamesIves/github-pages-deploy-action
      - name: 🚀 Deploy
        uses: JamesIves/[email protected]
        with:
          branch: gh-pages
          clean: false # disabling to keep previous versioned folders
          folder: "./dist"

Push up your changes
On the repo's top nav Actions > Workflows
- Your new workflow should now be available. On push or via a User manually triggering the build, it'll now:
  - Create a versioned dist path.
  - Sync code to that new path. You can replace the sync step, and build any content into that new path.
  - Create an index.html file that will redirect a User to the newest versioned code.
  - Then it'll deploy dist to the gh-pages branch.
Follow the settings instructions, but change the source branch to gh-pages.

the0neWhoKnocks/GitHub Pages.md

GitHub Pages

Static Pages

Build and deploy via an Action

Build and deploy versioned content via an Action