mirror/hugo
1
0
Fork 0
mirror of https://github.com/gohugoio/hugo.git synced 2025-08-20 21:31:32 +02:00
Code Issues Packages Projects Releases Wiki Activity

Merge commit 'a6e635ca7d905d9ec3ffd708db2694f680b03aae'

Browse Source
This commit is contained in:
Bjørn Erik Pedersen
2024-08-09 15:17:43 +02:00
parent dbff48e6c3 a6e635ca7d
commit e99eba39e7
143 changed files with 3258 additions and 2109 deletions
Download Patch File Download Diff File Expand all files Collapse all files

129
docs/content/en/functions/css/PostCSS.md Normal file
View File

@@ -0,0 +1,129 @@
---
title: css.PostCSS
description: Processes the given resource with PostCSS using any PostCSS plugin.
categories: []
keywords: []
action:
aliases: [postCSS]
related:
- functions/css/Sass
- functions/css/TailwindCSS
returnType: resource.Resource
signatures: ['css.PostCSS [OPTIONS] RESOURCE']
toc: true
---
{{< new-in 0.128.0 >}}
```go-html-template
{{ with resources.Get "css/main.css" | postCSS }}
<link rel="stylesheet" href="{{ .RelPermalink }}">
{{ end }}
```
## Setup
Follow the steps below to transform CSS using any of the available [PostCSS plugins].
Step 1
: Install [Node.js].
Step 2
: Install the required Node.js packages in the root of your project. For example, to add vendor prefixes to your CSS rules:
```sh
npm i -D postcss postcss-cli autoprefixer
```
Step 3
: Create a PostCSS configuration file in the root of your project. You must name this file `postcss.config.js` or another [supported file name]. For example:
```js
module.exports = {
plugins: [
require('autoprefixer')
]
};
```
{{% note %}}
{{% include "functions/resources/_common/postcss-windows-warning.md" %}}
{{% /note %}}
Step 4
: Place your CSS file within the `assets/css` directory.
Step 5
: Process the resource with PostCSS:
```go-html-template
{{ with resources.Get "css/main.css" | postCSS }}
<link rel="stylesheet" href="{{ .RelPermalink }}">
{{ end }}
```
## Options
The `css.PostCSS` method takes an optional map of options.
config
: (`string`) The directory that contains the PostCSS configuration file. Default is the root of the project directory.
noMap
: (`bool`) Default is `false`. If `true`, disables inline sourcemaps.
inlineImports
: (`bool`) Default is `false`. Enable inlining of @import statements. It does so recursively, but will only import a file once. URL imports (e.g. `@import url('https://fonts.googleapis.com/css?family=Open+Sans&display=swap');`) and imports with media queries will be ignored. Note that this import routine does not care about the CSS spec, so you can have @import anywhere in the file. Hugo will look for imports relative to the module mount and will respect theme overrides.
skipInlineImportsNotFound
: (`bool`) Default is `false`. Before Hugo 0.99.0 when `inlineImports` was enabled and we failed to resolve an import, we logged it as a warning. We now fail the build. If you have regular CSS imports in your CSS that you want to preserve, you can either use imports with URL or media queries (Hugo does not try to resolve those) or set `skipInlineImportsNotFound` to true.
```go-html-template
{{ $opts := dict "config" "config-directory" "noMap" true }}
{{ with resources.Get "css/main.css" | postCSS $opts }}
<link rel="stylesheet" href="{{ .RelPermalink }}">
{{ end }}
```
## No configuration file
To avoid using a PostCSS configuration file, you can specify a minimal configuration using the options map.
use
: (`string`) A space-delimited list of PostCSS plugins to use.
parser
: (`string`) A custom PostCSS parser.
stringifier
: (`string`) A custom PostCSS stringifier.
syntax
: (`string`) Custom postcss syntax.
```go-html-template
{{ $opts := dict "use" "autoprefixer postcss-color-alpha" }}
{{ with resources.Get "css/main.css" | postCSS $opts }}
<link rel="stylesheet" href="{{ .RelPermalink }}">
{{ end }}
```
## Check environment
The current Hugo environment name (set by `--environment` or in configuration or OS environment) is available in the Node context, which allows constructs like this:
```js
const autoprefixer = require('autoprefixer');
const purgecss = require('@fullhuman/postcss-purgecss');
module.exports = {
plugins: [
autoprefixer,
process.env.HUGO_ENVIRONMENT !== 'development' ? purgecss : null
]
}
```
[node.js]: https://nodejs.org/en/download
[postcss plugins]: https://www.postcss.parts/
[supported file name]: https://github.com/postcss/postcss-load-config#usage
[transpile to CSS]: /functions/css/sass/

226
docs/content/en/functions/css/Sass.md Normal file
View File

