Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/peaceiris/actions-hugo

GitHub Actions for Hugo ⚡️ Setup Hugo quickly and build your site fast. Hugo extended, Hugo Modules, Linux (Ubuntu), macOS, and Windows are supported.
https://github.com/peaceiris/actions-hugo

actions github-actions hugo

Last synced: 3 days ago
JSON representation

GitHub Actions for Hugo ⚡️ Setup Hugo quickly and build your site fast. Hugo extended, Hugo Modules, Linux (Ubuntu), macOS, and Windows are supported.

Awesome Lists containing this project

README 

        
## GitHub Actions for Hugo



GitHub Actions for Hugo



[![Project status: active – The project has reached a stable, usable state and is being actively developed.](https://www.repostatus.org/badges/latest/active.svg)](https://www.repostatus.org/#active)

[![license](https://img.shields.io/github/license/peaceiris/actions-hugo.svg)](https://github.com/peaceiris/actions-hugo/blob/main/LICENSE)

[![release](https://img.shields.io/github/release/peaceiris/actions-hugo.svg)](https://github.com/peaceiris/actions-hugo/releases/latest)

[![GitHub release date](https://img.shields.io/github/release-date/peaceiris/actions-hugo.svg)](https://github.com/peaceiris/actions-hugo/releases)

[![Release Feed](https://img.shields.io/badge/release-feed-yellow)](https://github.com/peaceiris/actions-hugo/releases.atom)

![Test](https://github.com/peaceiris/actions-hugo/workflows/Test/badge.svg?branch=main&event=push)

![Code Scanning](https://github.com/peaceiris/actions-hugo/workflows/Code%20Scanning/badge.svg?event=push)



[![CodeFactor](https://www.codefactor.io/repository/github/peaceiris/actions-hugo/badge)](https://www.codefactor.io/repository/github/peaceiris/actions-hugo)

[![codecov](https://codecov.io/gh/peaceiris/actions-hugo/branch/main/graph/badge.svg)](https://codecov.io/gh/peaceiris/actions-hugo)

[![Maintainability](https://api.codeclimate.com/v1/badges/ebf2eef3a046b396ba9c/maintainability)](https://codeclimate.com/github/peaceiris/actions-hugo/maintainability)



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.



[Hugo]: https://github.com/gohugoio/hugo



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](#getting-started)

  - [⭐️ Create your workflow](#%EF%B8%8F-create-your-workflow)

- [Options](#options)

  - [⭐️ Use Hugo extended](#%EF%B8%8F-use-hugo-extended)

  - [⭐️ Use the latest version of Hugo](#%EF%B8%8F-use-the-latest-version-of-hugo)

- [Tips](#tips)

  - [⭐️ Caching Hugo Modules](#%EF%B8%8F-caching-hugo-modules)

  - [⭐️ Read Hugo version from file](#%EF%B8%8F-read-hugo-version-from-file)

  - [⭐️ Workflow for autoprefixer and postcss-cli](#%EF%B8%8F-workflow-for-autoprefixer-and-postcss-cli)

  - [⭐️ Workflow for asciidoctor](#%EF%B8%8F-workflow-for-asciidoctor)

  - [⭐️ Non-ascii Filename](#%EF%B8%8F-non-ascii-filename)

- [CHANGELOG](#changelog)

- [License](#license)

- [About Maintainer](#about-maintainer)

- [Maintainer Notes](#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](https://github.com/peaceiris/actions-gh-pages#%EF%B8%8F-first-deployment-with-github_token)



[GitHub Actions for GitHub Pages]: https://github.com/peaceiris/actions-gh-pages



[![peaceiris/actions-gh-pages - GitHub](https://gh-card.dev/repos/peaceiris/actions-gh-pages.svg?fullname)](https://github.com/peaceiris/actions-gh-pages)



```yaml

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.



```yaml

- 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.



```yaml

- name: Setup Hugo

  uses: peaceiris/actions-hugo@v3

  with:

    hugo-version: 'latest'

```



This action fetches the latest version of Hugo by [hugo | Homebrew Formulae](https://formulae.brew.sh/formula/hugo)





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`:



```yaml

# * ...



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:



```yaml

- 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.



```sh

HUGO_VERSION=0.119.0

```



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



```yaml

    - 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.



```yaml

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)](https://github.com/peaceiris/hugo-extended-docker)





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].



[google/docsy]: https://github.com/google/docsy

[google/docsy-example]: https://github.com/google/docsy-example



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



```yaml

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`.



```yaml

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](https://github.com/gohugoio/hugo/issues/3071)



```yaml

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](CHANGELOG.md)



## License



- [MIT License - peaceiris/actions-hugo]



[MIT License - peaceiris/actions-hugo]: https://github.com/peaceiris/actions-hugo/blob/main/LICENSE



## About Maintainer



- [peaceiris homepage](https://peaceiris.com/)

- [GitHub Action Hero: Shohei Ueda - The GitHub Blog](https://github.blog/2020-03-22-github-action-hero-shohei-ueda/)



## Maintainer Notes



Run `npm test` on a Docker container.



```sh

# On container

make build

make all



# Release script on host

./release.sh

```





Back to TOC ☝️