What makes this guide particularly helpful is that I'll teach you how to integrate with GitHub Actions, too. This means your application will be automatically deployed every time you push code to your GitHub repository.

We'll just focus on deployment rather than building the entire Next.js app from scratch. For our example project, we'll use one from a previous article I wrote on freeCodeCamp in my article How to Build 2048 Game in React. I recently upgraded the codebase to use React 18 and added the Next.js framework.

If you want to see the end result of before reading the whole article, you can check it here.

As I mentioned above, we're using a project I made in my previous tutorial – and so that you can use it here, you can find its source code on Github. Feel free to clone or fork this repository, and just follow the steps in the tutorial to make it with me.

Prerequisites

Before we start, make sure you know a little bit about React and Next.js. We'll also be using GitHub, so it's important to understand some basics. You don't have to be an expert, just have some basic experience with these things.

Brief Introduction

Today we are going to explore two new things – GitHub Actions and GitHub Pages. If you haven't heard of them, let me quickly explain:

GitHub Actions are like little workflows that can do tasks on your projects. It's like having a helper that automatically does things you tell it to do. You can use Actions to run tests, for quality checks, or to build your application. In our case, we're going to use these workflows to publish my 2048 Game on GitHub Pages.

Now, what are GitHub Pages? Think of them like a web hosting option for developers and open source projects. You can use GitHub Pages to share your portfolios, host websites of your open-source projects, or just publish your pet projects like we're doing today.

If you want to learn more, you can read more on their official websites:

• GitHub Actions
• GitHub Pages

Now let's get our hands dirty.

Step 1 – Activate GitHub Pages for Your Repository

To publish our Next.js application, we have to activate GitHub Pages for our repository. Let's navigate to the Settings tab (1 in the image below), select Pages from the menu on the left-hand side (2), and find the dropdown menu that allows us to specify the deployment Source (3).

GitHub Project Settings

Now let's change the deployment Source to GitHub Actions.

GitHub Project Settings – GitHub Pages configuration

From now on, our project has a dedicated page. We only need to create an action that will publish content there.

Step 2 – Configure the Next.js Build Process

Before deploying the Next.js app, it's important to change the build output. By default, Next.js uses Node.js to run the application, and this is incompatible with GitHub Pages.

GitHub Pages is designed to host static files, which means we can publish only HTML, CSS, JavaScript (and other static files) there. So we'll need to enable static page generation in Next.js.

To do so, we will change the output mode to export inside next.config.js:

/** @type {import('next').NextConfig} */
const nextConfig = {
  output: "export",  // <=== enables static exports
  reactStrictMode: true,
};

module.exports = nextConfig;

Now after running next build, Next.js will generate an out folder containing static assets for our application. In the next steps, we will take this directory and upload it to GitHub Pages.

Side note for seasoned Next.js developers: you can use getStaticProps and getStaticPaths to generate static files for each page in your pages directory.

Step 3 – Configure Base Path to Fix Missing Images

Github publishes Pages under a sub-path of a domain and takes the project name as a sub-path. It sounds confusing, so let's take a URL to my 2048 game as an example:

https://mateuszsokola.github.io/2048-in-react/

As you can see, Github assigned a dedicated subdomain for me called mateuszsokola (after my username). But the project is published under the sub-path, which in my case is /2048-in-react. Unfortunately, this will lead to issues with missing images and styles.

By default, Next.js maps all static assets the domain. This means that the favicon.ico file will be resolved to mateuszsokola.github.io/favicon.ico instead of mateuszsokola.github.io/2048-in-react/favicon.icon.

To fix this, we can set up a path prefix by adding basePath inside the next.config.js file:

/** @type {import('next').NextConfig} */
const nextConfig = {
  basePath: "/2048-in-react",
  output: "export",
  reactStrictMode: true,
};

module.exports = nextConfig;

In my case, it is /2048-in-react since my project is called 2048-in-react.
Remember to include the (/) at beginning of the path.

Step 4 – Configure Github Actions

Now it's time to set up Github Actions for Next.js deployment. Reusability is a good practice so I divided the deployment into two separate actions:

• setup-node action – This action is responsible for setting up Node.js and installing all dependencies. Having a standalone action for the Node.js setup enables us to reuse it for other pipelines. For example, in my 2048 Game, I have pipelines that run code linter and tests. Likely you will have more than one action as well.
• publish action – This action handles the build process and publishes the Next.js app to GitHub Pages each time we merge code into the main branch.

Now, you can understand why it's beneficial to split the deployment into two actions.

Let me begin by explaining the setup-node action. Here is the code:

# File: .github/workflows/setup-node/action.yml
name: setup-node
description: "Setup Node.js ⚙️ - Cache dependencies ⚡ - Install dependencies 🔧"
runs:
  using: "composite"
  steps:
    - name: Setup Node.js ⚙️
      uses: actions/setup-node@v4
      with:
        node-version: 20

    - name: Cache dependencies ⚡
      id: cache_dependencies
      uses: actions/cache@v3
      with:
        path: node_modules
        key: node-modules-${{ hashFiles('package-lock.json') }}

    - name: Install dependencies 🔧
      shell: bash
      if: steps.cache_dependencies.outputs.cache-hit != 'true'
      run: npm ci

Important: Put this file in the .github/workflows/setup-node directory in your project. Make sure to call the file action.yml.

What does this code do?

• It declares a composite action. The composite action allows you to bundle multiple workflow steps into a single action, combining multiple run commands into a single reusable action.
• It creates a new build environment and sets up Node.js 20 there.
• It installs npm dependencies and uses a caching mechanism to speed up this process.

These are the most important parts of the setup-node action. Now, let's move on to the last action, which is publish.

# File: .github/workflows/publish.yml
name: publish-to-github-pages
on:
  push:
    branches:
      - master

permissions:
  contents: read
  pages: write
  id-token: write

concurrency:
  group: "pages"
  cancel-in-progress: false

jobs:
  build:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout 🛎️
        uses: actions/checkout@v4

      - name: Setup Node.js ⚙️ - Cache dependencies ⚡ - Install dependencies 🔧
        uses: ./.github/workflows/setup-node

      - name: Setup Pages ⚙️
        uses: actions/configure-pages@v4
        with:
          static_site_generator: next

      - name: Build with Next.js 🏗️
        run: npx next build

      - name: Upload artifact 📡
        uses: actions/upload-pages-artifact@v3
        with:
          path: ./out

  deploy:
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}

    runs-on: ubuntu-latest
    needs: build

    steps:
      - name: Publish to GitHub Pages 🚀
        id: deployment
        uses: actions/deploy-pages@v4

