From 012162e0d2ede071ad2b9637db5fb1dbd5995d52 Mon Sep 17 00:00:00 2001 From: Joe Mooring Date: Sun, 23 Jun 2024 08:54:42 -0700 Subject: [PATCH] Document changes to template functions in v0.128.0 - New: css.TailwindCSS - Deprecate/rename: resources.Babel => js.Babel - Deprecate/rename: resources.PostCSS => css.PostCSS - Deprecate/rename: resources.ToCSS => css.Sass - Document disableWatch mount parameter --- .../layouts/shortcodes/gomodules-info.html | 2 +- content/en/functions/css/PostCSS.md | 131 ++++++++++ content/en/functions/css/Sass.md | 226 ++++++++++++++++++ content/en/functions/css/TailwindCSS.md | 81 +++++++ content/en/functions/css/_index.md | 12 + content/en/functions/js/Babel.md | 90 +++++++ content/en/functions/resources/Babel.md | 7 + content/en/functions/resources/PostCSS.md | 9 +- content/en/functions/resources/PostProcess.md | 2 +- content/en/functions/resources/ToCSS.md | 11 +- content/en/hugo-modules/configuration.md | 44 ++-- content/en/hugo-pipes/babel.md | 4 +- content/en/hugo-pipes/introduction.md | 2 +- content/en/hugo-pipes/postcss.md | 6 +- content/en/hugo-pipes/postprocess.md | 4 +- .../en/hugo-pipes/resource-from-template.md | 2 +- .../en/hugo-pipes/transpile-sass-to-css.md | 6 +- content/en/methods/site/LastChange.md | 2 +- content/en/templates/shortcode-templates.md | 2 +- data/docs.yaml | 103 +++++--- 20 files changed, 680 insertions(+), 66 deletions(-) create mode 100644 content/en/functions/css/PostCSS.md create mode 100644 content/en/functions/css/Sass.md create mode 100644 content/en/functions/css/TailwindCSS.md create mode 100644 content/en/functions/css/_index.md create mode 100644 content/en/functions/js/Babel.md diff --git a/_vendor/github.com/gohugoio/gohugoioTheme/layouts/shortcodes/gomodules-info.html b/_vendor/github.com/gohugoio/gohugoioTheme/layouts/shortcodes/gomodules-info.html index b56758ac38..82234ff314 100644 --- a/_vendor/github.com/gohugoio/gohugoioTheme/layouts/shortcodes/gomodules-info.html +++ b/_vendor/github.com/gohugoio/gohugoioTheme/layouts/shortcodes/gomodules-info.html @@ -1,5 +1,5 @@ {{ $text := ` -Most of the commands for **Hugo Modules** require a newer version of Go installed (see https://golang.org/dl/) and the relevant VCS client (e.g. Git, see https://git-scm.com/downloads/ ). If you have an "older" site running on Netlify, you may have to set GO_VERSION to 1.12 in your Environment settings. +Most of the commands for Hugo Modules require a newer version of Go installed (see https://golang.org/dl/) and the relevant VCS client (e.g. Git, see https://git-scm.com/downloads/ ). If you have an "older" site running on Netlify, you may have to set GO_VERSION to 1.12 in your Environment settings. For more information about Go Modules, see: diff --git a/content/en/functions/css/PostCSS.md b/content/en/functions/css/PostCSS.md new file mode 100644 index 0000000000..ed1652d00e --- /dev/null +++ b/content/en/functions/css/PostCSS.md @@ -0,0 +1,131 @@ +--- +title: css.PostCSS +description: Processes the given resource with PostCSS using any PostCSS plugin. +categories: [] +keywords: [] +action: + aliases: [postCSS] + related: + - functions/resources/Fingerprint + - functions/resources/Minify + - functions/resources/PostProcess + - functions/css/Sass + 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 }} + +{{ 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 }} + +{{ 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 }} + +{{ 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 }} + +{{ 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/resources/tocss.md diff --git a/content/en/functions/css/Sass.md b/content/en/functions/css/Sass.md new file mode 100644 index 0000000000..2ff796436d --- /dev/null +++ b/content/en/functions/css/Sass.md @@ -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 }} + + {{ else }} + {{ with . | minify | fingerprint }} + + {{ 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 }} + +{{ 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.126.0 + DART_SASS_VERSION: 1.77.1 + 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.126.0" +DART_SASS_VERSION = "1.77.1" +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 }} + + {{ else }} + {{ with . | minify | fingerprint }} + + {{ 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 diff --git a/content/en/functions/css/TailwindCSS.md b/content/en/functions/css/TailwindCSS.md new file mode 100644 index 0000000000..8f356e336a --- /dev/null +++ b/content/en/functions/css/TailwindCSS.md @@ -0,0 +1,81 @@ +--- +title: css.TailwindCSS +description: Processes the given resource with the Tailwind CSS CLI. +categories: [] +keywords: [] +action: + aliases: [] + related: + - functions/resources/Fingerprint + - functions/resources/Minify + returnType: resource.Resource + signatures: ['css.TailwindCSS [OPTIONS] RESOURCE'] +toc: true +--- + +{{< new-in 0.128.0 >}} + + + +{{% 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 }} + + {{ else }} + {{ with . | fingerprint }} + + {{ end }} + {{ end }} + {{ end }} +{{ end }} +``` + +The example above publishes the minified CSS file to public/css/main.css. diff --git a/content/en/functions/css/_index.md b/content/en/functions/css/_index.md new file mode 100644 index 0000000000..a83a238198 --- /dev/null +++ b/content/en/functions/css/_index.md @@ -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. diff --git a/content/en/functions/js/Babel.md b/content/en/functions/js/Babel.md new file mode 100644 index 0000000000..4271cd35e3 --- /dev/null +++ b/content/en/functions/js/Babel.md @@ -0,0 +1,90 @@ +--- +title: js.Babel +description: Compiles the given JavaScript resource with Babel. +categories: [] +keywords: [] +action: + aliases: [babel] + related: + - functions/js/Build + - functions/resources/Fingerprint + - functions/resources/Minify + returnType: resource.Resource + signatures: ['js.Babel [OPTIONS] RESOURCE'] +toc: true +--- + +{{< new-in 0.128.0 >}} + +```go-html-template +{{ with resources.Get "js/main.js" }} + {{ if hugo.IsDevelopment }} + {{ with . | babel }} + + {{ end }} + {{ else }} + {{ $opts := dict "minified" true }} + {{ with . | babel $opts | fingerprint }} + + {{ end }} + {{ end }} +{{ end }} +``` + +## Setup + +Step 1 +: Install [Node.js](https://nodejs.org/en/download) + +Step 2 +: Install the required Node.js packages in the root of your project. + +```sh +npm install --save-dev @babel/core @babel/cli +``` + +Step 3 +: Add the babel executable to Hugo's `security.exec.allow` list in your site configuration: + +{{< code-toggle file=hugo >}} +[security.exec] + allow = ['^(dart-)?sass(-embedded)?$', '^go$', '^npx$', '^postcss$', '^babel$'] +{{< /code-toggle >}} + +## Configuration + +We add the main project's `node_modules` to `NODE_PATH` when running Babel and similar tools. There are some known [issues](https://github.com/babel/babel/issues/5618) with Babel in this area, so if you have a `babel.config.js` living in a Hugo Module (and not in the project itself), we recommend using `require` to load the presets/plugins, e.g.: + +```js +module.exports = { + presets: [ + [ + require("@babel/preset-env"), + { + useBuiltIns: "entry", + corejs: 3, + }, + ], + ], +}; +``` + +## Options + +config +: (`string`) Path to the Babel configuration file. Hugo will, by default, look for a `babel.config.js` in your project. More information on these configuration files can be found here: [babel configuration](https://babeljs.io/docs/en/configuration). + +minified +: (`bool`) Save as many bytes as possible when printing + +noComments +: (`bool`) Write comments to generated output (true by default) + +compact +: (`bool`) Do not include superfluous whitespace characters and line terminators. Defaults to `auto` if not set. + +verbose +: (`bool`) Log everything + +sourceMap +: (`string`) Output `inline` or `external` sourcemap from the babel compile. External sourcemaps will be written to the target with the output file name + ".map". Input sourcemaps can be read from js.Build and node modules and combined into the output sourcemaps. diff --git a/content/en/functions/resources/Babel.md b/content/en/functions/resources/Babel.md index 57ddb7d235..b2c46df2a2 100644 --- a/content/en/functions/resources/Babel.md +++ b/content/en/functions/resources/Babel.md @@ -12,8 +12,15 @@ action: returnType: resource.Resource signatures: ['resources.Babel [OPTIONS] RESOURCE'] toc: true +expiryDate: 2025-06-24 # deprecated 2024-06-24 --- +{{% deprecated-in 0.128.0 %}} +Use [js.Babel] instead. + +[js.Babel]: /functions/js/babel/ +{{% /deprecated-in %}} + ```go-html-template {{ with resources.Get "js/main.js" }} {{ if hugo.IsDevelopment }} diff --git a/content/en/functions/resources/PostCSS.md b/content/en/functions/resources/PostCSS.md index a9f9ed3c8d..9c51639cba 100644 --- a/content/en/functions/resources/PostCSS.md +++ b/content/en/functions/resources/PostCSS.md @@ -9,12 +9,19 @@ action: - functions/resources/Fingerprint - functions/resources/Minify - functions/resources/PostProcess - - functions/resources/ToCSS + - functions/css/Sass returnType: resource.Resource signatures: ['resources.PostCSS [OPTIONS] RESOURCE'] toc: true +expiryDate: 2025-06-24 # deprecated 2024-06-24 --- +{{% deprecated-in 0.128.0 %}} +Use [css.PostCSS] instead. + +[css.PostCSS]: /functions/css/postcss/ +{{% /deprecated-in %}} + ```go-html-template {{ with resources.Get "css/main.css" | postCSS }} diff --git a/content/en/functions/resources/PostProcess.md b/content/en/functions/resources/PostProcess.md index f765ea9af3..f9192aa9f5 100644 --- a/content/en/functions/resources/PostProcess.md +++ b/content/en/functions/resources/PostProcess.md @@ -149,7 +149,7 @@ You cannot manipulate the values returned from the resource’s methods. For exa ```go-html-template {{ $css := resources.Get "css/main.css" }} -{{ $css = $css | resources.PostCSS | minify | fingerprint | resources.PostProcess }} +{{ $css = $css | css.PostCSS | minify | fingerprint | resources.PostProcess }} {{ $css.RelPermalink | strings.ToUpper }} ``` diff --git a/content/en/functions/resources/ToCSS.md b/content/en/functions/resources/ToCSS.md index df03267e87..fe3f62b131 100644 --- a/content/en/functions/resources/ToCSS.md +++ b/content/en/functions/resources/ToCSS.md @@ -8,13 +8,20 @@ action: related: - functions/resources/Fingerprint - functions/resources/Minify - - functions/resources/PostCSS + - functions/css/PostCSS - functions/resources/PostProcess returnType: resource.Resource signatures: ['resources.ToCSS [OPTIONS] RESOURCE'] toc: true +expiryDate: 2025-06-24 # deprecated 2024-06-24 --- +{{% deprecated-in 0.128.0 %}} +Use [css.Sass] instead. + +[css.Sass]: /functions/css/sass/ +{{% /deprecated-in %}} + ```go-html-template {{ with resources.Get "sass/main.scss" }} {{ $opts := dict "transpiler" "libsass" "targetPath" "css/style.css" }} @@ -76,7 +83,7 @@ includePaths "transpiler" "dartsass" "targetPath" "css/style.css" "vars" site.Params.styles - "enableSourceMap" (not hugo.IsProduction) + "enableSourceMap" (not hugo.IsProduction) "includePaths" (slice "node_modules/bootstrap/scss") }} {{ with resources.Get "sass/main.scss" | toCSS $opts | minify | fingerprint }} diff --git a/content/en/hugo-modules/configuration.md b/content/en/hugo-modules/configuration.md index 3aec4699bf..cd51614b62 100644 --- a/content/en/hugo-modules/configuration.md +++ b/content/en/hugo-modules/configuration.md @@ -25,25 +25,25 @@ workspace = 'off' {{< /code-toggle >}} noProxy -: Comma separated glob list matching paths that should not use the proxy configured above. +: (`string`) Comma separated glob list matching paths that should not use the proxy configured above. noVendor -: A optional Glob pattern matching module paths to skip when vendoring, e.g. "github.com/**" +: (`string`) A optional Glob pattern matching module paths to skip when vendoring, e.g. "github.com/**" private -: Comma separated glob list matching paths that should be treated as private. +: (`string`) Comma separated glob list matching paths that should be treated as private. proxy -: Defines the proxy server to use to download remote modules. Default is `direct`, which means "git clone" and similar. +: (`string`) Defines the proxy server to use to download remote modules. Default is `direct`, which means "git clone" and similar. vendorClosest -: When enabled, we will pick the vendored module closest to the module using it. The default behavior is to pick the first. Note that there can still be only one dependency of a given module path, so once it is in use it cannot be redefined. +: (`bool`) When enabled, we will pick the vendored module closest to the module using it. The default behavior is to pick the first. Note that there can still be only one dependency of a given module path, so once it is in use it cannot be redefined. Default is `false`. workspace -: The workspace file to use. This enables Go workspace mode. Note that this can also be set via OS env, e.g. `export HUGO_MODULE_WORKSPACE=/my/hugo.work` This only works with Go 1.18+. In Hugo `v0.109.0` we changed the default to `off` and we now resolve any relative work file names relative to the working directory. +: (`string`) The workspace file to use. This enables Go workspace mode. Note that this can also be set via OS env, e.g. `export HUGO_MODULE_WORKSPACE=/my/hugo.work` This only works with Go 1.18+. In Hugo `v0.109.0` we changed the default to `off` and we now resolve any relative work file names relative to the working directory. replacements -: A comma-separated list of mappings from module paths to directories, e.g. `github.com/bep/my-theme -> ../..,github.com/bep/shortcodes -> /some/path`. This is mostly useful for temporary local development of a module, in which case you might want to save it as an environment variable, e.g: `env HUGO_MODULE_REPLACEMENTS="github.com/bep/my-theme -> ../.."`. Relative paths are relative to [themesDir](/getting-started/configuration/#all-configuration-settings). Absolute paths are allowed. +: (`string`) A comma-separated list of mappings from module paths to directories, e.g. `github.com/bep/my-theme -> ../..,github.com/bep/shortcodes -> /some/path`. This is mostly useful for temporary local development of a module, in which case you might want to save it as an environment variable, e.g: `env HUGO_MODULE_REPLACEMENTS="github.com/bep/my-theme -> ../.."`. Relative paths are relative to [themesDir](/getting-started/configuration/#all-configuration-settings). Absolute paths are allowed. Note that the above terms maps directly to their counterparts in Go Modules. Some of these setting may be natural to set as OS environment variables. To set the proxy server to use, as an example: @@ -69,13 +69,13 @@ If your module requires a particular version of Hugo to work, you can indicate t Any of the above can be omitted. min -: The minimum Hugo version supported, e.g. `0.55.0` +: (`string`) The minimum Hugo version supported, e.g. `0.55.0` max -: The maximum Hugo version supported, e.g. `0.55.0` +: (`string`) The maximum Hugo version supported, e.g. `0.55.0` extended -: Whether the extended version of Hugo is required. +: (`bool`) Whether the extended version of Hugo is required. ## Module configuration: imports @@ -120,7 +120,8 @@ When the `mounts` configuration was introduced in Hugo 0.56.0, we were careful t When you add a mount, the default mount for the concerned target root is ignored: be sure to explicitly add it. {{% /note %}} -**Default mounts** +### Default mounts + {{< code-toggle file=hugo >}} [module] [[module.mounts]] @@ -147,25 +148,30 @@ When you add a mount, the default mount for the concerned target root is ignored {{< /code-toggle >}} source -: The source directory of the mount. For the main project, this can be either project-relative or absolute. For other modules it must be project-relative. +: (`string`) The source directory of the mount. For the main project, this can be either project-relative or absolute. For other modules it must be project-relative. target -: Where it should be mounted into Hugo's virtual filesystem. It must start with one of Hugo's component folders: `static`, `content`, `layouts`, `data`, `assets`, `i18n`, or `archetypes`. E.g. `content/blog`. +: (`string`) Where it should be mounted into Hugo's virtual filesystem. It must start with one of Hugo's component folders: `static`, `content`, `layouts`, `data`, `assets`, `i18n`, or `archetypes`. E.g. `content/blog`. + +disableWatch +{{< new-in 0.128.0 >}} +: (`bool`) Whether to disable watching in watch mode for this mount. Default is `false`. lang -: The language code, e.g. "en". Only relevant for `content` mounts, and `static` mounts when in multihost mode. +: (`string`) The language code, e.g. "en". Only relevant for `content` mounts, and `static` mounts when in multihost mode. -includeFiles (string or slice) -: One or more [glob](https://github.com/gobwas/glob) patterns matching files or directories to include. If `excludeFiles` is not set, the files matching `includeFiles` will be the files mounted. +includeFiles +: (`string` or `string slice`) One or more [glob](https://github.com/gobwas/glob) patterns matching files or directories to include. If `excludeFiles` is not set, the files matching `includeFiles` will be the files mounted. The glob patterns are matched to the file names starting from the `source` root, they should have Unix styled slashes even on Windows, `/` matches the mount root and `**` can be used as a super-asterisk to match recursively down all directories, e.g `/posts/**.jpg`. The search is case-insensitive. -excludeFiles (string or slice) -: One or more glob patterns matching files to exclude. +excludeFiles +: (`string` or `string slice`) One or more glob patterns matching files to exclude. + +### Example -**Example** {{< code-toggle file=hugo >}} [module] [[module.mounts]] diff --git a/content/en/hugo-pipes/babel.md b/content/en/hugo-pipes/babel.md index c447983a93..766ff8ae8b 100755 --- a/content/en/hugo-pipes/babel.md +++ b/content/en/hugo-pipes/babel.md @@ -11,12 +11,12 @@ weight: 70 function: aliases: [babel] returnType: resource.Resource - signatures: ['resources.Babel [OPTIONS] RESOURCE'] + signatures: ['js.Babel [OPTIONS] RESOURCE'] --- ## Usage -Any JavaScript resource file can be transpiled to another JavaScript version using `resources.Babel` which takes for argument the resource object and an optional dict of options listed below. Babel uses the [babel cli](https://babeljs.io/docs/en/babel-cli). +Any JavaScript resource file can be transpiled to another JavaScript version using `js.Babel` which takes for argument the resource object and an optional dict of options listed below. Babel uses the [babel cli](https://babeljs.io/docs/en/babel-cli). {{% note %}} Hugo Pipe's Babel requires the `@babel/cli` and `@babel/core` JavaScript packages to be installed in the project or globally (`npm install -g @babel/cli @babel/core`) along with any Babel plugin(s) or preset(s) used (e.g., `npm install @babel/preset-env --save-dev`). diff --git a/content/en/hugo-pipes/introduction.md b/content/en/hugo-pipes/introduction.md index c993377f8d..0e64303113 100755 --- a/content/en/hugo-pipes/introduction.md +++ b/content/en/hugo-pipes/introduction.md @@ -62,7 +62,7 @@ Hugo publishes assets to the `publishDir` (typically `public`) when you invoke ` For improved readability, the Hugo Pipes examples of this documentation will be written using [Go Pipes](/templates/introduction/#pipes): ```go-html-template -{{ $style := resources.Get "sass/main.scss" | resources.ToCSS | resources.Minify | resources.Fingerprint }} +{{ $style := resources.Get "sass/main.scss" | css.Sass | resources.Minify | resources.Fingerprint }} ``` diff --git a/content/en/hugo-pipes/postcss.md b/content/en/hugo-pipes/postcss.md index 148b30a7ea..9d3146c432 100755 --- a/content/en/hugo-pipes/postcss.md +++ b/content/en/hugo-pipes/postcss.md @@ -12,7 +12,7 @@ toc: true action: aliases: [postCSS] returnType: resource.Resource - signatures: ['resources.PostCSS [OPTIONS] RESOURCE'] + signatures: ['css.PostCSS [OPTIONS] RESOURCE'] --- ## Setup @@ -50,7 +50,7 @@ Step 4 : Place your CSS file within the `assets` directory. Step 5 -: Capture the CSS file as a resource and pipe it through `resources.PostCSS` (alias `postCSS`): +: Capture the CSS file as a resource and pipe it through `css.PostCSS` (alias `postCSS`): {{< code file=layouts/partials/css.html >}} {{ with resources.Get "css/main.css" | postCSS }} @@ -68,7 +68,7 @@ If starting with a Sass file within the `assets` directory: ## Options -The `resources.PostCSS` method takes an optional map of 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. diff --git a/content/en/hugo-pipes/postprocess.md b/content/en/hugo-pipes/postprocess.md index e84c6d72d3..cf99049fe4 100755 --- a/content/en/hugo-pipes/postprocess.md +++ b/content/en/hugo-pipes/postprocess.md @@ -27,7 +27,7 @@ There are currently two limitations to this: ```go-html-template {{ $css := resources.Get "css/main.css" }} - {{ $css = $css | resources.PostCSS | minify | fingerprint | resources.PostProcess }} + {{ $css = $css | css.PostCSS | minify | fingerprint | resources.PostProcess }} {{ $css.RelPermalink | upper }} ``` @@ -70,7 +70,7 @@ Note that in the example above, the "CSS purge step" will only be applied to the ```go-html-template {{ $css := resources.Get "css/main.css" }} -{{ $css = $css | resources.PostCSS }} +{{ $css = $css | css.PostCSS }} {{ if hugo.IsProduction }} {{ $css = $css | minify | fingerprint | resources.PostProcess }} {{ end }} diff --git a/content/en/hugo-pipes/resource-from-template.md b/content/en/hugo-pipes/resource-from-template.md index 1627fa7d4b..0c81f0c009 100755 --- a/content/en/hugo-pipes/resource-from-template.md +++ b/content/en/hugo-pipes/resource-from-template.md @@ -34,5 +34,5 @@ body{ ```go-html-template {{ $sassTemplate := resources.Get "sass/template.scss" }} -{{ $style := $sassTemplate | resources.ExecuteAsTemplate "main.scss" . | resources.ToCSS }} +{{ $style := $sassTemplate | resources.ExecuteAsTemplate "main.scss" . | css.Sass }} ``` diff --git a/content/en/hugo-pipes/transpile-sass-to-css.md b/content/en/hugo-pipes/transpile-sass-to-css.md index ba5c399660..0e0f7d815c 100644 --- a/content/en/hugo-pipes/transpile-sass-to-css.md +++ b/content/en/hugo-pipes/transpile-sass-to-css.md @@ -13,7 +13,7 @@ weight: 30 action: aliases: [toCSS] returnType: resource.Resource - signatures: ['resources.ToCSS [OPTIONS] RESOURCE'] + signatures: ['css.Sass [OPTIONS] RESOURCE'] toc: true aliases: [/hugo-pipes/transform-to-css/] --- @@ -73,7 +73,7 @@ includePaths "transpiler" "dartsass" "targetPath" "css/style.css" "vars" site.Params.styles - "enableSourceMap" (not hugo.IsProduction) + "enableSourceMap" (not hugo.IsProduction) "includePaths" (slice "node_modules/bootstrap/scss") }} {{ with resources.Get "sass/main.scss" | toCSS $opts | minify | fingerprint }} @@ -187,7 +187,7 @@ command = """\ ### Example -To transpile with Dart Sass, set `transpiler` to `dartsass` in the options map passed to `resources.ToCSS`. For example: +To transpile with Dart Sass, set `transpiler` to `dartsass` in the options map passed to `css.Sass`. For example: ```go-html-template {{ $opts := dict "transpiler" "dartsass" "targetPath" "css/style.css" }} diff --git a/content/en/methods/site/LastChange.md b/content/en/methods/site/LastChange.md index 1397f37708..65925c0eb5 100644 --- a/content/en/methods/site/LastChange.md +++ b/content/en/methods/site/LastChange.md @@ -7,7 +7,7 @@ action: related: [] returnType: time.Time signatures: [SITE.LastChange] -expiryDate: 2025-02-19 # deprecated 2024-02-19 +expiryDate: 2025-02-19 # deprecated 2024-02-19 --- {{% deprecated-in 0.123.0 %}} diff --git a/content/en/templates/shortcode-templates.md b/content/en/templates/shortcode-templates.md index 3c8e1d213b..dc8e615439 100644 --- a/content/en/templates/shortcode-templates.md +++ b/content/en/templates/shortcode-templates.md @@ -104,7 +104,7 @@ The `.Inner` method returns the content between the opening and closing shortcod ``` {{% note %}} -Any shortcode that calls the `.Inner` method must be closed or self-closed. To call a shortcode using the self-closing sytax +Any shortcode that calls the `.Inner` method must be closed or self-closed. To call a shortcode using the self-closing syntax. ```go-html-template {{}} diff --git a/data/docs.yaml b/data/docs.yaml index 476d374a1f..4dd65d3052 100644 --- a/data/docs.yaml +++ b/data/docs.yaml @@ -1369,37 +1369,44 @@ config: min: "" imports: null mounts: - - excludeFiles: null + - disableWatch: false + excludeFiles: null includeFiles: null lang: "" source: content target: content - - excludeFiles: null + - disableWatch: false + excludeFiles: null includeFiles: null lang: "" source: data target: data - - excludeFiles: null + - disableWatch: false + excludeFiles: null includeFiles: null lang: "" source: layouts target: layouts - - excludeFiles: null + - disableWatch: false + excludeFiles: null includeFiles: null lang: "" source: i18n target: i18n - - excludeFiles: null + - disableWatch: false + excludeFiles: null includeFiles: null lang: "" source: archetypes target: archetypes - - excludeFiles: null + - disableWatch: false + excludeFiles: null includeFiles: null lang: "" source: assets target: assets - - excludeFiles: null + - disableWatch: false + excludeFiles: null includeFiles: null lang: "" source: static @@ -1667,6 +1674,7 @@ config: - ^go$ - ^npx$ - ^postcss$ + - ^tailwindcss$ osEnv: - (?i)^((HTTPS?|NO)_PROXY|PATH(EXT)?|APPDATA|TE?MP|TERM|GO\w+|(XDG_CONFIG_)?HOME|USERPROFILE|SSH_AUTH_SOCK|DISPLAY|LANG|SYSTEMDRIVE)$ funcs: @@ -2799,11 +2807,30 @@ tpl: - - '{{ sha256 "Hello world, gophers!" }}' - 6ec43b78da9669f50e4e422575c54bf87536954ccd58280219c393f2ce352b46 css: + PostCSS: + Aliases: + - postCSS + Args: + - args + Description: PostCSS processes the given Resource with PostCSS. + Examples: [] Quoted: Aliases: null Args: null Description: "" Examples: null + Sass: + Aliases: + - toCSS + Args: + - args + Description: Sass processes the given Resource with SASS. + Examples: [] + TailwindCSS: + Aliases: null + Args: null + Description: "" + Examples: null Unquoted: Aliases: null Args: null @@ -3239,6 +3266,13 @@ tpl: - - '{{ "cats" | singularize }}' - cat js: + Babel: + Aliases: + - babel + Args: + - args + Description: Babel processes the given Resource with Babel. + Examples: [] Build: Aliases: null Args: null @@ -3668,12 +3702,10 @@ tpl: - Slice resources: Babel: - Aliases: - - babel - Args: - - args - Description: Babel processes the given Resource with Babel. - Examples: [] + Aliases: null + Args: null + Description: "" + Examples: null ByType: Aliases: null Args: null @@ -3749,27 +3781,20 @@ tpl: minifier. Examples: [] PostCSS: - Aliases: - - postCSS - Args: - - args - Description: PostCSS processes the given Resource with PostCSS - Examples: [] + Aliases: null + Args: null + Description: "" + Examples: null PostProcess: Aliases: null Args: null Description: "" Examples: null ToCSS: - Aliases: - - toCSS - Args: - - args - Description: |- - ToCSS converts the given Resource to CSS. You can optional provide an Options object - as second argument. As an option, you can e.g. specify e.g. the target path (string) - for the converted CSS resource. - Examples: [] + Aliases: null + Args: null + Description: "" + Examples: null safe: CSS: Aliases: @@ -3849,6 +3874,11 @@ tpl: Args: null Description: "" Examples: null + CheckReady: + Aliases: null + Args: null + Description: "" + Examples: null Config: Aliases: null Args: null @@ -4350,6 +4380,23 @@ tpl: - - '{{ "With [Markdown](/markdown) inside." | markdownify | truncate 14 }}' - With Markdown … templates: + Defer: + Aliases: null + Args: + - args + Description: Defer defers the execution of a template block. + Examples: [] + DoDefer: + Aliases: + - doDefer + Args: + - ctx + - id + - optsv + Description: |- + DoDefer defers the execution of a template block. + For internal use only. + Examples: [] Exists: Aliases: null Args: