diff --git a/docs/.markdownlint.yaml b/docs/.markdownlint.yaml index d9c2c5a6743..ee0a28909ca 100644 --- a/docs/.markdownlint.yaml +++ b/docs/.markdownlint.yaml @@ -23,3 +23,4 @@ MD046: false MD049: false MD050: false MD053: false +MD055: false diff --git a/docs/_vendor/github.com/gohugoio/gohugoioTheme/assets/css/_code.css b/docs/_vendor/github.com/gohugoio/gohugoioTheme/assets/css/_code.css index c82e77ee776..9906a13d022 100644 --- a/docs/_vendor/github.com/gohugoio/gohugoioTheme/assets/css/_code.css +++ b/docs/_vendor/github.com/gohugoio/gohugoioTheme/assets/css/_code.css @@ -10,9 +10,9 @@ } code { - padding: 0.2em; + padding: 2px 3px; margin: 0; - font-size: 85%; + font-size: 93.75%; background-color: rgba(27,31,35,0.05); border-radius: 3px; } diff --git a/docs/_vendor/github.com/gohugoio/gohugoioTheme/assets/output/css/app.css b/docs/_vendor/github.com/gohugoio/gohugoioTheme/assets/output/css/app.css index b6343c7be82..4fd374a1fe1 100644 --- a/docs/_vendor/github.com/gohugoio/gohugoioTheme/assets/output/css/app.css +++ b/docs/_vendor/github.com/gohugoio/gohugoioTheme/assets/output/css/app.css @@ -4769,9 +4769,9 @@ h6:hover .header-link { margin: 0; } code { - padding: 0.2em; + padding: 2px 3px; margin: 0; - font-size: 85%; + font-size: 93.75%; background-color: rgba(27, 31, 35, .05); border-radius: 3px; } diff --git a/docs/_vendor/github.com/gohugoio/gohugoioTheme/layouts/partials/components/author-github-data-card.html b/docs/_vendor/github.com/gohugoio/gohugoioTheme/layouts/partials/components/author-github-data-card.html index 4caa21f3e2d..d3edadaac0f 100644 --- a/docs/_vendor/github.com/gohugoio/gohugoioTheme/layouts/partials/components/author-github-data-card.html +++ b/docs/_vendor/github.com/gohugoio/gohugoioTheme/layouts/partials/components/author-github-data-card.html @@ -4,14 +4,14 @@ {{ $data := "" }} {{ $url := urls.JoinPath "https://api.github.com/users" $author }} - {{ with resources.GetRemote $url }} + {{ with try (resources.GetRemote $url) }} {{ with .Err }} {{ errorf "%s" . }} - {{ else }} + {{ else with .Value }} {{ $data = . | transform.Unmarshal }} + {{ else }} + {{ errorf "Unable to get remote resource %q" $url }} {{ end }} - {{ else }} - {{ errorf "Unable to get remote resource %q" $url }} {{ end }}
diff --git a/docs/_vendor/github.com/gohugoio/gohugoioTheme/layouts/partials/components/author-github-data.html b/docs/_vendor/github.com/gohugoio/gohugoioTheme/layouts/partials/components/author-github-data.html index fbad3a0a74a..c281e411fce 100644 --- a/docs/_vendor/github.com/gohugoio/gohugoioTheme/layouts/partials/components/author-github-data.html +++ b/docs/_vendor/github.com/gohugoio/gohugoioTheme/layouts/partials/components/author-github-data.html @@ -4,14 +4,14 @@ {{ $data := "" }} {{ $url := urls.JoinPath "https://api.github.com/users" $author }} - {{ with resources.GetRemote $url }} + {{ with try (resources.GetRemote $url) }} {{ with .Err }} {{ errorf "%s" . }} - {{ else }} + {{ else with .Value }} {{ $data = . | transform.Unmarshal }} + {{ else }} + {{ errorf "Unable to get remote resource %q" $url }} {{ end }} - {{ else }} - {{ errorf "Unable to get remote resource %q" $url }} {{ end }} {{ with $data }} diff --git a/docs/_vendor/github.com/gohugoio/gohugoioTheme/layouts/partials/utilities/get-remote-data.html b/docs/_vendor/github.com/gohugoio/gohugoioTheme/layouts/partials/utilities/get-remote-data.html index 69ac41da40a..78b2ba06e99 100644 --- a/docs/_vendor/github.com/gohugoio/gohugoioTheme/layouts/partials/utilities/get-remote-data.html +++ b/docs/_vendor/github.com/gohugoio/gohugoioTheme/layouts/partials/utilities/get-remote-data.html @@ -11,13 +11,13 @@ {{ $url := . }} {{ $data := dict }} -{{ with resources.GetRemote $url }} +{{ with try (resources.GetRemote $url) }} {{ with .Err }} {{ errorf "%s" . }} - {{ else }} + {{ else with .Value }} {{ $data = .Content | transform.Unmarshal }} + {{ else }} + {{ errorf "Unable to get remote resource %q" $url }} {{ end }} -{{ else }} - {{ errorf "Unable to get remote resource %q" $url }} {{ end }} {{ return $data }} diff --git a/docs/_vendor/github.com/gohugoio/gohugoioTheme/layouts/shortcodes/hl.html b/docs/_vendor/github.com/gohugoio/gohugoioTheme/layouts/shortcodes/hl.html new file mode 100644 index 00000000000..1a5b4e1ec8e --- /dev/null +++ b/docs/_vendor/github.com/gohugoio/gohugoioTheme/layouts/shortcodes/hl.html @@ -0,0 +1,11 @@ +{{- /* +Returns syntax-highlighted code from the given text. + +This is useful as a terse way to highlight inline code snippets. Calling the +highlight shortcode for inline snippets is verbose. +*/}} + +{{- $code := .Inner | strings.TrimSpace }} +{{- $lang := or (.Get 0) "go" }} +{{- $opts := dict "hl_inline" true "noClasses" true }} +{{- transform.Highlight $code $lang $opts }} diff --git a/docs/_vendor/github.com/gohugoio/gohugoioTheme/layouts/shortcodes/img.html b/docs/_vendor/github.com/gohugoio/gohugoioTheme/layouts/shortcodes/img.html index dd8c60e18bd..7c2d805d2c0 100644 --- a/docs/_vendor/github.com/gohugoio/gohugoioTheme/layouts/shortcodes/img.html +++ b/docs/_vendor/github.com/gohugoio/gohugoioTheme/layouts/shortcodes/img.html @@ -120,8 +120,8 @@ {{- $validFilters := slice "autoorient" "brightness" "colorbalance" "colorize" "contrast" "dither" - "gamma" "gaussianblur" "grayscale" "hue" "invert" "none" "opacity" "overlay" - "padding" "pixelate" "process" "saturation" "sepia" "sigmoid" "text" + "gamma" "gaussianblur" "grayscale" "hue" "invert" "mask" "none" "opacity" + "overlay" "padding" "pixelate" "process" "saturation" "sepia" "sigmoid" "text" "unsharpmask" }} @@ -229,6 +229,12 @@ {{- $ctx = merge $ctx (dict "argsRequired" 0) }} {{- template "validate-arg-count" $ctx }} {{- $f = images.Invert }} +{{- else if eq $filter "mask" }} + {{- $ctx = merge $ctx (dict "argsRequired" 1) }} + {{- template "validate-arg-count" $ctx }} + {{- $ctx := dict "src" (index $filterArgs 0) "name" .Name "position" .Position }} + {{- $maskImage := partial "inline/get-resource.html" $ctx }} + {{- $f = images.Mask $maskImage }} {{- else if eq $filter "opacity" }} {{- $ctx = merge $ctx (dict "argsRequired" 1) }} {{- template "validate-arg-count" $ctx }} @@ -322,11 +328,15 @@ {{- end }} {{- /* Render. */}} +{{- $class := "di va b--black-20" }} +{{- if eq $filter "mask" }} + {{- $class = "di va" }} +{{- end }} {{- if $example }}