@@ -0,0 +1,226 @@
---
title: css.Sass
description: Transpiles Sass to CSS.
categories: []
keywords: []
action:
aliases: [toCSS]
related:
- functions/resources/Fingerprint
- functions/resources/Minify
- functions/css/PostCSS
- functions/resources/PostProcess
returnType: resource.Resource
signatures: ['css.Sass [OPTIONS] RESOURCE']
toc: true
---
{{< new-in 0.128.0 >}}
```go-html-template
{{ with resources.Get "sass/main.scss" }}
{{ $opts := dict "transpiler" "libsass" "targetPath" "css/style.css" }}
{{ with . | toCSS $opts }}
{{ if hugo.IsDevelopment }}
<link rel="stylesheet" href="{{ .RelPermalink }}">
{{ else }}
{{ with . | minify | fingerprint }}
<link rel="stylesheet" href="{{ .RelPermalink }}" integrity="{{ .Data.Integrity }}" crossorigin="anonymous">
{{ end }}
{{ end }}
{{ end }}
{{ end }}
```
Transpile Sass to CSS using the LibSass transpiler included in Hugo's extended edition, or [install Dart Sass](#dart-sass) to use the latest features of the Sass language.
Sass has two forms of syntax: [SCSS] and [indented]. Hugo supports both.
[scss]: https://sass-lang.com/documentation/syntax#scss
[indented]: https://sass-lang.com/documentation/syntax#the-indented-syntax
## Options
transpiler
: (`string`) The transpiler to use, either `libsass` (default) or `dartsass`. Hugo's extended edition includes the LibSass transpiler. To use the Dart Sass transpiler, see the [installation instructions](#dart-sass) below.
targetPath
: (`string`) If not set, the transformed resource's target path will be the original path of the asset file with its extension replaced by `.css`.
vars
: (`map`) A map of key-value pairs that will be available in the `hugo:vars` namespace. Useful for [initializing Sass variables from Hugo templates](https://discourse.gohugo.io/t/42053/).
```scss
// LibSass
@import "hugo:vars";
// Dart Sass
@use "hugo:vars" as v;
```
outputStyle
: (`string`) Output styles available to LibSass include `nested` (default), `expanded`, `compact`, and `compressed`. Output styles available to Dart Sass include `expanded` (default) and `compressed`.
precision
: (`int`) Precision of floating point math. Not applicable to Dart Sass.
enableSourceMap
: (`bool`) If `true`, generates a source map.
sourceMapIncludeSources
: (`bool`) If `true`, embeds sources in the generated source map. Not applicable to LibSass.
includePaths
: (`slice`) A slice of paths, relative to the project root, that the transpiler will use when resolving `@use` and `@import` statements.
```go-html-template
{{ $opts := dict
"transpiler" "dartsass"
"targetPath" "css/style.css"
"vars" site.Params.styles
"enableSourceMap" (not hugo.IsProduction)
"includePaths" (slice "node_modules/bootstrap/scss")
}}
{{ with resources.Get "sass/main.scss" | toCSS $opts | minify | fingerprint }}
<link rel="stylesheet" href="{{ .RelPermalink }}" integrity="{{ .Data.Integrity }}" crossorigin="anonymous">
{{ end }}
```
## Dart Sass
The extended version of Hugo includes [LibSass] to transpile Sass to CSS. In 2020, the Sass team deprecated LibSass in favor of [Dart Sass].
Use the latest features of the Sass language by installing Dart Sass in your development and production environments.
### Installation overview
Dart Sass is compatible with Hugo v0.114.0 and later.
If you have been using Embedded Dart Sass[^1] with Hugo v0.113.0 and earlier, uninstall Embedded Dart Sass, then install Dart Sass. If you have installed both, Hugo will use Dart Sass.
If you install Hugo as a [Snap package] there is no need to install Dart Sass. The Hugo Snap package includes Dart Sass.
[^1]: In 2023, the Sass team deprecated Embedded Dart Sass in favor of Dart Sass.
### Installing in a development environment
When you install Dart Sass somewhere in your PATH, Hugo will find it.
OS|Package manager|Site|Installation
:--|:--|:--|:--
Linux|Homebrew|[brew.sh]|`brew install sass/sass/sass`
Linux|Snap|[snapcraft.io]|`sudo snap install dart-sass`
macOS|Homebrew|[brew.sh]|`brew install sass/sass/sass`
Windows|Chocolatey|[chocolatey.org]|`choco install sass`
Windows|Scoop|[scoop.sh]|`scoop install sass`
You may also install [prebuilt binaries] for Linux, macOS, and Windows.
Run `hugo env` to list the active transpilers.
### Installing in a production environment
For [CI/CD] 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.
[^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.
#### GitHub Pages
To install Dart Sass for your builds on GitHub Pages, add this step to the GitHub Pages workflow file:
```yaml
- name: Install Dart Sass
run: sudo snap install dart-sass
```
If you are using GitHub Pages for the first time with your repository, GitHub provides a [starter workflow] for Hugo that includes Dart Sass. This is the simplest way to get started.
#### 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.128.0
DART_SASS_VERSION: 1.77.5
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.128.0"
DART_SASS_VERSION = "1.77.5"
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 \
"""
```
### Example
To transpile with Dart Sass, set `transpiler` to `dartsass` in the options map passed to `css.Sass`. For example:
```go-html-template
{{ with resources.Get "sass/main.scss" }}
{{ $opts := dict "transpiler" "dartsass" "targetPath" "css/style.css" }}
{{ with . | toCSS $opts }}
{{ if hugo.IsDevelopment }}
<link rel="stylesheet" href="{{ .RelPermalink }}">
{{ else }}
{{ with . | minify | fingerprint }}
<link rel="stylesheet" href="{{ .RelPermalink }}" integrity="{{ .Data.Integrity }}" crossorigin="anonymous">
{{ end }}
{{ end }}
{{ end }}
{{ end }}
```
### Miscellaneous
If you build Hugo from source and run `mage test -v`, the test will fail if you install Dart Sass as a Snap package. This is due to the Snap package's strict confinement model.
[brew.sh]: https://brew.sh/
[chocolatey.org]: https://community.chocolatey.org/packages/sass
[ci/cd]: https://en.wikipedia.org/wiki/CI/CD
[dart sass]: https://sass-lang.com/dart-sass
[libsass]: https://sass-lang.com/libsass
[prebuilt binaries]: https://github.com/sass/dart-sass/releases/latest
[scoop.sh]: https://scoop.sh/#/apps?q=sass
[site configuration]: /getting-started/configuration/#configure-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

86
docs/content/en/functions/css/TailwindCSS.md Normal file
View File

@@ -0,0 +1,86 @@
---
title: css.TailwindCSS
description: Processes the given resource with the Tailwind CSS CLI.
categories: []
keywords: []
action:
aliases: []
related:
- functions/resources/Fingerprint
- functions/resources/Minify
- functions/css/PostCSS
returnType: resource.Resource
signatures: ['css.TailwindCSS [OPTIONS] RESOURCE']
toc: true
---
{{< new-in 0.128.0 >}}
<!-- TODO remove this admonition when feature is stable. -->
{{% note %}}
This is an experimental feature pending the release of TailwindCSS v4.0.
The functionality, configuration requirements, and documentation are subject to change at any time and may be not compatible with prior releases.
{{% /note %}}
## Prerequisites
To use this function you must install the Tailwind CSS CLI v4.0 or later. You may install the CLI as an npm package or as a standalone executable. See the [Tailwind CSS documentation] for details.
[Tailwind CSS documentation]: https://tailwindcss.com/docs/installation
{{% note %}}
Use npm to install the CLI prior to the v4.0 release of Tailwind CSS.
`npm install --save-dev tailwindcss@next @tailwindcss/cli@next`
{{% /note %}}
## Options
minify
: (`bool`) Whether to optimize and minify the output. Default is `false`.
optimize
: (`bool`) Whether to optimize the output without minifying. Default is `false`.
inlineImports
: (`bool`) Whether to enable inlining of `@import` statements. Inlining is performed recursively, but currently once only per file. It is not possible to import the same file in different scopes (root, media query, etc.). Note that this import routine does not care about the CSS specification, so you can have `@import` statements anywhere in the file. Default is `false`.
skipInlineImportsNotFound
: (`bool`) When `inlineImports` is enabled, we fail the build if an import cannot be resolved. Enable this option to allow the build to continue and leave the import statement in place. Note that the inline importer does not process URL location or imports with media queries, so those will be left as-is even without enabling this option. Default is `false`.
## Example
Define a [cache buster] in your site configuration:
[cache buster]: /getting-started/configuration/#configure-cache-busters
{{< code-toggle file=hugo >}}
[[build.cachebusters]]
source = 'layouts/.*'
target = 'css'
{{< /code-toggle >}}
Process the resource:
```go-html-template
{{ with resources.Get "css/main.css" }}
{{ $opts := dict "minify" true }}
{{ with . | css.TailwindCSS $opts }}
{{ if hugo.IsDevelopment }}
<link rel="stylesheet" href="{{ .RelPermalink }}">
{{ else }}
{{ with . | fingerprint }}
<link rel="stylesheet" href="{{ .RelPermalink }}" integrity="{{ .Data.Integrity }}" crossorigin="anonymous">
{{ end }}
{{ end }}
{{ end }}
{{ end }}
```
The example above publishes the minified CSS file to public/css/main.css.
See [this repository] for more information about the integration with Tailwind CSS v4.0.
[this repository]: https://github.com/bep/hugo-testing-tailwindcss-v4

12
docs/content/en/functions/css/_index.md Normal file
View File

@@ -0,0 +1,12 @@
---
title: CSS functions
linkTitle: css
description: Template functions to work with CSS and Sass files.
categories: []
keywords: []
menu:
docs:
parent: functions
---
Use these functions to work with CSS and Sass files.