Deploying your site with GitHub Pages

In this guide we'll walk through the steps for setting up a GitHub Pages for your GitHub repository with GitHub Actions. With this setup, anytime you push to the designated branch, GitHub will automatically build your project with Greenwood and publish to GitHub Pages!

As a reference, the Project Evergreen website repository is configured using this exact setup.

Prerequisites

Following the steps outlined here, first make sure you have already:

1. Created a repo in the format <username>.github.io or <username>.github.io/<repo-name>
   • If using <username>.github.io/<repo-name>, make sure to set Greenwood's base path configuration to /<repo-name>, as you can see in this demo.
2. Greenwood installed and setup in your repository, ex.

   src/
     pages/
       index.md
   package.json
   

Setup

With the above in place, let's set everything up!

1. If you don't have a build script, let's add one to package.json to use in our GitHub Action

   {
     .
     .
   
     "scripts": {
       "build": "greenwood build"
     }
   }
   

2. Create a file called .github/workflows/gh-pages.yml in the repo

3. Now add this GitHub Action, making sure to use the correct branch name for your project; master, main, etc. (We're leveraging this action at the end for the actual auto deploy.)

   name: Deploy GitHub Pages
   
   on:
     push:
       branches:
         - main # change this to match your repo
   
   jobs:
   
     build-and-deploy:
       runs-on: ubuntu-20.04
   
       steps:
       - uses: actions/checkout@v2
       - uses: actions/setup-node@v3
         with:
           node-version: 18.15.0
   
       - name: Install Dependencies
         run: |
           npm ci # or replace with yarn, pnpm, etc
   
       - name: Build
         run: |
           npm run build
   
       - name: Deploy GitHub Pages
         uses: peaceiris/actions-gh-pages@v3
         if: ${{ github.ref == 'refs/heads/main' }} # change the branch name to match your repo
         with:
           github_token: ${{ secrets.GITHUB_TOKEN }}
           publish_dir: ./public
   

4. Now git commit that and push it to your repo!

If all was successful, you should now see a gh-pages branch in your repo with the output of the public/ directory committed to it. (your specific file output may differ, but it should match the output you see if you run greenwood build locally.)

You can see the status of any Action by going to the Actions tab of your repo

Now, configure your repository by going to your repo's Settings -> Pages and make the following changes.

1. Set the source branch to gh-pages
2. Set path to be /root

Next Steps

Now, everything should be setup so that on future pushes to the branch specified in the GitHub Actions workflow, GitHub pages should automatically build from the gh-pages branch and publish that. 🏆

Congrats, enjoy working on your website!! 🥳