I created a no-touch QR Code menu using GitHub Pages, and I built different versions of the menu with various frameworks such as Next.js and Tailwind CSS, Astro, and React. The menu is Caribbean-inspired with Afro-Guyanese foods because that's my parent's birthplace.

• HTML menu
• Next.js and TailwindCSS website
• Astro website
• You can also check out the QR code generator I built with React at this link.

I used GitHub Pages to host each of these websites because GitHub Pages now makes it easy to publish websites built with any static site generator or framework.

I’ve been underutilizing GitHub Pages

Over the past three years, restaurants introduced a new era of innovation and hospitality by replacing physical menus with no-touch QR code menus. The rise of QR code menus made me happy because I'm a bit germaphobic. As I frequented various restaurants, I recognized they all had one thing in common: the restaurants stored their menus in S3 buckets, but it costs a few cents and cents add up. This made me curious why aren't developers using GitHub Pages to store something as simple as a PDF? Then, I realized I am also guilty of underutilizing GitHub Pages. Since I learned to code in 2018, I've only used GitHub Pages to host my first website, my first portfolio, and a failed blog. I've also used it to teach beginners how to publish their first website.

GitHub Pages is a powerful option for storing static content for the following reasons:

• It’s free.
• It makes collaboration easy. Anyone can open a pull request to update the site.
• Your repository syncs with any changes you made to your site.
• While GitHub Pages comes with a default domain name like, https://YOUR_USER_NAME.github.io/ , it supports custom domains.
• It uses customizable GitHub Action workflows for builds and deployments.
• Because Pages uses customizable GitHub Action workflows to build and deploy your code, developers have control over their authoring framework and deployment.

There's so much static content that we could quickly publish on GitHub Pages, but due to a lack of exposure, we've opted for other platforms as developers.

Everyone can use these templates!

One of my graduation requirements in Resilient Coder, a non-profit coding bootcamp, was to land at least one freelance client. I was stressed because it was my first paid project, and I probably should've used a template because it wasn't the best design, but it was a good learning experience.

Anyways, I made each version of my menu open source, so that means anyone can use it! If you're a Resilient Coder, a student in #100Devs, a freelance developer, or just overall curious, you can fork my code and tweak it however you want! I believe these templates could be helpful for folks building websites for mom-and-pop restaurants.

GitHub Repository for menu built with HTML and CSS

Please note that if you run these locally you will not see any images or a PDF. This is because of the way GitHub Pages handles paths once deployed.

GitHub Repository for menu built with Next.js and Tailwind

GitHub Repository for menu built with Astro

How to publish a website built with static HTML to GitHub Pages

After you create and store HTML in a repository, navigate to the settings tab for that repository.

Click Pages on the left sidebar

Under build and deployment, choose GitHub Actions

This will suggest a few workflows for you based on the code in your repository. You can choose Static HTML.

Clicking configure will lead you to a pre-made workflow. Feel free to review the YAML, tweak it to your preference, and commit the code.

Within a few seconds, your Action will start running. It will generate a URL and deploy your static site to GitHub Pages if successful.

Head over to your URL named yourusername.github.io/your_repo_name to check out your live website!

How to publish a website on GitHub Pages using a starter workflow

The team at GitHub made a few starter workflows available to you, so you don’t have to write them from scratch, and you can use them as examples to support deployments in other frameworks. Currently there are starter workflows for Next.js, Nuxt.js, Gatsby, Hugo, Jekyll, and HTML.

After you create and store Next.js, Nuxt.js, Gatsby, Hugo, Jekyll, or HTML in a repository, navigate to the settings tab for that repository.

Click Pages on the left sidebar

Under build and deployment, choose GitHub Actions

This will suggest a few workflows for you based on the code in your repository. You can choose the workflow that’s compatible with your codebase.

Clicking configure will lead you to a pre-made workflow. Feel free to review the YAML, tweak it to your preference, and commit the code.

Within a few seconds, your Action will start running. It will generate a URL and deploy your static site to GitHub Pages if successful.

Head over to your URL named yourusername.github.io/your_repo_name to check out your live website!

How to publish a website on GitHub Pages using a customized workflow

Please note that your repository must be public to publish your site on GitHub Pages.

After you write your code (using a framework or static generator of your choice) and store it in a repository, go to the settings tab for that repository.

Click Pages on the left sidebar

Under build and deployment, choose GitHub Actions

Create a folder at the root of your project called .github/workflows

Inside of your .github/workflows folder, create a customized workflow to deploy your specified framework to GitHub Pages (see examples in the section below):

Example workflow for Astro

name: Deploy Astro to GitHub Pages

    on:
     # Trigger the workflow every time you push to the `main` branch
      push:
        branches: [ main ]
      # Allows you to run this workflow manually from the Actions tab on GitHub.
      workflow_dispatch:

      # Allow this job to clone the repo and create a page deployment
    permissions:
      contents: read
      pages: write
      id-token: write

    jobs:
      build:
        runs-on: ubuntu-latest
        steps:
        - name: Check out your repository using git
          uses: actions/checkout@v2

        - name: Use Node.js 16
          uses: actions/setup-node@v2
          with:
            node-version: '16'
            cache: 'npm'

        # Not using npm? Change `npm ci` to `yarn install` or `pnpm i`
        - name: Install dependencies
          run: npm ci

        # Not using npm? Change `npm run build` to `yarn build` or `pnpm run build`
        - name: Build Astro
          run: npm run build --if-present

        - name: Upload artifact
          uses: actions/upload-pages-artifact@v1
          with:
            path: ./dist

      deploy:
        environment:
          name: github-pages
          url: ${{ steps.deployment.outputs.page_url }}
        runs-on: ubuntu-latest
        needs: build
        steps:
          - name: Deploy to GitHub Pages
            id: deployment
            uses: actions/deploy-pages@v1