Put this file in the .github/workflows directory in your project. You can name the file as you like – I called it publish.yml.

What does this code do?

• This action is executed when code is pushed or merged into the main branch.
• It uses the setup-node action to set up the environment.
• The action has two stages: in the first stage, the Next.js app is bundled. In the second stage, we upload the artifacts from the first stage to GitHub Pages.

These are the most important aspects of the deployment pipeline. I skipped the permissions and concurrency setup since they remain unchanged for all deployments.

Now, your action is ready to use.

Commit and Push

After committing and pushing your changes to the main branch, GitHub will automatically initiate the deployment to GitHub Pages.

To inspect the process, navigate to the Actions tab (1 in the image below), and select the publish-to-github-pages action from the menu on the left hand side (2). You will see a all your deployments on the screen (they are called workflows).

GitHub Actions – Workflows responsible for publishing to GitHub Pages

Now, we need to select the first one of those workflows, and you will see a two-stage deployment. In the deploy stage, you can find a link to your website on GitHub Pages.

GitHub Project Workflow – Successful deployment

Wrapping Up

Github Pages isn't sufficient for hosting websites with millions of views. But it's an excellent choice for building your portfolio or hosting a website for your open-source project.

Nowadays, there are many free options to host our websites, but I wanted to show you this alternative. GitHub Pages is built by developers for developers – you can consider it a developer's natural habitat. I think every developer should be familiar with it.

I hope this article will be a gentle push towards learning more about GitHub Actions. Feel free to experiment with different approaches and try to create your own. Every application needs to be shipped and consider this article just as a starting point.

Here are the resources:

• 2048 Game on Github Pages
• Source code on Github. It'd mean the world to me if you star ⭐ this repository.

If this article helped you, please let me know on Twitter. Educators, like me, often feel like we are speaking into a vacuum and nobody cares what we teach. A simple "shoutout" shows it was worth an effort and inspires me to work even harder to create more content like this.

Feel free to share this article on your social media.

Thank you.

If you wish to know more about me – My name is Matéush. I am a software engineer and digital nomad. I can say I have an extraordinary career. I lived in three different countries and worked in various environments from startups to large enterprises.

Recently I started to share advice on growing a software developer career. I believe I created my blog for my younger self — a bit lost, motivated to become one of the best developers, and seeking a path into the world of “big tech”.

In this article, we'll create an application using the latest version of Angular. Then we'll host it on the GitHub Pages static website service using the continuous integration tool Travis CI to deploy the application.

Prerequisites

Before you start, you need to install and configure the tools below to create the Angular application.

• Git: Git is a distributed version control system that we'll use to sync the repository.
• Node.js and npm: Node.js is a JavaScript code runtime software based on Google's V8 engine. npm is a package manager for Node.js (Node Package Manager). We'll use these to build and run the Angular application and install the libraries.
• Angular CLI: Angular CLI is a command line utility tool for Angular which we'll use to create the base structure of the Angular application.
• An IDE (like Visual Studio Code or WebStorm): an IDE (Integrated Development Environment) is a tool with a graphical interface that helps us develop applications. Here, we'll use one to develop the Angular application.

Getting started

Create and configure your account on GitHub

GitHub is a source code and file storage service with version control using the Git tool. And GitHub Pages is a static file hosting service using a public repository.

First, you'll need to create an account on GitHub if you don't have one already. Visit https://github.com/ and click on the button Sign up.

Fill in the fields for Username, Email address, and Password, click on the button Verify to solve the challenge, and then click on the button Create account.

Next, we'll generate the token that will be used in Travis CI. Click on the menu with the avatar and click on the menu Settings.

Click on the menu Developer settings.

Click on the menu Personal access tokens.

Click on the button Generate new token.

Fill in the field Note, select the option repo and click on the button Create token.

Copy the generated token. In my case, the token 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 was generated because this token will be configured in Travis CI.

Let's create the repository. Click on the menu with the avatar and click on the menu Your repositories.

Click on the button New.

Fill in the field Repository name and click on the button Create repository.

Ready! Account created, token generated, and repository https://github.com/rodrigokamada/angular-travisci created.

Create and configure your account on Travis CI

Travis CI is a deployment service integrated with GitHub.

First, you'll need to create a Travis CI account if you don't already have one. Visit https://travis-ci.com/ and click on the button Sign up.

Click on the button SIGN IN WITH GITHUB to sign in with your GitHub account.

If Travis CI requests permission to list the GitHub repositories, accept the request. Click on the repository link angular-travisci.

Let's set up the GitHub access token. Click on the menu More options and click on the menu Settings.

Fill in the field NAME with the value GITHUB_TOKEN, VALUE with the value of your token generated on GitHub, and click on the button Add.

Ready! Account created and repository configured.

Create your Angular application

Angular is a development platform for building Web, mobile, and desktop applications using HTML, CSS and TypeScript (JavaScript). Currently, Angular is at version 13 and Google is the main maintainer of the project.

Let's create the application with the Angular base structure using the @angular/cli with the route file and the SCSS style format.

