From 0c2fa2460f485e0eca564dcccf36d34538374922 Mon Sep 17 00:00:00 2001 From: =?utf8?q?Bj=C3=B8rn=20Erik=20Pedersen?= Date: Tue, 24 Feb 2026 21:38:42 +0100 Subject: [PATCH] Squashed 'docs/' changes from 42914c50e..80dd7b067 80dd7b067 theme: Fix border class in render-codeblock template 0d3fde6c9 content: Fix typo 23a4adb29 content: More site => project changes 9243e9f6b content: Rename site configuration to project configuration (phase 2) 330aa2249 content: Miscellaneous edits 25ce893be content: Clarify sort order with PAGE.Rotate b398506dc content: Various dimension improvements c54573d13 content: Use singular form in method section descriptions d9a95fe54 content: Improve description of PAGE.Rotate 154f30600 content: Fix link c71bd2776 content: Address Markdown linting error 72c88e68e content: Improve pages related to content dimensions b85afa645 content: Fix formatting 7aaca8947 content: More site-to-project changes 8e1579030 content: Update quick start guide f7ba1fde2 content: Make new-in into a note 8b9d51584 theme: Address TailwindCSS warnings 3a4c2a25c theme: Address Hugo v0.156.0 deprecations 4f1a2bd7b content: Improve glossary entries 21bcd23a6 content: Update glossary entry c72ef1116 content: Update quick start guide c0737ffab content: Add typography plugin to TailwindCSS example 80bcb868e content: Remove Site.AllPages from examples 2b9ba5831 content: Replace Page.Sites and Site.Sites with hugo.Sites 2cdcc2556 content: Remove outdated badges 5a4beb530 content: Replace Site.Data with hugo.Data de4651b5d content: Update glossary entry 2302825a7 content: Add hugo.Data and note other deprecations bac5da4b5 content: Add hugo.Sites and update the other Sites methods 0f7d99153 content: Add Site.IsDefault f888f33bb content: Update glossary entries 65311c2de content: Include the "build" subcommand where appropriate 4991320d2 content: Standard shell language code in info strings b16d9f162 theme: Style todo lists f121450c6 content: Update version references 5a81dd8c2 content: Update CLI documentation f3ae0ce86 content: Rename site configuration to project configuration (phase 1) 9c8327119 content: Miscellaneous edits fbff91e22 Update HUGO_VERSION to 0.156.0 2ec625ae8 content: Restore snap installation instructions fc8c246b8 content: Clarify module initialization git-subtree-dir: docs git-subtree-split: 80dd7b067c31c28b13c51f3ac4636890509a4bb7 --- assets/css/components/all.css | 1 + assets/css/components/todo-lists.css | 15 ++ assets/css/styles.css | 4 +- .../functions/hugo/sites-collection.md | 9 + .../en/_common/menu-entries/pre-and-post.md | 2 +- .../en/_common/methods/page/next-and-prev.md | 4 +- .../page/nextinsection-and-previnsection.md | 4 +- .../methods/resource/processing-spec.md | 14 +- .../methods/taxonomy/get-a-taxonomy-object.md | 2 +- .../_common/ref-and-relref-error-handling.md | 2 +- content/en/about/features.md | 4 +- content/en/commands/hugo.md | 13 +- content/en/commands/hugo_build.md | 7 +- content/en/commands/hugo_completion.md | 3 +- content/en/commands/hugo_completion_bash.md | 1 - content/en/commands/hugo_completion_fish.md | 1 - .../en/commands/hugo_completion_powershell.md | 1 - content/en/commands/hugo_completion_zsh.md | 1 - content/en/commands/hugo_config.md | 7 +- content/en/commands/hugo_config_mounts.md | 3 +- content/en/commands/hugo_convert.md | 3 +- content/en/commands/hugo_convert_toJSON.md | 1 - content/en/commands/hugo_convert_toTOML.md | 1 - content/en/commands/hugo_convert_toYAML.md | 1 - content/en/commands/hugo_deploy.md | 7 +- content/en/commands/hugo_env.md | 3 +- content/en/commands/hugo_gen.md | 3 +- content/en/commands/hugo_gen_chromastyles.md | 1 - content/en/commands/hugo_gen_doc.md | 1 - content/en/commands/hugo_gen_man.md | 1 - content/en/commands/hugo_import.md | 7 +- content/en/commands/hugo_import_jekyll.md | 5 +- content/en/commands/hugo_list.md | 3 +- content/en/commands/hugo_list_all.md | 1 - content/en/commands/hugo_list_drafts.md | 1 - content/en/commands/hugo_list_expired.md | 1 - content/en/commands/hugo_list_future.md | 1 - content/en/commands/hugo_list_published.md | 1 - content/en/commands/hugo_mod.md | 5 +- content/en/commands/hugo_mod_clean.md | 1 - content/en/commands/hugo_mod_get.md | 3 +- content/en/commands/hugo_mod_graph.md | 1 - content/en/commands/hugo_mod_init.md | 1 - content/en/commands/hugo_mod_npm.md | 1 - content/en/commands/hugo_mod_npm_pack.md | 1 - content/en/commands/hugo_mod_tidy.md | 1 - content/en/commands/hugo_mod_vendor.md | 1 - content/en/commands/hugo_mod_verify.md | 1 - content/en/commands/hugo_new.md | 9 +- content/en/commands/hugo_new_content.md | 5 +- .../{hugo_new_site.md => hugo_new_project.md} | 17 +- content/en/commands/hugo_new_theme.md | 1 - content/en/commands/hugo_server.md | 11 +- content/en/commands/hugo_server_trust.md | 1 - content/en/commands/hugo_version.md | 3 +- content/en/configuration/all.md | 13 +- content/en/configuration/build.md | 2 +- content/en/configuration/caches.md | 4 +- content/en/configuration/cascade.md | 4 +- content/en/configuration/front-matter.md | 6 +- content/en/configuration/introduction.md | 24 +-- content/en/configuration/languages.md | 8 +- content/en/configuration/markup.md | 8 +- content/en/configuration/menus.md | 8 +- content/en/configuration/output-formats.md | 8 +- content/en/configuration/outputs.md | 2 +- content/en/configuration/page.md | 2 +- content/en/configuration/permalinks.md | 2 +- content/en/configuration/related-content.md | 4 +- content/en/configuration/roles.md | 17 +- content/en/configuration/security.md | 2 +- content/en/configuration/segments.md | 8 +- content/en/configuration/taxonomies.md | 2 +- content/en/configuration/versions.md | 21 +- content/en/content-management/comments.md | 2 +- .../en/content-management/content-adapters.md | 12 +- content/en/content-management/formats.md | 8 +- content/en/content-management/front-matter.md | 12 +- .../image-processing/index.md | 7 +- .../content-management/markdown-attributes.md | 4 +- content/en/content-management/mathematics.md | 14 +- content/en/content-management/menus.md | 6 +- content/en/content-management/multilingual.md | 14 +- .../content-management/organization/index.md | 2 +- .../en/content-management/page-resources.md | 4 +- content/en/content-management/shortcodes.md | 2 +- content/en/content-management/summaries.md | 2 +- .../content-management/syntax-highlighting.md | 4 +- content/en/content-management/urls.md | 10 +- content/en/contribute/development.md | 2 +- content/en/contribute/documentation.md | 16 +- content/en/functions/collections/IsSet.md | 2 +- content/en/functions/collections/Querify.md | 2 +- content/en/functions/collections/Sort.md | 4 +- content/en/functions/collections/Where.md | 6 +- content/en/functions/css/Sass.md | 2 +- content/en/functions/css/TailwindCSS.md | 5 +- content/en/functions/debug/Dump.md | 2 +- content/en/functions/debug/Timer.md | 2 +- content/en/functions/fmt/Erroridf.md | 4 +- content/en/functions/fmt/Warnidf.md | 4 +- content/en/functions/hugo/Data.md | 105 ++++++++++ content/en/functions/hugo/Environment.md | 4 +- content/en/functions/hugo/Generator.md | 2 +- content/en/functions/hugo/IsMultihost.md | 2 +- content/en/functions/hugo/IsMultilingual.md | 2 +- content/en/functions/hugo/Sites.md | 82 ++++++++ content/en/functions/hugo/Version.md | 2 +- content/en/functions/images/Mask.md | 4 +- content/en/functions/js/Babel.md | 2 +- content/en/functions/js/Build.md | 4 +- content/en/functions/lang/Translate.md | 6 +- content/en/functions/os/Getenv.md | 4 +- .../functions/resources/ExecuteAsTemplate.md | 4 +- content/en/functions/resources/FromString.md | 2 +- content/en/functions/resources/GetRemote.md | 10 +- content/en/functions/resources/PostProcess.md | 2 +- content/en/functions/strings/Title.md | 4 +- content/en/functions/templates/Current.md | 2 +- content/en/functions/time/AsTime.md | 4 +- content/en/functions/time/Format.md | 4 +- content/en/functions/transform/Emojify.md | 2 +- content/en/functions/transform/Highlight.md | 4 +- .../en/functions/transform/PortableText.md | 2 +- content/en/functions/transform/ToMath.md | 2 +- content/en/functions/urls/AbsLangURL.md | 8 +- content/en/functions/urls/AbsURL.md | 6 +- content/en/functions/urls/Anchorize.md | 2 +- content/en/functions/urls/RelLangURL.md | 8 +- content/en/functions/urls/RelURL.md | 6 +- content/en/functions/urls/URLize.md | 2 +- .../en/getting-started/directory-structure.md | 46 ++-- content/en/getting-started/quick-start.md | 78 ++++--- content/en/getting-started/usage.md | 26 +-- .../deploy-with-hugo-deploy.md | 6 +- .../en/host-and-deploy/deploy-with-rclone.md | 8 +- .../en/host-and-deploy/deploy-with-rsync.md | 2 +- .../host-on-aws-amplify/index.md | 6 +- .../host-on-cloudflare/index.md | 8 +- .../en/host-and-deploy/host-on-firebase.md | 2 +- .../host-on-github-pages/index.md | 10 +- .../host-and-deploy/host-on-gitlab-pages.md | 10 +- .../host-and-deploy/host-on-netlify/index.md | 16 +- .../host-and-deploy/host-on-render/index.md | 8 +- .../host-on-sourcehut-pages.md | 8 +- .../host-and-deploy/host-on-vercel/index.md | 8 +- content/en/hugo-modules/use-modules.md | 196 +++++++++++------- content/en/installation/linux.md | 2 - content/en/methods/duration/_index.md | 2 +- content/en/methods/menu-entry/Children.md | 2 +- content/en/methods/menu-entry/HasChildren.md | 2 +- content/en/methods/menu-entry/Name.md | 14 +- content/en/methods/menu-entry/PageRef.md | 6 +- content/en/methods/menu-entry/Params.md | 6 +- content/en/methods/menu-entry/Weight.md | 12 +- content/en/methods/output-format/Rel.md | 2 +- content/en/methods/page/Aliases.md | 9 +- content/en/methods/page/AllTranslations.md | 2 +- content/en/methods/page/Data.md | 2 +- content/en/methods/page/Date.md | 2 +- content/en/methods/page/Draft.md | 2 +- content/en/methods/page/ExpiryDate.md | 2 +- content/en/methods/page/File.md | 2 - content/en/methods/page/Fragments.md | 2 +- content/en/methods/page/GitInfo.md | 10 +- content/en/methods/page/HasMenuCurrent.md | 2 +- content/en/methods/page/IsMenuCurrent.md | 2 +- content/en/methods/page/IsTranslated.md | 2 +- content/en/methods/page/Language.md | 34 +-- content/en/methods/page/Paginate.md | 4 +- content/en/methods/page/Paginator.md | 4 +- content/en/methods/page/Permalink.md | 2 +- content/en/methods/page/PublishDate.md | 2 +- content/en/methods/page/RelPermalink.md | 2 +- content/en/methods/page/Rotate.md | 45 ++-- content/en/methods/page/Sitemap.md | 2 +- content/en/methods/page/Sites.md | 36 +++- content/en/methods/page/TableOfContents.md | 2 +- content/en/methods/page/Title.md | 4 +- content/en/methods/page/TranslationKey.md | 2 +- content/en/methods/page/Translations.md | 2 +- content/en/methods/pager/PagerSize.md | 4 +- content/en/methods/pager/_index.md | 2 +- content/en/methods/pages/ByDate.md | 4 +- content/en/methods/pages/ByExpiryDate.md | 4 +- content/en/methods/pages/ByLanguage.md | 27 ++- content/en/methods/pages/ByLastmod.md | 4 +- content/en/methods/pages/ByParam.md | 2 +- content/en/methods/pages/ByPublishDate.md | 4 +- content/en/methods/pages/GroupByDate.md | 4 +- content/en/methods/pages/GroupByExpiryDate.md | 4 +- content/en/methods/pages/GroupByLastmod.md | 4 +- .../en/methods/pages/GroupByPublishDate.md | 4 +- content/en/methods/resource/Exif.md | 2 +- content/en/methods/resource/Meta.md | 6 +- content/en/methods/resource/_index.md | 2 +- content/en/methods/site/AllPages.md | 5 + content/en/methods/site/BaseURL.md | 4 +- content/en/methods/site/BuildDrafts.md | 11 +- content/en/methods/site/Config.md | 4 +- content/en/methods/site/Copyright.md | 4 +- content/en/methods/site/Data.md | 5 + content/en/methods/site/Dimension.md | 12 +- content/en/methods/site/GetPage.md | 2 +- content/en/methods/site/Home.md | 2 +- content/en/methods/site/IsDefault.md | 50 +++++ content/en/methods/site/Language.md | 30 +-- content/en/methods/site/LanguagePrefix.md | 2 +- content/en/methods/site/Languages.md | 9 +- content/en/methods/site/MainSections.md | 8 +- content/en/methods/site/Param.md | 2 +- content/en/methods/site/Params.md | 4 +- content/en/methods/site/Role.md | 12 +- content/en/methods/site/Sites.md | 36 +++- content/en/methods/site/Taxonomies.md | 2 +- content/en/methods/site/Title.md | 4 +- content/en/methods/site/Version.md | 10 +- content/en/methods/site/_index.md | 2 +- content/en/methods/taxonomy/_index.md | 2 +- content/en/methods/time/_index.md | 2 +- .../glossary/build-artifacts.md | 5 + content/en/quick-reference/glossary/build.md | 2 +- .../glossary/canonical-output-format.md | 6 +- .../en/quick-reference/glossary/component.md | 4 +- .../glossary/default-language.md | 9 + .../quick-reference/glossary/default-role.md | 9 + .../quick-reference/glossary/default-site.md | 4 +- .../glossary/default-version.md | 9 + .../glossary/dependency-graph.md | 5 + .../en/quick-reference/glossary/dimension.md | 2 +- .../quick-reference/glossary/environment.md | 2 +- .../en/quick-reference/glossary/glob-slice.md | 2 +- .../en/quick-reference/glossary/language.md | 7 + .../quick-reference/glossary/page-relative.md | 2 +- .../en/quick-reference/glossary/project.md | 5 + .../glossary/regular-expression.md | 2 +- content/en/quick-reference/glossary/role.md | 4 +- .../glossary/server-relative.md | 2 +- .../quick-reference/glossary/site-relative.md | 2 +- .../en/quick-reference/glossary/site-root.md | 2 +- content/en/quick-reference/glossary/site.md | 2 +- .../glossary/sites-complements.md | 2 +- .../quick-reference/glossary/sites-matrix.md | 4 +- .../en/quick-reference/glossary/version.md | 9 + .../en/quick-reference/glossary/workspace.md | 7 + .../glossary/wrapper-component.md | 2 +- .../syntax-highlighting-styles.md | 2 +- content/en/render-hooks/code-blocks.md | 2 +- content/en/render-hooks/images.md | 6 +- content/en/render-hooks/links.md | 4 +- content/en/render-hooks/passthrough.md | 2 +- content/en/shortcodes/figure.md | 2 +- content/en/shortcodes/highlight.md | 6 +- content/en/shortcodes/instagram.md | 2 +- content/en/shortcodes/param.md | 2 +- content/en/shortcodes/vimeo.md | 2 +- content/en/shortcodes/x.md | 4 +- content/en/shortcodes/youtube.md | 2 +- content/en/templates/embedded.md | 17 +- content/en/templates/introduction.md | 6 +- content/en/templates/menu.md | 14 +- content/en/templates/pagination.md | 6 +- content/en/templates/robots.md | 8 +- content/en/templates/rss.md | 6 +- content/en/templates/sitemap.md | 2 +- content/en/tools/other.md | 2 +- content/en/troubleshooting/audit/index.md | 4 +- content/en/troubleshooting/deprecation.md | 4 +- content/en/troubleshooting/logging.md | 10 +- content/en/troubleshooting/performance.md | 2 +- data/docs.yaml | 48 ++--- layouts/_markup/render-codeblock.html | 2 +- .../helpers/validation/validate-keywords.html | 2 +- layouts/_partials/layouts/home/sponsors.html | 2 +- layouts/_shortcodes/chroma-lexers.html | 2 +- layouts/_shortcodes/code-toggle.html | 10 +- layouts/_shortcodes/datatable.html | 2 +- layouts/_shortcodes/eturl.html | 4 +- .../_shortcodes/list-pages-in-section.html | 2 +- .../_shortcodes/root-configuration-keys.html | 2 +- .../syntax-highlighting-styles.html | 2 +- netlify.toml | 2 +- 282 files changed, 1250 insertions(+), 820 deletions(-) create mode 100644 assets/css/components/todo-lists.css create mode 100644 content/en/_common/functions/hugo/sites-collection.md rename content/en/commands/{hugo_new_site.md => hugo_new_project.md} (83%) create mode 100644 content/en/functions/hugo/Data.md create mode 100644 content/en/functions/hugo/Sites.md create mode 100644 content/en/methods/site/IsDefault.md create mode 100644 content/en/quick-reference/glossary/build-artifacts.md create mode 100644 content/en/quick-reference/glossary/default-language.md create mode 100644 content/en/quick-reference/glossary/default-role.md create mode 100644 content/en/quick-reference/glossary/default-version.md create mode 100644 content/en/quick-reference/glossary/dependency-graph.md create mode 100644 content/en/quick-reference/glossary/language.md create mode 100644 content/en/quick-reference/glossary/project.md create mode 100644 content/en/quick-reference/glossary/version.md create mode 100644 content/en/quick-reference/glossary/workspace.md diff --git a/assets/css/components/all.css b/assets/css/components/all.css index f5002fd50..62c2b2a41 100644 --- a/assets/css/components/all.css +++ b/assets/css/components/all.css @@ -5,3 +5,4 @@ @import "./shortcodes.css"; @import "./tableofcontents.css"; @import "./view-transitions.css"; +@import "./todo-lists.css"; diff --git a/assets/css/components/todo-lists.css b/assets/css/components/todo-lists.css new file mode 100644 index 000000000..886beb41d --- /dev/null +++ b/assets/css/components/todo-lists.css @@ -0,0 +1,15 @@ +ul.todo { + padding-left: 0; +} + +ul.todo li { + display: flex; + gap: 0.8em; +} + +ul.todo li input[type="checkbox"] { + width: 1em; + height: 1em; + flex-shrink: 0; + margin-top: 0.3em; +} diff --git a/assets/css/styles.css b/assets/css/styles.css index 6734e9a30..79ce316d1 100644 --- a/assets/css/styles.css +++ b/assets/css/styles.css @@ -105,14 +105,14 @@ body { padding-right: max(env(safe-area-inset-right), 1rem); } -@media screen(md) { +@media (min-width: theme('--breakpoint-md')) { .px-main { padding-left: max(env(safe-area-inset-left), 2rem); padding-right: max(env(safe-area-inset-right), 2rem); } } -@media screen(lg) { +@media (min-width: theme('--breakpoint-lg')) { .px-main { padding-left: max(env(safe-area-inset-left), 3rem); padding-right: max(env(safe-area-inset-right), 3rem); diff --git a/content/en/_common/functions/hugo/sites-collection.md b/content/en/_common/functions/hugo/sites-collection.md new file mode 100644 index 000000000..9f4b81b5a --- /dev/null +++ b/content/en/_common/functions/hugo/sites-collection.md @@ -0,0 +1,9 @@ +--- +_comment: Do not remove front matter. +--- + +The returned collection follows a hierarchical sort where each subsequent dimension acts as a tie-breaker for the one above it. + +1. [Language](g) is sorted by [weight](g) in ascending order, falling back to lexicographical order if weights are tied or undefined. +1. [Version](g) is then sorted by weight in ascending order, with Hugo defaulting to a descending semantic sort for any ties. +1. [Role](g) is finally sorted by weight in ascending order, using lexicographical order as the final fallback. diff --git a/content/en/_common/menu-entries/pre-and-post.md b/content/en/_common/menu-entries/pre-and-post.md index da3d584d1..9f101b457 100644 --- a/content/en/_common/menu-entries/pre-and-post.md +++ b/content/en/_common/menu-entries/pre-and-post.md @@ -2,7 +2,7 @@ _comment: Do not remove front matter. --- -In this site configuration we enable rendering of [emoji shortcodes], and add emoji shortcodes before (pre) and after (post) each menu entry: +In this project configuration we enable rendering of [emoji shortcodes], and add emoji shortcodes before (pre) and after (post) each menu entry: {{< code-toggle file=hugo >}} enableEmoji = true diff --git a/content/en/_common/methods/page/next-and-prev.md b/content/en/_common/methods/page/next-and-prev.md index 27b069ddc..75f120c02 100644 --- a/content/en/_common/methods/page/next-and-prev.md +++ b/content/en/_common/methods/page/next-and-prev.md @@ -53,8 +53,8 @@ When you visit page-2: - The `Prev` method points to page-3 - The `Next` method points to page-1 -To reverse the meaning of _next_ and _previous_ you can change the sort direction in your [site configuration], or use the [`Next`] and [`Prev`] methods on a `Pages` object for more flexibility. +To reverse the meaning of _next_ and _previous_ you can change the sort direction in your [project configuration], or use the [`Next`] and [`Prev`] methods on a `Pages` object for more flexibility. -[site configuration]: /configuration/page/ +[project configuration]: /configuration/page/ [`Next`]: /methods/pages/prev [`Prev`]: /methods/pages/prev diff --git a/content/en/_common/methods/page/nextinsection-and-previnsection.md b/content/en/_common/methods/page/nextinsection-and-previnsection.md index 005953324..4ca8a4ac8 100644 --- a/content/en/_common/methods/page/nextinsection-and-previnsection.md +++ b/content/en/_common/methods/page/nextinsection-and-previnsection.md @@ -53,9 +53,9 @@ When you visit page-2: - The `PrevInSection` method points to page-3 - The `NextInSection` method points to page-1 -To reverse the meaning of _next_ and _previous_ you can change the sort direction in your [site configuration], or use the [`Next`] and [`Prev`] methods on a `Pages` object for more flexibility. +To reverse the meaning of _next_ and _previous_ you can change the sort direction in your [project configuration], or use the [`Next`] and [`Prev`] methods on a `Pages` object for more flexibility. -[site configuration]: /configuration/page/ +[project configuration]: /configuration/page/ [`Next`]: /methods/pages/prev [`Prev`]: /methods/pages/prev diff --git a/content/en/_common/methods/resource/processing-spec.md b/content/en/_common/methods/resource/processing-spec.md index 20b8f8498..226c0ba6d 100644 --- a/content/en/_common/methods/resource/processing-spec.md +++ b/content/en/_common/methods/resource/processing-spec.md @@ -10,14 +10,14 @@ action : Specify one of `crop`, `fill`, `fit`, or `resize`. This is applicable to the [`Process`][] method and the [`images.Process`][] filter. If you specify an action, you must also provide dimensions. anchor -: The focal point used when cropping or filling an image. Valid options include `TopLeft`, `Top`, `TopRight`, `Left`, `Center`, `Right`, `BottomLeft`, `Bottom`, `BottomRight`, or `Smart`. The `Smart` option utilizes the [`smartcrop.js`][] library to identify the most interesting area of the image. This defaults to the [`anchor`][] parameter in your site configuration. +: The focal point used when cropping or filling an image. Valid options include `TopLeft`, `Top`, `TopRight`, `Left`, `Center`, `Right`, `BottomLeft`, `Bottom`, `BottomRight`, or `Smart`. The `Smart` option utilizes the [`smartcrop.js`][] library to identify the most interesting area of the image. This defaults to the [`anchor`][] parameter in your project configuration. background color -: The background color used when converting transparent images to formats that do not support transparency, such as PNG to JPEG. This color also fills the empty space created when rotating an image by a non-orthogonal angle if the space is not transparent and a background color is not specified in the processing specification. The value must be an RGB [hexadecimal color][]. This defaults to the [`bgColor`][] parameter in your site configuration. +: The background color used when converting transparent images to formats that do not support transparency, such as PNG to JPEG. This color also fills the empty space created when rotating an image by a non-orthogonal angle if the space is not transparent and a background color is not specified in the processing specification. The value must be an RGB [hexadecimal color][]. This defaults to the [`bgColor`][] parameter in your project configuration. compression : {{< new-in 0.153.5 />}} -: The encoding strategy used for the image. Options are `lossy` or `lossless`. Note that `lossless` is only supported by the WebP format. This defaults to the [`compression`][] parameter in your site configuration. +: The encoding strategy used for the image. Options are `lossy` or `lossless`. Note that `lossless` is only supported by the WebP format. This defaults to the [`compression`][] parameter in your project configuration. dimensions : The dimensions of the resulting image, in pixels. The format is `WIDTHxHEIGHT` where `WIDTH` and `HEIGHT` are whole numbers. When resizing an image, you may specify only the width (such as `600x`) or only the height (such as `x400`) for proportional scaling. Specifying both width and height when resizing an image may result in non-proportional scaling. When cropping, fitting, or filling, you must provide both width and height such as `600x400`. @@ -26,7 +26,7 @@ format : The format of the resulting image. Valid options include `bmp`, `gif`, `jpeg`, `png`, `tiff`, or `webp`. This defaults to the format of the source image. hint -: The encoding preset used when processing WebP images, equivalent to the `-preset` flag for the [`cwebp`][] CLI. Valid options include `drawing`, `icon`, `photo`, `picture`, or `text`. This defaults to the [`hint`][] parameter in your site configuration. +: The encoding preset used when processing WebP images, equivalent to the `-preset` flag for the [`cwebp`][] CLI. Valid options include `drawing`, `icon`, `photo`, `picture`, or `text`. This defaults to the [`hint`][] parameter in your project configuration. Value|Example :--|:-- @@ -37,10 +37,10 @@ hint `text`|Image that is primarily text quality -: The visual fidelity of the image, applicable to JPEG and WebP formats when using `lossy` compression. The format is `qQUALITY` where `QUALITY` is a whole number between `1` and `100`, inclusive. Lower numbers prioritize smaller file size, while higher numbers prioritize visual clarity. This defaults to the [`quality`][] parameter in your site configuration. +: The visual fidelity of the image, applicable to JPEG and WebP formats when using `lossy` compression. The format is `qQUALITY` where `QUALITY` is a whole number between `1` and `100`, inclusive. Lower numbers prioritize smaller file size, while higher numbers prioritize visual clarity. This defaults to the [`quality`][] parameter in your project configuration. resampling filter -: The algorithm used to calculate new pixels when resizing, fitting, or filling an image. Common options include `box`, `lanczos`, `catmullRom`, `mitchellNetravali`, `linear`, or `nearestNeighbor`. This defaults to the [`resampleFilter`][] parameter in your site configuration. +: The algorithm used to calculate new pixels when resizing, fitting, or filling an image. Common options include `box`, `lanczos`, `catmullRom`, `mitchellNetravali`, `linear`, or `nearestNeighbor`. This defaults to the [`resampleFilter`][] parameter in your project configuration. Filter|Description :--|:-- @@ -56,7 +56,7 @@ resampling filter rotation : The number of whole degrees to rotate an image counter-clockwise. The format is `rDEGREES` where `DEGREES` is a whole number. Hugo performs rotation before any other transformations, so your [target dimensions](#dimensions) and any [anchor](#anchor) should refer to the image orientation after rotation. Use `r90`, `r180`, or `r270` for orthogonal rotations, or arbitrary angles such as `r45`. To rotate clockwise, use a negative number such as `r-45`. To automatically rotate an image based on its Exif orientation tag, use the [`images.AutoOrient`][] filter instead of manual rotation. - Rotating by non-orthogonal values increases the image extents to fit the rotated corners. For formats supporting alpha channels such as PNG or WebP, this resulting empty space is transparent by default. If the target format does not support transparency such as JPEG, or if you explicitly specify a [background color](#background-color) in the processing specification, the space is filled. If a color is required but not specified in the processing string, it defaults to the [`bgColor`][] parameter in your site configuration. + Rotating by non-orthogonal values increases the image extents to fit the rotated corners. For formats supporting alpha channels such as PNG or WebP, this resulting empty space is transparent by default. If the target format does not support transparency such as JPEG, or if you explicitly specify a [background color](#background-color) in the processing specification, the space is filled. If a color is required but not specified in the processing string, it defaults to the [`bgColor`][] parameter in your project configuration. [`anchor`]: /configuration/imaging/#anchor [`bgcolor`]: /configuration/imaging/#bgcolor diff --git a/content/en/_common/methods/taxonomy/get-a-taxonomy-object.md b/content/en/_common/methods/taxonomy/get-a-taxonomy-object.md index c90224338..75386145c 100644 --- a/content/en/_common/methods/taxonomy/get-a-taxonomy-object.md +++ b/content/en/_common/methods/taxonomy/get-a-taxonomy-object.md @@ -6,7 +6,7 @@ Before we can use a `Taxonomy` method, we need to capture a `Taxonomy` object. ## Capture a Taxonomy object -Consider this site configuration: +Consider this project configuration: {{< code-toggle file=hugo >}} [taxonomies] diff --git a/content/en/_common/ref-and-relref-error-handling.md b/content/en/_common/ref-and-relref-error-handling.md index 1d67bbc1f..9ec185d09 100644 --- a/content/en/_common/ref-and-relref-error-handling.md +++ b/content/en/_common/ref-and-relref-error-handling.md @@ -2,7 +2,7 @@ _comment: Do not remove front matter. --- -By default, Hugo will throw an error and fail the build if it cannot resolve the path. You can change this to a warning in your site configuration, and specify a URL to return when the path cannot be resolved. +By default, Hugo will throw an error and fail the build if it cannot resolve the path. You can change this to a warning in your project configuration, and specify a URL to return when the path cannot be resolved. {{< code-toggle file=hugo >}} refLinksErrorLevel = 'warning' diff --git a/content/en/about/features.md b/content/en/about/features.md index e39e359ec..04c61fc65 100644 --- a/content/en/about/features.md +++ b/content/en/about/features.md @@ -61,10 +61,10 @@ weight: 20 ## Content management [Multidimensional content model] -: Generate pages across any combination of language, role, and version from a single source. This allows a single piece of content to be published to multiple [sites](g) within your project, removing the need to duplicate files for different audiences or versions. +: Generate pages across any combination of language, version, and role from a single source. This allows a single piece of content to be published to multiple [sites](g) within your project, removing the need to duplicate files for different audiences or versions. [Content adapters] -: Create content adapters to dynamically add content when building your site. For example, use a content adapter to create pages from a remote data source such as JSON, TOML, YAML, or XML. +: Create content adapters to dynamically add content when building your project. For example, use a content adapter to create pages from a remote data source such as JSON, TOML, YAML, or XML. [Taxonomies] : Classify content to establish simple or complex logical relationships between pages. For example, create an authors taxonomy, and assign one or more authors to each page. Among other uses, the taxonomy system provides an inverted, weighted index to render a list of related pages, ordered by relevance. diff --git a/content/en/commands/hugo.md b/content/en/commands/hugo.md index ef0bca9a5..ad06ecab3 100644 --- a/content/en/commands/hugo.md +++ b/content/en/commands/hugo.md @@ -5,11 +5,11 @@ url: /commands/hugo/ --- ## hugo -Build your site +Build your project ### Synopsis -hugo is the main command, used to build your Hugo site. +hugo is the main command, used to build your Hugo project. Hugo is a Fast and Flexible Static Site Generator built with love by spf13 and friends in Go. @@ -68,17 +68,16 @@ hugo [flags] ### SEE ALSO -* [hugo build](/commands/hugo_build/) - Build your site +* [hugo build](/commands/hugo_build/) - Build your project * [hugo completion](/commands/hugo_completion/) - Generate the autocompletion script for the specified shell -* [hugo config](/commands/hugo_config/) - Display site configuration +* [hugo config](/commands/hugo_config/) - Display project 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 deploy](/commands/hugo_deploy/) - Deploy your project 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 +* [hugo import](/commands/hugo_import/) - Import a project from another system * [hugo list](/commands/hugo_list/) - List content * [hugo mod](/commands/hugo_mod/) - Manage modules * [hugo new](/commands/hugo_new/) - Create new content * [hugo server](/commands/hugo_server/) - Start the embedded web server * [hugo version](/commands/hugo_version/) - Display version - diff --git a/content/en/commands/hugo_build.md b/content/en/commands/hugo_build.md index 582cbe511..173cb095e 100644 --- a/content/en/commands/hugo_build.md +++ b/content/en/commands/hugo_build.md @@ -5,11 +5,11 @@ url: /commands/hugo_build/ --- ## hugo build -Build your site +Build your project ### Synopsis -build is the main command, used to build your Hugo site. +build is the main command, used to build your Hugo project. Hugo is a Fast and Flexible Static Site Generator built with love by spf13 and friends in Go. @@ -68,5 +68,4 @@ hugo build [flags] ### SEE ALSO -* [hugo](/commands/hugo/) - Build your site - +* [hugo](/commands/hugo/) - Build your project diff --git a/content/en/commands/hugo_completion.md b/content/en/commands/hugo_completion.md index ac60dc148..34b411481 100644 --- a/content/en/commands/hugo_completion.md +++ b/content/en/commands/hugo_completion.md @@ -38,9 +38,8 @@ See each sub-command's help for details on how to use the generated script. ### SEE ALSO -* [hugo](/commands/hugo/) - Build your site +* [hugo](/commands/hugo/) - Build your project * [hugo completion bash](/commands/hugo_completion_bash/) - Generate the autocompletion script for bash * [hugo completion fish](/commands/hugo_completion_fish/) - Generate the autocompletion script for fish * [hugo completion powershell](/commands/hugo_completion_powershell/) - Generate the autocompletion script for powershell * [hugo completion zsh](/commands/hugo_completion_zsh/) - Generate the autocompletion script for zsh - diff --git a/content/en/commands/hugo_completion_bash.md b/content/en/commands/hugo_completion_bash.md index 41fb47c0c..9f18169ca 100644 --- a/content/en/commands/hugo_completion_bash.md +++ b/content/en/commands/hugo_completion_bash.md @@ -62,4 +62,3 @@ hugo completion bash ### SEE ALSO * [hugo completion](/commands/hugo_completion/) - Generate the autocompletion script for the specified shell - diff --git a/content/en/commands/hugo_completion_fish.md b/content/en/commands/hugo_completion_fish.md index 7f971c3ca..3015d230c 100644 --- a/content/en/commands/hugo_completion_fish.md +++ b/content/en/commands/hugo_completion_fish.md @@ -53,4 +53,3 @@ hugo completion fish [flags] ### SEE ALSO * [hugo completion](/commands/hugo_completion/) - Generate the autocompletion script for the specified shell - diff --git a/content/en/commands/hugo_completion_powershell.md b/content/en/commands/hugo_completion_powershell.md index 6ea17892b..780f7fc7d 100644 --- a/content/en/commands/hugo_completion_powershell.md +++ b/content/en/commands/hugo_completion_powershell.md @@ -50,4 +50,3 @@ hugo completion powershell [flags] ### SEE ALSO * [hugo completion](/commands/hugo_completion/) - Generate the autocompletion script for the specified shell - diff --git a/content/en/commands/hugo_completion_zsh.md b/content/en/commands/hugo_completion_zsh.md index b9e79f9f3..e5743e988 100644 --- a/content/en/commands/hugo_completion_zsh.md +++ b/content/en/commands/hugo_completion_zsh.md @@ -64,4 +64,3 @@ hugo completion zsh [flags] ### SEE ALSO * [hugo completion](/commands/hugo_completion/) - Generate the autocompletion script for the specified shell - diff --git a/content/en/commands/hugo_config.md b/content/en/commands/hugo_config.md index 2b4eaafa1..3de89f18c 100644 --- a/content/en/commands/hugo_config.md +++ b/content/en/commands/hugo_config.md @@ -5,11 +5,11 @@ url: /commands/hugo_config/ --- ## hugo config -Display site configuration +Display project configuration ### Synopsis -Display site configuration, both default and custom settings. +Display project configuration, both default and custom settings. ``` hugo config [command] [flags] @@ -48,6 +48,5 @@ hugo config [command] [flags] ### SEE ALSO -* [hugo](/commands/hugo/) - Build your site +* [hugo](/commands/hugo/) - Build your project * [hugo config mounts](/commands/hugo_config_mounts/) - Print the configured file mounts - diff --git a/content/en/commands/hugo_config_mounts.md b/content/en/commands/hugo_config_mounts.md index 06a781220..eb540acff 100644 --- a/content/en/commands/hugo_config_mounts.md +++ b/content/en/commands/hugo_config_mounts.md @@ -41,5 +41,4 @@ hugo config mounts [flags] [args] ### SEE ALSO -* [hugo config](/commands/hugo_config/) - Display site configuration - +* [hugo config](/commands/hugo_config/) - Display project configuration diff --git a/content/en/commands/hugo_convert.md b/content/en/commands/hugo_convert.md index a8d0b6a38..f293fa4b4 100644 --- a/content/en/commands/hugo_convert.md +++ b/content/en/commands/hugo_convert.md @@ -40,8 +40,7 @@ See convert's subcommands toJSON, toTOML and toYAML for more information. ### SEE ALSO -* [hugo](/commands/hugo/) - Build your site +* [hugo](/commands/hugo/) - Build your project * [hugo convert toJSON](/commands/hugo_convert_tojson/) - Convert front matter to JSON * [hugo convert toTOML](/commands/hugo_convert_totoml/) - Convert front matter to TOML * [hugo convert toYAML](/commands/hugo_convert_toyaml/) - Convert front matter to YAML - diff --git a/content/en/commands/hugo_convert_toJSON.md b/content/en/commands/hugo_convert_toJSON.md index fe81146f9..59a6376fe 100644 --- a/content/en/commands/hugo_convert_toJSON.md +++ b/content/en/commands/hugo_convert_toJSON.md @@ -44,4 +44,3 @@ hugo convert toJSON [flags] [args] ### SEE ALSO * [hugo convert](/commands/hugo_convert/) - Convert front matter to another format - diff --git a/content/en/commands/hugo_convert_toTOML.md b/content/en/commands/hugo_convert_toTOML.md index 490b15ee6..de48f71cd 100644 --- a/content/en/commands/hugo_convert_toTOML.md +++ b/content/en/commands/hugo_convert_toTOML.md @@ -44,4 +44,3 @@ hugo convert toTOML [flags] [args] ### SEE ALSO * [hugo convert](/commands/hugo_convert/) - Convert front matter to another format - diff --git a/content/en/commands/hugo_convert_toYAML.md b/content/en/commands/hugo_convert_toYAML.md index 9b00ce247..ae14e8e33 100644 --- a/content/en/commands/hugo_convert_toYAML.md +++ b/content/en/commands/hugo_convert_toYAML.md @@ -44,4 +44,3 @@ hugo convert toYAML [flags] [args] ### SEE ALSO * [hugo convert](/commands/hugo_convert/) - Convert front matter to another format - diff --git a/content/en/commands/hugo_deploy.md b/content/en/commands/hugo_deploy.md index 696acf51f..b8c08a33f 100644 --- a/content/en/commands/hugo_deploy.md +++ b/content/en/commands/hugo_deploy.md @@ -5,11 +5,11 @@ url: /commands/hugo_deploy/ --- ## hugo deploy -Deploy your site to a cloud provider +Deploy your project to a cloud provider ### Synopsis -Deploy your site to a cloud provider +Deploy your project to a cloud provider See https://gohugo.io/hosting-and-deployment/hugo-deploy/ for detailed documentation. @@ -51,5 +51,4 @@ hugo deploy [flags] [args] ### SEE ALSO -* [hugo](/commands/hugo/) - Build your site - +* [hugo](/commands/hugo/) - Build your project diff --git a/content/en/commands/hugo_env.md b/content/en/commands/hugo_env.md index 7e21733a4..007eb2ad4 100644 --- a/content/en/commands/hugo_env.md +++ b/content/en/commands/hugo_env.md @@ -40,5 +40,4 @@ hugo env [flags] [args] ### SEE ALSO -* [hugo](/commands/hugo/) - Build your site - +* [hugo](/commands/hugo/) - Build your project diff --git a/content/en/commands/hugo_gen.md b/content/en/commands/hugo_gen.md index ae11a0321..605a8faa8 100644 --- a/content/en/commands/hugo_gen.md +++ b/content/en/commands/hugo_gen.md @@ -36,8 +36,7 @@ Generate documentation for your project using Hugo's documentation engine, inclu ### SEE ALSO -* [hugo](/commands/hugo/) - Build your site +* [hugo](/commands/hugo/) - Build your project * [hugo gen chromastyles](/commands/hugo_gen_chromastyles/) - Generate CSS stylesheet for the Chroma code highlighter * [hugo gen doc](/commands/hugo_gen_doc/) - Generate Markdown documentation for the Hugo CLI * [hugo gen man](/commands/hugo_gen_man/) - Generate man pages for the Hugo CLI - diff --git a/content/en/commands/hugo_gen_chromastyles.md b/content/en/commands/hugo_gen_chromastyles.md index 78cc62f88..5d6ed753c 100644 --- a/content/en/commands/hugo_gen_chromastyles.md +++ b/content/en/commands/hugo_gen_chromastyles.md @@ -49,4 +49,3 @@ hugo gen chromastyles [flags] [args] ### SEE ALSO * [hugo gen](/commands/hugo_gen/) - Generate documentation and syntax highlighting styles - diff --git a/content/en/commands/hugo_gen_doc.md b/content/en/commands/hugo_gen_doc.md index 3d808e75c..28f061735 100644 --- a/content/en/commands/hugo_gen_doc.md +++ b/content/en/commands/hugo_gen_doc.md @@ -47,4 +47,3 @@ hugo gen doc [flags] [args] ### SEE ALSO * [hugo gen](/commands/hugo_gen/) - Generate documentation and syntax highlighting styles - diff --git a/content/en/commands/hugo_gen_man.md b/content/en/commands/hugo_gen_man.md index 14fe859e3..7ebc9ffb8 100644 --- a/content/en/commands/hugo_gen_man.md +++ b/content/en/commands/hugo_gen_man.md @@ -44,4 +44,3 @@ hugo gen man [flags] [args] ### SEE ALSO * [hugo gen](/commands/hugo_gen/) - Generate documentation and syntax highlighting styles - diff --git a/content/en/commands/hugo_import.md b/content/en/commands/hugo_import.md index 2b8e62951..5e38a68c4 100644 --- a/content/en/commands/hugo_import.md +++ b/content/en/commands/hugo_import.md @@ -5,11 +5,11 @@ url: /commands/hugo_import/ --- ## hugo import -Import a site from another system +Import a project from another system ### Synopsis -Import a site from another system. +Import a project from another system. Import requires a subcommand, e.g. `hugo import jekyll jekyll_root_path target_path`. @@ -38,6 +38,5 @@ Import requires a subcommand, e.g. `hugo import jekyll jekyll_root_path target_p ### SEE ALSO -* [hugo](/commands/hugo/) - Build your site +* [hugo](/commands/hugo/) - Build your project * [hugo import jekyll](/commands/hugo_import_jekyll/) - hugo import from Jekyll - diff --git a/content/en/commands/hugo_import_jekyll.md b/content/en/commands/hugo_import_jekyll.md index 8746c156e..d1f16b926 100644 --- a/content/en/commands/hugo_import_jekyll.md +++ b/content/en/commands/hugo_import_jekyll.md @@ -10,7 +10,7 @@ hugo import from Jekyll ### Synopsis hugo import from Jekyll. - + Import from Jekyll requires two paths, e.g. `hugo import jekyll jekyll_root_path target_path`. ``` @@ -43,5 +43,4 @@ hugo import jekyll [flags] [args] ### SEE ALSO -* [hugo import](/commands/hugo_import/) - Import a site from another system - +* [hugo import](/commands/hugo_import/) - Import a project from another system diff --git a/content/en/commands/hugo_list.md b/content/en/commands/hugo_list.md index 741ca1d68..90b8e6d69 100644 --- a/content/en/commands/hugo_list.md +++ b/content/en/commands/hugo_list.md @@ -38,10 +38,9 @@ List requires a subcommand, e.g. hugo list drafts ### SEE ALSO -* [hugo](/commands/hugo/) - Build your site +* [hugo](/commands/hugo/) - Build your project * [hugo list all](/commands/hugo_list_all/) - List all content * [hugo list drafts](/commands/hugo_list_drafts/) - List draft content * [hugo list expired](/commands/hugo_list_expired/) - List expired content * [hugo list future](/commands/hugo_list_future/) - List future content * [hugo list published](/commands/hugo_list_published/) - List published content - diff --git a/content/en/commands/hugo_list_all.md b/content/en/commands/hugo_list_all.md index e0f1efdcb..6b324ab17 100644 --- a/content/en/commands/hugo_list_all.md +++ b/content/en/commands/hugo_list_all.md @@ -41,4 +41,3 @@ hugo list all [flags] [args] ### SEE ALSO * [hugo list](/commands/hugo_list/) - List content - diff --git a/content/en/commands/hugo_list_drafts.md b/content/en/commands/hugo_list_drafts.md index 25ddc78d3..c6a89077c 100644 --- a/content/en/commands/hugo_list_drafts.md +++ b/content/en/commands/hugo_list_drafts.md @@ -41,4 +41,3 @@ hugo list drafts [flags] [args] ### SEE ALSO * [hugo list](/commands/hugo_list/) - List content - diff --git a/content/en/commands/hugo_list_expired.md b/content/en/commands/hugo_list_expired.md index 1936b9920..b0618ca06 100644 --- a/content/en/commands/hugo_list_expired.md +++ b/content/en/commands/hugo_list_expired.md @@ -41,4 +41,3 @@ hugo list expired [flags] [args] ### SEE ALSO * [hugo list](/commands/hugo_list/) - List content - diff --git a/content/en/commands/hugo_list_future.md b/content/en/commands/hugo_list_future.md index 3152639c2..4f2fdcaff 100644 --- a/content/en/commands/hugo_list_future.md +++ b/content/en/commands/hugo_list_future.md @@ -41,4 +41,3 @@ hugo list future [flags] [args] ### SEE ALSO * [hugo list](/commands/hugo_list/) - List content - diff --git a/content/en/commands/hugo_list_published.md b/content/en/commands/hugo_list_published.md index a7a08c7b4..a49768707 100644 --- a/content/en/commands/hugo_list_published.md +++ b/content/en/commands/hugo_list_published.md @@ -41,4 +41,3 @@ hugo list published [flags] [args] ### SEE ALSO * [hugo list](/commands/hugo_list/) - List content - diff --git a/content/en/commands/hugo_mod.md b/content/en/commands/hugo_mod.md index 25a27185d..5cc9eef4e 100644 --- a/content/en/commands/hugo_mod.md +++ b/content/en/commands/hugo_mod.md @@ -14,7 +14,7 @@ Most operations here requires a Go version installed on your system (>= Go 1.12) This is not needed if you only operate on modules inside /themes or if you have vendored them via "hugo mod vendor". -Note that Hugo will always start out by resolving the components defined in the site +Note that Hugo will always start out by resolving the components defined in the project configuration, provided by a _vendor directory (if no --ignoreVendorPaths flag provided), Go Modules, or a folder inside the themes directory, in that order. @@ -47,7 +47,7 @@ See https://gohugo.io/hugo-modules/ for more information. ### SEE ALSO -* [hugo](/commands/hugo/) - Build your site +* [hugo](/commands/hugo/) - Build your project * [hugo mod clean](/commands/hugo_mod_clean/) - Delete the Hugo Module cache for the current project * [hugo mod get](/commands/hugo_mod_get/) - Resolves dependencies in your current Hugo project * [hugo mod graph](/commands/hugo_mod_graph/) - Print a module dependency graph @@ -56,4 +56,3 @@ See https://gohugo.io/hugo-modules/ for more information. * [hugo mod tidy](/commands/hugo_mod_tidy/) - Remove unused entries in go.mod and go.sum * [hugo mod vendor](/commands/hugo_mod_vendor/) - Vendor all module dependencies into the _vendor directory * [hugo mod verify](/commands/hugo_mod_verify/) - Verify dependencies - diff --git a/content/en/commands/hugo_mod_clean.md b/content/en/commands/hugo_mod_clean.md index ff2255e53..9abb1cbd9 100644 --- a/content/en/commands/hugo_mod_clean.md +++ b/content/en/commands/hugo_mod_clean.md @@ -48,4 +48,3 @@ hugo mod clean [flags] [args] ### SEE ALSO * [hugo mod](/commands/hugo_mod/) - Manage modules - diff --git a/content/en/commands/hugo_mod_get.md b/content/en/commands/hugo_mod_get.md index a5c9a9ea9..a7eebd7ea 100644 --- a/content/en/commands/hugo_mod_get.md +++ b/content/en/commands/hugo_mod_get.md @@ -34,7 +34,7 @@ Install the latest versions of all module dependencies (direct and indirect): Run "go help get" for more information. All flags available for "go get" is also relevant here. -Note that Hugo will always start out by resolving the components defined in the site +Note that Hugo will always start out by resolving the components defined in the project configuration, provided by a _vendor directory (if no --ignoreVendorPaths flag provided), Go Modules, or a folder inside the themes directory, in that order. @@ -72,4 +72,3 @@ hugo mod get [flags] [args] ### SEE ALSO * [hugo mod](/commands/hugo_mod/) - Manage modules - diff --git a/content/en/commands/hugo_mod_graph.md b/content/en/commands/hugo_mod_graph.md index cb2bdfb5a..2e840918c 100644 --- a/content/en/commands/hugo_mod_graph.md +++ b/content/en/commands/hugo_mod_graph.md @@ -49,4 +49,3 @@ hugo mod graph [flags] [args] ### SEE ALSO * [hugo mod](/commands/hugo_mod/) - Manage modules - diff --git a/content/en/commands/hugo_mod_init.md b/content/en/commands/hugo_mod_init.md index 3315e97d6..05d785caf 100644 --- a/content/en/commands/hugo_mod_init.md +++ b/content/en/commands/hugo_mod_init.md @@ -53,4 +53,3 @@ hugo mod init [flags] [args] ### SEE ALSO * [hugo mod](/commands/hugo_mod/) - Manage modules - diff --git a/content/en/commands/hugo_mod_npm.md b/content/en/commands/hugo_mod_npm.md index 39a559e0f..eafda1768 100644 --- a/content/en/commands/hugo_mod_npm.md +++ b/content/en/commands/hugo_mod_npm.md @@ -42,4 +42,3 @@ hugo mod npm [command] [flags] * [hugo mod](/commands/hugo_mod/) - Manage modules * [hugo mod npm pack](/commands/hugo_mod_npm_pack/) - Experimental: Prepares and writes a composite package.json file for your project - diff --git a/content/en/commands/hugo_mod_npm_pack.md b/content/en/commands/hugo_mod_npm_pack.md index 5ece05769..8637d7486 100644 --- a/content/en/commands/hugo_mod_npm_pack.md +++ b/content/en/commands/hugo_mod_npm_pack.md @@ -56,4 +56,3 @@ hugo mod npm pack [flags] [args] ### SEE ALSO * [hugo mod npm](/commands/hugo_mod_npm/) - Various npm helpers - diff --git a/content/en/commands/hugo_mod_tidy.md b/content/en/commands/hugo_mod_tidy.md index c7ae40625..1114772d5 100644 --- a/content/en/commands/hugo_mod_tidy.md +++ b/content/en/commands/hugo_mod_tidy.md @@ -42,4 +42,3 @@ hugo mod tidy [flags] [args] ### SEE ALSO * [hugo mod](/commands/hugo_mod/) - Manage modules - diff --git a/content/en/commands/hugo_mod_vendor.md b/content/en/commands/hugo_mod_vendor.md index dc403affe..4e828fe35 100644 --- a/content/en/commands/hugo_mod_vendor.md +++ b/content/en/commands/hugo_mod_vendor.md @@ -48,4 +48,3 @@ hugo mod vendor [flags] [args] ### SEE ALSO * [hugo mod](/commands/hugo_mod/) - Manage modules - diff --git a/content/en/commands/hugo_mod_verify.md b/content/en/commands/hugo_mod_verify.md index 2f22a2e49..6c15a88c2 100644 --- a/content/en/commands/hugo_mod_verify.md +++ b/content/en/commands/hugo_mod_verify.md @@ -47,4 +47,3 @@ hugo mod verify [flags] [args] ### SEE ALSO * [hugo mod](/commands/hugo_mod/) - Manage modules - diff --git a/content/en/commands/hugo_new.md b/content/en/commands/hugo_new.md index 56ab4aef9..a6587e469 100644 --- a/content/en/commands/hugo_new.md +++ b/content/en/commands/hugo_new.md @@ -14,9 +14,9 @@ It will guess which kind of file to create based on the path provided. You can also specify the kind with `-k KIND`. -If archetypes are provided in your theme or site, they will be used. +If archetypes are provided in your theme or project, they will be used. -Ensure you run this within the root directory of your site. +Ensure you run this within the root directory of your project. ### Options @@ -43,8 +43,7 @@ Ensure you run this within the root directory of your site. ### SEE ALSO -* [hugo](/commands/hugo/) - Build your site +* [hugo](/commands/hugo/) - Build your project * [hugo new content](/commands/hugo_new_content/) - Create new content -* [hugo new site](/commands/hugo_new_site/) - Create a new site +* [hugo new project](/commands/hugo_new_project/) - Create a new project * [hugo new theme](/commands/hugo_new_theme/) - Create a new theme - diff --git a/content/en/commands/hugo_new_content.md b/content/en/commands/hugo_new_content.md index 9624e9a61..0a5b5439e 100644 --- a/content/en/commands/hugo_new_content.md +++ b/content/en/commands/hugo_new_content.md @@ -14,9 +14,9 @@ It will guess which kind of file to create based on the path provided. You can also specify the kind with `-k KIND`. -If archetypes are provided in your theme or site, they will be used. +If archetypes are provided in your theme or project, they will be used. -Ensure you run this within the root directory of your site. +Ensure you run this within the root directory of your project. ``` hugo new content [path] [flags] @@ -56,4 +56,3 @@ hugo new content [path] [flags] ### SEE ALSO * [hugo new](/commands/hugo_new/) - Create new content - diff --git a/content/en/commands/hugo_new_site.md b/content/en/commands/hugo_new_project.md similarity index 83% rename from content/en/commands/hugo_new_site.md rename to content/en/commands/hugo_new_project.md index ccf74bc6f..652eefec6 100644 --- a/content/en/commands/hugo_new_site.md +++ b/content/en/commands/hugo_new_project.md @@ -1,18 +1,18 @@ --- -title: "hugo new site" -slug: hugo_new_site -url: /commands/hugo_new_site/ +title: "hugo new project" +slug: hugo_new_project +url: /commands/hugo_new_project/ --- -## hugo new site +## hugo new project -Create a new site +Create a new project ### Synopsis -Create a new site at the specified path. +Create a new project at the specified path. ``` -hugo new site [path] [flags] +hugo new project [path] [flags] ``` ### Options @@ -20,7 +20,7 @@ hugo new site [path] [flags] ``` -f, --force init inside non-empty directory --format string preferred file format (toml, yaml or json) (default "toml") - -h, --help help for site + -h, --help help for project ``` ### Options inherited from parent commands @@ -43,4 +43,3 @@ hugo new site [path] [flags] ### SEE ALSO * [hugo new](/commands/hugo_new/) - Create new content - diff --git a/content/en/commands/hugo_new_theme.md b/content/en/commands/hugo_new_theme.md index 140660077..7a7e0407b 100644 --- a/content/en/commands/hugo_new_theme.md +++ b/content/en/commands/hugo_new_theme.md @@ -43,4 +43,3 @@ hugo new theme [name] [flags] ### SEE ALSO * [hugo new](/commands/hugo_new/) - Create new content - diff --git a/content/en/commands/hugo_server.md b/content/en/commands/hugo_server.md index d735f449a..4345fbd7a 100644 --- a/content/en/commands/hugo_server.md +++ b/content/en/commands/hugo_server.md @@ -9,7 +9,7 @@ Start the embedded web server ### Synopsis -Hugo provides its own webserver which builds and serves the site. +Hugo provides its own webserver which builds and serves the project. While hugo server is high performance, it is a webserver with limited options. The `hugo server` command will by default write and serve files from disk, but @@ -17,8 +17,8 @@ you can render to memory by using the `--renderToMemory` flag. This can be faster in some cases, but it will consume more memory. By default hugo will also watch your files for any changes you make and -automatically rebuild the site. It will then live reload any open browser pages -and push the latest content to them. As most Hugo sites are built in a fraction +automatically rebuild the project. It will then live reload any open browser pages +and push the latest content to them. As most Hugo projects are built in a fraction of a second, you will be able to save and see your changes nearly instantly. ``` @@ -53,7 +53,7 @@ hugo server [command] [flags] --noChmod don't sync permission mode of files --noHTTPCache prevent HTTP caching --noTimes don't sync modification time of files - -O, --openBrowser open the site in a browser after server startup + -O, --openBrowser open the project in a browser after server startup --panicOnWarning panic on first WARNING log --poll string set this to a poll interval, e.g --poll 700ms, to use a poll based approach to watch for file system changes -p, --port int port on which the server will listen (default 1313) @@ -93,6 +93,5 @@ hugo server [command] [flags] ### SEE ALSO -* [hugo](/commands/hugo/) - Build your site +* [hugo](/commands/hugo/) - Build your project * [hugo server trust](/commands/hugo_server_trust/) - Install the local CA in the system trust store - diff --git a/content/en/commands/hugo_server_trust.md b/content/en/commands/hugo_server_trust.md index 22ca2491e..86498385e 100644 --- a/content/en/commands/hugo_server_trust.md +++ b/content/en/commands/hugo_server_trust.md @@ -38,4 +38,3 @@ hugo server trust [flags] [args] ### SEE ALSO * [hugo server](/commands/hugo_server/) - Start the embedded web server - diff --git a/content/en/commands/hugo_version.md b/content/en/commands/hugo_version.md index 14cc92a00..e71abdc28 100644 --- a/content/en/commands/hugo_version.md +++ b/content/en/commands/hugo_version.md @@ -40,5 +40,4 @@ hugo version [flags] [args] ### SEE ALSO -* [hugo](/commands/hugo/) - Build your site - +* [hugo](/commands/hugo/) - Build your project diff --git a/content/en/configuration/all.md b/content/en/configuration/all.md index fe8e3248d..cff51a2ae 100644 --- a/content/en/configuration/all.md +++ b/content/en/configuration/all.md @@ -58,14 +58,14 @@ dataDir : (`string`) The designated directory for data files. Default is `data`. {{% module-mounts-note %}} defaultContentLanguage -: (`string`) The projects's default content language, conforming to the syntax described in [RFC 5646][]. This value must match one of the defined [language keys][]. Default is `en`. +: (`string`) The projects's [default language](g), conforming to the syntax described in [RFC 5646][]. defaultContentLanguageInSubdir : (`bool`) Whether to publish the default content language to a subdirectory matching the [`defaultContentLanguage`][]. Default is `false`. defaultContentRole : {{< new-in 0.153.0 />}} -: (`string`) The project's default content [role](g). Default is `guest`. +: (`string`) The project's [default role](g). defaultContentRoleInSubdir : {{< new-in 0.153.0 />}} @@ -73,7 +73,7 @@ defaultContentRoleInSubdir defaultContentVersion : {{< new-in 0.153.0 />}} -: (`string`) The project's default content version. Default is `v1.0.0`. +: (`string`) The project's [default version](g). defaultContentVersionInSubdir : {{< new-in 0.153.0 />}} @@ -94,7 +94,7 @@ disableDefaultLanguageRedirect disableDefaultSiteRedirect : {{< new-in 0.154.5 />}} -: (bool) Whether to disable generation of the alias redirect to the [default site](g). When [`defaultContentLanguageInSubdir`][], [`defaultContentRoleInSubdir`][], or [`defaultContentVersionInSubdir`][] is `true`, this prevents the root directory from redirecting to the default site's subdirectory. Conversely, when these are `false`, it prevents the subdirectories from redirecting back to the root. The default site is the site with the default content language, version, and role. Default is `false`. +: (bool) Whether to disable generation of the alias redirect to the [default site](g). When [`defaultContentLanguageInSubdir`][], [`defaultContentRoleInSubdir`][], or [`defaultContentVersionInSubdir`][] is `true`, this prevents the root directory from redirecting to the default site's subdirectory. Conversely, when these are `false`, it prevents the subdirectories from redirecting back to the root. Default is `false`. disableHugoGeneratorInject : (`bool`) Whether to disable injection of a `` tag into the home page. Default is `false`. @@ -124,7 +124,7 @@ enableRobotsTXT : (`bool`) Whether to enable generation of a `robots.txt` file. Default is `false`. environment -: (`string`) The build environment. Default is `production` when running `hugo` and `development` when running `hugo server`. +: (`string`) The build environment. Default is `production` when running `hugo build` and `development` when running `hugo server`. frontmatter : See [configure front matter][]. @@ -253,7 +253,7 @@ removePathAccents : (`bool`) Whether to remove [non-spacing marks][] from [composite characters][] in content paths. Default is `false`. renderSegments -: (`[]string`) A slice of [segments](g) to render. If omitted, all segments are rendered. This option is typically set via a command-line flag, such as `hugo --renderSegments segment1,segment2`. The provided segment names must correspond to those defined in the [`segments`][] configuration. +: (`[]string`) A slice of [segments](g) to render. If omitted, all segments are rendered. This option is typically set via a command-line flag, such as `hugo build --renderSegments segment1,segment2`. The provided segment names must correspond to those defined in the [`segments`][] configuration. resourceDir : (`string`) The designated directory for caching output from [asset pipelines](g). Default is `resources`. @@ -421,7 +421,6 @@ Some configuration settings, such as menus and custom parameters, can be defined [embedded Open Graph template]: <{{% eturl opengraph %}}> [embedded RSS template]: <{{% eturl rss %}}> [IANA Time Zone Database]: https://en.wikipedia.org/wiki/List_of_tz_database_time_zones -[language keys]: /configuration/languages/#language-keys [module mounts]: /configuration/module/#mounts [non-spacing marks]: https://www.compart.com/en/unicode/category/Mn [os.UserCacheDir]: https://pkg.go.dev/os#UserCacheDir diff --git a/content/en/configuration/build.md b/content/en/configuration/build.md index 1354f0860..77432cf1a 100644 --- a/content/en/configuration/build.md +++ b/content/en/configuration/build.md @@ -78,6 +78,6 @@ disableClasses > > Built for speed, there may be "false positive" detections (e.g., HTML elements that are not HTML elements) while parsing the published site. These "false positives" are infrequent and inconsequential. -Due to the nature of partial server builds, new HTML entities are added while the server is running, but old values will not be removed until you restart the server or run a regular `hugo` build. +Due to the nature of partial server builds, new HTML entities are added while the server is running, but old values will not be removed until you restart the server or run `hugo build`. [`config/production`]: /configuration/introduction/#configuration-directory diff --git a/content/en/configuration/caches.md b/content/en/configuration/caches.md index 15783a7af..fb8ec3ad1 100644 --- a/content/en/configuration/caches.md +++ b/content/en/configuration/caches.md @@ -46,13 +46,13 @@ maxAge : (`string`) The designated cache directory. See [details](/configuration/all/#cachedir). `:project` -: (`string`) The base directory name of the current Hugo project. This ensures isolated file caches for each project, preventing the `hugo --gc` command from affecting other projects on the same machine. +: (`string`) The base directory name of the current Hugo project. This ensures isolated file caches for each project, preventing the `hugo build --gc` command from affecting other projects on the same machine. `:resourceDir` : (`string`) The designated directory for caching output from [asset pipelines](g). See [details](/configuration/all/#resourcedir). ## Garbage collection -As you modify your site or change your configuration, cached files from previous builds may remain on disk, consuming unnecessary space. Use the `hugo --gc` command to remove these expired or unused entries from the file cache. +As you modify your site or change your configuration, cached files from previous builds may remain on disk, consuming unnecessary space. Use the `hugo build --gc` command to remove these expired or unused entries from the file cache. [`resources.GetRemote`]: /functions/resources/getremote/ diff --git a/content/en/configuration/cascade.md b/content/en/configuration/cascade.md index 7b6ccd933..5616314a8 100644 --- a/content/en/configuration/cascade.md +++ b/content/en/configuration/cascade.md @@ -21,9 +21,7 @@ color = 'red' ## Target The `target`[^1] keyword allows you to target specific pages or [environments](g). For example, to cascade a "color" parameter to pages within the "articles" section, including the "articles" section page itself: diff --git a/content/en/configuration/front-matter.md b/content/en/configuration/front-matter.md index edffd302d..e348f8578 100644 --- a/content/en/configuration/front-matter.md +++ b/content/en/configuration/front-matter.md @@ -76,16 +76,16 @@ Hugo provides the following [tokens](g) to help you configure your front matter: Within the `YYYY-MM-DD-HH-MM-SS` format, the date and time values may be separated by any character including a space (e.g., `2025-02-01T14-30-00`). - Hugo resolves the extracted date to the [`timeZone`] defined in your site configuration, falling back to the system time zone. After extracting the date, Hugo uses the remaining part of the file name to generate the page's [`slug`], but only if you haven't already specified a slug in the page's front matter. + Hugo resolves the extracted date to the [`timeZone`] defined in your project configuration, falling back to the system time zone. After extracting the date, Hugo uses the remaining part of the file name to generate the page's [`slug`], but only if you haven't already specified a slug in the page's front matter. For example, if you name your file `2025-02-01-article.md`, Hugo will set the date to `2025-02-01` and the slug to `article`. `:git` -: The Git author date for the file's last revision. To enable access to the Git author date, set [`enableGitInfo`] to `true`, or use the `--enableGitInfo` flag when building your site. +: The Git author date for the file's last revision. To enable access to the Git author date, set [`enableGitInfo`] to `true`, or use the `--enableGitInfo` flag when building your project. ## Example -Consider this site configuration: +Consider this project configuration: {{< code-toggle file=hugo >}} [frontmatter] diff --git a/content/en/configuration/introduction.md b/content/en/configuration/introduction.md index c1f94ae8d..f4a60884c 100644 --- a/content/en/configuration/introduction.md +++ b/content/en/configuration/introduction.md @@ -23,7 +23,7 @@ Only define settings that deviate from the defaults. A smaller configuration fil ## Configuration file -Create a site configuration file in the root of your project directory, naming it `hugo.toml`, `hugo.yaml`, or `hugo.json`, with that order of precedence. +Create a project configuration file in the root of your project directory, naming it `hugo.toml`, `hugo.yaml`, or `hugo.json`, with that order of precedence. ```text my-project/ @@ -31,7 +31,7 @@ my-project/ ``` > [!note] -> For versions v0.109.0 and earlier, the site configuration file was named `config`. While you can still use this name, it's recommended to switch to the newer naming convention, `hugo`. +> For versions v0.109.0 and earlier, the project configuration file was named `config`. While you can still use this name, it's recommended to switch to the newer naming convention, `hugo`. A simple example: @@ -46,16 +46,16 @@ email = 'info@example.org' phone = '+1 202-555-1212' {{< /code-toggle >}} -To use a different configuration file when building your site, use the `--config` flag: +To use a different configuration file when building your project, use the `--config` flag: ```sh -hugo --config other.toml +hugo build --config other.toml ``` Combine two or more configuration files, with left-to-right precedence: ```sh -hugo --config a.toml,b.yaml,c.json +hugo build --config a.toml,b.yaml,c.json ``` > [!note] @@ -63,7 +63,7 @@ hugo --config a.toml,b.yaml,c.json ## Configuration directory -Instead of a single site configuration file, split your configuration by [environment](g), root configuration key, and language. For example: +Instead of a single project configuration file, split your configuration by [environment](g), root configuration key, and language. For example: ```text my-project/ @@ -129,9 +129,9 @@ my-project/ └── params.toml ``` -Considering the structure above, when running `hugo --environment staging`, Hugo will use every setting from `config/_default` and merge `staging`'s on top of those. +Considering the structure above, when running `hugo build --environment staging`, Hugo will use every setting from `config/_default` and merge `staging`'s on top of those. -Let's take an example to understand this better. Let's say you are using Google Analytics for your website. This requires you to specify a [Google tag ID] in your site configuration: +Let's take an example to understand this better. Let's say you are using Google Analytics for your website. This requires you to specify a [Google tag ID] in your project configuration: {{< code-toggle file=hugo >}} [services.googleAnalytics] @@ -159,7 +159,7 @@ To satisfy these requirements, configure your site as follows: {{< /code-toggle >}} - You do not need to include other parameters in this file. Include only those parameters that are specific to your production environment. Hugo will merge these parameters with the default configuration. - - By default, Hugo sets its `environment` to `production` when running `hugo`. The analytics code will use the `G-PPPPPPPPP` tag ID. + - By default, Hugo sets its `environment` to `production` when running `hugo build`. The analytics code will use the `G-PPPPPPPPP` tag ID. 1. `config/staging/hugo.toml` @@ -171,7 +171,7 @@ To satisfy these requirements, configure your site as follows: {{< /code-toggle >}} - You do not need to include other parameters in this file. Include only those parameters that are specific to your staging environment. Hugo will merge these parameters with the default configuration. - - To build your staging site, run `hugo --environment staging`. The analytics code will use the `G-SSSSSSSSS` tag ID. + - To build your staging site, run `hugo build --environment staging`. The analytics code will use the `G-SSSSSSSSS` tag ID. ## Merge configuration settings @@ -253,14 +253,14 @@ HUGO_FILE_LOG_FORMAT : (`string`) A format string for the file path, line number, and column number displayed when reporting errors, or when calling the `Position` method from a shortcode or Markdown render hook. Valid tokens are `:file`, `:line`, and `:col`. Default is `:file::line::col`. HUGO_MEMORYLIMIT -: (`int`) The maximum amount of system memory, in gigabytes, that Hugo can use while rendering your site. Default is 25% of total system memory. Note that `HUGO_MEMORYLIMIT` is a "best effort" setting. Don't expect Hugo to build a million pages with only 1 GB of memory. You can get more information about how this behaves during the build by building with `hugo --logLevel info` and look for the `dynacache` label. +: (`int`) The maximum amount of system memory, in gigabytes, that Hugo can use while rendering your site. Default is 25% of total system memory. Note that `HUGO_MEMORYLIMIT` is a "best effort" setting. Don't expect Hugo to build a million pages with only 1 GB of memory. You can get more information about how this behaves during the build by running `hugo build --logLevel info` and look for the `dynacache` label. HUGO_NUMWORKERMULTIPLIER : (`int`) The number of workers used in parallel processing. Default is the number of logical CPUs. ## Current configuration -Display the complete site configuration with: +Display the complete project configuration with: ```sh hugo config diff --git a/content/en/configuration/languages.md b/content/en/configuration/languages.md index f9f81e1ea..0ad9d44c6 100644 --- a/content/en/configuration/languages.md +++ b/content/en/configuration/languages.md @@ -56,7 +56,7 @@ languageCode Access this value from a template using the [`Language.LanguageCode`][] method on a `Site` or `Page` object. languageDirection -: (`string`) The language direction, either left-to-right (`ltr`) or right-to-left (`rtl`). Use this value in your templates with the global [`dir`][] HTML attribute. Access this value from a template using the [`Language.LanguageDirection`][] method on a `Site` or `Page` object. +: (`string`) The language direction, either left-to-right (`ltr`) or right-to-left (`rtl`). Use this value in your templates with the global [`dir`][] HTML attribute. Access this value from a template using the [`Language.LanguageDirection`][] method on a `Site` or `Page` object. Default is `ltr`. languageName : (`string`) The language name, typically used when rendering a language switcher. Access this value from a template using the [`Language.LanguageName`][] method on a `Site` or `Page` object. @@ -67,6 +67,10 @@ title weight : (`int`) The language [weight](g). When set to a non-zero value, this is the primary sort criteria for this language. Access this value from a template using the [`Language.Weight`][] method on a `Site` or `Page` object. +## Sort order + +Hugo sorts languages by weight in ascending order, then lexicographically in ascending order. This affects build order and complement selection. + ## Localized settings Some configuration settings can be defined separately for each language. For example: @@ -88,7 +92,7 @@ The following configuration keys can be defined separately for each language: {{< per-lang-config-keys >}} -Any key not defined in a `languages` object will fall back to the global value in the root of the site configuration. +Any key not defined in a `languages` object will fall back to the global value in the root of your project configuration. ## Language keys diff --git a/content/en/configuration/markup.md b/content/en/configuration/markup.md index 31c8de505..0829f9db5 100644 --- a/content/en/configuration/markup.md +++ b/content/en/configuration/markup.md @@ -18,7 +18,7 @@ defaultMarkdownHandler = 'goldmark' Files with ending with `.md`, `.mdown`, or `.markdown` are processed as Markdown, unless you've explicitly set a different format using the `markup` field in your front matter. -To use a different renderer for Markdown files, specify one of `asciidocext`, `org`, `pandoc`, or `rst` in your site configuration. +To use a different renderer for Markdown files, specify one of `asciidocext`, `org`, `pandoc`, or `rst` in your project configuration. `defaultMarkdownHandler`|Renderer :--|:-- @@ -58,8 +58,6 @@ Extension|Documentation|Enabled #### Extras -{{< new-in 0.126.0 />}} - Enable [deleted text], [inserted text], [mark text], [subscript], and [superscript] elements in Markdown. Element|Markdown|Rendered @@ -257,7 +255,7 @@ workingFolderCurrent Follow the steps below to enable syntax highlighting. Step 1 -: Set the `source-highlighter` attribute in your site configuration. For example: +: Set the `source-highlighter` attribute in your project configuration. For example: {{< code-toggle file=hugo >}} [markup.asciidocExt.attributes] @@ -300,7 +298,7 @@ Step 4 ### Troubleshooting -Run `hugo --logLevel debug` to examine Hugo's call to the Asciidoctor executable: +Run `hugo build --logLevel debug` to examine Hugo's call to the Asciidoctor executable: ```txt INFO 2019/12/22 09:08:48 Rendering book-as-pdf.adoc with C:\Ruby26-x64\bin\asciidoctor.bat using asciidoc args [--no-header-footer -r asciidoctor-html5s -b html5s -r asciidoctor-diagram --base-dir D:\prototypes\hugo_asciidoc_ddd\docs -a outdir=D:\prototypes\hugo_asciidoc_ddd\build -] ... diff --git a/content/en/configuration/menus.md b/content/en/configuration/menus.md index 6b27e966b..6eae4f268 100644 --- a/content/en/configuration/menus.md +++ b/content/en/configuration/menus.md @@ -12,10 +12,10 @@ keywords: [] There are three ways to define menu entries: 1. [Automatically] -1. [In front matter] -1. In site configuration +1. In [front matter] +1. In your project configuration -This page covers the site configuration method. +This page covers the project configuration method. ## Example @@ -132,6 +132,6 @@ rel = 'external' [`Menus`]: /methods/site/menus/ [Automatically]: /content-management/menus/#define-automatically -[In front matter]: /content-management/menus/#define-in-front-matter +[front matter]: /content-management/menus/#define-in-front-matter [menu templates]: /templates/menu/ [menus]: /content-management/menus/ diff --git a/content/en/configuration/output-formats.md b/content/en/configuration/output-formats.md index bf61b3d2e..f2a8e2da7 100644 --- a/content/en/configuration/output-formats.md +++ b/content/en/configuration/output-formats.md @@ -53,7 +53,7 @@ notAlternative : (`bool`) Whether to exclude this output format from the values returned by the [`AlternativeOutputFormats`][] method on a `Page` object. Default is `false`. noUgly -: (`bool`) Whether to disable ugly URLs for this output format when [`uglyURLs`][] are enabled in your site configuration. Default is `false`. +: (`bool`) Whether to disable ugly URLs for this output format when [`uglyURLs`][] are enabled in your project configuration. Default is `false`. path : (`string`) The first segment of the publication path for this output format. This path segment is relative to the root of your [`publishDir`][]. If omitted, Hugo will use the file's original content path for publishing. @@ -62,7 +62,7 @@ permalinkable : (`bool`) Whether to return the rendering output format rather than the main output format when invoking the [`Permalink`][] and [`RelPermalink`][] methods on a `Page` object. Along with [`isHTML`](#ishtml), this must be `true` to create [alias redirects][]. Enabled by default for the `html` and `amp` output formats. Default is `false`. protocol -: (`string`) The protocol (scheme) of the URL for this output format. For example, `https://` or `webcal://`. Default is the scheme of the [`baseURL`][] parameter in your site configuration, typically `https://`. +: (`string`) The protocol (scheme) of the URL for this output format. For example, `https://` or `webcal://`. Default is the scheme of the [`baseURL`][] parameter in your project configuration, typically `https://`. rel : (`string`) The relationship of the output format to the current page. Hugo uses this property to determine the [canonical output format](g) of the current page. For the predefined `html` output format, the default value is `canonical`; for all other predefined output formats, the default value is `alternate`. @@ -71,7 +71,7 @@ root : (`bool`) Whether to publish files to the root of the publish directory. Default is `false`. ugly -: (`bool`) Whether to enable uglyURLs for this output format when `uglyURLs` is `false` in your site configuration. Default is `false`. +: (`bool`) Whether to enable uglyURLs for this output format when `uglyURLs` is `false` in your project configuration. Default is `false`. weight : (`int`) When set to a non-zero value, Hugo uses the `weight` as the first criteria when sorting output formats, falling back to the name of the output format. Lighter items float to the top, while heavier items sink to the bottom. Hugo renders output formats sequentially based on the sort order. Default is `0`, except for the `html` output format, which has a default weight of `10`. @@ -138,7 +138,7 @@ Step 4 ## List output formats -To access output formats, each `Page` object provides two methods: [`OutputFormats`][] (for all formats, including the current one) and [`AlternativeOutputFormats`][]. Use `AlternativeOutputFormats` to create a link `rel` list within your site's `head` element, as shown below: +To access output formats, each `Page` object provides two methods: [`OutputFormats`][] (for all formats, including the current one) and [`AlternativeOutputFormats`][]. Use `AlternativeOutputFormats` to create a link `rel` list within a `head` element, as shown below: ```go-html-template {{ range .AlternativeOutputFormats }} diff --git a/content/en/configuration/outputs.md b/content/en/configuration/outputs.md index 9a83cb6e9..ba23f9ee8 100644 --- a/content/en/configuration/outputs.md +++ b/content/en/configuration/outputs.md @@ -41,7 +41,7 @@ title = 'Example' outputs = ['json'] {{< /code-toggle >}} -In its default configuration, Hugo will render both the `html` and `json` output formats for this page. The `outputs` field appends to, rather than replaces, the site's configured outputs. +In its default configuration, Hugo will render both the `html` and `json` output formats for this page. The `outputs` field appends to, rather than replaces, the project's configured outputs. [`Permalink`]: /methods/page/permalink/ [`RelPermalink`]: /methods/page/relpermalink/ diff --git a/content/en/configuration/page.md b/content/en/configuration/page.md index 81169e546..9012c928b 100644 --- a/content/en/configuration/page.md +++ b/content/en/configuration/page.md @@ -15,7 +15,7 @@ Hugo uses the default sort order to determine the _next_ and _previous_ page rel - [`Next`](/methods/page/next/) and [`Prev`](/methods/page/prev/) - [`NextInSection`](/methods/page/nextinsection/) and [`PrevInSection`](/methods/page/previnsection/) -This is based on this default site configuration: +This is based on this default project configuration: {{< code-toggle config=page />}} diff --git a/content/en/configuration/permalinks.md b/content/en/configuration/permalinks.md index 0810624a6..cd1c38083 100644 --- a/content/en/configuration/permalinks.md +++ b/content/en/configuration/permalinks.md @@ -97,7 +97,7 @@ content/ └── _index.md ``` -And this site configuration: +And this project configuration: {{< code-toggle file=hugo >}} defaultContentLanguage = 'en' diff --git a/content/en/configuration/related-content.md b/content/en/configuration/related-content.md index 967c72a9a..de8b33be4 100644 --- a/content/en/configuration/related-content.md +++ b/content/en/configuration/related-content.md @@ -9,7 +9,7 @@ keywords: [] > [!note] > To understand Hugo's related content identification, please refer to the [related content] page. -Hugo provides a sensible default configuration for identifying related content, but you can customize it in your site configuration, either globally or per language. +Hugo provides a sensible default configuration for identifying related content, but you can customize it in your project configuration, either globally or per language. ## Default configuration @@ -18,7 +18,7 @@ This is the default configuration: {{< code-toggle config=related />}} > [!note] -> Adding a `related` section to your site configuration requires you to provide a full configuration. You cannot override individual default values without specifying all related settings. +> Adding a `related` section to your project configuration requires you to provide a full configuration. You cannot override individual default values without specifying all related settings. ## Top-level options diff --git a/content/en/configuration/roles.md b/content/en/configuration/roles.md index 9c5bfe62c..e5db3dcee 100644 --- a/content/en/configuration/roles.md +++ b/content/en/configuration/roles.md @@ -12,7 +12,20 @@ This is the default configuration: {{< code-toggle config=roles />}} -To define "guest" and "member" roles: +## Settings + +Use the following setting to define how Hugo orders roles. + +weight +: (`int`) The role [weight](g). + +## Sort order + +Hugo sorts roles by weight in ascending order, then lexicographically in ascending order. This affects build order and complement selection. + +## Example + +The following configuration demonstrates how to define multiple roles with specific weights. {{< code-toggle >}} [roles.guest] @@ -20,5 +33,3 @@ weight = 20 [roles.member] weight = 10 {{< /code-toggle >}} - -Roles are sorted by their [weight](g) in descending order, then by their name in descending order. This affects build order and complement selection. diff --git a/content/en/configuration/security.md b/content/en/configuration/security.md index f9eb91bd9..54342ad51 100644 --- a/content/en/configuration/security.md +++ b/content/en/configuration/security.md @@ -36,7 +36,7 @@ http.urls > [!note] > Setting an allowlist to the string `none` will completely disable the associated feature. -You can also override the site configuration with environment variables. For example, to block `resources.GetRemote` from accessing any URL: +You can also override your project configuration with environment variables. For example, to block `resources.GetRemote` from accessing any URL: ```txt export HUGO_SECURITY_HTTP_URLS=none diff --git a/content/en/configuration/segments.md b/content/en/configuration/segments.md index a5e3f1c2a..77caa567e 100644 --- a/content/en/configuration/segments.md +++ b/content/en/configuration/segments.md @@ -62,14 +62,14 @@ Place broad filters, such as those for language or output format, in the exclude Render specific segments using the [`renderSegments`] configuration or the `--renderSegments` flag: -```bash -hugo --renderSegments segment1 +```sh +hugo build --renderSegments segment1 ``` You can configure multiple segments and use a comma-separated list with `--renderSegments` to render them all. -```bash -hugo --renderSegments segment1,segment2 +```sh +hugo build --renderSegments segment1,segment2 ``` [`renderSegments`]: /configuration/all/#rendersegments diff --git a/content/en/configuration/taxonomies.md b/content/en/configuration/taxonomies.md index fed1d4c5e..5da0f7f4c 100644 --- a/content/en/configuration/taxonomies.md +++ b/content/en/configuration/taxonomies.md @@ -56,7 +56,7 @@ taxonomies: tag: tags {{< /code-toggle >}} -To disable the taxonomy system, use the [`disableKinds`] setting in the root of your site configuration to disable the `taxonomy` and `term` page [kinds](g). +To disable the taxonomy system, use the [`disableKinds`] setting in the root of your project configuration to disable the `taxonomy` and `term` page [kinds](g). {{< code-toggle file=hugo >}} disableKinds = ['taxonomy','term'] diff --git a/content/en/configuration/versions.md b/content/en/configuration/versions.md index e6902b643..7c0e91e59 100644 --- a/content/en/configuration/versions.md +++ b/content/en/configuration/versions.md @@ -12,15 +12,26 @@ This is the default configuration: {{< code-toggle config=versions />}} -To define "v1.0.0" and "v2.0.0" versions: +## Settings + +Use the following setting to define how Hugo orders versions. + +weight +: (`int`) The language [weight](g). + +## Sort order + +Hugo sorts versions by weight in ascending order, then by their [semantic version][] in descending order. This affects build order and complement selection. + +## Example + +The following configuration demonstrates how to define multiple versions with specific weights. {{< code-toggle >}} [versions."v1.0.0"] -weight = 0 +weight = 20 [versions."v2.0.0"] -weight = 0 +weight = 10 {{< /code-toggle >}} -Versions are sorted by their [weight](g) in ascending order, then by their [semantic version] in descending order. This affects build order and complement selection. - [semantic version]: https://semver.org/ diff --git a/content/en/content-management/comments.md b/content/en/content-management/comments.md index f4ab7d8be..ce7f43841 100644 --- a/content/en/content-management/comments.md +++ b/content/en/content-management/comments.md @@ -16,7 +16,7 @@ Hugo comes with all the code you need to load Disqus into your templates. Before ### Configure Disqus -Disqus comments require you set a single value in your [site's configuration file][configuration] like so: +Disqus comments require you set a single value in your [project configuration][configuration]: {{< code-toggle file=hugo >}} [services.disqus] diff --git a/content/en/content-management/content-adapters.md b/content/en/content-management/content-adapters.md index f586311b3..0af08d732 100644 --- a/content/en/content-management/content-adapters.md +++ b/content/en/content-management/content-adapters.md @@ -1,12 +1,10 @@ --- title: Content adapters -description: Create content adapters to dynamically add content when building your site. +description: Create content adapters to dynamically add content when building your project. categories: [] keywords: [] --- -{{< new-in 0.126.0 />}} - ## Overview 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. @@ -120,7 +118,7 @@ For more fine-grained control, define a `sites.matrix` in front matter or in a c ### EnableAllDimensions -By default, Hugo executes the content adapter only once for the first matching site in the [sites matrix](g). Use this method to expand execution to every possible combination of language, role, and version. +By default, Hugo executes the content adapter only once for the first matching site in the [sites matrix](g). Use this method to expand execution to every possible combination of language, version, and role. For more fine-grained control, define a `sites.matrix` in front matter or in a content mount. @@ -284,7 +282,7 @@ With multilingual sites you can: ### Translations by file name -With this site configuration: +With this project configuration: {{< code-toggle file=hugo >}} [languages.en] @@ -307,7 +305,7 @@ content/ ### Translations by content directory -With this site configuration: +With this project configuration: {{< code-toggle file=hugo >}} [languages.en] @@ -347,7 +345,7 @@ content/ If the content adapter also creates `books/the-hunchback-of-notre-dame`, the content of the published page is indeterminate. You can not define the processing order. -To detect page collisions, use the `--printPathWarnings` flag when building your site. +To detect page collisions, use the `--printPathWarnings` flag when building your project. [content formats]: /content-management/formats/#classification [front matter field]: /content-management/front-matter/#fields diff --git a/content/en/content-management/formats.md b/content/en/content-management/formats.md index 65fb3d04d..0f9fe7f1c 100644 --- a/content/en/content-management/formats.md +++ b/content/en/content-management/formats.md @@ -34,7 +34,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][configure goldmark]. +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 [project configuration][configure goldmark]. Hugo provides custom Markdown features including: @@ -77,7 +77,7 @@ Create your content in the [Emacs Org Mode] format preceded by front matter. You 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 render the AsciiDoc content format. -You can configure the AsciiDoc renderer in your [site configuration][configure asciidoc]. +You can configure the AsciiDoc renderer in your [project configuration][configure asciidoc]. In its default configuration, Hugo passes these CLI flags when calling the Asciidoctor executable: @@ -85,10 +85,10 @@ In its default configuration, Hugo passes these CLI flags when calling the Ascii --no-header-footer ``` -The CLI flags passed to the Asciidoctor executable depend on configuration. You may inspect the flags when building your site: +The CLI flags passed to the Asciidoctor executable depend on configuration. You may inspect the flags when building your project: ```text -hugo --logLevel info +hugo build --logLevel info ``` [AsciiDoc]: https://asciidoc.org/ diff --git a/content/en/content-management/front-matter.md b/content/en/content-management/front-matter.md index 9b2a434b8..c734789df 100644 --- a/content/en/content-management/front-matter.md +++ b/content/en/content-management/front-matter.md @@ -178,7 +178,7 @@ The embedded templates will skip a parameter if not provided in front matter, bu ## Taxonomies -Classify content by adding taxonomy terms to front matter. For example, with this site configuration: +Classify content by adding taxonomy terms to front matter. For example, with this project configuration: {{< code-toggle file=hugo >}} [taxonomies] @@ -240,9 +240,7 @@ From Hugo 0.153.0, you can also set the [sites](#sites) front matter as cascade ### Target The `target`[^1] keyword allows you to target specific pages or [environments](g). For example, to cascade a "color" parameter from the home page only to pages within the "articles" section, including the "articles" section page itself: @@ -295,7 +293,7 @@ kind = 'page' {{< /code-toggle >}} > [!note] -> For multilingual sites, defining cascade values in your site configuration is often more efficient. This avoids repeating the same cascade values on the home, section, taxonomy, or term page for each language. See [details](/configuration/cascade/). +> For multilingual sites, defining cascade values in your project configuration is often more efficient. This avoids repeating the same cascade values on the home, section, taxonomy, or term page for each language. See [details](/configuration/cascade/). > > If you choose to define cascade values in front matter for a multilingual site, you must create a corresponding home, section, taxonomy, or term page for every language. @@ -330,10 +328,10 @@ When populating a date field, whether a [custom page parameter](#parameters) or {{% include "/_common/parsable-date-time-strings.md" %}} -To override the default time zone, set the [`timeZone`](/configuration/all/#timezone) in your site configuration. The order of precedence for determining the time zone is: +To override the default time zone, set the [`timeZone`](/configuration/all/#timezone) in your project configuration. The order of precedence for determining the time zone is: 1. The time zone offset in the date/time string -1. The time zone specified in your site configuration +1. The time zone specified in your project configuration 1. The `Etc/UTC` time zone [`aliases`]: /methods/page/aliases/ diff --git a/content/en/content-management/image-processing/index.md b/content/en/content-management/image-processing/index.md index fca742048..9df622265 100644 --- a/content/en/content-management/image-processing/index.md +++ b/content/en/content-management/image-processing/index.md @@ -134,9 +134,9 @@ Select a method from the table above for syntax and usage examples. ### Caching -Hugo processes images on demand and returns a new resource object. To ensure subsequent builds remain fast, Hugo caches the results in the directory specified in the [file cache] section of your site configuration. +Hugo processes images on demand and returns a new resource object. To ensure subsequent builds remain fast, Hugo caches the results in the directory specified in the [file cache][] section of your project configuration. -If you host your site with Netlify, include the following in your site configuration to persist the image cache between builds: +If you host your site with Netlify, include the following in your project configuration to persist the image cache between builds: ```toml [caches] @@ -149,7 +149,7 @@ If you host your site with Netlify, include the following in your site configura If you change image processing methods, or rename/remove images, the cache will eventually contain unused files. To remove them and reclaim disk space, run Hugo's garbage collection: ```text -hugo --gc +hugo build --gc ``` ### Resource usage @@ -175,3 +175,4 @@ See [configure imaging](/configuration/imaging). [`RelPermalink`]: /methods/resource/relpermalink/ [`Resize`]: /methods/resource/resize/ [`Width`]: /methods/resource/width/ +[file cache]: /configuration/caches/ diff --git a/content/en/content-management/markdown-attributes.md b/content/en/content-management/markdown-attributes.md index a27edc012..42e7bcf94 100644 --- a/content/en/content-management/markdown-attributes.md +++ b/content/en/content-management/markdown-attributes.md @@ -38,7 +38,7 @@ With `class` and `id` attributes, whether you use long-form or short-form notati ## Block elements -Update your site configuration to enable Markdown attributes for block-level elements. +Update your project configuration to enable Markdown attributes for block-level elements. {{< code-toggle file=hugo >}} [markup.goldmark.parser.attribute] @@ -103,7 +103,7 @@ For example: ````text ## Section 1 {class=foo} -```bash {class=foo linenos=inline} +```sh {class=foo linenos=inline} declare a=1 echo "${a}" ``` diff --git a/content/en/content-management/mathematics.md b/content/en/content-management/mathematics.md index 5414a00f9..6b86cac1c 100644 --- a/content/en/content-management/mathematics.md +++ b/content/en/content-management/mathematics.md @@ -35,7 +35,7 @@ Equations and expressions can be displayed inline with other text, or as standal 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. > [!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 with the [`transform.ToMath`][] function while building your site. +> 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 with the [`transform.ToMath`][] function while building your project. > > The first approach is described below. @@ -44,7 +44,7 @@ Whether an equation or expression appears inline, or as a block, depends on the Follow these instructions to include mathematical equations and expressions in your Markdown using LaTeX markup. Step 1 -: Enable and configure the Goldmark [passthrough extension][] in your site configuration. The passthrough extension preserves raw Markdown within delimited snippets of text, including the delimiters themselves. +: Enable and configure the Goldmark [passthrough extension][] in your project configuration. The passthrough extension preserves raw Markdown within delimited snippets of text, including the delimiters themselves. {{< code-toggle file=hugo copy=true >}} [markup.goldmark.extensions.passthrough] @@ -58,7 +58,7 @@ Step 1 math = true {{< /code-toggle >}} - The configuration above enables mathematical rendering on every page unless you set the `math` parameter to `false` in front matter. To enable mathematical rendering as needed, set the `math` parameter to `false` in your site configuration, and set the `math` parameter to `true` in front matter. Use this parameter in your base template as shown in [Step 3][]. + The configuration above enables mathematical rendering on every page unless you set the `math` parameter to `false` in front matter. To enable mathematical rendering as needed, set the `math` parameter to `false` in your project configuration, and set the `math` parameter to `true` in front matter. Use this parameter in your base template as shown in [Step 3][]. > [!note] > The configuration above precludes the use of the `$...$` delimiter pair for inline equations. Although you can add this delimiter pair to the configuration and JavaScript, you must double-escape the `$` symbol when used outside of math contexts to avoid unintended formatting. @@ -99,7 +99,7 @@ Step 2 ``` - The delimiters above must match the delimiters in your site configuration. + The delimiters above must match the delimiters in your project configuration. Step 3 : Conditionally call the _partial_ template from the base template. @@ -114,10 +114,10 @@ Step 3 ``` - The example above loads the _partial_ template if you have set the `math` parameter in front matter to `true`. If you have not set the `math` parameter in front matter, the conditional statement falls back to the `math` parameter in your site configuration. + The example above loads the _partial_ template if you have set the `math` parameter in front matter to `true`. If you have not set the `math` parameter in front matter, the conditional statement falls back to the `math` parameter in your project configuration. Step 4 -: If you set the `math` parameter to `false` in your site configuration, you must set the `math` parameter to `true` in front matter. For example: +: If you set the `math` parameter to `false` in your project configuration, you must set the `math` parameter to `true` in front matter. For example: {{< code-toggle file=content/math-examples.md fm=true >}} title = 'Math examples' @@ -211,7 +211,7 @@ To use KaTeX instead of MathJax, replace the _partial_ template from [Step 2][] ``` -The delimiters above must match the delimiters in your site configuration. +The delimiters above must match the delimiters in your project configuration. ## Chemistry diff --git a/content/en/content-management/menus.md b/content/en/content-management/menus.md index 8ff0597b3..50920eefa 100644 --- a/content/en/content-management/menus.md +++ b/content/en/content-management/menus.md @@ -20,14 +20,14 @@ There are three ways to define menu entries: 1. Automatically 1. In front matter -1. In site configuration +1. In your project configuration > [!note] > Although you can use these methods in combination when defining a menu, the menu will be easier to conceptualize and maintain if you use one method throughout the site. ## Define automatically -To automatically define a menu entry for each top-level [section](g) of your site, enable the section pages menu in your site configuration. +To automatically define a menu entry for each top-level [section](g) of your site, enable the section pages menu in your project configuration. {{< code-toggle file=hugo >}} sectionPagesMenu = "main" @@ -82,7 +82,7 @@ class = 'center' Access the entry with `site.Menus.main` in your templates. See [menu templates] for details. -## Define in site configuration +## Define in project configuration See [configure menus](/configuration/menus/). diff --git a/content/en/content-management/multilingual.md b/content/en/content-management/multilingual.md index 5a5cd2307..ec31204c2 100644 --- a/content/en/content-management/multilingual.md +++ b/content/en/content-management/multilingual.md @@ -253,8 +253,8 @@ See [lang.FormatPercent] for details. Localization of menu entries depends on how you define them: - When you define menu entries [automatically] using the section pages menu, you must use translation tables to localize each entry. -- When you define menu entries [in front matter], they are already localized based on the front matter itself. If the front matter values are insufficient, use translation tables to localize each entry. -- When you define menu entries [in site configuration], you must create language-specific menu entries under each language key. If the names of the menu entries are insufficient, use translation tables to localize each entry. +- When you define menu entries in [front matter], they are already localized based on the front matter itself. If the front matter values are insufficient, use translation tables to localize each entry. +- When you define menu entries in your [project configuration], you must create language-specific menu entries under each language key. If the names of the menu entries are insufficient, use translation tables to localize each entry. ### Create language-specific menu entries @@ -341,9 +341,9 @@ It queries the translation table for the current language using the menu entry's The `identifier` depends on how you define menu entries: - If you define the menu entry [automatically] using the section pages menu, the `identifier` is the page's `.Section`. -- If you define the menu entry [in site configuration] or [in front matter], set the `identifier` property to the desired value. +- If you define the menu entry in your [project configuration] or in [front matter], set the `identifier` property to the desired value. -For example, if you define menu entries in site configuration: +For example, if you define menu entries in project configuration: {{< code-toggle file=hugo >}} [[menus.main]] @@ -379,7 +379,7 @@ For merging of content from other languages (i.e. missing content translations), To track down missing translation strings, run Hugo with the `--printI18nWarnings` flag: ```sh -hugo --printI18nWarnings | grep i18n +hugo build --printI18nWarnings | grep i18n i18n|MISSING_TRANSLATION|en|wordCount ``` @@ -418,12 +418,12 @@ hugo new content content/de/post/test.md [config]: /configuration/ [configuration directory]: /configuration/introduction/#configuration-directory [example menu template]: /templates/menu/#example +[front matter]: /content-management/menus/#define-in-front-matter [i18func]: /functions/lang/translate/ -[in front matter]: /content-management/menus/#define-in-front-matter -[in site configuration]: /content-management/menus/#define-in-site-configuration [lang.FormatAccounting]: /functions/lang/formataccounting/ [lang.FormatCurrency]: /functions/lang/formatcurrency/ [lang.FormatNumber]: /functions/lang/formatnumber/ [lang.FormatNumberCustom]: /functions/lang/formatnumbercustom/ [lang.FormatPercent]: /functions/lang/formatpercent/ [lang.Merge]: /functions/lang/merge/ +[project configuration]: /content-management/menus/#define-in-project-configuration diff --git a/content/en/content-management/organization/index.md b/content/en/content-management/organization/index.md index e1f6d8acd..5762e0d4e 100644 --- a/content/en/content-management/organization/index.md +++ b/content/en/content-management/organization/index.md @@ -61,7 +61,7 @@ Without any additional configuration, the following will automatically work: ## Path breakdown in Hugo -The following demonstrates the relationships between your content organization and the output URL structure for your Hugo website when it renders. These examples assume you are [using pretty URLs][pretty], which is the default behavior for Hugo. The examples also assume a key-value of `baseURL = "https://example.org/"` in your [site's configuration file][config]. +The following demonstrates the relationships between your content organization and the output URL structure for your Hugo website when it renders. These examples assume you are [using pretty URLs][pretty], which is the default behavior for Hugo. The examples also assume a key-value of `baseURL = "https://example.org/"` in your [project configuration][config]. ### Index pages: `_index.md` diff --git a/content/en/content-management/page-resources.md b/content/en/content-management/page-resources.md index c429d8af5..a915b5f74 100644 --- a/content/en/content-management/page-resources.md +++ b/content/en/content-management/page-resources.md @@ -198,7 +198,7 @@ By default, with a multilingual single-host site, Hugo does not duplicate shared > [!note] > This behavior is limited to Markdown content. Shared page resources for other [content formats] are copied into each language bundle. -Consider this site configuration: +Consider this project configuration: {{< code-toggle file=hugo >}} defaultContentLanguage = 'de' @@ -278,7 +278,7 @@ This approach reduces build times, storage requirements, bandwidth consumption, > > You can also configure Hugo to `always` use the embedded link or image render hook, use it only as a `fallback`, or `never` use it. See [details](/configuration/markup/#renderhookslinkuseembedded). -Although duplicating shared page resources is inefficient, you can enable this feature in your site configuration if desired: +Although duplicating shared page resources is inefficient, you can enable this feature in your project configuration if desired: {{< code-toggle file=hugo >}} [markup.goldmark] diff --git a/content/en/content-management/shortcodes.md b/content/en/content-management/shortcodes.md index 59ac4d651..777364423 100644 --- a/content/en/content-management/shortcodes.md +++ b/content/en/content-management/shortcodes.md @@ -42,7 +42,7 @@ An inline shortcode is a _shortcode_ template defined within content. Hugo's security model is based on the premise that template and configuration authors are trusted, but content authors are not. This model enables generation of HTML output safe against code injection. -To conform with this security model, creating _shortcode_ templates within content is disabled by default. If you trust your content authors, you can enable this functionality in your site's configuration: +To conform with this security model, creating _shortcode_ templates within content is disabled by default. If you trust your content authors, you can enable this functionality in your project configuration: {{< code-toggle file=hugo >}} [security] diff --git a/content/en/content-management/summaries.md b/content/en/content-management/summaries.md index 93386eec2..cd9eaa836 100644 --- a/content/en/content-management/summaries.md +++ b/content/en/content-management/summaries.md @@ -84,7 +84,7 @@ This is the second paragraph. ## Automatic summary -If you do not define the summary manually or in front matter, Hugo automatically defines the summary based on the [`summaryLength`] in your site configuration. +If you do not define the summary manually or in front matter, Hugo automatically defines the summary based on the [`summaryLength`] in your project configuration. [`summaryLength`]: /configuration/all/#summarylength diff --git a/content/en/content-management/syntax-highlighting.md b/content/en/content-management/syntax-highlighting.md index 7e87efa49..57735b0ab 100644 --- a/content/en/content-management/syntax-highlighting.md +++ b/content/en/content-management/syntax-highlighting.md @@ -32,10 +32,10 @@ LANG : The language of the code to highlight. Choose from one of the [supported languages]. This value is case-insensitive. OPTIONS -: One or more space-separated or comma-separated key-value pairs wrapped in braces. Set default values for each option in your [site configuration]. The key names are case-insensitive. +: One or more space-separated or comma-separated key-value pairs wrapped in braces. Set default values for each option in your [project configuration]. The key names are case-insensitive. [supported languages]: #languages -[site configuration]: /configuration/markup/#highlight +[project configuration]: /configuration/markup/#highlight For example, with this Markdown: diff --git a/content/en/content-management/urls.md b/content/en/content-management/urls.md index 737d23367..c1b4979e7 100644 --- a/content/en/content-management/urls.md +++ b/content/en/content-management/urls.md @@ -1,6 +1,6 @@ --- title: URL management -description: Control the structure and appearance of URLs through front matter entries and settings in your site configuration. +description: Control the structure and appearance of URLs through front matter entries and settings in your project configuration. categories: [] keywords: [] aliases: [/extras/permalinks/,/extras/aliases/,/extras/urls/,/doc/redirects/,/doc/alias/,/doc/aliases/] @@ -14,7 +14,7 @@ By default, when Hugo renders a page, the resulting URL matches the file path wi content/posts/post-1.md → https://example.org/posts/post-1/ ``` -You can change the structure and appearance of URLs with front matter values and site configuration options. +You can change the structure and appearance of URLs with front matter values and project configuration options. ## Front matter @@ -121,7 +121,7 @@ Use any of these tokens: {{% include "/_common/permalink-tokens.md" %}} -## Site configuration +## Project configuration ### Permalinks @@ -185,7 +185,7 @@ Aliases allow you to redirect old URLs to new URLs. This is essential for preven ### Defining aliases -To add redirects to a page, list the previous paths in the [`aliases`][aliases_field] field in your front matter. Hugo resolves these to [server-relative](g) paths during the build process, accounting for the [`baseURL`][] and [content dimension](g) prefixes such as language, role, or version. +To add redirects to a page, list the previous paths in the [`aliases`][aliases_field] field in your front matter. Hugo resolves these to [server-relative](g) paths during the build process, accounting for the [`baseURL`][] and [content dimension](g) prefixes such as language, version, or role. {{< code-toggle file=content/examples/example-1.en.md fm=true >}} title = 'Example 1' @@ -247,7 +247,7 @@ To implement this, you typically create a single template to generate the necess See the [`Aliases`][aliases_method] method page for a complete example of how to iterate through pages to generate these rules. -If you implement server-side redirects, you should disable the generation of individual HTML files by setting [`disableAliases`][] to `true` in your site configuration. This setting only prevents the generation of the physical HTML files; the `Aliases` method on a `Page` object remains available for use in your configuration templates. +If you implement server-side redirects, you should disable the generation of individual HTML files by setting [`disableAliases`][] to `true` in your project configuration. This setting only prevents the generation of the physical HTML files; the `Aliases` method on a `Page` object remains available for use in your configuration templates. [`baseURL`]: /configuration/all/#baseurl [`disableAliases`]: /configuration/all/#disablealiases diff --git a/content/en/contribute/development.md b/content/en/contribute/development.md index 1269c8509..e19bd304e 100644 --- a/content/en/contribute/development.md +++ b/content/en/contribute/development.md @@ -143,7 +143,7 @@ CGO_ENABLED=1 go install -tags extended github.com/gohugoio/hugo@latest To build and install a specific release: ```sh -CGO_ENABLED=1 go install -tags extended github.com/gohugoio/hugo@v0.155.3 +CGO_ENABLED=1 go install -tags extended github.com/gohugoio/hugo@v0.156.0 ``` To build and install at the latest commit on the master branch: diff --git a/content/en/contribute/documentation.md b/content/en/contribute/documentation.md index 33f1e8a89..2d878b020 100644 --- a/content/en/contribute/documentation.md +++ b/content/en/contribute/documentation.md @@ -192,7 +192,7 @@ Field|Description|Required `params.minversion`|Applicable to the quick start page: the minimum Hugo version required|  `params.permalink`|Reserved for use by the news content adapter|  `params.reference (used in glossary term)`|Applicable to glossary entries: a URL for additional information|  -`params.searchable`|Whether to add the content of this page to the search index. The default value is cascaded down from the site configuration; `true` if the page kind is `page`, and `false` if the page kind is one of `home`, `section`, `taxonomy`, or `term`. Add this field to override the default value.|  +`params.searchable`|Whether to add the content of this page to the search index. The default value is cascaded down from the project configuration; `true` if the page kind is `page`, and `false` if the page kind is one of `home`, `section`, `taxonomy`, or `term`. Add this field to override the default value.|  `params.show_publish_date`|Whether to show the `publishDate` when rendering the page|  `weight`|The page weight|  `aliases`|Previous URLs used to access this page|  @@ -291,9 +291,9 @@ Use this syntax : ``` ```` -### Site configuration +### Project configuration -Use the [code-toggle shortcode](#code-toggle) to include site configuration examples: +Use the [code-toggle shortcode](#code-toggle) to include project configuration examples: ```text {{}} @@ -371,25 +371,25 @@ These shortcodes are commonly used throughout the documentation. Other shortcode ### code-toggle -Use the `code-toggle` shortcode to display examples of site configuration, front matter, or data files. This shortcode takes these arguments: +Use the `code-toggle` shortcode to display examples of project configuration, front matter, or data files. This shortcode takes these arguments: config -: (`string`) The section of `site.Data.docs.config` to render. +: (`string`) The section of `hugo.Data.docs.config` to render. copy : (`bool`) Whether to display a copy-to-clipboard button. Default is `false`. datakey: -: (`string`) The section of `site.Data.docs` to render. +: (`string`) The section of `hugo.Data.docs` to render. file -: (`string`) The file name to display above the rendered code. Omit the file extension for site configuration examples. +: (`string`) The file name to display above the rendered code. Omit the file extension for project configuration examples. fm : (`bool`) Whether to render the code as front matter. Default is `false`. skipHeader -: (`bool`) Whether to omit top-level key(s) when rendering a section of `site.Data.docs.config`. +: (`bool`) Whether to omit top-level key(s) when rendering a section of `hugo.Data.docs.config`. ```text {{}} diff --git a/content/en/functions/collections/IsSet.md b/content/en/functions/collections/IsSet.md index 405aa92af..9a37f355c 100644 --- a/content/en/functions/collections/IsSet.md +++ b/content/en/functions/collections/IsSet.md @@ -11,7 +11,7 @@ params: aliases: [/functions/isset] --- -For example, consider this site configuration: +For example, consider this project configuration: {{< code-toggle file=hugo >}} [params] diff --git a/content/en/functions/collections/Querify.md b/content/en/functions/collections/Querify.md index a91393787..53a30f094 100644 --- a/content/en/functions/collections/Querify.md +++ b/content/en/functions/collections/Querify.md @@ -34,7 +34,7 @@ Hugo renders this to: Link ``` -You can also pass in a map from your site configuration or front matter. For example: +You can also pass in a map from your project configuration or front matter. For example: {{< code-toggle file=content/example.md fm=true >}} title = 'Example' diff --git a/content/en/functions/collections/Sort.md b/content/en/functions/collections/Sort.md index c48610923..9a9ed4ac1 100644 --- a/content/en/functions/collections/Sort.md +++ b/content/en/functions/collections/Sort.md @@ -17,7 +17,7 @@ The `ORDER` may be either `asc` (ascending) or `desc` (descending). The default ## Sort a slice -The examples below assume this site configuration: +The examples below assume this project configuration: {{< code-toggle file=hugo >}} [params] @@ -47,7 +47,7 @@ In the example above, `value` is the `KEY` representing the value of the slice e ## Sort a map -The examples below assume this site configuration: +The examples below assume this project configuration: {{< code-toggle file=hugo >}} [params.authors.a] diff --git a/content/en/functions/collections/Where.md b/content/en/functions/collections/Where.md index a08412621..3123b6a36 100644 --- a/content/en/functions/collections/Where.md +++ b/content/en/functions/collections/Where.md @@ -23,7 +23,7 @@ Hugo will test for equality if you do not provide an `OPERATOR` argument. For ex ```go-html-template {{ $pages := where .Site.RegularPages "Section" "books" }} -{{ $books := where .Site.Data.books "genres" "suspense" }} +{{ $books := where hugo.Data.books "genres" "suspense" }} ``` ## Arguments @@ -264,13 +264,13 @@ Useful for theme authors, avoid hardcoding section names by using the `where` fu {{ $pages := where .Site.RegularPages "Section" "in" .Site.MainSections }} ``` -With this construct, a theme author can instruct users to specify their main sections in the site configuration: +With this construct, a theme author can instruct users to specify their main sections in their project configuration: {{< code-toggle file=hugo >}} mainSections = ['blog','galleries'] {{< /code-toggle >}} -If `mainSections` is not defined in the site configuration, the `MainSections` method returns a slice with one element---the top-level section with the most pages. +If `mainSections` is not defined in your project configuration, the `MainSections` method returns a slice with one element---the top-level section with the most pages. ## Boolean/undefined comparison diff --git a/content/en/functions/css/Sass.md b/content/en/functions/css/Sass.md index 407558c80..4acc706be 100644 --- a/content/en/functions/css/Sass.md +++ b/content/en/functions/css/Sass.md @@ -130,7 +130,7 @@ To use Dart Sass with Hugo on a [CI/CD](g) platform, you typically must modify y There's one key exception where you can skip this step: you have committed your `resources` directory to your repository. This is only possible if: - You have not changed Hugo's default asset cache location. -- You have not set [`useResourceCacheWhen`][] to never in your sites configuration. +- You have not set [`useResourceCacheWhen`][] to never in your project configuration. By committing the `resources` directory, you're providing the pre-built CSS files directly to your CI/CD platform, so it doesn't need to run the Sass compilation itself. diff --git a/content/en/functions/css/TailwindCSS.md b/content/en/functions/css/TailwindCSS.md index e8514679b..f6751a63a 100644 --- a/content/en/functions/css/TailwindCSS.md +++ b/content/en/functions/css/TailwindCSS.md @@ -29,7 +29,7 @@ Step 1 : Install the Tailwind CSS CLI v4.0 or later: ```sh {copy=true} - npm install --save-dev tailwindcss @tailwindcss/cli + npm install --save-dev tailwindcss @tailwindcss/cli @tailwindcss/typography ``` The Tailwind CSS CLI is also available as a [standalone executable]. You must install it outside of your project directory and ensure its path is included in your system's `PATH` environment variable. @@ -37,7 +37,7 @@ Step 1 [standalone executable]: https://github.com/tailwindlabs/tailwindcss/releases/latest Step 2 -: Add this to your site configuration: +: Add this to your project configuration: {{< code-toggle file=hugo copy=true >}} [build] @@ -64,6 +64,7 @@ Step 3 ```css {file="assets/css/main.css" copy=true} @import "tailwindcss"; + @plugin "@tailwindcss/typography"; @source "hugo_stats.json"; ``` diff --git a/content/en/functions/debug/Dump.md b/content/en/functions/debug/Dump.md index df846ac3d..c06a49ad5 100644 --- a/content/en/functions/debug/Dump.md +++ b/content/en/functions/debug/Dump.md @@ -11,7 +11,7 @@ params: --- ```go-html-template -
{{ debug.Dump site.Data.books }}
+
{{ debug.Dump hugo.Data.books }}
``` ```json diff --git a/content/en/functions/debug/Timer.md b/content/en/functions/debug/Timer.md index 4d4b02650..d72b79ed2 100644 --- a/content/en/functions/debug/Timer.md +++ b/content/en/functions/debug/Timer.md @@ -25,7 +25,7 @@ The timer starts when you instantiate it, and stops when you call its `Stop` met Use the `--logLevel info` command line flag when you build the site. ```sh -hugo --logLevel info +hugo build --logLevel info ``` The results are displayed in the console at the end of the build. You can have as many timers as you want and if you don't stop them, they will be stopped at the end of build. diff --git a/content/en/functions/fmt/Erroridf.md b/content/en/functions/fmt/Erroridf.md index 97d628bac..d6af48fd0 100644 --- a/content/en/functions/fmt/Erroridf.md +++ b/content/en/functions/fmt/Erroridf.md @@ -13,7 +13,7 @@ aliases: [/functions/erroridf] {{% include "/_common/functions/fmt/format-string.md" %}} -The `erroridf` function evaluates the format string, then prints the result to the ERROR log and fails the build. Unlike the [`errorf`] function, you may suppress errors logged by the `erroridf` function by adding the message ID to the `ignoreLogs` array in your site configuration. +The `erroridf` function evaluates the format string, then prints the result to the ERROR log and fails the build. Unlike the [`errorf`] function, you may suppress errors logged by the `erroridf` function by adding the message ID to the `ignoreLogs` array in your project configuration. This template code: @@ -25,7 +25,7 @@ Produces this console log: ```text ERROR You should consider fixing this. -You can suppress this error by adding the following to your site configuration: +You can suppress this error by adding the following to your project configuration: ignoreLogs = ['error-42'] ``` diff --git a/content/en/functions/fmt/Warnidf.md b/content/en/functions/fmt/Warnidf.md index 7b68cd88b..21fee2993 100644 --- a/content/en/functions/fmt/Warnidf.md +++ b/content/en/functions/fmt/Warnidf.md @@ -13,7 +13,7 @@ aliases: [/functions/warnidf] {{% include "/_common/functions/fmt/format-string.md" %}} -The `warnidf` function evaluates the format string, then prints the result to the WARNING log. Unlike the [`warnf`] function, you may suppress warnings logged by the `warnidf` function by adding the message ID to the `ignoreLogs` array in your site configuration. +The `warnidf` function evaluates the format string, then prints the result to the WARNING log. Unlike the [`warnf`] function, you may suppress warnings logged by the `warnidf` function by adding the message ID to the `ignoreLogs` array in your project configuration. This template code: @@ -25,7 +25,7 @@ Produces this console log: ```text WARN You should consider fixing this. -You can suppress this warning by adding the following to your site configuration: +You can suppress this warning by adding the following to your project configuration: ignoreLogs = ['warning-42'] ``` diff --git a/content/en/functions/hugo/Data.md b/content/en/functions/hugo/Data.md new file mode 100644 index 000000000..b8f8dbddf --- /dev/null +++ b/content/en/functions/hugo/Data.md @@ -0,0 +1,105 @@ +--- +title: hugo.Data +description: Returns a data structure composed from the files in the data directory. +categories: [] +keywords: [] +params: + functions_and_methods: + returnType: map + signatures: [hugo.Data] +--- + +{{< new-in 0.156.0 />}} + +Use the `hugo.Data` function to access data within the `data` directory, or within any directory [mounted] to the `data` directory. Supported data formats include JSON, TOML, YAML, and XML. + +> [!note] +> Although Hugo can unmarshal CSV files with the [`transform.Unmarshal`] function, do not place CSV files in the `data` directory. You cannot access data within CSV files using this method. + +Consider this `data` directory: + +```text +data/ +├── books/ +│ ├── fiction.yaml +│ └── nonfiction.yaml +├── films.json +├── paintings.xml +└── sculptures.toml +``` + +And these data files: + +```yaml {file="data/books/fiction.yaml"} +- title: The Hunchback of Notre Dame + author: Victor Hugo + isbn: 978-0140443530 +- title: Les Misérables + author: Victor Hugo + isbn: 978-0451419439 +``` + +```yaml {file="data/books/nonfiction.yaml"} +- title: The Ancien Régime and the Revolution + author: Alexis de Tocqueville + isbn: 978-0141441641 +- title: Interpreting the French Revolution + author: François Furet + isbn: 978-0521280495 +``` + +Access the data by [chaining](g) the [identifiers](g): + +```go-html-template +{{ range $category, $books := hugo.Data.books }} +

{{ $category | title }}

+ +{{ end }} +``` + +Hugo renders this to: + +```html +

Fiction

+ +

Nonfiction

+ +``` + +To limit the listing to fiction, and sort by title: + +```go-html-template + +``` + +To find a fiction book by ISBN: + +```go-html-template +{{ range where hugo.Data.books.fiction "isbn" "978-0140443530" }} +
  • {{ .title }} ({{ .author }})
    • +{{ end }} +``` + +In the template examples above, each of the keys is a valid identifier. For example, none of the keys contains a hyphen. To access a key that is not a valid identifier, use the [`index`] function. For example: + +```go-html-template +{{ index hugo.Data.books "historical-fiction" }} +``` + +[`index`]: /functions/collections/indexfunction/ +[`transform.Unmarshal`]: /functions/transform/unmarshal/ +[mounted]: /configuration/module/#mounts diff --git a/content/en/functions/hugo/Environment.md b/content/en/functions/hugo/Environment.md index 551306255..6f69dd3a6 100644 --- a/content/en/functions/hugo/Environment.md +++ b/content/en/functions/hugo/Environment.md @@ -20,7 +20,7 @@ Command line examples: Command|Environment :--|:-- -`hugo`|`production` -`hugo --environment staging`|`staging` +`hugo build`|`production` +`hugo build --environment staging`|`staging` `hugo server`|`development` `hugo server --environment staging`|`staging` diff --git a/content/en/functions/hugo/Generator.md b/content/en/functions/hugo/Generator.md index de3b5d46a..a090152a3 100644 --- a/content/en/functions/hugo/Generator.md +++ b/content/en/functions/hugo/Generator.md @@ -11,5 +11,5 @@ params: --- ```go-html-template -{{ hugo.Generator }} → +{{ hugo.Generator }} → ``` diff --git a/content/en/functions/hugo/IsMultihost.md b/content/en/functions/hugo/IsMultihost.md index a84ae4940..5820c8056 100644 --- a/content/en/functions/hugo/IsMultihost.md +++ b/content/en/functions/hugo/IsMultihost.md @@ -10,7 +10,7 @@ params: signatures: [hugo.IsMultihost] --- -Site configuration: +Project configuration: {{< code-toggle file=hugo >}} defaultContentLanguage = 'de' diff --git a/content/en/functions/hugo/IsMultilingual.md b/content/en/functions/hugo/IsMultilingual.md index d8c73f7d5..30a65909a 100644 --- a/content/en/functions/hugo/IsMultilingual.md +++ b/content/en/functions/hugo/IsMultilingual.md @@ -10,7 +10,7 @@ params: signatures: [hugo.IsMultilingual] --- -Site configuration: +Project configuration: {{< code-toggle file=hugo >}} defaultContentLanguage = 'de' diff --git a/content/en/functions/hugo/Sites.md b/content/en/functions/hugo/Sites.md new file mode 100644 index 000000000..10a8e147e --- /dev/null +++ b/content/en/functions/hugo/Sites.md @@ -0,0 +1,82 @@ +--- +title: hugo.Sites +description: Returns a collection of all sites for all dimensions. +categories: [] +keywords: [] +params: + functions_and_methods: + aliases: [] + returnType: page.Sites + signatures: [hugo.Sites] +--- + +{{< new-in 0.156.0 />}} + +{{% include "/_common/functions/hugo/sites-collection.md" %}} + +With this project configuration: + +{{< code-toggle file=hugo >}} +defaultContentLanguage = 'de' +defaultContentLanguageInSubdir = true +defaultContentVersionInSubdir = true + +[languages.de] +contentDir = 'content/de' +languageCode = 'de-DE' +languageDirection = 'ltr' +languageName = 'Deutsch' +title = 'Projekt Dokumentation' +weight = 1 + +[languages.en] +contentDir = 'content/en' +languageCode = 'en-US' +languageDirection = 'ltr' +languageName = 'English' +title = 'Project Documentation' +weight = 2 + +[versions.'v1.0.0'] +[versions.'v2.0.0'] +[versions.'v3.0.0'] +{{< /code-toggle >}} + +This template: + +```go-html-template + +``` + +Produces a list of links to each home page: + +```html + +``` + +To render a link to the home page of the [default site](g): + +```go-html-template +{{ with hugo.Sites.Default }} + {{ .Title }} +{{ end }} +``` + +This is equivalent to: + +```go-html-template +{{ with index hugo.Sites 0 }} + {{ .Title }} +{{ end }} +``` diff --git a/content/en/functions/hugo/Version.md b/content/en/functions/hugo/Version.md index 380b21eba..a8ba059c7 100644 --- a/content/en/functions/hugo/Version.md +++ b/content/en/functions/hugo/Version.md @@ -11,5 +11,5 @@ params: --- ```go-html-template -{{ hugo.Version }} → 0.155.3 +{{ hugo.Version }} → 0.156.0 ``` diff --git a/content/en/functions/images/Mask.md b/content/en/functions/images/Mask.md index 4f3b4aa3f..ecc489d8a 100644 --- a/content/en/functions/images/Mask.md +++ b/content/en/functions/images/Mask.md @@ -17,7 +17,7 @@ The `images.Mask` filter applies a mask to an image. Black pixels in the mask ma > [!note] > Of the formats supported by Hugo's imaging pipeline, only PNG and WebP have an alpha channel to support transparency. If your source image has a different format and you require transparent masked areas, convert it to either PNG or WebP as shown in the example below. -When applying a mask to a non-transparent image format such as JPEG, the masked areas will be filled with the color specified by the `bgColor` parameter in your [site configuration]. You can override that color with a `Process` image filter: +When applying a mask to a non-transparent image format such as JPEG, the masked areas will be filled with the color specified by the `bgColor` parameter in your [project configuration]. You can override that color with a `Process` image filter: ```go-html-template {{ $filter := images.Process "#00ff00" }} @@ -72,4 +72,4 @@ Mask [`Filter`]: /methods/resource/filter/ [`images.Filter`]: /functions/images/filter/ -[site configuration]: /configuration/imaging/ +[project configuration]: /configuration/imaging/ diff --git a/content/en/functions/js/Babel.md b/content/en/functions/js/Babel.md index 488c80503..2d76b6718 100644 --- a/content/en/functions/js/Babel.md +++ b/content/en/functions/js/Babel.md @@ -42,7 +42,7 @@ Step 2 ``` Step 3 -: Add the babel executable to Hugo's `security.exec.allow` list in your site configuration: +: Add the babel executable to Hugo's `security.exec.allow` list in your project configuration: {{< code-toggle file=hugo >}} [security.exec] diff --git a/content/en/functions/js/Build.md b/content/en/functions/js/Build.md index 79c52087d..d81ef2db3 100644 --- a/content/en/functions/js/Build.md +++ b/content/en/functions/js/Build.md @@ -75,7 +75,7 @@ For other files (e.g. `JSON`, `CSS`) you need to use the relative path including import * as data from 'my/module/data.json'; ``` -Any imports in a file outside `assets` or that does not resolve to a component inside `assets` will be resolved by [ESBuild](https://esbuild.github.io/) with the **project directory** as the resolve directory (used as the starting point when looking for `node_modules` etc.). Also see [hugo mod npm pack](/commands/hugo_mod_npm_pack/). If you have any imported npm dependencies in your project, you need to make sure to run `npm install` before you run `hugo`. +Any imports in a file outside `assets` or that does not resolve to a component inside `assets` will be resolved by [ESBuild](https://esbuild.github.io/) with the **project directory** as the resolve directory (used as the starting point when looking for `node_modules` etc.). Also see [hugo mod npm pack](/commands/hugo_mod_npm_pack/). If you have any imported npm dependencies in your project, you need to make sure to run `npm install` before you run `hugo build`. Also note the new `params` option that can be passed from template to your JS files, e.g.: @@ -95,7 +95,7 @@ Hugo will, by default, generate a `assets/jsconfig.json` file that maps the impo Use the `js.Build` function to include Node.js dependencies. -Any imports in a file outside `assets` or that does not resolve to a component inside `assets` will be resolved by [esbuild](https://esbuild.github.io/) with the **project directory** as the resolve directory (used as the starting point when looking for `node_modules` etc.). Also see [hugo mod npm pack](/commands/hugo_mod_npm_pack/). If you have any imported npm dependencies in your project, you need to make sure to run `npm install` before you run `hugo`. +Any imports in a file outside `assets` or that does not resolve to a component inside `assets` will be resolved by [esbuild](https://esbuild.github.io/) with the **project directory** as the resolve directory (used as the starting point when looking for `node_modules` etc.). Also see [hugo mod npm pack](/commands/hugo_mod_npm_pack/). If you have any imported npm dependencies in your project, you need to make sure to run `npm install` before you run `hugo build`. The start directory for resolving npm packages (aka. packages that live inside a `node_modules` directory) is always the main project directory. diff --git a/content/en/functions/lang/Translate.md b/content/en/functions/lang/Translate.md index 29406bd1b..b73a760e1 100644 --- a/content/en/functions/lang/Translate.md +++ b/content/en/functions/lang/Translate.md @@ -18,9 +18,9 @@ If the key is not found in the translation table for the current language, the ` If the key is not found in the translation table for the `defaultContentLanguage`, the `lang.Translate` function returns an empty string. > [!note] -> To list missing and fallback translations, set [`printI18nWarnings`][] to `true` in your site configuration, or use the `--printI18nWarnings` flag when building your site. +> To list missing and fallback translations, set [`printI18nWarnings`][] to `true` in your project configuration, or use the `--printI18nWarnings` flag when building your project. > -> To render placeholders for missing and fallback translations, set [`enableMissingTranslationPlaceholders`][] to `true` in your site configuration. +> To render placeholders for missing and fallback translations, set [`enableMissingTranslationPlaceholders`][] to `true` in your project configuration. ## Translation tables @@ -31,7 +31,7 @@ i18n/en.toml i18n/pt-BR.toml ``` -The base name must match the [`languageCode`][] or [language key][] as defined in your site configuration. Hugo selects the translation table based on the `languageCode`, falling back to the language key if a matching translation table does not exist. +The base name must match the [`languageCode`][] or [language key][] as defined in your project configuration. Hugo selects the translation table based on the `languageCode`, falling back to the language key if a matching translation table does not exist. Artificial languages with private use subtags as defined in [RFC 5646 § 2.2.7][] are also supported. You may omit the `art-x-` prefix for brevity. For example: diff --git a/content/en/functions/os/Getenv.md b/content/en/functions/os/Getenv.md index 04215e6c3..d9e6e08fe 100644 --- a/content/en/functions/os/Getenv.md +++ b/content/en/functions/os/Getenv.md @@ -18,7 +18,7 @@ By default, when using the `os.Getenv` function Hugo allows access to: - The `CI` environment variable - Any environment variable beginning with `HUGO_` -To access other environment variables, adjust your site configuration. For example, to allow access to the `HOME` and `USER` environment variables: +To access other environment variables, adjust your project configuration. For example, to allow access to the `HOME` and `USER` environment variables: {{< code-toggle file=hugo >}} [security.funcs] @@ -34,7 +34,7 @@ For more information see [configure security](/configuration/security). {{ getenv "USER" }} → victor ``` -You can pass values when building your site: +You can pass values when building your project: ```sh MY_VAR1=foo MY_VAR2=bar hugo diff --git a/content/en/functions/resources/ExecuteAsTemplate.md b/content/en/functions/resources/ExecuteAsTemplate.md index bff83832e..2ffb9dff7 100644 --- a/content/en/functions/resources/ExecuteAsTemplate.md +++ b/content/en/functions/resources/ExecuteAsTemplate.md @@ -14,7 +14,7 @@ The `resources.ExecuteAsTemplate` function returns a resource created from a Go Hugo publishes the resource to the target path when you call its [`Publish`], [`Permalink`], or [`RelPermalink`] methods. -Let's say you have a CSS file that you wish to populate with values from your site configuration: +Let's say you have a CSS file that you wish to populate with values from your project configuration: ```go-html-template {file="assets/css/template.css"} body { @@ -23,7 +23,7 @@ body { } ``` -And your site configuration contains: +And your project configuration contains: {{< code-toggle file=hugo >}} [params.style] diff --git a/content/en/functions/resources/FromString.md b/content/en/functions/resources/FromString.md index 8761d1c99..608b834de 100644 --- a/content/en/functions/resources/FromString.md +++ b/content/en/functions/resources/FromString.md @@ -23,7 +23,7 @@ Let's say you need to publish a file named "site.json" in the root of your `publ ```json { "build_date": "2026-01-11T11:27:49-08:00", - "hugo_version": "0.155.3", + "hugo_version": "0.156.0", "last_modified": "2026-01-11T11:27:59-08:00" } ``` diff --git a/content/en/functions/resources/GetRemote.md b/content/en/functions/resources/GetRemote.md index 29768eedf..4d8ae0f82 100644 --- a/content/en/functions/resources/GetRemote.md +++ b/content/en/functions/resources/GetRemote.md @@ -13,8 +13,7 @@ params: {{< new-in 0.141.0 >}} The `Err` method on the returned resource was removed in v0.141.0. -Use the [`try`] statement instead, as shown in the [error handling] example below. - +Use the [`try`](/functions/go-template/try) statement instead, as shown in the [error handling](#error-handling) example below. {{< /new-in >}} ```go-html-template @@ -207,7 +206,7 @@ ERROR error calling resources.GetRemote: failed to resolve media type... For example, you will see the error above if you attempt to download an executable. -Although the allowlist contains entries for common media types, you may encounter situations where Hugo is unable to resolve the media type of a file that you know to be safe. In these situations, edit your site configuration to add the media type to the allowlist. For example: +Although the allowlist contains entries for common media types, you may encounter situations where Hugo is unable to resolve the media type of a file that you know to be safe. In these situations, edit your project configuration to add the media type to the allowlist. For example: {{< code-toggle file=hugo >}} [security.http] @@ -219,9 +218,8 @@ Note that the entry above is: - An _addition_ to the allowlist; it does not _replace_ the allowlist - An array of [regular expressions](g) -[allowlist]: https://en.wikipedia.org/wiki/Whitelist -[Content-Type]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Type - [`try`]: /functions/go-template/try +[allowlist]: https://en.wikipedia.org/wiki/Whitelist [configure file caches]: /configuration/caches/ +[Content-Type]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Type [error handling]: #error-handling diff --git a/content/en/functions/resources/PostProcess.md b/content/en/functions/resources/PostProcess.md index 766817ff5..c848ec239 100644 --- a/content/en/functions/resources/PostProcess.md +++ b/content/en/functions/resources/PostProcess.md @@ -104,7 +104,7 @@ PWD HUGO_ENVIRONMENT : The current Hugo environment, set with the `--environment` command line flag. -Default is `production` for `hugo` and `development` for `hugo server`. +Default is `production` for `hugo build` and `development` for `hugo server`. HUGO_PUBLISHDIR : The absolute path to the publish directory, typically `public`. This value points to a directory on disk, even when rendering to memory with the `--renderToMemory` command line flag. diff --git a/content/en/functions/strings/Title.md b/content/en/functions/strings/Title.md index d1b4aca01..0ff79cdf0 100644 --- a/content/en/functions/strings/Title.md +++ b/content/en/functions/strings/Title.md @@ -15,7 +15,7 @@ aliases: [/functions/title] {{ title "table of contents (TOC)" }} → Table of Contents (TOC) ``` -By default, Hugo follows the capitalization rules published in the [Associated Press Stylebook]. Change your [site configuration] if you would prefer to: +By default, Hugo follows the capitalization rules published in the [Associated Press Stylebook]. Change your [project configuration] if you would prefer to: - Follow the capitalization rules published in the [Chicago Manual of Style] - Capitalize the first letter of every word @@ -26,4 +26,4 @@ The last option is useful if your theme uses the `title` function, and you would [Associated Press Stylebook]: https://www.apstylebook.com/ [Chicago Manual of Style]: https://www.chicagomanualofstyle.org/home.html -[site configuration]: /configuration/all/#title-case-style +[project configuration]: /configuration/all/#title-case-style diff --git a/content/en/functions/templates/Current.md b/content/en/functions/templates/Current.md index b82818c47..47adf38ae 100644 --- a/content/en/functions/templates/Current.md +++ b/content/en/functions/templates/Current.md @@ -36,7 +36,7 @@ Parent ## Examples -The examples below help visualize template execution and require a `debug` parameter set to `true` in your site configuration: +The examples below help visualize template execution and require a `debug` parameter set to `true` in your project configuration: {{< code-toggle file=hugo >}} [params] diff --git a/content/en/functions/time/AsTime.md b/content/en/functions/time/AsTime.md index 760329a13..884d6c61b 100644 --- a/content/en/functions/time/AsTime.md +++ b/content/en/functions/time/AsTime.md @@ -26,7 +26,7 @@ As shown above, the first argument must be a parsable string representation of a {{% include "/_common/parsable-date-time-strings.md" %}} -To override the default time zone, set the [`timeZone`] in your site configuration or provide a second argument to the `time.AsTime` function. For example: +To override the default time zone, set the [`timeZone`] in your project configuration or provide a second argument to the `time.AsTime` function. For example: ```go-html-template {{ time.AsTime "15 Oct 2023" "America/Los_Angeles" }} @@ -38,7 +38,7 @@ The order of precedence for determining the time zone is: 1. The time zone offset in the date/time string 1. The time zone provided as the second argument to the `time.AsTime` function -1. The time zone specified in your site configuration +1. The time zone specified in your project configuration 1. The `Etc/UTC` time zone [IANA Time Zone database]: https://en.wikipedia.org/wiki/List_of_tz_database_time_zones diff --git a/content/en/functions/time/Format.md b/content/en/functions/time/Format.md index f1b0d6d83..112a6e72e 100644 --- a/content/en/functions/time/Format.md +++ b/content/en/functions/time/Format.md @@ -29,10 +29,10 @@ Examples of parsable string representations: {{% include "/_common/parsable-date-time-strings.md" %}} -To override the default time zone, set the [`timeZone`] in your site configuration. The order of precedence for determining the time zone is: +To override the default time zone, set the [`timeZone`] in your project configuration. The order of precedence for determining the time zone is: 1. The time zone offset in the date/time string -1. The time zone specified in your site configuration +1. The time zone specified in your project configuration 1. The `Etc/UTC` time zone [`timeZone`]: /configuration/all/#timezone diff --git a/content/en/functions/transform/Emojify.md b/content/en/functions/transform/Emojify.md index 31c5dce70..6a4501fc5 100644 --- a/content/en/functions/transform/Emojify.md +++ b/content/en/functions/transform/Emojify.md @@ -15,7 +15,7 @@ aliases: [/functions/emojify] See the list of [emoji shortcodes] for available emoticons. -The `emojify` function can be called in your templates but not directly in your content files by default. For emojis in content files, set [`enableEmoji`] to `true` in your site's configuration. Then you can write emoji shorthand directly into your content files; +The `emojify` function can be called in your templates but not directly in your content files by default. For emojis in content files, set [`enableEmoji`] to `true` in your project configuration. Then you can write emoji shorthand directly into your content files; ```text I :heart: Hugo! diff --git a/content/en/functions/transform/Highlight.md b/content/en/functions/transform/Highlight.md index 5633f2256..1e4e235b4 100644 --- a/content/en/functions/transform/Highlight.md +++ b/content/en/functions/transform/Highlight.md @@ -27,9 +27,9 @@ LANG : (`string`) The language of the code to highlight. Choose from one of the [supported languages]. This value is case-insensitive. OPTIONS -: (`map or string`) A map or comma-separated key-value pairs wrapped in quotation marks. Set default values for each option in your [site configuration]. The key names are case-insensitive. +: (`map or string`) A map or comma-separated key-value pairs wrapped in quotation marks. Set default values for each option in your [project configuration]. The key names are case-insensitive. -[site configuration]: /configuration/markup#highlight +[project configuration]: /configuration/markup#highlight [supported languages]: /content-management/syntax-highlighting#languages ## Examples diff --git a/content/en/functions/transform/PortableText.md b/content/en/functions/transform/PortableText.md index fa9a91e33..d100f5eb2 100644 --- a/content/en/functions/transform/PortableText.md +++ b/content/en/functions/transform/PortableText.md @@ -180,7 +180,7 @@ export const postType = defineType({ Note that the above requires some additional plugins to be installed: -```bash +```sh npm i sanity-plugin-media @sanity/code-input ``` diff --git a/content/en/functions/transform/ToMath.md b/content/en/functions/transform/ToMath.md index 97689f5d5..27b2f0d70 100644 --- a/content/en/functions/transform/ToMath.md +++ b/content/en/functions/transform/ToMath.md @@ -99,7 +99,7 @@ The example below demonstrates error handing within a template. Instead of client-side JavaScript rendering of mathematical markup using MathJax or KaTeX, create a passthrough render hook which calls the `transform.ToMath` function. Step 1 -: Enable and configure the Goldmark [passthrough extension][] in your site configuration. The passthrough extension preserves raw Markdown within delimited snippets of text, including the delimiters themselves. +: Enable and configure the Goldmark [passthrough extension][] in your project configuration. The passthrough extension preserves raw Markdown within delimited snippets of text, including the delimiters themselves. [passthrough extension]: /configuration/markup/#passthrough diff --git a/content/en/functions/urls/AbsLangURL.md b/content/en/functions/urls/AbsLangURL.md index da45ca224..b2cf021c3 100644 --- a/content/en/functions/urls/AbsLangURL.md +++ b/content/en/functions/urls/AbsLangURL.md @@ -14,10 +14,10 @@ aliases: [/functions/abslangurl] Use this function with both monolingual and multilingual configurations. The URL returned by this function depends on: - Whether the input begins with a slash (`/`) -- The `baseURL` in your site configuration +- The `baseURL` in your project configuration - The language prefix, if any -This is the site configuration for the examples that follow: +This is the project configuration for the examples that follow: {{< code-toggle file=hugo >}} defaultContentLanguage = 'en' @@ -30,7 +30,7 @@ weight = 2 ## Input does not begin with a slash -If the input does not begin with a slash, the path in the resulting URL will be relative to the `baseURL` in your site configuration. +If the input does not begin with a slash, the path in the resulting URL will be relative to the `baseURL` in your project configuration. When rendering the `en` site with `baseURL = https://example.org/` @@ -50,7 +50,7 @@ When rendering the `en` site with `baseURL = https://example.org/docs/` ## Input begins with a slash -If the input begins with a slash, the path in the resulting URL will be relative to the protocol+host of the `baseURL` in your site configuration. +If the input begins with a slash, the path in the resulting URL will be relative to the protocol+host of the `baseURL` in your project configuration. When rendering the `en` site with `baseURL = https://example.org/` diff --git a/content/en/functions/urls/AbsURL.md b/content/en/functions/urls/AbsURL.md index 72613cd0b..e29862429 100644 --- a/content/en/functions/urls/AbsURL.md +++ b/content/en/functions/urls/AbsURL.md @@ -14,11 +14,11 @@ aliases: [/functions/absurl] With multilingual configurations, use the [`urls.AbsLangURL`] function instead. The URL returned by this function depends on: - Whether the input begins with a slash (`/`) -- The `baseURL` in your site configuration +- The `baseURL` in your project configuration ## Input does not begin with a slash -If the input does not begin with a slash, the path in the resulting URL will be relative to the `baseURL` in your site configuration. +If the input does not begin with a slash, the path in the resulting URL will be relative to the `baseURL` in your project configuration. With `baseURL = https://example.org/` @@ -38,7 +38,7 @@ With `baseURL = https://example.org/docs/` ## Input begins with a slash -If the input begins with a slash, the path in the resulting URL will be relative to the protocol+host of the `baseURL` in your site configuration. +If the input begins with a slash, the path in the resulting URL will be relative to the protocol+host of the `baseURL` in your project configuration. With `baseURL = https://example.org/` diff --git a/content/en/functions/urls/Anchorize.md b/content/en/functions/urls/Anchorize.md index d18bd9a4d..d529ec493 100644 --- a/content/en/functions/urls/Anchorize.md +++ b/content/en/functions/urls/Anchorize.md @@ -15,7 +15,7 @@ aliases: [/functions/anchorize] ## Sanitizing logic -With the default Markdown renderer, Goldmark, the sanitizing logic is controlled by your site configuration: +With the default Markdown renderer, Goldmark, the sanitizing logic is controlled by your project configuration: {{< code-toggle file=hugo >}} [markup.goldmark.parser] diff --git a/content/en/functions/urls/RelLangURL.md b/content/en/functions/urls/RelLangURL.md index af8bff3d7..ea3131672 100644 --- a/content/en/functions/urls/RelLangURL.md +++ b/content/en/functions/urls/RelLangURL.md @@ -14,10 +14,10 @@ aliases: [/functions/rellangurl] Use this function with both monolingual and multilingual configurations. The URL returned by this function depends on: - Whether the input begins with a slash (`/`) -- The `baseURL` in your site configuration +- The `baseURL` in your project configuration - The language prefix, if any -This is the site configuration for the examples that follow: +This is the project configuration for the examples that follow: {{< code-toggle file=hugo >}} defaultContentLanguage = 'en' @@ -30,7 +30,7 @@ weight = 2 ## Input does not begin with a slash -If the input does not begin with a slash, the resulting URL will be relative to the `baseURL` in your site configuration. +If the input does not begin with a slash, the resulting URL will be relative to the `baseURL` in your project configuration. When rendering the `en` site with `baseURL = https://example.org/` @@ -60,7 +60,7 @@ When rendering the `en` site with `baseURL = https://example.org/docs/` ## Input begins with a slash -If the input begins with a slash, the resulting URL will be relative to the protocol+host of the `baseURL` in your site configuration. +If the input begins with a slash, the resulting URL will be relative to the protocol+host of the `baseURL` in your project configuration. When rendering the `en` site with `baseURL = https://example.org/` diff --git a/content/en/functions/urls/RelURL.md b/content/en/functions/urls/RelURL.md index 0aef4043f..97328eb2a 100644 --- a/content/en/functions/urls/RelURL.md +++ b/content/en/functions/urls/RelURL.md @@ -14,11 +14,11 @@ aliases: [/functions/relurl] With multilingual configurations, use the [`urls.RelLangURL`] function instead. The URL returned by this function depends on: - Whether the input begins with a slash (`/`) -- The `baseURL` in your site configuration +- The `baseURL` in your project configuration ## Input does not begin with a slash -If the input does not begin with a slash, the resulting URL will be relative to the `baseURL` in your site configuration. +If the input does not begin with a slash, the resulting URL will be relative to the `baseURL` in your project configuration. With `baseURL = https://example.org/` @@ -48,7 +48,7 @@ With `baseURL = https://example.org/docs/` ## Input begins with a slash -If the input begins with a slash, the resulting URL will be relative to the protocol+host of the `baseURL` in your site configuration. +If the input begins with a slash, the resulting URL will be relative to the protocol+host of the `baseURL` in your project configuration. With `baseURL = https://example.org/` diff --git a/content/en/functions/urls/URLize.md b/content/en/functions/urls/URLize.md index b0cc812ec..28bc1dc47 100644 --- a/content/en/functions/urls/URLize.md +++ b/content/en/functions/urls/URLize.md @@ -17,7 +17,7 @@ aliases: [/functions/urlize] Use the `urlize` function to create a link to a [term page](g). -Consider this site configuration: +Consider this project configuration: {{< code-toggle file=hugo >}} [taxonomies] diff --git a/content/en/getting-started/directory-structure.md b/content/en/getting-started/directory-structure.md index d01822c96..863775d99 100644 --- a/content/en/getting-started/directory-structure.md +++ b/content/en/getting-started/directory-structure.md @@ -7,20 +7,20 @@ weight: 30 aliases: [/overview/source-directory/] --- -Each Hugo project is a directory, with subdirectories that contribute to the content, structure, behavior, and presentation of your site. +Each Hugo project is a directory, with subdirectories that contribute to content, structure, behavior, and presentation. -## Site skeleton +## Project skeleton -Hugo generates a project skeleton when you create a new site. For example, this command: +Hugo generates a project skeleton when you create a new project. For example, this command: ```sh -hugo new site my-site +hugo new project my-project ``` Creates this directory structure: ```txt -my-site/ +my-project/ ├── archetypes/ │ └── default.md ├── assets/ @@ -30,17 +30,17 @@ my-site/ ├── layouts/ ├── static/ ├── themes/ -└── hugo.toml <-- site configuration +└── hugo.toml <-- project configuration ``` -Depending on requirements, you may wish to organize your site configuration into subdirectories: +Depending on requirements, you may wish to organize your project configuration into subdirectories: ```txt -my-site/ +my-project/ ├── archetypes/ │ └── default.md ├── assets/ -├── config/ <-- site configuration +├── config/ <-- project configuration │ └── _default/ │ └── hugo.toml ├── content/ @@ -51,10 +51,10 @@ my-site/ └── themes/ ``` -When you build your site, Hugo creates a `public` directory, and typically a `resources` directory as well: +When you build your project, Hugo creates a `public` directory, and typically a `resources` directory as well: ```txt -my-site/ +my-project/ ├── archetypes/ │ └── default.md ├── assets/ @@ -65,15 +65,15 @@ my-site/ ├── data/ ├── i18n/ ├── layouts/ -├── public/ <-- created when you build your site -├── resources/ <-- created when you build your site +├── public/ <-- created when you build your project +├── resources/ <-- created when you build your project ├── static/ └── themes/ ``` ## Directories -Each of the subdirectories contributes to the content, structure, behavior, or presentation of your site. +Each of the subdirectories contributes to content, structure, behavior, or presentation. archetypes : The `archetypes` directory contains templates for new content. See [details](/content-management/archetypes/). @@ -82,28 +82,28 @@ assets : The `assets` directory contains global resources typically passed through an asset pipeline. This includes resources such as images, CSS, Sass, JavaScript, and TypeScript. See [details](/hugo-pipes/introduction/). config -: The `config` directory contains your site configuration, possibly split into multiple subdirectories and files. For projects with minimal configuration or projects that do not need to behave differently in different environments, a single configuration file named `hugo.toml` in the root of the project is sufficient. See [details](/configuration/introduction/#configuration-directory). +: The `config` directory contains your project configuration, possibly split into multiple subdirectories and files. For projects with minimal configuration or projects that do not need to behave differently in different environments, a single configuration file named `hugo.toml` in the root of the project is sufficient. See [details](/configuration/introduction/#configuration-directory). content -: The `content` directory contains the markup files (typically Markdown) and page resources that comprise the content of your site. See [details](/content-management/organization/). +: The `content` directory contains the markup files (typically Markdown) and page resources that comprise the content of your project. See [details](/content-management/organization/). data : The `data` directory contains data files (JSON, TOML, YAML, or XML) that augment content, configuration, localization, and navigation. See [details](/content-management/data-sources/). i18n -: The `i18n` directory contains translation tables for multilingual sites. See [details](/content-management/multilingual/). +: The `i18n` directory contains translation tables for multilingual projects. See [details](/content-management/multilingual/). layouts : The `layouts` directory contains templates to transform content, data, and resources into a complete website. See [details](/templates/). public -: The `public` directory contains the published website, generated when you run the `hugo` or `hugo server` commands. Hugo recreates this directory and its content as needed. See [details](/getting-started/usage/#build-your-site). +: The `public` directory contains the published website, generated when you run the `hugo build` or `hugo server` commands. Hugo recreates this directory and its content as needed. See [details](/getting-started/usage/#build-your-project). resources -: The `resources` directory contains cached output from Hugo's asset pipelines, generated when you run the `hugo` or `hugo server` commands. By default this cache directory includes CSS and images. Hugo recreates this directory and its content as needed. +: The `resources` directory contains cached output from Hugo's asset pipelines, generated when you run the `hugo build` or `hugo server` commands. By default this cache directory includes CSS and images. Hugo recreates this directory and its content as needed. static -: The `static` directory contains files that will be copied to the `public` directory when you build your site. For example: `favicon.ico`, `robots.txt`, and files that verify site ownership. Before the introduction of [page bundles](g) and [asset pipelines](/hugo-pipes/introduction/), the `static` directory was also used for images, CSS, and JavaScript. +: The `static` directory contains files that will be copied to the `public` directory when you build your project. For example: `favicon.ico`, `robots.txt`, and files that verify website ownership. Before the introduction of [page bundles](g) and [asset pipelines](/hugo-pipes/introduction/), the `static` directory was also used for images, CSS, and JavaScript. themes : The `themes` directory contains one or more [themes](g), each in its own subdirectory. @@ -115,7 +115,7 @@ Hugo creates a union file system, allowing you to mount two or more directories ```text home/ └── user/ - ├── my-site/ + ├── my-project/ │ ├── content/ │ │ ├── books/ │ │ │ ├── _index.md @@ -132,7 +132,7 @@ home/ └── film-2.md ``` -You can include the shared content when you build your site using mounts. In your site configuration: +You can include the shared content using mounts. In your project configuration: {{< code-toggle file=hugo >}} [[module.mounts]] @@ -154,7 +154,7 @@ After mounting, the union file system has this structure: ```text home/ └── user/ - └── my-site/ + └── my-project/ ├── content/ │ ├── books/ │ │ ├── _index.md diff --git a/content/en/getting-started/quick-start.md b/content/en/getting-started/quick-start.md index cc800181c..3d05333ba 100644 --- a/content/en/getting-started/quick-start.md +++ b/content/en/getting-started/quick-start.md @@ -1,20 +1,20 @@ --- title: Quick start -description: Create a Hugo site in minutes. +description: Create your first Hugo project. categories: [] keywords: [] params: - minVersion: v0.146.0 + minVersion: v0.156.0 weight: 10 aliases: [/quickstart/,/overview/quickstart/] --- In this tutorial you will: -1. Create a site +1. Create a project 1. Add content -1. Configure the site -1. Publish the site +1. Configure the project +1. Publish the project ## Prerequisites @@ -25,7 +25,7 @@ Before you begin this tutorial you must: You must also be comfortable working from the command line. -## Create a site +## Create a project ### Commands @@ -34,9 +34,9 @@ You must also be comfortable working from the command line. > > - Do not use the Command Prompt > - Do not use Windows PowerShell -> - Run these commands from [PowerShell] or a Linux terminal such as WSL or Git > Bash +> - Run these commands from [PowerShell][] or a Linux terminal such as WSL or Git > Bash > -> PowerShell and Windows PowerShell [are different applications]. +> PowerShell and Windows PowerShell [are different applications][]. Verify that you have installed Hugo {{% param "minVersion" %}} or later. @@ -44,10 +44,10 @@ Verify that you have installed Hugo {{% param "minVersion" %}} or later. hugo version ``` -Run these commands to create a Hugo site with the [Ananke] theme. The next section provides an explanation of each command. +Run these commands to create a Hugo project with the [Ananke][] theme. The next section provides an explanation of each command. ```text -hugo new site quickstart +hugo new project quickstart cd quickstart git init git submodule add https://github.com/theNewDynamic/gohugo-theme-ananke.git themes/ananke @@ -55,14 +55,14 @@ echo "theme = 'ananke'" >> hugo.toml hugo server ``` -View your site at the URL displayed in your terminal. Press `Ctrl + C` to stop Hugo's development server. +View your project at the URL displayed in your terminal. Press `Ctrl + C` to stop Hugo's development server. ### Explanation of commands -Create the [site skeleton] for your project in the `quickstart` directory. +Create the [project skeleton][] for your project in the `quickstart` directory. ```text -hugo new site quickstart +hugo new project quickstart ``` Change the current directory to the root of your project. @@ -77,19 +77,19 @@ Initialize an empty Git repository in the current directory. git init ``` -Clone the [Ananke] theme into the `themes` directory, adding it to your project as a [Git submodule]. +Clone the [Ananke][] theme into the `themes` directory, adding it to your project as a [Git submodule][]. ```text git submodule add https://github.com/theNewDynamic/gohugo-theme-ananke.git themes/ananke ``` -Append a line to the site configuration file, indicating the current theme. +Append a line to your project configuration file, indicating the current theme. ```text echo "theme = 'ananke'" >> hugo.toml ``` -Start Hugo's development server to view the site. +Start Hugo's development server. ```text hugo server @@ -99,7 +99,7 @@ Press `Ctrl + C` to stop Hugo's development server. ## Add content -Add a new page to your site. +Add a new page to your project. ```text hugo new content content/posts/my-first-post.md @@ -115,9 +115,9 @@ draft = true +++ ``` -Notice the `draft` value in the [front matter] is `true`. By default, Hugo does not publish draft content when you build the site. Learn more about [draft, future, and expired content]. +Notice the `draft` value in the [front matter][] is `true`. By default, Hugo does not publish draft content when you build the project. Learn more about [draft, future, and expired content][]. -Add some [Markdown] to the body of the post, but do not change the `draft` value. +Add some [Markdown][] to the body of the post, but do not change the `draft` value. ```text +++ @@ -132,36 +132,36 @@ This is **bold** text, and this is *emphasized* text. Visit the [Hugo](https://gohugo.io) website! ``` -Save the file, then start Hugo's development server to view the site. You can run either of the following commands to include draft content. +Save the file, then start Hugo's development server. You can run either of the following commands to include draft content. ```text hugo server --buildDrafts hugo server -D ``` -View your site at the URL displayed in your terminal. Keep the development server running as you continue to add and change content. +View your project at the URL displayed in your terminal. Keep the development server running as you continue to add and change content. When satisfied with your new content, set the front matter `draft` parameter to `false`. > [!note] -> Hugo's rendering engine conforms to the CommonMark [specification] for Markdown. The CommonMark organization provides a useful [live testing tool] powered by the reference implementation. +> Hugo's rendering engine conforms to the CommonMark [specification][] for Markdown. The CommonMark organization provides a useful [live testing tool][] powered by the reference implementation. -## Configure the site +## Configure the project -With your editor, open the [site configuration] file (`hugo.toml`) in the root of your project. +With your editor, open your [project configuration][] file (`hugo.toml`) in the root of your project. ```text baseURL = 'https://example.org/' languageCode = 'en-us' -title = 'My New Hugo Site' +title = 'My New Hugo Project' theme = 'ananke' ``` Make the following changes: -1. Set the `baseURL` for your production site. This value must begin with the protocol and end with a slash, as shown above. -1. Set the `languageCode` to your language and region. -1. Set the `title` for your production site. +1. Set the `baseURL` for your project. This value must begin with the protocol and end with a slash, as shown above. +1. Set the `languageCode` to your locale. +1. Set the `title` for your project. Start Hugo's development server to see your changes, remembering to include draft content. @@ -172,37 +172,34 @@ hugo server -D > [!note] > Most theme authors provide configuration guidelines and options. Make sure to visit your theme's repository or documentation site for details. > -> [The New Dynamic], authors of the Ananke theme, provide [documentation] for configuration and usage. They also provide a [demonstration site]. +> [The New Dynamic][], authors of the Ananke theme, provide [documentation][] for configuration and usage. They also provide a [demonstration site][]. -## Publish the site +## Publish the project -In this step you will _publish_ your site, but you will not _deploy_ it. +In this step you will _publish_ your project, but you will not _deploy_ it. -When you _publish_ your site, Hugo creates the entire static site in the `public` directory in the root of your project. This includes the HTML files, and assets such as images, CSS files, and JavaScript files. - -When you publish your site, you typically do _not_ want to include [draft, future, or expired content]. The command is simple. +When you publish your project, Hugo renders all build artifacts to the `public` directory in the root of your project. This includes the HTML files for every site, along with assets such as images, CSS, and JavaScript. The command is simple. ```text hugo ``` -To learn how to _deploy_ your site, see the [host and deploy] section. +To learn how to _deploy_ your project, see the [host and deploy][] section. ## Ask for help -Hugo's [forum] is an active community of users and developers who answer questions, share knowledge, and provide examples. A quick search of over 20,000 topics will often answer your question. Please be sure to read about [requesting help] before asking your first question. +Hugo's [forum][] is an active community of users and developers who answer questions, share knowledge, and provide examples. A quick search of over 20,000 topics will often answer your question. Please be sure to read about [requesting help] before asking your first question. ## Other resources -For other resources to help you learn Hugo, including books and video tutorials, see the [external learning resources](/getting-started/external-learning-resources/) page. +For other resources to help you learn Hugo, including books and video tutorials, see the [external learning resources][] page. [Ananke]: https://github.com/theNewDynamic/gohugo-theme-ananke [are different applications]: https://learn.microsoft.com/en-us/powershell/scripting/whats-new/differences-from-windows-powershell?view=powershell-7.3 [demonstration site]: https://gohugo-ananke-theme-demo.netlify.app/ -[site skeleton]: /getting-started/directory-structure/#site-skeleton [documentation]: https://github.com/theNewDynamic/gohugo-theme-ananke#readme [draft, future, and expired content]: /getting-started/usage/#draft-future-and-expired-content -[draft, future, or expired content]: /getting-started/usage/#draft-future-and-expired-content +[external learning resources]: /getting-started/external-learning-resources/ [forum]: https://discourse.gohugo.io/ [front matter]: /content-management/front-matter/ [Git submodule]: https://git-scm.com/book/en/v2/Git-Tools-Submodules @@ -212,7 +209,8 @@ For other resources to help you learn Hugo, including books and video tutorials, [live testing tool]: https://spec.commonmark.org/dingus/ [Markdown]: https://daringfireball.net/projects/markdown [PowerShell]: https://learn.microsoft.com/en-us/powershell/scripting/install/installing-powershell-on-windows +[project configuration]: /configuration/ +[project skeleton]: /getting-started/directory-structure/#project-skeleton [requesting help]: https://discourse.gohugo.io/t/requesting-help/9132 -[site configuration]: /configuration/ [specification]: https://spec.commonmark.org/ [The New Dynamic]: https://www.thenewdynamic.com/ diff --git a/content/en/getting-started/usage.md b/content/en/getting-started/usage.md index cc43c0cf0..41c703bfb 100644 --- a/content/en/getting-started/usage.md +++ b/content/en/getting-started/usage.md @@ -35,18 +35,18 @@ To get help with a subcommand, use the `--help` flag. For example: hugo server --help ``` -## Build your site +## Build your project -To build your site, `cd` into your project directory and run: +To build your project, `cd` into your project directory and run: ```sh -hugo +hugo build ``` -The [`hugo`] command builds your site, publishing the files to the `public` directory. To publish your site to a different directory, use the [`--destination`] flag or set [`publishDir`] in your site configuration. +The [`hugo build`] command builds your project, publishing the files to the `public` directory. To publish your project to a different directory, use the [`--destination`] flag or set [`publishDir`] in your project configuration. > [!note] -> Hugo does not clear the `public` directory before building your site. Existing files are overwritten, but not deleted. This behavior is intentional to prevent the inadvertent removal of files that you may have added to the `public` directory after the build. +> Hugo does not clear the `public` directory before building your project. Existing files are overwritten, but not deleted. This behavior is intentional to prevent the inadvertent removal of files that you may have added to the `public` directory after the build. > > Depending on your needs, you may wish to manually clear the contents of the `public` directory before every build. @@ -62,18 +62,18 @@ Hugo allows you to set `draft`, `date`, `publishDate`, and `expiryDate` in the [ > [!note] > Hugo publishes descendants of draft, future, and expired [node](g) pages. To prevent publication of these descendants, use the [`cascade`] front matter field to cascade [build options] to the descendant pages. -You can override the default behavior when running `hugo` or `hugo server` with command line flags: +You can override the default behavior when running `hugo build` or `hugo server` with command line flags: ```sh -hugo --buildDrafts # or -D -hugo --buildExpired # or -E -hugo --buildFuture # or -F +hugo build --buildDrafts # or -D +hugo build --buildExpired # or -E +hugo build --buildFuture # or -F ``` -Although you can also set these values in your site configuration, it can lead to unwanted results unless all content authors are aware of, and understand, the settings. +Although you can also set these values in your project configuration, it can lead to unwanted results unless all content authors are aware of, and understand, the settings. > [!note] -> As noted above, Hugo does not clear the `public` directory before building your site. Depending on the _current_ evaluation of the four conditions above, after the build your `public` directory may contain extraneous files from a previous build. +> As noted above, Hugo does not clear the `public` directory before building your project. Depending on the _current_ evaluation of the four conditions above, after the build your `public` directory may contain extraneous files from a previous build. > > A common practice is to manually clear the contents of the `public` directory before each build to remove draft, expired, and future content. @@ -110,7 +110,7 @@ hugo server --navigateToChanged ## Deploy your site > [!note] -> As noted above, Hugo does not clear the `public` directory before building your site. Manually clear the contents of the `public` directory before each build to remove draft, expired, and future content. +> As noted above, Hugo does not clear the `public` directory before building your project. Manually clear the contents of the `public` directory before each build to remove draft, expired, and future content. When you are ready to deploy your site, run: @@ -147,7 +147,7 @@ Most of our users deploy their sites to a [CI/CD](g) platform, where a push[^1] [`--destination`]: /commands/hugo/#options [`cascade`]: /content-management/front-matter/#cascade [`hugo server`]: /commands/hugo_server/ -[`hugo`]: /commands/hugo/ +[`hugo build`]: /commands/hugo/ [`publishDir`]: /configuration/all/#publishdir [build options]: /content-management/build-options/ [front matter]: /content-management/front-matter/ diff --git a/content/en/host-and-deploy/deploy-with-hugo-deploy.md b/content/en/host-and-deploy/deploy-with-hugo-deploy.md index 8feeccbae..6dae734c4 100644 --- a/content/en/host-and-deploy/deploy-with-hugo-deploy.md +++ b/content/en/host-and-deploy/deploy-with-hugo-deploy.md @@ -31,7 +31,7 @@ Use the `hugo deploy` command to deploy your site Amazon S3, Azure Blob Storage, ## Configuration -Create a deployment target in your [site configuration]. The only required parameters are [`name`] and [`url`]: +Create a deployment target in your [project configuration]. The only required parameters are [`name`] and [`url`]: {{< code-toggle file=hugo >}} [deployment] @@ -44,7 +44,7 @@ Create a deployment target in your [site configuration]. The only required param To deploy to a target: -```bash +```sh hugo deploy [--target=] ``` @@ -94,4 +94,4 @@ See [configure deployment](/configuration/deployment/). [Google Cloud]: https://cloud.google.com/ [installation]: /installation/ [Quick Start]: /getting-started/quick-start/ -[site configuration]: /configuration/deployment/ +[project configuration]: /configuration/deployment/ diff --git a/content/en/host-and-deploy/deploy-with-rclone.md b/content/en/host-and-deploy/deploy-with-rclone.md index 8f641bc5d..b5e898d83 100644 --- a/content/en/host-and-deploy/deploy-with-rclone.md +++ b/content/en/host-and-deploy/deploy-with-rclone.md @@ -14,14 +14,14 @@ aliases: [/hosting-and-deployment/deployment-with-rclone/] - Deploying from an [Rclone](https://rclone.org) compatible operating system - You have [installed Rclone](https://rclone.org/install/). -**NB**: You can remove ``--interactive`` in the commands below once you are comfortable with rclone, if you wish. Also, ``--gc`` and ``--minify`` are optional in the ``hugo`` commands below. +**NB**: You can remove `--interactive` in the commands below once you are comfortable with rclone, if you wish. Also, `--gc` and `--minify` are optional in the commands below. ## Getting started The spoiler is that you can even deploy your entire website from any compatible OS with no configuration. Using SFTP for example: ```txt -hugo --gc --minify +hugo build --gc --minify rclone sync --interactive --sftp-host sftp.example.com --sftp-user www-data --sftp-ask-password public/ :sftp:www/ ``` @@ -31,12 +31,12 @@ The easiest way is simply to run `rclone config`. The [Rclone docs](https://rclone.org/docs/) provide [an example of configuring Rclone to use SFTP](https://rclone.org/sftp/). -For the next commands, we will assume you configured a remote you named ``hugo-www`` +For the next commands, we will assume you configured a remote you named `hugo-www`. The above 'spoiler' commands could become: ```txt -hugo --gc --minify +hugo build --gc --minify rclone sync --interactive public/ hugo-www:www/ ``` diff --git a/content/en/host-and-deploy/deploy-with-rsync.md b/content/en/host-and-deploy/deploy-with-rsync.md index 0ad64d6fb..1c0967ba9 100644 --- a/content/en/host-and-deploy/deploy-with-rsync.md +++ b/content/en/host-and-deploy/deploy-with-rsync.md @@ -87,7 +87,7 @@ USER=my-user HOST=my-server.com DIR=my/directory/to/topologix.fr/ # the directory where your website files should go -hugo && rsync -avz --delete public/ ${USER}@${HOST}:~/${DIR} # this will delete everything on the server that's not in the local public directory +hugo build && rsync -avz --delete public/ ${USER}@${HOST}:~/${DIR} # this will delete everything on the server that's not in the local public directory exit 0 ``` diff --git a/content/en/host-and-deploy/host-on-aws-amplify/index.md b/content/en/host-and-deploy/host-on-aws-amplify/index.md index 216b828fb..7ea57860d 100644 --- a/content/en/host-and-deploy/host-on-aws-amplify/index.md +++ b/content/en/host-and-deploy/host-on-aws-amplify/index.md @@ -41,8 +41,8 @@ Step 2 variables: # Application versions DART_SASS_VERSION: 1.97.3 - GO_VERSION: 1.25.6 - HUGO_VERSION: 0.155.3 + GO_VERSION: 1.26.0 + HUGO_VERSION: 0.156.0 # Time zone TZ: Europe/Oslo # Cache @@ -95,7 +95,7 @@ Step 2 build: commands: - echo "Building site..." - - hugo --gc --minify + - hugo build --gc --minify artifacts: baseDirectory: public files: diff --git a/content/en/host-and-deploy/host-on-cloudflare/index.md b/content/en/host-and-deploy/host-on-cloudflare/index.md index 1341ca325..6218621c2 100644 --- a/content/en/host-and-deploy/host-on-cloudflare/index.md +++ b/content/en/host-and-deploy/host-on-cloudflare/index.md @@ -52,9 +52,9 @@ Step 2 main() { DART_SASS_VERSION=1.97.3 - GO_VERSION=1.25.6 - HUGO_VERSION=0.155.3 - NODE_VERSION=24.13.0 + GO_VERSION=1.26.0 + HUGO_VERSION=0.156.0 + NODE_VERSION=24.13.1 export TZ=Europe/Oslo @@ -103,7 +103,7 @@ Step 2 # Build the site echo "Building the site..." - hugo --gc --minify + hugo build --gc --minify } diff --git a/content/en/host-and-deploy/host-on-firebase.md b/content/en/host-and-deploy/host-on-firebase.md index 064ecadad..9a28f1f63 100644 --- a/content/en/host-and-deploy/host-on-firebase.md +++ b/content/en/host-and-deploy/host-on-firebase.md @@ -63,7 +63,7 @@ In new versions of Firebase, some other questions apply: After that Firebase has been set in your project with [CI/CD](g). After that run: ```sh -hugo && firebase deploy +hugo build && firebase deploy ``` With this you will have the app initialized manually. After that you can manage and fix your GitHub workflow from . diff --git a/content/en/host-and-deploy/host-on-github-pages/index.md b/content/en/host-and-deploy/host-on-github-pages/index.md index 5e900cffe..2ead348ee 100644 --- a/content/en/host-and-deploy/host-on-github-pages/index.md +++ b/content/en/host-and-deploy/host-on-github-pages/index.md @@ -36,7 +36,7 @@ Step 1 ![screen capture](gh-pages-02.png) Step 2 -: In your site configuration, change the location of the image cache to the [`cacheDir`] as shown below: +: In your project configuration, change the location of the image cache to the [`cacheDir`] as shown below: {{< code-toggle file=hugo copy=true >}} [caches.images] @@ -78,9 +78,9 @@ Step 4 runs-on: ubuntu-latest env: DART_SASS_VERSION: 1.97.3 - GO_VERSION: 1.25.6 - HUGO_VERSION: 0.155.3 - NODE_VERSION: 24.13.0 + GO_VERSION: 1.26.0 + HUGO_VERSION: 0.156.0 + NODE_VERSION: 24.13.1 TZ: Europe/Oslo steps: - name: Checkout @@ -138,7 +138,7 @@ Step 4 hugo- - name: Build the site run: | - hugo \ + hugo build \ --gc \ --minify \ --baseURL "${{ steps.pages.outputs.base_url }}/" \ diff --git a/content/en/host-and-deploy/host-on-gitlab-pages.md b/content/en/host-and-deploy/host-on-gitlab-pages.md index 46832909e..441c0b11f 100644 --- a/content/en/host-and-deploy/host-on-gitlab-pages.md +++ b/content/en/host-and-deploy/host-on-gitlab-pages.md @@ -15,7 +15,7 @@ aliases: [/hosting-and-deployment/hosting-on-gitlab/] ## BaseURL -The `baseURL` in your [site configuration](/configuration/) must reflect the full URL of your GitLab pages repository if you are using the default GitLab Pages URL (e.g., `https://.gitlab.io//`) and not a custom domain. +The `baseURL` in your [project configuration](/configuration/) must reflect the full URL of your GitLab pages repository if you are using the default GitLab Pages URL (e.g., `https://.gitlab.io//`) and not a custom domain. ## Configure GitLab CI/CD @@ -25,8 +25,8 @@ Define your [CI/CD](g) jobs by creating a `.gitlab-ci.yml` file in the root of y variables: # Application versions DART_SASS_VERSION: 1.97.3 - HUGO_VERSION: 0.155.3 - NODE_VERSION: 24.13.0 + HUGO_VERSION: 0.156.0 + NODE_VERSION: 24.13.1 # Git GIT_DEPTH: 0 GIT_STRATEGY: clone @@ -35,7 +35,7 @@ variables: TZ: Europe/Oslo image: - name: golang:1.25.6-bookworm + name: golang:1.26.0-bookworm pages: stage: deploy @@ -91,7 +91,7 @@ pages: # Build site - echo "Building site..." - - hugo --gc --minify --baseURL "${CI_PAGES_URL}" + - hugo build --gc --minify --baseURL "${CI_PAGES_URL}" # Compress published files - echo "Compressing published files..." diff --git a/content/en/host-and-deploy/host-on-netlify/index.md b/content/en/host-and-deploy/host-on-netlify/index.md index fcca62b72..eb2eca4d4 100644 --- a/content/en/host-and-deploy/host-on-netlify/index.md +++ b/content/en/host-and-deploy/host-on-netlify/index.md @@ -31,16 +31,16 @@ Step 1 ```text {file="netlify.toml" copy=true} [build.environment] DART_SASS_VERSION = "1.97.3" - GO_VERSION = "1.25.6" - HUGO_VERSION = "0.155.3" - NODE_VERSION = "24.13.0" + GO_VERSION = "1.26.0" + HUGO_VERSION = "0.156.0" + NODE_VERSION = "24.13.1" TZ = "Europe/Oslo" [build] publish = "public" command = """\ git config core.quotepath false && \ - hugo --gc --minify --baseURL "${URL}" + hugo build --gc --minify --baseURL "${URL}" """ ``` @@ -49,9 +49,9 @@ Step 1 ```text {file="netlify.toml" copy=true} [build.environment] DART_SASS_VERSION = "1.97.3" - GO_VERSION = "1.25.6" - HUGO_VERSION = "0.155.3" - NODE_VERSION = "24.13.0" + GO_VERSION = "1.26.0" + HUGO_VERSION = "0.156.0" + NODE_VERSION = "24.13.1" TZ = "Europe/Oslo" [build] @@ -62,7 +62,7 @@ Step 1 rm "dart-sass-${DART_SASS_VERSION}-linux-x64.tar.gz" && \ export PATH="${HOME}/.local/dart-sass:${PATH}" && \ git config core.quotepath false && \ - hugo --gc --minify --baseURL "${URL}" + hugo build --gc --minify --baseURL "${URL}" """ ``` diff --git a/content/en/host-and-deploy/host-on-render/index.md b/content/en/host-and-deploy/host-on-render/index.md index bec42af64..609ff8c31 100644 --- a/content/en/host-and-deploy/host-on-render/index.md +++ b/content/en/host-and-deploy/host-on-render/index.md @@ -37,11 +37,11 @@ Step 1 - key: DART_SASS_VERSION value: 1.97.3 - key: GO_VERSION - value: 1.25.6 + value: 1.26.0 - key: HUGO_VERSION - value: 0.155.3 + value: 0.156.0 - key: NODE_VERSION - value: 24.13.0 + value: 24.13.1 - key: TZ value: Europe/Oslo ``` @@ -103,7 +103,7 @@ Step 2 # Build the site echo "Building the site..." - hugo --gc --minify --baseURL "${RENDER_EXTERNAL_URL}" + hugo build --gc --minify --baseURL "${RENDER_EXTERNAL_URL}" } diff --git a/content/en/host-and-deploy/host-on-sourcehut-pages.md b/content/en/host-and-deploy/host-on-sourcehut-pages.md index 70fd1bb96..75f3b45b5 100644 --- a/content/en/host-and-deploy/host-on-sourcehut-pages.md +++ b/content/en/host-and-deploy/host-on-sourcehut-pages.md @@ -22,7 +22,7 @@ Any and all mentions of `` refer to your actual SourceHut username ## BaseURL -The [`baseURL`][] in your site configuration must reflect the full URL provided by SourceHut Pages if you are using the default address (e.g. `https://.srht.site/`). If you want to use another domain, check the [custom domain section][] of the official documentation. +The [`baseURL`][] in your project configuration must reflect the full URL provided by SourceHut Pages if you are using the default address (e.g. `https://.srht.site/`). If you want to use another domain, check the [custom domain section][] of the official documentation. [`baseURL`]: /configuration/all/#baseurl [custom domain section]: https://srht.site/custom-domains @@ -35,7 +35,7 @@ This method does not require a paid account. To proceed you will need to create [hut]: https://sr.ht/~xenrox/hut/ ```sh -hugo +hugo build tar -C public -cvz . > site.tar.gz hut init hut pages publish -d .srht.site site.tar.gz @@ -62,7 +62,7 @@ environment: tasks: - package: | cd $site - hugo + hugo build tar -C public -cvz . > ../site.tar.gz - upload: | hut pages publish -d $site site.tar.gz @@ -93,7 +93,7 @@ tasks: export PATH="$HOME/.local/dart-sass:$PATH" sass --version # Verify installation cd $site - hugo + hugo build tar -C public -cvz . > ../site.tar.gz - upload: | hut pages publish -d $site site.tar.gz diff --git a/content/en/host-and-deploy/host-on-vercel/index.md b/content/en/host-and-deploy/host-on-vercel/index.md index fb1b8b7e7..0a0143442 100644 --- a/content/en/host-and-deploy/host-on-vercel/index.md +++ b/content/en/host-and-deploy/host-on-vercel/index.md @@ -48,9 +48,9 @@ Step 2 main() { DART_SASS_VERSION=1.97.3 - GO_VERSION=1.25.6 - HUGO_VERSION=0.155.3 - NODE_VERSION=24.13.0 + GO_VERSION=1.26.0 + HUGO_VERSION=0.156.0 + NODE_VERSION=24.13.1 export TZ=Europe/Oslo @@ -99,7 +99,7 @@ Step 2 # Build the site echo "Building the site" - hugo --gc --minify --baseURL "https://${VERCEL_PROJECT_PRODUCTION_URL}" + hugo build --gc --minify --baseURL "https://${VERCEL_PROJECT_PRODUCTION_URL}" } diff --git a/content/en/hugo-modules/use-modules.md b/content/en/hugo-modules/use-modules.md index 6a0483e76..eb15b13a7 100644 --- a/content/en/hugo-modules/use-modules.md +++ b/content/en/hugo-modules/use-modules.md @@ -1,154 +1,200 @@ --- title: Use Hugo Modules -description: How to use Hugo Modules. +description: Use modules to manage the content, layout, presentation, and behavior of your site. categories: [] keywords: [] weight: 20 aliases: [/themes/usage/,/themes/installing/,/installing-and-using-themes/] --- -## Prerequisite +> [!note] +> To work with modules you must install [Git][] and [Go][] 1.18 or later. -{{% include "/_common/gomodules-info.md" %}} +## Introduction -## Initialize a new module +{{% glossary-term module %}} -Use `hugo mod init` to initialize a new Hugo Module. If it fails to guess the module path, you must provide it as an argument, e.g.: +- Modules can be imported in any combination or sequence. +- Module imports are recursive; importing Module A can trigger the import of Module B, and so on. +- Modules can provide configuration files and directories, subject to the constraints described in the [merge configuration settings][] section of the documentation. +- External directories, including those from non-Hugo projects, can be mounted to create a [unified file system](g). + +## Import + +To import a module, first initialize the project itself as a module. For example: ```sh -hugo mod init github.com// +hugo mod init github.com/user/project ``` -Also see the [CLI Doc](/commands/hugo_mod_init/). +This will generate a [`go.mod`][] file in the project root. + +> [!note] +> The module name is a unique identifier rather than a hosting requirement. Using a name like `github.com/user/project` is a common convention but it does not mean you must use Git or host your code on GitHub. You can use any name you like if you do not plan to have others import your project as a module. For example, you could use a simple name such as `my-project` when you run the initialization command. -## Use a module for a theme +Then define one or more imports in your project configuration. This contrived example imports three modules, each containing custom shortcodes: -The easiest way to use a Module for a theme is to import it in the configuration. +{{< code-toggle file=hugo >}} +[module] + [[module.imports]] + path = 'shortcodes-a' + [[module.imports]] + path = '/home/user/shortcodes-b' + [[module.imports]] + path = 'github.com/user/shortcodes-c' +{{< /code-toggle >}} -1. Initialize the hugo module system: `hugo mod init github.com//` -1. Import the theme: +Import precedence is top-down. For example, if `shortcodes-a`, `shortcodes-b`, and `shortcodes-c` each define an `image` shortcode, the `image` shortcode from `shortcodes-a` will take effect. - {{< code-toggle file=hugo >}} - [module] - [[module.imports]] - path = "github.com/spf13/hyde" - {{< /code-toggle >}} +> [!note] +> If multiple modules contain data files or [translation tables](g) with identical paths, the data is deeply merged, following top-down precedence. -## Update modules +When you build your project, Hugo will: -Modules will be downloaded and added when you add them as imports to your configuration. See [configure modules](/configuration/module/#imports). +1. Download the modules +1. Cache them for future use +1. Generate a [`go.sum`][] file in the project root -To update or manage versions, you can use `hugo mod get`. +See [configuring module imports][] for details and options. -Some examples: +## Update -### Update all modules +When you import a module, Hugo creates `go.mod` and `go.sum` files in your project root, storing version and checksum data. Clearing the module cache and rebuilding will re-download the originally imported module version, as specified in the `go.mod` file, ensuring consistent builds. Modules can be updated to other versions as needed. + +To update a module to the latest version: ```sh -hugo mod get -u +hugo mod get -u github.com/user/shortcodes-c ``` -### Update all modules recursively +To update a module to a specific version: ```sh -hugo mod get -u ./... +hugo mod get -u github.com/user/shortcodes-c@v0.42.0 ``` -### Update one module +To update all modules to the latest version: ```sh -hugo mod get -u github.com/gohugoio/myShortcodes +hugo mod get -u ``` -### Get a specific version +To recursively update all modules to the latest version: ```sh -hugo mod get github.com/gohugoio/myShortcodes@v1.0.7 +hugo mod get -u ./... ``` -Also see the [CLI Doc](/commands/hugo_mod_get/). - -## Make and test changes in a module +## Tidy -One way to do local development of a module imported in a project is to add a replace directive to a local directory with the source in `go.mod`: +To remove unused entries from the `go.mod` and `go.sum` files: ```sh -replace github.com/bep/hugotestmods/mypartials => /Users/bep/hugotestmods/mypartials +hugo mod tidy ``` -If you have the `hugo server` running, the configuration will be reloaded and `/Users/bep/hugotestmods/mypartials` put on the watch list. +## Cache -Instead of modifying the `go.mod` files, you can also use the modules configuration [`replacements`](/configuration/module/#top-level-options) option. +Hugo caches modules to avoid repeated downloads during site builds. By default, these are stored in the `modules` directory within the [`cacheDir`][]. -## Print dependency graph +To clean the module cache for the current project: -Use `hugo mod graph` from the relevant module directory and it will print the dependency graph, including vendoring, module replacement or disabled status. - -E.g.: +```sh +hugo mod clean +``` -```txt -hugo mod graph +To clean the module cache for all projects: -github.com/bep/my-modular-site github.com/bep/hugotestmods/mymounts@v1.2.0 -github.com/bep/my-modular-site github.com/bep/hugotestmods/mypartials@v1.0.7 -github.com/bep/hugotestmods/mypartials@v1.0.7 github.com/bep/hugotestmods/myassets@v1.0.4 -github.com/bep/hugotestmods/mypartials@v1.0.7 github.com/bep/hugotestmods/myv2@v1.0.0 -DISABLED github.com/bep/my-modular-site github.com/spf13/hyde@v0.0.0-20190427180251-e36f5799b396 -github.com/bep/my-modular-site github.com/bep/hugo-fresh@v1.0.1 -github.com/bep/my-modular-site in-themesdir +```sh +hugo mod clean --all ``` -Also see the [CLI Doc](/commands/hugo_mod_graph/). +For details on cache location and eviction, see [configuring file caches][]. -## Vendor your modules +## Vendor -`hugo mod vendor` will write all the module dependencies to a `_vendor` directory, which will then be used for all subsequent builds. +{{% glossary-term vendor %}} -Note that: +Vendoring a module provides the benefits described above and allows for local inspection of its [components](g). -- You can run `hugo mod vendor` on any level in the module tree. -- Vendoring will not store modules stored in your `themes` directory. -- Most commands accept a `--ignoreVendorPaths` flag, which will then not use the vendored modules in `_vendor` for the module paths matching the given [glob pattern](g). - -Also see the [CLI Doc](/commands/hugo_mod_vendor/). +```sh +hugo mod vendor +``` -## Tidy go.mod, go.sum +This command creates a `_vendor` directory containing copies of all imported modules, used in subsequent builds. Note that: -Run `hugo mod tidy` to remove unused entries in `go.mod` and `go.sum`. +- The `hugo mod vendor` command can be run from any module tree level. +- Modules within the `themes` directory are not vendored. +- The `--ignoreVendorPaths` flag allows you to exclude vendored modules matching a [glob pattern](g) from specific commands. -Also see the [CLI Doc](/commands/hugo_mod_clean/). +> [!important] +> Instead of modifying files directly within the `_vendor` directory, override them by creating a corresponding file with the same relative path in your project's root. -## Clean module cache +To remove the vendored modules, delete the `_vendor` directory. -Run `hugo mod clean` to delete the entire modules cache. +## Replace -Note that you can also configure the `modules` cache with a `maxAge`. See [configure caches](/configuration/caches/). +For local module development, use a `replace` directive in `go.mod` pointing to your local directory: -Also see the [CLI Doc](/commands/hugo_mod_clean/). +```text +replace github.com/user/module => /home/user/projects/module +``` -## Module workspaces +With `hugo serve`r running, this change will trigger a configuration reload and add the local directory to the watch list. Alternatively, configure replacements by setting the [`replacements`][] parameter in your project configuration. -Workspace support was added in [Go 1.18](https://go.dev/blog/get-familiar-with-workspaces) and Hugo got solid support for it in the `v0.109.0` version. +## Workspace -A common use case for a workspace is to simplify local development of a site with its theme modules. +{{% glossary-term "workspace" %}} -A workspace can be configured in a `*.work` file and activated with the [module.workspace](/configuration/module/) setting, which for this use is commonly controlled via the `HUGO_MODULE_WORKSPACE` OS environment variable. +Workspaces simplify local development of sites with modules. Create a `.work` file to define a workspace, and activate it via the [`workspace`][] configuration parameter or the `HUGO_MODULE_WORKSPACE` environment variable. -See the [hugo.work](https://github.com/gohugoio/hugo/blob/master/docs/hugo.work) file in the Hugo Docs repo for an example: +A `.work` file example: ```text -go 1.20 +go 1.24 use . -use ../gohugoioTheme +use ../my-hugo-module ``` -Using the `use` directive, list all the modules you want to work on, pointing to its relative location. As in the example above, it's recommended to always include the main project (the `.`) in the list. - -With that you can start the Hugo server with that workspace enabled: +Use the `use` directive to list module paths, including the main project (`.`). Start the Hugo server with the workspace enabled: ```sh HUGO_MODULE_WORKSPACE=hugo.work hugo server --ignoreVendorPaths "**" ``` -The `--ignoreVendorPaths` flag is added above to ignore any of the vendored dependencies inside `_vendor`. If you don't use vendoring, you don't need that flag. But now the server is set up watching the files and directories in the workspace and you can see your local edits reloaded. +The `--ignoreVendorPaths` flag, used to ignore vendored dependencies (if applicable), enables live reloading of local edits within the workspace. + +## Graph + +To generate a [dependency graph](g), including vendoring, module replacement, and disabled module information, execute `hugo mod graph` within the target module directory. For example: + +```sh +$ hugo mod graph + +github.com/bep/my-modular-site github.com/bep/hugotestmods/mymounts@v1.2.0 +github.com/bep/my-modular-site github.com/bep/hugotestmods/mypartials@v1.0.7 +github.com/bep/hugotestmods/mypartials@v1.0.7 github.com/bep/hugotestmods/myassets@v1.0.4 +github.com/bep/hugotestmods/mypartials@v1.0.7 github.com/bep/hugotestmods/myv2@v1.0.0 +DISABLED github.com/bep/my-modular-site github.com/spf13/hyde@v0.0.0-20190427180251-e36f5799b396 +github.com/bep/my-modular-site github.com/bep/hugo-fresh@v1.0.1 +github.com/bep/my-modular-site in-themesdir +``` + +## Mounts + +Imported modules automatically mount their component directories to Hugo's [unified file system](g). You can also manually mount any directory, including those from non-Hugo projects, to component directories. + +See [configuring module mounts][] for details. + +[`cacheDir`]: /configuration/all/#cachedir +[`go.mod`]: https://go.dev/ref/mod#go-mod-file +[`go.sum`]: https://go.dev/ref/mod#go-sum-files +[`replacements`]: /configuration/module/#replacements +[`workspace`]: /configuration/module/#workspace +[configuring file caches]: /configuration/caches/ +[configuring module imports]: /configuration/module/#imports +[configuring module mounts]: /configuration/module/#mounts +[Git]: https://git-scm.com/book/en/v2/Getting-Started-Installing-Git +[Go]: https://go.dev/doc/install +[merge configuration settings]: /configuration/introduction/#merge-configuration-settings diff --git a/content/en/installation/linux.md b/content/en/installation/linux.md index 31fcaa90d..6e8c9cd49 100644 --- a/content/en/installation/linux.md +++ b/content/en/installation/linux.md @@ -14,7 +14,6 @@ weight: 20 ## Package managers - {{% include "/_common/installation/homebrew.md" %}} diff --git a/content/en/methods/duration/_index.md b/content/en/methods/duration/_index.md index aeb113820..4c690ecc3 100644 --- a/content/en/methods/duration/_index.md +++ b/content/en/methods/duration/_index.md @@ -1,7 +1,7 @@ --- title: Duration methods linkTitle: Duration -description: Use these methods with time.Duration values. +description: Use these methods with a time.Duration value. categories: [] keywords: [] --- diff --git a/content/en/methods/menu-entry/Children.md b/content/en/methods/menu-entry/Children.md index ecad415fa..16cec71d9 100644 --- a/content/en/methods/menu-entry/Children.md +++ b/content/en/methods/menu-entry/Children.md @@ -11,7 +11,7 @@ params: Use the `Children` method when rendering a nested menu. -With this site configuration: +With this project configuration: {{< code-toggle file=hugo >}} [[menus.main]] diff --git a/content/en/methods/menu-entry/HasChildren.md b/content/en/methods/menu-entry/HasChildren.md index 03e6cb672..59ef2e19e 100644 --- a/content/en/methods/menu-entry/HasChildren.md +++ b/content/en/methods/menu-entry/HasChildren.md @@ -11,7 +11,7 @@ params: Use the `HasChildren` method when rendering a nested menu. -With this site configuration: +With this project configuration: {{< code-toggle file=hugo >}} [[menus.main]] diff --git a/content/en/methods/menu-entry/Name.md b/content/en/methods/menu-entry/Name.md index 706d0f8c8..a00601b2d 100644 --- a/content/en/methods/menu-entry/Name.md +++ b/content/en/methods/menu-entry/Name.md @@ -11,13 +11,7 @@ params: If you define the menu entry [automatically], the `Name` method returns the page's [`LinkTitle`], falling back to its [`Title`]. -If you define the menu entry [in front matter] or [in site configuration], the `Name` method returns the `name` property of the given menu entry. If the `name` is not defined, and the menu entry resolves to a page, the `Name` returns the page [`LinkTitle`], falling back to its [`Title`]. - -[`LinkTitle`]: /methods/page/linktitle/ -[`Title`]: /methods/page/title/ -[automatically]: /content-management/menus/#define-automatically -[in front matter]: /content-management/menus/#define-in-front-matter -[in site configuration]: /content-management/menus/#define-in-site-configuration +If you define the menu entry in [front matter] or in your [project configuration], the `Name` method returns the `name` property of the given menu entry. If the `name` is not defined, and the menu entry resolves to a page, the `Name` returns the page [`LinkTitle`], falling back to its [`Title`]. ```go-html-template
      @@ -26,3 +20,9 @@ If you define the menu entry [in front matter] or [in site configuration], the ` {{ end }}
    ``` + +[`LinkTitle`]: /methods/page/linktitle/ +[`Title`]: /methods/page/title/ +[automatically]: /content-management/menus/#define-automatically +[front matter]: /content-management/menus/#define-in-front-matter +[project configuration]: /content-management/menus/#define-in-project-configuration diff --git a/content/en/methods/menu-entry/PageRef.md b/content/en/methods/menu-entry/PageRef.md index 31db24de0..8d4e53656 100644 --- a/content/en/methods/menu-entry/PageRef.md +++ b/content/en/methods/menu-entry/PageRef.md @@ -15,7 +15,7 @@ params: ## Explanation -If you specify a `pageRef` property when [defining a menu entry] in your site configuration, Hugo looks for a matching page when rendering the entry. +If you specify a `pageRef` property when [defining a menu entry] in your project configuration, Hugo looks for a matching page when rendering the entry. If a matching page is found: @@ -100,10 +100,10 @@ Hugo renders this HTML: ``` -In the above note that Hugo populates the `href` attribute of the second `anchor` element with the `pageRef` property as defined in the site configuration because the template code falls back to the `PageRef` method. +In the above note that Hugo populates the `href` attribute of the second `anchor` element with the `pageRef` property as defined in your project configuration because the template code falls back to the `PageRef` method. [`HasMenuCurrent`]: /methods/page/hasmenucurrent/ [`IsMenuCurrent`]: /methods/page/ismenucurrent/ [`Page`]: /methods/menu-entry/page/ [`URL`]: /methods/menu-entry/url/ -[defining a menu entry]: /content-management/menus/#define-in-site-configuration +[defining a menu entry]: /content-management/menus/#define-in-project-configuration diff --git a/content/en/methods/menu-entry/Params.md b/content/en/methods/menu-entry/Params.md index 20c4f7fc7..113178147 100644 --- a/content/en/methods/menu-entry/Params.md +++ b/content/en/methods/menu-entry/Params.md @@ -9,7 +9,7 @@ params: signatures: [MENUENTRY.Params] --- -When you define menu entries [in site configuration] or [in front matter], you can include a `params` key to attach additional information to the entry. For example: +When you define menu entries in your [project configuration] or in [front matter], you can include a `params` key to attach additional information to the entry. For example: {{< code-toggle file=hugo >}} [[menus.main]] @@ -57,5 +57,5 @@ Hugo renders: See the [menu templates] section for more information. [menu templates]: /templates/menu/#menu-entry-parameters -[in front matter]: /content-management/menus/#define-in-front-matter -[in site configuration]: /content-management/menus/ +[front matter]: /content-management/menus/#define-in-front-matter +[project configuration]: /content-management/menus/ diff --git a/content/en/methods/menu-entry/Weight.md b/content/en/methods/menu-entry/Weight.md index b96e2cc87..17fc3a43b 100644 --- a/content/en/methods/menu-entry/Weight.md +++ b/content/en/methods/menu-entry/Weight.md @@ -11,12 +11,7 @@ params: If you define the menu entry [automatically], the `Weight` method returns the page's [`Weight`]. -If you define the menu entry [in front matter] or [in site configuration], the `Weight` method returns the `weight` property, falling back to the page's `Weight`. - -[`Weight`]: /methods/page/weight/ -[automatically]: /content-management/menus/#define-automatically -[in front matter]: /content-management/menus/#define-in-front-matter -[in site configuration]: /content-management/menus/#define-in-site-configuration +If you define the menu entry in [front matter] or in your [project configuration], the `Weight` method returns the `weight` property, falling back to the page's `Weight`. In this contrived example, we limit the number of menu entries based on weight: @@ -29,3 +24,8 @@ In this contrived example, we limit the number of menu entries based on weight: {{ end }} ``` + +[`Weight`]: /methods/page/weight/ +[automatically]: /content-management/menus/#define-automatically +[front matter]: /content-management/menus/#define-in-front-matter +[project configuration]: /content-management/menus/#define-in-project-configuration diff --git a/content/en/methods/output-format/Rel.md b/content/en/methods/output-format/Rel.md index 1dca4b10a..4c3db9791 100644 --- a/content/en/methods/output-format/Rel.md +++ b/content/en/methods/output-format/Rel.md @@ -1,6 +1,6 @@ --- title: Rel -description: Returns the rel value of the given output format, either the default or as defined in the site configuration. +description: Returns the rel value of the given output format, either the default or as defined in your project configuration. categories: [] keywords: [] params: diff --git a/content/en/methods/page/Aliases.md b/content/en/methods/page/Aliases.md index f549ad948..217af4e99 100644 --- a/content/en/methods/page/Aliases.md +++ b/content/en/methods/page/Aliases.md @@ -50,9 +50,9 @@ Page-relative paths can also include directory traversal: | page-relative | `content/examples/a.en.md` | `../a-old` | `/en/a-old/` | | site-relative | `content/examples/a.en.md` | `/a-old` | `/en/a-old/` | -### Site configuration +### Project configuration -To implement this, you must update your site configuration to: +To implement this, you must update your project configuration to: 1. Disable the generation of default HTML redirect files by setting `disableAliases` to `true`. 1. Define a [media type][] named `text/redirects` to handle the file format. @@ -102,8 +102,8 @@ Next, create a home page template specifically for the `redirects` output format To ensure the resulting `_redirects` file is valid, the template uses the [`strings.FindRE`][] function to check for whitespace such as tabs or newlines within the alias string. If whitespace is detected, Hugo will throw an error and fail the build to prevent generating an invalid file. ```go-html-template {file="layouts/home.redirects" copy=true} -{{- if not (hugo.Store.Get "has_printed_redirects") -}} - {{- range .Sites -}} +{{- if site.IsDefault -}} + {{- range hugo.Sites -}} {{- range $p := .Pages -}} {{- range .Aliases -}} {{- if findRE `\s` . -}} @@ -113,7 +113,6 @@ To ensure the resulting `_redirects` file is valid, the template uses the [`stri {{- end -}} {{- end -}} {{- end -}} - {{- hugo.Store.Set "has_printed_redirects" true -}} {{- end -}} ``` diff --git a/content/en/methods/page/AllTranslations.md b/content/en/methods/page/AllTranslations.md index ed92cd482..27a9f932a 100644 --- a/content/en/methods/page/AllTranslations.md +++ b/content/en/methods/page/AllTranslations.md @@ -9,7 +9,7 @@ params: signatures: [PAGE.AllTranslations] --- -With this site configuration: +With this project configuration: {{< code-toggle file=hugo >}} defaultContentLanguage = 'en' diff --git a/content/en/methods/page/Data.md b/content/en/methods/page/Data.md index 387422901..3d4433a8e 100644 --- a/content/en/methods/page/Data.md +++ b/content/en/methods/page/Data.md @@ -16,7 +16,7 @@ The `Data` method on a `Page` object returns a unique data object for each [page > > Themes that are not actively maintained may still use `.Data.Pages` in their templates. Although that syntax remains functional, use one of these methods instead: [`Pages`], [`RegularPages`], or [`RegularPagesRecursive`] -The examples that follow are based on this site configuration: +The examples that follow are based on this project configuration: {{< code-toggle file=hugo >}} [taxonomies] diff --git a/content/en/methods/page/Date.md b/content/en/methods/page/Date.md index 21bf03445..ffddcf047 100644 --- a/content/en/methods/page/Date.md +++ b/content/en/methods/page/Date.md @@ -17,7 +17,7 @@ date = 2023-10-19T00:40:04-07:00 {{< /code-toggle >}} > [!note] -> The date field in front matter is often considered to be the creation date, You can change its meaning, and its effect on your site, in the site configuration. See [details]. +> The date field in front matter is often considered to be the creation date, You can change its meaning, and its effect on your project, in your project configuration. See [details]. The date is a [time.Time] value. Format and localize the value with the [`time.Format`] function, or use it with any of the [time methods]. diff --git a/content/en/methods/page/Draft.md b/content/en/methods/page/Draft.md index 482a370bf..d814d8541 100644 --- a/content/en/methods/page/Draft.md +++ b/content/en/methods/page/Draft.md @@ -9,7 +9,7 @@ params: signatures: [PAGE.Draft] --- -By default, Hugo does not publish draft pages when you build your site. To include draft pages when you build your site, use the `--buildDrafts` command line flag. +By default, Hugo does not publish draft pages when you build your project. To include draft pages when you build your project, use the `--buildDrafts` command line flag. {{< code-toggle file=content/posts/post-1.md fm=true >}} title = 'Post 1' diff --git a/content/en/methods/page/ExpiryDate.md b/content/en/methods/page/ExpiryDate.md index a72155c33..67e6b30d3 100644 --- a/content/en/methods/page/ExpiryDate.md +++ b/content/en/methods/page/ExpiryDate.md @@ -9,7 +9,7 @@ params: signatures: [PAGE.ExpiryDate] --- -By default, Hugo excludes expired pages when building your site. To include expired pages, use the `--buildExpired` command line flag. +By default, Hugo excludes expired pages when building your project. To include expired pages, use the `--buildExpired` command line flag. Set the expiry date in front matter: diff --git a/content/en/methods/page/File.md b/content/en/methods/page/File.md index 2af60a719..0bf2fdecf 100644 --- a/content/en/methods/page/File.md +++ b/content/en/methods/page/File.md @@ -81,8 +81,6 @@ content/ ### IsContentAdapter -{{< new-in 0.126.0 />}} - (`bool`) Reports whether the file is a [content adapter]. ```go-html-template diff --git a/content/en/methods/page/Fragments.md b/content/en/methods/page/Fragments.md index 1b30ac973..9df47f31c 100644 --- a/content/en/methods/page/Fragments.md +++ b/content/en/methods/page/Fragments.md @@ -71,7 +71,7 @@ To inspect the data structure: (`template.HTML`) Returns a TOC as a nested list, either ordered or unordered, identical to the HTML returned by the [`TableOfContents`] method. This method take three arguments: the start level (`int`), the end level (`int`), and a boolean (`true` to return an ordered list, `false` to return an unordered list). -Use this method when you want to control the start level, end level, or list type independently from the table of contents settings in your site configuration. +Use this method when you want to control the start level, end level, or list type independently from the table of contents settings in your project configuration. ```go-html-template {{ $startLevel := 2 }} diff --git a/content/en/methods/page/GitInfo.md b/content/en/methods/page/GitInfo.md index f09eb76b4..ef2dffa4c 100644 --- a/content/en/methods/page/GitInfo.md +++ b/content/en/methods/page/GitInfo.md @@ -18,16 +18,16 @@ The `GitInfo` method on a `Page` object returns an object with additional method Install Git, create a repository, and commit your project files. -You must also allow Hugo to access your repository. In your site configuration: +You must also allow Hugo to access your repository. In your project configuration: {{< code-toggle file=hugo >}} enableGitInfo = true {{< /code-toggle >}} -Alternatively, use the command line flag when building your site: +Alternatively, use the command line flag when building your project: ```sh -hugo --enableGitInfo +hugo build --enableGitInfo ``` > [!note] @@ -149,7 +149,7 @@ To reverse the order: By default, when `enableGitInfo` is `true`, the `Lastmod` method on a `Page` object returns the Git AuthorDate of the last commit that included the file. -You can change this behavior in your [site configuration]. +You can change this behavior in your [project configuration]. ## Hosting considerations @@ -182,4 +182,4 @@ Vercel|Shallow|Yes [^1] [details]: /configuration/front-matter/#dates [gitmailmap]: https://git-scm.com/docs/gitmailmap -[site configuration]: /configuration/front-matter/ +[project configuration]: /configuration/front-matter/ diff --git a/content/en/methods/page/HasMenuCurrent.md b/content/en/methods/page/HasMenuCurrent.md index 207882167..22bcc6483 100644 --- a/content/en/methods/page/HasMenuCurrent.md +++ b/content/en/methods/page/HasMenuCurrent.md @@ -28,6 +28,6 @@ If the `Page` object associated with the menu entry is a section, this method al See [menu templates] for a complete example. > [!note] -> When using this method you must either define the menu entry in front matter, or specify a `pageRef` property when defining the menu entry in your site configuration. +> When using this method you must either define the menu entry in front matter, or specify a `pageRef` property when defining the menu entry in your project configuration. [menu templates]: /templates/menu/#example diff --git a/content/en/methods/page/IsMenuCurrent.md b/content/en/methods/page/IsMenuCurrent.md index 9bbacd018..60b68428a 100644 --- a/content/en/methods/page/IsMenuCurrent.md +++ b/content/en/methods/page/IsMenuCurrent.md @@ -26,6 +26,6 @@ aliases: [/functions/ismenucurrent] See [menu templates] for a complete example. > [!note] -> When using this method you must either define the menu entry in front matter, or specify a `pageRef` property when defining the menu entry in your site configuration. +> When using this method you must either define the menu entry in front matter, or specify a `pageRef` property when defining the menu entry in your project configuration. [menu templates]: /templates/menu/#example diff --git a/content/en/methods/page/IsTranslated.md b/content/en/methods/page/IsTranslated.md index 2cdf911ac..6ce340ecb 100644 --- a/content/en/methods/page/IsTranslated.md +++ b/content/en/methods/page/IsTranslated.md @@ -9,7 +9,7 @@ params: signatures: [PAGE.IsTranslated] --- -With this site configuration: +With this project configuration: {{< code-toggle file=hugo >}} defaultContentLanguage = 'en' diff --git a/content/en/methods/page/Language.md b/content/en/methods/page/Language.md index 8ccc578f6..7eac722dd 100644 --- a/content/en/methods/page/Language.md +++ b/content/en/methods/page/Language.md @@ -1,6 +1,6 @@ --- title: Language -description: Returns the language object for the given page. +description: Returns the Language object for the given page. categories: [] keywords: [] params: @@ -9,13 +9,13 @@ params: signatures: [PAGE.Language] --- -The `Language` method on a `Page` object returns the language object for the given page. The language object is derived from the language definition in the site configuration. +The `Language` method on a `Page` object returns the `Language` object for the given page, derived from the language definition in your project configuration. -You can also use the `Language` method on a `Site` object. See [details]. +You can also use the `Language` method on a `Site` object. See [details][]. ## Methods -The examples below assume the following in the site configuration: +The examples below assume the following in your project configuration: {{< code-toggle file=hugo >}} [languages.de] @@ -29,7 +29,7 @@ weight = 2 {{< new-in 0.153.0 />}} -(`bool`) Reports whether this is the default language object as defined by the [`defaultContentLanguage`][] setting in the site configuration. +(`bool`) Reports whether this is the [default language][]. ```go-html-template {{ .Language.IsDefault }} → true @@ -37,7 +37,7 @@ weight = 2 ### Lang -(`string`) The language tag as defined by [RFC 5646]. This is the lower cased key from the site configuration. +(`string`) Returns the language tag as defined by [RFC 5646][]. This is the lowercased key from your project configuration. ```go-html-template {{ .Language.Lang }} → de @@ -45,7 +45,7 @@ weight = 2 ### LanguageCode -(`string`) The language code from the site configuration. Falls back to `Lang` if not defined. +(`string`) Returns the [`languageCode`][] from your project configuration. Falls back to `Lang` if not defined. ```go-html-template {{ .Language.LanguageCode }} → de-DE @@ -53,7 +53,7 @@ weight = 2 ### LanguageDirection -(`string`) The language direction from the site configuration, either `ltr` or `rtl`. +(`string`) Returns the [`languageDirection`][] from your project configuration. ```go-html-template {{ .Language.LanguageDirection }} → ltr @@ -61,7 +61,7 @@ weight = 2 ### LanguageName -(`string`) The language name from the site configuration. +(`string`) Returns the [`languageName`][] from your project configuration. ```go-html-template {{ .Language.LanguageName }} → Deutsch @@ -69,20 +69,26 @@ weight = 2 ### Name -(`string`) The language tag as defined by [RFC 5646]. This is the lower cased key used in the site configuration. This is an alias for `Lang`. +{{< new-in 0.153.0 />}} + +(`string`) Returns the language tag as defined by [RFC 5646][]. This is the lowercased key from your project configuration. This is an alias for `Lang`. ```go-html-template -{{ .Site.Language.Name }} → de +{{ .Language.Name }} → de ``` ### Weight -(`int`) The language weight from the site configuration which determines its order in the slice of languages returned by the `Languages` method on a `Site` object. +(`int`) Returns the language [`weight`][] from your project configuration. ```go-html-template {{ .Language.Weight }} → 2 ``` -[`defaultContentLanguage`]: /configuration/all/#defaultcontentlanguage -[details]: /methods/site/language/ +[`languageCode`]: /configuration/languages/#languagecode +[`languageDirection`]: /configuration/languages/#languagedirection +[`languageName`]: /configuration/languages/#languagename +[`weight`]: /configuration/languages/#weight +[default language]: /quick-reference/glossary/#default-language +[details]: /methods/page/language/ [RFC 5646]: https://datatracker.ietf.org/doc/html/rfc5646 diff --git a/content/en/methods/page/Paginate.md b/content/en/methods/page/Paginate.md index 337811240..452bf9daf 100644 --- a/content/en/methods/page/Paginate.md +++ b/content/en/methods/page/Paginate.md @@ -11,7 +11,7 @@ params: Pagination is the process of splitting a list page into two or more pagers, where each pager contains a subset of the page collection and navigation links to other pagers. -By default, the number of elements on each pager is determined by your [site configuration]. The default is `10`. Override that value by providing a second argument, an integer, when calling the `Paginate` method. +By default, the number of elements on each pager is determined by your [project configuration]. The default is `10`. Override that value by providing a second argument, an integer, when calling the `Paginate` method. > [!note] > There is also a `Paginator` method on `Page` objects, but it can neither filter nor sort the page collection. @@ -42,6 +42,6 @@ In the example above, we: [home]: /templates/types/#home [section]: /templates/types/#section -[site configuration]: /configuration/pagination/ +[project configuration]: /configuration/pagination/ [taxonomy]: /templates/types/#taxonomy [term]: /templates/types/#term diff --git a/content/en/methods/page/Paginator.md b/content/en/methods/page/Paginator.md index 02b5d5719..059e55e2d 100644 --- a/content/en/methods/page/Paginator.md +++ b/content/en/methods/page/Paginator.md @@ -11,7 +11,7 @@ params: Pagination is the process of splitting a list page into two or more pagers, where each pager contains a subset of the page collection and navigation links to other pagers. -The number of elements on each pager is determined by your [site configuration]. The default is `10`. +The number of elements on each pager is determined by your [project configuration]. The default is `10`. You can invoke pagination in [home], [section], [taxonomy], and [term] templates. Each of these receives a collection of regular pages in [context](g). When you invoke the `Paginator` method, it paginates the page collection received in context. @@ -34,7 +34,7 @@ In the example above, the embedded pagination template creates navigation links [home]: /templates/types/#home [section]: /templates/types/#section -[site configuration]: /configuration/pagination/ +[project configuration]: /configuration/pagination/ [taxonomy]: /templates/types/#taxonomy [term]: /templates/types/#term [`Paginate`]: /methods/page/paginate/ diff --git a/content/en/methods/page/Permalink.md b/content/en/methods/page/Permalink.md index cc74f3342..ffd6ede0b 100644 --- a/content/en/methods/page/Permalink.md +++ b/content/en/methods/page/Permalink.md @@ -9,7 +9,7 @@ params: signatures: [PAGE.Permalink] --- -Site configuration: +Project configuration: {{< code-toggle file=hugo >}} title = 'Documentation' diff --git a/content/en/methods/page/PublishDate.md b/content/en/methods/page/PublishDate.md index 7500a08aa..ec3c13377 100644 --- a/content/en/methods/page/PublishDate.md +++ b/content/en/methods/page/PublishDate.md @@ -9,7 +9,7 @@ params: signatures: [PAGE.PublishDate] --- -By default, Hugo excludes pages with future publish dates when building your site. To include future pages, use the `--buildFuture` command line flag. +By default, Hugo excludes pages with future publish dates when building your project. To include future pages, use the `--buildFuture` command line flag. Set the publish date in front matter: diff --git a/content/en/methods/page/RelPermalink.md b/content/en/methods/page/RelPermalink.md index a3c610d50..ba03dc1bb 100644 --- a/content/en/methods/page/RelPermalink.md +++ b/content/en/methods/page/RelPermalink.md @@ -9,7 +9,7 @@ params: signatures: [PAGE.RelPermalink] --- -Site configuration: +Project configuration: {{< code-toggle file=hugo >}} title = 'Documentation' diff --git a/content/en/methods/page/Rotate.md b/content/en/methods/page/Rotate.md index 99cb69cc8..643945d85 100644 --- a/content/en/methods/page/Rotate.md +++ b/content/en/methods/page/Rotate.md @@ -1,6 +1,6 @@ --- title: Rotate -description: Returns a collection of all pages sharing the same identity across the specified dimension, including the current page, sorted by the dimension's weight. +description: Returns a collection of pages that vary along the specified dimension while sharing the current page's values for the other dimensions, including the current page, sorted by the dimension's default sort order. categories: [] keywords: [] params: @@ -11,36 +11,45 @@ params: {{< new-in 0.153.0 />}} -The `Rotate` method on a `Page` object returns a collection of all pages sharing the same identity across the specified [dimension](g), including the current page, sorted by the dimension's weight. +The rotate method on a page object returns a collection of pages that vary along the specified [dimension](g), while holding the other dimensions constant. The result includes the current page and is sorted according to the rules of the specified dimension. For example, rotating along [language](g) returns all language variants that share the current page's [version](g) and [role](g). -The `DIMENSION` argument must be one of `language`, `role`, or `version`. +The `DIMENSION` argument must be one of `language`, `version`, or `role`. -To render a list of all translations of the current page, including the current page: +## Sort order + +Use the following rules to understand how Hugo sorts the collection returned by the `Rotate` method. + +| Dimension | Primary Sort | Secondary Sort | +| :--- | :--- | :--- | +| Language | Weight ascending | Lexicographical ascending | +| Version | Weight ascending | Semantic version descending | +| Role | Weight ascending | Lexicographical ascending | + +## Examples + +To render a list of the current page's language variants, including the current page, while sharing its current version and role: ```go-html-template -{{ with .Rotate "language" }} - {{ range . }} -

    {{ .LinkTitle }}

    - {{ end }} +{{/* Returns languages sorted by weight ascending, then lexicographically ascending */}} +{{ range .Rotate "language" }} +

    {{ .LinkTitle }}

    {{ end }} ``` -To render a list of all [roles](g) of the current page, including the current page: +To render a list of the current page's version variants, including the current page, while sharing its current language and role: ```go-html-template -{{ with .Rotate "role" }} - {{ range . }} -

    {{ .LinkTitle }}

    - {{ end }} +{{/* Returns versions sorted by weight ascending, then semantic version descending */}} +{{ range .Rotate "version" }} +

    {{ .LinkTitle }}

    {{ end }} ``` -To render a list of all versions of the current page, including the current page: +To render a list of the current page's role variants, including the current page, while sharing its current language and version: ```go-html-template -{{ with .Rotate "version" }} - {{ range . }} -

    {{ .LinkTitle }}

    - {{ end }} +{{/* Returns roles sorted by weight ascending, then lexicographically ascending */}} +{{ range .Rotate "role" }} +

    {{ .LinkTitle }}

    {{ end }} ``` diff --git a/content/en/methods/page/Sitemap.md b/content/en/methods/page/Sitemap.md index 5dafb86b2..1d40f48b1 100644 --- a/content/en/methods/page/Sitemap.md +++ b/content/en/methods/page/Sitemap.md @@ -39,7 +39,7 @@ Access to the `Sitemap` method on a `Page` object is restricted to [sitemap temp ## Example -With this site configuration: +With this project configuration: {{< code-toggle file=hugo >}} [sitemap] diff --git a/content/en/methods/page/Sites.md b/content/en/methods/page/Sites.md index 308376680..98aeeab02 100644 --- a/content/en/methods/page/Sites.md +++ b/content/en/methods/page/Sites.md @@ -1,23 +1,32 @@ --- title: Sites -description: Returns a collection of all Site objects, one for each language, ordered by language weight. +description: Returns a collection of all sites for all dimensions. categories: [] keywords: [] params: functions_and_methods: returnType: page.Sites signatures: [PAGE.Sites] +expiryDate: '2028-02-18' # deprecated 2026-02-18 in v0.156.0 --- -This is a convenience method to access `.Site.Sites`. +{{< deprecated-in 0.156.0 >}} +Use [`hugo.Sites`] instead. -With this site configuration: +[`hugo.Sites`]: /functions/hugo/sites/ +{{< /deprecated-in >}} + +{{% include "/_common/functions/hugo/sites-collection.md" %}} + +With this project configuration: {{< code-toggle file=hugo >}} defaultContentLanguage = 'de' -defaultContentLanguageInSubdir = false +defaultContentLanguageInSubdir = true +defaultContentVersionInSubdir = true [languages.de] +contentDir = 'content/de' languageCode = 'de-DE' languageDirection = 'ltr' languageName = 'Deutsch' @@ -25,11 +34,16 @@ title = 'Projekt Dokumentation' weight = 1 [languages.en] +contentDir = 'content/en' languageCode = 'en-US' languageDirection = 'ltr' languageName = 'English' title = 'Project Documentation' weight = 2 + +[versions.'v1.0.0'] +[versions.'v2.0.0'] +[versions.'v3.0.0'] {{< /code-toggle >}} This template: @@ -37,7 +51,7 @@ This template: ```go-html-template ``` @@ -46,8 +60,12 @@ Produces a list of links to each home page: ```html ``` @@ -55,7 +73,7 @@ To render a link to the home page of the [default site](g): ```go-html-template {{ with .Sites.Default }} - {{ .Title }} + {{ .Title }} {{ end }} ``` @@ -63,6 +81,6 @@ This is equivalent to: ```go-html-template {{ with index .Sites 0 }} - {{ .Title }} + {{ .Title }} {{ end }} ``` diff --git a/content/en/methods/page/TableOfContents.md b/content/en/methods/page/TableOfContents.md index f44d660ae..d5ae21639 100644 --- a/content/en/methods/page/TableOfContents.md +++ b/content/en/methods/page/TableOfContents.md @@ -37,7 +37,7 @@ Produces this HTML: ``` -By default, the `TableOfContents` method returns an unordered list of level 2 and level 3 headings. You can adjust this in your site configuration: +By default, the `TableOfContents` method returns an unordered list of level 2 and level 3 headings. You can adjust this in your project configuration: {{< code-toggle file=hugo >}} [markup.tableOfContents] diff --git a/content/en/methods/page/Title.md b/content/en/methods/page/Title.md index 2201266a7..5135c5ac4 100644 --- a/content/en/methods/page/Title.md +++ b/content/en/methods/page/Title.md @@ -28,14 +28,14 @@ section|section name (capitalized and pluralized) taxonomy|taxonomy name (capitalized and pluralized) term|term name (capitalized and pluralized) -You can disable automatic capitalization and pluralization in your site configuration: +You can disable automatic capitalization and pluralization in your project configuration: {{< code-toggle file=hugo >}} capitalizeListTitles = false pluralizeListTitles = false {{< /code-toggle >}} -You can change the capitalization style in your site configuration to one of `ap`, `chicago`, `go`, `firstupper`, or `none`. For example: +You can change the capitalization style in your project configuration to one of `ap`, `chicago`, `go`, `firstupper`, or `none`. For example: {{< code-toggle file=hugo >}} titleCaseStyle = "firstupper" diff --git a/content/en/methods/page/TranslationKey.md b/content/en/methods/page/TranslationKey.md index 1e930687e..2f6b8f308 100644 --- a/content/en/methods/page/TranslationKey.md +++ b/content/en/methods/page/TranslationKey.md @@ -11,7 +11,7 @@ params: The translation key creates a relationship between all translations of a given page. The translation key is derived from the file path, or from the `translationKey` parameter if defined in front matter. -With this site configuration: +With this project configuration: {{< code-toggle file=hugo >}} defaultContentLanguage = 'en' diff --git a/content/en/methods/page/Translations.md b/content/en/methods/page/Translations.md index c342a8618..58f9024f7 100644 --- a/content/en/methods/page/Translations.md +++ b/content/en/methods/page/Translations.md @@ -9,7 +9,7 @@ params: signatures: [PAGE.Translations] --- -With this site configuration: +With this project configuration: {{< code-toggle file=hugo >}} defaultContentLanguage = 'en' diff --git a/content/en/methods/pager/PagerSize.md b/content/en/methods/pager/PagerSize.md index b2397a3e8..13aa6c1cd 100644 --- a/content/en/methods/pager/PagerSize.md +++ b/content/en/methods/pager/PagerSize.md @@ -11,10 +11,10 @@ params: {{< new-in 0.128.0 />}} -The number of pages per pager is determined by the optional second argument passed to the [`Paginate`] method, falling back to the `pagerSize` as defined in your [site configuration]. +The number of pages per pager is determined by the optional second argument passed to the [`Paginate`] method, falling back to the `pagerSize` as defined in your [project configuration]. [`Paginate`]: /methods/page/paginate/ -[site configuration]: /templates/pagination/#configuration +[project configuration]: /templates/pagination/#configuration ```go-html-template {{ $pages := where site.RegularPages "Type" "posts" }} diff --git a/content/en/methods/pager/_index.md b/content/en/methods/pager/_index.md index 7a79bf42f..200640c3a 100644 --- a/content/en/methods/pager/_index.md +++ b/content/en/methods/pager/_index.md @@ -1,6 +1,6 @@ --- title: Pager methods linkTitle: Pager -description: Use these methods with Pager objects when building navigation for a paginated list page. +description: Use these methods with a Pager object when building navigation for a paginated list page. keywords: [] --- diff --git a/content/en/methods/pages/ByDate.md b/content/en/methods/pages/ByDate.md index 18f1b985e..5d1e339a0 100644 --- a/content/en/methods/pages/ByDate.md +++ b/content/en/methods/pages/ByDate.md @@ -9,9 +9,9 @@ params: signatures: [PAGES.ByDate] --- -When sorting by date, the value is determined by your [site configuration], defaulting to the `date` field in front matter. +When sorting by date, the value is determined by your [project configuration], defaulting to the `date` field in front matter. -[site configuration]: /configuration/front-matter/#dates +[project configuration]: /configuration/front-matter/#dates ```go-html-template {{ range .Pages.ByDate }} diff --git a/content/en/methods/pages/ByExpiryDate.md b/content/en/methods/pages/ByExpiryDate.md index 703988c4e..4f34c6e03 100644 --- a/content/en/methods/pages/ByExpiryDate.md +++ b/content/en/methods/pages/ByExpiryDate.md @@ -9,9 +9,9 @@ params: signatures: [PAGES.ByExpiryDate] --- -When sorting by expiration date, the value is determined by your [site configuration], defaulting to the `expiryDate` field in front matter. +When sorting by expiration date, the value is determined by your [project configuration], defaulting to the `expiryDate` field in front matter. -[site configuration]: /configuration/front-matter/#dates +[project configuration]: /configuration/front-matter/#dates ```go-html-template {{ range .Pages.ByExpiryDate }} diff --git a/content/en/methods/pages/ByLanguage.md b/content/en/methods/pages/ByLanguage.md index 36244eb4d..751e1d8f5 100644 --- a/content/en/methods/pages/ByLanguage.md +++ b/content/en/methods/pages/ByLanguage.md @@ -1,6 +1,6 @@ --- title: ByLanguage -description: Returns the given page collection sorted by language in ascending order. +description: Returns the given page collection sorted by language. categories: [] keywords: [] params: @@ -9,8 +9,25 @@ params: signatures: [PAGES.ByLanguage] --- +When sorting by language, Hugo orders the page collection using the following priority: + +1. Language weight (ascending) +1. Date (descending) +1. LinkTitle (ascending) + +This method is rarely, if ever, needed. Page collections that already contain multiple languages, such as those returned by the [`Rotate`][], [`Translations`][], or [`AllTranslations`][] methods on a `Page` object, are already sorted by language weight. + +This contrived example aggregates pages from all sites and then sorts them by language: + ```go-html-template -{{ range .Site.AllPages.ByLanguage }} +{{ $p := slice }} +{{ range hugo.Sites }} + {{ range .Pages }} + {{ $p = $p | append . }} + {{ end }} +{{ end }} + +{{ range $p.ByLanguage }}

    {{ .LinkTitle }}

    {{ end }} ``` @@ -18,7 +35,11 @@ params: To sort in descending order: ```go-html-template -{{ range .Site.AllPages.ByLanguage.Reverse }} +{{ range $p.ByLanguage.Reverse }}

    {{ .LinkTitle }}

    {{ end }} ``` + +[`AllTranslations`]: /methods/page/alltranslations/ +[`Rotate`]: /methods/page/rotate/ +[`Translations`]: /methods/page/translations/ diff --git a/content/en/methods/pages/ByLastmod.md b/content/en/methods/pages/ByLastmod.md index 3c03d2a6e..7fc865e0a 100644 --- a/content/en/methods/pages/ByLastmod.md +++ b/content/en/methods/pages/ByLastmod.md @@ -9,9 +9,9 @@ params: signatures: [PAGES.ByLastmod] --- -When sorting by last modification date, the value is determined by your [site configuration], defaulting to the `lastmod` field in front matter. +When sorting by last modification date, the value is determined by your [project configuration], defaulting to the `lastmod` field in front matter. -[site configuration]: /configuration/front-matter/#dates +[project configuration]: /configuration/front-matter/#dates ```go-html-template {{ range .Pages.ByLastmod }} diff --git a/content/en/methods/pages/ByParam.md b/content/en/methods/pages/ByParam.md index 9544122a6..fcc9b287f 100644 --- a/content/en/methods/pages/ByParam.md +++ b/content/en/methods/pages/ByParam.md @@ -9,7 +9,7 @@ params: signatures: [PAGES.ByParam PARAM] --- -If the given parameter is not present in front matter, Hugo will use the matching parameter in your site configuration if present. +If the given parameter is not present in front matter, Hugo will use the matching parameter in your project configuration if present. ```go-html-template {{ range .Pages.ByParam "author" }} diff --git a/content/en/methods/pages/ByPublishDate.md b/content/en/methods/pages/ByPublishDate.md index 3dde6fd95..76d2b2b58 100644 --- a/content/en/methods/pages/ByPublishDate.md +++ b/content/en/methods/pages/ByPublishDate.md @@ -9,9 +9,9 @@ params: signatures: [PAGES.ByPublishDate] --- -When sorting by publish date, the value is determined by your [site configuration], defaulting to the `publishDate` field in front matter. +When sorting by publish date, the value is determined by your [project configuration], defaulting to the `publishDate` field in front matter. -[site configuration]: /configuration/front-matter/#dates +[project configuration]: /configuration/front-matter/#dates ```go-html-template {{ range .Pages.ByPublishDate }} diff --git a/content/en/methods/pages/GroupByDate.md b/content/en/methods/pages/GroupByDate.md index 7ef4843a4..19f791886 100644 --- a/content/en/methods/pages/GroupByDate.md +++ b/content/en/methods/pages/GroupByDate.md @@ -9,13 +9,13 @@ params: signatures: ['PAGES.GroupByDate LAYOUT [SORT]'] --- -When grouping by date, the value is determined by your [site configuration], defaulting to the `date` field in front matter. +When grouping by date, the value is determined by your [project configuration], defaulting to the `date` field in front matter. The [layout string] has the same format as the layout string for the [`time.Format`] function. The resulting group key is [localized](g) for language and region. [`time.Format`]: /functions/time/format/ [layout string]: #layout-string -[site configuration]: /configuration/front-matter/#dates +[project configuration]: /configuration/front-matter/#dates {{% include "/_common/methods/pages/group-sort-order.md" %}} diff --git a/content/en/methods/pages/GroupByExpiryDate.md b/content/en/methods/pages/GroupByExpiryDate.md index d209e6c2b..7fe0282c2 100644 --- a/content/en/methods/pages/GroupByExpiryDate.md +++ b/content/en/methods/pages/GroupByExpiryDate.md @@ -9,13 +9,13 @@ params: signatures: ['PAGES.GroupByExpiryDate LAYOUT [SORT]'] --- -When grouping by expiration date, the value is determined by your [site configuration], defaulting to the `expiryDate` field in front matter. +When grouping by expiration date, the value is determined by your [project configuration], defaulting to the `expiryDate` field in front matter. The [layout string] has the same format as the layout string for the [`time.Format`] function. The resulting group key is [localized](g) for language and region. [`time.Format`]: /functions/time/format/ [layout string]: #layout-string -[site configuration]: /configuration/front-matter/#dates +[project configuration]: /configuration/front-matter/#dates {{% include "/_common/methods/pages/group-sort-order.md" %}} diff --git a/content/en/methods/pages/GroupByLastmod.md b/content/en/methods/pages/GroupByLastmod.md index 8729cd3c9..45da5af31 100644 --- a/content/en/methods/pages/GroupByLastmod.md +++ b/content/en/methods/pages/GroupByLastmod.md @@ -9,13 +9,13 @@ params: signatures: ['PAGES.GroupByLastmod LAYOUT [SORT]'] --- -When grouping by last modification date, the value is determined by your [site configuration], defaulting to the `lastmod` field in front matter. +When grouping by last modification date, the value is determined by your [project configuration], defaulting to the `lastmod` field in front matter. The [layout string] has the same format as the layout string for the [`time.Format`] function. The resulting group key is [localized](g) for language and region. [`time.Format`]: /functions/time/format/ [layout string]: #layout-string -[site configuration]: /configuration/front-matter/#dates +[project configuration]: /configuration/front-matter/#dates {{% include "/_common/methods/pages/group-sort-order.md" %}} diff --git a/content/en/methods/pages/GroupByPublishDate.md b/content/en/methods/pages/GroupByPublishDate.md index 50e12f085..629a8480a 100644 --- a/content/en/methods/pages/GroupByPublishDate.md +++ b/content/en/methods/pages/GroupByPublishDate.md @@ -9,13 +9,13 @@ params: signatures: ['PAGES.GroupByPublishDate LAYOUT [SORT]'] --- -When grouping by publish date, the value is determined by your [site configuration], defaulting to the `publishDate` field in front matter. +When grouping by publish date, the value is determined by your [project configuration], defaulting to the `publishDate` field in front matter. The [layout string] has the same format as the layout string for the [`time.Format`] function. The resulting group key is [localized](g) for language and region. [`time.Format`]: /functions/time/format/ [layout string]: #layout-string -[site configuration]: /configuration/front-matter/#dates +[project configuration]: /configuration/front-matter/#dates {{% include "/_common/methods/pages/group-sort-order.md" %}} diff --git a/content/en/methods/resource/Exif.md b/content/en/methods/resource/Exif.md index 4df1eef5b..e1cd2ab59 100644 --- a/content/en/methods/resource/Exif.md +++ b/content/en/methods/resource/Exif.md @@ -34,7 +34,7 @@ To extract [Exif][Exif_Definition], [IPTC][IPTC_Definition], and [XMP][XMP_Defin ### Tags -(`meta.Tags`) Returns a collection of available Exif fields for this image. Availability is determined by the [`includeFields`][] and [`excludeFields`][] settings in your site configuration. +(`meta.Tags`) Returns a collection of available Exif fields for this image. Availability is determined by the [`includeFields`][] and [`excludeFields`][] settings in your project configuration. ## Examples diff --git a/content/en/methods/resource/Meta.md b/content/en/methods/resource/Meta.md index a1c8a9010..b02e99862 100644 --- a/content/en/methods/resource/Meta.md +++ b/content/en/methods/resource/Meta.md @@ -55,15 +55,15 @@ Value|Description ### Exif -(`meta.Tags`) Returns a collection of available Exif fields for this image. Availability is determined by the [`sources`][] setting and specific fields are managed via the [`fields`][] setting, both of which are managed in your site configuration. +(`meta.Tags`) Returns a collection of available Exif fields for this image. Availability is determined by the [`sources`][] setting and specific fields are managed via the [`fields`][] setting, both of which are managed in your project configuration. ### IPTC -(`meta.Tags`) Returns a collection of available IPTC fields for this image. Availability is determined by the [`sources`][] setting and specific fields are managed via the [`fields`][] setting, both of which are managed in your site configuration. +(`meta.Tags`) Returns a collection of available IPTC fields for this image. Availability is determined by the [`sources`][] setting and specific fields are managed via the [`fields`][] setting, both of which are managed in your project configuration. ### XMP -(`meta.Tags`) Returns a collection of available XMP fields for this image. Availability is determined by the [`sources`][] setting and specific fields are managed via the [`fields`][] setting, both of which are managed in your site configuration. +(`meta.Tags`) Returns a collection of available XMP fields for this image. Availability is determined by the [`sources`][] setting and specific fields are managed via the [`fields`][] setting, both of which are managed in your project configuration. ## Examples diff --git a/content/en/methods/resource/_index.md b/content/en/methods/resource/_index.md index edfbc5b14..c6012e75b 100644 --- a/content/en/methods/resource/_index.md +++ b/content/en/methods/resource/_index.md @@ -1,7 +1,7 @@ --- title: Resource methods linkTitle: Resource -description: Use these methods with global, page, and remote Resource objects. +description: Use these methods with a global, page, or remote Resource object. categories: [] keywords: [] --- diff --git a/content/en/methods/site/AllPages.md b/content/en/methods/site/AllPages.md index 90cceee8c..aec40d558 100644 --- a/content/en/methods/site/AllPages.md +++ b/content/en/methods/site/AllPages.md @@ -7,8 +7,13 @@ params: functions_and_methods: returnType: page.Pages signatures: [SITE.AllPages] +expiryDate: '2028-02-18' # deprecated 2026-02-18 in v0.156.0 --- +{{< deprecated-in 0.156.0 >}} +See [details](https://discourse.gohugo.io/t/56732). +{{< /deprecated-in >}} + This method returns all page [kinds](g) in all languages, in the [default sort order](g). That includes the home page, section pages, taxonomy pages, term pages, and regular pages. In most cases you should use the [`RegularPages`] method instead. diff --git a/content/en/methods/site/BaseURL.md b/content/en/methods/site/BaseURL.md index 3644443cb..7b1b5e870 100644 --- a/content/en/methods/site/BaseURL.md +++ b/content/en/methods/site/BaseURL.md @@ -1,6 +1,6 @@ --- title: BaseURL -description: Returns the base URL as defined in the site configuration. +description: Returns the base URL as defined in your project configuration. categories: [] keywords: [] params: @@ -9,7 +9,7 @@ params: signatures: [SITE.BaseURL] --- -Site configuration: +Project configuration: {{< code-toggle file=hugo >}} baseURL = 'https://example.org/docs/' diff --git a/content/en/methods/site/BuildDrafts.md b/content/en/methods/site/BuildDrafts.md index 4beceeb6b..7b5019ffe 100644 --- a/content/en/methods/site/BuildDrafts.md +++ b/content/en/methods/site/BuildDrafts.md @@ -1,21 +1,26 @@ --- title: BuildDrafts -description: Reports whether the current build includes draft pages. +description: Reports reports whether draft publishing is enabled for the current build. categories: [] keywords: [] params: functions_and_methods: returnType: bool signatures: [SITE.BuildDrafts] +expiryDate: '2028-02-18' # deprecated 2026-02-18 in v0.156.0 --- +{{< deprecated-in 0.156.0 >}} +See [details](https://discourse.gohugo.io/t/56732). +{{< /deprecated-in >}} + By default, draft pages are not published when building a site. You can change this behavior with a command line flag: ```sh -hugo --buildDrafts +hugo build --buildDrafts ``` -Or by setting `buildDrafts` to `true` in your site configuration: +Or by setting `buildDrafts` to `true` in your project configuration: {{< code-toggle file=hugo >}} buildDrafts = true diff --git a/content/en/methods/site/Config.md b/content/en/methods/site/Config.md index d1b4d1f42..9cc885650 100644 --- a/content/en/methods/site/Config.md +++ b/content/en/methods/site/Config.md @@ -1,6 +1,6 @@ --- title: Config -description: Returns a subset of the site configuration. +description: Returns a subset of your project configuration. categories: [] keywords: [] params: @@ -9,7 +9,7 @@ params: signatures: [SITE.Config] --- -The `Config` method on a `Site` object provides access to a subset of the site configuration, specifically the `services` and `privacy` keys. +The `Config` method on a `Site` object provides access to a subset of your project configuration, specifically the `services` and `privacy` keys. ## Services diff --git a/content/en/methods/site/Copyright.md b/content/en/methods/site/Copyright.md index dd8bdb4a3..e73ff66bc 100644 --- a/content/en/methods/site/Copyright.md +++ b/content/en/methods/site/Copyright.md @@ -1,6 +1,6 @@ --- title: Copyright -description: Returns the copyright notice as defined in the site configuration. +description: Returns the copyright notice as defined in your project configuration. categories: [] keywords: [] params: @@ -9,7 +9,7 @@ params: signatures: [SITE.Copyright] --- -Site configuration: +Project configuration: {{< code-toggle file=hugo >}} copyright = '© 2023 ABC Widgets, Inc.' diff --git a/content/en/methods/site/Data.md b/content/en/methods/site/Data.md index 296851874..e54bad0f1 100644 --- a/content/en/methods/site/Data.md +++ b/content/en/methods/site/Data.md @@ -7,8 +7,13 @@ params: functions_and_methods: returnType: map signatures: [SITE.Data] +expiryDate: '2028-02-18' # deprecated 2026-02-18 in v0.156.0 --- +{{< deprecated-in 0.156.0 >}} +Use [`hugo.Data`](/functions/hugo/data/) instead. +{{< /deprecated-in >}} + Use the `Data` method on a `Site` object to access data within the `data` directory, or within any directory [mounted] to the `data` directory. Supported data formats include JSON, TOML, YAML, and XML. > [!note] diff --git a/content/en/methods/site/Dimension.md b/content/en/methods/site/Dimension.md index 67297a353..7c2001640 100644 --- a/content/en/methods/site/Dimension.md +++ b/content/en/methods/site/Dimension.md @@ -13,24 +13,24 @@ params: The `Dimension` method on a `Site` object returns the dimension object for the given [dimension](g). -The `DIMENSION` argument must be one of `language`, `role`, or `version`. +The `DIMENSION` argument must be one of `language`, `version`, or `role`. Example|Returns|Equivalent to :--|:--|:-- `{{ .Site.Dimension "language" }}`|`langs.Language`|`{{ .Site.Language }}` -`{{ .Site.Dimension "role" }}`|`roles.Role`|`{{ .Site.Role }}` `{{ .Site.Dimension "version" }}`|`version.Version`|`{{ .Site.Version }}` +`{{ .Site.Dimension "role" }}`|`roles.Role`|`{{ .Site.Role }}` ```go-html-template {{ $languageObject := .Site.Dimension "language" }} {{ $languageObject.IsDefault }} → true {{ $languageObject.Name }} → en -{{ $roleObject := .Site.Dimension "role" }} -{{ $roleObject.IsDefault }} → true -{{ $roleObject.Name }} → guest - {{ $versionObject := .Site.Dimension "version" }} {{ $versionObject.IsDefault }} → true {{ $versionObject.Name }} → v1.0.0 + +{{ $roleObject := .Site.Dimension "role" }} +{{ $roleObject.IsDefault }} → true +{{ $roleObject.Name }} → guest ``` diff --git a/content/en/methods/site/GetPage.md b/content/en/methods/site/GetPage.md index 34f531720..f21061a35 100644 --- a/content/en/methods/site/GetPage.md +++ b/content/en/methods/site/GetPage.md @@ -71,7 +71,7 @@ With multilingual projects, the `GetPage` method on a `Site` object resolves the To get a page from a different language, query the `Sites` object: ```go-html-template -{{ with where .Site.Sites "Language.Lang" "eq" "de" }} +{{ with where hugo.Sites "Language.Lang" "eq" "de" }} {{ with index . 0 }} {{ with .GetPage "/works/paintings/starry-night" }} {{ .Title }} → Sternenklare Nacht diff --git a/content/en/methods/site/Home.md b/content/en/methods/site/Home.md index 11ce617ef..57b2ceaae 100644 --- a/content/en/methods/site/Home.md +++ b/content/en/methods/site/Home.md @@ -23,7 +23,7 @@ Because it returns a `Page` object, you can use any of the available [page metho This method is commonly used to generate a link to the home page. For example: -Site configuration: +Project configuration: {{< code-toggle file=hugo >}} baseURL = 'https://example.org/docs/' diff --git a/content/en/methods/site/IsDefault.md b/content/en/methods/site/IsDefault.md new file mode 100644 index 000000000..251a3bbe4 --- /dev/null +++ b/content/en/methods/site/IsDefault.md @@ -0,0 +1,50 @@ +--- +title: IsDefault +description: Reports whether the given site is the default site across all dimensions. +categories: [] +keywords: [] +params: + functions_and_methods: + returnType: bool + signatures: [SITE.IsDefault] +--- + +{{< new-in 0.156.0 />}} + +The `IsDefault` method on a `Site` object reports whether the given site is the [default site](g) across all dimensions: [language](g), [version](g), and [role](g). This is useful to ensure that a block of code executes only once per build, regardless of the number of [sites](g) generated by your [dimensions](g). + +For example, the following configuration defines a matrix of sites across language and version dimensions. + +{{< code-toggle file=hugo >}} +[languages.de] +contentDir = 'content/de' +languageCode = 'de-DE' +languageDirection = 'ltr' +languageName = 'Deutsch' +title = 'Projekt Dokumentation' +weight = 1 + +[languages.en] +contentDir = 'content/en' +languageCode = 'en-US' +languageDirection = 'ltr' +languageName = 'English' +title = 'Project Documentation' +weight = 2 + +[versions.'v1.0.0'] +[versions.'v2.0.0'] +[versions.'v3.0.0'] +{{< /code-toggle >}} + +If you call an initialization partial to handle one-time build logic or global variable setup, wrap that call in an [`if`][] statement using this function. This prevents the logic from being executed for every dimensional variation. + +```go-html-template +{{ if .Site.IsDefault }} + {{ partial "init.html" . }} +{{ end }} +``` + +In this setup, the code block is only executed for the English version v3.0.0 site. English is selected because it has the lowest weight, and version v3.0.0 is selected because it is the first version when sorted semantically in descending order. + +[`if`]: /functions/go-template/if/ diff --git a/content/en/methods/site/Language.md b/content/en/methods/site/Language.md index 2550ad585..8e8cb7372 100644 --- a/content/en/methods/site/Language.md +++ b/content/en/methods/site/Language.md @@ -1,6 +1,6 @@ --- title: Language -description: Returns the language object for the given site. +description: Returns the Language object for the given site. categories: [] keywords: [] params: @@ -9,13 +9,13 @@ params: signatures: [SITE.Language] --- -The `Language` method on a `Page` object returns the language object for the given page. The language object is derived from the language definition in the site configuration. +The `Language` method on a `Site` object returns the `Language` object for the given site, derived from the language definition in your project configuration. -You can also use the `Language` method on a `Page` object. See [details]. +You can also use the `Language` method on a `Page` object. See [details][]. ## Methods -The examples below assume the following in the site configuration: +The examples below assume the following in your project configuration: {{< code-toggle file=hugo >}} [languages.de] @@ -29,7 +29,7 @@ weight = 1 {{< new-in 0.153.0 />}} -(`bool`) Reports whether this is the default language object as defined by the [`defaultContentLanguage`][] setting in the site configuration. +(`bool`) Reports whether this is the [default language][]. ```go-html-template {{ .Site.Language.IsDefault }} → true @@ -37,7 +37,7 @@ weight = 1 ### Lang -(`string`) The language tag as defined by [RFC 5646]. This is the lower cased key from the site configuration. +(`string`) Returns the language tag as defined by [RFC 5646][]. This is the lowercased key from your project configuration. ```go-html-template {{ .Site.Language.Lang }} → de @@ -45,7 +45,7 @@ weight = 1 ### LanguageCode -(`string`) The language code from the site configuration. Falls back to `Lang` if not defined. +(`string`) Returns the [`languageCode`][] from your project configuration. Falls back to `Lang` if not defined. ```go-html-template {{ .Site.Language.LanguageCode }} → de-DE @@ -53,7 +53,7 @@ weight = 1 ### LanguageDirection -(`string`) The language direction from the site configuration, either `ltr` or `rtl`. +(`string`) Returns the [`languageDirection`][] from your project configuration. ```go-html-template {{ .Site.Language.LanguageDirection }} → ltr @@ -61,7 +61,7 @@ weight = 1 ### LanguageName -(`string`) The language name from the site configuration. +(`string`) Returns the [`languageName`][] from your project configuration. ```go-html-template {{ .Site.Language.LanguageName }} → Deutsch @@ -69,7 +69,9 @@ weight = 1 ### Name -(`string`) The language tag as defined by [RFC 5646]. This is the lower cased key from the site configuration. This is an alias for `Lang`. +{{< new-in 0.153.0 />}} + +(`string`) Returns the language tag as defined by [RFC 5646][]. This is the lowercased key from your project configuration. This is an alias for `Lang`. ```go-html-template {{ .Site.Language.Name }} → de @@ -77,7 +79,7 @@ weight = 1 ### Weight -(`int`) The language weight from the site configuration which determines its order in the slice of languages returned by the `Languages` method on a `Site` object. +(`int`) Returns the language [`weight`][] from your project configuration. ```go-html-template {{ .Site.Language.Weight }} → 1 @@ -94,6 +96,10 @@ Some of the methods above are commonly used in a base template as attributes for > ``` -[`defaultContentLanguage`]: /configuration/all/#defaultcontentlanguage +[`languageCode`]: /configuration/languages/#languagecode +[`languageDirection`]: /configuration/languages/#languagedirection +[`languageName`]: /configuration/languages/#languagename +[`weight`]: /configuration/languages/#weight +[default language]: /quick-reference/glossary/#default-language [details]: /methods/page/language/ [RFC 5646]: https://datatracker.ietf.org/doc/html/rfc5646 diff --git a/content/en/methods/site/LanguagePrefix.md b/content/en/methods/site/LanguagePrefix.md index 81a5e8607..7b92c5950 100644 --- a/content/en/methods/site/LanguagePrefix.md +++ b/content/en/methods/site/LanguagePrefix.md @@ -9,7 +9,7 @@ params: signatures: [SITE.LanguagePrefix] --- -Consider this site configuration: +Consider this project configuration: {{< code-toggle file=hugo >}} defaultContentLanguage = 'de' diff --git a/content/en/methods/site/Languages.md b/content/en/methods/site/Languages.md index 056d6193a..69277f329 100644 --- a/content/en/methods/site/Languages.md +++ b/content/en/methods/site/Languages.md @@ -7,9 +7,14 @@ params: functions_and_methods: returnType: langs.Languages signatures: [SITE.Languages] +expiryDate: '2028-02-18' # deprecated 2026-02-18 in v0.156.0 --- -The `Languages` method on a `Site` object returns a collection of language objects for all sites, ordered by language weight. Each language object points to its language definition in the site configuration. +{{< deprecated-in 0.156.0 >}} +See [details](https://discourse.gohugo.io/t/56732). +{{< /deprecated-in >}} + +The `Languages` method on a `Site` object returns a collection of language objects for all sites, ordered by language weight. Each language object points to its language definition in your project configuration. To inspect the data structure: @@ -17,7 +22,7 @@ To inspect the data structure: 
    {{ debug.Dump .Site.Languages }}
    ``` -With this site configuration: +With this project configuration: {{< code-toggle file=hugo >}} defaultContentLanguage = 'de' diff --git a/content/en/methods/site/MainSections.md b/content/en/methods/site/MainSections.md index 6a0dbdc74..0df8de649 100644 --- a/content/en/methods/site/MainSections.md +++ b/content/en/methods/site/MainSections.md @@ -1,6 +1,6 @@ --- title: MainSections -description: Returns a slice of the main section names as defined in the site configuration, falling back to the top-level section with the most pages. +description: Returns a slice of the main section names as defined in your project configuration, falling back to the top-level section with the most pages. categories: [] keywords: [] params: @@ -9,7 +9,7 @@ params: signatures: [SITE.MainSections] --- -Site configuration: +Project configuration: {{< code-toggle file=hugo >}} mainSections = ['books','films'] @@ -21,7 +21,7 @@ Template: {{ .Site.MainSections }} → [books films] ``` -If `mainSections` is not defined in the site configuration, this method returns a slice with one element---the top-level section with the most pages. +If `mainSections` is not defined in your project configuration, this method returns a slice with one element---the top-level section with the most pages. With this content structure, the "films" section has the most pages: @@ -43,7 +43,7 @@ Template: {{ .Site.MainSections }} → [films] ``` -When creating a theme, instead of hardcoding section names when listing the most relevant pages on the front page, instruct site authors to set `mainSections` in their site configuration. +When creating a theme, instead of hardcoding section names when listing the most relevant pages on the front page, instruct users to set `mainSections` in their project configuration. Then your _home_ template can do something like this: diff --git a/content/en/methods/site/Param.md b/content/en/methods/site/Param.md index 929e30e98..b2ec5d9bb 100644 --- a/content/en/methods/site/Param.md +++ b/content/en/methods/site/Param.md @@ -9,7 +9,7 @@ params: signatures: [SITE.Param KEY] --- -The `Param` method on a `Site` object is a convenience method to return the value of a user-defined parameter in the site configuration. +The `Param` method on a `Site` object is a convenience method to return the value of a user-defined parameter in your project configuration. {{< code-toggle file=hugo >}} [params] diff --git a/content/en/methods/site/Params.md b/content/en/methods/site/Params.md index 8467be41d..62bc8f1f5 100644 --- a/content/en/methods/site/Params.md +++ b/content/en/methods/site/Params.md @@ -1,6 +1,6 @@ --- title: Params -description: Returns a map of custom parameters as defined in the site configuration. +description: Returns a map of custom parameters as defined in your project configuration. categories: [] keywords: [] params: @@ -9,7 +9,7 @@ params: signatures: [SITE.Params] --- -With this site configuration: +With this project configuration: {{< code-toggle file=hugo >}} [params] diff --git a/content/en/methods/site/Role.md b/content/en/methods/site/Role.md index cec6f8ffa..b8aee5f4a 100644 --- a/content/en/methods/site/Role.md +++ b/content/en/methods/site/Role.md @@ -1,23 +1,23 @@ --- title: Role -description: Returns the role object for the given site. +description: Returns the Role object for the given site. categories: [] keywords: [] params: functions_and_methods: - returnType: roles.RoleSite + returnType: roles.Role signatures: [SITE.Role] --- {{< new-in 0.153.0 />}} -The `Role` method on a `Site` object returns the role object for the given site. The role object is derived from the role definition in the site configuration. +The `Role` method on a `Site` object returns the `Role` object for the given site, derived from the role definition in your project configuration. ## Methods ### IsDefault -(`bool`) Reports whether this is the default role object as defined by the [`defaultContentRole`][] setting in the site configuration. +(`bool`) Reports whether this is the [default role][]. ```go-html-template {{ .Site.Role.IsDefault }} → true @@ -25,10 +25,10 @@ The `Role` method on a `Site` object returns the role object for the given site. ### Name -(`string`) Returns the role name. This is the lower cased key from the site configuration. +(`string`) Returns the role name. This is the lowercased key from your project configuration. ```go-html-template {{ .Site.Role.Name }} → guest ``` -[`defaultContentRole`]: /configuration/all/#defaultcontentrole +[default role]: /quick-reference/glossary/#default-role diff --git a/content/en/methods/site/Sites.md b/content/en/methods/site/Sites.md index 7d5d02724..7a06e232f 100644 --- a/content/en/methods/site/Sites.md +++ b/content/en/methods/site/Sites.md @@ -1,21 +1,32 @@ --- title: Sites -description: Returns a collection of all Site objects, one for each language, ordered by default content language then by language weight. +description: Returns a collection of all sites for all dimensions. categories: [] keywords: [] params: functions_and_methods: returnType: page.Sites signatures: [SITE.Sites] +expiryDate: '2028-02-18' # deprecated 2026-02-18 in v0.156.0 --- -With this site configuration: +{{< deprecated-in 0.156.0 >}} +Use [`hugo.Sites`] instead. + +[`hugo.Sites`]: /functions/hugo/sites/ +{{< /deprecated-in >}} + +{{% include "/_common/functions/hugo/sites-collection.md" %}} + +With this project configuration: {{< code-toggle file=hugo >}} defaultContentLanguage = 'de' -defaultContentLanguageInSubdir = false +defaultContentLanguageInSubdir = true +defaultContentVersionInSubdir = true [languages.de] +contentDir = 'content/de' languageCode = 'de-DE' languageDirection = 'ltr' languageName = 'Deutsch' @@ -23,11 +34,16 @@ title = 'Projekt Dokumentation' weight = 1 [languages.en] +contentDir = 'content/en' languageCode = 'en-US' languageDirection = 'ltr' languageName = 'English' title = 'Project Documentation' weight = 2 + +[versions.'v1.0.0'] +[versions.'v2.0.0'] +[versions.'v3.0.0'] {{< /code-toggle >}} This template: @@ -35,7 +51,7 @@ This template: ```go-html-template ``` @@ -44,8 +60,12 @@ Produces a list of links to each home page: ```html ``` @@ -53,7 +73,7 @@ To render a link to the home page of the [default site](g): ```go-html-template {{ with .Site.Sites.Default }} - {{ .Title }} + {{ .Title }} {{ end }} ``` @@ -61,6 +81,6 @@ This is equivalent to: ```go-html-template {{ with index .Site.Sites 0 }} - {{ .Title }} + {{ .Title }} {{ end }} ``` diff --git a/content/en/methods/site/Taxonomies.md b/content/en/methods/site/Taxonomies.md index ab28aff1d..4417c9ef7 100644 --- a/content/en/methods/site/Taxonomies.md +++ b/content/en/methods/site/Taxonomies.md @@ -30,7 +30,7 @@ taxonomy b: For example, on a book review site you might create two taxonomies; one for genres and another for authors. -With this site configuration: +With this project configuration: {{< code-toggle file=hugo >}} [taxonomies] diff --git a/content/en/methods/site/Title.md b/content/en/methods/site/Title.md index 935edda0c..ad8a48c3c 100644 --- a/content/en/methods/site/Title.md +++ b/content/en/methods/site/Title.md @@ -1,6 +1,6 @@ --- title: Title -description: Returns the title as defined in the site configuration. +description: Returns the title as defined in your project configuration. categories: [] keywords: [] params: @@ -9,7 +9,7 @@ params: signatures: [SITE.Title] --- -Site configuration: +Project configuration: {{< code-toggle file=hugo >}} title = 'My Documentation Site' diff --git a/content/en/methods/site/Version.md b/content/en/methods/site/Version.md index 1c8870cc5..d424d4666 100644 --- a/content/en/methods/site/Version.md +++ b/content/en/methods/site/Version.md @@ -1,6 +1,6 @@ --- title: Version -description: Returns the version object for the given site. +description: Returns the Version object for the given site. categories: [] keywords: [] params: @@ -11,13 +11,13 @@ params: {{< new-in 0.153.0 />}} -The `Version` method on a `Site` object returns the version object for the given site. The version object is derived from the version definition in the site configuration. +The `Version` method on a `Site` object returns the `Version` object for the given site, derived from the version definition in your project configuration. ## Methods ### IsDefault -(`bool`) Reports whether this is the default version object as defined by the [`defaultContentVersion`][] setting in the site configuration. +(`bool`) Reports whether this is the [default version][]. ```go-html-template {{ .Site.Version.IsDefault }} → true @@ -25,10 +25,10 @@ The `Version` method on a `Site` object returns the version object for the given ### Name -(`string`) Returns the version name. This is the lower cased key from the site configuration. +(`string`) Returns the version name. This is the lowercased key from your project configuration. ```go-html-template {{ .Site.Version.Name }} → v1.0.0 ``` -[`defaultContentVersion`]: /configuration/all/#defaultcontentversion +[default version]: /quick-reference/glossary/#default-version diff --git a/content/en/methods/site/_index.md b/content/en/methods/site/_index.md index f395a3693..4f878a100 100644 --- a/content/en/methods/site/_index.md +++ b/content/en/methods/site/_index.md @@ -1,7 +1,7 @@ --- title: Site methods linkTitle: Site -description: Use these methods with Site objects. +description: Use these methods with a Site object. categories: [] keywords: [] aliases: [/variables/site/] diff --git a/content/en/methods/taxonomy/_index.md b/content/en/methods/taxonomy/_index.md index 13acdb10c..9cf4c7456 100644 --- a/content/en/methods/taxonomy/_index.md +++ b/content/en/methods/taxonomy/_index.md @@ -1,7 +1,7 @@ --- title: Taxonomy methods linkTitle: Taxonomy -description: Use these methods with Taxonomy objects. +description: Use these methods with a Taxonomy object. keywords: [] aliases: [/variables/taxonomy/] --- diff --git a/content/en/methods/time/_index.md b/content/en/methods/time/_index.md index 8114664d3..067d91a7e 100644 --- a/content/en/methods/time/_index.md +++ b/content/en/methods/time/_index.md @@ -1,7 +1,7 @@ --- title: Time methods linkTitle: Time -description: Use these methods with time.Time values. +description: Use these methods with a time.Time value. categories: [] keywords: [] --- diff --git a/content/en/quick-reference/glossary/build-artifacts.md b/content/en/quick-reference/glossary/build-artifacts.md new file mode 100644 index 000000000..c3c2dbd6a --- /dev/null +++ b/content/en/quick-reference/glossary/build-artifacts.md @@ -0,0 +1,5 @@ +--- +title: build artifacts +--- + +The _build artifacts_ are the static files produced during the [_build_](g) process. These assets are stored in the `public` directory by default and represent the final, ready-to-deploy output of the project. diff --git a/content/en/quick-reference/glossary/build.md b/content/en/quick-reference/glossary/build.md index 9a4df3bb1..4d4f73cb4 100644 --- a/content/en/quick-reference/glossary/build.md +++ b/content/en/quick-reference/glossary/build.md @@ -2,4 +2,4 @@ title: build --- -To _build_ (verb) a site is to generate HTML files and assets such as images, CSS files, and JavaScript files. The build process includes rendering and resource transformations. +To _build_ (verb) is to generate the static files for a [_project_](g), including HTML, images, CSS, and JavaScript. This process involves rendering templates, transforming resources, and resolving the matrix of [_language_](g), [_role_](g), and [_version_](g) defined in your project configuration. diff --git a/content/en/quick-reference/glossary/canonical-output-format.md b/content/en/quick-reference/glossary/canonical-output-format.md index 88842a11f..d360083ba 100644 --- a/content/en/quick-reference/glossary/canonical-output-format.md +++ b/content/en/quick-reference/glossary/canonical-output-format.md @@ -2,13 +2,13 @@ title: canonical output format --- -The _canonical output format_ is the [_output format_](g) for the current page where the format's [`rel`][] property is set to `canonical` in your site configuration, if such a format exists. If there is only one _output format_ for the current page, that is the _canonical output format_, regardless of whether the format's `rel` property is set to `canonical`. +The _canonical output format_ is the [_output format_](g) for the current page where the format's [`rel`][] property is set to `canonical` in your project configuration, if such a format exists. If there is only one _output format_ for the current page, that is the _canonical output format_, regardless of whether the format's `rel` property is set to `canonical`. By default, `html` is the only predefined _output format_ with this setting; the `rel` property for all others is set to `alternate`. If two or more _output formats_ for the current page have their `rel` property set to `canonical`, the _canonical output format_ is the first one specified in: - The [`outputs`][outputs_front_matter] front matter field of the current page, or - - The [`outputs`][outputs_site_config] section of your site configuration for the current [_page kind_](g). + - The [`outputs`][outputs_project_config] section of your project configuration for the current [_page kind_](g). [`rel`]: /configuration/output-formats/#rel [outputs_front_matter]: /configuration/outputs/#outputs-per-page - [outputs_site_config]: /configuration/outputs/#outputs-per-page-kind + [outputs_project_config]: /configuration/outputs/#outputs-per-page-kind diff --git a/content/en/quick-reference/glossary/component.md b/content/en/quick-reference/glossary/component.md index 11820608b..1843b1838 100644 --- a/content/en/quick-reference/glossary/component.md +++ b/content/en/quick-reference/glossary/component.md @@ -2,9 +2,7 @@ title: component --- -A _component_ is a collection of related files, housed within the [_unified file system_](g), that fulfills a specific function in building a Hugo website. These components are categorized into seven types: [_archetypes_](g), assets, content, data, templates, [_translation tables_](g), and static files, and can be defined within the project or provided by [_modules_](g). - - Each component has a dedicated directory within the unified file system: +A _component_ is a collection of related files, housed within the [_unified file system_](g), that fulfills a specific function in building a Hugo [_project_](g). These components are categorized into seven types: [_archetypes_](g), assets, content, data, templates, [_translation tables_](g), and static files, and can be defined within the project or provided by [_modules_](g). Each component has a dedicated directory within the unified file system: Component|Directory within the unified file system :--|:-- diff --git a/content/en/quick-reference/glossary/default-language.md b/content/en/quick-reference/glossary/default-language.md new file mode 100644 index 000000000..73f942c2f --- /dev/null +++ b/content/en/quick-reference/glossary/default-language.md @@ -0,0 +1,9 @@ +--- +title: default language +--- + +The _default language_ is is the value defined by the [`defaultContentLanguage`][] setting, falling back to the first language in the project, and finally to `en`. The first language is identified by the lowest [_weight_](g), using lexicographical order as the final fallback if weights are tied or undefined. + + See also: [_language_](g). + + [`defaultContentLanguage`]: /configuration/all/#defaultcontentlanguage diff --git a/content/en/quick-reference/glossary/default-role.md b/content/en/quick-reference/glossary/default-role.md new file mode 100644 index 000000000..f065189c1 --- /dev/null +++ b/content/en/quick-reference/glossary/default-role.md @@ -0,0 +1,9 @@ +--- +title: default role +--- + +The _default role_ is the value defined by the [`defaultContentRole`][] setting, falling back to the first role in the project, and finally to `guest`. The first role is identified by the lowest [_weight_](g), using lexicographical order as the final fallback if weights are tied or undefined. + + See also: [_role_](g). + + [`defaultContentRole`]: /configuration/all/#defaultcontentrole diff --git a/content/en/quick-reference/glossary/default-site.md b/content/en/quick-reference/glossary/default-site.md index 664643cf9..3acad31d0 100644 --- a/content/en/quick-reference/glossary/default-site.md +++ b/content/en/quick-reference/glossary/default-site.md @@ -2,6 +2,4 @@ title: default site --- -The _default site_ is the [_site_](g) identified by the primary value in each [_content dimension_](g). Specifically, it is the site that combines the first language, the first [_role_](g), and the first version defined in your site configuration. - - The "first" language and role are those with the lowest [weight](g). If weights are tied or undefined, Hugo defaults to lexicographical order. Similarly, the "first" version is the one with the lowest weight; if weights are tied or undefined, it is identified as the last version when sorted semantically. +The _default site_ is the [_site_](g) with the [_default language_](g), [_default version_](g), and [_default role_](g). diff --git a/content/en/quick-reference/glossary/default-version.md b/content/en/quick-reference/glossary/default-version.md new file mode 100644 index 000000000..dc2904725 --- /dev/null +++ b/content/en/quick-reference/glossary/default-version.md @@ -0,0 +1,9 @@ +--- +title: default version +--- + +The _default version_ is the value defined by the [`defaultContentVersion`][] setting, falling back to the first version in the project, and finally to `v1.0.0`. The first version is identified by the lowest [_weight_](g), using a descending semantic sort as the final fallback if weights are tied or undefined. + + See also: [_version_](g). + + [`defaultContentVersion`]: /configuration/all/#defaultcontentversion diff --git a/content/en/quick-reference/glossary/dependency-graph.md b/content/en/quick-reference/glossary/dependency-graph.md new file mode 100644 index 000000000..946e5b197 --- /dev/null +++ b/content/en/quick-reference/glossary/dependency-graph.md @@ -0,0 +1,5 @@ +--- +title: dependency graph +--- + +A _dependency graph_ visually represents the relationships between the [_modules_](g) used in a Hugo project. It shows how modules depend on each other, forming a network of dependencies. diff --git a/content/en/quick-reference/glossary/dimension.md b/content/en/quick-reference/glossary/dimension.md index ba0bc5e8c..9db6d64b8 100644 --- a/content/en/quick-reference/glossary/dimension.md +++ b/content/en/quick-reference/glossary/dimension.md @@ -2,4 +2,4 @@ title: dimension --- -A _dimension_ is a categorized axis of content variation that allows multiple variations of a logical page to exist simultaneously. The three dimensions are language, [_role_](g), and version. For example, a logical page may exist in 6 languages, 4 versions, and 2 _roles_. +A _dimension_ is a categorized axis of content variation that allows multiple variations of a logical page to exist simultaneously. The three dimensions are [_language_](g), [_role_](g), and [_version_](g). For example, a logical page may exist in 6 languages, 4 versions, and 2 roles. diff --git a/content/en/quick-reference/glossary/environment.md b/content/en/quick-reference/glossary/environment.md index ebba0ccdf..0cfba95f7 100644 --- a/content/en/quick-reference/glossary/environment.md +++ b/content/en/quick-reference/glossary/environment.md @@ -4,6 +4,6 @@ title: environment Typically one of `development`, `staging`, or `production`, each _environment_ may exhibit different behavior depending on configuration and template logic. For example, in a production environment you might minify and fingerprint CSS, but that probably doesn't make sense in a development environment. - When running the built-in development server with the `hugo server` command, the environment is set to `development`. When building your site with the `hugo` command, the environment is set to `production`. To override the environment value, use the `--environment` command line flag or the `HUGO_ENVIRONMENT` environment variable. + When running the built-in development server with the `hugo server` command, the environment is set to `development`. When building your project with the `hugo build` command, the environment is set to `production`. To override the environment value, use the `--environment` command line flag or the `HUGO_ENVIRONMENT` environment variable. To determine the current environment within a template, use the [`hugo.Environment`](/functions/hugo/environment/) function. diff --git a/content/en/quick-reference/glossary/glob-slice.md b/content/en/quick-reference/glossary/glob-slice.md index faaa64581..df37718b1 100644 --- a/content/en/quick-reference/glossary/glob-slice.md +++ b/content/en/quick-reference/glossary/glob-slice.md @@ -4,7 +4,7 @@ title: glob slice A _glob slice_ is a [_slice_](g) of [_glob patterns_](g). Within the _slice_, a _glob_ can be negated by prefixing it with an exclamation mark (`!`) and one space. Matches in negated patterns short-circuit the evaluation of the rest of the _slice_, and are useful for early coarse grained exclusions. - The following example illustrates how to use _glob slices_ to define a [_sites matrix_](g) in your site configuration: + The following example illustrates how to use _glob slices_ to define a [_sites matrix_](g) in your project configuration: ```toml [sites.matrix] diff --git a/content/en/quick-reference/glossary/language.md b/content/en/quick-reference/glossary/language.md new file mode 100644 index 000000000..551dc691c --- /dev/null +++ b/content/en/quick-reference/glossary/language.md @@ -0,0 +1,7 @@ +--- +title: language +--- + +A _language_ is a [_dimension_](g) that facilitates the localization and internationalization of content. While [_version_](g) focuses on lifecycle and [_role_](g) focuses on audience, the language dimension allows a logical page to be represented in different locales across the project. + + See also: [_default language_](g). diff --git a/content/en/quick-reference/glossary/page-relative.md b/content/en/quick-reference/glossary/page-relative.md index 11c485aa0..d12327bb9 100644 --- a/content/en/quick-reference/glossary/page-relative.md +++ b/content/en/quick-reference/glossary/page-relative.md @@ -2,6 +2,6 @@ title: page-relative --- - A _page-relative_ path is resolved relative to the current page's location in the content hierarchy. These paths do not begin with a leading slash. Examples include `old-name`, `./old-name`, and `../old-name`. +A _page-relative_ path is resolved relative to the current page's location in the content hierarchy. These paths do not begin with a leading slash. Examples include `old-name`, `./old-name`, and `../old-name`. See also: [_site-relative_](g), [_server-relative_](g). diff --git a/content/en/quick-reference/glossary/project.md b/content/en/quick-reference/glossary/project.md new file mode 100644 index 000000000..86a3f63d3 --- /dev/null +++ b/content/en/quick-reference/glossary/project.md @@ -0,0 +1,5 @@ +--- +title: project +--- + +A _project_ is a collection of [_components_](g) used to generate one or more [sites](g). While a project may consist of only a single site, Hugo allows a single project to generate a matrix of sites based on [_language_](g), [role](g), and [_version_](g). The project serves as the parent container for the common assets and logic used across all sites within the build. diff --git a/content/en/quick-reference/glossary/regular-expression.md b/content/en/quick-reference/glossary/regular-expression.md index 222f289d9..82f8d98f5 100644 --- a/content/en/quick-reference/glossary/regular-expression.md +++ b/content/en/quick-reference/glossary/regular-expression.md @@ -3,6 +3,6 @@ title: regular expression reference: --- -A _regular expression_, also known as a _regex_, is a sequence of characters that defines a search pattern. Use the [RE2 syntax] when defining regular expressions in your templates or site configuration. +A _regular expression_, also known as a _regex_, is a sequence of characters that defines a search pattern. Use the [RE2 syntax] when defining regular expressions in your templates or in your project configuration. [RE2 syntax]: https://github.com/google/re2/wiki/syntax diff --git a/content/en/quick-reference/glossary/role.md b/content/en/quick-reference/glossary/role.md index be85f656d..f491d3610 100644 --- a/content/en/quick-reference/glossary/role.md +++ b/content/en/quick-reference/glossary/role.md @@ -2,4 +2,6 @@ title: role --- -A _role_ is a [_dimension_](g) that allows a logical page to be served in different forms depending on the target audience. Common use cases include user personas, access control, and intended audience. +A _role_ is a [_dimension_](g) that allows a logical page to be served in different forms depending on the target audience. While [_language_](g) focuses on localization and [_version_](g) focuses on lifecycle, the role dimension allows a project to generate variations of a page without duplicating content. + + See also: [_default role_](g). diff --git a/content/en/quick-reference/glossary/server-relative.md b/content/en/quick-reference/glossary/server-relative.md index 4420ba504..8783a25af 100644 --- a/content/en/quick-reference/glossary/server-relative.md +++ b/content/en/quick-reference/glossary/server-relative.md @@ -2,7 +2,7 @@ title: server-relative --- - A _server-relative_ path is the final path from the web server's root, used in the generated site. These paths always begin with a leading slash and account for the [`baseURL`] and [_content dimension_](g) prefixes such as language, [_role_](g), or version. For example, `/en/examples/old-name/` is a server-relative path. +A _server-relative_ path is the final path from the web server's root, used in the generated site. These paths always begin with a leading slash and account for the [`baseURL`] and [_content dimension_](g) prefixes such as language, [_role_](g), or version. For example, `/en/examples/old-name/` is a server-relative path. See also: [_page-relative_](g), [_site-relative_](g). diff --git a/content/en/quick-reference/glossary/site-relative.md b/content/en/quick-reference/glossary/site-relative.md index c6536a165..b434fd1c2 100644 --- a/content/en/quick-reference/glossary/site-relative.md +++ b/content/en/quick-reference/glossary/site-relative.md @@ -2,6 +2,6 @@ title: site-relative --- - A _site-relative_ path is resolved relative to the root of the content directory. These paths begin with a leading slash. For example, `/old-name` is a site-relative path. +A _site-relative_ path is resolved relative to the root of the content directory. These paths begin with a leading slash. For example, `/old-name` is a site-relative path. See also: [_page-relative_](g), [_server-relative_](g). diff --git a/content/en/quick-reference/glossary/site-root.md b/content/en/quick-reference/glossary/site-root.md index 71c4477a8..1066acb4d 100644 --- a/content/en/quick-reference/glossary/site-root.md +++ b/content/en/quick-reference/glossary/site-root.md @@ -2,7 +2,7 @@ title: site root --- -The _site root_ is the root directory of the current [_site_](g), relative to the [`publishDir`][]. The _site root_ may include one or more content [_dimension_](g) prefixes, such as language, [_role_](g), or version. +The _site root_ is the root directory of the current [_site_](g), relative to the [`publishDir`][]. The _site root_ may include one or more content [_dimension_](g) prefixes, such as [_language_](g), [_role_](g), or [_version_](g). Project description|Site root examples :--|:--|:-- diff --git a/content/en/quick-reference/glossary/site.md b/content/en/quick-reference/glossary/site.md index 1d2d016dc..f3be3a1f3 100644 --- a/content/en/quick-reference/glossary/site.md +++ b/content/en/quick-reference/glossary/site.md @@ -2,4 +2,4 @@ title: site --- -A _site_ is a specific instance of your project representing a unique combination of language, [_role_](g), and version. While a simple project may consist of only a single site, Hugo's multidimensional content model allows a single codebase to generate a matrix of sites simultaneously. Each site operates with its own configuration, set of pages, and output destination, allowing you to serve tailored content to different audiences from one unified source. +A _site_ is a specific instance of your [_project_](g) representing a unique combination of [_language_](g), [_role_](g), and [_version_](g). While a simple project may consist of only a single site, Hugo's multidimensional content model allows a single codebase to generate a matrix of sites simultaneously. diff --git a/content/en/quick-reference/glossary/sites-complements.md b/content/en/quick-reference/glossary/sites-complements.md index 5854f288c..80213e1f9 100644 --- a/content/en/quick-reference/glossary/sites-complements.md +++ b/content/en/quick-reference/glossary/sites-complements.md @@ -2,4 +2,4 @@ title: sites complements --- -_sites complements_ is a configuration object defined in content front matter or a file mount. The links will point to the complementary sites. The configuration is structured as a map of [_glob slices_](g). +A _sites complements_ is a configuration object defined in content front matter or a file mount. The links will point to the complementary [_sites_](g). The configuration is structured as a map of [_glob slices_](g). diff --git a/content/en/quick-reference/glossary/sites-matrix.md b/content/en/quick-reference/glossary/sites-matrix.md index 5900334e1..8e6838d4e 100644 --- a/content/en/quick-reference/glossary/sites-matrix.md +++ b/content/en/quick-reference/glossary/sites-matrix.md @@ -2,8 +2,6 @@ title: sites matrix --- -_sites matrix_ is a configuration object defined in content front matter or a file mount to precisely control which sites the content should be generated for. When defined in a file mount for [_templates_](g), it controls which sites the template will be applied to. - - In Hugo's multidimensional content model, the matrix defines the intersection of three dimensions: language, role, and version. The configuration is structured as a map of [_glob slices_](g). +A _sites matrix_ is a configuration object defined in content front matter or a file mount to precisely control which [_sites_](g) the content should be generated for. When defined in a file mount for templates, it controls which sites the template will be applied to. In Hugo multidimensional content model, the matrix defines the intersection of three dimensions: [_language_](g), [_role_](g), and [_version_](g). The configuration is structured as a map of [_glob slices_](g). See also [_sites complements_](g), [front matter: sites](/content-management/front-matter/#sites), [module mounts: sites](/configuration/module/#sites), and [segments: sites](/configuration/segments/#sites). diff --git a/content/en/quick-reference/glossary/version.md b/content/en/quick-reference/glossary/version.md new file mode 100644 index 000000000..62eb8f35a --- /dev/null +++ b/content/en/quick-reference/glossary/version.md @@ -0,0 +1,9 @@ +--- +title: version +--- + +A _version_ is a [_dimension_](g) that represents a specific iteration, release, or lifecycle stage of content. While [_language_](g) focuses on localization and [_role_](g) focuses on audience, the version dimension allows you to maintain multiple states of the same content simultaneously using [semantic versioning]. + + See also: [_default version_](g). + + [semantic versioning]: https://semver.org/ diff --git a/content/en/quick-reference/glossary/workspace.md b/content/en/quick-reference/glossary/workspace.md new file mode 100644 index 000000000..6eda9bab3 --- /dev/null +++ b/content/en/quick-reference/glossary/workspace.md @@ -0,0 +1,7 @@ +--- +title: workspace +params: + reference: /hugo-modules/use-modules/#workspace +--- + +A _workspace_ is a collection of [_modules_](g) on disk. diff --git a/content/en/quick-reference/glossary/wrapper-component.md b/content/en/quick-reference/glossary/wrapper-component.md index 938a0271d..ada5d466e 100644 --- a/content/en/quick-reference/glossary/wrapper-component.md +++ b/content/en/quick-reference/glossary/wrapper-component.md @@ -4,4 +4,4 @@ title: wrapper component A _wrapper component_ is an interface pattern that encloses other content through composition rather than fixed parameters. It provides a reusable shell to handle layout, styling, or logic, allowing the calling template to inject arbitrary content into the component's interior. - See also: [_partial decorator_](g) + See also: [_partial decorator_](g). diff --git a/content/en/quick-reference/syntax-highlighting-styles.md b/content/en/quick-reference/syntax-highlighting-styles.md index 76aa77bf4..3ba6fd833 100644 --- a/content/en/quick-reference/syntax-highlighting-styles.md +++ b/content/en/quick-reference/syntax-highlighting-styles.md @@ -15,7 +15,7 @@ Hugo provides several methods to add syntax highlighting to code examples: Regardless of method, use any of the syntax highlighting styles below. -Set the default syntax highlighting style in your site configuration: +Set the default syntax highlighting style in your project configuration: {{< code-toggle file=hugo >}} [markup.highlight] diff --git a/content/en/render-hooks/code-blocks.md b/content/en/render-hooks/code-blocks.md index 136c3b6d7..5b226467b 100755 --- a/content/en/render-hooks/code-blocks.md +++ b/content/en/render-hooks/code-blocks.md @@ -11,7 +11,7 @@ keywords: [] This Markdown example contains a fenced code block: ````text {file="content/example.md"} -```bash {class="my-class" id="my-codeblock" lineNos=inline tabWidth=2} +```sh {class="my-class" id="my-codeblock" lineNos=inline tabWidth=2} declare a=1 echo "$a" exit diff --git a/content/en/render-hooks/images.md b/content/en/render-hooks/images.md index e5f631cdc..c89ce1746 100755 --- a/content/en/render-hooks/images.md +++ b/content/en/render-hooks/images.md @@ -89,7 +89,7 @@ To render standalone images within `figure` elements: {{- end -}} ``` -Note that the above requires the following site configuration: +Note that the above requires the following project configuration: {{< code-toggle file=hugo >}} [markup.goldmark.parser] @@ -98,7 +98,7 @@ wrapStandAloneImageWithinParagraph = false ## Embedded -Hugo includes an [embedded image render hook] to resolve Markdown image destinations. You can adjust its behavior in your site configuration. This is the default setting: +Hugo includes an [embedded image render hook] to resolve Markdown image destinations. You can adjust its behavior in your project configuration. This is the default setting: {{< code-toggle file=hugo >}} [markup.goldmark.renderHooks.image] @@ -111,7 +111,7 @@ You can also configure Hugo to `always` use the embedded image render hook, use The embedded image render hook resolves internal Markdown destinations by looking for a matching [page resource](g), falling back to a matching [global resource](g). Remote destinations are passed through, and the render hook will not throw an error or warning if unable to resolve a destination. -You must place global resources in the `assets` directory. If you have placed your resources in the `static` directory, and you are unable or unwilling to move them, you must mount the `static` directory to the `assets` directory by including both of these entries in your site configuration: +You must place global resources in the `assets` directory. If you have placed your resources in the `static` directory, and you are unable or unwilling to move them, you must mount the `static` directory to the `assets` directory by including both of these entries in your project configuration: {{< code-toggle file=hugo >}} [[module.mounts]] diff --git a/content/en/render-hooks/links.md b/content/en/render-hooks/links.md index d35869160..ee765c14b 100755 --- a/content/en/render-hooks/links.md +++ b/content/en/render-hooks/links.md @@ -71,7 +71,7 @@ To include a `rel` attribute set to `external` for external links: ## Embedded -Hugo includes an [embedded link render hook] to resolve Markdown link destinations. You can adjust its behavior in your site configuration. This is the default setting: +Hugo includes an [embedded link render hook] to resolve Markdown link destinations. You can adjust its behavior in your project configuration. This is the default setting: {{< code-toggle file=hugo >}} [markup.goldmark.renderHooks.link] @@ -84,7 +84,7 @@ You can also configure Hugo to `always` use the embedded link render hook, use i The embedded link render hook resolves internal Markdown destinations by looking for a matching page, falling back to a matching [page resource](g), then falling back to a matching [global resource](g). Remote destinations are passed through, and the render hook will not throw an error or warning if unable to resolve a destination. -You must place global resources in the `assets` directory. If you have placed your resources in the `static` directory, and you are unable or unwilling to move them, you must mount the `static` directory to the `assets` directory by including both of these entries in your site configuration: +You must place global resources in the `assets` directory. If you have placed your resources in the `static` directory, and you are unable or unwilling to move them, you must mount the `static` directory to the `assets` directory by including both of these entries in your project configuration: {{< code-toggle file=hugo >}} [[module.mounts]] diff --git a/content/en/render-hooks/passthrough.md b/content/en/render-hooks/passthrough.md index 76643718f..7aada5713 100755 --- a/content/en/render-hooks/passthrough.md +++ b/content/en/render-hooks/passthrough.md @@ -27,7 +27,7 @@ passthrough element with opening and closing block delimiters. This is an \(inline\) passthrough element with opening and closing inline delimiters. ``` -Update your site configuration to enable the Passthrough extension and define opening and closing delimiters for each passthrough element type, either `block` or `inline`. For example: +Update your project configuration to enable the Passthrough extension and define opening and closing delimiters for each passthrough element type, either `block` or `inline`. For example: {{< code-toggle file=hugo >}} [markup.goldmark.extensions.passthrough] diff --git a/content/en/shortcodes/figure.md b/content/en/shortcodes/figure.md index 24d85064b..42438f7ad 100755 --- a/content/en/shortcodes/figure.md +++ b/content/en/shortcodes/figure.md @@ -94,7 +94,7 @@ attrlink The `figure` shortcode resolves internal Markdown destinations by looking for a matching [page resource](g), falling back to a matching [global resource](g). Remote destinations are passed through, and the render hook will not throw an error or warning if unable to resolve a destination. -You must place global resources in the `assets` directory. If you have placed your resources in the `static` directory, and you are unable or unwilling to move them, you must mount the `static` directory to the `assets` directory by including both of these entries in your site configuration: +You must place global resources in the `assets` directory. If you have placed your resources in the `static` directory, and you are unable or unwilling to move them, you must mount the `static` directory to the `assets` directory by including both of these entries in your project configuration: {{< code-toggle file=hugo >}} [[module.mounts]] diff --git a/content/en/shortcodes/highlight.md b/content/en/shortcodes/highlight.md index c349e97be..d427da7cc 100755 --- a/content/en/shortcodes/highlight.md +++ b/content/en/shortcodes/highlight.md @@ -33,7 +33,7 @@ LANG : (`string`) The language of the code to highlight. Choose from one of the [supported languages]. This value is case-insensitive. OPTIONS -: (`string`) Zero or more space-separated key-value pairs wrapped in quotation marks. Set default values for each option in your [site configuration]. The key names are case-insensitive. +: (`string`) Zero or more space-separated key-value pairs wrapped in quotation marks. Set default values for each option in your [project configuration]. The key names are case-insensitive. ## Example @@ -94,7 +94,7 @@ This is some {{< hl >}}fmt.Println("inline"){{< /hl >}} code. ## Options -Pass the options when calling the shortcode. You can set their default values in your [site configuration]. +Pass the options when calling the shortcode. You can set their default values in your [project configuration]. {{% include "_common/syntax-highlighting-options.md" %}} @@ -102,6 +102,6 @@ Pass the options when calling the shortcode. You can set their default values in [Chroma]: https://github.com/alecthomas/chroma [content format]: /content-management/formats/ [highlighting styles]: /quick-reference/syntax-highlighting-styles/ -[site configuration]: /configuration/markup/#highlight +[project configuration]: /configuration/markup/#highlight [source code]: <{{% eturl highlight %}}> [supported languages]: /content-management/syntax-highlighting/#languages diff --git a/content/en/shortcodes/instagram.md b/content/en/shortcodes/instagram.md index 9f8b4fd26..f3223e742 100755 --- a/content/en/shortcodes/instagram.md +++ b/content/en/shortcodes/instagram.md @@ -29,7 +29,7 @@ Huge renders this to: ## Privacy -Adjust the relevant privacy settings in your site configuration. +Adjust the relevant privacy settings in your project configuration. {{< code-toggle config=privacy.instagram />}} diff --git a/content/en/shortcodes/param.md b/content/en/shortcodes/param.md index 967d12846..51310a2a1 100755 --- a/content/en/shortcodes/param.md +++ b/content/en/shortcodes/param.md @@ -1,7 +1,7 @@ --- title: Param shortcode linkTitle: Param -description: Insert a parameter from front matter or site configuration into your content using the param shortcode. +description: Insert a parameter from front matter or your project configuration into your content using the param shortcode. categories: [] keywords: [] --- diff --git a/content/en/shortcodes/vimeo.md b/content/en/shortcodes/vimeo.md index b09420018..d7ca7ee6c 100755 --- a/content/en/shortcodes/vimeo.md +++ b/content/en/shortcodes/vimeo.md @@ -54,7 +54,7 @@ Here's an example using some of the available arguments: ## Privacy -Adjust the relevant privacy settings in your site configuration. +Adjust the relevant privacy settings in your project configuration. {{< code-toggle config=privacy.vimeo />}} diff --git a/content/en/shortcodes/x.md b/content/en/shortcodes/x.md index 967a526a8..1ca87949a 100755 --- a/content/en/shortcodes/x.md +++ b/content/en/shortcodes/x.md @@ -31,7 +31,7 @@ Rendered: ## Privacy -Adjust the relevant privacy settings in your site configuration. +Adjust the relevant privacy settings in your project configuration. {{< code-toggle config=privacy.x />}} @@ -46,7 +46,7 @@ simple The source code for the simple version of the shortcode is available [in this file]. -If you enable simple mode you may want to disable the hardcoded inline styles by setting `disableInlineCSS` to `true` in your site configuration. The default value for this setting is `false`. +If you enable simple mode you may want to disable the hardcoded inline styles by setting `disableInlineCSS` to `true` in your project configuration. The default value for this setting is `false`. {{< code-toggle config=services.x />}} diff --git a/content/en/shortcodes/youtube.md b/content/en/shortcodes/youtube.md index 1e72ee284..c76c5f308 100755 --- a/content/en/shortcodes/youtube.md +++ b/content/en/shortcodes/youtube.md @@ -70,7 +70,7 @@ Here's an example using some of the available arguments: ## Privacy -Adjust the relevant privacy settings in your site configuration. +Adjust the relevant privacy settings in your project configuration. {{< code-toggle config=privacy.youTube />}} diff --git a/content/en/templates/embedded.md b/content/en/templates/embedded.md index 1ab5e04e7..d8de3061a 100644 --- a/content/en/templates/embedded.md +++ b/content/en/templates/embedded.md @@ -47,7 +47,7 @@ You can also set the following in the front matter for a given piece of content: ### Privacy {#privacy-disqus} -Adjust the relevant privacy settings in your site configuration. +Adjust the relevant privacy settings in your project configuration. {{< code-toggle config=privacy.disqus />}} @@ -82,7 +82,7 @@ To use this value in your own template, access the configured ID with `{{ site.C ### Privacy {#privacy-google-analytics} -Adjust the relevant privacy settings in your site configuration. +Adjust the relevant privacy settings in your project configuration. {{< code-toggle config=privacy.googleAnalytics />}} @@ -134,9 +134,7 @@ series = [] tags = [] {{}} -Hugo uses the page title and description for the title and description metadata. -The first 6 URLs from the `images` array are used for image metadata. -If [page bundles](/content-management/page-bundles/) are used and the `images` array is empty or undefined, images with file names matching `*feature*`, `*cover*`, or `*thumbnail*` are used for image metadata. +Hugo uses the page title and description for the title and description metadata. The first 6 URLs from the `images` array are used for image metadata. If [page bundles](/content-management/page-bundles/) are used and the `images` array is empty or undefined, images with file names matching `*feature*`, `*cover*`, or `*thumbnail*` are used for image metadata. Various optional metadata can also be set: @@ -173,8 +171,7 @@ To include the embedded template: > > `{{ partial "twitter_cards.html" . }}` -Hugo includes an embedded template for [X (Twitter) Cards](https://developer.x.com/en/docs/twitter-for-websites/cards/overview/abouts-cards), -metadata used to attach rich media to Tweets linking to your site. +Hugo includes an embedded template for [X (Twitter) Cards](https://developer.x.com/en/docs/twitter-for-websites/cards/overview/abouts-cards), metadata used to attach rich media to Tweets linking to your site. To include the embedded template: @@ -198,13 +195,11 @@ description = "Text about this post" images = ["post-cover.png"] {{}} -If [page bundles](/content-management/page-bundles/) are used and the `images` array is empty or undefined, images with file names matching `*feature*`, `*cover*`, or `*thumbnail*` are used for image metadata. -If no image resources with those names are found, the images defined in the [site config](/configuration/) are used instead. -If no images are found at all, then an image-less Twitter `summary` card is used instead of `summary_large_image`. +If [page bundles](/content-management/page-bundles/) are used and the `images` array is empty or undefined, images with file names matching `*feature*`, `*cover*`, or `*thumbnail*` are used for image metadata. If no image resources with those names are found, the images defined in your [project configuration](/configuration/) are used instead. If no images are found at all, then an image-less Twitter `summary` card is used instead of `summary_large_image`. Hugo uses the page title and description for the card's title and description fields. The page summary is used if no description is given. -Set the value of `twitter:site` in your site configuration: +Set the value of `twitter:site` in your project configuration: {{< code-toggle file=hugo >}} [params.social] diff --git a/content/en/templates/introduction.md b/content/en/templates/introduction.md index 57a1ac1b7..fcc7d445e 100644 --- a/content/en/templates/introduction.md +++ b/content/en/templates/introduction.md @@ -311,8 +311,8 @@ Object|Method|Description `Page`|[`Params`](methods/page/params/)|Returns a map of custom parameters as defined in the front matter of the given page. `Page`|[`Title`](methods/page/title/)|Returns the title of the given page. `Site`|[`Data`](methods/site/data/)|Returns a data structure composed from the files in the `data` directory. -`Site`|[`Params`](methods/site/params/)|Returns a map of custom parameters as defined in the site configuration. -`Site`|[`Title`](methods/site/title/)|Returns the title as defined in the site configuration. +`Site`|[`Params`](methods/site/params/)|Returns a map of custom parameters as defined in your project configuration. +`Site`|[`Title`](methods/site/title/)|Returns the title as defined in the your project configuration. Chain the method to its object with a dot (`.`) as shown below, remembering that the leading dot represents the [current context]. @@ -491,7 +491,7 @@ To test multiple conditions: See documentation for the [`Params`](/methods/site/params/) method on a `Site` object. -With this site configuration: +With this project configuration: {{< code-toggle file=hugo >}} title = 'ABC Widgets' diff --git a/content/en/templates/menu.md b/content/en/templates/menu.md index aa0e7c673..976e9f832 100644 --- a/content/en/templates/menu.md +++ b/content/en/templates/menu.md @@ -13,9 +13,9 @@ After [defining menu entries], use [menu methods] to render a menu. Three factors determine how to render a menu: -1. The method used to define the menu entries: [automatic], [in front matter], or [in site configuration] +1. The method used to define the menu entries: [automatic], in [front matter], or in your [project configuration] 1. The menu structure: flat or nested -1. The method used to [localize the menu entries]: site configuration or translation tables +1. The method used to [localize the menu entries]: project configuration or translation tables The example below handles every combination. @@ -96,9 +96,9 @@ This simplistic example renders a page parameter named `version` next to each en ## Menu entry parameters -When you define menu entries [in site configuration] or [in front matter], you can include a `params` key as shown in these examples: +When you define menu entries in your [project configuration] or in [front matter], you can include a `params` key as shown in these examples: -- [Menu entry defined in site configuration] +- [Menu entry defined in your project configuration] - [Menu entry defined in front matter] This simplistic example renders a `class` attribute for each anchor element. Code defensively using `with` or `if` to handle entries where `params.class` is not defined. @@ -118,10 +118,10 @@ Hugo provides two methods to localize your menu entries. See [multilingual]. [automatic]: /content-management/menus/#define-automatically [define menu entries]: /content-management/menus/ [defining menu entries]: /content-management/menus/ -[in front matter]: /content-management/menus/#define-in-front-matter -[in site configuration]: /content-management/menus/#define-in-site-configuration +[front matter]: /content-management/menus/#define-in-front-matter [localize the menu entries]: /content-management/multilingual/#menus [menu entry defined in front matter]: /content-management/menus/#example -[menu entry defined in site configuration]: /configuration/menus +[menu entry defined in your project configuration]: /configuration/menus [menu methods]: /methods/menu/ [multilingual]: /content-management/multilingual/#menus +[project configuration]: /content-management/menus/#define-in-project-configuration diff --git a/content/en/templates/pagination.md b/content/en/templates/pagination.md index a1174980d..3891da574 100644 --- a/content/en/templates/pagination.md +++ b/content/en/templates/pagination.md @@ -47,7 +47,7 @@ The `Paginate` method is more flexible, allowing you to: - Paginate any page collection - Filter, sort, and group the page collection -- Override the number of pages per pager as defined in your site configuration +- Override the number of pages per pager as defined in your project configuration By comparison, the `Paginator` method paginates the page collection passed into the template, and you cannot override the number of pages per pager. @@ -163,7 +163,7 @@ content/ └── _index.md ``` -And this site configuration: +And this project configuration: {{< code-toggle file=hugo >}} [pagination] @@ -204,7 +204,7 @@ public/ └── index.html ``` -To disable alias generation for the first pager, change your site configuration: +To disable alias generation for the first pager, change your project configuration: {{< code-toggle file=hugo >}} [pagination] diff --git a/content/en/templates/robots.md b/content/en/templates/robots.md index 75bd8bbce..00ca20e41 100644 --- a/content/en/templates/robots.md +++ b/content/en/templates/robots.md @@ -8,7 +8,7 @@ weight: 190 aliases: [/extras/robots-txt/] --- -To generate a robots.txt file from a template, change the [site configuration]: +To generate a robots.txt file from a template, change your [project configuration]: {{< code-toggle file=hugo >}} enableRobotsTXT = true @@ -43,10 +43,10 @@ This template creates a robots.txt file with a `Disallow` directive for each pag > [!note] > To create a robots.txt file without using a template: > -> 1. Set `enableRobotsTXT` to `false` in the site configuration. +> 1. Set `enableRobotsTXT` to `false` in your project configuration. > 1. Create a robots.txt file in the `static` directory. > -> Remember that Hugo copies everything in the static director to the root of `publishDir` (typically `public`) when you build your site. +> Remember that Hugo copies everything in the static director to the root of `publishDir` (typically `public`) when you build your project. [embedded template]: <{{% eturl robots %}}> -[site configuration]: /configuration/ +[project configuration]: /configuration/ diff --git a/content/en/templates/rss.md b/content/en/templates/rss.md index cbc393a03..e0c64e421 100644 --- a/content/en/templates/rss.md +++ b/content/en/templates/rss.md @@ -8,7 +8,7 @@ weight: 140 ## Configuration -By default, when you build your site, Hugo generates RSS feeds for home, section, taxonomy, and term pages. Control feed generation in your site configuration. For example, to generate feeds for home and section pages, but not for taxonomy and term pages: +By default, when you build your project, Hugo generates RSS feeds for home, section, taxonomy, and term pages. Control feed generation in your project configuration. For example, to generate feeds for home and section pages, but not for taxonomy and term pages: {{< code-toggle file=hugo >}} [outputs] @@ -24,7 +24,7 @@ To disable feed generation for all [page kinds](g): disableKinds = ['rss'] {{< /code-toggle >}} -By default, the number of items in each feed is unlimited. Change this as needed in your site configuration: +By default, the number of items in each feed is unlimited. Change this as needed in your project configuration: {{< code-toggle file=hugo >}} [services.rss] @@ -33,7 +33,7 @@ limit = 42 Set `limit` to `-1` to generate an unlimited number of items per feed. -The built-in RSS template will render the following values, if present, from your site configuration: +The built-in RSS template will render the following values, if present, from your project configuration: {{< code-toggle file=hugo >}} copyright = '© 2023 ABC Widgets, Inc.' diff --git a/content/en/templates/sitemap.md b/content/en/templates/sitemap.md index a79ec7bba..221cb6c0f 100644 --- a/content/en/templates/sitemap.md +++ b/content/en/templates/sitemap.md @@ -42,7 +42,7 @@ To override the built-in sitemapindex.xml template, create a new `layouts/sitema ## Disable sitemap generation -You may disable sitemap generation in your site configuration: +You may disable sitemap generation in your project configuration: {{< code-toggle file=hugo >}} disableKinds = ['sitemap'] diff --git a/content/en/tools/other.md b/content/en/tools/other.md index 489d78506..052041c7a 100644 --- a/content/en/tools/other.md +++ b/content/en/tools/other.md @@ -10,7 +10,7 @@ weight: 50 And for all the other community projects around Hugo: - [diego](https://github.com/ttybitnik/diego) - A CLI tool that integrates with Hugo to assist in importing and utilizing exported social media data from popular services on Hugo websites. -- [Emacs Easy Hugo](https://github.com/masasam/emacs-easy-hugo) - Emacs package for writing blog posts in Markdown or org-mode and building your site with Hugo. +- [Emacs Easy Hugo](https://github.com/masasam/emacs-easy-hugo) - Emacs package for writing blog posts in Markdown or org-mode and building your project with Hugo. - [Hugo SFTP Upload](https://github.com/thomasmey/HugoSftpUpload) - Sync the local build of your Hugo website with your remote web server via SFTP. - [HugoPhotoSwipe](https://github.com/GjjvdBurg/HugoPhotoSwipe) - Make it easy to create image galleries using PhotoSwipe. - [JAMStack Themes](https://jamstackthemes.dev/ssg/hugo/) - A collection of site themes filterable by static site generator and supported CMS to help build CMS-connected sites using Hugo (linking to Hugo-specific themes). diff --git a/content/en/troubleshooting/audit/index.md b/content/en/troubleshooting/audit/index.md index 2efad55e3..a20b33651 100644 --- a/content/en/troubleshooting/audit/index.md +++ b/content/en/troubleshooting/audit/index.md @@ -23,10 +23,10 @@ _Tested with GNU Bash 5.1 and GNU grep 3.7._ ### Environment variables `HUGO_MINIFY_TDEWOLFF_HTML_KEEPCOMMENTS=true` -: Retain HTML comments even if minification is enabled. This takes precedence over `minify.tdewolff.html.keepComments` in the site configuration. If you minify without keeping HTML comments when performing this audit, you will not be able to detect when raw HTML has been omitted. +: Retain HTML comments even if minification is enabled. This takes precedence over `minify.tdewolff.html.keepComments` in your project configuration. If you minify without keeping HTML comments when performing this audit, you will not be able to detect when raw HTML has been omitted. `HUGO_ENABLEMISSINGTRANSLATIONPLACEHOLDERS=true` -: Show a placeholder instead of the default value or an empty string if a translation is missing. This takes precedence over `enableMissingTranslationPlaceholders` in the site configuration. +: Show a placeholder instead of the default value or an empty string if a translation is missing. This takes precedence over `enableMissingTranslationPlaceholders` in your project configuration. ### Grep options diff --git a/content/en/troubleshooting/deprecation.md b/content/en/troubleshooting/deprecation.md index f2e5259a6..a627a0e36 100644 --- a/content/en/troubleshooting/deprecation.md +++ b/content/en/troubleshooting/deprecation.md @@ -37,13 +37,13 @@ The project team will: To see the INFO messages, you must use the `--logLevel` command line flag: ```text -hugo --logLevel info +hugo build --logLevel info ``` To limit the output to deprecation notices: ```text -hugo --logLevel info | grep deprecate +hugo build --logLevel info | grep deprecate ``` Run the above command every time you upgrade Hugo. diff --git a/content/en/troubleshooting/logging.md b/content/en/troubleshooting/logging.md index 0cd25d1ae..2a98633d7 100644 --- a/content/en/troubleshooting/logging.md +++ b/content/en/troubleshooting/logging.md @@ -1,6 +1,6 @@ --- title: Logging -description: Enable logging to inspect events while building your site. +description: Enable logging to inspect events while building your project. categories: [] keywords: [] --- @@ -15,28 +15,28 @@ error : Display error messages only. ```sh - hugo --logLevel error + hugo build --logLevel error ``` warn : Display warning and error messages. ```sh - hugo --logLevel warn + hugo build --logLevel warn ``` info : Display information, warning, and error messages. ```sh - hugo --logLevel info + hugo build --logLevel info ``` debug : Display debug, information, warning, and error messages. ```sh - hugo --logLevel debug + hugo build --logLevel debug ``` > [!note] diff --git a/content/en/troubleshooting/performance.md b/content/en/troubleshooting/performance.md index c52dc6966..45be5c7be 100644 --- a/content/en/troubleshooting/performance.md +++ b/content/en/troubleshooting/performance.md @@ -28,7 +28,7 @@ Other virus scanners have similar exclusion mechanisms. See their respective doc Hugo is fast, but inefficient templates impede performance. Enable template metrics to determine which templates take the most time, and to identify caching opportunities: ```sh -hugo --templateMetrics --templateMetricsHints +hugo build --templateMetrics --templateMetricsHints ``` The result will look something like this: diff --git a/data/docs.yaml b/data/docs.yaml index 6815c0661..b5a519c2c 100644 --- a/data/docs.yaml +++ b/data/docs.yaml @@ -2181,12 +2181,12 @@ tpl: Description: |- Append appends args up to the last one to the slice in the last argument. This construct allows template constructs like this: - + {{ $pages = $pages | append $p2 $p1 }} - + Note that with 2 arguments where both are slices of the same type, the first slice will be appended to the second: - + {{ $pages = $pages | append .Site.RegularPages }} Examples: [] Apply: @@ -2207,11 +2207,11 @@ tpl: Description: |- Complement gives the elements in the last element of ls that are not in any of the others. - + All elements of ls must be slices or arrays of comparable types. - + The reasoning behind this rather clumsy API is so we can do this in the templates: - + {{ $c := .Pages | complement $last4 }} Examples: - - '{{ slice "a" "b" "c" "d" "e" "f" | complement (slice "b" "c") (slice "d" "e") }}' @@ -2286,9 +2286,9 @@ tpl: Index returns the result of indexing its first argument by the following arguments. Thus "index x 1 2 3" is, in Go syntax, x[1][2][3]. Each indexed item must be a map, slice, or array. - + Adapted from Go stdlib src/text/template/funcs.go. - + We deviate from the stdlib mostly because of https://github.com/golang/go/issues/14751. Examples: [] Intersect: @@ -2338,7 +2338,7 @@ tpl: Description: |- Merge creates a copy of the final parameter in params and merges the preceding parameters into it in reverse order. - + Currently only maps are supported. Key handling is case insensitive. Examples: - - '{{ dict "title" "Hugo Rocks!" | collections.Merge (dict "title" "Default Title" "description" "Yes, Hugo Rocks!") | sort }}' @@ -2385,9 +2385,9 @@ tpl: - args Description: |- Seq creates a sequence of integers from args. It's named and used as GNU's seq. - + Examples: - + 3 => 1, 2, 3 1 2 4 => 1, 3 -3 => -1, -2, -3 @@ -2476,7 +2476,7 @@ tpl: - v2 Description: |- Conditional can be used as a ternary operator. - + It returns v1 if cond is true, else v2. Examples: - - '{{ cond (eq (add 2 2) 4) "2+2 is 4" "what?" | safeHTML }}' @@ -2644,10 +2644,10 @@ tpl: Dump returns a object dump of val as a string. Note that not every value passed to Dump will print so nicely, but we'll improve on that. - + We recommend using the "go" Chroma lexer to format the output nicely. - + Also note that the output from Dump may change from Hugo version to the next, so don't depend on a specific output. Examples: @@ -3049,7 +3049,7 @@ tpl: - v Description: |- Humanize returns the humanized form of v. - + If v is either an integer or a string containing an integer value, the behavior is to add the appropriate ordinal. Examples: @@ -3113,7 +3113,7 @@ tpl: Description: |- FormatAccounting returns the currency representation of number for the given currency and precision for the current language in accounting notation. - + The return value is formatted with at least two decimal places. Examples: - - '{{ 512.5032 | lang.FormatAccounting 2 "NOK" }}' @@ -3127,7 +3127,7 @@ tpl: Description: |- FormatCurrency returns the currency representation of number for the given currency and precision for the current language. - + The return value is formatted with at least two decimal places. Examples: - - '{{ 512.5032 | lang.FormatCurrency 2 "USD" }}' @@ -3725,16 +3725,16 @@ tpl: so if you organize your resources in sub-folders, you need to be explicit about it, e.g.: "images/*.png". To match any PNG image anywhere in the bundle you can do "**.png", and to match all PNG images below the images folder, use "images/**.jpg". - + The matching is case insensitive. - + Match matches by using the files name with path relative to the file system root with Unix style slashes (/) and no leading slash, e.g. "images/logo.png". - + See https://github.com/gobwas/glob for the full rules set. - + It looks for files in the assets file system. - + See Match for a more complete explanation about the rules used. Examples: [] Minify: @@ -4075,7 +4075,7 @@ tpl: expression in content. Each element is a slice of strings holding the text of the leftmost match of the regular expression and the matches, if any, of its subexpressions. - + By default all matches will be included. The number of matches can be limited with the optional limit parameter. A return value of nil indicates no match. @@ -4435,7 +4435,7 @@ tpl: - s Description: |- Emojify returns a copy of s with all emoji codes replaced with actual emojis. - + See http://www.emoji-cheat-sheet.com/ Examples: - - '{{ "I :heart: Hugo" | emojify }}' diff --git a/layouts/_markup/render-codeblock.html b/layouts/_markup/render-codeblock.html index 0f1d09d1f..f9a7d8ddf 100644 --- a/layouts/_markup/render-codeblock.html +++ b/layouts/_markup/render-codeblock.html @@ -80,7 +80,7 @@ may also specify the following parameters:
    + class="render-hook-codeblock font-mono not-prose relative mt-6 mb-8 border border-gray-200 dark:border-gray-800 bg-light dark:bg-dark"> {{- $fileSelectClass := "select-none" }} {{- if $copy }} {{- $fileSelectClass = "select-text" }} diff --git a/layouts/_partials/helpers/validation/validate-keywords.html b/layouts/_partials/helpers/validation/validate-keywords.html index 3447ec4ef..58500c0a4 100644 --- a/layouts/_partials/helpers/validation/validate-keywords.html +++ b/layouts/_partials/helpers/validation/validate-keywords.html @@ -11,7 +11,7 @@ effort. */}} {{/* prettier-ignore-end */ -}} {{- $t := debug.Timer "validateKeywords" }} -{{- $allowedKeywords := collections.Apply site.Data.keywords "strings.ToLower" "." }} +{{- $allowedKeywords := collections.Apply hugo.Data.keywords "strings.ToLower" "." }} {{- range $p := site.Pages }} {{- range .Params.keywords }} {{- if not (in $allowedKeywords (lower .)) }} diff --git a/layouts/_partials/layouts/home/sponsors.html b/layouts/_partials/layouts/home/sponsors.html index 1f391e1ec..465106de6 100644 --- a/layouts/_partials/layouts/home/sponsors.html +++ b/layouts/_partials/layouts/home/sponsors.html @@ -3,7 +3,7 @@ {{ $isFooter := (eq $gtag "footer") }} {{ $utmSource := cond $isFooter "hugofooter" "hugohome" }} {{ $containerClass := .containerClass | default "mx-auto max-w-7xl px-6 lg:px-8" }} -{{ with .ctx.Site.Data.sponsors }} +{{ with hugo.Data.sponsors }}

    Hugo Sponsors

    diff --git a/layouts/_shortcodes/chroma-lexers.html b/layouts/_shortcodes/chroma-lexers.html index fd7130501..95bc944b6 100644 --- a/layouts/_shortcodes/chroma-lexers.html +++ b/layouts/_shortcodes/chroma-lexers.html @@ -12,7 +12,7 @@ Renders an HTML template of Chroma lexers and their aliases. Identifiers - {{- range site.Data.docs.chroma.lexers }} + {{- range hugo.Data.docs.chroma.lexers }} {{ .Name }} diff --git a/layouts/_shortcodes/code-toggle.html b/layouts/_shortcodes/code-toggle.html index a22c378be..48a83b3d3 100644 --- a/layouts/_shortcodes/code-toggle.html +++ b/layouts/_shortcodes/code-toggle.html @@ -2,12 +2,12 @@ {{- /* Renders syntax-highlighted configuration data in JSON, TOML, and YAML formats. -@param {string} [config] The section of site.Data.docs.config to render. +@param {string} [config] The section of hugo.Data.docs.config to render. @param {bool} [copy=false] Whether to display a copy-to-clipboard button. -@param {string} [dataKey] The section of site.Data.docs to render. +@param {string} [dataKey] The section of hugo.Data.docs to render. @param {string} [file] The file name to display above the rendered code. @param {bool} [fm=false] Whether to render the code as front matter. -@param {bool} [skipHeader=false] Whether to omit top level key(s) when rendering a section of site.Data.docs.config. +@param {bool} [skipHeader=false] Whether to omit top level key(s) when rendering a section of hugo.Data.docs.config. @example {{< code-toggle file=hugo config=build />}} @@ -55,7 +55,7 @@ Renders syntax-highlighted configuration data in JSON, TOML, and YAML formats. {{- if $config }} {{- $file = $file | default "hugo" }} {{- $sections := (split $config ".") }} - {{- $configSection := index $.Site.Data.docs.config $sections }} + {{- $configSection := index hugo.Data.docs.config $sections }} {{- $code = dict $sections $configSection }} {{- if $skipHeader }} {{- $code = $configSection }} @@ -63,7 +63,7 @@ Renders syntax-highlighted configuration data in JSON, TOML, and YAML formats. {{- else if $dataKey }} {{- $file = $file | default $dataKey }} {{- $sections := (split $dataKey ".") }} - {{- $code = index $.Site.Data.docs $sections }} + {{- $code = index hugo.Data.docs $sections }} {{- else }} {{- $code = $.Inner }} {{- end }} diff --git a/layouts/_shortcodes/datatable.html b/layouts/_shortcodes/datatable.html index f135d841c..0ee540d83 100644 --- a/layouts/_shortcodes/datatable.html +++ b/layouts/_shortcodes/datatable.html @@ -1,6 +1,6 @@ {{ $package := (index .Params 0) }} {{ $listname := (index .Params 1) }} -{{ $list := (index (index .Site.Data.docs $package) $listname) }} +{{ $list := (index (index hugo.Data.docs $package) $listname) }} {{ $fields := after 2 .Params }} diff --git a/layouts/_shortcodes/eturl.html b/layouts/_shortcodes/eturl.html index a0237dbe0..41faf98c7 100644 --- a/layouts/_shortcodes/eturl.html +++ b/layouts/_shortcodes/eturl.html @@ -12,9 +12,9 @@ embedded_templates.toml file in the data directory. */ -}} {{/* prettier-ignore-end */ -}} {{- with $filename := or (.Get "filename") (.Get 0) }} - {{- with site.Data.embedded_template_urls }} + {{- with hugo.Data.embedded_template_urls }} {{- with index . $filename }} - {{- urls.JoinPath site.Data.embedded_template_urls.base_url . }} + {{- urls.JoinPath hugo.Data.embedded_template_urls.base_url . }} {{- else }} {{- errorf "The %q shortcode was unable to find a URL for the embedded template named %q. Check the name. See %s" $.Name $filename $.Position }} {{- end }} diff --git a/layouts/_shortcodes/list-pages-in-section.html b/layouts/_shortcodes/list-pages-in-section.html index df06d53ca..cf74bd93a 100644 --- a/layouts/_shortcodes/list-pages-in-section.html +++ b/layouts/_shortcodes/list-pages-in-section.html @@ -27,7 +27,7 @@ if any of the pages in the filter do not exist. {{/* Build slice of filtered pages. */}} {{ with $filter }} - {{ with index site.Data.page_filters . }} + {{ with index hugo.Data.page_filters . }} {{ range . }} {{ with site.GetPage . }} {{ $filteredPages = $filteredPages | append . }} diff --git a/layouts/_shortcodes/root-configuration-keys.html b/layouts/_shortcodes/root-configuration-keys.html index 46a6e074f..a9c685fc3 100644 --- a/layouts/_shortcodes/root-configuration-keys.html +++ b/layouts/_shortcodes/root-configuration-keys.html @@ -7,7 +7,7 @@ Renders a comma-separated list of links to the root key configuration pages. {{/* prettier-ignore-end */ -}} {{- /* Create scratch map of key:filename. */}} {{- $s := newScratch }} -{{- range $k, $v := site.Data.docs.config }} +{{- range $k, $v := hugo.Data.docs.config }} {{- if or (reflect.IsMap .) (reflect.IsSlice .) }} {{- $s.Set $k ($k | humanize | anchorize) }} {{- end }} diff --git a/layouts/_shortcodes/syntax-highlighting-styles.html b/layouts/_shortcodes/syntax-highlighting-styles.html index 297849cef..de6bbdb3b 100644 --- a/layouts/_shortcodes/syntax-highlighting-styles.html +++ b/layouts/_shortcodes/syntax-highlighting-styles.html @@ -51,7 +51,7 @@ string = 'foo' {{- $examples := $examples | append $example }} {{- /* Render */}} -{{- with site.Data.docs.chroma.styles }} +{{- with hugo.Data.docs.chroma.styles }} {{- range $style := . }} ### {{ $style }} {class="!mt-7 !mb-6"}{{/* Do not indent. */}} diff --git a/netlify.toml b/netlify.toml index 290bbd32d..c49f06d41 100644 --- a/netlify.toml +++ b/netlify.toml @@ -3,7 +3,7 @@ command = "npm ls && hugo --gc --minify" [build.environment] - HUGO_VERSION = "0.155.3" + HUGO_VERSION = "0.156.0" [context.production.environment] HUGO_ENV = "production" -- 2.39.5