diff --git a/.markdownlint.yaml b/.markdownlint.yaml index d9c2c5a67..ee0a28909 100644 --- a/.markdownlint.yaml +++ b/.markdownlint.yaml @@ -23,3 +23,4 @@ MD046: false MD049: false MD050: false MD053: false +MD055: false diff --git a/_vendor/github.com/gohugoio/gohugoioTheme/assets/css/_code.css b/_vendor/github.com/gohugoio/gohugoioTheme/assets/css/_code.css index c82e77ee7..9906a13d0 100644 --- a/_vendor/github.com/gohugoio/gohugoioTheme/assets/css/_code.css +++ b/_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/_vendor/github.com/gohugoio/gohugoioTheme/assets/output/css/app.css b/_vendor/github.com/gohugoio/gohugoioTheme/assets/output/css/app.css index b6343c7be..4fd374a1f 100644 --- a/_vendor/github.com/gohugoio/gohugoioTheme/assets/output/css/app.css +++ b/_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/_vendor/github.com/gohugoio/gohugoioTheme/layouts/partials/components/author-github-data-card.html b/_vendor/github.com/gohugoio/gohugoioTheme/layouts/partials/components/author-github-data-card.html index 4caa21f3e..d3edadaac 100644 --- a/_vendor/github.com/gohugoio/gohugoioTheme/layouts/partials/components/author-github-data-card.html +++ b/_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/_vendor/github.com/gohugoio/gohugoioTheme/layouts/partials/components/author-github-data.html b/_vendor/github.com/gohugoio/gohugoioTheme/layouts/partials/components/author-github-data.html index fbad3a0a7..c281e411f 100644 --- a/_vendor/github.com/gohugoio/gohugoioTheme/layouts/partials/components/author-github-data.html +++ b/_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/_vendor/github.com/gohugoio/gohugoioTheme/layouts/partials/utilities/get-remote-data.html b/_vendor/github.com/gohugoio/gohugoioTheme/layouts/partials/utilities/get-remote-data.html index 69ac41da4..78b2ba06e 100644 --- a/_vendor/github.com/gohugoio/gohugoioTheme/layouts/partials/utilities/get-remote-data.html +++ b/_vendor/github.com/gohugoio/gohugoioTheme/layouts/partials/utilities/get-remote-data.html @@ -11,13 +11,13 @@ Supports CSV, JSON, TOML, YAML, and XML. {{ $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/_vendor/github.com/gohugoio/gohugoioTheme/layouts/shortcodes/hl.html b/_vendor/github.com/gohugoio/gohugoioTheme/layouts/shortcodes/hl.html new file mode 100644 index 000000000..1a5b4e1ec --- /dev/null +++ b/_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/_vendor/github.com/gohugoio/gohugoioTheme/layouts/shortcodes/img.html b/_vendor/github.com/gohugoio/gohugoioTheme/layouts/shortcodes/img.html index dd8c60e18..7c2d805d2 100644 --- a/_vendor/github.com/gohugoio/gohugoioTheme/layouts/shortcodes/img.html +++ b/_vendor/github.com/gohugoio/gohugoioTheme/layouts/shortcodes/img.html @@ -120,8 +120,8 @@ Renders the given image using the given filter, if any. {{- $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 @@ Renders the given image using the given filter, if any. {{- $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 @@ Renders the given image using the given filter, if any. {{- 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 @@ Renders the given image using the given filter, if any. {{- $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/_vendor/modules.txt b/_vendor/modules.txt index a5092f11e..50178323d 100644 --- a/_vendor/modules.txt +++ b/_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/archetypes/glossary.md b/archetypes/glossary.md new file mode 100644 index 000000000..b38ced64a --- /dev/null +++ b/archetypes/glossary.md @@ -0,0 +1,19 @@ +--- +title: {{ replace .File.ContentBaseName "-" " " }} +--- + + diff --git a/archetypes/showcase/index.md b/archetypes/showcase/index.md index 04d454575..cdd036722 100644 --- a/archetypes/showcase/index.md +++ b/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/assets/images/examples/mask.png b/assets/images/examples/mask.png new file mode 100644 index 000000000..c3005a669 Binary files /dev/null and b/assets/images/examples/mask.png differ diff --git a/config/_default/menus/menus.en.toml b/config/_default/menus/menus.en.toml index 3f4e76879..aac432fab 100644 --- a/config/_default/menus/menus.en.toml +++ b/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/content/en/about/features.md b/content/en/about/features.md index 58d324853..c04f69686 100644 --- a/content/en/about/features.md +++ b/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/content/en/about/privacy.md b/content/en/about/privacy.md index a3491f864..425af0bcf 100644 --- a/content/en/about/privacy.md +++ b/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/content/en/commands/hugo.md b/content/en/commands/hugo.md index ef0bca9a5..42f882ad7 100644 --- a/content/en/commands/hugo.md +++ b/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/content/en/commands/hugo_completion.md b/content/en/commands/hugo_completion.md index 96f53742a..ac60dc148 100644 --- a/content/en/commands/hugo_completion.md +++ b/content/en/commands/hugo_completion.md @@ -29,6 +29,7 @@ See each sub-command's help for details on how to use the generated script. -e, --environment string build environment --ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern --logLevel string log level (debug|info|warn|error) + --noBuildLock don't create .hugo_build.lock file --quiet build in quiet mode -M, --renderToMemory render to memory (mostly useful when running the server) -s, --source string filesystem path to read files relative from diff --git a/content/en/commands/hugo_completion_bash.md b/content/en/commands/hugo_completion_bash.md index 60973415f..41fb47c0c 100644 --- a/content/en/commands/hugo_completion_bash.md +++ b/content/en/commands/hugo_completion_bash.md @@ -52,6 +52,7 @@ hugo completion bash -e, --environment string build environment --ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern --logLevel string log level (debug|info|warn|error) + --noBuildLock don't create .hugo_build.lock file --quiet build in quiet mode -M, --renderToMemory render to memory (mostly useful when running the server) -s, --source string filesystem path to read files relative from diff --git a/content/en/commands/hugo_completion_fish.md b/content/en/commands/hugo_completion_fish.md index 92bbd6c22..7f971c3ca 100644 --- a/content/en/commands/hugo_completion_fish.md +++ b/content/en/commands/hugo_completion_fish.md @@ -43,6 +43,7 @@ hugo completion fish [flags] -e, --environment string build environment --ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern --logLevel string log level (debug|info|warn|error) + --noBuildLock don't create .hugo_build.lock file --quiet build in quiet mode -M, --renderToMemory render to memory (mostly useful when running the server) -s, --source string filesystem path to read files relative from diff --git a/content/en/commands/hugo_completion_powershell.md b/content/en/commands/hugo_completion_powershell.md index f01442920..6ea17892b 100644 --- a/content/en/commands/hugo_completion_powershell.md +++ b/content/en/commands/hugo_completion_powershell.md @@ -40,6 +40,7 @@ hugo completion powershell [flags] -e, --environment string build environment --ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern --logLevel string log level (debug|info|warn|error) + --noBuildLock don't create .hugo_build.lock file --quiet build in quiet mode -M, --renderToMemory render to memory (mostly useful when running the server) -s, --source string filesystem path to read files relative from diff --git a/content/en/commands/hugo_completion_zsh.md b/content/en/commands/hugo_completion_zsh.md index 142c53103..b9e79f9f3 100644 --- a/content/en/commands/hugo_completion_zsh.md +++ b/content/en/commands/hugo_completion_zsh.md @@ -54,6 +54,7 @@ hugo completion zsh [flags] -e, --environment string build environment --ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern --logLevel string log level (debug|info|warn|error) + --noBuildLock don't create .hugo_build.lock file --quiet build in quiet mode -M, --renderToMemory render to memory (mostly useful when running the server) -s, --source string filesystem path to read files relative from diff --git a/content/en/commands/hugo_config.md b/content/en/commands/hugo_config.md index 8e8d745d2..2b4eaafa1 100644 --- a/content/en/commands/hugo_config.md +++ b/content/en/commands/hugo_config.md @@ -24,6 +24,7 @@ hugo config [command] [flags] --format string preferred file format (toml, yaml or json) (default "toml") -h, --help help for config --lang string the language to display config for. Defaults to the first language defined. + --printZero include config options with zero values (e.g. false, 0, "") in the output --renderSegments strings named segments to render (configured in the segments config) -t, --theme strings themes to use (located in /themes/THEMENAME/) ``` @@ -38,6 +39,7 @@ hugo config [command] [flags] -e, --environment string build environment --ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern --logLevel string log level (debug|info|warn|error) + --noBuildLock don't create .hugo_build.lock file --quiet build in quiet mode -M, --renderToMemory render to memory (mostly useful when running the server) -s, --source string filesystem path to read files relative from diff --git a/content/en/commands/hugo_config_mounts.md b/content/en/commands/hugo_config_mounts.md index 5af4819a2..06a781220 100644 --- a/content/en/commands/hugo_config_mounts.md +++ b/content/en/commands/hugo_config_mounts.md @@ -32,6 +32,7 @@ hugo config mounts [flags] [args] -e, --environment string build environment --ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern --logLevel string log level (debug|info|warn|error) + --noBuildLock don't create .hugo_build.lock file --quiet build in quiet mode -M, --renderToMemory render to memory (mostly useful when running the server) -s, --source string filesystem path to read files relative from diff --git a/content/en/commands/hugo_convert.md b/content/en/commands/hugo_convert.md index aeaa37766..a8d0b6a38 100644 --- a/content/en/commands/hugo_convert.md +++ b/content/en/commands/hugo_convert.md @@ -31,6 +31,7 @@ See convert's subcommands toJSON, toTOML and toYAML for more information. -e, --environment string build environment --ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern --logLevel string log level (debug|info|warn|error) + --noBuildLock don't create .hugo_build.lock file --quiet build in quiet mode -M, --renderToMemory render to memory (mostly useful when running the server) -s, --source string filesystem path to read files relative from diff --git a/content/en/commands/hugo_convert_toJSON.md b/content/en/commands/hugo_convert_toJSON.md index 40403193c..fe81146f9 100644 --- a/content/en/commands/hugo_convert_toJSON.md +++ b/content/en/commands/hugo_convert_toJSON.md @@ -32,6 +32,7 @@ hugo convert toJSON [flags] [args] -e, --environment string build environment --ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern --logLevel string log level (debug|info|warn|error) + --noBuildLock don't create .hugo_build.lock file -o, --output string filesystem path to write files to --quiet build in quiet mode -M, --renderToMemory render to memory (mostly useful when running the server) diff --git a/content/en/commands/hugo_convert_toTOML.md b/content/en/commands/hugo_convert_toTOML.md index 53ab82651..490b15ee6 100644 --- a/content/en/commands/hugo_convert_toTOML.md +++ b/content/en/commands/hugo_convert_toTOML.md @@ -32,6 +32,7 @@ hugo convert toTOML [flags] [args] -e, --environment string build environment --ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern --logLevel string log level (debug|info|warn|error) + --noBuildLock don't create .hugo_build.lock file -o, --output string filesystem path to write files to --quiet build in quiet mode -M, --renderToMemory render to memory (mostly useful when running the server) diff --git a/content/en/commands/hugo_convert_toYAML.md b/content/en/commands/hugo_convert_toYAML.md index efb63a4e2..9b00ce247 100644 --- a/content/en/commands/hugo_convert_toYAML.md +++ b/content/en/commands/hugo_convert_toYAML.md @@ -32,6 +32,7 @@ hugo convert toYAML [flags] [args] -e, --environment string build environment --ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern --logLevel string log level (debug|info|warn|error) + --noBuildLock don't create .hugo_build.lock file -o, --output string filesystem path to write files to --quiet build in quiet mode -M, --renderToMemory render to memory (mostly useful when running the server) diff --git a/content/en/commands/hugo_deploy.md b/content/en/commands/hugo_deploy.md index fce1e5422..696acf51f 100644 --- a/content/en/commands/hugo_deploy.md +++ b/content/en/commands/hugo_deploy.md @@ -42,6 +42,7 @@ hugo deploy [flags] [args] -e, --environment string build environment --ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern --logLevel string log level (debug|info|warn|error) + --noBuildLock don't create .hugo_build.lock file --quiet build in quiet mode -M, --renderToMemory render to memory (mostly useful when running the server) -s, --source string filesystem path to read files relative from diff --git a/content/en/commands/hugo_env.md b/content/en/commands/hugo_env.md index e216be416..7e21733a4 100644 --- a/content/en/commands/hugo_env.md +++ b/content/en/commands/hugo_env.md @@ -31,6 +31,7 @@ hugo env [flags] [args] -e, --environment string build environment --ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern --logLevel string log level (debug|info|warn|error) + --noBuildLock don't create .hugo_build.lock file --quiet build in quiet mode -M, --renderToMemory render to memory (mostly useful when running the server) -s, --source string filesystem path to read files relative from diff --git a/content/en/commands/hugo_gen.md b/content/en/commands/hugo_gen.md index 97cdbdb9d..d6333b52d 100644 --- a/content/en/commands/hugo_gen.md +++ b/content/en/commands/hugo_gen.md @@ -27,6 +27,7 @@ Generate documentation for your project using Hugo's documentation engine, inclu -e, --environment string build environment --ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern --logLevel string log level (debug|info|warn|error) + --noBuildLock don't create .hugo_build.lock file --quiet build in quiet mode -M, --renderToMemory render to memory (mostly useful when running the server) -s, --source string filesystem path to read files relative from diff --git a/content/en/commands/hugo_gen_chromastyles.md b/content/en/commands/hugo_gen_chromastyles.md index 49cde6bb9..2863e46b4 100644 --- a/content/en/commands/hugo_gen_chromastyles.md +++ b/content/en/commands/hugo_gen_chromastyles.md @@ -37,6 +37,7 @@ hugo gen chromastyles [flags] [args] -e, --environment string build environment --ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern --logLevel string log level (debug|info|warn|error) + --noBuildLock don't create .hugo_build.lock file --quiet build in quiet mode -M, --renderToMemory render to memory (mostly useful when running the server) -s, --source string filesystem path to read files relative from diff --git a/content/en/commands/hugo_gen_doc.md b/content/en/commands/hugo_gen_doc.md index 180dc4f95..2c2c3a118 100644 --- a/content/en/commands/hugo_gen_doc.md +++ b/content/en/commands/hugo_gen_doc.md @@ -37,6 +37,7 @@ hugo gen doc [flags] [args] -e, --environment string build environment --ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern --logLevel string log level (debug|info|warn|error) + --noBuildLock don't create .hugo_build.lock file --quiet build in quiet mode -M, --renderToMemory render to memory (mostly useful when running the server) -s, --source string filesystem path to read files relative from diff --git a/content/en/commands/hugo_gen_man.md b/content/en/commands/hugo_gen_man.md index f33342c54..14fe859e3 100644 --- a/content/en/commands/hugo_gen_man.md +++ b/content/en/commands/hugo_gen_man.md @@ -34,6 +34,7 @@ hugo gen man [flags] [args] -e, --environment string build environment --ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern --logLevel string log level (debug|info|warn|error) + --noBuildLock don't create .hugo_build.lock file --quiet build in quiet mode -M, --renderToMemory render to memory (mostly useful when running the server) -s, --source string filesystem path to read files relative from diff --git a/content/en/commands/hugo_import.md b/content/en/commands/hugo_import.md index b20b58599..2b8e62951 100644 --- a/content/en/commands/hugo_import.md +++ b/content/en/commands/hugo_import.md @@ -29,6 +29,7 @@ Import requires a subcommand, e.g. `hugo import jekyll jekyll_root_path target_p -e, --environment string build environment --ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern --logLevel string log level (debug|info|warn|error) + --noBuildLock don't create .hugo_build.lock file --quiet build in quiet mode -M, --renderToMemory render to memory (mostly useful when running the server) -s, --source string filesystem path to read files relative from diff --git a/content/en/commands/hugo_import_jekyll.md b/content/en/commands/hugo_import_jekyll.md index 14c57cc44..8746c156e 100644 --- a/content/en/commands/hugo_import_jekyll.md +++ b/content/en/commands/hugo_import_jekyll.md @@ -34,6 +34,7 @@ hugo import jekyll [flags] [args] -e, --environment string build environment --ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern --logLevel string log level (debug|info|warn|error) + --noBuildLock don't create .hugo_build.lock file --quiet build in quiet mode -M, --renderToMemory render to memory (mostly useful when running the server) -s, --source string filesystem path to read files relative from diff --git a/content/en/commands/hugo_list.md b/content/en/commands/hugo_list.md index 726fe51a9..741ca1d68 100644 --- a/content/en/commands/hugo_list.md +++ b/content/en/commands/hugo_list.md @@ -29,6 +29,7 @@ List requires a subcommand, e.g. hugo list drafts -e, --environment string build environment --ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern --logLevel string log level (debug|info|warn|error) + --noBuildLock don't create .hugo_build.lock file --quiet build in quiet mode -M, --renderToMemory render to memory (mostly useful when running the server) -s, --source string filesystem path to read files relative from diff --git a/content/en/commands/hugo_list_all.md b/content/en/commands/hugo_list_all.md index 59846733d..e0f1efdcb 100644 --- a/content/en/commands/hugo_list_all.md +++ b/content/en/commands/hugo_list_all.md @@ -31,6 +31,7 @@ hugo list all [flags] [args] -e, --environment string build environment --ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern --logLevel string log level (debug|info|warn|error) + --noBuildLock don't create .hugo_build.lock file --quiet build in quiet mode -M, --renderToMemory render to memory (mostly useful when running the server) -s, --source string filesystem path to read files relative from diff --git a/content/en/commands/hugo_list_drafts.md b/content/en/commands/hugo_list_drafts.md index 5f3bcd617..25ddc78d3 100644 --- a/content/en/commands/hugo_list_drafts.md +++ b/content/en/commands/hugo_list_drafts.md @@ -31,6 +31,7 @@ hugo list drafts [flags] [args] -e, --environment string build environment --ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern --logLevel string log level (debug|info|warn|error) + --noBuildLock don't create .hugo_build.lock file --quiet build in quiet mode -M, --renderToMemory render to memory (mostly useful when running the server) -s, --source string filesystem path to read files relative from diff --git a/content/en/commands/hugo_list_expired.md b/content/en/commands/hugo_list_expired.md index c010d1159..1936b9920 100644 --- a/content/en/commands/hugo_list_expired.md +++ b/content/en/commands/hugo_list_expired.md @@ -31,6 +31,7 @@ hugo list expired [flags] [args] -e, --environment string build environment --ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern --logLevel string log level (debug|info|warn|error) + --noBuildLock don't create .hugo_build.lock file --quiet build in quiet mode -M, --renderToMemory render to memory (mostly useful when running the server) -s, --source string filesystem path to read files relative from diff --git a/content/en/commands/hugo_list_future.md b/content/en/commands/hugo_list_future.md index 888784dcd..3152639c2 100644 --- a/content/en/commands/hugo_list_future.md +++ b/content/en/commands/hugo_list_future.md @@ -31,6 +31,7 @@ hugo list future [flags] [args] -e, --environment string build environment --ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern --logLevel string log level (debug|info|warn|error) + --noBuildLock don't create .hugo_build.lock file --quiet build in quiet mode -M, --renderToMemory render to memory (mostly useful when running the server) -s, --source string filesystem path to read files relative from diff --git a/content/en/commands/hugo_list_published.md b/content/en/commands/hugo_list_published.md index b8ec0e7b2..a7a08c7b4 100644 --- a/content/en/commands/hugo_list_published.md +++ b/content/en/commands/hugo_list_published.md @@ -31,6 +31,7 @@ hugo list published [flags] [args] -e, --environment string build environment --ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern --logLevel string log level (debug|info|warn|error) + --noBuildLock don't create .hugo_build.lock file --quiet build in quiet mode -M, --renderToMemory render to memory (mostly useful when running the server) -s, --source string filesystem path to read files relative from diff --git a/content/en/commands/hugo_mod.md b/content/en/commands/hugo_mod.md index 2c07b89cf..c037be6da 100644 --- a/content/en/commands/hugo_mod.md +++ b/content/en/commands/hugo_mod.md @@ -38,6 +38,7 @@ See https://gohugo.io/hugo-modules/ for more information. -e, --environment string build environment --ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern --logLevel string log level (debug|info|warn|error) + --noBuildLock don't create .hugo_build.lock file --quiet build in quiet mode -M, --renderToMemory render to memory (mostly useful when running the server) -s, --source string filesystem path to read files relative from diff --git a/content/en/commands/hugo_mod_clean.md b/content/en/commands/hugo_mod_clean.md index 7df51059f..6f49284b7 100644 --- a/content/en/commands/hugo_mod_clean.md +++ b/content/en/commands/hugo_mod_clean.md @@ -38,6 +38,7 @@ hugo mod clean [flags] [args] -e, --environment string build environment --ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern --logLevel string log level (debug|info|warn|error) + --noBuildLock don't create .hugo_build.lock file --quiet build in quiet mode -M, --renderToMemory render to memory (mostly useful when running the server) -s, --source string filesystem path to read files relative from diff --git a/content/en/commands/hugo_mod_get.md b/content/en/commands/hugo_mod_get.md index f4ca6069a..08e1e5c84 100644 --- a/content/en/commands/hugo_mod_get.md +++ b/content/en/commands/hugo_mod_get.md @@ -62,6 +62,7 @@ hugo mod get [flags] [args] -e, --environment string build environment --ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern --logLevel string log level (debug|info|warn|error) + --noBuildLock don't create .hugo_build.lock file --quiet build in quiet mode -M, --renderToMemory render to memory (mostly useful when running the server) -s, --source string filesystem path to read files relative from diff --git a/content/en/commands/hugo_mod_graph.md b/content/en/commands/hugo_mod_graph.md index 5b5a14d5d..b7bfc6bfe 100644 --- a/content/en/commands/hugo_mod_graph.md +++ b/content/en/commands/hugo_mod_graph.md @@ -39,6 +39,7 @@ hugo mod graph [flags] [args] -e, --environment string build environment --ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern --logLevel string log level (debug|info|warn|error) + --noBuildLock don't create .hugo_build.lock file --quiet build in quiet mode -M, --renderToMemory render to memory (mostly useful when running the server) -s, --source string filesystem path to read files relative from diff --git a/content/en/commands/hugo_mod_init.md b/content/en/commands/hugo_mod_init.md index bf9651b59..0d9f1fd4e 100644 --- a/content/en/commands/hugo_mod_init.md +++ b/content/en/commands/hugo_mod_init.md @@ -43,6 +43,7 @@ hugo mod init [flags] [args] -e, --environment string build environment --ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern --logLevel string log level (debug|info|warn|error) + --noBuildLock don't create .hugo_build.lock file --quiet build in quiet mode -M, --renderToMemory render to memory (mostly useful when running the server) -s, --source string filesystem path to read files relative from diff --git a/content/en/commands/hugo_mod_npm.md b/content/en/commands/hugo_mod_npm.md index a013fb91f..4c6b0c6a7 100644 --- a/content/en/commands/hugo_mod_npm.md +++ b/content/en/commands/hugo_mod_npm.md @@ -31,6 +31,7 @@ hugo mod npm [command] [flags] -e, --environment string build environment --ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern --logLevel string log level (debug|info|warn|error) + --noBuildLock don't create .hugo_build.lock file --quiet build in quiet mode -M, --renderToMemory render to memory (mostly useful when running the server) -s, --source string filesystem path to read files relative from diff --git a/content/en/commands/hugo_mod_npm_pack.md b/content/en/commands/hugo_mod_npm_pack.md index 8f8738280..ffbf0703e 100644 --- a/content/en/commands/hugo_mod_npm_pack.md +++ b/content/en/commands/hugo_mod_npm_pack.md @@ -46,6 +46,7 @@ hugo mod npm pack [flags] [args] -e, --environment string build environment --ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern --logLevel string log level (debug|info|warn|error) + --noBuildLock don't create .hugo_build.lock file --quiet build in quiet mode -M, --renderToMemory render to memory (mostly useful when running the server) -s, --source string filesystem path to read files relative from diff --git a/content/en/commands/hugo_mod_tidy.md b/content/en/commands/hugo_mod_tidy.md index c15ddb3c8..cff192130 100644 --- a/content/en/commands/hugo_mod_tidy.md +++ b/content/en/commands/hugo_mod_tidy.md @@ -32,6 +32,7 @@ hugo mod tidy [flags] [args] -e, --environment string build environment --ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern --logLevel string log level (debug|info|warn|error) + --noBuildLock don't create .hugo_build.lock file --quiet build in quiet mode -M, --renderToMemory render to memory (mostly useful when running the server) -s, --source string filesystem path to read files relative from diff --git a/content/en/commands/hugo_mod_vendor.md b/content/en/commands/hugo_mod_vendor.md index ae112a36a..2b812e4c4 100644 --- a/content/en/commands/hugo_mod_vendor.md +++ b/content/en/commands/hugo_mod_vendor.md @@ -38,6 +38,7 @@ hugo mod vendor [flags] [args] -e, --environment string build environment --ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern --logLevel string log level (debug|info|warn|error) + --noBuildLock don't create .hugo_build.lock file --quiet build in quiet mode -M, --renderToMemory render to memory (mostly useful when running the server) -s, --source string filesystem path to read files relative from diff --git a/content/en/commands/hugo_mod_verify.md b/content/en/commands/hugo_mod_verify.md index 63dd28ce8..051477c90 100644 --- a/content/en/commands/hugo_mod_verify.md +++ b/content/en/commands/hugo_mod_verify.md @@ -37,6 +37,7 @@ hugo mod verify [flags] [args] -e, --environment string build environment --ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern --logLevel string log level (debug|info|warn|error) + --noBuildLock don't create .hugo_build.lock file --quiet build in quiet mode -M, --renderToMemory render to memory (mostly useful when running the server) -s, --source string filesystem path to read files relative from diff --git a/content/en/commands/hugo_new.md b/content/en/commands/hugo_new.md index 4d3021b44..2788ef168 100644 --- a/content/en/commands/hugo_new.md +++ b/content/en/commands/hugo_new.md @@ -34,6 +34,7 @@ Ensure you run this within the root directory of your site. -e, --environment string build environment --ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern --logLevel string log level (debug|info|warn|error) + --noBuildLock don't create .hugo_build.lock file --quiet build in quiet mode -M, --renderToMemory render to memory (mostly useful when running the server) -s, --source string filesystem path to read files relative from diff --git a/content/en/commands/hugo_new_content.md b/content/en/commands/hugo_new_content.md index a8d2100f9..9624e9a61 100644 --- a/content/en/commands/hugo_new_content.md +++ b/content/en/commands/hugo_new_content.md @@ -46,6 +46,7 @@ hugo new content [path] [flags] -e, --environment string build environment --ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern --logLevel string log level (debug|info|warn|error) + --noBuildLock don't create .hugo_build.lock file --quiet build in quiet mode -M, --renderToMemory render to memory (mostly useful when running the server) -s, --source string filesystem path to read files relative from diff --git a/content/en/commands/hugo_new_site.md b/content/en/commands/hugo_new_site.md index cc0e63013..0f0096ae4 100644 --- a/content/en/commands/hugo_new_site.md +++ b/content/en/commands/hugo_new_site.md @@ -35,6 +35,7 @@ hugo new site [path] [flags] -e, --environment string build environment --ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern --logLevel string log level (debug|info|warn|error) + --noBuildLock don't create .hugo_build.lock file --quiet build in quiet mode -M, --renderToMemory render to memory (mostly useful when running the server) -s, --source string filesystem path to read files relative from diff --git a/content/en/commands/hugo_new_theme.md b/content/en/commands/hugo_new_theme.md index a79978c4a..b1c937bae 100644 --- a/content/en/commands/hugo_new_theme.md +++ b/content/en/commands/hugo_new_theme.md @@ -34,6 +34,7 @@ hugo new theme [name] [flags] -e, --environment string build environment --ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern --logLevel string log level (debug|info|warn|error) + --noBuildLock don't create .hugo_build.lock file --quiet build in quiet mode -M, --renderToMemory render to memory (mostly useful when running the server) -s, --source string filesystem path to read files relative from diff --git a/content/en/commands/hugo_server.md b/content/en/commands/hugo_server.md index a1c77d36f..4ab161f8f 100644 --- a/content/en/commands/hugo_server.md +++ b/content/en/commands/hugo_server.md @@ -50,7 +50,6 @@ hugo server [command] [flags] --liveReloadPort int port for live reloading (i.e. 443 in HTTPS proxy situations) (default -1) --minify minify any supported output format (HTML, XML etc.) -N, --navigateToChanged navigate to changed content file on live browser reload - --noBuildLock don't create .hugo_build.lock file --noChmod don't sync permission mode of files --noHTTPCache prevent HTTP caching --noTimes don't sync modification time of files @@ -85,6 +84,7 @@ hugo server [command] [flags] -e, --environment string build environment --ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern --logLevel string log level (debug|info|warn|error) + --noBuildLock don't create .hugo_build.lock file --quiet build in quiet mode -M, --renderToMemory render to memory (mostly useful when running the server) -s, --source string filesystem path to read files relative from diff --git a/content/en/commands/hugo_server_trust.md b/content/en/commands/hugo_server_trust.md index 1a904e845..9d24e78e3 100644 --- a/content/en/commands/hugo_server_trust.md +++ b/content/en/commands/hugo_server_trust.md @@ -28,6 +28,7 @@ hugo server trust [flags] [args] -e, --environment string build environment --ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern --logLevel string log level (debug|info|warn|error) + --noBuildLock don't create .hugo_build.lock file --quiet build in quiet mode -M, --renderToMemory render to memory (mostly useful when running the server) -s, --source string filesystem path to read files relative from diff --git a/content/en/commands/hugo_version.md b/content/en/commands/hugo_version.md index b1a6b971e..14cc92a00 100644 --- a/content/en/commands/hugo_version.md +++ b/content/en/commands/hugo_version.md @@ -31,6 +31,7 @@ hugo version [flags] [args] -e, --environment string build environment --ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern --logLevel string log level (debug|info|warn|error) + --noBuildLock don't create .hugo_build.lock file --quiet build in quiet mode -M, --renderToMemory render to memory (mostly useful when running the server) -s, --source string filesystem path to read files relative from diff --git a/content/en/content-management/archetypes.md b/content/en/content-management/archetypes.md index acf101fda..30747258c 100644 --- a/content/en/content-management/archetypes.md +++ b/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/content/en/content-management/build-options.md b/content/en/content-management/build-options.md index a279fb651..e78462455 100644 --- a/content/en/content-management/build-options.md +++ b/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/content/en/content-management/content-adapters.md b/content/en/content-management/content-adapters.md index a88bdba5f..369e91a12 100644 --- a/content/en/content-management/content-adapters.md +++ b/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/content/en/content-management/cross-references.md b/content/en/content-management/cross-references.md index 124a3bf06..56f4c39e1 100644 --- a/content/en/content-management/cross-references.md +++ b/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/content/en/content-management/data-sources.md b/content/en/content-management/data-sources.md index c009fb7f3..1237e4f4d 100644 --- a/content/en/content-management/data-sources.md +++ b/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/content/en/content-management/formats.md b/content/en/content-management/formats.md index 1132c888c..a02aa2545 100644 --- a/content/en/content-management/formats.md +++ b/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/content/en/content-management/front-matter.md b/content/en/content-management/front-matter.md index 5cbf645a5..dba77f1d1 100644 --- a/content/en/content-management/front-matter.md +++ b/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/content/en/content-management/image-processing/index.md b/content/en/content-management/image-processing/index.md index 841f12863..69ee30dc8 100644 --- a/content/en/content-management/image-processing/index.md +++ b/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/content/en/content-management/markdown-attributes.md b/content/en/content-management/markdown-attributes.md index 9c62c4fba..a465f244d 100644 --- a/content/en/content-management/markdown-attributes.md +++ b/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/content/en/content-management/mathematics.md b/content/en/content-management/mathematics.md index 3212fe251..5eda9ffa3 100644 --- a/content/en/content-management/mathematics.md +++ b/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,18 +15,11 @@ math: true {{< new-in 0.122.0 >}} -\[ -\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]. +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, this is the mathematical markup for the equations displayed at the top of this page: +For example, with this LaTeX markup: ```text \[ @@ -37,15 +30,30 @@ JS(\hat{y} || y) &= \frac{1}{2}(KL(y||\frac{y+\hat{y}}{2}) + KL(\hat{y}||\frac{y \] ``` +The MathJax display engine renders this: + +\[ +\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 >}} - - - + + +