Hugo and Neocities#

Decided to setup a static site with Hugo and deploy it to Neocities using GitHub actions.

Here’s how I did it:

Hugo setup#

NOTE: Follow Quick Start for up to date instructions.

Ubuntu setup#

sudo snap install hugo

Then followed the rest of the steps in Quick Start.

GitHub Workflow#

Create a .github/workflows directory under your hugo repo if it doesn’t already exist.

mkdir -p .github/workflows

Then save this under .github/workflows/hugo-neocities.yml:

name: Neocities

on:
  push:
    branches:
      - main  # Set a branch to deploy
  pull_request:

jobs:
  deploy:
    runs-on: ubuntu-22.04
    concurrency:
      group: ${{ github.workflow }}-${{ github.ref }}
    steps:
      - uses: actions/checkout@v4
        with:
          submodules: true  # Fetch Hugo themes (true OR recursive)
          fetch-depth: 0    # Fetch all history for .GitInfo and .Lastmod

      - name: Setup Hugo
        uses: peaceiris/actions-hugo@v3
        with:
          hugo-version: '0.119.0'
          # extended: true

      - name: Build
        run: hugo --minify

      - name: Deploy
        uses: bcomnes/deploy-to-neocities@v2
        with:
          api_token: ${{ secrets.NEOCITIES_API_TOKEN }}
          cleanup: false
          dist_dir: public

Add this to your git repo.

git add .github/workflows/hugo-neocities.yml
git commit -m "Add github workflow"

You’ll then need to get a Neocities API key by going to your site settings -> API.

On GitHub, go to your repo’s Settings, then under Security go to Secrets and variables -> Actions. Click “New repository secret”. Set the secret name to NEOCITIES_API_TOKEN and the value to the Neocities API key.

From now on, when you add new content and push to your remote GitHub repo, GitHub actions will generate the site and then upload it to Neocities.

git commit -am "New post"
git push -u origin main