I recently decided to update my personal home page (a simple one-page HTML site using Jekyll) to try out Ignite, as I’d much prefer to maintain a Swift package over working directly with HTML.

Ignite is an open-source static site builder for Swift developers, created by Paul Hudson.

While working with Ignite is fairly straightforward, and there are plenty of excellent examples provided in the IgniteSamples repo, I ran into a couple speed bumps deploying via GitHub Pages.

Below, I’ll walk you through the steps to get your own static site up and running using Ignite and GitHub Pages.

Prerequisites

This guide expects you to already be familiar with Git, Swift and SPM. Also, you should have followed the steps to setup a personal GitHub Page using GitHub’s own documentation and have that repo cloned locally.

In doing so, you should be able to visit github-username.github.io and see a basic HTML page (replacing github-username with your own).

Setting up your Ignite home page

The simplest way to get started is to download the IgniteStarter project.

Add the contents of this project to the root directory of your personal GitHub Page repo you cloned locally.

Since this is a Swift Package, open the contents in Xcode and open the Site.swift file. Inside, change the value url property to match the url of your personal Github Page:

struct ExampleSite: Site {    
    var url = URL("github-username.github.io")
}

Once updated, build and run the IgniteStarter scheme in Xcode. This should generate a new Build/ folder in your project and at the top level should be an index.html file representing your home page.

Running your website locally

Before deploying to GitHub Pages, verify that you can run your website locally. In your terminal, navigate into the Build/ directory generated by Ignite and run the following:

 python3 -m http.server

The output of this command should include the port your local web server is running on (e.g. 8000). In your web browser, navigate to http://localhost:port and verify you can view your page.

Deploying to GitHub Pages

By default, GitHub Pages only deploys from either the root of a branch, or from a docs/ folder. Since our site live in the Build/ directory, there are a couple steps to take before successfully deploying to GitHub Pages:

Remove the index.html file from the root of your directory that you created when first setting up your GitHub Page
Open your .gitignore and remove the Build directory
In your GitHub Page repo, navigate to Settings → Pages → Build and deployment. Use the Source dropdown to switch from Deploy from a branch to GitHub Actions
Back in your terminal, in the root of your project, prepare a new workflow to deploy your page
```
mkdir -p .github/workflows && touch .github/workflows/static.yml
```

Open static.yml and paste the following, changing your default branch as necessary a. The important piece here is in the Upload artifact step. Instead of defaulting to the root directory, we’re pointing at the Build directory that contains our home page

# Simple workflow for deploying static content to GitHub Pages
name: Deploy static content to Pages

on:
  # Runs on pushes targeting the default branch
  push:
    branches: ["main"]

  # Allows you to run this workflow manually from the Actions tab
  workflow_dispatch:

# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
permissions:
  contents: read
  pages: write
  id-token: write

# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
concurrency:
  group: "pages"
  cancel-in-progress: false

jobs:
  # Single deploy job since we're just deploying
  deploy:
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4
      - name: Setup Pages
        uses: actions/configure-pages@v5
      - name: Upload artifact
        uses: actions/upload-pages-artifact@v3
        with:
          path: './Build'
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4

Push your changes up to GitHub and, once the deployment completes, visit your new Ignite-driven home page 🎉

Prerequisites#

Setting up your Ignite home page#

Running your website locally#

Deploying to GitHub Pages#

Prerequisites

Setting up your Ignite home page

Running your website locally

Deploying to GitHub Pages