How to host a Hugo or Next.js site on GitHub Pages
Tags: github, tutorial, nextjs, javascript
Published: 2022-08-12 00:50:00

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](https://github.com/actions/starter-workflows/tree/main/pages) 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](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/3raq26t4wdejjko3me2i.png)

**Click Pages on the left sidebar**

![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/g5hs463f7z9i5qf927c1.png)

**Under build and deployment, choose GitHub Actions**

![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/rcqhvagwy5q10kdx92uu.png)

**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](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/mslmt4sry4cg7rmcsss3.png)

**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](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/5i6ieyj56j28rgldk5pz.png)

**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](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/gvrj0siaezzapxtcdict.png)

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

![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/eys6qboy8v3d7xbd0vye.png)
## 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 blackgirlbytes/blackgyalbites-nextjs %}

## Learn more

* Watch this talk delivered by Tommy Byrd on [Using GitHub Pages with Actions to deploy Hugo sites in seconds](https://www.youtube.com/watch?v=Z_7RIuf_Z-Q)
* The [repository and ReadMe](https://github.com/actions/deploy-pages) for Deploy Pages
* GitHub’s [changelog](https://github.blog/changelog/2022-07-27-github-pages-custom-github-actions-workflows-beta/) announcement
* Official [GitHub Blog Post](https://github.blog/2022-08-10-github-pages-now-uses-actions-by-default/)

{% youtube Kq28yBigDYw %}
_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](https://dev.to/github) and [me](https://dev.to/blackgirlbytes) on DEV!_**