Original

- {{ $alt }} + {{ $alt }}

Processed

- {{ $alt }} + {{ $alt }} {{- else -}} {{ $alt }} {{- end }} @@ -354,15 +364,15 @@ {{- $u := urls.Parse .src }} {{- $msg := "The %q shortcode was unable to resolve %s. See %s" }} {{- if $u.IsAbs }} - {{- with resources.GetRemote $u.String }} + {{- with try (resources.GetRemote $u.String) }} {{- with .Err }} {{- errorf "%s" . }} - {{- else }} + {{- else with .Value }} {{- /* This is a remote resource. */}} {{- $r = . }} + {{- else }} + {{- errorf $msg $.name $u.String $.position }} {{- end }} - {{- else }} - {{- errorf $msg $.name $u.String $.position }} {{- end }} {{- else }} {{- with .page.Resources.Get (strings.TrimPrefix "./" $u.Path) }} diff --git a/docs/_vendor/modules.txt b/docs/_vendor/modules.txt index a5092f11edc..50178323d2d 100644 --- a/docs/_vendor/modules.txt +++ b/docs/_vendor/modules.txt @@ -1 +1 @@ -# github.com/gohugoio/gohugoioTheme v0.0.0-20250106044328-feb60697e056 +# github.com/gohugoio/gohugoioTheme v0.0.0-20250116152525-2d382cae7743 diff --git a/docs/archetypes/glossary.md b/docs/archetypes/glossary.md new file mode 100644 index 00000000000..b38ced64ad0 --- /dev/null +++ b/docs/archetypes/glossary.md @@ -0,0 +1,19 @@ +--- +title: {{ replace .File.ContentBaseName "-" " " }} +--- + + diff --git a/docs/archetypes/showcase/index.md b/docs/archetypes/showcase/index.md index 04d4545756f..cdd0367224a 100644 --- a/docs/archetypes/showcase/index.md +++ b/docs/archetypes/showcase/index.md @@ -20,7 +20,7 @@ byline: "[bep](https://github.com/bep), Hugo Lead" To complete this showcase: 1. Write the story about your site in this file. -2. Add a summary to the `bio.md` file in this folder. +2. Add a summary to the `bio.md` file in this directory. 3. Replace the `featured-template.png` with a screenshot of your site. You can rename it, but it must contain the word `featured`. 4. Create a new pull request in https://github.com/gohugoio/hugoDocs/pulls diff --git a/docs/assets/images/examples/mask.png b/docs/assets/images/examples/mask.png new file mode 100644 index 00000000000..c3005a66949 Binary files /dev/null and b/docs/assets/images/examples/mask.png differ diff --git a/docs/config/_default/menus/menus.en.toml b/docs/config/_default/menus/menus.en.toml index 3f4e76879a3..aac432fab58 100644 --- a/docs/config/_default/menus/menus.en.toml +++ b/docs/config/_default/menus/menus.en.toml @@ -55,20 +55,26 @@ identifier = 'render-hooks' pageRef = '/render-hooks/' [[docs]] -name = 'Hugo Modules' +name = 'Shortcodes' weight = 100 +identifier = 'shortcodes' +pageRef = '/shortcodes/' + +[[docs]] +name = 'Hugo Modules' +weight = 110 identifier = 'modules' pageRef = '/hugo-modules/' [[docs]] name = 'Hugo Pipes' -weight = 110 +weight = 120 identifier = 'hugo-pipes' pageRef = '/hugo-pipes/' [[docs]] name = 'CLI' -weight = 120 +weight = 130 post = 'break' identifier = 'commands' pageRef = '/commands/' @@ -77,25 +83,25 @@ pageRef = '/commands/' [[docs]] name = 'Troubleshooting' -weight = 130 +weight = 140 identifier = 'troubleshooting' pageRef = '/troubleshooting/' [[docs]] name = 'Developer tools' -weight = 140 +weight = 150 identifier = 'developer-tools' pageRef = '/tools/' [[docs]] name = 'Hosting and deployment' -weight = 150 +weight = 160 identifier = 'hosting-and-deployment' pageRef = '/hosting-and-deployment/' [[docs]] name = 'Contribute' -weight = 160 +weight = 170 post = 'break' identifier = 'contribute' pageRef = '/contribute/' diff --git a/docs/content/en/about/features.md b/docs/content/en/about/features.md index 58d32485361..c04f6968691 100644 --- a/docs/content/en/about/features.md +++ b/docs/content/en/about/features.md @@ -55,7 +55,7 @@ toc: true : Use fenced code blocks and Markdown render hooks to include diagrams in your content. [Mathematics] -: Include mathematical equations and expressions in Markdown using LaTeX or TeX typesetting syntax. +: Include mathematical equations and expressions in Markdown using LaTeX markup. [Syntax highlighting] : Syntactically highlight code examples using Hugo's embedded syntax highlighter, enabled by default for fenced code blocks in Markdown. The syntax highlighter supports hundreds of code languages and dozens of styles. @@ -123,7 +123,7 @@ toc: true [Mathematics]: /content-management/mathematics/ [Menus]: /content-management/menus/ [Minification]: /getting-started/configuration/#configure-minify -[Modules]: https://gohugo.io/hugo-modules/ +[Modules]: /hugo-modules/ [Multilingual]: /content-management/multilingual/ [Multiplatform]: /installation/ [Output formats]: /templates/output-formats/ @@ -134,6 +134,6 @@ toc: true [Syntax highlighting]: /content-management/syntax-highlighting/ [Tailwind CSS processing]: /functions/css/tailwindcss/ [Taxonomies]: /content-management/taxonomies/ -[Templates]: templates/introduction/ +[Templates]: /templates/introduction/ [Themes]: https://themes.gohugo.io/ [URL management]: /content-management/urls/ diff --git a/docs/content/en/about/privacy.md b/docs/content/en/about/privacy.md index a3491f864c9..425af0bcfa5 100644 --- a/docs/content/en/about/privacy.md +++ b/docs/content/en/about/privacy.md @@ -39,11 +39,11 @@ respectDoNotTrack = false [privacy.instagram] disable = false simple = false -[privacy.twitter] +[privacy.vimeo] disable = false enableDNT = false simple = false -[privacy.vimeo] +[privacy.x] disable = false enableDNT = false simple = false @@ -64,10 +64,10 @@ disable = true disable = true [privacy.instagram] disable = true -[privacy.twitter] -disable = true [privacy.vimeo] disable = true +[privacy.x] +disable = true [privacy.youtube] disable = true {{< /code-toggle >}} @@ -92,19 +92,19 @@ simple disableInlineCSS = true {{< /code-toggle >}} -### Twitter +### X enableDNT -: Enabling this for the twitter/tweet shortcode, the tweet and its embedded page on your site are not used for purposes that include personalized suggestions and personalized ads. +: Enabling this for the x shortcode, the post and its embedded page on your site are not used for purposes that include personalized suggestions and personalized ads. simple -: If simple mode is enabled, a static and no-JS version of a tweet will be built. +: If simple mode is enabled, a static and no-JS version of a post will be built. -**Note:** If you use the _simple mode_ for Twitter, you may want to disable the inline styles provided by Hugo: +**Note:** If you use the _simple mode_ for X, you may want to disable the inline styles provided by Hugo: {{< code-toggle file=hugo >}} [services] -[services.twitter] +[services.x] disableInlineCSS = true {{< /code-toggle >}} diff --git a/docs/content/en/commands/hugo.md b/docs/content/en/commands/hugo.md index ef0bca9a5f6..42f882ad7e8 100644 --- a/docs/content/en/commands/hugo.md +++ b/docs/content/en/commands/hugo.md @@ -72,7 +72,6 @@ hugo [flags] * [hugo completion](/commands/hugo_completion/) - Generate the autocompletion script for the specified shell * [hugo config](/commands/hugo_config/) - Display site configuration * [hugo convert](/commands/hugo_convert/) - Convert front matter to another format -* [hugo deploy](/commands/hugo_deploy/) - Deploy your site to a cloud provider * [hugo env](/commands/hugo_env/) - Display version and environment info * [hugo gen](/commands/hugo_gen/) - Generate documentation and syntax highlighting styles * [hugo import](/commands/hugo_import/) - Import a site from another system diff --git a/docs/content/en/content-management/archetypes.md b/docs/content/en/content-management/archetypes.md index acf101fda15..30747258c02 100644 --- a/docs/content/en/content-management/archetypes.md +++ b/docs/content/en/content-management/archetypes.md @@ -15,7 +15,7 @@ aliases: [/content/archetypes/] ## Overview -A content file consists of [front matter] and markup. The markup is typically Markdown, but Hugo also supports other [content formats]. Front matter can be TOML, YAML, or JSON. +A content file consists of [front matter](g) and markup. The markup is typically Markdown, but Hugo also supports other [content formats](g). Front matter can be TOML, YAML, or JSON. The `hugo new content` command creates a new file in the `content` directory, using an archetype as a template. This is the default archetype: @@ -25,7 +25,7 @@ date = '{{ .Date }}' draft = true {{< /code-toggle >}} -When you create new content, Hugo evaluates the [template actions] within the archetype. For example: +When you create new content, Hugo evaluates the [template actions](g) within the archetype. For example: ```sh hugo new content posts/my-first-post.md @@ -39,7 +39,7 @@ date = '2023-08-24T11:49:46-07:00' draft = true {{< /code-toggle >}} -You can create an archetype for one or more [content types]. For example, use one archetype for posts, and use the default archetype for everything else: +You can create an archetype for one or more [content types](g). For example, use one archetype for posts, and use the default archetype for everything else: ```text archetypes/ @@ -59,18 +59,18 @@ hugo new content posts/my-first-post.md The archetype lookup order is: -1. archetypes/posts.md -1. archetypes/default.md -1. themes/my-theme/archetypes/posts.md -1. themes/my-theme/archetypes/default.md +1. `archetypes/posts.md` +1. `archetypes/default.md` +1. `themes/my-theme/archetypes/posts.md` +1. `themes/my-theme/archetypes/default.md` If none of these exists, Hugo uses a built-in default archetype. ## Functions and context -You can use any [template function] within an archetype. As shown above, the default archetype uses the [`replace`](/functions/strings/replace) function to replace hyphens with spaces when populating the title in front matter. +You can use any template [function](g) within an archetype. As shown above, the default archetype uses the [`replace`](/functions/strings/replace) function to replace hyphens with spaces when populating the title in front matter. -Archetypes receive the following [context]: +Archetypes receive the following [context](g): Date : (`string`) The current date and time, formatted in compliance with RFC3339. @@ -79,9 +79,7 @@ File : (`hugolib.fileInfo`) Returns file information for the current page. See [details](/methods/page/file). Type -: (`string`) The [content type] inferred from the top-level directory name, or as specified by the `--kind` flag passed to the `hugo new content` command. - -[content type]: /getting-started/glossary#content-type +: (`string`) The [content type](g) inferred from the top-level directory name, or as specified by the `--kind` flag passed to the `hugo new content` command. Site : (`page.Site`) The current site object. See [details](/methods/site/). @@ -130,11 +128,11 @@ One or more practical examples, each within a fenced code block. Additional information to clarify as needed. {{< /code >}} -Although you can include [template actions] within the content body, remember that Hugo evaluates these once---at the time of content creation. In most cases, place template actions in a [template] where Hugo evaluates the actions every time you [build](/getting-started/glossary/#build) the site. +Although you can include [template actions](g) within the content body, remember that Hugo evaluates these once---at the time of content creation. In most cases, place template actions in a [template](g) where Hugo evaluates the actions every time you [build](g) the site. ## Leaf bundles -You can also create archetypes for [leaf bundles](/getting-started/glossary/#leaf-bundle). +You can also create archetypes for [leaf bundles](g). For example, in a photography site you might have a section (content type) for galleries. Each gallery is leaf bundle with content and images. @@ -193,11 +191,3 @@ To create an article using the tutorials archetype: ```sh hugo new content --kind tutorials articles/something.md ``` - -[content formats]: /getting-started/glossary/#content-format -[content types]: /getting-started/glossary/#content-type -[context]: /getting-started/glossary/#context -[front matter]: /getting-started/glossary/#front-matter -[template actions]: /getting-started/glossary/#template-action -[template]: /getting-started/glossary/#template -[template function]: /getting-started/glossary/#function diff --git a/docs/content/en/content-management/build-options.md b/docs/content/en/content-management/build-options.md index a279fb651f8..e7846245530 100644 --- a/docs/content/en/content-management/build-options.md +++ b/docs/content/en/content-management/build-options.md @@ -21,7 +21,6 @@ publishResources = true render = 'always' {{< /code-toggle >}} - list : When to include the page within page collections. Specify one of: @@ -115,7 +114,7 @@ public/ In the example above, note that: 1. Hugo did not publish an HTML file for the page. -2. Despite setting `publishResources` to `false` in front matter, Hugo published the [page resources] because we invoked the [`RelPermalink`] method on each resource. This is the expected behavior. +1. Despite setting `publishResources` to `false` in front matter, Hugo published the [page resources] because we invoked the [`RelPermalink`] method on each resource. This is the expected behavior. ## Example -- headless section @@ -181,7 +180,7 @@ public/ In the example above, note that: 1. Hugo did not publish an HTML file for the page. -2. Despite setting `publishResources` to `false` in front matter, Hugo correctly published the [page resources] because we invoked the [`RelPermalink`] method on each resource. This is the expected behavior. +1. Despite setting `publishResources` to `false` in front matter, Hugo correctly published the [page resources] because we invoked the [`RelPermalink`] method on each resource. This is the expected behavior. ## Example -- list without publishing diff --git a/docs/content/en/content-management/content-adapters.md b/docs/content/en/content-management/content-adapters.md index a88bdba5f17..369e91a1240 100644 --- a/docs/content/en/content-management/content-adapters.md +++ b/docs/content/en/content-management/content-adapters.md @@ -17,7 +17,7 @@ toc: true A content adapter is a template that dynamically creates pages when building a site. For example, use a content adapter to create pages from a remote data source such as JSON, TOML, YAML, or XML. -Unlike templates that reside in the layouts directory, content adapters reside in the content directory, no more than one per directory per language. When a content adapter creates a page, the page's [logical path] will be relative to the content adapter. +Unlike templates that reside in the `layouts` directory, content adapters reside in the `content` directory, no more than one per directory per language. When a content adapter creates a page, the page's [logical path](g) will be relative to the content adapter. ```text content/ @@ -33,7 +33,7 @@ content/ └── _index.md ``` -Each content adapter is named _content.gotmpl and uses the same [syntax] as templates in the layouts directory. You can use any of the [template functions] within a content adapter, as well as the methods described below. +Each content adapter is named _content.gotmpl and uses the same [syntax] as templates in the `layouts` directory. You can use any of the [template functions] within a content adapter, as well as the methods described below. ## Methods @@ -137,9 +137,8 @@ Key|Description|Required `dates.expiryDate`|The page expiry date as a `time.Time` value.|  `dates.lastmod`|The page last modification date as a `time.Time` value.|  `dates.publishDate`|The page publication date as a `time.Time` value.|  -`kind`|The [page kind]. Default is `page`.|  `params`|A map of page parameters.|  -`path`|The page's [logical path] relative to the content adapter. Do not include a leading slash or file extension.|:heavy_check_mark: +`path`|The page's [logical path](g) relative to the content adapter. Do not include a leading slash or file extension.|:heavy_check_mark: `title`|The page title.|  {{% note %}} @@ -158,7 +157,7 @@ Key|Description|Required `content.value`|The content value as a string or resource.|:heavy_check_mark: `name`|The resource name.|  `params`|A map of resource parameters.|  -`path`|The resources's [logical path] relative to the content adapter. Do not include a leading slash.|:heavy_check_mark: +`path`|The resources's [logical path](g) relative to the content adapter. Do not include a leading slash.|:heavy_check_mark: `title`|The resource title.|  {{% note %}} @@ -193,14 +192,14 @@ Step 3 {{/* Get remote data. */}} {{ $data := dict }} {{ $url := "https://gohugo.io/shared/examples/data/books.json" }} -{{ with resources.GetRemote $url }} +{{ with try (resources.GetRemote $url) }} {{ with .Err }} {{ errorf "Unable to get remote resource %s: %s" $url . }} - {{ else }} + {{ else with .Value }} {{ $data = . | transform.Unmarshal }} + {{ else }} + {{ errorf "Unable to get remote resource %s" $url }} {{ end }} -{{ else }} - {{ errorf "Unable to get remote resource %s" $url }} {{ end }} {{/* Add pages and page resources. */}} @@ -223,10 +222,10 @@ Step 3 {{/* Add page resource. */}} {{ $item := . }} {{ with $url := $item.cover }} - {{ with resources.GetRemote $url }} + {{ with try (resources.GetRemote $url) }} {{ with .Err }} {{ errorf "Unable to get remote resource %s: %s" $url . }} - {{ else }} + {{ else with .Value }} {{ $content := dict "mediaType" .MediaType.Type "value" .Content }} {{ $params := dict "alt" $item.title }} {{ $resource := dict @@ -235,9 +234,9 @@ Step 3 "path" (printf "%s/cover.%s" $item.title .MediaType.SubType) }} {{ $.AddResource $resource }} + {{ else }} + {{ errorf "Unable to get remote resource %s" $url }} {{ end }} - {{ else }} - {{ errorf "Unable to get remote resource %s" $url }} {{ end }} {{ end }} @@ -281,7 +280,7 @@ Step 4 With multilingual sites you can: 1. Create one content adapter for all languages using the [`EnableAllLanguages`](#enablealllanguages) method as described above. -2. Create content adapters unique to each language. See the examples below. +1. Create content adapters unique to each language. See the examples below. ### Translations by file name @@ -352,8 +351,6 @@ To detect page collisions, use the `--printPathWarnings` flag when building your [content formats]: /content-management/formats/#classification [front matter field]: /content-management/front-matter/#fields -[logical path]: /getting-started/glossary/#logical-path [media type]: https://en.wikipedia.org/wiki/Media_type -[page kind]: /getting-started/glossary/#page-kind [syntax]: /templates/introduction/ [template functions]: /functions/ diff --git a/docs/content/en/content-management/cross-references.md b/docs/content/en/content-management/cross-references.md index 124a3bf06ac..56f4c39e184 100644 --- a/docs/content/en/content-management/cross-references.md +++ b/docs/content/en/content-management/cross-references.md @@ -49,7 +49,7 @@ The pages can be referenced as follows: {{}} ``` -index.md can be reference either by its path or by its containing folder without the ending `/`. \_index.md can be referenced only by its containing folder: +`index.md` can be reference either by its path or by its containing directory without the ending `/`. `_index.md` can be referenced only by its containing directory: ```text {{}} <-- References /about/_index.md diff --git a/docs/content/en/content-management/data-sources.md b/docs/content/en/content-management/data-sources.md index c009fb7f3a3..1237e4f4d5e 100644 --- a/docs/content/en/content-management/data-sources.md +++ b/docs/content/en/content-management/data-sources.md @@ -12,21 +12,15 @@ toc: true aliases: [/extras/datafiles/,/extras/datadrivencontent/,/doc/datafiles/,/templates/data-templates/] --- -Hugo can access and [unmarshal] local and remote data sources including CSV, JSON, TOML, YAML, and XML. Use this data to augment existing content or to create new content. +Hugo can access and [unmarshal](g) local and remote data sources including CSV, JSON, TOML, YAML, and XML. Use this data to augment existing content or to create new content. -[unmarshal]: /getting-started/glossary/#unmarshal - -A data source might be a file in the data directory, a [global resource], a [page resource], or a [remote resource]. - -[global resource]: /getting-started/glossary/#global-resource -[page resource]: /getting-started/glossary/#page-resource -[remote resource]: /getting-started/glossary/#remote-resource +A data source might be a file in the `data` directory, a [global resource](g), a [page resource](g), or a [remote resource](g). ## Data directory -The data directory in the root of your project may contain one or more data files, in either a flat or nested tree. Hugo merges the data files to create a single data structure, accessible with the `Data` method on a `Site` object. +The `data` directory in the root of your project may contain one or more data files, in either a flat or nested tree. Hugo merges the data files to create a single data structure, accessible with the `Data` method on a `Site` object. -Hugo also merges data directories from themes and modules into this single data structure, where the data directory in the root of your project takes precedence. +Hugo also merges data directories from themes and modules into this single data structure, where the `data` directory in the root of your project takes precedence. {{% note %}} Hugo reads the combined data structure into memory and keeps it there for the entire build. For data that is infrequently accessed, use global or page resources instead. @@ -42,7 +36,7 @@ project/ ``` {{% note %}} -Do not place CSV files in the data directory. Access CSV files as page, global, or remote resources. +Do not place CSV files in the `data` directory. Access CSV files as page, global, or remote resources. {{% /note %}} See the documentation for the [`Data`] method on a `Site` object for details and examples. diff --git a/docs/content/en/content-management/formats.md b/docs/content/en/content-management/formats.md index 1132c888c25..a02aa254574 100644 --- a/docs/content/en/content-management/formats.md +++ b/docs/content/en/content-management/formats.md @@ -29,7 +29,10 @@ content/ Regardless of content format, all content must have [front matter], preferably including both `title` and `date`. -Hugo selects the content renderer based on the `markup` identifier in front matter, falling back to the file extension. See the [classification](#classification) table below for a list of markup identifiers and recognized file extensions. +Hugo selects the content renderer based on the `markup` identifier in front matter, falling back to the file extension. See the [classification] table below for a list of markup identifiers and recognized file extensions. + +[classification]: #classification +[front matter]: /content-management/front-matter/ ## Formats @@ -37,7 +40,7 @@ Hugo selects the content renderer based on the `markup` identifier in front matt Create your content in [Markdown] preceded by front matter. -Markdown is Hugo's default content format. Hugo natively renders Markdown to HTML using [Goldmark]. Goldmark is fast and conforms to the [CommonMark] and [GitHub Flavored Markdown] specifications. You can [configure Goldmark] in your site configuration. +Markdown is Hugo's default content format. Hugo natively renders Markdown to HTML using [Goldmark]. Goldmark is fast and conforms to the [CommonMark] and [GitHub Flavored Markdown] specifications. You can configure Goldmark in your [site configuration][configure goldmark]. Hugo provides custom Markdown features including: @@ -48,24 +51,39 @@ Hugo provides custom Markdown features including: : Leverage the embedded Markdown extensions to create tables, definition lists, footnotes, task lists, inserted text, mark text, subscripts, superscripts, and more. [Mathematics] -: Include mathematical equations and expressions in Markdown using LaTeX or TeX typesetting syntax. +: Include mathematical equations and expressions in Markdown using LaTeX markup. [Render hooks] : Override the conversion of Markdown to HTML when rendering fenced code blocks, headings, images, and links. For example, render every standalone image as an HTML `figure` element. +[Attributes]: /content-management/markdown-attributes/ +[CommonMark]: https://spec.commonmark.org/current/ +[Extensions]: /getting-started/configuration-markup/#goldmark-extensions +[GitHub Flavored Markdown]: https://github.github.com/gfm/ +[Goldmark]: https://github.com/yuin/goldmark +[Markdown]: https://daringfireball.net/projects/markdown/ +[Mathematics]: /content-management/mathematics/ +[Render hooks]: /render-hooks/introduction/ +[configure goldmark]: /getting-started/configuration-markup/#goldmark + ### HTML Create your content in [HTML] preceded by front matter. The content is typically what you would place within an HTML document's `body` or `main` element. +[HTML]: https://developer.mozilla.org/en-US/docs/Learn_web_development/Getting_started/Your_first_website/Creating_the_content + ### Emacs Org Mode -Create your content in the [Emacs Org Mode] format preceded by front matter. You can use Org Mode keywords for front matter. See [details](/content-management/front-matter/#emacs-org-mode). +Create your content in the [Emacs Org Mode] format preceded by front matter. You can use Org Mode keywords for front matter. See [details]. + +[details]: /content-management/front-matter/#emacs-org-mode +[Emacs Org Mode]: https://orgmode.org/ ### AsciiDoc Create your content in the [AsciiDoc] format preceded by front matter. Hugo renders AsciiDoc content to HTML using the Asciidoctor executable. You must install Asciidoctor and its dependencies (Ruby) to use the AsciiDoc content format. -You can [configure the AsciiDoc renderer] in your site configuration. +You can configure the AsciiDoc renderer in your [site configuration][configure asciidoc]. In its default configuration, Hugo passes these CLI flags when calling the Asciidoctor executable: @@ -79,6 +97,10 @@ The CLI flags passed to the Asciidoctor executable depend on configuration. You hugo --logLevel info ``` +[AsciiDoc]: https://asciidoc.org/ +[configure the AsciiDoc renderer]: /getting-started/configuration-markup/#asciidoc +[configure asciidoc]: /getting-started/configuration-markup/#asciidoc + ### Pandoc Create your content in the [Pandoc] format preceded by front matter. Hugo renders Pandoc content to HTML using the Pandoc executable. You must install Pandoc to use the Pandoc content format. @@ -89,6 +111,8 @@ Hugo passes these CLI flags when calling the Pandoc executable: --mathjax ``` +[Pandoc]: https://pandoc.org/ + ### reStructuredText Create your content in the [reStructuredText] format preceded by front matter. Hugo renders reStructuredText content to HTML using [Docutils], specifically rst2html. You must install Docutils and its dependencies (Python) to use the reStructuredText content format. @@ -99,6 +123,9 @@ Hugo passes these CLI flags when calling the rst2html executable: --leave-comments --initial-header-level=2 ``` +[Docutils]: https://docutils.sourceforge.io/ +[reStructuredText]: https://docutils.sourceforge.io/rst.html + ## Classification Content format|Media type|Identifier|File extensions @@ -116,22 +143,3 @@ When converting content to HTML, Hugo uses: - External renderers for AsciiDoc, Pandoc, and reStructuredText Native renderers are faster than external renderers. - -[AsciiDoc]: https://asciidoc.org/ -[Asciidoctor]: https://asciidoctor.org/ -[Attributes]: /content-management/markdown-attributes/ -[CommonMark]: https://spec.commonmark.org/current/ -[Docutils]: https://docutils.sourceforge.io/ -[Emacs Org Mode]: https://orgmode.org/ -[Extensions]: /getting-started/configuration-markup/#goldmark-extensions -[GitHub Flavored Markdown]: https://github.github.com/gfm/ -[Goldmark]: https://github.com/yuin/goldmark -[HTML]: https://developer.mozilla.org/en-US/docs/Learn/Getting_started_with_the_web/HTML_basics -[Markdown]: https://daringfireball.net/projects/markdown/ -[Mathematics]: /content-management/mathematics/ -[Pandoc]: https://pandoc.org/ -[Render hooks]: https://gohugo.io/render-hooks/introduction/ -[configure Goldmark]: /getting-started/configuration-markup/#goldmark -[configure the AsciiDoc renderer]: /getting-started/configuration-markup/#asciidoc -[front matter]: /content-management/front-matter/ -[reStructuredText]: https://docutils.sourceforge.io/rst.html diff --git a/docs/content/en/content-management/front-matter.md b/docs/content/en/content-management/front-matter.md index 5cbf645a5b1..dba77f1d1e2 100644 --- a/docs/content/en/content-management/front-matter.md +++ b/docs/content/en/content-management/front-matter.md @@ -39,15 +39,7 @@ weight = 10 author = 'John Smith' {{< /code-toggle >}} -Front matter fields may be [boolean], [integer], [float], [string], [arrays], or [maps]. Note that the TOML format also supports unquoted date/time values. - -[scalar]: /getting-started/glossary/#scalar -[arrays]: /getting-started/glossary/#array -[maps]: /getting-started/glossary/#map -[boolean]: /getting-started/glossary/#boolean -[integer]: /getting-started/glossary/#integer -[float]: /getting-started/glossary/#float -[string]: /getting-started/glossary/#string +Front matter fields may be [boolean](g), [integer](g), [float](g), [string](g), [arrays](g), or [maps](g). Note that the TOML format also supports unquoted date/time values. ## Fields @@ -82,7 +74,6 @@ The field names below are reserved. For example, you cannot create a custom fiel (`string`) The date associated with the page, typically the creation date. Note that the TOML format also supports unquoted date/time values. See the [dates](#dates) section for examples. Access this value from a template using the [`Date`] method on a `Page` object. - [`date`]: /methods/page/date/ ###### description @@ -113,22 +104,19 @@ If `true`, the page will not be rendered unless you pass the `--buildDrafts` fla ###### isCJKLanguage -(`bool`) Set to `true` if the content language is in the [CJK] family. This value determines how Hugo calculates word count, and affects the values returned by the [`WordCount`], [`FuzzyWordCount`], [`ReadingTime`], and [`Summary`] methods on a `Page` object. +(`bool`) Set to `true` if the content language is in the [CJK](g) family. This value determines how Hugo calculates word count, and affects the values returned by the [`WordCount`], [`FuzzyWordCount`], [`ReadingTime`], and [`Summary`] methods on a `Page` object. [`fuzzywordcount`]: /methods/page/wordcount/ [`readingtime`]: /methods/page/readingtime/ [`summary`]: /methods/page/summary/ [`wordcount`]: /methods/page/wordcount/ -[cjk]: /getting-started/glossary/#cjk ###### keywords -(`string array`) An array of keywords, typically rendered within a `meta` element within the `head` element of the published HTML file, or used as a [taxonomy] to classify content. Access these values from a template using the [`Keywords`] method on a `Page` object. +(`string array`) An array of keywords, typically rendered within a `meta` element within the `head` element of the published HTML file, or used as a [taxonomy](g) to classify content. Access these values from a template using the [`Keywords`] method on a `Page` object. [`keywords`]: /methods/page/keywords/ -[taxonomy]: /getting-started/glossary/#taxonomy -{{% comment %}} -{{% /comment %}} ###### lastmod @@ -154,7 +141,7 @@ lang [`layout`]: /methods/page/layout/ [template lookup order]: /templates/lookup-order/ -[target a specific template]: templates/lookup-order/#target-a-template +[target a specific template]: /templates/lookup-order/#target-a-template ###### linkTitle @@ -184,13 +171,11 @@ Alias to [lastmod](#lastmod). [output formats]: /templates/output-formats/ -{{% comment %}} -{{% /comment %}} ###### params @@ -254,9 +239,8 @@ Alias to [publishDate](#publishdate). ###### type -(`string`) The [content type], overriding the value derived from the top level section in which the page resides. Access this value from a template using the [`Type`] method on a `Page` object. +(`string`) The [content type](g), overriding the value derived from the top level section in which the page resides. Access this value from a template using the [`Type`] method on a `Page` object. -[content type]: /getting-started/glossary/#content-type [`type`]: /methods/page/type/ ###### unpublishdate @@ -268,10 +252,8 @@ Alias to [expirydate](#expirydate). (`string`) Overrides the entire URL path. Applicable to regular pages and section pages. See the [URL management] page for details. ###### weight -(`int`) The page [weight], used to order the page within a [page collection]. Access this value from a template using the [`Weight`] method on a `Page` object. +(`int`) The page [weight](g), used to order the page within a [page collection](g). Access this value from a template using the [`Weight`] method on a `Page` object. -[page collection]: /getting-started/glossary/#page-collection -[weight]: /getting-started/glossary/#weight [`weight`]: /methods/page/weight/ ## Parameters @@ -302,7 +284,7 @@ Parameter|Data type|Used by these embedded templates `images`|`[]string`|[`opengraph.html`], [`schema.html`], [`twitter_cards.html`] `videos`|`[]string`|[`opengraph.html`] -The embedded templates will skip a parameter if not provided in front matter, but will throw an error if the data type is unexpected. +The embedded templates will skip a parameter if not provided in front matter, but will throw an error if the data type is unexpected. [`opengraph.html`]: {{% eturl opengraph %}} [`schema.html`]: {{% eturl schema %}} @@ -332,7 +314,7 @@ genres = ['mystery','romance'] author = 'John Smith' {{< /code-toggle >}} -You can add taxonomy terms to the front matter of any these [page kinds]: +You can add taxonomy terms to the front matter of any these [page kinds](g): - `home` - `page` @@ -340,8 +322,6 @@ You can add taxonomy terms to the front matter of any these [page kinds]: - `taxonomy` - `term` -[page kinds]: /getting-started/glossary/#page-kind - Access taxonomy terms from a template using the [`Params`] or [`GetTerms`] method on a `Page` object. For example: {{< code file=layouts/_default/single.html >}} @@ -360,9 +340,7 @@ Access taxonomy terms from a template using the [`Params`] or [`GetTerms`] metho ## Cascade -Any [node] can pass down to its descendants a set of front matter values. - -[node]: /getting-started/glossary/#node +Any [node](g) can pass down to its descendants a set of front matter values. ### Target specific pages @@ -459,5 +437,5 @@ When populating a date field, whether a [custom page parameter](#parameters) or To override the default time zone, set the [`timeZone`](https://gohugo.io/getting-started/configuration/#timezone) in your site configuration. The order of precedence for determining the time zone is: 1. The time zone offset in the date/time string -2. The time zone specified in your site configuration -3. The `Etc/UTC` time zone +1. The time zone specified in your site configuration +1. The `Etc/UTC` time zone diff --git a/docs/content/en/content-management/image-processing/index.md b/docs/content/en/content-management/image-processing/index.md index 841f1286367..69ee30dc8a6 100644 --- a/docs/content/en/content-management/image-processing/index.md +++ b/docs/content/en/content-management/image-processing/index.md @@ -88,15 +88,15 @@ Example 3: A more concise way to skip image rendering if the resource is not fou Example 4: Skips rendering if there's problem accessing a remote resource. ```go-html-template -{{ $u := "https://gohugo.io/img/hugo-logo.png" }} -{{ with resources.GetRemote $u }} +{{ $url := "https://gohugo.io/img/hugo-logo.png" }} +{{ with try (resources.GetRemote $url) }} {{ with .Err }} {{ errorf "%s" . }} - {{ else }} + {{ else with .Value }} + {{ else }} + {{ errorf "Unable to get remote resource %q" $url }} {{ end }} -{{ else }} - {{ errorf "Unable to get remote resource %q" $u }} {{ end }} ``` @@ -482,7 +482,7 @@ To control tag availability, change the `excludeFields` or `includeFields` setti ## Smart cropping of images -By default, Hugo uses the [Smartcrop] library when cropping images with the `Crop` or`Fill` methods. You can set the anchor point manually, but in most cases the `Smart` option will make a good choice. +By default, Hugo uses the [Smartcrop] library when cropping images with the `Crop` or `Fill` methods. You can set the anchor point manually, but in most cases the `Smart` option will make a good choice. Examples using the sunset image from above: @@ -500,15 +500,14 @@ If you change image processing methods or options, or if you rename or remove im hugo --gc ``` - [`anchor`]: /content-management/image-processing#anchor [mounted]: /hugo-modules/configuration#module-configuration-mounts [page bundle]: /content-management/page-bundles/ [`lang.FormatNumber`]: /functions/lang/formatnumber/ [filters]: /functions/images/filter/#image-filters -[github.com/disintegration/imaging]: -[Smartcrop]: -[Exif]: +[github.com/disintegration/imaging]: https://github.com/disintegration/imaging#image-resizing +[Smartcrop]: https://github.com/muesli/smartcrop#smartcrop +[Exif]: https://en.wikipedia.org/wiki/Exif [`Process`]: #process [`Colors`]: #colors [`Crop`]: #crop diff --git a/docs/content/en/content-management/markdown-attributes.md b/docs/content/en/content-management/markdown-attributes.md index 9c62c4fba3a..a465f244d0e 100644 --- a/docs/content/en/content-management/markdown-attributes.md +++ b/docs/content/en/content-management/markdown-attributes.md @@ -45,7 +45,6 @@ title = true # default is true block = true # default is false {{< /code-toggle >}} - ## Standalone images By default, when the [Goldmark] Markdown renderer encounters a standalone image element (no other elements or text on the same line), it wraps the image element within a paragraph element per the [CommonMark specification]. diff --git a/docs/content/en/content-management/mathematics.md b/docs/content/en/content-management/mathematics.md index 3212fe251c1..5eda9ffa32c 100644 --- a/docs/content/en/content-management/mathematics.md +++ b/docs/content/en/content-management/mathematics.md @@ -1,9 +1,9 @@ --- title: Mathematics in Markdown linkTitle: Mathematics -description: Include mathematical equations and expressions in your Markdown using LaTeX or TeX typesetting syntax. +description: Include mathematical equations and expressions in Markdown using LaTeX markup. categories: [content management] -keywords: [chemical,chemistry,latex,math,mathjax,tex,typesetting] +keywords: [katex,latex,math,mathjax,typesetting] menu: docs: parent: content-management @@ -15,37 +15,45 @@ math: true {{< new-in 0.122.0 >}} +## Overview + +Mathematical equations and expressions written in [LaTeX] are common in academic and scientific publications. Your browser typically renders this mathematical markup using an open-source JavaScript display engine such as [MathJax] or [KaTeX]. + +For example, with this LaTeX markup: + +```text \[ \begin{aligned} KL(\hat{y} || y) &= \sum_{c=1}^{M}\hat{y}_c \log{\frac{\hat{y}_c}{y_c}} \\ JS(\hat{y} || y) &= \frac{1}{2}(KL(y||\frac{y+\hat{y}}{2}) + KL(\hat{y}||\frac{y+\hat{y}}{2})) \end{aligned} \] +``` -## Overview - -Mathematical equations and expressions authored in [LaTeX] or [TeX] are common in academic and scientific publications. Your browser typically renders this mathematical markup using an open-source JavaScript display engine such as [MathJax] or [KaTeX]. - -For example, this is the mathematical markup for the equations displayed at the top of this page: +The MathJax display engine renders this: -```text \[ \begin{aligned} KL(\hat{y} || y) &= \sum_{c=1}^{M}\hat{y}_c \log{\frac{\hat{y}_c}{y_c}} \\ JS(\hat{y} || y) &= \frac{1}{2}(KL(y||\frac{y+\hat{y}}{2}) + KL(\hat{y}||\frac{y+\hat{y}}{2})) \end{aligned} \] -``` Equations and expressions can be displayed inline with other text, or as standalone blocks. Block presentation is also known as "display" mode. -Whether an equation or expression appears inline, or as a block, depends on the delimiters that surround the mathematical markup. Delimiters are defined in pairs, where each pair consists of an opening and closing delimiter. The opening and closing delimiters may be the same, or different. Common delimiter pairs are shown in [Step 1]. +Whether an equation or expression appears inline, or as a block, depends on the delimiters that surround the mathematical markup. Delimiters are defined in pairs, where each pair consists of an opening and closing delimiter. The opening and closing delimiters may be the same, or different. -The approach described below avoids reliance on platform-specific features like shortcodes or code block render hooks. Instead, it utilizes a standardized markup format for mathematical equations and expressions, compatible with the rendering engines used by GitHub, GitLab, [Microsoft VS Code], [Obsidian], [Typora], and others. +{{% note %}} +You can configure Hugo to render mathematical markup on the client-side using the MathJax or KaTeX display engine, or you can render the markup while building your site with the [`transform.ToMath`]function. + +The first approach is described below. + +[`transform.ToMath`]: /functions/transform/tomath/ +{{% /note %}} ## Setup -Follow these instructions to include mathematical equations and expressions in your Markdown using LaTeX or TeX typesetting syntax. +Follow these instructions to include mathematical equations and expressions in your Markdown using LaTeX markup. ###### Step 1 @@ -122,7 +130,7 @@ The example above loads the partial template if you have set the `math` paramete ###### Step 4 -Include mathematical equations and expressions in your Markdown using LaTeX or TeX typesetting syntax. +Include mathematical equations and expressions in Markdown using LaTeX markup. {{< code file=content/math-examples.md copy=true >}} This is an inline \(a^*=x-b^*\) equation. @@ -173,7 +181,7 @@ If you use the `$...$` delimiter pair for inline equations, and occasionally use ## Engines -MathJax and KaTeX are open-source JavaScript display engines. Both engines are fast, but at the time of this writing MathJax v3.2.2 is slightly faster than KaTeX v0.16.9. +MathJax and KaTeX are open-source JavaScript display engines. Both engines are fast, but at the time of this writing MathJax v3.2.2 is slightly faster than KaTeX v0.16.11. {{% note %}} If you use the `$...$` delimiter pair for inline equations, and occasionally use the `$` symbol outside of math contexts, you must use MathJax instead of KaTeX to avoid unintended formatting caused by [this KaTeX limitation](https://github.com/KaTeX/KaTeX/issues/437). @@ -184,9 +192,9 @@ See the [inline delimiters](#inline-delimiters) section for details. To use KaTeX instead of MathJax, replace the partial template from [Step 2] with this: {{< code file=layouts/partials/math.html copy=true >}} - - - + + +