diff --git a/content/en/functions/css/Sass.md b/content/en/functions/css/Sass.md index 73440879a..ac5d3788b 100644 --- a/content/en/functions/css/Sass.md +++ b/content/en/functions/css/Sass.md @@ -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 diff --git a/content/en/host-and-deploy/host-on-aws-amplify/index.md b/content/en/host-and-deploy/host-on-aws-amplify/index.md index 706394dd9..a6d3b7419 100644 --- a/content/en/host-and-deploy/host-on-aws-amplify/index.md +++ b/content/en/host-and-deploy/host-on-aws-amplify/index.md @@ -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 diff --git a/content/en/host-and-deploy/host-on-github-pages/index.md b/content/en/host-and-deploy/host-on-github-pages/index.md index bfb49a613..49720ba1a 100644 --- a/content/en/host-and-deploy/host-on-github-pages/index.md +++ b/content/en/host-and-deploy/host-on-github-pages/index.md @@ -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 diff --git a/content/en/host-and-deploy/host-on-gitlab-pages.md b/content/en/host-and-deploy/host-on-gitlab-pages.md index 59c1d1e0b..4b63f9195 100644 --- a/content/en/host-and-deploy/host-on-gitlab-pages.md +++ b/content/en/host-and-deploy/host-on-gitlab-pages.md @@ -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 diff --git a/content/en/host-and-deploy/host-on-netlify/index.md b/content/en/host-and-deploy/host-on-netlify/index.md index b5e9f12ab..cf60894fa 100644 --- a/content/en/host-and-deploy/host-on-netlify/index.md +++ b/content/en/host-and-deploy/host-on-netlify/index.md @@ -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}" """ ```