GitHub Actions for Hugo

This Hugo Setup Action can install Hugo to a virtual machine of GitHub Actions. Hugo extended version, Hugo Modules, Linux (Ubuntu), macOS, and Windows are supported.

From v2, this Hugo Setup Action has migrated to a JavaScript (TypeScript) action. We no longer build or pull a Hugo docker image. Thanks to this change, we can complete this action in less than a few seconds. (A docker base action was taking about 1 min or more execution time to build and pull a docker image.)

OS (runs-on)	ubuntu-latest, ubuntu-20.04, ubuntu-22.04	macos-latest	windows-2019
Support	✅️	✅️	✅️

Hugo type	Hugo Extended	Hugo Modules	Latest Hugo
Support	✅️	✅️	✅️

Table of Contents

• Getting started
  • ⭐️ Create your workflow
• Options
  • ⭐️ Use Hugo extended
  • ⭐️ Use the latest version of Hugo
• Tips
  • ⭐️ Caching Hugo Modules
  • ⭐️ Read Hugo version from file
  • ⭐️ Workflow for autoprefixer and postcss-cli
  • ⭐️ Workflow for asciidoctor
  • ⭐️ Non-ascii Filename
• CHANGELOG
• License
• About Maintainer
• Maintainer Notes

Getting started

⭐️ Create your workflow

An example workflow .github/workflows/gh-pages.yml with GitHub Actions for GitHub Pages. For the first deployment, we have to do this operation: First Deployment with GITHUB_TOKEN - peaceiris/actions-gh-pages

name: GitHub Pages

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: peaceiris/actions-gh-pages@v3
        if: github.ref == 'refs/heads/main'
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./public

Back to TOC ☝️

Options

⭐️ Use Hugo extended

Set extended: true to use a Hugo extended version.

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

⭐️ Use the latest version of Hugo

Set hugo-version: 'latest' to use the latest version of Hugo.

- name: Setup Hugo
  uses: peaceiris/actions-hugo@v3
  with:
    hugo-version: 'latest'

This action fetches the latest version of Hugo by hugo | Homebrew Formulae

Back to TOC ☝️

Tips

⭐️ Caching Hugo Modules

Insert a cache step before site-building as follows.

First, to maximize compatibility with all Hugo versions, let's define the variable HUGO_CACHEDIR:

# * ...

jobs:
  deploy:
    runs-on: ubuntu-22.04
    env:
      HUGO_CACHEDIR: /tmp/hugo_cache # <- Define the env variable here, so that Hugo's cache dir is now predictible in your workflow and doesn't depend on the Hugo's version you're using.

# * ...

Now, let's add the cache action call just above the Build step:

- uses: actions/cache@v4
  with:
    path: ${{ env.HUGO_CACHEDIR }} # <- Use the same env variable just right here
    key: ${{ runner.os }}-hugomod-${{ hashFiles('**/go.sum') }}
    restore-keys: |
      ${{ runner.os }}-hugomod-

- name: Build
  run: hugo --minify

Back to TOC ☝️

⭐️ Read Hugo version from file

How to sync a Hugo version between a Docker Compose and a GitHub Actions workflow via .env file.

Write a HUGO_VERSION to the .env file like the following and push it to a remote branch.

HUGO_VERSION=0.119.0

Next, add a step to read a Hugo version from the .env file.

    - name: Read .env
      id: hugo-version
      run: |
        . ./.env
        echo "HUGO_VERSION=${HUGO_VERSION}" >> "${GITHUB_OUTPUT}"

    - name: Setup Hugo
      uses: peaceiris/actions-hugo@v3
      with:
        hugo-version: '${{ steps.hugo-version.outputs.HUGO_VERSION }}'
        extended: true

Here is a docker-compose.yml example.

version: '3'

services:
  hugo:
    container_name: hugo
    image: "peaceiris/hugo:v${HUGO_VERSION}"
    # image: peaceiris/hugo:v${HUGO_VERSION}-mod   # Hugo Modules
    # image: peaceiris/hugo:v${HUGO_VERSION}-full  # Hugo Modules and Node.js
    ports:
      - 1313:1313
    volumes:
      - ${PWD}:/src
    command:
      - server
      - --bind=0.0.0.0
      - --buildDrafts

The alpine base Hugo Docker image is provided on the following repository.

peaceiris/hugo-extended-docker: Hugo alpine base Docker image (Hugo extended and Hugo Modules)

Back to TOC ☝️

⭐️ Workflow for autoprefixer and postcss-cli

Here is an example workflow for the google/docsy Hugo theme. This theme needs autoprefixer and postcss-cli to build a project. The following workflow is tested with google/docsy-example.

A workflow for the Hugo Babel pipeline is also the same as follows.

name: GitHub Pages

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

jobs:
  deploy:
    runs-on: ubuntu-22.04
    concurrency:
      group: ${{ github.workflow }}-${{ github.ref }}
    steps:
      - uses: actions/checkout@4
        with:
          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

      - uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'
          # The action defaults to search for the dependency file (package-lock.json,
          # npm-shrinkwrap.json or yarn.lock) in the repository root, and uses its
          # hash as a part of the cache key.
          # https://github.com/actions/setup-node/blob/main/docs/advanced-usage.md#caching-packages-data
          cache-dependency-path: '**/package-lock.json'

      - run: npm ci
      - run: hugo --minify

      - name: Deploy
        uses: peaceiris/actions-gh-pages@v3
        if: github.ref == 'refs/heads/master'
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}

Back to TOC ☝️

⭐️ Workflow for asciidoctor

Here is an example workflow for a Hugo project using asciidoctor.

name: GitHub Pages

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: Setup Ruby
        uses: ruby/setup-ruby@v1
        with:
          ruby-version: 3.2

      - run: gem install asciidoctor

      - name: Run Hugo
        run: |
          alias asciidoctor="asciidoctor --attribute=experimental=true --attribute=icons=font"
          hugo --minify

      - name: Deploy
        uses: peaceiris/actions-gh-pages@v3
        if: github.ref == 'refs/heads/main'
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}

Back to TOC ☝️

⭐️ Non-ascii Filename

cf. Gitinfo fails on unicode filename · Issue #3071 · gohugoio/hugo

name: GitHub Pages

on:
  push:
    branches:
      - main

jobs:
  deploy:
    runs-on: ubuntu-22.04
    concurrency:
      group: ${{ github.workflow }}-${{ github.ref }}
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Disable quotePath
        run: git config core.quotePath false

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

Back to TOC ☝️

CHANGELOG

• CHANGELOG.md

License

• MIT License - peaceiris/actions-hugo

About Maintainer

• peaceiris homepage
• GitHub Action Hero: Shohei Ueda - The GitHub Blog

Maintainer Notes

Run npm test on a Docker container.

# On container
make build
make all

# Release script on host
./release.sh

Back to TOC ☝️