? Would you like to add Angular routing? Yes
? Which stylesheet format would you like to use? SCSS   [ https://sass-lang.com/documentation/syntax#scss                ]
CREATE angular-travisci/README.md (1061 bytes)
CREATE angular-travisci/.editorconfig (274 bytes)
CREATE angular-travisci/.gitignore (604 bytes)
CREATE angular-travisci/angular.json (3267 bytes)
CREATE angular-travisci/package.json (1078 bytes)
CREATE angular-travisci/tsconfig.json (783 bytes)
CREATE angular-travisci/.browserslistrc (703 bytes)
CREATE angular-travisci/karma.conf.js (1433 bytes)
CREATE angular-travisci/tsconfig.app.json (287 bytes)
CREATE angular-travisci/tsconfig.spec.json (333 bytes)
CREATE angular-travisci/src/favicon.ico (948 bytes)
CREATE angular-travisci/src/index.html (301 bytes)
CREATE angular-travisci/src/main.ts (372 bytes)
CREATE angular-travisci/src/polyfills.ts (2820 bytes)
CREATE angular-travisci/src/styles.scss (80 bytes)
CREATE angular-travisci/src/test.ts (743 bytes)
CREATE angular-travisci/src/assets/.gitkeep (0 bytes)
CREATE angular-travisci/src/environments/environment.prod.ts (51 bytes)
CREATE angular-travisci/src/environments/environment.ts (658 bytes)
CREATE angular-travisci/src/app/app-routing.module.ts (245 bytes)
CREATE angular-travisci/src/app/app.module.ts (393 bytes)
CREATE angular-travisci/src/app/app.component.scss (0 bytes)
CREATE angular-travisci/src/app/app.component.html (23809 bytes)
CREATE angular-travisci/src/app/app.component.spec.ts (1087 bytes)
CREATE angular-travisci/src/app/app.component.ts (221 bytes)
✔ Packages installed successfully.
    Successfully initialized git.

Create the .travis.yml file.

touch .travis.yml

Configure the .travis.yml file with the content below:

notifications:
  email:
    recipients:
      - rodrigo@kamada.com.br

language: node_js

node_js:
  - 16

before_script:
  - npm install

script:
  - npm run test:headless

before_deploy:
  - npm run build:prod

deploy:
  provider: pages
  skip_cleanup: true
  github_token: $GITHUB_TOKEN
  local_dir: dist/angular-travisci
  on:
    branch: main

Change the package.json file and add the scripts below. Replace the rodrigokamada value with your GitHub username.

  "build:prod": "ng build --prod --base-href https://rodrigokamada.github.io/angular-travisci/",
  "test:headless": "ng test --watch=false --browsers=ChromeHeadless"

Change the src/app/app.component.spec.ts file and remove the tests should have as title 'angular-travisci' and should render title.

Run the test with the command below:

npm run test:headless

> angular-travisci@1.0.0 test:headless
> ng test --watch=false --browsers=ChromeHeadless

⠋ Generating browser application bundles (phase: setup)...Compiling @angular/core/testing : es2015 as esm2015
Compiling @angular/compiler/testing : es2015 as esm2015
Compiling @angular/platform-browser/testing : es2015 as esm2015
Compiling @angular/common/testing : es2015 as esm2015
Compiling @angular/platform-browser-dynamic/testing : es2015 as esm2015
Compiling @angular/router/testing : es2015 as esm2015
⠸ Generating browser application bundles (phase: building)...05 09 2021 19:40:04.329:INFO [karma-server]: Karma v6.3.4 server started at http://localhost:9876/
05 09 2021 19:40:04.331:INFO [launcher]: Launching browsers ChromeHeadless with concurrency unlimited
05 09 2021 19:40:04.369:INFO [launcher]: Starting browser ChromeHeadless
✔ Browser application bundle generation complete.
05 09 2021 19:40:09.704:INFO [Chrome Headless 92.0.4515.159 (Linux x86_64)]: Connected on socket NUtJhjavb1JvssqOAAAB with id 25989029
Chrome Headless 92.0.4515.159 (Linux x86_64): Executed 1 of 1 SUCCESS (0.068 secs / 0.042 secs)
TOTAL: 1 SUCCESS

Run the application with the command below. Access the URL http://localhost:4200/ and check if the application is working.

npm start

> angular-travisci@1.0.0 start
> ng serve

✔ Browser application bundle generation complete.

Initial Chunk Files | Names         |      Size
vendor.js           | vendor        |   2.39 MB
polyfills.js        | polyfills     | 128.51 kB
main.js             | main          |   8.89 kB
runtime.js          | runtime       |   6.63 kB
styles.css          | styles        |   1.18 kB

                    | Initial Total |   2.53 MB

Build at: 2021-09-05T22:35:38.010Z - Hash: a4cfc9149589386eca5b - Time: 39997ms

** Angular Live Development Server is listening on localhost:4200, open your browser on http://localhost:4200/ **


✔ Compiled successfully.

Build the application with the command below:

npm run build:prod

> angular-travisci@1.0.0 build:prod
> ng build --configuration production --base-href https://rodrigokamada.github.io/angular-travisci/

✔ Browser application bundle generation complete.
✔ Copying assets complete.
✔ Index html generation complete.

Initial Chunk Files           | Names         |      Size
main.c678fa8750e7c769.js      | main          | 177.63 kB
polyfills.6d7801353e02e327.js | polyfills     |  36.21 kB
runtime.b136bda8a38c4f2e.js   | runtime       |   1.06 kB
styles.ef46db3751d8e999.css   | styles        |   0 bytes

                              | Initial Total | 214.90 kB

Build at: 2021-09-05T22:42:19.525Z - Hash: 83bfffc079b083727ca4 - Time: 26030ms

Syncronize the application on the GitHub repository that you created.

Ready! After synchronizing the application on the GitHub repository, Travis CI builds the application and synchronizes on the branch gh-pages.

Access the URL https://rodrigokamada.github.io/angular-travisci/ and check if the application is working. Replace the rodrigokamada value with your GitHub username.

And that's it! The application repository is available at https://github.com/rodrigokamada/angular-travisci.

Conclusion

Summarizing what was covered in this article:

• We created an account on GitHub.
• We created an access token on GitHub.
• We created a repository on GitHub.
• We created an account on Travis CI.
• We configured the GitHub access token on Travis CI.
• We create an Angular application.

You can use this article to create your personal website and have an online portfolio.

Thank you for reading and I hope you enjoyed the article!

To stay updated whenever I post new articles, follow me on Twitter.

This tutorial was posted on my blog in Portuguese.

You have finished creating your HTML website and you're feeling proud of your hard work. But there is one thing that is still missing: you have no idea how to publish your website.

In this tutorial, you will learn how to publish an HTML website using two popular platforms – Netlify and GitHub.

Before we start, make sure that you have a GitHub account because you will need to host your repository (your source code) on GitHub. Without it, you won't be able to publish your HTML website following this tutorial.

How to Publish a Website on Netlify

The first method we're going to explore is how to publish your website on Netlify.

Netlify is a platform for hosting websites. It is easy to host sites on Netlify as you don't need to configure it manually – and best of all, it's free. If you haven't signed up for an account, now is a good time to do so.

Here's the step-by-step process of publishing your website on Netlify:

Step 1: Add your new site

Once you've logged in, it will take you to a home dashboard. Click the New site from git button to add your new website to Netlify.

Step 2: Link to your GitHub

When you click the New site from git button, it will take you to the "Create a new site" page. Make sure that you push your repository on GitHub so that Netlify can link to your GitHub account.

Click the GitHub button as shown in the screenshot below:

Step 3: Authorize Netlify

Next, click the Authorize Netlify by Netlify button. This permission is needed so that both Netlify and GitHub can connect.

Step 4: Select your repository

Once you grant permission to Netlify, you can see a list of all your repositories. Select your website to publish. You can find it by either scrolling down the list or using the search bar to narrow down the list.

Step 5: Configure your settings

After selecting your website, you will be prompted to configure the settings for deploying the website. Since your website is simply a static one, there's not much to do here. Just click Deploy site to continue.

Step 6: Publish your website

Your website is now ready to publish! Netlify will do the rest of the work for you, and it will only take a minute or so to complete the process.

Now you are done! Your new website is published, and you can view it by clicking the green link.

Right now, your URL looks random, but you can edit it by clicking the Site settings button and then the Change site name button.

Congratulation on publishing your first new website! Now we'll learn how to publish a website with GitHub.

How to Publish a Website on GitHub

The second method we'll look at uses GitHub to publish your site. GitHub is a platform for storing, tracking, and managing project source code. It is also where you can publish your HTML website – and like Netlify, it is free to host here.

Here's the step-by-step process of publishing your website on GitHub:

Note: You can only publish your website on GitHub if you set the repository's visibility to public. If you want to deploy a website while it is private, upgrade your account to Pro or use Netlify to host there instead.

Step 1: Go to your website's repository

After you've logged in, go to the repository on the left sidebar and select the one you want to publish.

Step 2: Select the settings

In your repository, click the Settings link, and it will take you to the repository's settings page.

Step 3: Go to GitHub Pages

When you're in a repository's settings, scroll down a bit until you see the Pages link on the left sidebar. Click it, and it will lead you to GitHub Pages.

Step 4: Select the branch

In the source section, click the dropdown and select the master branch and save it. Depending on how you name it, it can be master or main.

Step 5: All done

And you are done! Your website will be published, and it will take only a minute or so to complete the process. Refresh the page, and you will see a link to your newly published website.

Conclusion

I hope you've found this tutorial helpful. You have learned how to publish your HTML website with Netlify and GitHub. Now you can go ahead and show the world of your incredible work.

If you're looking to learn more about modern web-development, I invite you to join my Full-Stack JavaScript Course or read more articles about JS, HTML and CSS at my programming blog.

A project that just uses JavaScript, HTML and CSS is simple to host on GitHub Pages. Projects that are built in React, Vue or Angular require some configurations, though. This gives anyone who visits your application online the same experience you have when you build the application locally.

In this article, I'll show you how to create a simple React application that uses routing and then we'll learn how to upload it to GitHub Pages. We will give special attention to the routing part since it is important to understand and implement.

⚠️ This article assumes you have some knowledge of React and Git.

Prerequisites

You need to have Node, yarn and npm installed on your machine. To check if they are installed, open up a terminal window and type the following:

npm -v
yarn -v
node -v

If these commands print out a version number in the terminal, you are good to go. If not, you need to go ahead and install what is missing.

• Node (contains npm)
• Yarn

We will also need to create a repository on GitHub. Head over to your account and create a new repository. Choose whichever name you deem fit for this project, but I will go with starter-project for the rest of this article.

To create our project, we will be using create-react-app. It is a package that lets you create a single page application with ease. To create a project, you need to type the following in the terminal:

npx create-react-app starter-project

Once the operation finishes, you will have a boilerplate React project, ready to go. To see if it works properly, head into the directory of the project (in our example it would be starter-project) and run the command:

yarn start

If everything runs properly, you will see a message in the terminal that says that your application is running on a local server at this address: http://localhost:3000

If you head over there in your browser, you will see this:

How to Deploy Your Project to GitHub

You may have noticed that we have not created any repository in GitHub. So before we move on, we must have our project uploaded there. Head over to your GitHub account and create a repository with the same name as the React project.

☝️ Make sure to mark your repository as public. If you mark it as private, you won't be able to use GitHub Pages.

We are going to add this repository as a remote to our project. To do that, in the terminal, type:

git remote add <name-of-remote> <url-of-repository>

So, in our case, the command looks like this:

git remote add origin https://github.com/TomerPacific/starter-project

It's important to call the remote origin as it will be used in our deploy process.

After executing the command above, we can't push our code yet. First, we need to configure an upstream branch and set the remote as origin.

 git push --set-upstream origin master

Now, we can push all our project's files to our repository.

In order for us to be able to upload our built application to GitHub Pages, we first need to install the gh-pages package.

yarn add gh-pages

This package will help us to deploy our code to the gh-pages branch which will be used to host our application on GitHub Pages.

To allow us to use the gh-pages package properly, we need to add two keys to our scripts value in the package.json file:

"scripts": {
    "start": "react-scripts start",
    "predeploy": "npm run build", <----------- #1
    "deploy": "gh-pages -d build", <---------- #2
    "build": "react-scripts build",
    "test": "react-scripts test",
    "eject": "react-scripts eject"
  },

Next, we need to modify our package.json file by adding the homepage field. This field is used by React to figure out the root URL in the built HTML file. In it, we will put the URL of our GitHub repository.

{
  "name": "starter-project",
  "homepage": "https://tomerpacific.github.io/starter-project/", <----
  "version": "0.1.0",
  /....
}

To deploy our application, type the following in the terminal:

npm run deploy

Running the command above takes care of building your application and pushing it to a branch called gh-pages, which GitHub uses to link with GitHub Pages.

🚧 If you did not name your remote origin, you will get an error during this phase stating that: Failed to get remote.origin.url (task must either be run in a git repository with a configured origin remote or must be configured with the "repo" option).

You will know that the process was successful if at the end of it you see the word Published. We can now head to our GitHub repository under Settings and scroll down to the GitHub Pages section.

If you see a message similar to the one above, it means your application is now hosted successfully on GitHub Pages.

_Photo by [Unsplash](https://unsplash.com/@noahglynn?utm_source=ghost&utm_medium=referral&utm_campaign=api-credit">Noah Glynn / <a href="https://unsplash.com/?utm_source=ghost&utm_medium=referral&utmcampaign=api-credit)

Routing in React

So far - so good:

1. We have a basic React application that is hosted on GitHub Pages
2. We also have a streamlined process to deploy it when we want to make changes

But since the purpose of this article is to show a more complex application than the one we initially created, we will be discussing routing.

One component that is missing from out application is navigation. Our application won't just be one page, it will probably have many pages. So, how will users be able to navigate between them?

Routing is the practice of selecting a path for traffic in a network. Or in more basic terms, what happens when you click on a link inside of a webpage and where you get redirected.

React is a library, and it does not contain everything you need for your application out of the box (in our case, routing). Therefore, we will need to install react router.

React router has different components for web applications and for native ones. Since we are building a web application, we will be using react-router-dom.

yarn add react-router-dom

To make use of routing in our application, let's create a navigation element which will be visible at the top of the application. We will be adding this inside our App.js file and replacing the current HTML markup that is there.

 <div>
     <nav>
         <ul id="navigation">
             <li>
                 <Link to="/">Home</Link>
             </li>
             <li>
                 <Link to="/about">About</Link>
             </li>
             <li>
                 <Link to="/contact">Contact</Link>
             </li>
         </ul>
     </nav>
</div>

Usually, in a non React project, we would put a relative path to our HTML pages for each section. That way, the browser knows where to load the data from.

But in our project, we won't have different HTML pages for each section. We will just load a different component. The markup that used to be inside of App.js will now be found inside of a component called Home.

import './App.css';
import React from 'react';
import logo from './logo.svg';

class Home extends React.Component {
    render() {
        return (
            <div className="App">
                <header className="App-header">
                <img src={logo} className="App-logo" alt="logo" />
                <p>
                    Edit <code>src/App.js</code> and save to reload.
                </p>
                <a
                    className="App-link"
                    href="https://reactjs.org"
                    target="_blank"
                    rel="noopener noreferrer"
                >
                    Learn React
                </a>
                </header>
            </div>

        );
    }

}

export default Home;

As we have created three sections in our navgiation and taken care of the home section, let's give another example with the About section.

We'll create a new file called About.jsx that will hold our template and code for the about section.

import React from 'react';

const divStyle = {
    color:'white'
};

class About extends React.Component {

    render() {
        return (
            <div style={divStyle}>
                <h2>About Page</h2>
                <main>
                    <p>This section contains information about...</p>
                </main>
            </div>
        )
    }
}



export default About;

You may be asking yourself, how will the application know to redirect the user once they click on the about link? For that we will use a component called Route.

The Route is one of the most important components in react-router because it lets you render different component based on the path of the URL. For our project, we will use the code below inside of App.js just below the navigation markup.

<Switch>
    <Route exact path="/">
    <Home />
    </Route>
    <Route path="/about">
    <About />
    </Route>
</Switch>

You can see that we created two routes for home and about. The Switch component lets us group route components together and it will only match one of them.

Our combined App.js file looks like this:

import './App.css';
import React from 'react';
import { Route, Switch, Link } from "react-router-dom";
import About from './About';
import Home from './Home';

class App extends React.Component {
  render() {
      return (
        <div className="App">
          <div>
            <nav>
              <ul id="navigation">
                <li>
                  <Link to="/">Home</Link>
                </li>
                <li>
                <Link to="/about">About</Link>
                </li>
                <li>
                <Link to="/contact">Contact</Link>
                </li>
              </ul>
            </nav>
          </div>
            <Switch>
            <Route exact path="/">
              <Home />
            </Route>
            <Route path="/about">
              <About />
            </Route>
          </Switch>
          </div>
            );
  }
}

export default App;

One last thing we should do is wrap our entire project in a Router component. We need to do this because it enables us to use routing in our application. We will be using the BrowserRouter component as it uses HTML5's history API.

ReactDOM.render(
  <React.StrictMode>
    <BrowserRouter>
      <App />
    </BrowserRouter>
  </React.StrictMode>,
  document.getElementById('root')
);

If we run things locally, everything seems to work. Let's deploy our augmented project to GitHub Pages and see what the result is.

How to Handle Routing Using HashRouter

At first glance, everything seems to be working fine. But when you try refreshing the page or navigating through the browser itself, you'll keep getting 404 errors.

Why does this happen? Because GitHub Pages does not support browser history like your browser does. In our case, the route https://tomerpacific.github.io/starter-project/about doesn't help GitHub Pages understand where to point the user (since it is a frontend route).

To overcome this problem, we need to use a Hash Router instead of a Browser Router in our application. This type of router uses the hash portion of the URL to keep the UI in sync with the URL.

ReactDOM.render(
  <React.StrictMode>
    <HashRouter>
      <App />
    </HashRouter>
  </React.StrictMode>,
  document.getElementById('root')
);

You can read more about this here.

Deploy your application again and you'll be satisfied with the result. No more 404 errors.

This article was inspired by working on a project of mine. You can view it below:

And you can see the source code here:

Sir Issac Newton discovered the law of gravity when practicing “social distancing” during the Plague. What will YOU do? One silver lining of quarantine is that all this free time brings out the entrepreneur spirit and creativity in us.

However, especially because of the quarantine, now more than ever, any new idea or project must have a web site. Traditional CMS solutions like Wordpress, Squarespace, or Wix are difficult to use, look dated, are expensive, or all of the above!

We wanted to create a web site that has a sophisticated look and feel, yet is easy to customize. A non-technical person should be able to edit the source files and see the changes appear on the live web site in a few minutes. Ideally, it should also be free (forever free, not just free-for-now), and can scale to handle millions of visitors if it becomes popular.

Is this possible?

In this short article, I will walk you through a solution based on the Hugo framework, GitHub Pages, and GitHub Actions. You can get up and running with your shiny new website by the end of this article.

It is so easy that my 9-year-old son did it. He now manages a web site for his fictional country called Arenztopia. Check out the back story.

TL;DR

If you just want to get started with a working web site as soon as possible, first make sure that you have a free GitHub account.

Go to this GitHub repository, and click on the “Fork” button on the top right, and fork it to your own account.

Go to your forked repository, and click on the Actions tab. You will see a message like the one in the picture below. Click on the “I understand my workflows …” button.

Go to the Settings tab of your repository, and then scroll down to GitHub Pages. Re-select the gh-pages from the dropdown for the web site to build.

Go to the Code tab of the repository, open the config.toml file, and edit it. Change its title attribute to something else, and click on the “Commit changes” button at the bottom. We need this step to trigger the workflow at the new repository.

Wait a few minutes, go to the “published at” web address at GitHub Pages and you will see the template web site.

Next, you can customize the site by editing the config.toml file and the files in the content folder. Go to the “Add your own content” section at the end of this article to see how. You can check out the instructions for the Ananke theme here.

That’s it for the quick start! In the next several sections, I will explain in more detail the concepts and processes.

Hugo basics

Older generation CMS solutions like Wordpress are too difficult to adapt to new web site designs, and commercially hosted solutions like SquareSpace are too expensive and not flexible enough. Static web site generators like Hugo offer a good balance among features, flexibility, and ease of authoring.

• Hugo web sites can be customized and modified through configuration files.

• New pages and content sections can be written in markdown instead of HTML. That makes content authoring much easier.

• There are many modern design themes to choose from.

• The output of Hugo is a static HTML web site that can be deployed on any low-cost hosting provider.

• Together with static web site hosting services like GitHub Pages and Netlify, they can offer a completely free solution.

The Hugo software distribution is available on all major operating systems. You can learn about it here. But, since we will use GitHub Actions to automatically build our Hugo web sites, we do not actually need to install Hugo software here.

Here is how to do it.

Create a template website

First, select a Hugo theme. There are many. Some are geared toward web sites with one or more content web pages, while others are optimized for blog-like sites with timestamped posts.

Hugo themes

Find one you like, download a zip package or clone a GitHub repo, and unpack the theme into a folder. Let’s assume that the theme distribution is unpacked into a folder called my-theme. The following are commands in a Linux terminal. You could use the Terminal app on Mac or PowerShell on Windows.

Next, create your web site project directory on your computer.

$ mkdir -r my-site/themes

Copy the theme folder into your project.

$ cp -r my-theme my-site/themes

Next, copy the theme’s exampleSite to the project’s top-level directory.

$ cd my-site
$ cp -r themes/my-theme/exampleSite/* ./

Edit the config.toml in the project root directory my-site/ to point to the right theme.

baseURL = "/"themesDir = "themes"theme = "my-theme"

Next, create a GitHub repo called my-site, and push the my-site directory onto its master branch. Here are the steps for uploading files from GitHub’s web UI. Now we are ready to publish the theme example site.

For a Hugo-based system to be useable to a non-developer (or a young developer who has yet to master the command line tools), we must automate the process of building and deploying the static web site.

Automate deployment

In the GitHub project, go to Settings and enable GitHub Pages. Select the source to be the gh-pages branch.

Settings, GitHub Pages

Next, we create a GitHub Actions workflow to run the Hugo command on the source files from master branch, and push the generated HTML files to the gh-pages branch for publication. From the project’s Actions tab, click on the “set up a workflow yourself” button.

Set up a workflow yourself

The workflow is stored in the master branch as .github/workflows/main.yml file. The content of the file is as follows.

name: github pages

on:
  push:
    branches:
      - master

jobs:
  deploy:
    runs-on: ubuntu-18.04
    steps:
      - uses: actions/checkout@v1  # v2 does not have submodules option now
        # with:
        #   submodules: true

      - name: Setup Hugo
        uses: peaceiris/actions-hugo@v2
        with:
          hugo-version: '0.62.2'
          extended: true

      - name: Build
        run: hugo

      - name: Deploy
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./public

What happens here is that the web site authors and editors will change content and files on the master branch. Whenever new content is pushed to the master branch, the automated GitHub Actions workflow will set up the Hugo software, run the hugo command, and turn those files into HTML files for a static web site.

The HTML files are pushed to the gh-pages branch of the same repository. They will be published on the specified web address by GitHub Pages as configured.

Notice the cname attribute in the last line. That is the custom domain name we set up with GitHub Pages. If you do not have a custom domain name, just remove this line, and you can access your web site at the domain provided by GitHub Pages.

Now go to the web site, and you should see the theme’s default web page.

The HugoSerif template for one of our web sites.

Add your own content

To change the default theme web site to your own content, you just need to change the files on the master branch. Please refer to the documentation of your selected theme. In general, Hugo templates work like this:

• The web pages are authored in markdown format and the md files are in the content folder.

• Each md file has a header section with properties such as the page’s menu placement, priority, timestamp, excerpt, etc.

• The overall configuration, such as the menu items and properties used by multiple pages, are stored in the data folder.

• Static content such as raw HTML files, JavaScript files, and image files can be placed in the static folder.

In particular, here is how you customize the Ananke theme that comes with our template:

• The config.toml file allows you to configure the website title, social icons on all pages, and the big featured image on the home page.

• All images should be uploaded to the static/images folder.

• The content/_index.md file contains the text for the home page.

• To add pages to the site, you can just create markdown files in the content folder. An example is the contact.md file. Notice that at the top of the file, there are attributes to control whether this page should be on the website menu.

• To add articles to the site, you can create markdown files in the content/post folder. Those are blog-like content articles that have dates and titles at the top. The most recent two articles will show up on the home page.

If you are interested in learning more and see how we did it, you can watch our progress at

• The Country of Arenztopia [GitHub] [Web site]

• Second State blog [GitHub] [Web site]

Good luck and stay healthy!

About the author

Dr. Michael Yuan is the author of 5 books on software engineering. His latest book Building Blockchain Apps was published by Addison-Wesley in Dec 2019. Dr. Yuan is the co-founder of Second State, a VC-funded startup that brings WebAssembly and Rust technologies to cloud, blockchain, and AI applications. It enables developers to deploy fast, safe, portable, and serverless Rust functions on Node.js.

Prior to Second State, Dr. Yuan was a long time open source contributor at Red Hat, JBoss, and Mozilla. Outside of software, Dr. Yuan is a Principal Investigator at the National Institutes of Health, with multiple research awards on cancer and public health research. He holds a PhD in astrophysics from the University of Texas at Austin.

Static sites have become all the rage, and with good reason – they are blazingly fast and, with an ever growing number of supported hosting services, pretty easy to set up.

I'm not going to go into all the who, what, when, where or why of static sites here. I'm assuming that you have at least a vague idea of what they are or just want to create your own site and don't care about the other details. Either way this post is for you.

First, I want you to know I'm writing this for as broad an audience as possible; you don't need any programming knowledge to follow along, but some familiarity with the command line and Git will help out a lot.

So how can you create a static site with GitHub in 10 minutes?

We will be working with two specific tools: GitHub Pages, which is specifically designed to serve static content, and a static content generator called Jekyll.

Jekyll is a Ruby gem for creating static sites easily, so you will need to have Ruby installed on your computer if you want to use Jekyll. If you have OSX you most likely already have a version of Ruby (although you may need to update it). If you don’t, or are on a Windows computer, you can learn more about installing it here: Installing Ruby.

With that out of the way, open up a new terminal widow and type gem install bundler jekyll. This will install Bundler (a Ruby package management tool) and Jekyll.

Once those gems (Ruby packages) have installed, type Jekyll new my-static-site (name it whatever you want) which will run Jekyll's generator to create your project in a new directory. After your site is created, hop into your newly created site directory by typing cd my-static-site (or cd whatever you called you project).

Open your project in a text editor and you will see several files and folders Jekyll created for you. Right now you only need to concern yourself with the Gemfile (not Gemfile.lock). The Gemfile is a Ruby file that manages all associated Ruby packages needed to run a project.

The file will contain a line with the Jekyll version, comment it out:

#gem "jekyll", "~> 4.0.0"

Then add this line:

gem "github-pages", group: :jekyll_plugins

There can be a lot of gotchas when you install the GitHub Pages gem – sometimes the gems it depends on are out of date or the gems you have locally installed are too modern for GitHub Pages.

I have found that this can make it difficult to build and test my Jekyll site locally. It may be easiest just to test your site locally and save building it until you are ready to deploy. However, at the time of this writing you can can specify these dependency versions in your Gemfile and Jekyll will work both locally and with GitHub Pages:

gem "jekyll", "~> 3.8.5"
gem "github-pages","~> 202" , group: :jekyll_plugins
group :jekyll_plugins do
  gem "jekyll-feed", "~> 0.11.0"
end

Thanks to Alex Waibel on StackOverflow for that most recent configuration.

To see your site in action, run bundle exec Jekyll serve in your command line. This will start a server and you can see your site by typing "localhost:4000" into the URL bar of a browser.

Voila! You have created a static site with Jekyll and you are in the project directory. You are about 50% done.

Lets get this online

Go to GitHub.com and sign up, or if you already have an account, select the “new” button and create a repository. It’s important that you name your repository after the link that your GitHub Pages account will be serving, which is your_username.github.io. For example my GitHub username is tfantina and my blog is tfantina.github.io, so my GitHub repo is named: "tfantina.github.io".

Back in your terminal window, push your Jekyll site from your computer up to GitHub by running the following commands:

git init
git remote add origin git@github.com:<your_github_username>/<your_github_repo_name>.git
git commit -am “Setting up Jekyll!”
git push -u origin master

(When substituting your username and project name you don't need the opening and closing <>).

Once your changes have been pushed to your repository you should have a working static site. This is because your're using the GitHub Pages gem and named your repository in such a way that GitHub understands you want to serve it with GitHub Pages.

You can confirm this either by visiting your site or by going into the settings tab on GitHub and scrolling to the pages section. You should see a green box showing where your site has been published:

You will also note that you can easily change your theme from in here as well. GitHub provides a few default themes for Jekyll, but of course you can also make your own.
If your site says it’s published but looks blank, you may need to do a hard refresh or try looking at your site in a private window. This may seem obvious, but it gets me almost every time I set up a new Jekyll instance.

If everything went according to plan your site should look something like this:

There you go – in just a few minutes you have created and deployed a static website with GitHub pages. But you probably want to be able to put some content on your page.

I promised this would only take ten minutes, so I won’t dive into all the details of pages, front matter, or the Liquid templating language. That’s a post for another day. But I will share how to create your first post.

Back in your text editor, open the “_posts” folder. There is already a post welcoming you to your new blog. Create a new markdown file and save it with a name in this format: YEAR-MONTH-DAY-TITLE.markdown (see below):

A Jekyll post contains two sections: front matter, and body.

The front matter gives specific instructions to Jekyll such as what the title of the post is going to be, which layout to use, and when the post was written.

Front matter is highly customizable. For example, I wanted my posts to have hero images, so I created a lead_image tag and placed some syntax in my layout to specifically check for lead images in each post’s front matter. The Liquid templating language makes it easy to pull content from front matter into your theme.

There's a lot more you can do with front matter, but let's start off with a generic example.

The default front matter looks like this:

—
layout: post 
title:  "Welcome to Jekyll!"
date:   2019-11-09 18:07:11 -0600
categories: jekyll update
—

• Layout tells Jekyll which layout you want the content to be shown on. You can have multiple layouts for different pages or post types.
• The post title
• The post date
• Categories, which are essentially tags. You can add as few or as many as you want separated by spaces.

After the front matter your post can be written in Markdown, which gives you lots of flexibility in writing your post content.

Once your post is finished save it and open up your terminal window.

git commit -am “Publishes first post
git push

After a minute (and maybe a refresh), you will be able to see your post.

Hopefully, you now have a working static site on GitHub Pages created with Jekyll! If you have any problems or questions please tweet @tfantina, or you can shoot me an email at contact@travisfantina.com.

With the general availability of GitHub Actions, we have a chance to programmatically access and preserve GitHub event data in our repository. Making the data part of the repository itself is a way of preserving it outside of GitHub. It also gives us the ability to feature the data on a front-facing website, such as with GitHub Pages.

And, if you’re like me, you can turn GitHub issue comments into an awesome 90s guestbook page.

No matter the usage, the principle concepts are the same. We can use Actions to access, preserve, and display GitHub event data - with just one workflow file. To illustrate the process, I’ll take you through the workflow code that makes my guestbook shine on.

For an introductory look at GitHub Actions including how workflows are triggered, see A lightweight, tool-agnostic CI/CD flow with GitHub Actions.

Accessing GitHub event data

An Action workflow runs in an environment with some default environment variables. A lot of convenient information is available here, including event data. The most complete way to access the event data is using the $GITHUB_EVENT_PATH variable, the path of the file with the complete JSON event payload.

The expanded path looks like /home/runner/work/_temp/_github_workflow/event.json and its data corresponds to its webhook event. You can find the documentation for webhook event data in GitHub REST API Event Types and Payloads. To make the JSON data available in the workflow environment, you can use a tool like jq to parse the event data and put it in an environment variable.

Below, I grab the comment ID from an issue comment event:

ID="$(jq '.comment.id' $GITHUB_EVENT_PATH)"

Most event data is also available via the github.event context variable without needing to parse JSON. The fields are accessed using dot notation, as in the example below where I grab the same comment ID:

ID=${{ github.event.comment.id }}

For my guestbook, I want to display entries with the user’s handle, and the date and time. I can capture this event data like so:

AUTHOR=${{ github.event.comment.user.login }}
DATE=${{ github.event.comment.created_at }}

Shell variables are handy for accessing data, however, they’re ephemeral. The workflow environment is created anew each run, and even shell variables set in one step do not persist to other steps. To persist the captured data, you have two options: use artifacts, or commit it to the repository.

Preserving event data: using artifacts

Using artifacts, you can persist data between workflow jobs without committing it to your repository. This is handy when, for example, you wish to transform or incorporate the data before putting it somewhere more permanent. It’s necessary to persist data between workflow jobs because:

Each job in a workflow runs in a fresh instance of the virtual environment. When the job completes, the runner terminates and deletes the instance of the virtual environment. (Persisting workflow data using artifacts)

Two actions assist with using artifacts: upload-artifact and download-artifact. You can use these actions to make files available to other jobs in the same workflow. For a full example, see passing data between jobs in a workflow.

The upload-artifact action’s action.yml contains an explanation of the keywords. The uploaded files are saved in .zip format. Another job in the same workflow run can use the download-artifact action to utilize the data in another step.

You can also manually download the archive on the workflow run page, under the repository’s Actions tab.

Persisting workflow data between jobs does not make any changes to the repository files, as the artifacts generated live only in the workflow environment.

Personally, being comfortable working in a shell environment, I see a narrow use case for artifacts, though I’d have been remiss not to mention them. Besides passing data between jobs, they could be useful for creating .zip format archives of, say, test output data. In the case of my guestbook example, I simply ran all the necessary steps in one job, negating any need for passing data between jobs.

Preserving event data: pushing workflow files to the repository

To preserve data captured in the workflow in the repository itself, it is necessary to add and push this data to the Git repository. You can do this in the workflow by creating new files with the data, or by appending data to existing files, using shell commands.

Creating files in the workflow

To work with the repository files in the workflow, use the checkout action to first get a copy to work with:

- uses: actions/checkout@master
  with:
    fetch-depth: 1

To add comments to my guestbook, I turn the event data captured in shell variables into proper files, using substitutions in shell parameter expansion to sanitize user input and translate newlines to paragraphs. I wrote previously about why user input should be treated carefully.

- name: Turn comment into file
  run: |
    ID=${{ github.event.comment.id }}
    AUTHOR=${{ github.event.comment.user.login }}
    DATE=${{ github.event.comment.created_at }}
    COMMENT=$(echo "${{ github.event.comment.body }}")
    NO_TAGS=${COMMENT//[<>]/\`}
    FOLDER=comments

    printf '%b\n' "<div class=\"comment\"><p>${AUTHOR} says:</p><p>${NO_TAGS//$'\n'/\<\/p\>\<p\>}</p><p>${DATE}</p></div>\r\n" > ${FOLDER}/${ID}.html

By using printf and directing its output with > to a new file, the event data is transformed into an HTML file, named with the comment ID number, that contains the captured event data. Formatted, it looks like:

<div class="comment">
  <p>victoriadrake says:</p>
  <p>This is a comment!</p>
  <p>2019-11-04T00:28:36Z</p>
</div>

When working with comments, one effect of naming files using the comment ID is that a new file with the same ID will overwrite the previous. This is handy for a guestbook, as it allows any edits to a comment to replace the original comment file.

If you’re using a static site generator like Hugo, you could build a Markdown format file, stick it in your content/ folder, and the regular site build will take care of the rest.

In the case of my simplistic guestbook, I have an extra step to consolidate the individual comment files into a page. Each time it runs, it overwrites the existing index.html with the header.html portion (>), then finds and appends (>>) all the comment files’ contents in descending order, and lastly appends the footer.html portion to end the page.

- name: Assemble page
  run: |
    cat header.html > index.html
    find comments/ -name "*.html" | sort -r | xargs -I % cat % >> index.html
    cat footer.html >> index.html

Committing changes to the repository

Since the checkout action is not quite the same as cloning the repository, at time of writing, there are some issues still to work around. A couple extra steps are necessary to pull, checkout, and successfully push changes back to the master branch, but this is pretty trivially done in the shell.

Below is the step that adds, commits, and pushes changes made by the workflow back to the repository’s master branch.

- name: Push changes to repo
  run: |
    REMOTE=https://${{ secrets.GITHUB_TOKEN }}@github.com/${{ github.repository }}
    git config user.email "${{ github.actor }}@users.noreply.github.com"
    git config user.name "${{ github.actor }}"

    git pull ${REMOTE}
    git checkout master
    git add .
    git status
    git commit -am "Add new comment"
    git push ${REMOTE} master

The remote, in fact, our repository, is specified using the github.repository context variable. For our workflow to be allowed to push to master, we use the secrets.GITHUB_TOKEN variable.

Since the workflow environment is shiny and newborn, we need to configure Git. In the above example, I’ve used the github.actor context variable to input the username of the account initiating the workflow. The email is similarly configured using the default noreply GitHub email address.

Displaying event data

Nov 6, 2019 correction: GitHub Actions requires a Personal Access Token to trigger a Pages site build.

If you're using GitHub Pages with the default secrets.GITHUB_TOKEN variable and without a site generator, pushing changes to the repository in the workflow will only update the repository files. The GitHub Pages build will fail with an error, "Your site is having problems building: Page build failed."

To enable Actions to trigger a Pages site build, you'll need to create a Personal Access Token. This token can be stored as a secret in the repository settings and passed into the workflow in place of the default secrets.GITHUB_TOKEN variable. I wrote more about Actions environment and variables in this post.

With the use of a Personal Access Token, a push initiated by the Actions workflow will also update the Pages site. You can see it for yourself by leaving a comment in my guestbook! The comment creation event triggers the workflow, which then takes around 30 seconds to a minute to run and update the guestbook page.

Where a site build is necessary for changes to be published, such as when using Hugo, an Action can do this too. However, in order to avoid creating unintended loops, one Action workflow will not trigger another. Instead, it's extremely convenient to handle the process of building the site with a Makefile, which any workflow can then run. Simply add running the Makefile as the final step in your workflow job, with the repository token where necessary:

- name: Run Makefile
  env:
    TOKEN: ${{ secrets.GITHUB_TOKEN }}
  run: make all

This ensures that the final step of your workflow builds and deploys the updated site.

No more event data horizon

GitHub Actions provides a neat way to capture and utilize event data so that it’s not only available within GitHub. The possibilities are only as limited as your imagination! Here are a few ideas for things this lets us create:

1. A public-facing issues board, where customers without GitHub accounts can view and give feedback on project issues.
2. An automatically-updating RSS feed of new issues, comments, or PRs for any repository.
3. A comments system for static sites, utilizing GitHub issue comments as an input method.
4. An awesome 90s guestbook page.

Did I mention I made a 90s guestbook page? My inner-Geocities-nerd is a little excited.