diff options
author | Bjørn Erik Pedersen <bjorn.erik.pedersen@gmail.com> | 2023-01-17 12:51:01 +0100 |
---|---|---|
committer | Bjørn Erik Pedersen <bjorn.erik.pedersen@gmail.com> | 2023-01-17 12:51:01 +0100 |
commit | ef6f101e75256c3bb88a6f1f3b5c1273bf8d7382 (patch) | |
tree | dfb035e3998be1faa66623c8a594cac0863208af /content/en | |
parent | 41bc6f702aa54200530efbf4267e5c823df3028d (diff) |
1214f6ffb Document cleanDestinationDir configuration setting
27ca65463 Clarify .Page.Param method (#1953)
3fa1792d2 Document the usage of `hardWrap` option for markdown rendering (#1951)
8b5afdfb4 Update theme
207e7f0a0 fix docs for getting remote font
1f7094b9e Correct typo
f9d6445c4 Added missing `/` in URL generator (#1946)
3a22ee7d6 Remove translations
b3b900f3f Update introduction.md
aca440052 rm Forestry - facing end-of-life shortly (#1944)
af0014e14 Update scss-sass.md
1c43bbbc9 Merge branch 'docs/goworkspace'
d034175ca netlify: Hugo 0.109.0
d3a6a5c3f Merge branch 'tempv0.109.0'
e033dbead docs: Regen docs helper JSON
452bf675c resource/page: Add Page.Ancestors
12edd7363 Add some docs for workspaces
8f0fcba6b Add HUGO_PUBLISHDIR to the Node environment
4e66d98ad Update theme
808aee6f6 config: Update to ga v4
1de2bc5a9 config: Update to ga v4
ddb5fd6b0 Merge commit '41bc6f702aa54200530efbf4267e5c823df3028d'
54c54bf76 modules: Adjust watch logic vs workspace use definitions
git-subtree-dir: docs
git-subtree-split: 1214f6ffbf680e853746aaeb6cb097b28c0c556b
Diffstat (limited to 'content/en')
-rw-r--r-- | content/en/content-management/sections.md | 21 | ||||
-rw-r--r-- | content/en/functions/images/index.md | 2 | ||||
-rw-r--r-- | content/en/functions/param.md | 59 | ||||
-rw-r--r-- | content/en/getting-started/configuration-markup.md | 3 | ||||
-rw-r--r-- | content/en/getting-started/configuration.md | 8 | ||||
-rw-r--r-- | content/en/getting-started/usage.md | 2 | ||||
-rw-r--r-- | content/en/hugo-modules/configuration.md | 4 | ||||
-rw-r--r-- | content/en/hugo-modules/use-modules.md | 30 | ||||
-rwxr-xr-x | content/en/hugo-pipes/introduction.md | 22 | ||||
-rwxr-xr-x | content/en/hugo-pipes/postprocess.md | 27 | ||||
-rwxr-xr-x | content/en/hugo-pipes/scss-sass.md | 3 | ||||
-rw-r--r-- | content/en/templates/single-page-templates.md | 29 | ||||
-rw-r--r-- | content/en/tools/frontends.md | 1 | ||||
-rw-r--r-- | content/en/variables/page.md | 3 |
14 files changed, 146 insertions, 68 deletions
diff --git a/content/en/content-management/sections.md b/content/en/content-management/sections.md index 5ff884610..b68a5bdb9 100644 --- a/content/en/content-management/sections.md +++ b/content/en/content-management/sections.md @@ -63,19 +63,16 @@ If you need a specific template for a sub-section, you need to adjust either the With the available [section variables and methods](#section-page-variables-and-methods) you can build powerful navigation. One common example would be a partial to show Breadcrumb navigation: {{< code file="layouts/partials/breadcrumb.html" download="breadcrumb.html" >}} -<ol class="nav navbar-nav"> - {{ template "breadcrumbnav" (dict "p1" . "p2" .) }} -</ol> -{{ define "breadcrumbnav" }} -{{ if .p1.Parent }} -{{ template "breadcrumbnav" (dict "p1" .p1.Parent "p2" .p2 ) }} -{{ else if not .p1.IsHome }} -{{ template "breadcrumbnav" (dict "p1" .p1.Site.Home "p2" .p2 ) }} -{{ end }} -<li{{ if eq .p1 .p2 }} class="active" aria-current="page" {{ end }}> - <a href="{{ .p1.Permalink }}">{{ .p1.Title }}</a> +<ol class="nav navbar-nav"> +<ul> +{{- range .Ancestors.Reverse }} +<li><a href="{{ .Permalink }}">{{ .Title }}</a></li> +{{- end }} +<li class="active" aria-current="page"> +<a href="{{ .Permalink }}">{{ .Title }}</a> </li> -{{ end }} +</ul> +</ol> {{< /code >}} ## Section Page Variables and Methods diff --git a/content/en/functions/images/index.md b/content/en/functions/images/index.md index 0cf45b6ee..e7fc50f7e 100644 --- a/content/en/functions/images/index.md +++ b/content/en/functions/images/index.md @@ -60,7 +60,7 @@ You can load a custom font if needed. Load the font as a Hugo `Resource` and set ```go-html-template -{{ $font := resources.Get "https://github.com/google/fonts/raw/main/apache/roboto/static/Roboto-Black.ttf" }} +{{ $font := resources.GetRemote "https://github.com/google/fonts/raw/main/apache/roboto/static/Roboto-Black.ttf" }} {{ $img := resources.Get "/images/background.png"}} {{ $img = $img.Filter (images.Text "Hugo rocks!" (dict "font" $font diff --git a/content/en/functions/param.md b/content/en/functions/param.md index 5387647d2..4f1764814 100644 --- a/content/en/functions/param.md +++ b/content/en/functions/param.md @@ -1,40 +1,47 @@ --- title: .Param -description: Calls page or site variables into your template. -date: 2017-02-01 -publishdate: 2017-02-01 -lastmod: 2017-04-30 -keywords: ["front matter"] +description: Returns a page parameter, falling back to a site parameter if present. +signature: ['.Param KEY'] categories: [functions] +keywords: ['front matter', 'params'] menu: docs: - parent: "functions" -toc: -signature: [".Param KEY"] -workson: [] -hugoversion: -relatedfuncs: [default] -deprecated: false -draft: false + parent: 'functions' aliases: [] --- -In Hugo, you can declare [site-wide params][sitevars] (i.e. in your [configuration]), as well as params for [individual pages][pagevars]. +The `.Param` method on `.Page` looks for the given `KEY` in page parameters, and returns the corresponding value. If it cannot find the `KEY` in page parameters, it looks for the `KEY` in site parameters. If it cannot find the `KEY` in either location, the `.Param` method returns `nil`. -A common use case is to have a general value for the site and a more specific value for some of the pages (e.g., an image). +Site and theme developers commonly set parameters at the site level, allowing content authors to override those parameters at the page level. -You can use the `.Param` method to call these values into your template. The following will first look for an `image` param in a specific content's [front matter]. If not found, Hugo will look for an `image` param in your site's configuration: +For example, to show a table of contents on every page, but allow authors to hide the table of contents as needed: -``` -$.Param "image" -``` +**Configuration** -{{% note %}} -The `Param` method may not consider empty strings in a content's front matter as "not found." If you are setting preconfigured front matter fields to empty strings using Hugo's archetypes, it may be best to use the [`default` function](/functions/default/) instead of `Param`. See the [related issue on GitHub](https://github.com/gohugoio/hugo/issues/3366). -{{% /note %}} +{{< code-toggle file="config" copy=false >}} +[params] +display_toc = true +{{< /code-toggle >}} +**Content** -[configuration]: /getting-started/configuration/ -[front matter]: /content-management/front-matter/ -[pagevars]: /variables/page/ -[sitevars]: /variables/site/ +{{< code-toggle file="content/about.md" fm=true copy=false >}} +title = 'About' +date = 2023-01-01 +draft = false +display_toc = false +{{< /code-toggle >}} + +**Template** + +{{< code file="layouts/_default/single.html" copy="false" >}} +{{ if .Param "display_toc" }} + {{ .TableOfContents }} +{{ end }} +{{< /code >}} + +The `.Param` method returns the value associated with the given `KEY`, regardless of whether the value is truthy or falsy. If you need to ignore falsy values, use this construct instead: + +{{< code file="layouts/_default/single.html" copy="false" >}} +{{ or .Params.foo site.Params.foo }} +{{< /code >}} diff --git a/content/en/getting-started/configuration-markup.md b/content/en/getting-started/configuration-markup.md index 4694bd439..b55bd79c4 100644 --- a/content/en/getting-started/configuration-markup.md +++ b/content/en/getting-started/configuration-markup.md @@ -32,6 +32,9 @@ For details on the extensions, refer to [this section](https://github.com/yuin/g Some settings explained: +hardWrap +: By default, Goldmark ignores newlines within a paragraph. Set to `true` to render newlines as `<br>` elements. + unsafe : By default, Goldmark does not render raw HTMLs and potentially dangerous links. If you have lots of inline HTML and/or JavaScript, you may need to turn this on. diff --git a/content/en/getting-started/configuration.md b/content/en/getting-started/configuration.md index 39f27453f..3c9b42678 100644 --- a/content/en/getting-started/configuration.md +++ b/content/en/getting-started/configuration.md @@ -173,6 +173,12 @@ Pass down default configuration values (front matter) to pages in the content tr Enable to turn relative URLs into absolute. +### cleanDestinationDir + +**Default value:** false + +When building, removes files from destination not found in static directories. + ### contentDir **Default value:** "content" @@ -231,7 +237,7 @@ Disable automatic live reloading of browser window. **Default value:** false -: Do not convert the url/path to lowercase. +Do not convert the url/path to lowercase. ### enableEmoji diff --git a/content/en/getting-started/usage.md b/content/en/getting-started/usage.md index edf3e82a5..15cf46cbf 100644 --- a/content/en/getting-started/usage.md +++ b/content/en/getting-started/usage.md @@ -120,7 +120,7 @@ hugo server --navigateToChanged As noted above, Hugo does not clear the public directory before building your site. Manually clear the contents of the public directory before each build to remove draft, expired, and future content. {{% /note %}} -When are ready to deploy your site, run: +When you are ready to deploy your site, run: ```bash hugo diff --git a/content/en/hugo-modules/configuration.md b/content/en/hugo-modules/configuration.md index c05201f8a..5b19d2419 100644 --- a/content/en/hugo-modules/configuration.md +++ b/content/en/hugo-modules/configuration.md @@ -23,7 +23,7 @@ proxy = "direct" noProxy = "none" private = "*.*" replacements = "" -workspace = "" +workspace = "off" {{< /code-toggle >}} noVendor @@ -42,7 +42,7 @@ private : Comma separated glob list matching paths that should be treated as private. 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+. +: 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 filenames relative to the working directory. replacements : A comma separated (or a slice) list of module path to directory replacement mapping, e.g. `github.com/bep/my-theme -> ../..,github.com/bep/shortcodes -> /some/path`. This is mostly useful for temporary locally development of a module, and then it makes sense to set it as an OS environment variable, e.g: `env HUGO_MODULE_REPLACEMENTS="github.com/bep/my-theme -> ../.."`. Any relative path is relate to [themesDir](https://gohugo.io/getting-started/configuration/#all-configuration-settings), and absolute paths are allowed. diff --git a/content/en/hugo-modules/use-modules.md b/content/en/hugo-modules/use-modules.md index 8870307b3..977a52bd6 100644 --- a/content/en/hugo-modules/use-modules.md +++ b/content/en/hugo-modules/use-modules.md @@ -135,3 +135,33 @@ Run `hugo mod clean` to delete the entire modules cache. Note that you can also configure the `modules` cache with a `maxAge`, see [File Caches](/getting-started/configuration/#configure-file-caches). Also see the [CLI Doc](/commands/hugo_mod_clean/). + +## Module Workspaces + +{{< new-in "0.109.0" >}} + +Workspace support was added in [Go 1.18](https://go.dev/blog/get-familiar-with-workspaces) and Hugo got solid support for it in the `v0.109.0` version. + +A common use case for a workspace is to simplify local development of a site with its theme modules. + +A workspace can be configured in a `*.work` file and activated with the [module.workspace](/hugo-modules/configuration/) setting, which for this use is commonly controlled via the `HUGO_MODULE_WORKSPACE` OS environment variable. + +See the [hugo.work](https://github.com/gohugoio/hugo/blob/master/hugo.work) file in the Hugo Docs repo for an example: + +``` +go 1.19 + +use . +use ../gohugoioTheme +``` + +Using the `use` directive, list all the modules you want to work on, pointing to its relative location. As in the example above, it's recommended to always include the main project (the ".") in the list. + +With that you can start the Hugo server with that workspace enabled: + +``` +HUGO_MODULE_WORKSPACE=hugo.work hugo server --ignoreVendorPaths "**" +``` + +The `--ignoreVendorPaths` flag is added above to ignore any of the vendored dependencies inside `_vendor`. If you don't use vendoring, you don't need that flag. But now the server is set up watching the files and directories in the workspace and you can see your local edits reloaded. + diff --git a/content/en/hugo-pipes/introduction.md b/content/en/hugo-pipes/introduction.md index c16572e48..f38ec5895 100755 --- a/content/en/hugo-pipes/introduction.md +++ b/content/en/hugo-pipes/introduction.md @@ -50,16 +50,6 @@ With `resources.GetRemote`, the first argument is a remote URL: `resources.Get` and `resources.GetRemote` return `nil` if the resource is not found. -## Copy a Resource - -{{< new-in "0.100.0" >}} - -`resources.Copy` allows you to copy almost any Hugo `Resource` (the one exception is the `Page`), possibly most useful for renaming things: - -```go-html-template -{{ $resized := $image.Resize "400x400" | resources.Copy "images/mynewname.jpg" }} -<img src="{{ $resized.RelPermalink }}"> -``` ### Caching @@ -119,6 +109,18 @@ You can also change the request method and set the request body: Remote resources fetched with `resources.GetRemote` will be cached on disk. See [Configure File Caches](/getting-started/configuration/#configure-file-caches) for details. + +## Copy a Resource + +{{< new-in "0.100.0" >}} + +`resources.Copy` allows you to copy almost any Hugo `Resource` (the one exception is the `Page`), possibly most useful for renaming things: + +```go-html-template +{{ $resized := $image.Resize "400x400" | resources.Copy "images/mynewname.jpg" }} +<img src="{{ $resized.RelPermalink }}"> +``` + ## Asset directory Asset files must be stored in the asset directory. This is `/assets` by default, but can be configured via the configuration file's `assetDir` key. diff --git a/content/en/hugo-pipes/postprocess.md b/content/en/hugo-pipes/postprocess.md index 1aa398356..55552d105 100755 --- a/content/en/hugo-pipes/postprocess.md +++ b/content/en/hugo-pipes/postprocess.md @@ -68,3 +68,30 @@ Note that in the example above, the "CSS purge step" will only be applied to the {{ end }} <link href="{{ $css.RelPermalink }}" rel="stylesheet" /> ``` + + +## Hugo Environment variables available in PostCSS + +These are the environment variables Hugo passes down to PostCSS (and Babel), which allows you do do `process.env.HUGO_ENVIRONMENT === 'production' ? [autoprefixer] : []` and similar: + +PWD +: The absolute path to the project working directory. +HUGO_ENVIRONMENT (and the alias HUGO_ENV) +: The value e.g. set with `hugo -e production` (defaults to `production` for `hugo` and `development` for `hugo server`). + +HUGO_PUBLISHDIR +: {{ new-in "0.109.0" }} The absolute path to the publish directory (the `public` directory). Note that the value will always point to a directory on disk even when running `hugo server` in memory mode. If you write to this folder from PostCSS when running the server, you could run the server with one of these flags: + +``` +hugo server --renderToDisk +hugo server --renderStaticToDisk +``` + +Also, Hugo will add environment variables for all files mounted below `assets/_jsconfig`. A default mount will be set up with files in the project root matching this regexp: `(babel|postcss|tailwind)\.config\.js`. + +These will get environment variables named on the form `HUGO_FILE_:filename:` where `:filename:` is all upper case with periods replaced with underscore. This allows you do do this and similar: + +```js +let tailwindConfig = process.env.HUGO_FILE_TAILWIND_CONFIG_JS || './tailwind.config.js'; +``` + diff --git a/content/en/hugo-pipes/scss-sass.md b/content/en/hugo-pipes/scss-sass.md index 169c473d2..4e39207fa 100755 --- a/content/en/hugo-pipes/scss-sass.md +++ b/content/en/hugo-pipes/scss-sass.md @@ -29,6 +29,9 @@ transpiler [string] targetPath [string] : If not set, the resource's target path will be the asset file original path with its extension replaced by `.css`. +vars [map] +: Map of key/value pairs that will be available in the `hugo:vars` namespace, e.g. with `@use "hugo:vars" as v;` or (globally) with `@import "hugo:vars";` {{< new-in "0.109.0" >}} + outputStyle [string] : Default is `nested` (LibSass) and `expanded` (Dart Sass). Other available output styles for LibSass are `expanded`, `compact` and `compressed`. Dart Sass only supports `expanded` and `compressed`. diff --git a/content/en/templates/single-page-templates.md b/content/en/templates/single-page-templates.md index 2b0cfe0e2..925f97b03 100644 --- a/content/en/templates/single-page-templates.md +++ b/content/en/templates/single-page-templates.md @@ -6,7 +6,7 @@ date: 2017-02-01 publishdate: 2017-02-01 lastmod: 2017-04-06 categories: [templates] -keywords: [page,templates] +keywords: [page, templates] menu: docs: parent: "templates" @@ -32,6 +32,7 @@ This single page template makes use of Hugo [base templates], the [`.Format` fun {{< code file="layouts/posts/single.html" download="single.html" >}} {{ define "main" }} + <section id="main"> <h1 id="title">{{ .Title }}</h1> <div> @@ -46,20 +47,20 @@ This single page template makes use of Hugo [base templates], the [`.Format` fun <h4 id="date"> {{ .Date.Format "Mon Jan 2, 2006" }} </h4> <h5 id="wordcount"> {{ .WordCount }} Words </h5> </section> - {{ with .Params.topics }} - <ul id="topics"> - {{ range . }} - <li><a href="{{ "topics" | absURL}}{{ . | urlize }}">{{ . }}</a> </li> + {{ with .GetTerms "topics" }} + <ul id="topics"> + {{ range . }} + <li><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></li> + {{ end }} + </ul> {{ end }} - </ul> - {{ end }} - {{ with .Params.tags }} - <ul id="tags"> - {{ range . }} - <li> <a href="{{ "tags" | absURL }}{{ . | urlize }}">{{ . }}</a> </li> + {{ with .GetTerms "tags" }} + <ul id="tags"> + {{ range . }} + <li><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></li> + {{ end }} + </ul> {{ end }} - </ul> - {{ end }} </div> <div> {{ with .PrevInSection }} @@ -81,7 +82,7 @@ To easily generate new instances of a content type (e.g., new `.md` files in a s [content type]: /content-management/types/ [directory structure]: /getting-started/directory-structure/ [dry]: https://en.wikipedia.org/wiki/Don%27t_repeat_yourself -[`.Format` function]: /functions/format/ +[`.format` function]: /functions/format/ [front matter]: /content-management/front-matter/ [pagetaxonomy]: /templates/taxonomy-templates/#display-a-single-piece-of-contents-taxonomies [pagevars]: /variables/page/ diff --git a/content/en/tools/frontends.md b/content/en/tools/frontends.md index 9f52c4c67..7ad44df53 100644 --- a/content/en/tools/frontends.md +++ b/content/en/tools/frontends.md @@ -26,5 +26,4 @@ toc: false ## Commercial Services - [DATOCMS](https://www.datocms.com) DatoCMS is a fully customizable administrative area for your static websites. Use your favorite website generator, let your clients publish new content independently, and the host the site anywhere you like. -- [Forestry.io](https://forestry.io/). Forestry is a git-backed CMS for Hugo, Gatsby, Jekyll and VuePress websites with support for GitHub, GitLab, Bitbucket and Azure Devops. Forestry provides a nice user interface to edit and model content for non technical editors. It supports S3, Cloudinary and Netlify Large Media integrations for storing media. Every time an update is made via the CMS, Forestry will commit changes back to your repo and vice-versa. - [CloudCannon](https://cloudcannon.com/hugo-cms/). The intuitive Git-based CMS for your Hugo website. CloudCannon syncs changes from your Git repository and pushes content changes back, so your development and content teams are always in sync. Edit all of your content on the page with visual editing, build entire pages with reusable custom components and then publish confidently. diff --git a/content/en/variables/page.md b/content/en/variables/page.md index 07acc4831..2de54ff8b 100644 --- a/content/en/variables/page.md +++ b/content/en/variables/page.md @@ -32,6 +32,9 @@ See [`.Scratch`](/functions/scratch/) for page-scoped, writable variables. .Aliases : aliases of this page +.Ancestors +: get the ancestors of each page, simplify [breadcrumb navigation]({{< relref "content-management/sections#example-breadcrumb-navigation" >}}) implementation complexity + .BundleType : the [bundle] type: `leaf`, `branch`, or an empty string if the page is not a bundle. |