blogs/hugo
1
0
Fork 0
mirror of https://github.com/gohugoio/hugo.git synced 2026-08-25 07:48:52 +00:00
Code Issues Packages Projects Releases Wiki Activity

content: Update hosting workflow files

Browse Source 
- Amplify
- GitHub Pages
- GitLab Pages
- Netlify
This commit is contained in:
Joe Mooring
2025-08-09 10:44:06 -07:00
committed by Joe Mooring
parent 57fd362bf9
commit 8ecbc985c0
5 changed files with 174 additions and 167 deletions
Download Patch File Download Diff File Expand all files Collapse all files
content/en/functions/css/Sass.md
+14 -64
View File
@@ -122,83 +122,33 @@ Run `hugo env` to list the active transpilers.
### Installing in a production environment
For [CI/CD](g) deployments (e.g., GitHub Pages, GitLab Pages, Netlify, etc.) you must edit the workflow to install Dart Sass before Hugo builds the site[^2]. Some providers allow you to use one of the package managers above, or you can download and extract one of the prebuilt binaries.
To use Dart Sass with Hugo on a CI/CD platform like GitHub Pages, GitLab Pages, or Netlify, you typically must modify your build workflow to install Dart Sass before the Hugo site build begins. This is because these platforms don't have Dart Sass pre-installed, and Hugo needs it to process your Sass files.
[^2]: You do not have to do this if (a) you have not modified the assets cache location, and (b) you have not set `useResourceCacheWhen` to `never` in your [site configuration], and (c) you add and commit your `resources` directory to your repository.
There's one key exception where you can skip this step: you have committed your `resources` directory to your repository. This is only possible if:
#### GitHub Pages
- You have not changed Hugo's default asset cache location.
- You have not set [`useResourceCacheWhen`] to never in your sites configuration.
To install Dart Sass for your builds on GitHub Pages, add this step to the GitHub Pages workflow file:
By committing the `resources` directory, you're providing the pre-built CSS files directly to your CI/CD service, so it doesn't need to run the Sass compilation itself.
```yaml
- name: Install Dart Sass
run: sudo snap install dart-sass
```
For examples of how to install Dart Sass in a production environment, see the following workflow files:
#### GitLab Pages
To install Dart Sass for your builds on GitLab Pages, the `.gitlab-ci.yml` file should look something like this:
```yaml
variables:
HUGO_VERSION: 0.148.0
DART_SASS_VERSION: 1.89.2
GIT_DEPTH: 0
GIT_STRATEGY: clone
GIT_SUBMODULE_STRATEGY: recursive
TZ: America/Los_Angeles
image:
name: golang:1.20-buster
pages:
script:
# Install Dart Sass
- curl -LJO https://github.com/sass/dart-sass/releases/download/${DART_SASS_VERSION}/dart-sass-${DART_SASS_VERSION}-linux-x64.tar.gz
- tar -xf dart-sass-${DART_SASS_VERSION}-linux-x64.tar.gz
- cp -r dart-sass/* /usr/local/bin
- rm -rf dart-sass*
# Install Hugo
- curl -LJO https://github.com/gohugoio/hugo/releases/download/v${HUGO_VERSION}/hugo_extended_${HUGO_VERSION}_linux-amd64.deb
- apt install -y ./hugo_extended_${HUGO_VERSION}_linux-amd64.deb
- rm hugo_extended_${HUGO_VERSION}_linux-amd64.deb
# Build
- hugo --gc --minify
artifacts:
paths:
- public
rules:
- if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
```
#### Netlify
To install Dart Sass for your builds on Netlify, the `netlify.toml` file should look something like this:
```toml
[build.environment]
HUGO_VERSION = "0.148.0"
DART_SASS_VERSION = "1.89.2"
NODE_VERSION = "22"
TZ = "America/Los_Angeles"
[build]
publish = "public"
command = """\
curl -LJO https://github.com/sass/dart-sass/releases/download/${DART_SASS_VERSION}/dart-sass-${DART_SASS_VERSION}-linux-x64.tar.gz && \
tar -xf dart-sass-${DART_SASS_VERSION}-linux-x64.tar.gz && \
rm dart-sass-${DART_SASS_VERSION}-linux-x64.tar.gz && \
export PATH=/opt/build/repo/dart-sass:$PATH && \
hugo --gc --minify \
"""
```
- [GitHub Pages]
- [GitLab Pages]
- [Netlify]
[`publishDir`]: /configuration/all/#publishdir
[`useResourceCacheWhen`]: /configuration/build/#useresourcecachewhen
[brew.sh]: https://brew.sh/
[chocolatey.org]: https://community.chocolatey.org/packages/sass
[dart sass]: https://sass-lang.com/dart-sass
[GitHub Pages]: /host-and-deploy/host-on-github-pages/#step-7
[GitLab Pages]: /host-and-deploy/host-on-gitlab-pages/#configure-gitlab-cicd
[libsass]: https://sass-lang.com/libsass
[Netlify]: /host-and-deploy/host-on-gitlab-pages/#configure-gitlab-cicd
[prebuilt binaries]: https://github.com/sass/dart-sass/releases/latest
[scoop.sh]: https://scoop.sh/#/apps?q=sass
[site configuration]: /configuration/build/
[snap package]: /installation/linux/#snap
[snapcraft.io]: https://snapcraft.io/dart-sass
[starter workflow]: https://github.com/actions/starter-workflows/blob/main/pages/hugo.yml
[`publishDir`]: /configuration/all/#publishdir
content/en/host-and-deploy/host-on-aws-amplify/index.md
+36 -25
View File
@@ -44,11 +44,11 @@ version: 1
env:
variables:
# Application versions
DART_SASS_VERSION: 1.89.2
GO_VERSION: 1.24.2
HUGO_VERSION: 0.148.0
DART_SASS_VERSION: 1.90.0
GO_VERSION: 1.24.5
HUGO_VERSION: 0.148.2
# Time zone
TZ: America/Los_Angeles
TZ: Europe/Oslo
# Cache
HUGO_CACHEDIR: ${PWD}/.hugo
NPM_CONFIG_CACHE: ${PWD}/.npm
@@ -56,38 +56,49 @@ frontend:
phases:
preBuild:
commands:
# Create directory for user-specific executable files
- echo "Creating directory for user-specific executable files..."
- mkdir -p "${HOME}/.local"
# Install Dart Sass
- curl -LJO https://github.com/sass/dart-sass/releases/download/${DART_SASS_VERSION}/dart-sass-${DART_SASS_VERSION}-linux-x64.tar.gz
- sudo tar -C /usr/local/bin -xf dart-sass-${DART_SASS_VERSION}-linux-x64.tar.gz
- rm dart-sass-${DART_SASS_VERSION}-linux-x64.tar.gz
- export PATH=/usr/local/bin/dart-sass:$PATH
- echo "Installing Dart Sass ${DART_SASS_VERSION}..."
- curl -sLJO "https://github.com/sass/dart-sass/releases/download/${DART_SASS_VERSION}/dart-sass-${DART_SASS_VERSION}-linux-x64.tar.gz"
- tar -C "${HOME}/.local" -xf "dart-sass-${DART_SASS_VERSION}-linux-x64.tar.gz"
- rm "dart-sass-${DART_SASS_VERSION}-linux-x64.tar.gz"
- export PATH="${HOME}/.local/dart-sass:${PATH}"
# Install Go
- curl -LJO https://go.dev/dl/go${GO_VERSION}.linux-amd64.tar.gz
- sudo tar -C /usr/local -xf go${GO_VERSION}.linux-amd64.tar.gz
- rm go${GO_VERSION}.linux-amd64.tar.gz
- export PATH=/usr/local/go/bin:$PATH
- echo "Installing Go ${GO_VERSION}..."
- curl -sLJO "https://go.dev/dl/go${GO_VERSION}.linux-amd64.tar.gz"
- tar -C "${HOME}/.local" -xf "go${GO_VERSION}.linux-amd64.tar.gz"
- rm "go${GO_VERSION}.linux-amd64.tar.gz"
- export PATH="${HOME}/.local/go/bin:${PATH}"
# Install Hugo
- curl -LJO https://github.com/gohugoio/hugo/releases/download/v${HUGO_VERSION}/hugo_extended_${HUGO_VERSION}_linux-amd64.tar.gz
- sudo tar -C /usr/local/bin -xf hugo_extended_${HUGO_VERSION}_linux-amd64.tar.gz
- rm hugo_extended_${HUGO_VERSION}_linux-amd64.tar.gz
- export PATH=/usr/local/bin:$PATH
- echo "Installing Hugo ${HUGO_VERSION}..."
- curl -sLJO "https://github.com/gohugoio/hugo/releases/download/v${HUGO_VERSION}/hugo_extended_${HUGO_VERSION}_linux-amd64.tar.gz"
- mkdir "${HOME}/.local/hugo"
- tar -C "${HOME}/.local/hugo" -xf "hugo_extended_${HUGO_VERSION}_linux-amd64.tar.gz"
- rm "hugo_extended_${HUGO_VERSION}_linux-amd64.tar.gz"
- export PATH="${HOME}/.local/hugo:${PATH}"
# Check installed versions
- go version
- hugo version
- node -v
- npm -v
- sass --embedded --version
# Verify installations
- echo "Verifying installations..."
- "echo Dart Sass: $(sass --version)"
- "echo Go: $(go version)"
- "echo Hugo: $(hugo version)"
- "echo Node.js: $(node --version)"
# Install Node.JS dependencies
# Install Node.js dependencies
- echo "Installing Node.js dependencies..."
- "[[ -f package-lock.json || -f npm-shrinkwrap.json ]] && npm ci --prefer-offline || true"
# https://github.com/gohugoio/hugo/issues/9810
- git config --add core.quotepath false
# Configure Git
- echo "Configuring Git..."
- git config core.quotepath false
build:
commands:
- echo "Building site..."
- hugo --gc --minify
artifacts:
baseDirectory: public
content/en/host-and-deploy/host-on-github-pages/index.md
+48 -41
View File
@@ -73,90 +73,97 @@ touch .github/workflows/hugo.yaml
Copy and paste the YAML below into the file you created. Change the branch name and Hugo version as needed.
```yaml {file=".github/workflows/hugo.yaml" copy=true}
# Sample workflow for building and deploying a Hugo site to GitHub Pages
name: Deploy Hugo site to Pages
name: Build and deploy Hugo site to GitHub Pages
on:
# Runs on pushes targeting the default branch
push:
branches:
- main
# Allows you to run this workflow manually from the Actions tab
workflow_dispatch:
# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
permissions:
contents: read
pages: write
id-token: write
# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
concurrency:
group: "pages"
group: pages
cancel-in-progress: false
# Default to bash
defaults:
run:
# GitHub-hosted runners automatically enable `set -eo pipefail` for Bash shells.
shell: bash
jobs:
# Build job
build:
runs-on: ubuntu-latest
env:
DART_SASS_VERSION: 1.89.2
HUGO_VERSION: 0.148.0
HUGO_ENVIRONMENT: production
TZ: America/Los_Angeles
DART_SASS_VERSION: 1.90.0
GO_VERSION: 1.24.5
HUGO_VERSION: 0.148.2
NODE_VERSION: 22.18.0
TZ: Europe/Oslo
steps:
- name: Install Hugo CLI
run: |
wget -O ${{ runner.temp }}/hugo.deb https://github.com/gohugoio/hugo/releases/download/v${HUGO_VERSION}/hugo_extended_${HUGO_VERSION}_linux-amd64.deb
sudo dpkg -i ${{ runner.temp }}/hugo.deb
- name: Install Dart Sass
run: |
wget -O ${{ runner.temp }}/dart-sass.tar.gz https://github.com/sass/dart-sass/releases/download/${DART_SASS_VERSION}/dart-sass-${DART_SASS_VERSION}-linux-x64.tar.gz
tar -xf ${{ runner.temp }}/dart-sass.tar.gz --directory ${{ runner.temp }}
mv ${{ runner.temp }}/dart-sass/ /usr/local/bin
echo "/usr/local/bin/dart-sass" >> $GITHUB_PATH
- name: Checkout
uses: actions/checkout@v4
with:
submodules: recursive
fetch-depth: 0
- name: Setup Go
uses: actions/setup-go@v5
with:
go-version: ${{ env.GO_VERSION }}
cache: false
- name: Setup Node.js
uses: actions/setup-node@v4
with:
node-version: ${{ env.NODE_VERSION }}
- name: Setup Pages
id: pages
uses: actions/configure-pages@v5
- name: Create directory for user-specific executable files
run: |
mkdir -p "${HOME}/.local"
- name: Install Dart Sass
run: |
curl -sLJO "https://github.com/sass/dart-sass/releases/download/${DART_SASS_VERSION}/dart-sass-${DART_SASS_VERSION}-linux-x64.tar.gz"
tar -C "${HOME}/.local" -xf "dart-sass-${DART_SASS_VERSION}-linux-x64.tar.gz"
rm "dart-sass-${DART_SASS_VERSION}-linux-x64.tar.gz"
echo "${HOME}/.local/dart-sass" >> "${GITHUB_PATH}"
- name: Install Hugo
run: |
curl -sLJO "https://github.com/gohugoio/hugo/releases/download/v${HUGO_VERSION}/hugo_extended_${HUGO_VERSION}_linux-amd64.tar.gz"
mkdir "${HOME}/.local/hugo"
tar -C "${HOME}/.local/hugo" -xf "hugo_extended_${HUGO_VERSION}_linux-amd64.tar.gz"
rm "hugo_extended_${HUGO_VERSION}_linux-amd64.tar.gz"
echo "${HOME}/.local/hugo" >> "${GITHUB_PATH}"
- name: Verify installations
run: |
echo "Dart Sass: $(sass --version)"
echo "Go: $(go version)"
echo "Hugo: $(hugo version)"
echo "Node.js: $(node --version)"
- name: Install Node.js dependencies
run: "[[ -f package-lock.json || -f npm-shrinkwrap.json ]] && npm ci || true"
- name: Cache Restore
run: |
[[ -f package-lock.json || -f npm-shrinkwrap.json ]] && npm ci || true
- name: Configure Git
run: |
git config core.quotepath false
- name: Cache restore
id: cache-restore
uses: actions/cache/restore@v4
with:
path: |
${{ runner.temp }}/hugo_cache
path: ${{ runner.temp }}/hugo_cache
key: hugo-${{ github.run_id }}
restore-keys:
hugo-
- name: Configure Git
run: git config core.quotepath false
- name: Build with Hugo
- name: Build the site
run: |
hugo \
--gc \
--minify \
--baseURL "${{ steps.pages.outputs.base_url }}/" \
--cacheDir "${{ runner.temp }}/hugo_cache"
- name: Cache Save
- name: Cache save
id: cache-save
uses: actions/cache/save@v4
with:
path: |
${{ runner.temp }}/hugo_cache
path: ${{ runner.temp }}/hugo_cache
key: ${{ steps.cache-restore.outputs.cache-primary-key }}
- name: Upload artifact
uses: actions/upload-pages-artifact@v3
content/en/host-and-deploy/host-on-gitlab-pages.md
+57 -21
View File
@@ -23,42 +23,78 @@ Define your [CI/CD](g) jobs by creating a `.gitlab-ci.yml` file in the root of y
```yaml {file=".gitlab-ci.yml" copy=true}
variables:
DART_SASS_VERSION: 1.89.2
# Application versions
DART_SASS_VERSION: 1.90.0
HUGO_VERSION: 0.148.2
NODE_VERSION: 22.18.0
# Git
GIT_DEPTH: 0
GIT_STRATEGY: clone
GIT_SUBMODULE_STRATEGY: recursive
HUGO_VERSION: 0.148.0
NODE_VERSION: 22.x
TZ: America/Los_Angeles
# Time zone
TZ: Europe/Oslo
image:
name: golang:1.24.2-bookworm
name: golang:1.24.5-bookworm
pages:
stage: deploy
script:
# Install brotli
# Create directory for user-specific executable files
- echo "Creating directory for user-specific executable files..."
- mkdir -p "${HOME}/.local"
# Install utilities
- echo "Installing utilities..."
- apt-get update
- apt-get install -y brotli
- apt-get install -y brotli xz-utils zstd
# Install Dart Sass
- curl -LJO https://github.com/sass/dart-sass/releases/download/${DART_SASS_VERSION}/dart-sass-${DART_SASS_VERSION}-linux-x64.tar.gz
- tar -xf dart-sass-${DART_SASS_VERSION}-linux-x64.tar.gz
- cp -r dart-sass/ /usr/local/bin
- rm -rf dart-sass*
- export PATH=/usr/local/bin/dart-sass:$PATH
- echo "Installing Dart Sass ${DART_SASS_VERSION}..."
- curl -sLJO "https://github.com/sass/dart-sass/releases/download/${DART_SASS_VERSION}/dart-sass-${DART_SASS_VERSION}-linux-x64.tar.gz"
- tar -C "${HOME}/.local" -xf "dart-sass-${DART_SASS_VERSION}-linux-x64.tar.gz"
- rm "dart-sass-${DART_SASS_VERSION}-linux-x64.tar.gz"
- export PATH="${HOME}/.local/dart-sass:${PATH}"
# Install Hugo
- curl -LJO https://github.com/gohugoio/hugo/releases/download/v${HUGO_VERSION}/hugo_extended_${HUGO_VERSION}_linux-amd64.deb
- apt-get install -y ./hugo_extended_${HUGO_VERSION}_linux-amd64.deb
- rm hugo_extended_${HUGO_VERSION}_linux-amd64.deb
- echo "Installing Hugo ${HUGO_VERSION}..."
- curl -sLJO "https://github.com/gohugoio/hugo/releases/download/v${HUGO_VERSION}/hugo_extended_${HUGO_VERSION}_linux-amd64.tar.gz"
- mkdir "${HOME}/.local/hugo"
- tar -C "${HOME}/.local/hugo" -xf "hugo_extended_${HUGO_VERSION}_linux-amd64.tar.gz"
- rm "hugo_extended_${HUGO_VERSION}_linux-amd64.tar.gz"
- export PATH="${HOME}/.local/hugo:${PATH}"
# Install Node.js
- curl -fsSL https://deb.nodesource.com/setup_${NODE_VERSION} | bash -
- apt-get install -y nodejs
- echo "Installing Node.js ${NODE_VERSION}..."
- curl -sLJO "https://nodejs.org/dist/v${NODE_VERSION}/node-v${NODE_VERSION}-linux-x64.tar.xz"
- tar -C "${HOME}/.local" -xf "node-v${NODE_VERSION}-linux-x64.tar.xz"
- rm "node-v${NODE_VERSION}-linux-x64.tar.xz"
- export PATH="${HOME}/.local/node-v${NODE_VERSION}-linux-x64/bin:${PATH}"
# Verify installations
- echo "Verifying installations..."
- "echo Dart Sass: $(sass --version)"
- "echo Go: $(go version)"
- "echo Hugo: $(hugo version)"
- "echo Node.js: $(node --version)"
- "echo brotli: $(brotli --version)"
- "echo xz: $(xz --version)"
- "echo zstd: $(zstd --version)"
# Install Node.js dependencies
- "[[ -f package-lock.json || -f npm-shrinkwrap.json ]] && npm ci || true"
- echo "Installing Node.js dependencies..."
- "[[ -f package-lock.json || -f npm-shrinkwrap.json ]] && npm ci --prefer-offline || true"
# Configure Git
- echo "Configuring Git..."
- git config core.quotepath false
# Build
- hugo --gc --minify --baseURL ${CI_PAGES_URL}
# Compress
# Build site
- echo "Building site..."
- hugo --gc --minify --baseURL "${CI_PAGES_URL}"
# Compress published files
- echo "Compressing published files..."
- find public/ -type f -regextype posix-extended -regex '.+\.(css|html|js|json|mjs|svg|txt|xml)$' -print0 > files.txt
- time xargs --null --max-procs=0 --max-args=1 brotli --quality=10 --force --keep < files.txt
- time xargs --null --max-procs=0 --max-args=1 gzip -9 --force --keep < files.txt
content/en/host-and-deploy/host-on-netlify/index.md
+19 -16
View File
@@ -109,38 +109,41 @@ Press the **Open production deploy** button to view the live site.
In the procedure above we configured our site using the Netlify user interface. Most site owners find it easier to use a configuration file checked into source control.
Create a new file named netlify.toml in the root of your project directory. In its simplest form, the configuration file might look like this:
Create a new file named `netlify.toml` in the root of your project directory. In its simplest form, the configuration file might look like this:
```toml {file="netlify.toml"}
[build.environment]
GO_VERSION = "1.24.2"
HUGO_VERSION = "0.148.0"
NODE_VERSION = "22"
TZ = "America/Los_Angeles"
GO_VERSION = "1.24.5"
HUGO_VERSION = "0.148.2"
NODE_VERSION = "22.18.0"
TZ = "Europe/Oslo"
[build]
publish = "public"
command = "git config core.quotepath false && hugo --gc --minify"
command = """\
git config core.quotepath false && \
hugo --gc --minify --baseURL "${URL}"
"""
```
If your site requires Dart Sass to transpile Sass to CSS, the configuration file should look something like this:
```toml {file="netlify.toml"}
[build.environment]
DART_SASS_VERSION = "1.89.2"
GO_VERSION = "1.24.2"
HUGO_VERSION = "0.148.0"
NODE_VERSION = "22"
TZ = "America/Los_Angeles"
DART_SASS_VERSION = "1.90.0"
GO_VERSION = "1.24.5"
HUGO_VERSION = "0.148.2"
NODE_VERSION = "22.18.0"
TZ = "Europe/Oslo"
[build]
publish = "public"
command = """\
curl -LJO https://github.com/sass/dart-sass/releases/download/${DART_SASS_VERSION}/dart-sass-${DART_SASS_VERSION}-linux-x64.tar.gz && \
tar -xf dart-sass-${DART_SASS_VERSION}-linux-x64.tar.gz && \
rm dart-sass-${DART_SASS_VERSION}-linux-x64.tar.gz && \
export PATH=/opt/build/repo/dart-sass:$PATH && \
curl -sLJO "https://github.com/sass/dart-sass/releases/download/${DART_SASS_VERSION}/dart-sass-${DART_SASS_VERSION}-linux-x64.tar.gz" && \
tar -C "${HOME}/.local" -xf "dart-sass-${DART_SASS_VERSION}-linux-x64.tar.gz" && \
rm "dart-sass-${DART_SASS_VERSION}-linux-x64.tar.gz" && \
export PATH="${HOME}/.local/dart-sass:${PATH}" && \
git config core.quotepath false && \
hugo --gc --minify \
hugo --gc --minify --baseURL "${URL}"
"""
```