Awesome
GitHub Actions for Hugo
<img width="400" alt="GitHub Actions for Hugo" src="./images/ogp.svg">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
<!-- START doctoc generated TOC please keep comment here to allow auto update --> <!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE --> <!-- END doctoc generated TOC please keep comment here to allow auto update -->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
<div align="right">
<a href="#table-of-contents">Back to TOC ☝️</a>
</div>
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
<div align="right"> <a href="#table-of-contents">Back to TOC ☝️</a> </div>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
<div align="right">
<a href="#table-of-contents">Back to TOC ☝️</a>
</div>
⭐️ 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.
<div align="right"> <a href="#table-of-contents">Back to TOC ☝️</a> </div>peaceiris/hugo-extended-docker: Hugo alpine base Docker image (Hugo extended and Hugo Modules)
⭐️ 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 }}
<div align="right">
<a href="#table-of-contents">Back to TOC ☝️</a>
</div>
⭐️ 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 }}
<div align="right">
<a href="#table-of-contents">Back to TOC ☝️</a>
</div>
⭐️ 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'
<div align="right">
<a href="#table-of-contents">Back to TOC ☝️</a>
</div>
CHANGELOG
License
About Maintainer
Maintainer Notes
Run npm test
on a Docker container.
# On container
make build
make all
# Release script on host
./release.sh
<div align="right">
<a href="#table-of-contents">Back to TOC ☝️</a>
</div>