actions-hugo/README.md

342 lines
9.1 KiB
Markdown
Raw Normal View History

2019-05-21 20:57:34 +00:00
[![license](https://img.shields.io/github/license/peaceiris/actions-hugo.svg)](https://github.com/peaceiris/actions-hugo/blob/master/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)
2020-03-16 01:49:39 +00:00
[![Release Feed](https://img.shields.io/badge/release-feed-yellow)](https://github.com/peaceiris/actions-hugo/releases.atom)
2020-01-27 03:29:34 +00:00
![Test](https://github.com/peaceiris/actions-hugo/workflows/Test/badge.svg?branch=master&event=push)
2020-03-16 01:49:39 +00:00
2019-11-13 03:58:32 +00:00
[![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/master/graph/badge.svg)](https://codecov.io/gh/peaceiris/actions-hugo)
2020-03-16 01:49:39 +00:00
[![Maintainability](https://api.codeclimate.com/v1/badges/ebf2eef3a046b396ba9c/maintainability)](https://codeclimate.com/github/peaceiris/actions-hugo/maintainability)
2019-05-21 20:57:34 +00:00
2019-09-15 23:27:57 +00:00
<img width="400" alt="GitHub Actions for Hugo" src="./images/ogp.svg">
2019-05-21 20:57:34 +00:00
## GitHub Actions for Hugo
2019-05-21 20:57:34 +00:00
- [gohugoio/hugo: The worlds fastest framework for building websites.](https://github.com/gohugoio/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.
2020-01-19 07:35:39 +00:00
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.)
2019-11-06 23:21:32 +00:00
| OS (runs-on) | ubuntu-18.04 | macos-latest | windows-2019 |
|---|:---:|:---:|:---:|
| Support | ✅️ | ✅️ | ✅️ |
| Hugo type | Hugo Extended | Hugo Modules | Latest Hugo |
|---|:---:|:---:|:---:|
| Support | ✅️ | ✅️ | ✅️ |
## Table of Contents
2019-09-22 00:43:11 +00:00
<!-- START doctoc generated TOC please keep comment here to allow auto update -->
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
2019-09-22 00:43:11 +00:00
- [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)
2019-11-22 03:15:00 +00:00
- [⭐️ Read Hugo version from file](#%EF%B8%8F-read-hugo-version-from-file)
2020-05-24 03:10:28 +00:00
- [⭐️ Workflow for autoprefixer and postcss-cli](#%EF%B8%8F-workflow-for-autoprefixer-and-postcss-cli)
- [⭐️ Workflow for asciidoctor](#%EF%B8%8F-workflow-for-asciidoctor)
2020-01-17 16:50:49 +00:00
- [CHANGELOG](#changelog)
2019-09-22 00:43:11 +00:00
- [License](#license)
2020-01-17 16:50:49 +00:00
- [About Maintainer](#about-maintainer)
- [Maintainer Notes](#maintainer-notes)
2019-09-22 00:43:11 +00:00
<!-- END doctoc generated TOC please keep comment here to allow auto update -->
2019-05-21 20:57:34 +00:00
## Getting started
2019-09-22 00:43:11 +00:00
### ⭐️ Create your workflow
2019-05-21 20:57:34 +00:00
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)
2019-10-19 07:52:57 +00:00
[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
2019-08-21 20:03:19 +00:00
name: github pages
on:
push:
branches:
2020-01-17 16:56:05 +00:00
- master
jobs:
2020-02-23 12:45:14 +00:00
deploy:
2019-08-21 17:54:38 +00:00
runs-on: ubuntu-18.04
steps:
2020-03-21 03:49:54 +00:00
- uses: actions/checkout@v2
with:
submodules: true # Fetch Hugo themes (true OR recursive)
fetch-depth: 0 # Fetch all history for .GitInfo and .Lastmod
2020-01-17 16:56:05 +00:00
- name: Setup Hugo
uses: peaceiris/actions-hugo@v2
with:
2020-05-25 09:59:13 +00:00
hugo-version: '0.71.1'
2020-01-17 16:56:05 +00:00
# extended: true
- name: Build
run: hugo --minify
- name: Deploy
uses: peaceiris/actions-gh-pages@v3
with:
2020-02-23 12:41:38 +00:00
github_token: ${{ secrets.GITHUB_TOKEN }}
publish_dir: ./public
2019-05-21 20:57:34 +00:00
```
2019-11-22 03:19:08 +00:00
<div align="right">
<a href="#table-of-contents">Back to TOC ☝️</a>
</div>
2019-05-21 20:57:34 +00:00
2019-09-15 23:27:57 +00:00
## Options
2019-09-22 00:43:11 +00:00
### ⭐️ Use Hugo extended
2019-09-15 23:27:57 +00:00
Set `extended: true` to use a Hugo extended version.
2019-09-15 23:27:57 +00:00
```yaml
- name: Setup Hugo
2019-11-28 11:47:38 +00:00
uses: peaceiris/actions-hugo@v2
2019-09-15 23:27:57 +00:00
with:
2020-05-25 10:00:37 +00:00
hugo-version: '0.71.1'
2019-09-15 23:27:57 +00:00
extended: true
```
2019-09-22 00:43:11 +00:00
### ⭐️ Use the latest version of Hugo
2019-09-15 23:27:57 +00:00
Set `hugo-version: 'latest'` to use the latest version of Hugo.
2019-09-15 23:27:57 +00:00
```yaml
- name: Setup Hugo
2019-11-28 11:47:38 +00:00
uses: peaceiris/actions-hugo@v2
2019-09-15 23:27:57 +00:00
with:
hugo-version: 'latest'
```
This action fetches the latest version of Hugo by [hugo | Homebrew Formulae](https://formulae.brew.sh/formula/hugo)
2019-09-15 23:27:57 +00:00
2019-11-22 03:19:08 +00:00
<div align="right">
<a href="#table-of-contents">Back to TOC ☝️</a>
</div>
2019-09-15 23:27:57 +00:00
## Tips
2019-11-22 03:15:00 +00:00
### ⭐️ Read Hugo version from file
2019-11-28 11:43:56 +00:00
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
2020-05-25 10:00:37 +00:00
HUGO_VERSION=0.71.1
```
Next, add a step to read a Hugo version from the `.env` file.
```yaml
- name: Read .env
id: hugo-version
run: |
. ./.env
2019-11-22 03:17:04 +00:00
echo "::set-output name=HUGO_VERSION::${HUGO_VERSION}"
- name: Setup Hugo
2019-11-28 11:47:38 +00:00
uses: peaceiris/actions-hugo@v2
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
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)
### ⭐️ 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 on [google/docsy-example].
[google/docsy]: https://github.com/google/docsy
[google/docsy-example]: https://github.com/google/docsy-example
2020-06-09 23:46:47 +00:00
A workflow for the Hugo Babel pipeline is also the same as follows.
```yaml
name: github pages
on:
push:
branches:
- master
jobs:
deploy:
runs-on: ubuntu-18.04
steps:
- uses: actions/checkout@v2
with:
submodules: recursive # Fetch the Docsy theme
fetch-depth: 0 # Fetch all history for .GitInfo and .Lastmod
- name: Setup Hugo
uses: peaceiris/actions-hugo@v2
with:
2020-05-25 10:00:37 +00:00
hugo-version: '0.71.1'
extended: true
- name: Setup Node
uses: actions/setup-node@v1
with:
node-version: '12.x'
- name: Cache dependencies
uses: actions/cache@v1
with:
path: ~/.npm
key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}
restore-keys: |
${{ runner.os }}-node-
- run: npm ci
- run: hugo --minify
- name: Deploy
uses: peaceiris/actions-gh-pages@v3
with:
github_token: ${{ secrets.GITHUB_TOKEN }}
```
### ⭐️ Workflow for asciidoctor
Here is an example workflow for a Hugo project using `asciidoctor`.
```yaml
name: github pages
on:
push:
branches:
- master
jobs:
deploy:
runs-on: ubuntu-18.04
steps:
- uses: actions/checkout@v2
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@v2
with:
hugo-version: '0.71.1'
extended: true
- name: Setup Ruby
uses: ruby/setup-ruby@v1
with:
ruby-version: 2.7
- 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
with:
github_token: ${{ secrets.GITHUB_TOKEN }}
```
2020-01-17 16:54:59 +00:00
<div align="right">
<a href="#table-of-contents">Back to TOC ☝️</a>
</div>
2020-01-17 16:50:49 +00:00
## CHANGELOG
- [CHANGELOG.md](CHANGELOG.md)
2019-05-21 20:57:34 +00:00
## License
- [MIT License - peaceiris/actions-hugo]
2019-05-21 20:57:34 +00:00
[MIT License - peaceiris/actions-hugo]: https://github.com/peaceiris/actions-hugo/blob/master/LICENSE
2020-01-17 16:50:49 +00:00
## 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/)
2020-01-17 16:50:49 +00:00
2019-05-22 12:01:05 +00:00
2020-01-17 16:50:49 +00:00
## Maintainer Notes
2020-03-27 10:12:10 +00:00
Run `npm test` on a Docker container.
2020-01-17 16:50:49 +00:00
```sh
2020-03-27 10:12:10 +00:00
# On container
2020-01-17 16:50:49 +00:00
make build
2020-03-27 10:12:10 +00:00
make all
2020-01-17 16:50:49 +00:00
2020-03-27 10:12:10 +00:00
# Release script on host
2020-01-17 16:50:49 +00:00
./release.sh
```
2019-11-22 03:19:08 +00:00
<div align="right">
<a href="#table-of-contents">Back to TOC ☝️</a>
</div>