Example workflow for React

    name: Deploy to React GitHub Pages

    on:
     # Trigger the workflow every time you push to the `main` branch
      push:
        branches: [ main ]
      # Allows you to run this workflow manually from the Actions tab on GitHub.
      workflow_dispatch:

      # Allow this job to clone the repo and create a page deployment
    permissions:
      contents: read
      pages: write
      id-token: write

    jobs:
      build:
        runs-on: ubuntu-latest
        steps:
        - name: Check out your repository using git
          uses: actions/checkout@v2

        - name: Use Node.js 16
          uses: actions/setup-node@v2
          with:
            node-version: '16'
            cache: 'npm'

        # Not using npm? Change `npm ci` to `yarn install` or `pnpm i`
        - name: Install dependencies
          run: npm ci

        # Not using npm? Change `npm run build` to `yarn build` or `pnpm run build`
        - name: Build React
          run: npm run build --if-present

        - name: Upload artifact
          uses: actions/upload-pages-artifact@v1
          with:
            path: ./build

      deploy:
        environment:
          name: github-pages
          url: ${{ steps.deployment.outputs.page_url }}
        runs-on: ubuntu-latest
        needs: build
        steps:
          - name: Deploy to GitHub Pages
            id: deployment
            uses: actions/deploy-pages@v1

Example template for any static generator of your choice

    name: Deploy to “your frameworks” GitHub Pages

    on:
     # Trigger the workflow every time you push to the `main` branch
      push:
        branches: [ main ]
      # Allows you to run this workflow manually from the Actions tab on GitHub.
      workflow_dispatch:

      # Allow this job to clone the repo and create a page deployment
    permissions:
      contents: read
      pages: write
      id-token: write

    jobs:
      build:
        runs-on: ubuntu-latest
        steps:
        - name: Check out your repository using git
          uses: actions/checkout@v2

        - name: Use “REPLACE WITH THE RUNTIME OF YOUR CHOICE”
          uses: “REPLACE WITH THE ACTION THAT SETS UP THE RUN TIME OF YOUR CHOICE”

        # Not using npm? Change `npm ci` to `yarn install` or `pnpm i`
        - name: Install dependencies
          run: “REPLACE WITH COMMANDS TO INSTALL DEPENDENCIES”

        # Not using npm? Change `npm run build` to `yarn build` or `pnpm run build`
        - name: Build “YOUR STATIC GENERATOR HERE”
          run: “REPLACE WITH YOUR BUILD COMMAND”

        - name: Upload artifact
          uses: actions/upload-pages-artifact@v1
          with:
            path: “REPLACE WITH YOUR BUILD OUTPUT FOLDER”

      deploy:
        environment:
          name: github-pages
          url: ${{ steps.deployment.outputs.page_url }}
        runs-on: ubuntu-latest
        needs: build
        steps:
          - name: Deploy to GitHub Pages
            id: deployment
            uses: actions/deploy-pages@v1

Within a few seconds, your Action will start running. It will generate a URL and deploy your static site to GitHub Pages if successful.

Head over to your URL named yourusername.github.io/your_repo_name to check out your live website!

Gotchas: handling asset paths

When I first published my site on GitHub Pages, I was confused and surprised that I couldn’t see any images or PDFs even though they were present when I locally hosted the site. This happened because GitHub Pages handles paths differently.

For example, if I have PDF living in this relative path: assets/pdfs/menu-food.pdf, then once hosted on GitHub Pages, update the new path to {“REPOSITORY NAME”}/assets/pdfs/menu-food.pdf

Learn more

• Watch this talk delivered by Tommy Byrd on Using GitHub Pages with Actions to deploy Hugo sites in seconds
• The repository and ReadMe for Deploy Pages
• GitHub’s changelog announcement

Thanks to those who helped me!

I didn’t do this project independently, so I can’t take all the credit.

I want to thank those who helped me design the template:

• Thank you, Ellie! You can find their website at https://holistictech.io/
• Thank you, cuocdoiprints for the illustrations! You can find their website at https://www.cuocdoiprints.com/

Also, thank you to those who watched and helped me code in Next.js on my Twitch stream:

• Thank you, AJ. You can follow him on Twitter at @ajcwebdev. He has a ton of excellent content around web3, Jamstack, and open source.
• Thank you, Mayank! You can check out their blog. They have a ton of deep frontend knowledge.
• Thank you, Ramon! You can check out his awesome Twitch streams, where he streams about cool topics like Web Assembly.
• Also, thanks to @trollinchief, @dfluxty, @firebox_hd, and anyone else who tuned in.

Thank you to my colleagues at GitHub like @tcbyrd, @yoannchaudet, and @dylansmith for answering all my silly questions about GitHub Pages, Astro, and Actions.

Watch this awesome YouTube short by Kedasha demonstrating how to use a customized workflow to deploy a static site generator to GitHub Pages!

I'd love your thoughts on the new customized workflows to deploy to GitHub Pages. Comment below! For more content like this, follow GitHub and me on DEV!