DEV Community

Cover image for How to host a Hugo or Next.js site on GitHub Pages
Rizèl Scarlett for GitHub

Posted on • Edited on

How to host a Hugo or Next.js site on GitHub Pages

GitHub Pages now uses customizable GitHub Action workflows to build and deploy your code so that developers can control their authoring framework and deployment. 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.

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.

Let’s learn how to host static sites built with Hugo, Next.js, or Gatsby on GitHub Pages!

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.

Image description

Click Pages on the left sidebar

Image description

Under build and deployment, choose GitHub Actions

Image description

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.

Image description

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.

Image description

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

Image description

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

Image description

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

Example

Here's an example repository I built using this method

GitHub logo blackgirlbytes / blackgyalbites-nextjs

no touch restaurant menu template hosted on GitHub Pages

blackgyalbites

Template for No-touch Menus and Host Static Pages Built with Any Framework on GitHub Pages

screenshot of website with 3 buttons that read: food menu, drinks menu, and catering menu. on the right of it is a screenshot of the drinks menu

Website built with Next.js and Tailwind CSS to display restaurant menus when users scan a QR code.

Powered By GitHub Pages

This is a demonstration to show developers that they can build and host static websites using any framework. See more example frameworks hosted on GitHub Pages:

Link to live site: https://blackgirlbytes.github.io/blackgyalbites-nextjs/

Design and Development

All designs and elements are open source, available for free for anyone to use.

Owned by Rizel Scarlett (@blackgirlbytes)

Designed by The Holistic Technologist

Illustrations by Cuoc Doi Prints

Feel free to fork, copy, tweak, and use for any purpose. This project is completely open source, and under MIT license.

Menu Design Template: Canva

Download Assets & Design Elements: Google Drive

blackgirlbytes logo




Learn more


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!

Top comments (11)

Collapse
 
andyhaskell profile image
Andy Haskell

Great tutorial! I remember in 2015 teaching myself Angular.js being really excited to have some of my code running on a website. I'm interested in revisiting to see how that is these days with static site generators!

Collapse
 
blackgirlbytes profile image
Rizèl Scarlett

Thank you! GitHub Pages got an awesome refresh and works really well with any static generator now, which is great for beginners or anyone trying to spin something up quick. If you ever get a chance, try it out with Angular.

And this blog post is just an abridged version of this longer post that I wrote where I used multiple static site generators to build a QR code menu and deployed them to GitHub Pages: dev.to/github/create-a-no-touch-qr...

Collapse
 
thomasbnt profile image
Thomas Bnt

Next? How to deploy NuxtJS on GitHub pages? 🥳🤩

Collapse
 
blackgirlbytes profile image
Rizèl Scarlett

You can use the same strategy listed in this blog post to deploy a NuxtJS site to GitHub Pages!

Collapse
 
thomasbnt profile image
Thomas Bnt

Yeah I see the repository this afternoon! I will test that!

Collapse
 
jonrandy profile image
Jon Randy 🎖️

GitHub Pages Pages??

Collapse
 
blackgirlbytes profile image
Rizèl Scarlett

Um yes

Collapse
 
jonrandy profile image
Jon Randy 🎖️ • Edited

Maybe:

  • "GitHub Pages" Pages
  • GitHub Pages pages

Or best of all, just:

  • GitHub Pages

"GITHUB PAGES PAGES" just reads really badly. Took me maybe four or five reads to think that perhaps it wasn't a glaring error in the image.

Thread Thread
 
blackgirlbytes profile image
Rizèl Scarlett

oh im sorry. I didn't realize I wrote that. I'm doing too many things at once.

Thread Thread
 
blackgirlbytes profile image
Rizèl Scarlett

thanks for catching that

Thread Thread
 
blackgirlbytes profile image
Rizèl Scarlett

updated! @jonrandy

Next time, do you mind just kindly saying..hey I think you have a typo in your blog banner?

Thanks!