From 5be51ac3db225d5df501ed1fa1499c41d97dbf65 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bj=C3=B8rn=20Erik=20Pedersen?= Date: Thu, 10 Apr 2025 13:02:49 +0200 Subject: [PATCH] Squashed 'docs/' changes from d1a251933..dc7a9ae12 dc7a9ae12 content: Update JS options 07d3d8803 npm: Use tilde ranges for versions e06362a13 Minor grammar fixes c42db0838 content: Algolia DocSearch clarification d67412b82 deps: Upgrade to TailwindCSS 4.1.0 da1fb12d3 theme: Update Lato font path for images.Text example 140fa3bb9 Update introduction.md 7b1fcca27 content: Fix links to embedded template source 908a55532 theme: Improve dark mode syntax highlighting background d830e5962 Update XxHash.md 807be5dbf Update Defer.md 4b56693f6 content: Update GitHub Pages sample workflow 57b766fba Update TailwindCSS.md 64982ab6a Update TailwindCSS.md 1b6e879c6 Update TailwindCSS.md e67cbcdd2 content: Add caching to the GitHub Pages workflow example b7ca3b07c Update index.md 14e1a3977 Update XxHash.md 980f344ae Update XxHash.md 6b815f03e theme: Remove aria-label attribute from links 1c00bbc45 theme: Update npm dependencies 533149bf9 theme: Include section pages in related content 2b6bda6bd content: Fix typos 92ce95cbb content: Miscellaneous edits f12936681 theme: Add a simple LRU cache for search 339ca3388 Fix the previous broken commit 8537e59e0 Make it into a non-link e13f17d29 Add Algolia logo/link to the search listing dialog d3e09e886 content: Fix typo 7217f64b6 content: Miscellaneous edits 51aa1ae73 content: Improve some examples 8ebaa53f9 theme: Adjust shortcodes 898870438 theme: Hide anchor until mouse-over c933ea237 content: More front matter cleanup f26ca047a content: Miscellaneous edits e272b2039 theme: Fix inline partial refs c540e6d29 content: Replace note shortcode calls with blockquote alerts aef899bc5 theme: Add title and QR code when printing bd46ef626 theme: Implement blockquote render hook ddefbefaa content: Improve contributing page f41d28ee1 content: Adjust usage of whitespace removal with action delimiters 03315336d theme: Use full title in related content sidebar 4f4076364 misc: Document the front matter fields used on this site 2f78d7632 misc: Fix gitignore file 7de6dbab3 content: Fix front matter for several function pages 5d3542ea6 config: Disable tags taxonomy 68bc28d67 content: Add linkTitle to shortcode pages 5f32c92ed theme: Restore deduplication logic for related items a943a4bb8 theme: Implement related content tooling fd628be6e content: Replace calls to the code shortcode with fenced code blocks b23c9a583 content: Fix position of new-in badges ec056f251 content: Fix typo 245351c84 theme: Adjust spacing in highlighting theme examples 2fcd21ee5 content: Remove "related" array from function and method pages 71d8426ee theme: Create code block render hook 4cdde6649 theme: Adjust number of news items to display 34ab45261 content: Miscellaneous edits b6cae5cbc content: Consolidate configuration documentation 727ef6f66 theme: Fix overflow issue for wide tables c4f759e01 Add es2024 93cce62c8 Update support list of more recent targets with js.Build / esbuild 974d0655f Update hosting-on-codeberg.md b3f0ed9ce content: Add hosting instructions for Codeberg Pages 8217c0900 content: Correct the SourceHut repository URL a8cf3d28f content: Add hosting instructions for SourceHut Pages 8c059cbe1 theme: Use content adapter for news section 03938c600 Remove some old new-in 5c50a75e8 content: Fix typo 5cf89f2f6 theme: Re-enable banner gtag outbound link tracking 3c555d5f8 One more copy button 94bce999a Add some copy buttons 9e1cc0c2b Update PortableText.md dd26ac49f Document transform.PortableText 5f632ab32 netlify: Hugo 0.145.0 59e057bb4 Update index.md d07e07d6c Remove some unused home page front matter d482657b7 Add footnote about alias to the build front matter key f0629b77c content: Fix typo d91c4cccf theme: Fix news items URLs ca931cd1f theme: Restore RSS feed for news section e6b870bc9 theme: Adjust copy-to-clipboard button 071851431 Update netlify.toml e68431034 theme: Format layouts aa3cd839a theme: Format assets 22ad3eee3 theme: Add some more space on the right for copy buttons f4a19083a netlify: Hugo 0.144.1 974cb8795 theme: Remove Internet Explorer configs (#2929) 4a23a1f41 content: Fix typos d49f15d03 theme: Get the scrollspy back working 720c7ff67 config: Evict getresource cache hourly 1f62ca97e theme: Hide the Turbo progress bar f6449ace3 Move the dark class up to the html element 074cd1a07 content: Miscellaneous edits e098a7716 content: Miscellaneous edits 8e1e104aa content: Updates for v0.144.0 18e1aa916 theme: Add anchor links via JS ac3b5505c Close new-in bfa4db6b8 netlify: Hugo 0.144.0 fd6e7feee Regen CLI docs da9d1218a Regen docs helper 5de494ded Merge branch 'tempv0.144.0' f683e6469 theme: Minor improvements to base template ef8bf89d8 resources/page: Revise the new contentbasename permalinks tokens 901adb07b resources/page: Add :contentbasename and :contentbasenameorslug permalink tokens 0fca8ef25 all: Change shortcode usage and design to prevent invalid HTML c41d76613 Update RegularPagesRecursive.md e93574748 content: Correct return type for strings.Split 3d504abba Revert "content: Add ids to the Netlify steps" c08c8e15e content: Add ids to the Netlify steps 5a3b470a2 theme: "move" the id from content to article b878613aa theme: Add page kind as a CSS class to body 269657e8f content: Fix formatting error 664f6c92f config: Change image cache location fa6b719b1 theme: Reduce ToC to level 2-4 bc16341ca theme: Render mathematical markup with transform.ToMath 14bf9dc70 theme: Add aria-label attribute to search fields ed42af5b3 theme: Adjust search field and search activation f042e4970 dev: Add prettier-plugin-void-html f6ec83533 content: Fix inline shortcode example 0a74210e2 theme: Remove readfile shortcode 334ca06ac theme: Fix some dark mode accessibility as reported by Axe core 02626ff92 theme: aria-lbabel => aria-label 227b76ab7 Add Prettier and config 43ab22428 content: Bump minimum required Go version to 1.23.0 03e54683f modules: Add GOAUTH to module config 9f06a3b9c js/esbuild: Add drop option ddcd99369 Merge commit 'a024bc7d76fcc5e49e8210f9b0896db9ef21861a' 733731253 helpers: Add Chroma styles to docs.yaml git-subtree-dir: docs git-subtree-split: dc7a9ae127717cde17840496cb0287f481c5f0ee --- .cspell.json | 5 +- .gitignore | 5 +- .markdownlint.yaml | 1 + .prettierignore | 18 + .prettierrc | 24 + LICENSE.md | 2 +- README.md | 4 +- archetypes/default.md | 6 + archetypes/functions.md | 10 +- archetypes/glossary.md | 3 +- archetypes/methods.md | 8 +- archetypes/news.md | 7 + archetypes/news/index.md | 5 - archetypes/showcase/bio.md | 7 - archetypes/showcase/index.md | 36 - assets/css/components/all.css | 2 +- assets/css/components/chroma_dark.css | 2 +- assets/css/components/content.css | 19 +- assets/css/components/view-transitions.css | 4 +- assets/css/styles.css | 12 +- assets/js/alpinejs/data/explorer.js | 2 +- assets/js/alpinejs/data/navbar.js | 18 + assets/js/alpinejs/data/search.js | 16 +- assets/js/alpinejs/data/toc.js | 2 +- assets/js/alpinejs/stores/nav.js | 4 +- assets/js/helpers/index.js | 1 + assets/js/helpers/lrucache.js | 19 + content/en/_common/_index.md | 4 +- content/en/_common/content-format-table.md | 13 + content/en/_common/filter-sort-group.md | 8 + .../functions/fmt/format-string.md} | 0 .../functions}/go-html-template-package.md | 0 .../functions/go-template}/text-template.md | 0 .../functions/images}/apply-image-filter.md | 0 content/en/_common/functions/js/options.md | 108 ++ content/en/_common/functions/locales.md | 8 + .../functions}/regular-expressions.md | 0 .../functions}/truthy-falsy.md | 0 .../functions/urls}/anchorize-vs-urlize.md | 2 +- .../{functions => }/_common/glob-patterns.md | 0 content/en/_common/gomodules-info.md | 13 + .../installation}/01-editions.md | 2 +- .../installation}/02-prerequisites.md | 0 .../installation}/03-prebuilt-binaries.md | 0 .../installation}/04-build-from-source.md | 2 +- .../installation}/homebrew.md | 0 .../menu-entries/pre-and-post.md} | 0 content/en/_common/menu-entry-properties.md | 31 + .../methods/page}/next-and-prev.md | 10 +- .../page}/nextinsection-and-previnsection.md | 10 +- .../methods/page/output-format-methods.md | 35 + .../methods/pages}/group-sort-order.md | 0 .../methods/pages}/next-and-prev.md | 14 +- .../resource/global-page-remote-resources.md | 6 + .../methods/resource}/processing-spec.md | 0 .../taxonomy}/get-a-taxonomy-object.md | 4 +- .../ordered-taxonomy-element-methods.md | 0 .../_common/parsable-date-time-strings.md | 0 content/en/_common/permalink-tokens.md | 71 ++ .../_common/ref-and-relref-error-handling.md | 10 + content/en/_common/ref-and-relref-options.md | 12 + .../render-hooks}/pageinner.md | 22 +- content/en/_common/store-methods.md | 16 +- .../syntax-highlighting-options.md} | 33 +- .../_common/time-layout-string.md | 0 content/en/_index.md | 49 +- content/en/about/_index.md | 9 +- content/en/about/features.md | 23 +- content/en/about/introduction.md | 17 +- content/en/about/license.md | 11 +- content/en/about/security.md | 80 +- content/en/commands/_index.md | 4 - content/en/commands/hugo.md | 1 + content/en/configuration/_index.md | 7 + content/en/configuration/all.md | 362 +++++++ content/en/configuration/build.md | 81 ++ content/en/configuration/caches.md | 30 + content/en/configuration/cascade.md | 77 ++ content/en/configuration/content-types.md | 63 ++ content/en/configuration/deployment.md | 159 +++ content/en/configuration/front-matter.md | 91 ++ content/en/configuration/http-cache.md | 107 ++ content/en/configuration/imaging.md | 69 ++ content/en/configuration/introduction.md | 284 +++++ content/en/configuration/languages.md | 193 ++++ content/en/configuration/markup.md | 341 ++++++ content/en/configuration/media-types.md | 82 ++ content/en/configuration/menus.md | 135 +++ content/en/configuration/minify.md | 15 + content/en/configuration/module.md | 179 ++++ content/en/configuration/output-formats.md | 209 ++++ content/en/configuration/outputs.md | 49 + content/en/configuration/page.md | 34 + content/en/configuration/pagination.md | 45 + content/en/configuration/params.md | 100 ++ content/en/configuration/permalinks.md | 162 +++ .../en/{about => configuration}/privacy.md | 21 +- content/en/configuration/related-content.md | 111 ++ content/en/configuration/security.md | 50 + content/en/configuration/segments.md | 77 ++ content/en/configuration/server.md | 128 +++ content/en/configuration/services.md | 52 + content/en/configuration/sitemap.md | 24 + content/en/configuration/taxonomies.md | 68 ++ content/en/configuration/ugly-urls.md | 36 + .../en/content-management/_common/_index.md | 13 - .../content-management/_common/page-kinds.md | 17 - content/en/content-management/_index.md | 8 - content/en/content-management/archetypes.md | 15 +- .../en/content-management/build-options.md | 89 +- content/en/content-management/comments.md | 18 +- .../en/content-management/content-adapters.md | 95 +- .../en/content-management/cross-references.md | 148 --- content/en/content-management/data-sources.md | 35 +- content/en/content-management/diagrams.md | 37 +- content/en/content-management/formats.md | 27 +- content/en/content-management/front-matter.md | 411 +++----- .../image-processing/index.md | 137 +-- .../content-management/markdown-attributes.md | 10 +- content/en/content-management/mathematics.md | 73 +- content/en/content-management/menus.md | 157 +-- content/en/content-management/multilingual.md | 281 +---- .../1-featured-content-bundles.png | Bin 34394 -> 0 bytes .../content-management/organization/index.md | 29 +- content/en/content-management/page-bundles.md | 48 +- .../en/content-management/page-resources.md | 69 +- .../en/content-management/related-content.md | 102 ++ content/en/content-management/related.md | 156 --- content/en/content-management/sections.md | 39 +- content/en/content-management/shortcodes.md | 83 +- content/en/content-management/summaries.md | 24 +- .../content-management/syntax-highlighting.md | 198 ++-- content/en/content-management/taxonomies.md | 84 +- content/en/content-management/types.md | 10 +- content/en/content-management/urls.md | 272 +---- content/en/contribute/_index.md | 9 +- content/en/contribute/development.md | 112 +- content/en/contribute/documentation.md | 488 +++++---- content/en/contribute/themes.md | 9 +- content/en/documentation.md | 22 +- content/en/functions/_common/_index.md | 13 - content/en/functions/_common/locales.md | 10 - content/en/functions/_index.md | 9 - content/en/functions/cast/ToFloat.md | 12 +- content/en/functions/cast/ToInt.md | 17 +- content/en/functions/cast/ToString.md | 12 +- content/en/functions/cast/_index.md | 7 +- content/en/functions/collections/After.md | 16 +- content/en/functions/collections/Append.md | 15 +- content/en/functions/collections/Apply.md | 10 +- .../en/functions/collections/Complement.md | 29 +- content/en/functions/collections/Delimit.md | 16 +- .../en/functions/collections/Dictionary.md | 11 +- content/en/functions/collections/First.md | 15 +- content/en/functions/collections/Group.md | 10 +- content/en/functions/collections/In.md | 15 +- .../en/functions/collections/IndexFunction.md | 11 +- content/en/functions/collections/Intersect.md | 13 +- content/en/functions/collections/IsSet.md | 17 +- content/en/functions/collections/KeyVals.md | 13 +- content/en/functions/collections/Last.md | 14 +- content/en/functions/collections/Merge.md | 16 +- .../en/functions/collections/NewScratch.md | 33 +- content/en/functions/collections/Querify.md | 12 +- content/en/functions/collections/Reverse.md | 13 +- content/en/functions/collections/Seq.md | 21 +- content/en/functions/collections/Shuffle.md | 13 +- content/en/functions/collections/Slice.md | 11 +- content/en/functions/collections/Sort.md | 28 +- content/en/functions/collections/SymDiff.md | 14 +- content/en/functions/collections/Union.md | 26 +- content/en/functions/collections/Uniq.md | 14 +- content/en/functions/collections/Where.md | 62 +- content/en/functions/collections/_index.md | 7 +- content/en/functions/compare/Conditional.md | 11 +- content/en/functions/compare/Default.md | 31 +- content/en/functions/compare/Eq.md | 15 +- content/en/functions/compare/Ge.md | 15 +- content/en/functions/compare/Gt.md | 15 +- content/en/functions/compare/Le.md | 15 +- content/en/functions/compare/Lt.md | 15 +- content/en/functions/compare/Ne.md | 15 +- content/en/functions/compare/_index.md | 7 +- content/en/functions/crypto/FNV32a.md | 16 +- content/en/functions/crypto/HMAC.md | 14 +- content/en/functions/crypto/MD5.md | 14 +- content/en/functions/crypto/SHA1.md | 14 +- content/en/functions/crypto/SHA256.md | 14 +- content/en/functions/crypto/_index.md | 7 +- content/en/functions/css/PostCSS.md | 58 +- content/en/functions/css/Sass.md | 32 +- content/en/functions/css/TailwindCSS.md | 50 +- content/en/functions/css/_index.md | 7 +- content/en/functions/data/GetCSV.md | 24 +- content/en/functions/data/GetJSON.md | 20 +- content/en/functions/data/_index.md | 7 +- content/en/functions/debug/Dump.md | 15 +- content/en/functions/debug/Timer.md | 10 +- content/en/functions/debug/_index.md | 7 +- content/en/functions/diagrams/Goat.md | 38 +- content/en/functions/diagrams/_index.md | 7 +- content/en/functions/encoding/Base64Decode.md | 13 +- content/en/functions/encoding/Base64Encode.md | 11 +- content/en/functions/encoding/Jsonify.md | 15 +- content/en/functions/encoding/_index.md | 7 +- content/en/functions/fmt/Errorf.md | 15 +- content/en/functions/fmt/Erroridf.md | 15 +- content/en/functions/fmt/Print.md | 12 +- content/en/functions/fmt/Printf.md | 14 +- content/en/functions/fmt/Println.md | 12 +- content/en/functions/fmt/Warnf.md | 15 +- content/en/functions/fmt/Warnidf.md | 15 +- content/en/functions/fmt/_common/_index.md | 13 - content/en/functions/fmt/_index.md | 7 +- content/en/functions/global/_index.md | 7 +- content/en/functions/global/page.md | 21 +- content/en/functions/global/site.md | 16 +- .../functions/go-template/_common/_index.md | 13 - content/en/functions/go-template/_index.md | 9 +- content/en/functions/go-template/and.md | 16 +- content/en/functions/go-template/block.md | 26 +- content/en/functions/go-template/break.md | 14 +- content/en/functions/go-template/continue.md | 14 +- content/en/functions/go-template/define.md | 17 +- content/en/functions/go-template/else.md | 16 +- content/en/functions/go-template/end.md | 17 +- content/en/functions/go-template/if.md | 18 +- content/en/functions/go-template/len.md | 16 +- content/en/functions/go-template/not.md | 14 +- content/en/functions/go-template/or.md | 16 +- content/en/functions/go-template/range.md | 34 +- content/en/functions/go-template/return.md | 49 +- content/en/functions/go-template/template.md | 15 +- content/en/functions/go-template/try.md | 34 +- content/en/functions/go-template/urlquery.md | 13 +- content/en/functions/go-template/with.md | 29 +- content/en/functions/hash/FNV32a.md | 17 +- content/en/functions/hash/XxHash.md | 17 +- content/en/functions/hash/_index.md | 7 +- content/en/functions/hugo/BuildDate.md | 10 +- content/en/functions/hugo/CommitHash.md | 10 +- content/en/functions/hugo/Deps.md | 10 +- content/en/functions/hugo/Environment.md | 12 +- content/en/functions/hugo/Generator.md | 14 +- content/en/functions/hugo/GoVersion.md | 10 +- content/en/functions/hugo/IsDevelopment.md | 12 +- content/en/functions/hugo/IsExtended.md | 10 +- content/en/functions/hugo/IsMultihost.md | 11 +- content/en/functions/hugo/IsMultilingual.md | 10 +- content/en/functions/hugo/IsProduction.md | 12 +- content/en/functions/hugo/IsServer.md | 10 +- content/en/functions/hugo/Store.md | 29 +- content/en/functions/hugo/Version.md | 12 +- content/en/functions/hugo/WorkingDir.md | 10 +- content/en/functions/hugo/_index.md | 7 +- content/en/functions/images/AutoOrient.md | 20 +- content/en/functions/images/Brightness.md | 15 +- content/en/functions/images/ColorBalance.md | 15 +- content/en/functions/images/Colorize.md | 15 +- content/en/functions/images/Config.md | 19 +- content/en/functions/images/Contrast.md | 15 +- content/en/functions/images/Dither.md | 21 +- content/en/functions/images/Filter.md | 14 +- content/en/functions/images/Gamma.md | 15 +- content/en/functions/images/GaussianBlur.md | 15 +- content/en/functions/images/Grayscale.md | 15 +- content/en/functions/images/Hue.md | 15 +- content/en/functions/images/Invert.md | 15 +- content/en/functions/images/Mask.md | 27 +- content/en/functions/images/Opacity.md | 15 +- content/en/functions/images/Overlay.md | 15 +- content/en/functions/images/Padding.md | 15 +- content/en/functions/images/Pixelate.md | 15 +- content/en/functions/images/Process.md | 16 +- content/en/functions/images/QR.md | 39 +- content/en/functions/images/Saturation.md | 15 +- content/en/functions/images/Sepia.md | 15 +- content/en/functions/images/Sigmoid.md | 15 +- content/en/functions/images/Text.md | 19 +- content/en/functions/images/UnsharpMask.md | 15 +- content/en/functions/images/_common/_index.md | 13 - content/en/functions/images/_index.md | 5 - content/en/functions/inflect/Humanize.md | 12 +- content/en/functions/inflect/Pluralize.md | 12 +- content/en/functions/inflect/Singularize.md | 12 +- content/en/functions/inflect/_index.md | 7 +- content/en/functions/js/Babel.md | 71 +- content/en/functions/js/Batch.md | 146 ++- content/en/functions/js/Build.md | 40 +- content/en/functions/js/_common/_index.md | 13 - content/en/functions/js/_common/options.md | 121 --- content/en/functions/js/_index.md | 7 +- content/en/functions/lang/FormatAccounting.md | 16 +- content/en/functions/lang/FormatCurrency.md | 16 +- content/en/functions/lang/FormatNumber.md | 16 +- .../en/functions/lang/FormatNumberCustom.md | 16 +- content/en/functions/lang/FormatPercent.md | 16 +- content/en/functions/lang/Merge.md | 10 +- content/en/functions/lang/Translate.md | 65 +- content/en/functions/lang/_index.md | 7 +- content/en/functions/math/Abs.md | 10 +- content/en/functions/math/Acos.md | 17 +- content/en/functions/math/Add.md | 15 +- content/en/functions/math/Asin.md | 17 +- content/en/functions/math/Atan.md | 17 +- content/en/functions/math/Atan2.md | 17 +- content/en/functions/math/Ceil.md | 12 +- content/en/functions/math/Cos.md | 17 +- content/en/functions/math/Counter.md | 18 +- content/en/functions/math/Div.md | 15 +- content/en/functions/math/Floor.md | 12 +- content/en/functions/math/Log.md | 10 +- content/en/functions/math/Max.md | 11 +- content/en/functions/math/Min.md | 11 +- content/en/functions/math/Mod.md | 11 +- content/en/functions/math/ModBool.md | 11 +- content/en/functions/math/Mul.md | 15 +- content/en/functions/math/Pi.md | 17 +- content/en/functions/math/Pow.md | 11 +- content/en/functions/math/Product.md | 17 +- content/en/functions/math/Rand.md | 10 +- content/en/functions/math/Round.md | 12 +- content/en/functions/math/Sin.md | 17 +- content/en/functions/math/Sqrt.md | 11 +- content/en/functions/math/Sub.md | 17 +- content/en/functions/math/Sum.md | 17 +- content/en/functions/math/Tan.md | 17 +- content/en/functions/math/ToDegrees.md | 12 +- content/en/functions/math/ToRadians.md | 12 +- content/en/functions/math/_index.md | 7 +- content/en/functions/openapi3/Unmarshal.md | 10 +- content/en/functions/openapi3/_index.md | 7 +- content/en/functions/os/FileExists.md | 16 +- content/en/functions/os/Getenv.md | 19 +- content/en/functions/os/ReadDir.md | 14 +- content/en/functions/os/ReadFile.md | 16 +- content/en/functions/os/Stat.md | 16 +- content/en/functions/os/_index.md | 7 +- content/en/functions/partials/Include.md | 14 +- .../en/functions/partials/IncludeCached.md | 32 +- content/en/functions/partials/_index.md | 7 +- content/en/functions/path/Base.md | 18 +- content/en/functions/path/BaseName.md | 16 +- content/en/functions/path/Clean.md | 16 +- content/en/functions/path/Dir.md | 16 +- content/en/functions/path/Ext.md | 16 +- content/en/functions/path/Join.md | 17 +- content/en/functions/path/Split.md | 18 +- content/en/functions/path/_index.md | 7 +- content/en/functions/reflect/IsMap.md | 11 +- content/en/functions/reflect/IsSlice.md | 11 +- content/en/functions/reflect/_index.md | 7 +- content/en/functions/resources/Babel.md | 13 +- content/en/functions/resources/ByType.md | 25 +- content/en/functions/resources/Concat.md | 10 +- content/en/functions/resources/Copy.md | 15 +- .../functions/resources/ExecuteAsTemplate.md | 27 +- content/en/functions/resources/Fingerprint.md | 15 +- content/en/functions/resources/FromString.md | 11 +- content/en/functions/resources/Get.md | 24 +- content/en/functions/resources/GetMatch.md | 32 +- content/en/functions/resources/GetRemote.md | 51 +- content/en/functions/resources/Match.md | 29 +- content/en/functions/resources/Minify.md | 15 +- content/en/functions/resources/PostCSS.md | 13 +- content/en/functions/resources/PostProcess.md | 51 +- content/en/functions/resources/ToCSS.md | 13 +- .../en/functions/resources/_common/_index.md | 12 - .../_common/postcss-windows-warning.md | 8 - content/en/functions/resources/_index.md | 7 +- content/en/functions/safe/CSS.md | 27 +- content/en/functions/safe/HTML.md | 18 +- content/en/functions/safe/HTMLAttr.md | 20 +- content/en/functions/safe/JS.md | 18 +- content/en/functions/safe/JSStr.md | 18 +- content/en/functions/safe/URL.md | 27 +- content/en/functions/safe/_index.md | 9 +- content/en/functions/strings/Chomp.md | 16 +- content/en/functions/strings/Contains.md | 15 +- content/en/functions/strings/ContainsAny.md | 15 +- .../en/functions/strings/ContainsNonSpace.md | 15 +- content/en/functions/strings/Count.md | 14 +- content/en/functions/strings/CountRunes.md | 14 +- content/en/functions/strings/CountWords.md | 14 +- content/en/functions/strings/Diff/index.md | 8 +- .../en/functions/strings/FindRESubmatch.md | 20 +- content/en/functions/strings/FindRe.md | 20 +- content/en/functions/strings/FirstUpper.md | 13 +- content/en/functions/strings/HasPrefix.md | 15 +- content/en/functions/strings/HasSuffix.md | 15 +- content/en/functions/strings/Repeat.md | 10 +- content/en/functions/strings/Replace.md | 13 +- content/en/functions/strings/ReplaceRE.md | 23 +- content/en/functions/strings/RuneCount.md | 14 +- content/en/functions/strings/SliceString.md | 11 +- content/en/functions/strings/Split.md | 16 +- content/en/functions/strings/Substr.md | 13 +- content/en/functions/strings/Title.md | 15 +- content/en/functions/strings/ToLower.md | 13 +- content/en/functions/strings/ToUpper.md | 13 +- content/en/functions/strings/Trim.md | 16 +- content/en/functions/strings/TrimLeft.md | 16 +- content/en/functions/strings/TrimPrefix.md | 16 +- content/en/functions/strings/TrimRight.md | 16 +- content/en/functions/strings/TrimSpace.md | 14 +- content/en/functions/strings/TrimSuffix.md | 16 +- content/en/functions/strings/Truncate.md | 15 +- content/en/functions/strings/_index.md | 7 +- content/en/functions/templates/Defer.md | 31 +- content/en/functions/templates/Exists.md | 10 +- content/en/functions/templates/_index.md | 8 +- content/en/functions/time/AsTime.md | 19 +- content/en/functions/time/Duration.md | 16 +- content/en/functions/time/Format.md | 23 +- content/en/functions/time/Now.md | 14 +- content/en/functions/time/ParseDuration.md | 14 +- content/en/functions/time/_common/_index.md | 13 - content/en/functions/time/_index.md | 7 +- .../en/functions/transform/CanHighlight.md | 12 +- content/en/functions/transform/Emojify.md | 16 +- content/en/functions/transform/HTMLEscape.md | 11 +- .../en/functions/transform/HTMLUnescape.md | 11 +- content/en/functions/transform/Highlight.md | 27 +- .../functions/transform/HighlightCodeBlock.md | 12 +- content/en/functions/transform/Markdownify.md | 22 +- content/en/functions/transform/Plainify.md | 10 +- .../en/functions/transform/PortableText.md | 213 ++++ content/en/functions/transform/Remarshal.md | 21 +- content/en/functions/transform/ToMath.md | 89 +- content/en/functions/transform/Unmarshal.md | 36 +- content/en/functions/transform/XMLEscape.md | 14 +- content/en/functions/transform/_index.md | 7 +- content/en/functions/urls/AbsLangURL.md | 55 +- content/en/functions/urls/AbsURL.md | 24 +- content/en/functions/urls/Anchorize.md | 15 +- content/en/functions/urls/JoinPath.md | 11 +- content/en/functions/urls/Parse.md | 11 +- content/en/functions/urls/Ref.md | 71 +- content/en/functions/urls/RelLangURL.md | 65 +- content/en/functions/urls/RelRef.md | 78 +- content/en/functions/urls/RelURL.md | 46 +- content/en/functions/urls/URLize.md | 13 +- content/en/functions/urls/_common/_index.md | 13 - content/en/functions/urls/_index.md | 7 +- content/en/getting-started/_index.md | 12 - .../en/getting-started/configuration-build.md | 85 -- .../getting-started/configuration-markup.md | 387 ------- content/en/getting-started/configuration.md | 996 ------------------ .../en/getting-started/directory-structure.md | 86 +- .../external-learning-resources/index.md | 21 +- content/en/getting-started/quick-start.md | 80 +- content/en/getting-started/usage.md | 56 +- content/en/host-and-deploy/_index.md | 8 + .../deploy-with-hugo-deploy.md | 97 ++ .../deploy-with-rclone.md} | 24 +- .../deploy-with-rsync.md} | 24 +- .../host-on-21yunbox.md} | 32 +- .../host-on-aws-amplify}/amplify-step-05.png | Bin .../host-on-aws-amplify}/amplify-step-06.png | Bin .../host-on-aws-amplify}/amplify-step-07.png | Bin .../host-on-aws-amplify}/amplify-step-08.png | Bin .../host-on-aws-amplify}/amplify-step-09.png | Bin .../host-on-aws-amplify}/amplify-step-11.png | Bin .../host-on-aws-amplify}/index.md | 79 +- .../host-on-azure-static-web-apps.md} | 11 +- .../host-on-cloudflare-pages.md} | 11 +- .../host-and-deploy/host-on-codeberg-pages.md | 82 ++ .../host-on-firebase.md} | 30 +- .../host-on-github-pages}/gh-pages-1.png | Bin .../host-on-github-pages}/gh-pages-2.png | Bin .../host-on-github-pages}/gh-pages-3.png | Bin .../host-on-github-pages}/gh-pages-4.png | Bin .../host-on-github-pages}/gh-pages-5.png | Bin .../host-on-github-pages}/index.md | 133 ++- .../host-on-gitlab-pages.md} | 32 +- .../host-on-keycdn}/index.md | 18 +- .../host-on-keycdn}/keycdn-pull-zone.png | Bin .../host-on-keycdn}/secret-api-key.png | Bin .../host-on-keycdn}/secret-zone-id.png | Bin .../host-on-netlify}/index.md | 112 +- .../host-on-netlify}/netlify-step-02.png | Bin .../host-on-netlify}/netlify-step-03.png | Bin .../host-on-netlify}/netlify-step-04.png | Bin .../host-on-netlify}/netlify-step-05.png | Bin .../host-on-netlify}/netlify-step-06.png | Bin .../host-on-netlify}/netlify-step-07.png | Bin .../host-on-netlify}/netlify-step-08.png | Bin .../host-on-netlify}/netlify-step-09.png | Bin .../host-on-netlify}/netlify-step-10.png | Bin .../host-on-netlify}/netlify-step-11.png | Bin .../host-on-netlify}/netlify-step-12.png | Bin .../host-on-netlify}/netlify-step-13.png | Bin .../host-on-render.md} | 21 +- .../host-on-sourcehut-pages.md | 94 ++ content/en/hosting-and-deployment/_index.md | 15 - .../en/hosting-and-deployment/hugo-deploy.md | 261 ----- content/en/hugo-modules/_index.md | 21 - content/en/hugo-modules/configuration.md | 187 ---- content/en/hugo-modules/introduction.md | 19 + content/en/hugo-modules/theme-components.md | 34 +- content/en/hugo-modules/use-modules.md | 39 +- content/en/hugo-pipes/_index.md | 5 - content/en/hugo-pipes/bundling.md | 7 +- content/en/hugo-pipes/fingerprint.md | 7 +- content/en/hugo-pipes/introduction.md | 11 +- content/en/hugo-pipes/js.md | 7 +- content/en/hugo-pipes/minification.md | 7 +- content/en/hugo-pipes/postcss.md | 7 +- content/en/hugo-pipes/postprocess.md | 7 +- content/en/hugo-pipes/resource-from-string.md | 7 +- .../en/hugo-pipes/resource-from-template.md | 7 +- .../en/hugo-pipes/transpile-sass-to-css.md | 7 +- content/en/installation/_common/_index.md | 13 - content/en/installation/_index.md | 10 +- content/en/installation/bsd.md | 17 +- content/en/installation/linux.md | 117 +- content/en/installation/macos.md | 19 +- content/en/installation/windows.md | 37 +- content/en/methods/_index.md | 9 - content/en/methods/duration/Abs.md | 10 +- content/en/methods/duration/Hours.md | 10 +- content/en/methods/duration/Microseconds.md | 10 +- content/en/methods/duration/Milliseconds.md | 10 +- content/en/methods/duration/Minutes.md | 10 +- content/en/methods/duration/Nanoseconds.md | 10 +- content/en/methods/duration/Round.md | 10 +- content/en/methods/duration/Seconds.md | 10 +- content/en/methods/duration/Truncate.md | 10 +- content/en/methods/duration/_index.md | 5 - content/en/methods/menu-entry/Children.md | 9 +- content/en/methods/menu-entry/HasChildren.md | 9 +- content/en/methods/menu-entry/Identifier.md | 19 +- content/en/methods/menu-entry/KeyName.md | 10 +- content/en/methods/menu-entry/Menu.md | 10 +- content/en/methods/menu-entry/Name.md | 10 +- content/en/methods/menu-entry/Page.md | 8 +- content/en/methods/menu-entry/PageRef.md | 45 +- content/en/methods/menu-entry/Params.md | 8 +- content/en/methods/menu-entry/Parent.md | 10 +- content/en/methods/menu-entry/Post.md | 13 +- content/en/methods/menu-entry/Pre.md | 13 +- content/en/methods/menu-entry/Title.md | 12 +- content/en/methods/menu-entry/URL.md | 8 +- content/en/methods/menu-entry/Weight.md | 14 +- .../en/methods/menu-entry/_common/_index.md | 13 - content/en/methods/menu-entry/_index.md | 5 - content/en/methods/menu/ByName.md | 8 +- content/en/methods/menu/ByWeight.md | 15 +- content/en/methods/menu/Limit.md | 8 +- content/en/methods/menu/Reverse.md | 8 +- content/en/methods/menu/_index.md | 5 - content/en/methods/page/Aliases.md | 8 +- content/en/methods/page/AllTranslations.md | 13 +- .../methods/page/AlternativeOutputFormats.md | 15 +- content/en/methods/page/Ancestors.md | 19 +- content/en/methods/page/BundleType.md | 8 +- content/en/methods/page/CodeOwners.md | 9 +- content/en/methods/page/Content.md | 14 +- .../en/methods/page/ContentWithoutSummary.md | 14 +- content/en/methods/page/CurrentSection.md | 20 +- content/en/methods/page/Data.md | 33 +- content/en/methods/page/Date.md | 21 +- content/en/methods/page/Description.md | 13 +- content/en/methods/page/Draft.md | 8 +- content/en/methods/page/Eq.md | 10 +- content/en/methods/page/ExpiryDate.md | 15 +- content/en/methods/page/File.md | 53 +- content/en/methods/page/FirstSection.md | 24 +- content/en/methods/page/Fragments.md | 59 +- content/en/methods/page/FuzzyWordCount.md | 12 +- content/en/methods/page/GetPage.md | 15 +- content/en/methods/page/GetTerms.md | 8 +- content/en/methods/page/GitInfo.md | 66 +- content/en/methods/page/HasMenuCurrent.md | 14 +- content/en/methods/page/HasShortcode.md | 20 +- content/en/methods/page/HeadingsFiltered.md | 12 +- content/en/methods/page/InSection.md | 32 +- content/en/methods/page/IsAncestor.md | 30 +- content/en/methods/page/IsDescendant.md | 29 +- content/en/methods/page/IsHome.md | 11 +- content/en/methods/page/IsMenuCurrent.md | 14 +- content/en/methods/page/IsNode.md | 11 +- content/en/methods/page/IsPage.md | 11 +- content/en/methods/page/IsSection.md | 11 +- content/en/methods/page/IsTranslated.md | 11 +- content/en/methods/page/Keywords.md | 10 +- content/en/methods/page/Kind.md | 9 +- content/en/methods/page/Language.md | 19 +- content/en/methods/page/Lastmod.md | 18 +- content/en/methods/page/Layout.md | 11 +- content/en/methods/page/Len.md | 9 +- content/en/methods/page/LinkTitle.md | 9 +- content/en/methods/page/Next.md | 15 +- content/en/methods/page/NextInSection.md | 15 +- content/en/methods/page/OutputFormats.md | 18 +- content/en/methods/page/Page.md | 29 +- content/en/methods/page/Pages.md | 21 +- content/en/methods/page/Paginate.md | 40 +- content/en/methods/page/Paginator.md | 43 +- content/en/methods/page/Param.md | 8 +- content/en/methods/page/Params.md | 24 +- content/en/methods/page/Parent.md | 24 +- content/en/methods/page/Path.md | 78 +- content/en/methods/page/Permalink.md | 9 +- content/en/methods/page/Plain.md | 14 +- content/en/methods/page/PlainWords.md | 22 +- content/en/methods/page/Prev.md | 15 +- content/en/methods/page/PrevInSection.md | 15 +- content/en/methods/page/PublishDate.md | 13 +- content/en/methods/page/RawContent.md | 23 +- content/en/methods/page/ReadingTime.md | 10 +- content/en/methods/page/Ref.md | 33 +- content/en/methods/page/RegularPages.md | 21 +- .../en/methods/page/RegularPagesRecursive.md | 17 +- content/en/methods/page/RelPermalink.md | 9 +- content/en/methods/page/RelRef.md | 33 +- content/en/methods/page/Render.md | 10 +- content/en/methods/page/RenderShortcodes.md | 30 +- content/en/methods/page/RenderString.md | 10 +- content/en/methods/page/Resources.md | 33 +- content/en/methods/page/Scratch.md | 12 +- content/en/methods/page/Section.md | 15 +- content/en/methods/page/Sections.md | 17 +- content/en/methods/page/Site.md | 9 +- content/en/methods/page/Sitemap.md | 30 +- content/en/methods/page/Sites.md | 9 +- content/en/methods/page/Slug.md | 8 +- content/en/methods/page/Store.md | 13 +- content/en/methods/page/Summary.md | 24 +- content/en/methods/page/TableOfContents.md | 9 +- content/en/methods/page/Title.md | 15 +- content/en/methods/page/TranslationKey.md | 11 +- content/en/methods/page/Translations.md | 13 +- content/en/methods/page/Truncated.md | 14 +- content/en/methods/page/Type.md | 12 +- content/en/methods/page/Weight.md | 8 +- content/en/methods/page/WordCount.md | 10 +- content/en/methods/page/_common/_index.md | 13 - .../page/_common/output-format-methods.md | 27 - content/en/methods/page/_index.md | 5 - content/en/methods/pager/First.md | 14 +- content/en/methods/pager/HasNext.md | 14 +- content/en/methods/pager/HasPrev.md | 14 +- content/en/methods/pager/Last.md | 14 +- content/en/methods/pager/Next.md | 14 +- content/en/methods/pager/NumberOfElements.md | 10 +- content/en/methods/pager/PageGroups.md | 9 +- content/en/methods/pager/PageNumber.md | 10 +- content/en/methods/pager/PageSize.md | 12 +- content/en/methods/pager/PagerSize.md | 9 +- content/en/methods/pager/Pagers.md | 9 +- content/en/methods/pager/Pages.md | 9 +- content/en/methods/pager/Prev.md | 14 +- .../en/methods/pager/TotalNumberOfElements.md | 10 +- content/en/methods/pager/TotalPages.md | 10 +- content/en/methods/pager/URL.md | 9 +- content/en/methods/pager/_index.md | 10 +- content/en/methods/pages/ByDate.md | 13 +- content/en/methods/pages/ByExpiryDate.md | 13 +- content/en/methods/pages/ByLanguage.md | 8 +- content/en/methods/pages/ByLastmod.md | 13 +- content/en/methods/pages/ByLength.md | 8 +- content/en/methods/pages/ByLinkTitle.md | 10 +- content/en/methods/pages/ByParam.md | 10 +- content/en/methods/pages/ByPublishDate.md | 13 +- content/en/methods/pages/ByTitle.md | 10 +- content/en/methods/pages/ByWeight.md | 8 +- content/en/methods/pages/GroupBy.md | 10 +- content/en/methods/pages/GroupByDate.md | 18 +- content/en/methods/pages/GroupByExpiryDate.md | 18 +- content/en/methods/pages/GroupByLastmod.md | 18 +- content/en/methods/pages/GroupByParam.md | 10 +- content/en/methods/pages/GroupByParamDate.md | 16 +- .../en/methods/pages/GroupByPublishDate.md | 18 +- content/en/methods/pages/Len.md | 8 +- content/en/methods/pages/Limit.md | 8 +- content/en/methods/pages/Next.md | 15 +- content/en/methods/pages/Prev.md | 15 +- content/en/methods/pages/Related.md | 26 +- content/en/methods/pages/Reverse.md | 8 +- content/en/methods/pages/_common/_index.md | 13 - content/en/methods/pages/_index.md | 5 - content/en/methods/resource/Colors.md | 47 +- content/en/methods/resource/Content.md | 17 +- content/en/methods/resource/Crop.md | 20 +- content/en/methods/resource/Data.md | 29 +- content/en/methods/resource/Err.md | 21 +- content/en/methods/resource/Exif.md | 36 +- content/en/methods/resource/Fill.md | 22 +- content/en/methods/resource/Filter.md | 16 +- content/en/methods/resource/Fit.md | 22 +- content/en/methods/resource/Height.md | 13 +- content/en/methods/resource/Key.md | 45 - content/en/methods/resource/MediaType.md | 40 +- content/en/methods/resource/Name.md | 10 +- content/en/methods/resource/Params.md | 8 +- content/en/methods/resource/Permalink.md | 16 +- content/en/methods/resource/Process.md | 20 +- content/en/methods/resource/Publish.md | 14 +- content/en/methods/resource/RelPermalink.md | 14 +- content/en/methods/resource/Resize.md | 19 +- content/en/methods/resource/ResourceType.md | 16 +- content/en/methods/resource/Title.md | 10 +- content/en/methods/resource/Width.md | 13 +- content/en/methods/resource/_common/_index.md | 13 - .../_common/global-page-remote-resources.md | 7 - content/en/methods/resource/_index.md | 5 - content/en/methods/shortcode/Get.md | 37 +- content/en/methods/shortcode/Inner.md | 64 +- content/en/methods/shortcode/InnerDeindent.md | 23 +- content/en/methods/shortcode/IsNamedParams.md | 17 +- content/en/methods/shortcode/Name.md | 14 +- content/en/methods/shortcode/Ordinal.md | 26 +- content/en/methods/shortcode/Page.md | 12 +- content/en/methods/shortcode/Params.md | 25 +- content/en/methods/shortcode/Parent.md | 22 +- content/en/methods/shortcode/Position.md | 21 +- content/en/methods/shortcode/Ref.md | 33 +- content/en/methods/shortcode/RelRef.md | 33 +- content/en/methods/shortcode/Scratch.md | 12 +- content/en/methods/shortcode/Site.md | 9 +- content/en/methods/shortcode/Store.md | 24 +- content/en/methods/shortcode/_index.md | 5 - content/en/methods/site/AllPages.md | 13 +- content/en/methods/site/BaseURL.md | 25 +- content/en/methods/site/BuildDrafts.md | 8 +- content/en/methods/site/Config.md | 17 +- content/en/methods/site/Copyright.md | 10 +- content/en/methods/site/Data.md | 31 +- content/en/methods/site/DisqusShortname.md | 12 +- content/en/methods/site/GetPage.md | 10 +- content/en/methods/site/GoogleAnalytics.md | 12 +- content/en/methods/site/Home.md | 8 +- content/en/methods/site/IsDevelopment.md | 12 +- content/en/methods/site/IsMultiLingual.md | 12 +- content/en/methods/site/IsServer.md | 12 +- content/en/methods/site/Language.md | 22 +- content/en/methods/site/LanguagePrefix.md | 10 +- content/en/methods/site/Languages.md | 9 +- content/en/methods/site/LastChange.md | 12 +- content/en/methods/site/Lastmod.md | 8 +- content/en/methods/site/MainSections.md | 15 +- content/en/methods/site/Menus.md | 21 +- content/en/methods/site/Pages.md | 13 +- content/en/methods/site/Param.md | 8 +- content/en/methods/site/Params.md | 11 +- content/en/methods/site/RegularPages.md | 22 +- content/en/methods/site/Sections.md | 15 +- content/en/methods/site/Sites.md | 8 +- content/en/methods/site/Store.md | 28 +- content/en/methods/site/Taxonomies.md | 29 +- content/en/methods/site/Title.md | 8 +- content/en/methods/site/_index.md | 5 - content/en/methods/taxonomy/Alphabetical.md | 16 +- content/en/methods/taxonomy/ByCount.md | 16 +- content/en/methods/taxonomy/Count.md | 11 +- content/en/methods/taxonomy/Get.md | 11 +- content/en/methods/taxonomy/Page.md | 8 +- content/en/methods/taxonomy/_common/_index.md | 13 - content/en/methods/taxonomy/_index.md | 6 - content/en/methods/time/Add.md | 11 +- content/en/methods/time/AddDate.md | 18 +- content/en/methods/time/After.md | 11 +- content/en/methods/time/Before.md | 11 +- content/en/methods/time/Day.md | 14 +- content/en/methods/time/Equal.md | 11 +- content/en/methods/time/Format.md | 31 +- content/en/methods/time/Hour.md | 14 +- content/en/methods/time/IsDST.md | 9 +- content/en/methods/time/IsZero.md | 9 +- content/en/methods/time/Local.md | 10 +- content/en/methods/time/Minute.md | 14 +- content/en/methods/time/Month.md | 14 +- content/en/methods/time/Nanosecond.md | 9 +- content/en/methods/time/Round.md | 11 +- content/en/methods/time/Second.md | 14 +- content/en/methods/time/Sub.md | 9 +- content/en/methods/time/Truncate.md | 11 +- content/en/methods/time/UTC.md | 10 +- content/en/methods/time/Unix.md | 14 +- content/en/methods/time/UnixMicro.md | 14 +- content/en/methods/time/UnixMilli.md | 14 +- content/en/methods/time/UnixNano.md | 14 +- content/en/methods/time/Weekday.md | 11 +- content/en/methods/time/Year.md | 14 +- content/en/methods/time/YearDay.md | 8 +- content/en/methods/time/_index.md | 6 - content/en/myshowcase/featured.png | Bin 41270 -> 0 bytes content/en/news/_content.gotmpl | 30 + content/en/news/_index.md | 2 +- content/en/quick-reference/_index.md | 10 +- content/en/quick-reference/emojis.md | 10 +- content/en/quick-reference/functions.md | 8 +- content/en/quick-reference/glossary/_index.md | 16 +- content/en/quick-reference/glossary/cicd.md | 7 + content/en/quick-reference/glossary/cli.md | 2 +- .../glossary/default-sort-order.md | 7 +- .../quick-reference/glossary/environment.md | 6 +- content/en/quick-reference/glossary/glob.md | 2 +- .../en/quick-reference/glossary/interval.md | 6 +- .../quick-reference/glossary/logical-path.md | 4 +- .../glossary/markdown-attribute.md | 2 +- .../en/quick-reference/glossary/media-type.md | 6 + content/en/quick-reference/glossary/method.md | 2 +- .../glossary/ordered-taxonomy.md | 5 +- .../quick-reference/glossary/output-format.md | 4 +- .../en/quick-reference/glossary/pipeline.md | 2 +- .../glossary/primary-output-format.md | 10 + .../glossary/regular-expression.md | 8 + .../quick-reference/glossary/resource-type.md | 5 +- .../en/quick-reference/glossary/resource.md | 2 +- .../quick-reference/glossary/scratch-pad.md | 5 +- .../en/quick-reference/glossary/shortcode.md | 2 +- .../glossary/template-action.md | 2 +- content/en/quick-reference/methods.md | 8 +- .../en/quick-reference/page-collections.md | 36 +- .../syntax-highlighting-styles.md | 35 + content/en/render-hooks/_common/_index.md | 13 - content/en/render-hooks/_index.md | 9 - content/en/render-hooks/blockquotes.md | 115 +- content/en/render-hooks/code-blocks.md | 101 +- content/en/render-hooks/headings.md | 73 +- content/en/render-hooks/images.md | 104 +- content/en/render-hooks/introduction.md | 24 +- content/en/render-hooks/links.md | 74 +- content/en/render-hooks/passthrough.md | 93 +- content/en/render-hooks/tables.md | 76 +- content/en/shortcodes/_index.md | 9 - content/en/shortcodes/comment.md | 39 - content/en/shortcodes/details.md | 22 +- content/en/shortcodes/figure.md | 22 +- content/en/shortcodes/gist.md | 18 +- content/en/shortcodes/highlight.md | 58 +- content/en/shortcodes/instagram.md | 20 +- content/en/shortcodes/param.md | 23 +- content/en/shortcodes/qr.md | 36 +- content/en/shortcodes/ref.md | 73 +- content/en/shortcodes/relref.md | 73 +- content/en/shortcodes/vimeo.md | 21 +- content/en/shortcodes/x.md | 23 +- content/en/shortcodes/youtube.md | 42 +- content/en/showcase/1password-support/bio.md | 1 - .../en/showcase/1password-support/index.md | 16 +- content/en/showcase/_index.md | 5 +- .../{myshowcase => showcase/_template}/bio.md | 5 +- .../en/showcase/_template}/featured.png | Bin .../_template}/index.md | 12 +- content/en/showcase/alora-labs/index.md | 2 +- content/en/showcase/ampio-help/bio.md | 5 +- content/en/showcase/ampio-help/index.md | 7 +- content/en/showcase/bypasscensorship/bio.md | 4 +- content/en/showcase/bypasscensorship/index.md | 3 +- content/en/showcase/digitalgov/bio.md | 1 - content/en/showcase/digitalgov/index.md | 8 +- content/en/showcase/fireship/bio.md | 3 +- content/en/showcase/fireship/index.md | 2 +- content/en/showcase/forestry/bio.md | 1 - content/en/showcase/forestry/index.md | 26 +- content/en/showcase/godot-tutorials/index.md | 7 - content/en/showcase/hapticmedia/index.md | 2 +- content/en/showcase/hartwell-insurance/bio.md | 1 - .../en/showcase/hartwell-insurance/index.md | 34 +- content/en/showcase/keycdn/index.md | 22 +- content/en/showcase/letsencrypt/bio.md | 2 - content/en/showcase/letsencrypt/index.md | 8 +- content/en/showcase/linode/bio.md | 1 - content/en/showcase/linode/index.md | 4 +- content/en/showcase/overmindstudios/bio.md | 3 +- content/en/showcase/overmindstudios/index.md | 1 + content/en/showcase/pharmaseal/index.md | 10 - .../index.md | 16 +- content/en/showcase/template/bio.md | 7 - .../showcase/template/featured-template.png | Bin 41270 -> 0 bytes content/en/showcase/template/index.md | 18 - content/en/showcase/tomango/bio.md | 1 - content/en/showcase/tomango/index.md | 9 +- content/en/templates/404.md | 12 +- content/en/templates/_common/_index.md | 13 - .../en/templates/_common/filter-sort-group.md | 9 - content/en/templates/_index.md | 8 - content/en/templates/base.md | 50 +- content/en/templates/content-view.md | 31 +- content/en/templates/embedded.md | 90 +- content/en/templates/home.md | 30 +- content/en/templates/introduction.md | 197 ++-- content/en/templates/lookup-order.md | 22 +- content/en/templates/menu.md | 32 +- content/en/templates/output-formats.md | 241 ----- content/en/templates/pagination.md | 87 +- content/en/templates/partial.md | 40 +- content/en/templates/robots.md | 33 +- content/en/templates/rss.md | 17 +- content/en/templates/section.md | 13 +- content/en/templates/shortcode.md | 209 ++-- content/en/templates/single.md | 17 +- content/en/templates/sitemap.md | 32 +- content/en/templates/taxonomy.md | 29 +- content/en/templates/term.md | 17 +- .../en/templates/{types/index.md => types.md} | 93 +- content/en/templates/types/site-hierarchy.svg | 1 - content/en/tools/_index.md | 13 - content/en/tools/editors.md | 12 +- content/en/tools/front-ends.md | 11 +- content/en/tools/migrations.md | 15 +- content/en/tools/other.md | 10 +- content/en/tools/search.md | 15 +- content/en/troubleshooting/_index.md | 8 - content/en/troubleshooting/audit/index.md | 11 +- content/en/troubleshooting/deprecation.md | 7 +- content/en/troubleshooting/faq.md | 153 ++- content/en/troubleshooting/inspection.md | 7 +- content/en/troubleshooting/logging.md | 39 +- content/en/troubleshooting/performance.md | 30 +- data/docs.yaml | 84 +- data/keywords.yaml | 12 + data/page_filters.yaml | 2 +- hugo.toml | 241 +++-- layouts/404.html | 2 +- .../_default/_markup/render-blockquote.html | 33 + .../_default/_markup/render-codeblock.html | 98 ++ layouts/_default/_markup/render-heading.html | 10 - layouts/_default/_markup/render-link.html | 49 +- .../_default/_markup/render-passthrough.html | 9 + layouts/_default/_markup/render-table.html | 31 + layouts/_default/baseof.html | 25 +- layouts/_default/list.html | 30 +- layouts/_default/list.rss.xml | 33 + layouts/_default/single.html | 19 +- layouts/index.html | 6 +- layouts/index.redir | 4 +- layouts/index.rss.xml | 68 -- layouts/partials/docs/functions-aliases.html | 2 +- .../partials/docs/functions-return-type.html | 2 +- .../partials/docs/functions-signatures.html | 2 +- .../helpers/debug/list-item-metadata.html | 23 + .../helpers/funcs/get-remote-data.html | 3 +- layouts/partials/helpers/linkcss.html | 4 +- layouts/partials/helpers/picture.html | 10 +- .../helpers/validation/validate-keywords.html | 22 + layouts/partials/layouts/blocks/alert.html | 18 +- layouts/partials/layouts/breadcrumbs.html | 2 +- layouts/partials/layouts/date.html | 5 + layouts/partials/layouts/footer.html | 7 +- layouts/partials/layouts/head/head.html | 3 - layouts/partials/layouts/header/header.html | 2 +- layouts/partials/layouts/header/qr.html | 6 +- layouts/partials/layouts/home/opensource.html | 19 +- layouts/partials/layouts/home/sponsors.html | 5 +- layouts/partials/layouts/hooks/body-end.html | 4 +- .../layouts/hooks/body-main-start.html | 8 + layouts/partials/layouts/icons.html | 47 +- layouts/partials/layouts/in-this-section.html | 8 +- layouts/partials/layouts/page-edit.html | 16 +- layouts/partials/layouts/related.html | 23 +- .../partials/layouts/search/algolialogo.html | 45 + layouts/partials/layouts/search/button.html | 23 +- layouts/partials/layouts/search/results.html | 14 +- layouts/partials/layouts/templates.html | 7 + layouts/partials/layouts/toc.html | 50 +- layouts/partials/news/get-news-items.html | 45 - layouts/partials/opengraph/opengraph.html | 32 +- layouts/shortcodes/chroma-lexers.html | 35 +- layouts/shortcodes/code-toggle.html | 67 +- layouts/shortcodes/code.html | 38 - layouts/shortcodes/datatable-filtered.html | 64 +- layouts/shortcodes/datatable.html | 56 +- layouts/shortcodes/deprecated-in.html | 42 +- layouts/shortcodes/eturl.html | 40 +- layouts/shortcodes/glossary-term.html | 6 +- layouts/shortcodes/glossary.html | 64 +- layouts/shortcodes/gomodules-info.html | 12 - layouts/shortcodes/hl.html | 7 +- layouts/shortcodes/img.html | 164 +-- layouts/shortcodes/imgproc.html | 46 +- layouts/shortcodes/include.html | 9 +- layouts/shortcodes/list-pages-in-section.html | 111 +- layouts/shortcodes/module-mounts-note.html | 3 +- layouts/shortcodes/new-in.html | 46 +- layouts/shortcodes/note.html | 7 - layouts/shortcodes/per-lang-config-keys.html | 71 ++ layouts/shortcodes/quick-reference.html | 35 +- layouts/shortcodes/readfile.html | 1 - .../shortcodes/root-configuration-keys.html | 45 + .../syntax-highlighting-styles.html | 70 ++ netlify.toml | 2 +- package.json | 17 +- static/browserconfig.xml | 10 - 987 files changed, 12449 insertions(+), 14072 deletions(-) create mode 100644 .prettierignore create mode 100644 .prettierrc create mode 100644 archetypes/default.md create mode 100644 archetypes/news.md delete mode 100644 archetypes/news/index.md delete mode 100644 archetypes/showcase/bio.md delete mode 100644 archetypes/showcase/index.md create mode 100644 assets/js/helpers/lrucache.js create mode 100644 content/en/_common/content-format-table.md create mode 100644 content/en/_common/filter-sort-group.md rename content/en/{functions/fmt/_common/fmt-layout.md => _common/functions/fmt/format-string.md} (100%) rename content/en/{functions/_common => _common/functions}/go-html-template-package.md (100%) rename content/en/{functions/go-template/_common => _common/functions/go-template}/text-template.md (100%) rename content/en/{functions/images/_common => _common/functions/images}/apply-image-filter.md (100%) create mode 100644 content/en/_common/functions/js/options.md create mode 100644 content/en/_common/functions/locales.md rename content/en/{functions/_common => _common/functions}/regular-expressions.md (100%) rename content/en/{functions/go-template/_common => _common/functions}/truthy-falsy.md (100%) rename content/en/{functions/urls/_common => _common/functions/urls}/anchorize-vs-urlize.md (92%) rename content/en/{functions => }/_common/glob-patterns.md (100%) create mode 100644 content/en/_common/gomodules-info.md rename content/en/{installation/_common => _common/installation}/01-editions.md (94%) rename content/en/{installation/_common => _common/installation}/02-prerequisites.md (100%) rename content/en/{installation/_common => _common/installation}/03-prebuilt-binaries.md (100%) rename content/en/{installation/_common => _common/installation}/04-build-from-source.md (96%) rename content/en/{installation/_common => _common/installation}/homebrew.md (100%) rename content/en/{methods/menu-entry/_common/pre-post.md => _common/menu-entries/pre-and-post.md} (100%) create mode 100644 content/en/_common/menu-entry-properties.md rename content/en/{methods/page/_common => _common/methods/page}/next-and-prev.md (89%) rename content/en/{methods/page/_common => _common/methods/page}/nextinsection-and-previnsection.md (91%) create mode 100644 content/en/_common/methods/page/output-format-methods.md rename content/en/{methods/pages/_common => _common/methods/pages}/group-sort-order.md (100%) rename content/en/{methods/pages/_common => _common/methods/pages}/next-and-prev.md (88%) create mode 100644 content/en/_common/methods/resource/global-page-remote-resources.md rename content/en/{methods/resource/_common => _common/methods/resource}/processing-spec.md (100%) rename content/en/{methods/taxonomy/_common => _common/methods/taxonomy}/get-a-taxonomy-object.md (96%) rename content/en/{methods/taxonomy/_common => _common/methods/taxonomy}/ordered-taxonomy-element-methods.md (100%) rename content/en/{functions/time => }/_common/parsable-date-time-strings.md (100%) create mode 100644 content/en/_common/permalink-tokens.md create mode 100644 content/en/_common/ref-and-relref-error-handling.md create mode 100644 content/en/_common/ref-and-relref-options.md rename content/en/{render-hooks/_common => _common/render-hooks}/pageinner.md (70%) rename content/en/{functions/_common/highlighting-options.md => _common/syntax-highlighting-options.md} (68%) rename content/en/{functions => }/_common/time-layout-string.md (100%) create mode 100644 content/en/configuration/_index.md create mode 100644 content/en/configuration/all.md create mode 100644 content/en/configuration/build.md create mode 100644 content/en/configuration/caches.md create mode 100644 content/en/configuration/cascade.md create mode 100644 content/en/configuration/content-types.md create mode 100644 content/en/configuration/deployment.md create mode 100644 content/en/configuration/front-matter.md create mode 100644 content/en/configuration/http-cache.md create mode 100644 content/en/configuration/imaging.md create mode 100644 content/en/configuration/introduction.md create mode 100644 content/en/configuration/languages.md create mode 100644 content/en/configuration/markup.md create mode 100644 content/en/configuration/media-types.md create mode 100644 content/en/configuration/menus.md create mode 100644 content/en/configuration/minify.md create mode 100644 content/en/configuration/module.md create mode 100644 content/en/configuration/output-formats.md create mode 100644 content/en/configuration/outputs.md create mode 100644 content/en/configuration/page.md create mode 100644 content/en/configuration/pagination.md create mode 100644 content/en/configuration/params.md create mode 100644 content/en/configuration/permalinks.md rename content/en/{about => configuration}/privacy.md (79%) create mode 100644 content/en/configuration/related-content.md create mode 100644 content/en/configuration/security.md create mode 100644 content/en/configuration/segments.md create mode 100644 content/en/configuration/server.md create mode 100644 content/en/configuration/services.md create mode 100644 content/en/configuration/sitemap.md create mode 100644 content/en/configuration/taxonomies.md create mode 100644 content/en/configuration/ugly-urls.md delete mode 100644 content/en/content-management/_common/_index.md delete mode 100644 content/en/content-management/_common/page-kinds.md delete mode 100644 content/en/content-management/cross-references.md delete mode 100644 content/en/content-management/organization/1-featured-content-bundles.png create mode 100644 content/en/content-management/related-content.md delete mode 100644 content/en/content-management/related.md delete mode 100644 content/en/functions/_common/_index.md delete mode 100644 content/en/functions/_common/locales.md delete mode 100644 content/en/functions/fmt/_common/_index.md delete mode 100644 content/en/functions/go-template/_common/_index.md delete mode 100644 content/en/functions/images/_common/_index.md delete mode 100644 content/en/functions/js/_common/_index.md delete mode 100644 content/en/functions/js/_common/options.md delete mode 100644 content/en/functions/resources/_common/_index.md delete mode 100644 content/en/functions/resources/_common/postcss-windows-warning.md delete mode 100644 content/en/functions/time/_common/_index.md create mode 100644 content/en/functions/transform/PortableText.md delete mode 100644 content/en/functions/urls/_common/_index.md delete mode 100644 content/en/getting-started/configuration-build.md delete mode 100644 content/en/getting-started/configuration-markup.md delete mode 100644 content/en/getting-started/configuration.md create mode 100644 content/en/host-and-deploy/_index.md create mode 100644 content/en/host-and-deploy/deploy-with-hugo-deploy.md rename content/en/{hosting-and-deployment/deployment-with-rclone.md => host-and-deploy/deploy-with-rclone.md} (64%) rename content/en/{hosting-and-deployment/deployment-with-rsync.md => host-and-deploy/deploy-with-rsync.md} (87%) rename content/en/{hosting-and-deployment/hosting-on-21yunbox.md => host-and-deploy/host-on-21yunbox.md} (51%) rename content/en/{hosting-and-deployment/hosting-on-aws-amplify => host-and-deploy/host-on-aws-amplify}/amplify-step-05.png (100%) rename content/en/{hosting-and-deployment/hosting-on-aws-amplify => host-and-deploy/host-on-aws-amplify}/amplify-step-06.png (100%) rename content/en/{hosting-and-deployment/hosting-on-aws-amplify => host-and-deploy/host-on-aws-amplify}/amplify-step-07.png (100%) rename content/en/{hosting-and-deployment/hosting-on-aws-amplify => host-and-deploy/host-on-aws-amplify}/amplify-step-08.png (100%) rename content/en/{hosting-and-deployment/hosting-on-aws-amplify => host-and-deploy/host-on-aws-amplify}/amplify-step-09.png (100%) rename content/en/{hosting-and-deployment/hosting-on-aws-amplify => host-and-deploy/host-on-aws-amplify}/amplify-step-11.png (100%) rename content/en/{hosting-and-deployment/hosting-on-aws-amplify => host-and-deploy/host-on-aws-amplify}/index.md (68%) rename content/en/{hosting-and-deployment/hosting-on-azure-static-web-apps.md => host-and-deploy/host-on-azure-static-web-apps.md} (73%) rename content/en/{hosting-and-deployment/hosting-on-cloudflare-pages.md => host-and-deploy/host-on-cloudflare-pages.md} (60%) create mode 100644 content/en/host-and-deploy/host-on-codeberg-pages.md rename content/en/{hosting-and-deployment/hosting-on-firebase.md => host-and-deploy/host-on-firebase.md} (75%) rename content/en/{hosting-and-deployment/hosting-on-github => host-and-deploy/host-on-github-pages}/gh-pages-1.png (100%) rename content/en/{hosting-and-deployment/hosting-on-github => host-and-deploy/host-on-github-pages}/gh-pages-2.png (100%) rename content/en/{hosting-and-deployment/hosting-on-github => host-and-deploy/host-on-github-pages}/gh-pages-3.png (100%) rename content/en/{hosting-and-deployment/hosting-on-github => host-and-deploy/host-on-github-pages}/gh-pages-4.png (100%) rename content/en/{hosting-and-deployment/hosting-on-github => host-and-deploy/host-on-github-pages}/gh-pages-5.png (100%) rename content/en/{hosting-and-deployment/hosting-on-github => host-and-deploy/host-on-github-pages}/index.md (62%) rename content/en/{hosting-and-deployment/hosting-on-gitlab.md => host-and-deploy/host-on-gitlab-pages.md} (72%) rename content/en/{hosting-and-deployment/hosting-on-keycdn => host-and-deploy/host-on-keycdn}/index.md (70%) rename content/en/{hosting-and-deployment/hosting-on-keycdn => host-and-deploy/host-on-keycdn}/keycdn-pull-zone.png (100%) rename content/en/{hosting-and-deployment/hosting-on-keycdn => host-and-deploy/host-on-keycdn}/secret-api-key.png (100%) rename content/en/{hosting-and-deployment/hosting-on-keycdn => host-and-deploy/host-on-keycdn}/secret-zone-id.png (100%) rename content/en/{hosting-and-deployment/hosting-on-netlify => host-and-deploy/host-on-netlify}/index.md (51%) rename content/en/{hosting-and-deployment/hosting-on-netlify => host-and-deploy/host-on-netlify}/netlify-step-02.png (100%) rename content/en/{hosting-and-deployment/hosting-on-netlify => host-and-deploy/host-on-netlify}/netlify-step-03.png (100%) rename content/en/{hosting-and-deployment/hosting-on-netlify => host-and-deploy/host-on-netlify}/netlify-step-04.png (100%) rename content/en/{hosting-and-deployment/hosting-on-netlify => host-and-deploy/host-on-netlify}/netlify-step-05.png (100%) rename content/en/{hosting-and-deployment/hosting-on-netlify => host-and-deploy/host-on-netlify}/netlify-step-06.png (100%) rename content/en/{hosting-and-deployment/hosting-on-netlify => host-and-deploy/host-on-netlify}/netlify-step-07.png (100%) rename content/en/{hosting-and-deployment/hosting-on-netlify => host-and-deploy/host-on-netlify}/netlify-step-08.png (100%) rename content/en/{hosting-and-deployment/hosting-on-netlify => host-and-deploy/host-on-netlify}/netlify-step-09.png (100%) rename content/en/{hosting-and-deployment/hosting-on-netlify => host-and-deploy/host-on-netlify}/netlify-step-10.png (100%) rename content/en/{hosting-and-deployment/hosting-on-netlify => host-and-deploy/host-on-netlify}/netlify-step-11.png (100%) rename content/en/{hosting-and-deployment/hosting-on-netlify => host-and-deploy/host-on-netlify}/netlify-step-12.png (100%) rename content/en/{hosting-and-deployment/hosting-on-netlify => host-and-deploy/host-on-netlify}/netlify-step-13.png (100%) rename content/en/{hosting-and-deployment/hosting-on-render.md => host-and-deploy/host-on-render.md} (85%) create mode 100644 content/en/host-and-deploy/host-on-sourcehut-pages.md delete mode 100644 content/en/hosting-and-deployment/_index.md delete mode 100644 content/en/hosting-and-deployment/hugo-deploy.md delete mode 100644 content/en/hugo-modules/configuration.md create mode 100644 content/en/hugo-modules/introduction.md delete mode 100644 content/en/installation/_common/_index.md delete mode 100644 content/en/methods/menu-entry/_common/_index.md delete mode 100644 content/en/methods/page/_common/_index.md delete mode 100644 content/en/methods/page/_common/output-format-methods.md delete mode 100644 content/en/methods/pages/_common/_index.md delete mode 100644 content/en/methods/resource/Key.md delete mode 100644 content/en/methods/resource/_common/_index.md delete mode 100644 content/en/methods/resource/_common/global-page-remote-resources.md delete mode 100644 content/en/methods/taxonomy/_common/_index.md delete mode 100644 content/en/myshowcase/featured.png create mode 100644 content/en/news/_content.gotmpl create mode 100644 content/en/quick-reference/glossary/cicd.md create mode 100644 content/en/quick-reference/glossary/media-type.md create mode 100644 content/en/quick-reference/glossary/primary-output-format.md create mode 100644 content/en/quick-reference/glossary/regular-expression.md create mode 100644 content/en/quick-reference/syntax-highlighting-styles.md delete mode 100644 content/en/render-hooks/_common/_index.md delete mode 100755 content/en/shortcodes/comment.md rename content/en/{myshowcase => showcase/_template}/bio.md (51%) rename {archetypes/showcase => content/en/showcase/_template}/featured.png (100%) rename content/en/{myshowcase => showcase/_template}/index.md (90%) delete mode 100644 content/en/showcase/template/bio.md delete mode 100644 content/en/showcase/template/featured-template.png delete mode 100644 content/en/showcase/template/index.md delete mode 100644 content/en/templates/_common/_index.md delete mode 100644 content/en/templates/_common/filter-sort-group.md delete mode 100644 content/en/templates/output-formats.md rename content/en/templates/{types/index.md => types.md} (77%) delete mode 100644 content/en/templates/types/site-hierarchy.svg create mode 100644 data/keywords.yaml create mode 100644 layouts/_default/_markup/render-blockquote.html create mode 100644 layouts/_default/_markup/render-codeblock.html delete mode 100644 layouts/_default/_markup/render-heading.html create mode 100644 layouts/_default/_markup/render-passthrough.html create mode 100644 layouts/_default/_markup/render-table.html create mode 100644 layouts/_default/list.rss.xml delete mode 100644 layouts/index.rss.xml create mode 100644 layouts/partials/helpers/debug/list-item-metadata.html create mode 100644 layouts/partials/helpers/validation/validate-keywords.html create mode 100644 layouts/partials/layouts/date.html create mode 100644 layouts/partials/layouts/hooks/body-main-start.html create mode 100644 layouts/partials/layouts/search/algolialogo.html create mode 100644 layouts/partials/layouts/templates.html delete mode 100644 layouts/partials/news/get-news-items.html delete mode 100644 layouts/shortcodes/code.html delete mode 100644 layouts/shortcodes/gomodules-info.html delete mode 100644 layouts/shortcodes/note.html create mode 100644 layouts/shortcodes/per-lang-config-keys.html delete mode 100644 layouts/shortcodes/readfile.html create mode 100644 layouts/shortcodes/root-configuration-keys.html create mode 100644 layouts/shortcodes/syntax-highlighting-styles.html delete mode 100644 static/browserconfig.xml diff --git a/.cspell.json b/.cspell.json index 8d51085ab..bf61489da 100644 --- a/.cspell.json +++ b/.cspell.json @@ -60,6 +60,7 @@ "redirections", "subexpression", "suppressible", + "synchronisation", "templating", "transpile", "unmarshal", @@ -161,7 +162,7 @@ "# ----------------------------------------------------------------------", "achristie", "ccpa", - "crpa", + "cpra", "ddmaurier", "dring", "fleqn", @@ -171,6 +172,8 @@ "jsmith", "leqno", "milli", + "monokai", + "mysanityprojectid", "rgba", "rsmith", "tdewolff", diff --git a/.gitignore b/.gitignore index debc86d46..5208c5c3a 100644 --- a/.gitignore +++ b/.gitignore @@ -4,10 +4,9 @@ /.vscode /dist /public +/resources hugo_stats.json node_modules/ nohup.out package-lock.json -public/ -resources/ -trace.out \ No newline at end of file +trace.out diff --git a/.markdownlint.yaml b/.markdownlint.yaml index ee0a28909..dbb5b2ee8 100644 --- a/.markdownlint.yaml +++ b/.markdownlint.yaml @@ -22,5 +22,6 @@ MD041: false MD046: false MD049: false MD050: false +MD051: false MD053: false MD055: false diff --git a/.prettierignore b/.prettierignore new file mode 100644 index 000000000..f24bbcef0 --- /dev/null +++ b/.prettierignore @@ -0,0 +1,18 @@ +# Ignore all SVG icons. +**/icons.html + +# These are whitespace sensitive. +layouts/_default/_markup/render-code* +layouts/_default/_markup/render-table* +layouts/shortcodes/glossary-term.html +layouts/shortcodes/glossary.html +layouts/shortcodes/highlighting-styles.html +layouts/shortcodes/list-pages-in-section.html +layouts/shortcodes/quick-reference.html + +# No root node. +layouts/partials/layouts/head/head.html + +# Auto generated. +assets/css/components/chroma*.css +assets/jsconfig.json diff --git a/.prettierrc b/.prettierrc new file mode 100644 index 000000000..395ae39af --- /dev/null +++ b/.prettierrc @@ -0,0 +1,24 @@ +{ + "plugins": [ + "prettier-plugin-go-template", + "@awmottaz/prettier-plugin-void-html" + ], + "overrides": [ + { + "files": ["*.html"], + "options": { + "parser": "go-template", + "goTemplateBracketSpacing": true, + "bracketSameLine": true + } + }, + { + "files": ["*.js", "*.ts"], + "options": { + "useTabs": true, + "printWidth": 120, + "singleQuote": true + } + } + ] +} diff --git a/LICENSE.md b/LICENSE.md index 979711275..d4facbf8a 100644 --- a/LICENSE.md +++ b/LICENSE.md @@ -1,3 +1,3 @@ See [content/LICENSE.md](content/LICENSE.md) for the license of the content of this repository. -The theme (layouts, CSS, JavaScript etc.) of this repository has no open source license. It is custom made for the Hugo sites and is not meant for reuse. \ No newline at end of file +The theme (layouts, CSS, JavaScript etc.) of this repository has no open source license. It is custom made for the Hugo sites and is not meant for reuse. diff --git a/README.md b/README.md index 64ba31a48..58d0e748c 100644 --- a/README.md +++ b/README.md @@ -19,9 +19,9 @@ Please see the [contributing] section for guidelines, examples, and process. # Install -```bash +```sh npm i hugo server ``` -**Note:** We're working on removing the need to run `npm i` for local development. Stay tuned. \ No newline at end of file +**Note:** We're working on removing the need to run `npm i` for local development. Stay tuned. diff --git a/archetypes/default.md b/archetypes/default.md new file mode 100644 index 000000000..58a60edc4 --- /dev/null +++ b/archetypes/default.md @@ -0,0 +1,6 @@ +--- +title: {{ replace .File.ContentBaseName "-" " " | strings.FirstUpper }} +description: +categories: [] +keywords: [] +--- diff --git a/archetypes/functions.md b/archetypes/functions.md index 44a2a5635..de2d72060 100644 --- a/archetypes/functions.md +++ b/archetypes/functions.md @@ -3,9 +3,9 @@ title: {{ replace .File.ContentBaseName "-" " " | title }} description: categories: [] keywords: [] -action: - aliases: [] - related: [] - returnType: - signatures: [] +params: + functions_and_methods: + aliases: [] + returnType: + signatures: [] --- diff --git a/archetypes/glossary.md b/archetypes/glossary.md index 4fa4669ec..1eeb4ef4b 100644 --- a/archetypes/glossary.md +++ b/archetypes/glossary.md @@ -1,6 +1,7 @@ --- title: {{ replace .File.ContentBaseName "-" " " }} -reference: +params: + reference: --- diff --git a/content/en/_common/content-format-table.md b/content/en/_common/content-format-table.md new file mode 100644 index 000000000..c0a66a146 --- /dev/null +++ b/content/en/_common/content-format-table.md @@ -0,0 +1,13 @@ +--- +_comment: Do not remove front matter. +--- + +Content format|Media type|Identifier|File extensions +:--|:--|:--|:-- +Markdown|`text/markdown`|`markdown`|`markdown`,`md`, `mdown` +HTML|`text/html`|`html`|`htm`, `html` +Emacs Org Mode|`text/org`|`org`|`org` +AsciiDoc|`text/asciidoc`|`asciidoc`|`ad`, `adoc`, `asciidoc` +Pandoc|`text/pandoc`|`pandoc`|`pandoc`, `pdc` +reStructuredText|`text/rst`|`rst`|`rst` + diff --git a/content/en/_common/filter-sort-group.md b/content/en/_common/filter-sort-group.md new file mode 100644 index 000000000..ac73766da --- /dev/null +++ b/content/en/_common/filter-sort-group.md @@ -0,0 +1,8 @@ +--- +_comment: Do not remove front matter. +--- + +> [!note] +> The [page collections quick reference guide] describes methods and functions to filter, sort, and group page collections. + +[page collections quick reference guide]: /quick-reference/page-collections/ diff --git a/content/en/functions/fmt/_common/fmt-layout.md b/content/en/_common/functions/fmt/format-string.md similarity index 100% rename from content/en/functions/fmt/_common/fmt-layout.md rename to content/en/_common/functions/fmt/format-string.md diff --git a/content/en/functions/_common/go-html-template-package.md b/content/en/_common/functions/go-html-template-package.md similarity index 100% rename from content/en/functions/_common/go-html-template-package.md rename to content/en/_common/functions/go-html-template-package.md diff --git a/content/en/functions/go-template/_common/text-template.md b/content/en/_common/functions/go-template/text-template.md similarity index 100% rename from content/en/functions/go-template/_common/text-template.md rename to content/en/_common/functions/go-template/text-template.md diff --git a/content/en/functions/images/_common/apply-image-filter.md b/content/en/_common/functions/images/apply-image-filter.md similarity index 100% rename from content/en/functions/images/_common/apply-image-filter.md rename to content/en/_common/functions/images/apply-image-filter.md diff --git a/content/en/_common/functions/js/options.md b/content/en/_common/functions/js/options.md new file mode 100644 index 000000000..475429d05 --- /dev/null +++ b/content/en/_common/functions/js/options.md @@ -0,0 +1,108 @@ +--- +_comment: Do not remove front matter. +--- + +params +: (`map` or `slice`) Params that can be imported as JSON in your JS files, e.g. + + ```go-html-template + {{ $js := resources.Get "js/main.js" | js.Build (dict "params" (dict "api" "https://example.org/api")) }} + ``` + And then in your JS file: + + ```js + import * as params from '@params'; + ``` + + Note that this is meant for small data sets, e.g., configuration settings. For larger data sets, please put/mount the files into `assets` and import them directly. + +minify +: (`bool`) Whether to let `js.Build` handle the minification. + +loaders +: {{< new-in 0.140.0 />}} +: (`map`) Configuring a loader for a given file type lets you load that file type with an `import` statement or a `require` call. For example, configuring the `.png` file extension to use the data URL loader means importing a `.png` file gives you a data URL containing the contents of that image. Loaders available are `none`, `base64`, `binary`, `copy`, `css`, `dataurl`, `default`, `empty`, `file`, `global-css`, `js`, `json`, `jsx`, `local-css`, `text`, `ts`, `tsx`. See https://esbuild.github.io/api/#loader. + +inject +: (`slice`) This option allows you to automatically replace a global variable with an import from another file. The path names must be relative to `assets`. See https://esbuild.github.io/api/#inject. + +shims +: (`map`) This option allows swapping out a component with another. A common use case is to load dependencies like React from a CDN (with _shims_) when in production, but running with the full bundled `node_modules` dependency during development: + + ```go-html-template + {{ $shims := dict "react" "js/shims/react.js" "react-dom" "js/shims/react-dom.js" }} + {{ $js = $js | js.Build dict "shims" $shims }} + ``` + + The _shim_ files may look like these: + + ```js + // js/shims/react.js + module.exports = window.React; + ``` + + ```js + // js/shims/react-dom.js + module.exports = window.ReactDOM; + ``` + + With the above, these imports should work in both scenarios: + + ```js + import * as React from 'react'; + import * as ReactDOM from 'react-dom/client'; + ``` + +target +: (`string`) The language target. One of: `es5`, `es2015`, `es2016`, `es2017`, `es2018`, `es2019`, `es2020`, `es2021`, `es2022`, `es2023`, `es2024`, or `esnext`. Default is `esnext`. + +platform +: {{< new-in 0.140.0 />}} +: (`string`) One of `browser`, `node`, `neutral`. Default is `browser`. See https://esbuild.github.io/api/#platform. + +externals +: (`slice`) External dependencies. Use this to trim dependencies you know will never be executed. See https://esbuild.github.io/api/#external. + +defines +: (`map`) This option allows you to define a set of string replacements to be performed when building. It must be a map where each key will be replaced by its value. + + ```go-html-template + {{ $defines := dict "process.env.NODE_ENV" `"development"` }} + ``` + +drop +: {{< new-in 0.144.0 />}} +: (`string`) Edit your source code before building to drop certain constructs: One of `debugger` or `console`. +: See https://esbuild.github.io/api/#drop + +sourceMap +: (`string`) Whether to generate `inline`, `linked`, or `external` source maps from esbuild. Linked and external source maps will be written to the target with the output file name + ".map". When `linked` a `sourceMappingURL` will also be written to the output file. By default, source maps are not created. Note that the `linked` option was added in Hugo 0.140.0. + +sourcesContent +: {{< new-in 0.140.0 />}} +: (`bool`) Whether to include the content of the source files in the source map. By default, this is `true`. + +JSX +: {{< new-in 0.124.0 />}} +: (`string`) How to handle/transform JSX syntax. One of: `transform`, `preserve`, `automatic`. Default is `transform`. Notably, the `automatic` transform was introduced in React 17+ and will cause the necessary JSX helper functions to be imported automatically. See https://esbuild.github.io/api/#jsx. + +JSXImportSource +: {{< new-in 0.124.0 />}} +: (`string`) Which library to use to automatically import its JSX helper functions from. This only works if `JSX` is set to `automatic`. The specified library needs to be installed through npm and expose certain exports. See https://esbuild.github.io/api/#jsx-import-source. + + The combination of `JSX` and `JSXImportSource` is helpful if you want to use a non-React JSX library like Preact, e.g.: + + ```go-html-template + {{ $js := resources.Get "js/main.jsx" | js.Build (dict "JSX" "automatic" "JSXImportSource" "preact") }} + ``` + + With the above, you can use Preact components and JSX without having to manually import `h` and `Fragment` every time: + + ```jsx + import { render } from 'preact'; + + const App = () => <>Hello world!; + + const container = document.getElementById('app'); + if (container) render(, container); + ``` diff --git a/content/en/_common/functions/locales.md b/content/en/_common/functions/locales.md new file mode 100644 index 000000000..1cfd7a1e6 --- /dev/null +++ b/content/en/_common/functions/locales.md @@ -0,0 +1,8 @@ +--- +_comment: Do not remove front matter. +--- + +> [!note] +> Localization of dates, currencies, numbers, and percentages is performed by the [gohugoio/locales] package. The language tag of the current site must match one of the listed locales. + +[gohugoio/locales]: https://github.com/gohugoio/locales diff --git a/content/en/functions/_common/regular-expressions.md b/content/en/_common/functions/regular-expressions.md similarity index 100% rename from content/en/functions/_common/regular-expressions.md rename to content/en/_common/functions/regular-expressions.md diff --git a/content/en/functions/go-template/_common/truthy-falsy.md b/content/en/_common/functions/truthy-falsy.md similarity index 100% rename from content/en/functions/go-template/_common/truthy-falsy.md rename to content/en/_common/functions/truthy-falsy.md diff --git a/content/en/functions/urls/_common/anchorize-vs-urlize.md b/content/en/_common/functions/urls/anchorize-vs-urlize.md similarity index 92% rename from content/en/functions/urls/_common/anchorize-vs-urlize.md rename to content/en/_common/functions/urls/anchorize-vs-urlize.md index 710a3c592..e00c181b8 100644 --- a/content/en/functions/urls/_common/anchorize-vs-urlize.md +++ b/content/en/_common/functions/urls/anchorize-vs-urlize.md @@ -2,7 +2,7 @@ _comment: Do not remove front matter. --- -The [`anchorize`] and [`urlize`] functions are similar: +The [`anchorize`] and [`urlize`] functions are similar: [`anchorize`]: /functions/urls/anchorize/ [`urlize`]: /functions/urls/urlize/ diff --git a/content/en/functions/_common/glob-patterns.md b/content/en/_common/glob-patterns.md similarity index 100% rename from content/en/functions/_common/glob-patterns.md rename to content/en/_common/glob-patterns.md diff --git a/content/en/_common/gomodules-info.md b/content/en/_common/gomodules-info.md new file mode 100644 index 000000000..5d88a6f9d --- /dev/null +++ b/content/en/_common/gomodules-info.md @@ -0,0 +1,13 @@ +--- +_comment: Do not remove front matter. +--- + +> [!note] Hugo Modules are Go Modules +> You need [Go] version 1.18 or later and [Git] to use Hugo Modules. For older sites hosted on Netlify, please ensure the `GO_VERSION` environment variable is set to `1.18` or higher. +> +> Go Modules resources: +> - [go.dev/wiki/Modules](https://go.dev/wiki/Modules) +> - [blog.golang.org/using-go-modules](https://go.dev/blog/using-go-modules) + +[Git]: https://git-scm.com/book/en/v2/Getting-Started-Installing-Git +[Go]: https://go.dev/doc/install diff --git a/content/en/installation/_common/01-editions.md b/content/en/_common/installation/01-editions.md similarity index 94% rename from content/en/installation/_common/01-editions.md rename to content/en/_common/installation/01-editions.md index 11e7e9080..634002822 100644 --- a/content/en/installation/_common/01-editions.md +++ b/content/en/_common/installation/01-editions.md @@ -13,4 +13,4 @@ Deploy your site directly to a Google Cloud Storage bucket, an AWS S3 bucket, or [dart sass]: /functions/css/sass/#dart-sass [processing images]: /content-management/image-processing/ [transpile sass to css]: /functions/css/sass/ -[details]: /hosting-and-deployment/hugo-deploy/ +[details]: /host-and-deploy/deploy-with-hugo-deploy/ diff --git a/content/en/installation/_common/02-prerequisites.md b/content/en/_common/installation/02-prerequisites.md similarity index 100% rename from content/en/installation/_common/02-prerequisites.md rename to content/en/_common/installation/02-prerequisites.md diff --git a/content/en/installation/_common/03-prebuilt-binaries.md b/content/en/_common/installation/03-prebuilt-binaries.md similarity index 100% rename from content/en/installation/_common/03-prebuilt-binaries.md rename to content/en/_common/installation/03-prebuilt-binaries.md diff --git a/content/en/installation/_common/04-build-from-source.md b/content/en/_common/installation/04-build-from-source.md similarity index 96% rename from content/en/installation/_common/04-build-from-source.md rename to content/en/_common/installation/04-build-from-source.md index b3039d18a..3ce245f4a 100644 --- a/content/en/installation/_common/04-build-from-source.md +++ b/content/en/_common/installation/04-build-from-source.md @@ -7,7 +7,7 @@ _comment: Do not remove front matter. To build the extended or extended/deploy edition from source you must: 1. Install [Git] -1. Install [Go] version 1.20 or later +1. Install [Go] version 1.23.0 or later 1. Install a C compiler, either [GCC] or [Clang] 1. Update your `PATH` environment variable as described in the [Go documentation] diff --git a/content/en/installation/_common/homebrew.md b/content/en/_common/installation/homebrew.md similarity index 100% rename from content/en/installation/_common/homebrew.md rename to content/en/_common/installation/homebrew.md diff --git a/content/en/methods/menu-entry/_common/pre-post.md b/content/en/_common/menu-entries/pre-and-post.md similarity index 100% rename from content/en/methods/menu-entry/_common/pre-post.md rename to content/en/_common/menu-entries/pre-and-post.md diff --git a/content/en/_common/menu-entry-properties.md b/content/en/_common/menu-entry-properties.md new file mode 100644 index 000000000..daeadd79d --- /dev/null +++ b/content/en/_common/menu-entry-properties.md @@ -0,0 +1,31 @@ +--- +_comment: Do not remove front matter. +--- + + + +identifier +: (`string`) Required when two or more menu entries have the same `name`, or when localizing the `name` using translation tables. Must start with a letter, followed by letters, digits, or underscores. + +name +: (`string`) The text to display when rendering the menu entry. + +params +: (`map`) User-defined properties for the menu entry. + +parent +: (`string`) The `identifier` of the parent menu entry. If `identifier` is not defined, use `name`. Required for child entries in a nested menu. + +post +: (`string`) The HTML to append when rendering the menu entry. + +pre +: (`string`) The HTML to prepend when rendering the menu entry. + +title +: (`string`) The HTML `title` attribute of the rendered menu entry. + +weight +: (`int`) A non-zero integer indicating the entry's position relative the root of the menu, or to its parent for a child entry. Lighter entries float to the top, while heavier entries sink to the bottom. diff --git a/content/en/methods/page/_common/next-and-prev.md b/content/en/_common/methods/page/next-and-prev.md similarity index 89% rename from content/en/methods/page/_common/next-and-prev.md rename to content/en/_common/methods/page/next-and-prev.md index 0a3022265..f859961a4 100644 --- a/content/en/methods/page/_common/next-and-prev.md +++ b/content/en/_common/methods/page/next-and-prev.md @@ -32,13 +32,13 @@ content/ And these templates: -{{< code file=layouts/_default/list.html >}} +```go-html-template {file="layouts/_default/list.html"} {{ range .Pages.ByWeight }}

{{ .LinkTitle }}

{{ end }} -{{< /code >}} +``` -{{< code file=layouts/_default/single.html >}} +```go-html-template {file="layouts/_default/single.html"} {{ with .Prev }} Previous {{ end }} @@ -46,7 +46,7 @@ And these templates: {{ with .Next }} Next {{ end }} -{{< /code >}} +``` When you visit page-2: @@ -55,6 +55,6 @@ When you visit page-2: 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. -[site configuration]: /getting-started/configuration/#configure-page +[site configuration]: /configuration/page/ [`Next`]: /methods/pages/prev [`Prev`]: /methods/pages/prev diff --git a/content/en/methods/page/_common/nextinsection-and-previnsection.md b/content/en/_common/methods/page/nextinsection-and-previnsection.md similarity index 91% rename from content/en/methods/page/_common/nextinsection-and-previnsection.md rename to content/en/_common/methods/page/nextinsection-and-previnsection.md index 1d1f5438a..54d240eb4 100644 --- a/content/en/methods/page/_common/nextinsection-and-previnsection.md +++ b/content/en/_common/methods/page/nextinsection-and-previnsection.md @@ -32,13 +32,13 @@ content/ And these templates: -{{< code file=layouts/_default/list.html >}} +```go-html-template {file="layouts/_default/list.html"} {{ range .Pages.ByWeight }}

{{ .LinkTitle }}

{{ end }} -{{< /code >}} +``` -{{< code file=layouts/_default/single.html >}} +```go-html-template {file="layouts/_default/single.html"} {{ with .PrevInSection }} Previous {{ end }} @@ -46,7 +46,7 @@ And these templates: {{ with .NextInSection }} Next {{ end }} -{{< /code >}} +``` When you visit page-2: @@ -55,7 +55,7 @@ When you visit page-2: 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. -[site configuration]: /getting-started/configuration/#configure-page +[site configuration]: /configuration/page/ [`Next`]: /methods/pages/prev [`Prev`]: /methods/pages/prev diff --git a/content/en/_common/methods/page/output-format-methods.md b/content/en/_common/methods/page/output-format-methods.md new file mode 100644 index 000000000..1e914db03 --- /dev/null +++ b/content/en/_common/methods/page/output-format-methods.md @@ -0,0 +1,35 @@ +--- +_comment: Do not remove front matter. +--- + +### Get IDENTIFIER + +(`any`) Returns the `OutputFormat` object with the given identifier. + +### MediaType + +(`media.Type`) Returns the media type of the output format. + +### MediaType.MainType + +(`string`) Returns the main type of the output format's media type. + +### MediaType.SubType + +(`string`) Returns the subtype of the current format's media type. + +### Name + +(`string`) Returns the output identifier of the output format. + +### Permalink + +(`string`) Returns the permalink of the page generated by the current output format. + +### Rel + +(`string`) Returns the `rel` value of the output format, either the default or as defined in the site configuration. + +### RelPermalink + +(`string`) Returns the relative permalink of the page generated by the current output format. diff --git a/content/en/methods/pages/_common/group-sort-order.md b/content/en/_common/methods/pages/group-sort-order.md similarity index 100% rename from content/en/methods/pages/_common/group-sort-order.md rename to content/en/_common/methods/pages/group-sort-order.md diff --git a/content/en/methods/pages/_common/next-and-prev.md b/content/en/_common/methods/pages/next-and-prev.md similarity index 88% rename from content/en/methods/pages/_common/next-and-prev.md rename to content/en/_common/methods/pages/next-and-prev.md index 540783992..462545c3f 100644 --- a/content/en/methods/pages/_common/next-and-prev.md +++ b/content/en/_common/methods/pages/next-and-prev.md @@ -32,13 +32,13 @@ content/ And these templates: -{{< code file=layouts/_default/list.html >}} -{{ range .Pages.ByWeight}} +```go-html-template {file="layouts/_default/list.html"} +{{ range .Pages.ByWeight }}

{{ .LinkTitle }}

{{ end }} -{{< /code >}} +``` -{{< code file=layouts/_default/single.html >}} +```go-html-template {file="layouts/_default/single.html"} {{ $pages := .CurrentSection.Pages.ByWeight }} {{ with $pages.Prev . }} @@ -48,7 +48,7 @@ And these templates: {{ with $pages.Next . }} Next {{ end }} -{{< /code >}} +``` When you visit page-2: @@ -57,7 +57,7 @@ When you visit page-2: To reverse the meaning of _next_ and _previous_ you can chain the [`Reverse`] method to the page collection definition: -{{< code file=layouts/_default/single.html >}} +```go-html-template {file="layouts/_default/single.html"} {{ $pages := .CurrentSection.Pages.ByWeight.Reverse }} {{ with $pages.Prev . }} @@ -67,6 +67,6 @@ To reverse the meaning of _next_ and _previous_ you can chain the [`Reverse`] me {{ with $pages.Next . }} Next {{ end }} -{{< /code >}} +``` [`Reverse`]: /methods/pages/reverse/ diff --git a/content/en/_common/methods/resource/global-page-remote-resources.md b/content/en/_common/methods/resource/global-page-remote-resources.md new file mode 100644 index 000000000..49146aed4 --- /dev/null +++ b/content/en/_common/methods/resource/global-page-remote-resources.md @@ -0,0 +1,6 @@ +--- +_comment: Do not remove front matter. +--- + +> [!note] +> Use this method with [global resources](g), [page resources](g), or [remote resources](g). diff --git a/content/en/methods/resource/_common/processing-spec.md b/content/en/_common/methods/resource/processing-spec.md similarity index 100% rename from content/en/methods/resource/_common/processing-spec.md rename to content/en/_common/methods/resource/processing-spec.md diff --git a/content/en/methods/taxonomy/_common/get-a-taxonomy-object.md b/content/en/_common/methods/taxonomy/get-a-taxonomy-object.md similarity index 96% rename from content/en/methods/taxonomy/_common/get-a-taxonomy-object.md rename to content/en/_common/methods/taxonomy/get-a-taxonomy-object.md index 9ef2585e1..6fb729c17 100644 --- a/content/en/methods/taxonomy/_common/get-a-taxonomy-object.md +++ b/content/en/_common/methods/taxonomy/get-a-taxonomy-object.md @@ -34,9 +34,9 @@ To capture the "genres" `Taxonomy` object from within any template, use the [`Ta To capture the "genres" `Taxonomy` object when rendering its page with a taxonomy template, use the [`Terms`] method on the page's [`Data`] object: -{{< code file=layouts/_default/taxonomy.html >}} +```go-html-template {file="layouts/_default/taxonomy.html"} {{ $taxonomyObject := .Data.Terms }} -{{< /code >}} +``` To inspect the data structure: diff --git a/content/en/methods/taxonomy/_common/ordered-taxonomy-element-methods.md b/content/en/_common/methods/taxonomy/ordered-taxonomy-element-methods.md similarity index 100% rename from content/en/methods/taxonomy/_common/ordered-taxonomy-element-methods.md rename to content/en/_common/methods/taxonomy/ordered-taxonomy-element-methods.md diff --git a/content/en/functions/time/_common/parsable-date-time-strings.md b/content/en/_common/parsable-date-time-strings.md similarity index 100% rename from content/en/functions/time/_common/parsable-date-time-strings.md rename to content/en/_common/parsable-date-time-strings.md diff --git a/content/en/_common/permalink-tokens.md b/content/en/_common/permalink-tokens.md new file mode 100644 index 000000000..4aec68fb8 --- /dev/null +++ b/content/en/_common/permalink-tokens.md @@ -0,0 +1,71 @@ +--- +_comment: Do not remove front matter. +--- + +`:year` +: The 4-digit year as defined in the front matter `date` field. + +`:month` +: The 2-digit month as defined in the front matter `date` field. + +`:monthname` +: The name of the month as defined in the front matter `date` field. + +`:day` +: The 2-digit day as defined in the front matter `date` field. + +`:weekday` +: The 1-digit day of the week as defined in the front matter `date` field (Sunday = `0`). + +`:weekdayname` +: The name of the day of the week as defined in the front matter `date` field. + +`:yearday` +: The 1- to 3-digit day of the year as defined in the front matter `date` field. + +`:section` +: The content's section. + +`:sections` +: The content's sections hierarchy. You can use a selection of the sections using _slice syntax_: `:sections[1:]` includes all but the first, `:sections[:last]` includes all but the last, `:sections[last]` includes only the last, `:sections[1:2]` includes section 2 and 3. Note that this slice access will not throw any out-of-bounds errors, so you don't have to be exact. + +`:title` +: The `title` as defined in front matter, else the automatic title. Hugo generates titles automatically for section, taxonomy, and term pages that are not backed by a file. + +`:slug` +: The `slug` as defined in front matter, else the `title` as defined in front matter, else the automatic title. Hugo generates titles automatically for section, taxonomy, and term pages that are not backed by a file. + +`:filename` +: The content's file name without extension, applicable to the `page` page kind. + + {{< deprecated-in v0.144.0 >}} + The `:filename` token has been deprecated. Use `:contentbasename` instead. + {{< /deprecated-in >}} + +`:slugorfilename` +: The `slug` as defined in front matter, else the content's file name without extension, applicable to the `page` page kind. + + {{< deprecated-in v0.144.0 >}} + The `:slugorfilename` token has been deprecated. Use `:slugorcontentbasename` instead. + {{< /deprecated-in >}} + +`:contentbasename` +: {{< new-in 0.144.0 />}} +: The [content base name]. + +[content base name]: /methods/page/file/#contentbasename + +`:slugorcontentbasename` +: {{< new-in 0.144.0 />}} +: The `slug` as defined in front matter, else the [content base name]. + +For time-related values, you can also use the layout string components defined in Go's [time package]. For example: + +[time package]: https://pkg.go.dev/time#pkg-constants + +{{< code-toggle file=hugo >}} +permalinks: + posts: /:06/:1/:2/:title/ +{{< /code-toggle >}} + +[content base name]: /methods/page/file/#contentbasename diff --git a/content/en/_common/ref-and-relref-error-handling.md b/content/en/_common/ref-and-relref-error-handling.md new file mode 100644 index 000000000..1d67bbc1f --- /dev/null +++ b/content/en/_common/ref-and-relref-error-handling.md @@ -0,0 +1,10 @@ +--- +_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. + +{{< code-toggle file=hugo >}} +refLinksErrorLevel = 'warning' +refLinksNotFoundURL = '/some/other/url' +{{< /code-toggle >}} diff --git a/content/en/_common/ref-and-relref-options.md b/content/en/_common/ref-and-relref-options.md new file mode 100644 index 000000000..ed0dd14c6 --- /dev/null +++ b/content/en/_common/ref-and-relref-options.md @@ -0,0 +1,12 @@ +--- +_comment: Do not remove front matter. +--- + +path +: (`string`) The path to the target page. Paths without a leading slash (`/`) are resolved first relative to the current page, and then relative to the rest of the site. + +lang +: (`string`) The language of the target page. Default is the current language. Optional. + +outputFormat +: (`string`) The output format of the target page. Default is the current output format. Optional. diff --git a/content/en/render-hooks/_common/pageinner.md b/content/en/_common/render-hooks/pageinner.md similarity index 70% rename from content/en/render-hooks/_common/pageinner.md rename to content/en/_common/render-hooks/pageinner.md index 6f2622880..a598b880a 100644 --- a/content/en/render-hooks/_common/pageinner.md +++ b/content/en/_common/render-hooks/pageinner.md @@ -8,7 +8,7 @@ _comment: Do not remove front matter. The primary use case for `PageInner` is to resolve links and [page resources](g) relative to an included `Page`. For example, create an "include" shortcode to compose a page from multiple content files, while preserving a global context for footnotes and the table of contents: -{{< code file=layouts/shortcodes/include.html >}} +```go-html-template {file="layouts/shortcodes/include.html" copy=true} {{ with .Get 0 }} {{ with $.Page.GetPage . }} {{- .RenderShortcodes }} @@ -18,13 +18,13 @@ The primary use case for `PageInner` is to resolve links and [page resources](g) {{ else }} {{ errorf "The %q shortcode requires a positional parameter indicating the logical path of the file to include. See %s" .Name .Position }} {{ end }} -{{< /code >}} +``` Then call the shortcode in your Markdown: -{{< code file=content/posts/p1.md >}} +```text {file="content/posts/p1.md"} {{%/* include "/posts/p2" */%}} -{{< /code >}} +``` Any render hook triggered while rendering `/posts/p2` will get: @@ -33,15 +33,15 @@ Any render hook triggered while rendering `/posts/p2` will get: `PageInner` falls back to the value of `Page` if not relevant, and always returns a value. -{{% note %}} -The `PageInner` method is only relevant for shortcodes that invoke the [`RenderShortcodes`] method, and you must call the shortcode using the `{{%/*..*/%}}` notation. - -[`RenderShortcodes`]: /methods/page/rendershortcodes/ -{{% /note %}} +> [!note] +> The `PageInner` method is only relevant for shortcodes that invoke the [`RenderShortcodes`] method, and you must call the shortcode using [Markdown notation]. As a practical example, Hugo's embedded link and image render hooks use the `PageInner` method to resolve markdown link and image destinations. See the source code for each: -- [Embedded link render hook]({{% eturl render-link %}}) -- [Embedded image render hook]({{% eturl render-image %}}) +- [Embedded link render hook] +- [Embedded image render hook] [`RenderShortcodes`]: /methods/page/rendershortcodes/ +[Markdown notation]: /content-management/shortcodes/#notation +[Embedded link render hook]: {{% eturl render-link %}} +[Embedded image render hook]: {{% eturl render-image %}} diff --git a/content/en/_common/store-methods.md b/content/en/_common/store-methods.md index 074216f7b..1dd776130 100644 --- a/content/en/_common/store-methods.md +++ b/content/en/_common/store-methods.md @@ -4,7 +4,7 @@ ## Methods -###### Set +### Set Sets the value of the given key. @@ -12,7 +12,7 @@ Sets the value of the given key. {{ .Store.Set "greeting" "Hello" }} ``` -###### Get +### Get Gets the value of the given key. @@ -21,7 +21,7 @@ Gets the value of the given key. {{ .Store.Get "greeting" }} → Hello ``` -###### Add +### Add Adds the given value to the existing value(s) of the given key. @@ -45,7 +45,7 @@ For single values, `Add` accepts values that support Go's `+` operator. If the f {{ .Store.Get "greetings" }} → [Hello Welcome Cheers] ``` -###### SetInMap +### SetInMap Takes a `key`, `mapKey` and `value` and adds a map of `mapKey` and `value` to the given `key`. @@ -53,9 +53,9 @@ Takes a `key`, `mapKey` and `value` and adds a map of `mapKey` and `value` to th {{ .Store.SetInMap "greetings" "english" "Hello" }} {{ .Store.SetInMap "greetings" "french" "Bonjour" }} {{ .Store.Get "greetings" }} → map[english:Hello french:Bonjour] -``` + ``` -###### DeleteInMap +### DeleteInMap Takes a `key` and `mapKey` and removes the map of `mapKey` from the given `key`. @@ -66,7 +66,7 @@ Takes a `key` and `mapKey` and removes the map of `mapKey` from the given `key`. {{ .Store.Get "greetings" }} → map[french:Bonjour] ``` -###### GetSortedMapValues +### GetSortedMapValues Returns an array of values from `key` sorted by `mapKey`. @@ -76,7 +76,7 @@ Returns an array of values from `key` sorted by `mapKey`. {{ .Store.GetSortedMapValues "greetings" }} → [Hello Bonjour] ``` -###### Delete +### Delete Removes the given key. diff --git a/content/en/functions/_common/highlighting-options.md b/content/en/_common/syntax-highlighting-options.md similarity index 68% rename from content/en/functions/_common/highlighting-options.md rename to content/en/_common/syntax-highlighting-options.md index 2d07ccccc..36144e090 100644 --- a/content/en/functions/_common/highlighting-options.md +++ b/content/en/_common/syntax-highlighting-options.md @@ -11,9 +11,8 @@ codeFences guessSyntax : (`bool`) Whether to automatically detect the language if the `LANG` argument is blank or set to a language for which there is no corresponding [lexer](g). Falls back to a plain text lexer if unable to automatically detect the language. Default is `false`. -{{% note %}} -The Chroma syntax highlighter includes lexers for approximately 250 languages, but only 5 of these have implemented automatic language detection. -{{% /note %}} + > [!note] + > The Chroma syntax highlighter includes lexers for approximately 250 languages, but only 5 of these have implemented automatic language detection. hl_Lines : (`string`) A space-delimited list of lines to emphasize within the highlighted code. To emphasize lines 2, 3, 4, and 7, set this value to `2-4 7`. This option is independent of the `lineNoStart` option. @@ -28,32 +27,30 @@ lineNoStart : (`int`) The number to display at the beginning of the first line. Irrelevant if `lineNos` is `false`. Default is `1`. lineNos -: (`bool`) Whether to display a number at the beginning of each line. Default is `false`. +: (`any`) Controls line number display. Default is `false`. + - `true`: Enable line numbers, controlled by `lineNumbersInTable`. + - `false`: Disable line numbers. + - `inline`: Enable inline line numbers (sets `lineNumbersInTable` to `false`). + - `table`: Enable table-based line numbers (sets `lineNumbersInTable` to `true`). lineNumbersInTable : (`bool`) Whether to render the highlighted code in an HTML table with two cells. The left table cell contains the line numbers, while the right table cell contains the code. Irrelevant if `lineNos` is `false`. Default is `true`. noClasses -: (`bool`) Whether to use inline CSS styles instead of an external CSS file. To use an external CSS file, set this value to `false` and generate the CSS file using the `hugo gen chromastyles` command. Default is `true`. +: (`bool`) Whether to use inline CSS styles instead of an external CSS file. Default is `true`. To use an external CSS file, set this value to `false` and generate the CSS file from the command line: + + ```text + hugo gen chromastyles --style=monokai > syntax.css + ``` style -: (`string`) The CSS styles to apply to the highlighted code. See the [style gallery] for examples. Case-sensitive. Default is `monokai`. - -[style gallery]: https://xyproto.github.io/splash/docs/ +: (`string`) The CSS styles to apply to the highlighted code. Case-sensitive. Default is `monokai`. See [syntax highlighting styles]. tabWidth : (`int`) Substitute this number of spaces for each tab character in your highlighted code. Irrelevant if `noClasses` is `false`. Default is `4`. wrapperClass -{{< new-in 0.140.2 />}} +: {{< new-in 0.140.2 />}} : (`string`) The class or classes to use for the outermost element of the highlighted code. Default is `highlight`. -{{% note %}} -Instead of specifying both `lineNos` and `lineNumbersInTable`, you can use the following shorthand notation: - -lineNos=inline -: equivalent to `lineNos=true` and `lineNumbersInTable=false` - -lineNos=table -: equivalent to `lineNos=true` and `lineNumbersInTable=true` -{{% /note %}} +[syntax highlighting styles]: /quick-reference/syntax-highlighting-styles/ diff --git a/content/en/functions/_common/time-layout-string.md b/content/en/_common/time-layout-string.md similarity index 100% rename from content/en/functions/_common/time-layout-string.md rename to content/en/_common/time-layout-string.md diff --git a/content/en/_index.md b/content/en/_index.md index 96ba0c413..358f6a4d9 100644 --- a/content/en/_index.md +++ b/content/en/_index.md @@ -1,49 +1,4 @@ --- -title: The world’s fastest framework for building websites -date: 2017-03-02T12:00:00-05:00 -features: - - heading: Blistering Speed - image_path: /images/icon-fast.svg - tagline: What's modern about waiting for your site to build? - copy: Hugo is the fastest tool of its kind. At <1 ms per page, the average site builds in less than a second. - - - heading: Robust Content Management - image_path: /images/icon-content-management.svg - tagline: Flexibility rules. Hugo is a content strategist's dream. - copy: Hugo supports unlimited content types, taxonomies, menus, dynamic API-driven content, and more, all without plugins. - - - heading: Shortcodes - image_path: /images/icon-shortcodes.svg - tagline: Hugo's shortcodes are Markdown's hidden superpower. - copy: We love the beautiful simplicity of Markdown’s syntax, but there are times when we want more flexibility. Hugo shortcodes allow for both beauty and flexibility. - - - heading: Built-in Templates - image_path: /images/icon-built-in-templates.svg - tagline: Hugo has common patterns to get your work done quickly. - copy: Hugo ships with pre-made templates to make quick work of SEO, commenting, analytics and other functions. One line of code, and you're done. - - - heading: Multilingual and i18n - image_path: /images/icon-multilingual2.svg - tagline: Polyglot baked in. - copy: Hugo provides full i18n support for multi-language sites with the same straightforward development experience Hugo users love in single-language sites. - - - heading: Custom Outputs - image_path: /images/icon-custom-outputs.svg - tagline: HTML not enough? - copy: Hugo allows you to output your content in multiple formats, including JSON or AMP, and makes it easy to create your own. -sections: - - heading: "300+ Themes" - cta: Check out the Hugo themes. - link: https://themes.gohugo.io/ - color_classes: bg-accent-color white - image: /images/homepage-screenshot-hugo-themes.jpg - copy: "Hugo provides a robust theming system that is easy to implement but capable of producing even the most complicated websites." - - heading: "Capable Templating" - cta: Get Started. - link: templates/ - color_classes: bg-primary-color-light black - image: /images/home-page-templating-example.png - copy: "Hugo's Go-based templating provides just the right amount of logic to build anything from the simple to complex." +title: The world's fastest framework for building websites +description: Hugo is one of the most popular open-source static site generators. With its amazing speed and flexibility, Hugo makes building websites fun again. --- - -Hugo is one of the most popular open-source static site generators. With its amazing speed and flexibility, Hugo makes building websites fun again. diff --git a/content/en/about/_index.md b/content/en/about/_index.md index f15c38dcc..e55800959 100644 --- a/content/en/about/_index.md +++ b/content/en/about/_index.md @@ -1,16 +1,9 @@ --- title: About Hugo -linktitle: About +linkTitle: About description: Learn about Hugo and its features, privacy protections, and security model. categories: [] keywords: [] -menu: - docs: - identifier: about-hugo-in-this-section - parent: about - weight: 10 weight: 10 aliases: [/about-hugo/,/docs/] --- - -Learn about Hugo and its features, privacy protections, and security model. diff --git a/content/en/about/features.md b/content/en/about/features.md index 883d53407..ff1a6b8eb 100644 --- a/content/en/about/features.md +++ b/content/en/about/features.md @@ -1,14 +1,9 @@ --- title: Features description: Hugo's rich and powerful feature set provides the framework and tools to create static sites that build in seconds, often less. -categories: [about] +categories: [] keywords: [] -menu: - docs: - parent: about - weight: 30 -weight: 30 -toc: true +weight: 20 --- ## Framework @@ -61,7 +56,7 @@ toc: true : Syntactically highlight code examples using Hugo's embedded syntax highlighter, enabled by default for fenced code blocks in Markdown. The syntax highlighter supports hundreds of code languages and dozens of styles. [Shortcodes] -: Use Hugo's embedded shortcodes, or create your own, to insert complex content. For example, use shortcodes to include `audio` and `video` elements, render tables from local or remote data sources, insert snippets from other pages, and more. +: Use Hugo's embedded shortcodes, or create your own, to insert complex content. For example, use shortcodes to include `audio` and `video` elements, render tables from local or remote data sources, insert snippets from other pages, and more. ## Content management @@ -83,7 +78,7 @@ toc: true ## Asset pipelines [Image processing] -: Convert, resize, crop, rotate, adjust colors, apply filters, overlay text and images, and extract EXIF data. +: Convert, resize, crop, rotate, adjust colors, apply filters, overlay text and images, and extract EXIF data. [JavaScript bundling] : Transpile TypeScript and JSX to JavaScript, bundle, tree shake, minify, create source maps, and perform SRI hashing. @@ -107,18 +102,18 @@ toc: true [Multilingual]: /content-management/multilingual/ [Multiplatform]: /installation/ -[Output formats]: /templates/output-formats/ +[Output formats]: /configuration/output-formats/ [Templates]: /templates/introduction/ [Themes]: https://themes.gohugo.io/ [Modules]: /hugo-modules/ -[Privacy]: /about/privacy/ +[Privacy]: /configuration/privacy/ [Security]: /about/security/ [Content formats]: /content-management/formats/ [CommonMark]: https://spec.commonmark.org/current/ [GitHub Flavored Markdown]: https://github.github.com/gfm/ [Markdown attributes]: /content-management/markdown-attributes/ -[Markdown extensions]: /getting-started/configuration-markup/#goldmark-extensions +[Markdown extensions]: /configuration/markup/#extensions [Markdown render hooks]: /render-hooks/introduction/ [Diagrams]: /content-management/diagrams/ [Mathematics]: /content-management/mathematics/ @@ -137,5 +132,5 @@ toc: true [Tailwind CSS processing]: /functions/css/tailwindcss/ [Caching]: /functions/partials/includecached/ -[Segmentation]: /getting-started/configuration/#configure-segments -[Minification]: /getting-started/configuration/#configure-minify +[Segmentation]: /configuration/segments/ +[Minification]: /configuration/minify/ diff --git a/content/en/about/introduction.md b/content/en/about/introduction.md index d89938eed..9586d08f8 100644 --- a/content/en/about/introduction.md +++ b/content/en/about/introduction.md @@ -1,14 +1,9 @@ --- title: Introduction -description: Hugo is a static site generator written in Go, optimized for speed and designed for flexibility. -categories: [about] +description: Hugo is a static site generator written in Go, optimized for speed and designed for flexibility. +categories: [] keywords: [] -menu: - docs: - identifier: about-introduction - parent: about - weight: 20 -weight: 20 +weight: 10 aliases: [/about/what-is-hugo/,/about/benefits/] --- @@ -32,8 +27,8 @@ Learn more about Hugo's [features], [privacy protections], and [security model]. [Go]: https://go.dev [Hugo Modules]: /hugo-modules/ [static site generator]: https://en.wikipedia.org/wiki/Static_site_generator -[features]: /about/features -[security model]: /about/security -[privacy protections]: /about/privacy +[features]: /about/features/ +[security model]: about/security/ +[privacy protections]: /configuration/privacy {{< youtube 0RKpf3rK57I >}} diff --git a/content/en/about/license.md b/content/en/about/license.md index f434b233e..06a3a695d 100644 --- a/content/en/about/license.md +++ b/content/en/about/license.md @@ -1,18 +1,13 @@ --- title: License description: Hugo is released under the Apache 2.0 license. -categories: [about] -keywords: [apache] -menu: - docs: - parent: about - weight: 60 -weight: 60 +categories: [] +keywords: [] +weight: 40 --- ## Apache License - _Version 2.0, January 2004_ __ diff --git a/content/en/about/security.md b/content/en/about/security.md index 29f2c7ed1..509ca6a75 100644 --- a/content/en/about/security.md +++ b/content/en/about/security.md @@ -2,71 +2,57 @@ title: Security model linkTitle: Security description: A summary of Hugo's security model. -categories: [about] -keywords: [security,privacy] -menu: - docs: - parent: about - weight: 50 -weight: 50 -toc: true +categories: [] +keywords: [] +weight: 30 aliases: [/about/security-model/] --- ## Runtime security -Hugo produces static output, so once built, the runtime is the browser (assuming the output is HTML) and any server (API) that you integrate with. +Hugo generates static websites, meaning the final output runs directly in the browser and interacts with any integrated APIs. However, during development and site building, the `hugo` executable itself is the runtime environment. -But when developing and building your site, the runtime is the `hugo` executable. Securing a runtime can be [a real challenge](https://blog.logrocket.com/how-to-protect-your-node-js-applications-from-malicious-dependencies-5f2e60ea08f9/). +Securing a runtime is a complex task. Hugo addresses this through a robust sandboxing approach and a strict security policy with default protections. Key features include: -**Hugo's main approach is that of sandboxing and a security policy with strict defaults:** +- Virtual file system: Hugo employs a virtual file system, limiting file access. Only the main project, not external components, can access files or directories outside the project root. +- Read-Only access: User-defined components have read-only access to the file system, preventing unintended modifications. +- Controlled external binaries: While Hugo utilizes external binaries for features like Asciidoctor support, these are strictly predefined with specific flags and are disabled by default. The [security policy] details these limitations. +- No arbitrary commands: To mitigate risks, Hugo intentionally avoids implementing general functions that would allow users to execute arbitrary operating system commands. -* Hugo has a virtual file system and only the main project (not third-party components) is allowed to mount directories or files outside the project root. -* User-defined components have read-only access to the filesystem. -* We shell out to some external binaries to support [Asciidoctor](/content-management/formats/#formats) and similar, but those binaries and their flags are predefined and disabled by default (see [Security Policy](#security-policy)). General functions to run arbitrary external OS commands have been [discussed](https://github.com/gohugoio/hugo/issues/796), but not implemented because of security concerns. +This combination of sandboxing and strict defaults effectively minimizes potential security vulnerabilities during the Hugo build process. -## Security policy - -Hugo has a built-in security policy that restricts access to [os/exec](https://pkg.go.dev/os/exec), remote communication and similar. - -The default configuration is listed below. Any build using features not in the allow list of the security policy will fail with a detailed message about what needs to be done. Most of these settings are allow lists (string or slice, [Regular Expressions](https://pkg.go.dev/regexp) or `none` which matches nothing). - -{{< code-toggle config=security />}} - -By default, Hugo permits the [`resources.GetRemote`] function to download files with media types corresponding to an internal allow list. To add media types to the allow list: - -[`resources.GetRemote`]: /functions/resources/getremote - -{{< code-toggle file=hugo >}} -[security.http] -mediaTypes = ['^image/avif$'] -{{< /code-toggle >}} - -Note that these and other configuration settings in Hugo can be overridden by the OS environment. For example, if you want to block all remote HTTP fetching of data: - -```txt -HUGO_SECURITY_HTTP_URLS=none hugo -``` +[security policy]: /configuration/security/ ## Dependency security -Hugo is built as a static binary using [Go Modules](https://github.com/golang/go/wiki/Modules) to manage its dependencies. Go Modules have several safeguards, one of them being the `go.sum` file. This is a database of the expected cryptographic checksums of all of your dependencies, including transitive dependencies. +Hugo utilizes [Go Modules] to manage its dependencies, compiling as a static binary. Go Modules create a `go.sum` file, a critical security feature. This file acts as a database, storing the expected cryptographic checksums of all dependencies, including those required indirectly (transitive dependencies). -[Hugo Modules](/hugo-modules/) is a feature built on top of the functionality of Go Modules. Like Go Modules, a Hugo project using Hugo Modules will have a `go.sum` file. We recommend that you commit this file to your version control system. The Hugo build will fail if there is a checksum mismatch, which would be an indication of [dependency tampering](https://julienrenaux.fr/2019/12/20/github-actions-security-risk/). +[Hugo Modules], which extend Go Modules' functionality, also produce a `go.sum` file. To ensure dependency integrity, commit this `go.sum` file to your version control. If Hugo detects a checksum mismatch during the build process, it will fail, indicating a possible attempt to [tamper with your project's dependencies]. + +[Go Modules]: https://go.dev/wiki/Modules#modules +[Hugo Modules]: /hugo-modules/ +[tamper with your project's dependencies]: https://julienrenaux.fr/2019/12/20/github-actions-security-risk/ ## Web application security -These are the security threats as defined by [OWASP](https://en.wikipedia.org/wiki/OWASP). +Hugo's security philosophy is rooted in established security standards, primarily aligning with the threats defined by [OWASP]. For HTML output, Hugo operates under a clear trust model. This model assumes that template and configuration authors, the developers, are trustworthy. However, the data supplied to these templates is inherently considered untrusted. This distinction is crucial for understanding how Hugo handles potential security risks. -For HTML output, this is the core security model: +[OWASP]: https://en.wikipedia.org/wiki/OWASP - +To prevent unintended escaping of data that developers know is safe, Hugo provides [`safe`] functions, such as [`safeHTML`]. These functions allow developers to explicitly mark data as trusted, bypassing the default escaping mechanisms. This is essential for scenarios where data is generated or sourced from reliable sources. However, an exception exists: enabling [inline shortcodes]. By activating this feature, you are implicitly trusting the logic within the shortcodes and the data contained within your content files. -In short: +[`safeHTML`]: /functions/safe/html/ +[inline shortcodes]: /content-management/shortcodes/#inline -Template and configuration authors (you) are trusted, but the data you send in is not. -This is why you sometimes need to use the _safe_ functions, such as `safeHTML`, to avoid escaping of data you know is safe. -There is one exception to the above, as noted in the documentation: If you enable inline shortcodes, you also say that the shortcodes and data handling in content files are trusted, as those macros are treated as pure text. -It may be worth adding that Hugo is a static site generator with no concept of dynamic user input. +It's vital to remember that Hugo is a static site generator. This architectural choice significantly reduces the attack surface by eliminating the complexities and vulnerabilities associated with dynamic user input. Unlike dynamic websites, Hugo generates static HTML files, minimizing the risk of real-time attacks. Regarding content, Hugo's default Markdown renderer is [configured to sanitize] potentially unsafe content. This default behavior ensures that potentially malicious code or scripts are removed or escaped. However, this setting can be reconfigured if you have a high degree of confidence in the safety of your content sources. -For content, the default Markdown renderer is [configured](/getting-started/configuration-markup) to remove or escape potentially unsafe content. This behavior can be reconfigured if you trust your content. +[configured to sanitize]: /configuration/markup/#rendererunsafe + +In essence, Hugo prioritizes secure output by establishing a clear trust boundary between developers and data. By default, it errs on the side of caution, sanitizing potentially unsafe content and escaping data. Developers have the flexibility to adjust these defaults through [`safe`] functions and [configuration options], but they must do so with a clear understanding of the security implications. Hugo's static site generation model further strengthens its security posture by minimizing dynamic vulnerabilities. + +[`safe`]: /functions/safe +[configuration options]: /configuration/security + +## Configuration + +See [configure security](/configuration/security/). diff --git a/content/en/commands/_index.md b/content/en/commands/_index.md index 89f673bf2..5869bfd9d 100644 --- a/content/en/commands/_index.md +++ b/content/en/commands/_index.md @@ -4,9 +4,5 @@ linkTitle: CLI description: Use the command line interface (CLI) to manage your site. categories: [] keywords: [] -menu: - docs: - parent: commands - weight: 10 weight: 10 --- diff --git a/content/en/commands/hugo.md b/content/en/commands/hugo.md index 42f882ad7..ef0bca9a5 100644 --- a/content/en/commands/hugo.md +++ b/content/en/commands/hugo.md @@ -72,6 +72,7 @@ hugo [flags] * [hugo completion](/commands/hugo_completion/) - Generate the autocompletion script for the specified shell * [hugo config](/commands/hugo_config/) - Display site configuration * [hugo convert](/commands/hugo_convert/) - Convert front matter to another format +* [hugo deploy](/commands/hugo_deploy/) - Deploy your site to a cloud provider * [hugo env](/commands/hugo_env/) - Display version and environment info * [hugo gen](/commands/hugo_gen/) - Generate documentation and syntax highlighting styles * [hugo import](/commands/hugo_import/) - Import a site from another system diff --git a/content/en/configuration/_index.md b/content/en/configuration/_index.md new file mode 100644 index 000000000..7cb08cc73 --- /dev/null +++ b/content/en/configuration/_index.md @@ -0,0 +1,7 @@ +--- +title: Configuration +description: Configure your site. +categories: [] +keywords: [] +weight: 10 +--- diff --git a/content/en/configuration/all.md b/content/en/configuration/all.md new file mode 100644 index 000000000..9bc05057f --- /dev/null +++ b/content/en/configuration/all.md @@ -0,0 +1,362 @@ +--- +title: All settings +description: The complete list of Hugo configuration settings. +categories: [] +keywords: [] +weight: 20 +aliases: [/getting-started/configuration/] +--- + +## Settings + +archetypeDir +: (`string`) The designated directory for [archetypes](g). Default is `archetypes`. {{% module-mounts-note %}} + +assetDir +: (`string`) The designated directory for [global resources](g). Default is `assets`. {{% module-mounts-note %}} + +baseURL +: (`string`) The absolute URL of your published site including the protocol, host, path, and a trailing slash. + +build +: See [configure build](/configuration/build/). + +buildDrafts +: (`bool`) Whether to include draft content when building a site. Default is `false`. + +buildExpired +: (`bool`) Whether to include expired content when building a site. Default is `false`. + +buildFuture +: (`bool`) Whether to include future content when building a site. Default is `false`. + +cacheDir +: (`string`) The designated cache directory. See [details](#cache-directory). + +caches +: See [configure file caches](/configuration/caches/). + +canonifyURLs +: (`bool`) See [details](/content-management/urls/#canonical-urls) before enabling this feature. Default is `false`. + +capitalizeListTitles +: {{< new-in 0.123.3 />}} +: (`bool`) Whether to capitalize automatic list titles. Applicable to section, taxonomy, and term pages. Default is `true`. Use the [`titleCaseStyle`](#titlecasestyle) setting to configure capitalization rules. + +cascade +: See [configure cascade](/configuration/cascade/). + +cleanDestinationDir +: (`bool`) Whether to remove files from the site's destination directory that do not have corresponding files in the `static` directory during the build. Default is `false`. + +contentDir +: (`string`) The designated directory for content files. Default is `content`. {{% module-mounts-note %}} + +copyright +: (`string`) The copyright notice for a site, typically displayed in the footer. + +dataDir +: (`string`) The designated directory for data files. Default is `data`. {{% module-mounts-note %}} + +defaultContentLanguage +: (`string`) The project's default language key, conforming to the syntax described in [RFC 5646]. This value must match one of the defined language keys. Default is `en`. + +defaultContentLanguageInSubdir +: (`bool`) Whether to publish the default language site to a subdirectory matching the `defaultContentLanguage`. Default is `false`. + +defaultOutputFormat +: (`string`) The default output format for the site. If unspecified, the first available format in the defined order (by weight, then alphabetically) will be used. + +deployment +: See [configure deployment](/configuration/deployment/). + +disableAliases +: (`bool`) Whether to disable generation of alias redirects. Even if this option is enabled, the defined aliases will still be present on the page. This allows you to manage redirects separately, for example, by generating 301 redirects in an `.htaccess` file or a Netlify `_redirects` file using a custom output format. Default is `false`. + +disableDefaultLanguageRedirect +: {{< new-in 0.140.0 />}} +: (`bool`) Whether to disable generation of the alias redirect to the default language when `DefaultContentLanguageInSubdir` is `true`. Default is `false`. + +disableHugoGeneratorInject +: (`bool`) Whether to disable injection of a `` tag into the home page. Default is `false`. + +disableKinds +: (`[]string`) A slice of page [kinds](g) to disable during the build process, any of `404`, `home`, `page`, `robotstxt`, `rss`, `section`, `sitemap`, `taxonomy`, or `term`. + +disableLanguages +: (`[]string]`) A slice of language keys representing the languages to disable during the build process. Although this is functional, consider using the [`disabled`] key under each language instead. + +disableLiveReload +: (`bool`) Whether to disable automatic live reloading of the browser window. Default is `false`. + +disablePathToLower +: (`bool`) Whether to disable transformation of page URLs to lower case. + +enableEmoji +: (`bool`) Whether to allow emoji in Markdown. Default is `false`. + +enableGitInfo +: (`bool`) For sites under Git version control, whether to enable the [`GitInfo`] object for each page. With the [default front matter configuration], the `Lastmod` method on a `Page` object will return the Git author date. Default is `false`. + +enableMissingTranslationPlaceholders +: (`bool`) Whether to show a placeholder instead of the default value or an empty string if a translation is missing. Default is `false`. + +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`. + +frontmatter +: See [configure front matter](/configuration/front-matter/). + +hasCJKLanguage +: (`bool`) Whether to automatically detect [CJK](g) languages in content. Affects the values returned by the [`WordCount`] and [`FuzzyWordCount`] methods. Default is `false`. + +HTTPCache +: See [configure HTTP cache](/configuration/http-cache/). + +i18nDir +: (`string`) The designated directory for translation tables. Default is `i18n`. {{% module-mounts-note %}} + +ignoreCache +: (`bool`) Whether to ignore the cache directory. Default is `false`. + +ignoreFiles +: (`[]string]`) A slice of [regular expressions](g) used to exclude specific files from a build. These expressions are matched against the absolute file path and apply to files within the `content`, `data`, and `i18n` directories. For more advanced file exclusion options, see the section on [module mounts]. + +ignoreLogs +: (`[]string`) A slice of message identifiers corresponding to warnings and errors you wish to suppress. See [`erroridf`] and [`warnidf`]. + +ignoreVendorPaths +: (`string`) A [glob](g) pattern matching the module paths to exclude from the `_vendor` directory. + +imaging +: See [configure imaging](/configuration/imaging/). + +languageCode +: (`string`) The site's language tag, conforming to the syntax described in [RFC 5646]. This value does not affect translations or localization. Hugo uses this value to populate: + + - The `language` element in the [embedded RSS template] + - The `lang` attribute of the `html` element in the [embedded alias template] + - The `og:locale` `meta` element in the [embedded Open Graph template] + + When present in the root of the configuration, this value is ignored if one or more language keys exists. Please specify this value independently for each language key. + +languages +: See [configure languages](/configuration/languages/). + +layoutDir +: (`string`) The designated directory for templates. Default is `layouts`. {{% module-mounts-note %}} + +mainSections +: (`string` or `[]string`) The main sections of a site. If set, the [`MainSections`] method on the `Site` object returns the given sections, otherwise it returns the section with the most pages. + +markup +: See [configure markup](/configuration/markup/). + +mediaTypes +: See [configure media types](/configuration/media-types/). + +menus +: See [configure menus](/configuration/menus/). + +minify +: See [configure minify](/configuration/minify/). + +module +: See [configure modules](/configuration/module/). + +newContentEditor +: (`string`) The editor to use when creating new content. + +noBuildLock +: (`bool`) Whether to disable creation of the `.hugo_build.lock` file. Default is `false`. + +noChmod +: (`bool`) Whether to disable synchronization of file permission modes. Default is `false`. + +noTimes +: (`bool`) Whether to disable synchronization of file modification times. Default is `false`. + +outputFormats +: See [configure output formats](/configuration/output-formats/). + +outputs +: See [configure outputs](/configuration/outputs/). + +page +: See [configure page](/configuration/page/). + +pagination +: See [configure pagination](/configuration/pagination/). + +panicOnWarning +: (`bool`) Whether to panic on the first WARNING. Default is `false`. + +params +: See [configure params](/configuration/params/). + +permalinks +: See [configure permalinks](/configuration/permalinks/). + +pluralizeListTitles +: (`bool`) Whether to pluralize automatic list titles. Applicable to section pages. Default is `true`. + +printI18nWarnings +: (`bool`) Whether to log WARNINGs for each missing translation. Default is `false`. + +printPathWarnings +: (`bool`) Whether to log WARNINGs when Hugo publishes two or more files to the same path. Default is `false`. + +printUnusedTemplates +: (`bool`) Whether to log WARNINGs for each unused template. Default is `false`. + +privacy +: See [configure privacy](/configuration/privacy/). + +publishDir +: (`string`) The designated directory for publishing the site. Default is `public`. + +refLinksErrorLevel +: (`string`) The logging error level to use when the `ref` and `relref` functions, methods, and shortcodes are unable to resolve a reference to a page. Either `ERROR` or `WARNING`. Any `ERROR` will fail the build. Default is `ERROR`. + +refLinksNotFoundURL +: (`string`) The URL to return when the `ref` and `relref` functions, methods, and shortcodes are unable to resolve a reference to a page. + +related +: See [configure related content](/configuration/related-content/). + +relativeURLs +: (`bool`) See [details](/content-management/urls/#relative-urls) before enabling this feature. Default is `false`. + +removePathAccents +: (`bool`) Whether to remove [non-spacing marks](https://www.compart.com/en/unicode/category/Mn) from [composite characters](https://en.wikipedia.org/wiki/Precomposed_character) in content paths. Default is `false`. + +renderSegments +: {{< new-in 0.124.0 />}} +: (`[]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. + +resourceDir +: (`string`) The designated directory for caching output from [asset pipelines](g). Default is `resources`. + +security +: See [configure security](/configuration/security/). + +sectionPagesMenu +: (`string`) When set, each top-level section will be added to the menu identified by the provided value. See [details](/content-management/menus/#define-automatically). + +segments +: See [configure segments](/configuration/segments/). + +server +: See [configure server](/configuration/server/). + +services +: See [configure services](/configuration/services/). + +sitemap +: See [configure sitemap](/configuration/sitemap/). + +staticDir +: (`string`) The designated directory for static files. Default is `static`. {{% module-mounts-note %}} + +summaryLength +: (`int`) Applicable to [automatic summaries], the minimum number of words returned by the [`Summary`] method on a `Page` object. The `Summary` method will return content truncated at the paragraph boundary closest to the specified `summaryLength`, but at least this minimum number of words. + +taxonomies +: See [configure taxonomies](/configuration/taxonomies/). + +templateMetrics +: (`bool`) Whether to print template execution metrics to the console. Default is `false`. See [details](/troubleshooting/performance/#template-metrics). + +templateMetricsHints +: (`bool`) Whether to print template execution improvement hints to the console. Applicable when `templateMetrics` is `true`. Default is `false`. See [details](/troubleshooting/performance/#template-metrics). + +theme +: (`string` or `[]string`) The [theme](g) to use. Multiple themes can be listed, with precedence given from left to right. See [details](/hugo-modules/theme-components/). + +themesDir +: (`string`) The designated directory for themes. Default is `themes`. + +timeout +: (`string`) The timeout for generating page content, either as a [duration] or in seconds. This timeout is used to prevent infinite recursion during content generation. You may need to increase this value if your pages take a long time to generate, for example, due to extensive image processing or reliance on remote content. Default is `30s`. + +timeZone +: (`string`) The time zone used to parse dates without time zone offsets, including front matter date fields and values passed to the [`time.AsTime`] and [`time.Format`] template functions. The list of valid values may be system dependent, but should include `UTC`, `Local`, and any location in the [IANA Time Zone Database]. For example, `America/Los_Angeles` and `Europe/Oslo` are valid time zones. + +title +: (`string`) The site title. + +titleCaseStyle +: (`string`) The capitalization rules to follow when Hugo automatically generates a section title, or when using the [`strings.Title`] function. One of `ap`, `chicago`, `go`, `firstupper`, or `none`. Default is `ap`. See [details](#title-case-style). + +uglyurls +: See [configure ugly URLs](/configuration/ugly-urls/). + +## Cache directory + +Hugo's file cache directory is configurable via the [`cacheDir`] configuration option or the `HUGO_CACHEDIR` environment variable. If neither is set, Hugo will use, in order of preference: + +1. If running on Netlify: `/opt/build/cache/hugo_cache/`. This means that if you run your builds on Netlify, all caches configured with `:cacheDir` will be saved and restored on the next build. For other [CI/CD](g) vendors, please read their documentation. For an CircleCI example, see [this configuration]. +1. In a `hugo_cache` directory below the OS user cache directory as defined by Go's [os.UserCacheDir] function. On Unix systems, per the [XDG base directory specification], this is `$XDG_CACHE_HOME` if non-empty, else `$HOME/.cache`. On MacOS, this is `$HOME/Library/Caches`. On Windows, this is`%LocalAppData%`. On Plan 9, this is `$home/lib/cache`. +1. In a `hugo_cache_$USER` directory below the OS temp dir. + +To determine the current `cacheDir`: + +```sh +hugo config | grep cachedir +``` + +## Title case style + +Hugo's [`titleCaseStyle`] setting governs capitalization for automatically generated section titles and the [`strings.Title`] function. By default, it follows the capitalization rules published in the Associated Press Stylebook. Change this setting to use other capitalization rules. + +ap +: Use the capitalization rules published in the [Associated Press Stylebook]. This is the default. + +chicago +: Use the capitalization rules published in the [Chicago Manual of Style]. + +go +: Capitalize the first letter of every word. + +firstupper +: Capitalize the first letter of the first word. + +none +: Disable transformation of automatic section titles, and disable the transformation performed by the `strings.Title` function. This is useful if you would prefer to manually capitalize section titles as needed, and to bypass opinionated theme usage of the `strings.Title` function. + +## Localized settings + +Some configuration settings, such as menus and custom parameters, can be defined separately for each language. See [configure languages](/configuration/languages/#localized-settings). + +[`cacheDir`]: #cachedir +[`disabled`]: /configuration/languages/#disabled +[`erroridf`]: /functions/fmt/erroridf/ +[`FuzzyWordCount`]: /methods/page/fuzzywordcount/ +[`GitInfo`]: /methods/page/gitinfo/ +[`MainSections`]: /methods/site/mainsections/ +[`segments`]: /configuration/segments/ +[`strings.Title`]: /functions/strings/title/ +[`strings.Title`]: /functions/strings/title +[`Summary`]: /methods/page/summary/ +[`time.AsTime`]: /functions/time/astime/ +[`time.Format`]: /functions/time/format/ +[`titleCaseStyle`]: #titlecasestyle +[`warnidf`]: /functions/fmt/warnidf/ +[`WordCount`]: /methods/page/wordcount/ +[Associated Press Stylebook]: https://www.apstylebook.com/ +[automatic summaries]: /content-management/summaries/#automatic-summary +[Chicago Manual of Style]: https://www.chicagomanualofstyle.org/home.html +[default front matter configuration]: /configuration/front-matter/ +[duration]: https://pkg.go.dev/time#Duration +[embedded alias template]: {{% eturl alias %}} +[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 +[module mounts]: /configuration/module/#mounts +[os.UserCacheDir]: https://pkg.go.dev/os#UserCacheDir +[RFC 5646]: https://datatracker.ietf.org/doc/html/rfc5646#section-2.1 +[this configuration]: https://github.com/bep/hugo-sass-test/blob/6c3960a8f4b90e8938228688bc49bdcdd6b2d99e/.circleci/config.yml +[XDG base directory specification]: https://specifications.freedesktop.org/basedir-spec/latest/ diff --git a/content/en/configuration/build.md b/content/en/configuration/build.md new file mode 100644 index 000000000..116294f05 --- /dev/null +++ b/content/en/configuration/build.md @@ -0,0 +1,81 @@ +--- +title: Configure build +linkTitle: Build +description: Configure global build options. +categories: [] +keywords: [] +aliases: [/getting-started/configuration-build/] +--- + +The `build` configuration section contains global build-related configuration options. + +{{< code-toggle config=build />}} + +buildStats +: See the [build stats](#build-stats) section below. + +cachebusters +: See the [cache busters](#cache-busters) section below. + +noJSConfigInAssets +: (`bool`) Whether to disable writing a `jsconfig.json` in your `assets` directory with mapping of imports from running [js.Build](/hugo-pipes/js). This file is intended to help with intellisense/navigation inside code editors such as [VS Code](https://code.visualstudio.com/). Note that if you do not use `js.Build`, no file will be written. + +useResourceCacheWhen +: (`string`) When to use the resource file cache, one of `never`, `fallback`, or `always`. Applicable when transpiling Sass to CSS. Default is `fallback`. + +## Cache busters + +The `build.cachebusters` configuration option was added to support development using Tailwind 3.x's JIT compiler where a `build` configuration may look like this: + +{{< code-toggle file=hugo >}} +[build] + [build.buildStats] + enable = true + [[build.cachebusters]] + source = "assets/watching/hugo_stats\\.json" + target = "styles\\.css" + [[build.cachebusters]] + source = "(postcss|tailwind)\\.config\\.js" + target = "css" + [[build.cachebusters]] + source = "assets/.*\\.(js|ts|jsx|tsx)" + target = "js" + [[build.cachebusters]] + source = "assets/.*\\.(.*)$" + target = "$1" +{{< /code-toggle >}} + +When `buildStats` is enabled, Hugo writes a `hugo_stats.json` file on each build with HTML classes etc. that's used in the rendered output. Changes to this file will trigger a rebuild of the `styles.css` file. You also need to add `hugo_stats.json` to Hugo's server watcher. See [Hugo Starter Tailwind Basic](https://github.com/bep/hugo-starter-tailwind-basic) for a running example. + +source +: (`string`) A [regular expression](g) matching file(s) relative to one of the virtual component directories in Hugo, typically `assets/...`. + +target +: (`string`) A [regular expression](g) matching the keys in the resource cache that should be expired when `source` changes. You can use the matching regexp groups from `source` in the expression, e.g. `$1`. + +## Build stats + +{{< code-toggle config=build.buildStats />}} + +enable +: (`bool`) Whether to create a `hugo_stats.json` file in the root of your project. This file contains arrays of the `class` attributes, `id` attributes, and tags of every HTML element within your published site. Use this file as data source when [removing unused CSS] from your site. This process is also known as pruning, purging, or tree shaking. Default is `false`. + +[removing unused CSS]: /functions/resources/postprocess/ + +disableIDs +: (`bool`) Whether to exclude `id` attributes. Default is `false`. + +disableTags +: (`bool`) Whether to exclude element tags. Default is `false`. + +disableClasses +: (`bool`) Whether to exclude `class` attributes. Default is `false`. + +> [!note] +> Given that CSS purging is typically limited to production builds, place the `buildStats` object below [`config/production`]. +> +> 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. + +[`config/production`]: /configuration/introduction/#configuration-directory diff --git a/content/en/configuration/caches.md b/content/en/configuration/caches.md new file mode 100644 index 000000000..03b499dcb --- /dev/null +++ b/content/en/configuration/caches.md @@ -0,0 +1,30 @@ +--- +title: Configure file caches +linkTitle: Caches +description: Configure file caches. +categories: [] +keywords: [] +--- + +This is the default configuration: + +{{< code-toggle config=caches />}} + +## Keys + +dir +: (`string`) The absolute file system path where the cached files will be stored. You can begin the path with the `:cacheDir` or `:resourceDir` token. These tokens will be replaced with the actual configured cache directory and resource directory paths, respectively. + +maxAge +: (`string`) The [duration](g) a cached entry remains valid before being evicted. A value of `0` disables the cache. A value of `-1` means the cache entry never expires (the default). + +## Tokens + +`:cacheDir` +: (`string`) The designated cache directory. See [details](/configuration/all/#cachedir). + +`:project` +: (`string`) The base directory name of the current Hugo project. By default, this ensures each project has isolated file caches, so running `hugo --gc` will only affect the current project's cache and not those of other Hugo projects on the same machine. + +`:resourceDir` +: (`string`) The designated directory for caching output from [asset pipelines](g). See [details](/configuration/all/#resourcedir). diff --git a/content/en/configuration/cascade.md b/content/en/configuration/cascade.md new file mode 100644 index 000000000..d91996301 --- /dev/null +++ b/content/en/configuration/cascade.md @@ -0,0 +1,77 @@ +--- +title: Configure cascade +linkTitle: Cascade +description: Configure cascade. +categories: [] +keywords: [] +--- + +You can configure your site to cascade front matter values to the home page and any of its descendants. However, this cascading will be prevented if the descendant already defines the field, or if a closer ancestor [node](g) has already cascaded a value for the same field through its front matter's `cascade` key. + +> [!note] +> You can also configure cascading behavior within a page's front matter. See [details]. + +For example, to cascade a "color" parameter to the home page and all its descendants: + +{{< code-toggle file=hugo >}} +title = 'Home' +[cascade.params] +color = 'red' +{{< /code-toggle >}} + +## 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: + +[^1]: The `_target` alias for `target` is deprecated and will be removed in a future release. + +{{< code-toggle file=hugo >}} +[cascade.params] +color = 'red' +[cascade.target] +path = '{/articles,/articles/**}' +{{< /code-toggle >}} + +Use any combination of these keywords to target pages and/or environments: + +environment +: (`string`) A [glob](g) pattern matching the build [environment](g). For example: `{staging,production}`. + +kind +: (`string`) A [glob](g) pattern matching the [page kind](g). For example: ` {taxonomy,term}`. + +lang +: (`string`) A [glob](g) pattern matching the [page language]. For example: `{en,de}`. + +path +: (`string`) A [glob](g) pattern matching the page's [logical path](g). For example: `{/books,/books/**}`. + +## Array + +Define an array of cascade parameters to apply different values to different targets. For example: + +{{< code-toggle file=hugo >}} +[[cascade]] +[cascade.params] +color = 'red' +[cascade.target] +path = '{/books/**}' +kind = 'page' +lang = '{en,de}' +[[cascade]] +[cascade.params] +color = 'blue' +[cascade.target] +path = '{/films/**}' +kind = 'page' +environment = 'production' +{{< /code-toggle >}} + +[details]: /content-management/front-matter/#cascade-1 +[page language]: /methods/page/language/ diff --git a/content/en/configuration/content-types.md b/content/en/configuration/content-types.md new file mode 100644 index 000000000..4c5b5a23b --- /dev/null +++ b/content/en/configuration/content-types.md @@ -0,0 +1,63 @@ +--- +title: Configure content types +linkTitle: Content types +description: Configure content types. +categories: [] +keywords: [] +--- + +{{< new-in 0.144.0 />}} + +Hugo supports six [content formats](g): + +{{% include "/_common/content-format-table.md" %}} + +These can be used as either page content or [page resources](g). When used as page resources, their [resource type](g) is `page`. + +Consider this example of a [page bundle](g): + +```text +content/ +└── example/ + ├── index.md <-- content + ├── a.adoc <-- resource (resource type: page) + ├── b.html <-- resource (resource type: page) + ├── c.md <-- resource (resource type: page) + ├── d.org <-- resource (resource type: page) + ├── e.pdc <-- resource (resource type: page) + ├── f.rst <-- resource (resource type: page) + ├── g.jpg <-- resource (resource type: image) + └── h.png <-- resource (resource type: image) +``` + +The `index.md` file is the page's content, while the other files are page resources. Files `a` through `f` are of resource type `page`, while `g` and `h` are of resource type `image`. + +When you build a site, Hugo does not publish page resources having a resource type of `page`. For example, this is the result of building the site above: + +```text +public/ +├── example/ +│ ├── g.jpg +│ ├── h.png +│ └── index.html +└── index.html +``` + +The default behavior is appropriate in most cases. Given that page resources containing markup are typically intended for inclusion in the main content, publishing them independently is generally undesirable. + +The default behavior is determined by the `contentTypes` configuration: + +{{< code-toggle config=contentTypes />}} + +In this default configuration, page resources with those media types will have a resource type of `page`, and will not be automatically published. To change the resource type assignment from `page` to `text` for a given media type, remove the corresponding entry from the list. + +For example, to set the resource type of `text/html` files to `text`, thereby enabling automatic publication, remove the `text/html` entry: + +{{< code-toggle file=hugo >}} +contentTypes: + text/asciidoc: {} + text/markdown: {} + text/org: {} + text/pandoc: {} + text/rst: {} +{{< /code-toggle >}} diff --git a/content/en/configuration/deployment.md b/content/en/configuration/deployment.md new file mode 100644 index 000000000..fad50da63 --- /dev/null +++ b/content/en/configuration/deployment.md @@ -0,0 +1,159 @@ +--- +title: Configure deployment +linkTitle: Deployment +description: Configure deployments to Amazon S3, Azure Blob Storage, or Google Cloud Storage. +categories: [] +keywords: [] +--- + +> [!note] +> This configuration is only relevant when running `hugo deploy`. See [details](/host-and-deploy/deploy-with-hugo-deploy/). + +## Top-level options + +These settings control the overall behavior of the deployment process. This is the default configuration: + +{{< code-toggle file=hugo config=deployment />}} + +confirm +: (`bool`) Whether to prompt for confirmation before deploying. Default is `false`. + +dryRun +: (`bool`) Whether to simulate the deployment without any remote changes. Default is `false`. + +force +: (`bool`) Whether to re-upload all files. Default is `false`. + +invalidateCDN +: (`bool`) Whether to invalidate the CDN cache listed in the deployment target. Default is `true`. + +maxDeletes +: (`int`) The maximum number of files to delete, or `-1` to disable. Default is `256`. + +matchers +: (`[]*Matcher`) A slice of [matchers](#matchers-1). + +order +: (`[]string`) An ordered slice of [regular expressions](g) that determines upload priority (left to right). Files not matching any expression are uploaded last in an arbitrary order. + +target +: (`string`) The target deployment [`name`](#name). Defaults to the first target. + +targets +: (`[]*Target`) A slice of [targets](#targets-1). + +workers +: (`int`) The number of concurrent workers to use when uploading files. Default is `10`. + +## Targets + +A target represents a deployment target such as "staging" or "production". + +cloudFrontDistributionID +: (`string`) The CloudFront Distribution ID, applicable if you are using the Amazon Web Services CloudFront CDN. Hugo will invalidate the CDN when deploying this target. + +exclude +: (`string`) A [glob](g) pattern matching files to exclude when deploying to this target. Local files failing the include/exclude filters are not uploaded, and remote files failing these filters are not deleted. + +googleCloudCDNOrigin +: (`string`) The Google Cloud project and CDN origin to invalidate when deploying this target, specified as `/`. + +include +: (`string`) A [glob](g) pattern matching files to include when deploying to this target. Local files failing the include/exclude filters are not uploaded, and remote files failing these filters are not deleted. + +name +: (`string`) An arbitrary name for this target. + +stripIndexHTML +: (`bool`) Whether to map files named `/index.html` to `` on the remote (except for the root `index.html`). This is useful for key-value cloud storage (e.g., Amazon S3, Google Cloud Storage, Azure Blob Storage) to align canonical URLs with object keys. Default is `false`. + +url +: (`string`) The [destination URL](#destination-urls) for deployment. + +## Matchers + +A Matcher represents a configuration to be applied to files whose paths match +the specified pattern. + +cacheControl +: (`string`) The caching attributes to use when serving the blob. See [details][cacheControl]. + +contentEncoding +: (`string`) The encoding used for the blob's content, if any. See [details][contentEncoding]. + +contentType +: (`string`) The media type of the blob being written. See [details][contentType]. + +force +: (`bool`) Whether matching files should be re-uploaded. Useful when other route-determined metadata (e.g., `contentType`) has changed. Default is `false`. + +gzip +: (`bool`) Whether the file should be gzipped before upload. If so, the `ContentEncoding` field will automatically be set to `gzip`. Default is `false`. + +pattern +: (`string`) A [regular expression](g) used to match paths. Paths are converted to use forward slashes (`/`) before matching. + +[cacheControl]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cache-Control +[contentEncoding]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Encoding +[contentType]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Type + +## Destination URLs + +Service|URL example +:--|:-- +Amazon Simple Storage Service (S3)|`s3://my-bucket?region=us-west-1` +Azure Blob Storage|`azblob://my-container` +Google Cloud Storage (GCS)|`gs://my-bucket` + +With Google Cloud Storage you can target a subdirectory: + +```text +gs://my-bucket?prefix=a/subdirectory +``` + +You can also to deploy to storage servers compatible with Amazon S3 such as: + +- [Ceph] +- [MinIO] +- [SeaweedFS] + +[Ceph]: https://ceph.com/ +[Minio]: https://www.minio.io/ +[SeaweedFS]: https://github.com/chrislusf/seaweedfs + +For example, the `url` for a MinIO deployment target might resemble this: + +```text +s3://my-bucket?endpoint=https://my.minio.instance&awssdk=v2&use_path_style=true&disable_https=false +``` + +## Example + +{{< code-toggle file=hugo >}} +[deployment] + order = ['.jpg$', '.gif$'] + [[deployment.matchers]] + cacheControl = 'max-age=31536000, no-transform, public' + gzip = true + pattern = '^.+\.(js|css|svg|ttf)$' + [[deployment.matchers]] + cacheControl = 'max-age=31536000, no-transform, public' + gzip = false + pattern = '^.+\.(png|jpg)$' + [[deployment.matchers]] + contentType = 'application/xml' + gzip = true + pattern = '^sitemap\.xml$' + [[deployment.matchers]] + gzip = true + pattern = '^.+\.(html|xml|json)$' + [[deployment.targets]] + url = 's3://my_production_bucket?region=us-west-1' + cloudFrontDistributionID = 'E1234567890ABCDEF0' + exclude = '**.{heic,psd}' + name = 'production' + [[deployment.targets]] + url = 's3://my_staging_bucket?region=us-west-1' + exclude = '**.{heic,psd}' + name = 'staging' +{{< /code-toggle >}} diff --git a/content/en/configuration/front-matter.md b/content/en/configuration/front-matter.md new file mode 100644 index 000000000..9f51b8a5a --- /dev/null +++ b/content/en/configuration/front-matter.md @@ -0,0 +1,91 @@ +--- +title: Configure front matter +linkTitle: Front matter +description: Configure front matter. +categories: [] +keywords: [] +--- + +## Dates + +There are four methods on a `Page` object that return a date. + +Method|Description +:--|:-- +[`Date`]|Returns the date of the given page. +[`ExpiryDate`]|Returns the expiry date of the given page. +[`Lastmod`]|Returns the last modification date of the given page. +[`PublishDate`]|Returns the publish date of the given page. + +[`Date`]: /methods/page/date +[`ExpiryDate`]: /methods/page/expirydate +[`Lastmod`]: /methods/page/lastmod +[`PublishDate`]: /methods/page/publishdate + +Hugo determines the values to return based on this configuration: + +{{< code-toggle config=frontmatter />}} + +The `ExpiryDate` method, for example, returns the `expirydate` value if it exists, otherwise it returns `unpublishdate`. + +You can also use custom date parameters: + +{{< code-toggle file=hugo >}} +[frontmatter] +date = ["myDate", "date"] +{{< /code-toggle >}} + +In the example above, the `Date` method returns the `myDate` value if it exists, otherwise it returns `date`. + +To fall back to the default sequence of dates, use the `:default` token: + +{{< code-toggle file=hugo >}} +[frontmatter] +date = ["myDate", ":default"] +{{< /code-toggle >}} + +In the example above, the `Date` method returns the `myDate` value if it exists, otherwise it returns the first valid date from `date`, `publishdate`, `pubdate`, `published`, `lastmod`, and `modified`. + +## Aliases + +Some of the front matter fields have aliases. + +Front matter field|Aliases +:--|:-- +`expiryDate`|`unpublishdate` +`lastmod`|`modified` +`publishDate`|`pubdate`, `published` + +The default front matter configuration includes these aliases. + +## Tokens + +Hugo provides several [tokens](g) to assist with front matter configuration. + +Token|Description +:--|:-- +`:default`|The default ordered sequence of date fields. +`:fileModTime`|The file's last modification timestamp. +`:filename`|The date from the file name, if present. +`:git`|The Git author date for the file's last revision. + +When Hugo extracts a date from a file name, it uses the rest of the file name to generate the page's [`slug`], but only if a slug isn't already specified in the page's front matter. For example, given the name `2025-02-01-article.md`, Hugo will set the `date` to `2025-02-01` and the `slug` to `article`. + +[`slug`]: /content-management/front-matter/#slug + +To enable access to the Git author date, set [`enableGitInfo`] to `true`, or use\ +the `--enableGitInfo` flag when building your site. + +[`enableGitInfo`]: /configuration/all/#enablegitinfo + +Consider this example: + +{{< code-toggle file=hugo >}} +[frontmatter] +date = [':filename', ':default'] +lastmod = ['lastmod', ':fileModTime'] +{{< /code-toggle >}} + +To determine `date`, Hugo tries to extract the date from the file name, falling back to the default ordered sequence of date fields. + +To determine `lastmod`, Hugo looks for a `lastmod` field in front matter, falling back to the file's last modification timestamp. diff --git a/content/en/configuration/http-cache.md b/content/en/configuration/http-cache.md new file mode 100644 index 000000000..788d22a08 --- /dev/null +++ b/content/en/configuration/http-cache.md @@ -0,0 +1,107 @@ +--- +title: Configure the HTTP cache +linkTitle: HTTP cache +description: Configure the HTTP cache. +categories: [] +keywords: [] +--- + +> [!note] +> This configuration is only relevant when using the [`resources.GetRemote`] function. + +## Layered caching + +Hugo employs a layered caching system. + +```goat {.w-40} + .-----------. +| dynacache | + '-----+-----' + | + v + .----------. +| HTTP cache | + '-----+----' + | + v + .----------. +| file cache | + '-----+----' +``` + +Dynacache +: An in-memory cache employing a Least Recently Used (LRU) eviction policy. Entries are removed from the cache when changes occur, when they match [cache-busting] patterns, or under low-memory conditions. + +HTTP Cache +: An HTTP cache for remote resources as specified in [RFC 9111]. Optimal performance is achieved when resources include appropriate HTTP cache headers. The HTTP cache utilizes the file cache for storage and retrieval of cached resources. + +File cache +: See [configure file caches]. + +The HTTP cache involves two key aspects: determining which content to cache (the caching process itself) and defining the frequency with which to check for updates (the polling strategy). + +## HTTP caching + +The HTTP cache behavior is defined for a configured set of resources. Stale resources will be refreshed from the file cache, even if their configured Time-To-Live (TTL) has not expired. If HTTP caching is disabled for a resource, Hugo will bypass the cache and access the file directly. + +The default configuration disables everything: + +{{< code-toggle file=hugo >}} +[HTTPCache.cache.for] +excludes = ['**'] +includes = [] +{{< /code-toggle >}} + +cache.for.excludes +: (`string`) A list of [glob](g) patterns to exclude from caching. + +cache.for.includes +: (`string`) A list of [glob](g) patterns to cache. + +## HTTP polling + +Polling is used in watch mode (e.g., `hugo server`) to detect changes in remote resources. Polling can be enabled even if HTTP caching is disabled. Detected changes trigger a rebuild of pages using the affected resource. Polling can be disabled for specific resources, typically those known to be static. + +The default configuration disables everything: + +{{< code-toggle file=hugo >}} +[[HTTPCache.polls]] +disable = true +high = '0s' +low = '0s' +[HTTPCache.polls.for] +includes = ['**'] +excludes = [] +{{< /code-toggle >}} + +polls +: A slice of polling configurations. + +polls.disable +: (`bool`) Whether to disable polling for this configuration. + +polls.low +: (`string`) The minimum polling interval expressed as a [duration](g). This is used after a recent change and gradually increases towards `polls.high`. + +polls.high +: (`string`) The maximum polling interval expressed as a [duration](g). This is used when the resource is considered stable. + +polls.for.excludes +: (`string`) A list of [glob](g) patterns to exclude from polling for this configuration. + +polls.for.includes +: (`string`) A list of [glob](g) patterns to include in polling for this configuration. + +## Behavior + +Polling and HTTP caching interact as follows: + +- With polling enabled, rebuilds are triggered only by actual changes, detected via `eTag` changes (Hugo generates an MD5 hash if the server doesn't provide one). +- If polling is enabled but HTTP caching is disabled, the remote is checked for changes only after the file cache's TTL expires (e.g., a `maxAge` of `10h` with a `1s` polling interval is inefficient). +- If both polling and HTTP caching are enabled, changes are checked for even before the file cache's TTL expires. Cached `eTag` and `last-modified` values are sent in `if-none-match` and `if-modified-since` headers, respectively, and a cached response is returned on HTTP [304]. + +[`resources.GetRemote`]: /functions/resources/getremote/ +[304]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/304 +[cache-busting]: /configuration/build/#cache-busters +[configure file caches]: /configuration/caches/ +[RFC 9111]: https://datatracker.ietf.org/doc/html/rfc9111 diff --git a/content/en/configuration/imaging.md b/content/en/configuration/imaging.md new file mode 100644 index 000000000..13ecf9c26 --- /dev/null +++ b/content/en/configuration/imaging.md @@ -0,0 +1,69 @@ +--- +title: Configure imaging +linkTitle: Imaging +description: Configure imaging. +categories: [] +keywords: [] +--- + +## Processing options + +These are the default settings for processing images: + +{{< code-toggle file=hugo >}} +[imaging] +anchor = 'Smart' +bgColor = '#ffffff' +hint = 'photo' +quality = 75 +resampleFilter = 'box' +{{< /code-toggle >}} + +anchor +: (`string`) When using the [`Crop`] or [`Fill`] method, the anchor determines the placement of the crop box. One of `TopLeft`, `Top`, `TopRight`, `Left`, `Center`, `Right`, `BottomLeft`, `Bottom`, `BottomRight`, or `Smart`. Default is `Smart`. + +bgColor +: (`string`) The background color of the resulting image. Applicable when converting from a format that supports transparency to a format that does not support transparency, for example, when converting from PNG to JPEG. Expressed as an RGB [hexadecimal] value. Default is `#ffffff`. + +[hexadecimal]: https://developer.mozilla.org/en-US/docs/Web/CSS/hex-color + +hint +: (`string`) Applicable to WebP images, this option corresponds to a set of predefined encoding parameters. One of `drawing`, `icon`, `photo`, `picture`, or `text`. Default is `photo`. See [details](/content-management/image-processing/#hint). + +quality +: (`int`) Applicable to JPEG and WebP images, this value determines the quality of the converted image. Higher values produce better quality images, while lower values produce smaller files. Set this value to a whole number between `1` and `100`, inclusive. Default is `75`. + +resampleFilter +: (`string`) The resampling filter used when resizing an image. Default is `box`. See [details](/content-management/image-processing/#resampling-filter) + +## EXIF data + +These are the default settings for extracting EXIF data from images: + +{{< code-toggle file=hugo >}} +[imaging.exif] +includeFields = "" +excludeFields = "" +disableDate = false +disableLatLong = false +{{< /code-toggle >}} + +disableDate +: (`bool`) Whether to disable extraction of the image creation date/time. Default is `false`. + +disableLatLong +: (`bool`) Whether to disable extraction of the GPS latitude and longitude. Default is `false`. + +excludeFields +: (`string`) A [regular expression](g) matching the tags to exclude when extracting EXIF data. + +includeFields +: (`string`) A [regular expression](g) matching the tags to include when extracting EXIF data. To include all available tags, set this value to `".*"`. + +> [!note] +> To improve performance and decrease cache size, Hugo excludes the following tags: `ColorSpace`, `Contrast`, `Exif`, `Exposure[M|P|B]`, `Flash`, `GPS`, `JPEG`, `Metering`, `Resolution`, `Saturation`, `Sensing`, `Sharp`, and `WhiteBalance`. +> +> To control tag availability, change the `excludeFields` or `includeFields` settings as described above. + +[`Crop`]: /methods/resource/crop/ +[`Fill`]: /methods/resource/fill/ diff --git a/content/en/configuration/introduction.md b/content/en/configuration/introduction.md new file mode 100644 index 000000000..121a483c4 --- /dev/null +++ b/content/en/configuration/introduction.md @@ -0,0 +1,284 @@ +--- +title: Introduction +description: Configure your site using files, directories, and environment variables. +categories: [] +keywords: [] +weight: 10 +--- + +## Sensible defaults + +Hugo offers many configuration options, but its defaults are often sufficient. A new site requires only these settings: + +{{< code-toggle file=hugo >}} +baseURL = 'https://example.org/' +languageCode = 'en-us' +title = 'My New Hugo Site' +{{< /code-toggle >}} + +Only define settings that deviate from the defaults. A smaller configuration file is easier to read, understand, and debug. Keep your configuration concise. + +> [!note] +> The best configuration file is a short configuration file. + +## 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. + +```text +my-project/ +└── hugo.toml +``` + +> [!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`. + +A simple example: + +{{< code-toggle file=hugo >}} +baseURL = 'https://example.org/' +languageCode = 'en-us' +title = 'ABC Widgets, Inc.' +[params] +subtitle = 'The Best Widgets on Earth' +[params.contact] +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: + +```sh +hugo --config other.toml +``` + +Combine two or more configuration files, with left-to-right precedence: + +```sh +hugo --config a.toml,b.yaml,c.json +``` + +> [!note] +> See the specifications for each file format: [TOML], [YAML], and [JSON]. + +## Configuration directory + +Instead of a single site configuration file, split your configuration by [environment](g), root configuration key, and language. For example: + +```text +my-project/ +└── config/ + ├── _default/ + │ ├── hugo.toml + │ ├── menus.en.toml + │ ├── menus.de.toml + │ └── params.toml + └── production/ + └── params.toml +``` + +The root configuration keys are {{< root-configuration-keys >}}. + +### Omit the root key + +When splitting the configuration by root key, omit the root key in the component file. For example, these are equivalent: + +{{< code-toggle file=config/_default/hugo >}} +[params] +foo = 'bar' +{{< /code-toggle >}} + +{{< code-toggle file=config/_default/params >}} +foo = 'bar' +{{< /code-toggle >}} + +### Recursive parsing + +Hugo parses the `config` directory recursively, allowing you to organize the files into subdirectories. For example: + +```text +my-project/ +└── config/ + └── _default/ + ├── navigation/ + │ ├── menus.de.toml + │ └── menus.en.toml + └── hugo.toml +``` + +### Example + +```text +my-project/ +└── config/ + ├── _default/ + │ ├── hugo.toml + │ ├── menus.en.toml + │ ├── menus.de.toml + │ └── params.toml + ├── production/ + │ ├── hugo.toml + │ └── params.toml + └── staging/ + ├── hugo.toml + └── 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. + +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: + +{{< code-toggle file=hugo >}} +[services.googleAnalytics] +ID = 'G-XXXXXXXXX' +{{< /code-toggle >}} + +Now consider the following scenario: + +1. You don't want to load the analytics code when running `hugo server`. +1. You want to use different Google tag IDs for your production and staging environments. For example: + - `G-PPPPPPPPP` for production + - `G-SSSSSSSSS` for staging + +To satisfy these requirements, configure your site as follows: + +1. `config/_default/hugo.toml` + - Exclude the `services.googleAnalytics` section. This will prevent loading of the analytics code when you run `hugo server`. + - By default, Hugo sets its `environment` to `development` when running `hugo server`. In the absence of a `config/development` directory, Hugo uses the `config/_default` directory. +1. `config/production/hugo.toml` + - Include this section only: + + {{< code-toggle file=hugo >}} + [services.googleAnalytics] + ID = 'G-PPPPPPPPP' + {{< /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. + +1. `config/staging/hugo.toml` + + - Include this section only: + + {{< code-toggle file=hugo >}} + [services.googleAnalytics] + ID = 'G-SSSSSSSSS' + {{< /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. + +## Merge configuration settings + +Hugo merges configuration settings from themes and modules, prioritizing the project's own settings. Given this simplified project structure with two themes: + +```text +project/ +├── themes/ +│ ├── theme-a/ +│ │ └── hugo.toml +│ └── theme-b/ +│ └── hugo.toml +└── hugo.toml +``` + +and this project-level configuration: + +{{< code-toggle file=hugo >}} +baseURL = 'https://example.org/' +languageCode = 'en-us' +title = 'My New Hugo Site' +theme = ['theme-a','theme-b'] +{{< /code-toggle >}} + +Hugo merges settings in this order: + +1. Project configuration (`hugo.toml` in the project root) +1. `theme-a` configuration +1. `theme-b` configuration + +The `_merge` setting within each top-level configuration key controls _which_ settings are merged and _how_ they are merged. + +The value for `_merge` can be one of: + +none +: No merge. + +shallow +: Only add values for new keys. + +deep +: Add values for new keys, merge existing. + +Note that you don't need to be so verbose as in the default setup below; a `_merge` value higher up will be inherited if not set. + +{{< code-toggle file=hugo dataKey="config_helpers.mergeStrategy" skipHeader=true />}} + +## Environment variables + +You can also configure settings using operating system environment variables: + +```sh +export HUGO_BASEURL=https://example.org/ +export HUGO_ENABLEGITINFO=true +export HUGO_ENVIRONMENT=staging +hugo +``` + +The above sets the [`baseURL`], [`enableGitInfo`], and [`environment`] configuration options and then builds your site. + +> [!note] +> An environment variable takes precedence over the values set in the configuration file. This means that if you set a configuration value with both an environment variable and in the configuration file, the value in the environment variable will be used. + +Environment variables simplify configuration for [CI/CD](g) deployments like GitHub Pages, GitLab Pages, and Netlify by allowing you to set values directly within their respective configuration and workflow files. + +> [!note] +> Environment variable names must be prefixed with `HUGO_`. +> +> To set custom site parameters, prefix the name with `HUGO_PARAMS_`. + +For snake_case variable names, the standard `HUGO_` prefix won't work. Hugo infers the delimiter from the first character following `HUGO`. This allows for variations like `HUGOxPARAMSxAPI_KEY=abcdefgh` using any [permitted delimiter]. + +In addition to configuring standard settings, environment variables may be used to override default values for certain internal settings: + +DART_SASS_BINARY +: (`string`) The absolute path to the Dart Sass executable. By default, Hugo searches for the executable in each of the paths in the `PATH` environment variable. + +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 +: {{< new-in 0.123.0 />}} +: (`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 The `HUGO_MEMORYLIMIT` is a “best effort” setting. Don't expect Hugo to build a million pages with only 1 GB 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. + +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: + +```sh +hugo config +``` + +Display a specific configuration setting with: + +```sh +hugo config | grep [key] +``` + +Display the configured file mounts with: + +```sh +hugo config mounts +``` + +[`baseURL`]: /configuration/all#baseurl +[`enableGitInfo`]: /configuration/all#enablegitinfo +[`environment`]: /configuration/all#environment +[Google tag ID]: https://support.google.com/tagmanager/answer/12326985?hl=en +[JSON]: https://datatracker.ietf.org/doc/html/rfc7159 +[permitted delimiter]: https://pubs.opengroup.org/onlinepubs/000095399/basedefs/xbd_chap08.html +[TOML]: https://toml.io/en/latest +[YAML]: https://yaml.org/spec/ diff --git a/content/en/configuration/languages.md b/content/en/configuration/languages.md new file mode 100644 index 000000000..540cfd34f --- /dev/null +++ b/content/en/configuration/languages.md @@ -0,0 +1,193 @@ +--- +title: Configure languages +linkTitle: Languages +description: Configure the languages in your multilingual site. +categories: [] +keywords: [] +--- + +## Base settings + +Configure the following base settings within the site's root configuration: + +{{< code-toggle file=hugo >}} +defaultContentLanguage = 'en' +defaultContentLanguageInSubdir = false +disableDefaultLanguageRedirect = false +disableLanguages = [] +{{< /code-toggle >}} + +defaultContentLanguage +: (`string`) The project's default language key, conforming to the syntax described in [RFC 5646]. This value must match one of the defined [language keys](#language-keys). Default is `en`. + +defaultContentLanguageInSubdir +: (`bool`) Whether to publish the default language site to a subdirectory matching the `defaultContentLanguage`. Default is `false`. + +disableDefaultLanguageRedirect +: {{< new-in 0.140.0 />}} +: (`bool`) Whether to disable generation of the alias redirect to the default language when `DefaultContentLanguageInSubdir` is `true`. Default is `false`. + +disableLanguages +: (`[]string]`) A slice of language keys representing the languages to disable during the build process. Although this is functional, consider using the [`disabled`](#disabled) key under each language instead. + +## Language settings + +Configure each language under the `languages` key: + +{{< code-toggle config=languages />}} + +In the above, `en` is the [language key](#language-keys). + +disabled +: (`bool`) Whether to disable this language when building the site. Default is `false`. + +languageCode +: (`string`) The language tag as described in [RFC 5646]. This value does not affect localization or URLs. Hugo uses this value to populate: + + - The `lang` attribute of the `html` element in the [embedded alias template] + - The `language` element in the [embedded RSS template] + - The `locale` property in the [embedded OpenGraph template] + + 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. + +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. + +title +: (`string`) The site title for this language. Access this value from a template using the [`Title`] method on a `Site` object. + +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. + +## Localized settings + +Some configuration settings can be defined separately for each language. For example: + +{{< code-toggle file=hugo >}} +[languages.en] +languageCode = 'en-US' +languageName = 'English' +weight = 1 +title = 'Project Documentation' +timeZone = 'America/New_York' +[languages.en.pagination] +path = 'page' +[languages.en.params] +subtitle = 'Reference, Tutorials, and Explanations' +{{< /code-toggle >}} + +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. + +## Language keys + +Language keys must conform to the syntax described in [RFC 5646]. For example: + +{{< code-toggle file=hugo >}} +defaultContentLanguage = 'de' +[languages.de] + weight = 1 +[languages.en-US] + weight = 2 +[languages.pt-BR] + weight = 3 +{{< /code-toggle >}} + +Artificial languages with private use subtags as defined in [RFC 5646 § 2.2.7] are also supported. Omit the `art-x-` prefix from the language key. For example: + +{{< code-toggle file=hugo >}} +defaultContentLanguage = 'en' +[languages.en] +weight = 1 +[languages.hugolang] +weight = 2 +{{< /code-toggle >}} + +> [!note] +> Private use subtags must not exceed 8 alphanumeric characters. + +## Example + +{{< code-toggle file=hugo >}} +defaultContentLanguage = 'de' +defaultContentLanguageInSubdir = true +disableDefaultLanguageRedirect = false + +[languages.de] +contentDir = 'content/de' +disabled = false +languageCode = 'de-DE' +languageDirection = 'ltr' +languageName = 'Deutsch' +title = 'Projekt Dokumentation' +weight = 1 + +[languages.de.params] +subtitle = 'Referenz, Tutorials und Erklärungen' + +[languages.en] +contentDir = 'content/en' +disabled = false +languageCode = 'en-US' +languageDirection = 'ltr' +languageName = 'English' +title = 'Project Documentation' +weight = 2 + +[languages.en.params] +subtitle = 'Reference, Tutorials, and Explanations' +{{< /code-toggle >}} + +> [!note] +> In the example above, omit `contentDir` if [translating by file name]. + +## Multihost + +Hugo supports multiple languages in a multihost configuration. This means you can configure a `baseURL` per `language`. + +> [!note] +> If you define a `baseURL` for one language, you must define a unique `baseURL` for all languages. + +For example: + +{{< code-toggle file=hugo >}} +defaultContentLanguage = 'fr' +[languages] + [languages.en] + baseURL = 'https://en.example.org/' + languageName = 'English' + title = 'In English' + weight = 2 + [languages.fr] + baseURL = 'https://fr.example.org' + languageName = 'Français' + title = 'En Français' + weight = 1 +{{}} + +With the above, Hugo publishes two sites, each with their own root: + +```text +public +├── en +└── fr +``` + +[`dir`]: https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/dir +[`Language.LanguageCode`]: /methods/site/language/#languagecode +[`Language.LanguageDirection`]: /methods/site/language/#languagedirection +[`Language.LanguageName`]: /methods/site/language/#languagename +[`Language.Weight`]: /methods/site/language/#weight +[`Title`]: /methods/site/title/ +[embedded alias template]: {{% eturl alias %}} +[embedded OpenGraph template]: {{% eturl opengraph %}} +[embedded RSS template]: {{% eturl rss %}} +[RFC 5646]: https://datatracker.ietf.org/doc/html/rfc5646#section-2.1 +[RFC 5646 § 2.2.7]: https://datatracker.ietf.org/doc/html/rfc5646#section-2.2.7 +[translating by file name]: /content-management/multilingual/#translation-by-file-name diff --git a/content/en/configuration/markup.md b/content/en/configuration/markup.md new file mode 100644 index 000000000..b6135cee5 --- /dev/null +++ b/content/en/configuration/markup.md @@ -0,0 +1,341 @@ +--- +title: Configure markup +linkTitle: Markup +description: Configure markup. +categories: [] +keywords: [] +aliases: [/getting-started/configuration-markup/] +--- + +## Default handler + +In its default configuration, Hugo uses [Goldmark] to render Markdown to HTML. + +{{< code-toggle file=hugo >}} +[markup] +defaultMarkdownHandler = 'goldmark' +{{< /code-toggle >}} + +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. + +`defaultMarkdownHandler`|Renderer +:--|:-- +`asciidocext`|[AsciiDoc] +`goldmark`|[Goldmark] +`org`|[Emacs Org Mode] +`pandoc`|[Pandoc] +`rst`|[reStructuredText] + +To use AsciiDoc, Pandoc, or reStructuredText you must install the relevant renderer and update your [security policy]. + +> [!note] +> Unless you need a unique capability provided by one of the alternative Markdown handlers, we strongly recommend that you use the default setting. Goldmark is fast, well maintained, conforms to the [CommonMark] specification, and is compatible with [GitHub Flavored Markdown] (GFM). + +## Goldmark + +This is the default configuration for the Goldmark Markdown renderer: + +{{< code-toggle config=markup.goldmark />}} + +### Extensions + +The extensions below, excluding Extras and Passthrough, are enabled by default. + +Extension|Documentation|Enabled +:--|:--|:-: +`cjk`|[Goldmark Extensions: CJK]|:heavy_check_mark: +`definitionList`|[PHP Markdown Extra: Definition lists]|:heavy_check_mark: +`extras`|[Hugo Goldmark Extensions: Extras]|| +`footnote`|[PHP Markdown Extra: Footnotes]|:heavy_check_mark: +`linkify`|[GitHub Flavored Markdown: Autolinks]|:heavy_check_mark: +`passthrough`|[Hugo Goldmark Extensions: Passthrough]|| +`strikethrough`|[GitHub Flavored Markdown: Strikethrough]|:heavy_check_mark: +`table`|[GitHub Flavored Markdown: Tables]|:heavy_check_mark: +`taskList`|[GitHub Flavored Markdown: Task list items]|:heavy_check_mark: +`typographer`|[Goldmark Extensions: Typographer]|:heavy_check_mark: + +#### Extras + +{{< new-in 0.126.0 />}} + +Enable [deleted text], [inserted text], [mark text], [subscript], and [superscript] elements in Markdown. + +Element|Markdown|Rendered +:--|:--|:-- +Deleted text|`~~foo~~`|`foo` +Inserted text|`++bar++`|`bar` +Mark text|`==baz==`|`baz` +Subscript|`H~2~O`|`H2O` +Superscript|`1^st^`|`1st` + +To avoid a conflict when enabling the "subscript" feature of the Extras extension, if you want to render subscript and strikethrough text concurrently you must: + +1. Disable the Strikethrough extension +1. Enable the "deleted text" feature of the Extras extension + +For example: + +{{< code-toggle file=hugo >}} +[markup.goldmark.extensions] +strikethrough = false + +[markup.goldmark.extensions.extras.delete] +enable = true + +[markup.goldmark.extensions.extras.subscript] +enable = true +{{< /code-toggle >}} + +#### Passthrough + +{{< new-in 0.122.0 />}} + +Enable the Passthrough extension to include mathematical equations and expressions in Markdown using LaTeX markup. See [mathematics in Markdown] for details. + +#### Typographer + +The Typographer extension replaces certain character combinations with HTML entities as specified below: + +Markdown|Replaced by|Description +:--|:--|:-- +`...`|`…`|horizontal ellipsis +`'`|`’`|apostrophe +`--`|`–`|en dash +`---`|`—`|em dash +`«`|`«`|left angle quote +`“`|`“`|left double quote +`‘`|`‘`|left single quote +`»`|`»`|right angle quote +`”`|`”`|right double quote +`’`|`’`|right single quote + +### Settings explained + +Most of the Goldmark settings above are self-explanatory, but some require explanation. + +duplicateResourceFiles +: {{< new-in 0.123.0 />}} +: (`bool`) Whether to duplicate shared page resources for each language on multilingual single-host sites. See [multilingual page resources] for details. Default is `false`. + + > [!note] + > With multilingual single-host sites, setting this parameter to `false` will enable Hugo's [embedded link render hook] and [embedded image render hook]. This is the default configuration for multilingual single-host sites. + +parser.wrapStandAloneImageWithinParagraph +: (`bool`) Whether to wrap image elements without adjacent content within a `p` element when rendered. This is the default Markdown behavior. Set to `false` when using an [image render hook] to render standalone images as `figure` elements. Default is `true`. + +parser.autoDefinitionTermID +: {{< new-in 0.144.0 />}} +: (`bool`) Whether to automatically add `id` attributes to description list terms (i.e., `dt` elements). When `true`, the `id` attribute of each `dt` element is accessible through the [`Fragments.Identifiers`] method on a `Page` object. + +parser.autoHeadingID +: (`bool`) Whether to automatically add `id` attributes to headings (i.e., `h1`, `h2`, `h3`, `h4`, `h5`, and `h6` elements). + +parser.autoIDType +: (`string`) The strategy used to automatically generate `id` attributes, one of `github`, `github-ascii` or `blackfriday`. + + - `github` produces GitHub-compatible `id` attributes + - `github-ascii` drops any non-ASCII characters after accent normalization + - `blackfriday` produces `id` attributes compatible with the Blackfriday Markdown renderer + + This is also the strategy used by the [anchorize](/functions/urls/anchorize) template function. Default is `github`. + +parser.attribute.block +: (`bool`) Whether to enable [Markdown attributes] for block elements. Default is `false`. + +parser.attribute.title +: (`bool`) Whether to enable [Markdown attributes] for headings. Default is `true`. + +renderHooks.image.enableDefault +: {{< new-in 0.123.0 />}} +: (`bool`) Whether to enable the [embedded image render hook]. Default is `false`. + + > [!note] + > The embedded image render hook is automatically enabled for multilingual single-host sites if [duplication of shared page resources] is disabled. This is the default configuration for multilingual single-host sites. + +renderHooks.link.enableDefault +: {{< new-in 0.123.0 />}} +: (`bool`) Whether to enable the [embedded link render hook]. Default is `false`. + + > [!note] + > The embedded link render hook is automatically enabled for multilingual single-host sites if [duplication of shared page resources] is disabled. This is the default configuration for multilingual single-host sites. + +renderer.hardWraps +: (`bool`) Whether to replace newline characters within a paragraph with `br` elements. Default is `false`. + +renderer.unsafe +: (`bool`) Whether to render raw HTML mixed within Markdown. This is unsafe unless the content is under your control. Default is `false`. + +## AsciiDoc + +This is the default configuration for the AsciiDoc renderer: + +{{< code-toggle config=markup.asciidocExt />}} + +### Settings explained + +attributes +: (`map`) A map of key-value pairs, each a document attribute. See Asciidoctor's [attributes]. + +backend +: (`string`) The backend output file format. Default is `html5`. + +extensions +: (`string array`) An array of enabled extensions, one or more of `asciidoctor-html5s`, `asciidoctor-bibtex`, `asciidoctor-diagram`, `asciidoctor-interdoc-reftext`, `asciidoctor-katex`, `asciidoctor-latex`, `asciidoctor-mathematical`, or `asciidoctor-question`. + + > [!note] + > To mitigate security risks, entries in the extension array may not contain forward slashes (`/`), backslashes (`\`), or periods. Due to this restriction, extensions must be in Ruby's `$LOAD_PATH`. + +failureLevel +: (`string`) The minimum logging level that triggers a non-zero exit code (failure). Default is `fatal`. + +noHeaderOrFooter +: (`bool`) Whether to output an embeddable document, which excludes the header, the footer, and everything outside the body of the document. Default is `true`. + +preserveTOC +: (`bool`) Whether to preserve the table of contents (TOC) rendered by Asciidoctor. By default, to make the TOC compatible with existing themes, Hugo removes the TOC rendered by Asciidoctor. To render the TOC, use the [`TableOfContents`] method on a `Page` object in your templates. Default is `false`. + +safeMode +: (`string`) The safe mode level, one of `unsafe`, `safe`, `server`, or `secure`. Default is `unsafe`. + +sectionNumbers +: (`bool`) Whether to number each section title. Default is `false`. + +trace +: (`bool`) Whether to include backtrace information on errors. Default is `false`. + +verbose +: (`bool`) Whether to verbosely print processing information and configuration file checks to stderr. Default is `false`. + +workingFolderCurrent +: (`bool`) Whether to set the working directory to be the same as that of the AsciiDoc file being processed, allowing [includes] to work with relative paths. Set to `true` to render diagrams with the [asciidoctor-diagram] extension. Default is `false`. + +### Configuration example + +{{< code-toggle file=hugo >}} +[markup.asciidocExt] + extensions = ["asciidoctor-html5s", "asciidoctor-diagram"] + workingFolderCurrent = true + [markup.asciidocExt.attributes] + my-base-url = "https://example.com/" + my-attribute-name = "my value" +{{< /code-toggle >}} + +### Syntax highlighting + +Follow the steps below to enable syntax highlighting. + +#### Step 1 + +Set the `source-highlighter` attribute in your site configuration. For example: + +{{< code-toggle file=hugo >}} +[markup.asciidocExt.attributes] +source-highlighter = 'rouge' +{{< /code-toggle >}} + +#### Step 2 + +Generate the highlighter CSS. For example: + +```text +rougify style monokai.sublime > assets/css/syntax.css +``` + +#### Step 3 + +In your base template add a link to the CSS file: + +```go-html-template {file="layouts/_default/baseof.html"} + + ... + {{ with resources.Get "css/syntax.css" }} + + {{ end }} + ... + +``` + +Then add the code to be highlighted to your markup: + +```text +[#hello,ruby] +---- +require 'sinatra' + +get '/hi' do + "Hello World!" +end +---- +``` + +### Troubleshooting + +Run `hugo --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 -] ... +``` + +## Highlight + +This is the default configuration. + +{{< code-toggle config=markup.highlight />}} + +{{% include "/_common/syntax-highlighting-options.md" %}} + +## Table of contents + +This is the default configuration for the table of contents, applicable to Goldmark and Asciidoctor: + +{{< code-toggle config=markup.tableOfContents />}} + +startLevel +: (`int`) Heading levels less than this value will be excluded from the table of contents. For example, to exclude `h1` elements from the table of contents, set this value to `2`. Default is `2`. + +endLevel +: (`int`) Heading levels greater than this value will be excluded from the table of contents. For example, to exclude `h4`, `h5`, and `h6` elements from the table of contents, set this value to `3`. Default is `3`. + +ordered +: (`bool`) Whether to generates an ordered list instead of an unordered list. Default is `false`. + +[`Fragments.Identifiers`]: /methods/page/fragments/#identifiers +[`TableOfContents`]: /methods/page/tableofcontents/ +[asciidoctor-diagram]: https://asciidoctor.org/docs/asciidoctor-diagram/ +[attributes]: https://asciidoctor.org/docs/asciidoc-syntax-quick-reference/#attributes-and-substitutions +[CommonMark]: https://spec.commonmark.org/current/ +[deleted text]: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/del +[duplication of shared page resources]: /configuration/markup/#duplicateresourcefiles +[duplication of shared page resources]: /configuration/markup/#duplicateresourcefiles +[embedded image render hook]: /render-hooks/images/#default +[embedded image render hook]: /render-hooks/images/#default +[embedded link render hook]: /render-hooks/links/#default +[embedded link render hook]: /render-hooks/links/#default +[GitHub Flavored Markdown]: https://github.github.com/gfm/ +[GitHub Flavored Markdown: Autolinks]: https://github.github.com/gfm/#autolinks-extension- +[GitHub Flavored Markdown: Strikethrough]: https://github.github.com/gfm/#strikethrough-extension- +[GitHub Flavored Markdown: Tables]: https://github.github.com/gfm/#tables-extension- +[GitHub Flavored Markdown: Task list items]: https://github.github.com/gfm/#task-list-items-extension- +[Goldmark]: https://github.com/yuin/goldmark/ +[Goldmark Extensions: CJK]: https://github.com/yuin/goldmark?tab=readme-ov-file#cjk-extension +[Goldmark Extensions: Typographer]: https://github.com/yuin/goldmark?tab=readme-ov-file#typographer-extension +[Hugo Goldmark Extensions: Extras]: https://github.com/gohugoio/hugo-goldmark-extensions?tab=readme-ov-file#extras-extension +[Hugo Goldmark Extensions: Passthrough]: https://github.com/gohugoio/hugo-goldmark-extensions?tab=readme-ov-file#passthrough-extension +[image render hook]: /render-hooks/images/ +[includes]: https://docs.asciidoctor.org/asciidoc/latest/syntax-quick-reference/#includes +[inserted text]: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/ins +[mark text]: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/mark +[Markdown attributes]: /content-management/markdown-attributes/ +[mathematics in Markdown]: content-management/mathematics/ +[multilingual page resources]: /content-management/page-resources/#multilingual +[PHP Markdown Extra: Definition lists]: https://michelf.ca/projects/php-markdown/extra/#def-list +[PHP Markdown Extra: Footnotes]: https://michelf.ca/projects/php-markdown/extra/#footnotes +[security policy]: /configuration/security/ +[subscript]: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/sub +[superscript]: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/sup +[AsciiDoc]: https://asciidoc.org/ +[Emacs Org Mode]: https://orgmode.org/ +[Pandoc]: https://www.pandoc.org/ +[reStructuredText]: https://docutils.sourceforge.io/rst.html diff --git a/content/en/configuration/media-types.md b/content/en/configuration/media-types.md new file mode 100644 index 000000000..ea89ee04a --- /dev/null +++ b/content/en/configuration/media-types.md @@ -0,0 +1,82 @@ +--- +title: Configure media types +linkTitle: Media types +description: Configure media types. +categories: [] +keywords: [] +--- + +{{% glossary-term "media type" %}} + +Configured media types serve multiple purposes in Hugo, including the definition of [output formats](g). This is the default media type configuration in tabular form: + +{{< datatable "config" "mediaTypes" "_key" "suffixes" >}} + +The `suffixes` column in the table above shows the suffixes associated with each media type. For example, Hugo associates `.html` and `.htm` files with the `text/html` media type. + +> [!note] +> The first suffix is the primary suffix. Use the primary suffix when naming template files. For example, when creating a template for an RSS feed, use the `xml` suffix. + +## Default configuration + +The following is the default configuration that matches the table above: + +{{< code-toggle file=hugo config=mediaTypes />}} + +delimiter +: (`string`) The delimiter between the file name and the suffix. The delimiter, in conjunction with the suffix, forms the file extension. Default is `"."`. + +suffixes +: (`[]string`) The suffixes associated with this media type. The first suffix is the primary suffix. + +## Modify a media type + +You can modify any of the default media types. For example, to switch the primary suffix for `text/html` from `html` to `htm`: + +{{< code-toggle file=hugo >}} +[mediaTypes.'text/html'] +suffixes = ['htm','html'] +{{< /code-toggle >}} + +If you alter a default media type, you must also explicitly redefine all output formats that utilize that media type. For example, to ensure the changes above affect the `html` output format, redefine the `html` output format: + +{{< code-toggle file=hugo >}} +[outputFormats.html] +mediaType = 'text/html' +{{< /code-toggle >}} + +## Create a media type + +You can create new media types as needed. For example, to create a media type for an Atom feed: + +{{< code-toggle file=hugo >}} +[mediaTypes.'application/atom+xml'] +suffixes = ['atom'] +{{< /code-toggle >}} + +## Media types without suffixes + +Occasionally, you may need to create a media type without a suffix or delimiter. For example, [Netlify] recognizes configuration files named `_redirects` and `_headers`, which Hugo can generate using custom [output formats](g). + +To support these custom output formats, register a custom media type with no suffix or delimiter: + +{{< code-toggle file=hugo >}} +[mediaTypes."text/netlify"] +delimiter = "" +{{< /code-toggle >}} + +The custom output format definitions would look something like this: + +{{< code-toggle file=hugo >}} +[outputFormats.redir] +baseName = "_redirects" +isPlainText = true +mediatype = "text/netlify" +[outputFormats.headers] +baseName = "_headers" +isPlainText = true +mediatype = "text/netlify" +notAlternative = true +{{< /code-toggle >}} + +[Netlify]: https://www.netlify.com/ diff --git a/content/en/configuration/menus.md b/content/en/configuration/menus.md new file mode 100644 index 000000000..759f53ff3 --- /dev/null +++ b/content/en/configuration/menus.md @@ -0,0 +1,135 @@ +--- +title: Configure menus +linkTitle: Menus +description: Centrally define menu entries for one or more menus. +categories: [] +keywords: [] +--- + +> [!note] +> To understand Hugo's menu system, please refer to the [menus] page. + +There are three ways to define menu entries: + +1. [Automatically] +1. [In front matter] +1. In site configuration + +This page covers the site configuration method. + +## Example + +To define entries for a "main" menu: + +{{< code-toggle file=hugo >}} +[[menus.main]] +name = 'Home' +pageRef = '/' +weight = 10 + +[[menus.main]] +name = 'Products' +pageRef = '/products' +weight = 20 + +[[menus.main]] +name = 'Services' +pageRef = '/services' +weight = 30 +{{< /code-toggle >}} + +This creates a menu structure that you can access with [`Menus`] method on a `Site` object: + +```go-html-template +{{ range .Site.Menus.main }} + ... +{{ end }} +``` + +See [menu templates] for a detailed example. + +To define entries for a "footer" menu: + +{{< code-toggle file=hugo >}} +[[menus.footer]] +name = 'Terms' +pageRef = '/terms' +weight = 10 + +[[menus.footer]] +name = 'Privacy' +pageRef = '/privacy' +weight = 20 +{{< /code-toggle >}} + +Access this menu structure in the same way: + +```go-html-template +{{ range .Site.Menus.footer }} + ... +{{ end }} +``` + +## Properties + +Menu entries usually include at least three properties: `name`, `weight`, and either `pageRef` or `url`. Use `pageRef` for internal page destinations and `url` for external destinations. + +These are the available menu entry properties: + +{{% include "/_common/menu-entry-properties.md" %}} + +pageRef +: (`string`) The [logical path](g) of the target page. For example: + + page kind|pageRef + :--|:-- + home|`/` + page|`/books/book-1` + section|`/books` + taxonomy|`/tags` + term|`/tags/foo` + +url +: (`string`) The destination URL. Use this for external destinations only. + +## Nested menu + +This nested menu demonstrates some of the available properties: + +{{< code-toggle file=hugo >}} +[[menus.main]] +name = 'Products' +pageRef = '/products' +weight = 10 + +[[menus.main]] +name = 'Hardware' +pageRef = '/products/hardware' +parent = 'Products' +weight = 1 + +[[menus.main]] +name = 'Software' +pageRef = '/products/software' +parent = 'Products' +weight = 2 + +[[menus.main]] +name = 'Services' +pageRef = '/services' +weight = 20 + +[[menus.main]] +name = 'Hugo' +pre = '' +url = 'https://gohugo.io/' +weight = 30 +[menus.main.params] +rel = 'external' +{{< /code-toggle >}} + +[`Menus`]: /methods/site/menus/ +[Automatically]: /content-management/menus/#define-automatically +[In front matter]: /content-management/menus/#define-in-front-matter +[menu templates]: /templates/menu/ +[menus]: /content-management/menus/ diff --git a/content/en/configuration/minify.md b/content/en/configuration/minify.md new file mode 100644 index 000000000..a530cb73d --- /dev/null +++ b/content/en/configuration/minify.md @@ -0,0 +1,15 @@ +--- +title: Configure minify +linkTitle: Minify +description: Configure minify. +categories: [] +keywords: [] +--- + +This is the default configuration: + +{{< code-toggle config=minify />}} + +See the [tdewolff/minify] project page for details. + +[tdewolff/minify]: https://github.com/tdewolff/minify diff --git a/content/en/configuration/module.md b/content/en/configuration/module.md new file mode 100644 index 000000000..d736b7c6f --- /dev/null +++ b/content/en/configuration/module.md @@ -0,0 +1,179 @@ +--- +title: Configure modules +linkTitle: Modules +description: Configure modules. +categories: [] +keywords: [] +aliases: [/hugo-modules/configuration/] +--- + +## Top-level options + +This is the default configuration: + +{{< code-toggle file=hugo >}} +[module] +noProxy = 'none' +noVendor = '' +private = '*.*' +proxy = 'direct' +vendorClosest = false +workspace = 'off' +{{< /code-toggle >}} + +auth +: {{< new-in 0.144.0 />}} +: (`string`) Configures `GOAUTH` when running the Go command for module operations. This is a semicolon-separated list of authentication commands for go-import and HTTPS module mirror interactions. This is useful for private repositories. See `go help goauth` for more information. + +noProxy +: (`string`) A comma-separated list of [glob](g) patterns matching paths that should not use the [configured proxy server](#proxy). + +noVendor +: (`string`) A [glob](g) pattern matching module paths to skip when vendoring. + +private +: (`string`) A comma-separated list of [glob](g) patterns matching paths that should be treated as private. + +proxy +: (`string`) The proxy server to use to download remote modules. Default is `direct`, which means `git clone` and similar. + +replacements +: (`string`) Primarily useful for local module development, a comma-separated list of mappings from module paths to directories. Paths may be absolute or relative to the [`themesDir`]. + + {{< code-toggle file=hugo >}} + [module] + replacements = 'github.com/bep/my-theme -> ../..,github.com/bep/shortcodes -> /some/path' + {{< /code-toggle >}} + +vendorClosest +: (`bool`) Whether to pick the vendored module closest to the module using it. The default behavior is to pick the first. Note that there can still be only one dependency of a given module path, so once it is in use it cannot be redefined. Default is `false`. + +workspace +: (`string`) The Go workspace file to use, either as an absolute path or a path relative to the current working directory. Enabling this activates Go workspace mode and requires Go 1.18 or later. The default is `off`. + +You may also use environment variables to set any of the above. For example: + +```sh +export HUGO_MODULE_PROXY="https://proxy.example.org" +export HUGO_MODULE_REPLACEMENTS="github.com/bep/my-theme -> ../.." +export HUGO_MODULE_WORKSPACE="/my/hugo.work" +``` + +{{% include "/_common/gomodules-info.md" %}} + +## Hugo version + +You can specify a required Hugo version for your module in the `module` section. Users will then receive a warning if their Hugo version is incompatible. + +This is the default configuration: + +{{< code-toggle config=module.hugoVersion />}} + +You can omit any of the settings above. + +extended +: (`bool`) Whether the extended edition of Hugo is required, satisfied by installing either the extended or extended/deploy edition. + +max +: (`string`) The maximum Hugo version supported, for example `0.143.0`. + +min +: (`string`) The minimum Hugo version supported, for example `0.123.0`. + +[`themesDir`]: /configuration/all/#themesdir + +## Imports + +{{< code-toggle file=hugo >}} +[[module.imports]] +disable = false +ignoreConfig = false +ignoreImports = false +path = "github.com/gohugoio/hugoTestModules1_linux/modh1_2_1v" +[[module.imports]] +path = "my-shortcodes" +{{< /code-toggle >}} + +disable +: (`bool`) Whether to disable the module but keep version information in the `go.*` files. Default is `false`. + +ignoreConfig +: (`bool`) Whether to ignore module configuration files, for example, `hugo.toml`. This will also prevent loading of any transitive module dependencies. Default is `false`. + +ignoreImports +: (`bool`) Whether to ignore module imports. Default is `false`. + +noMounts +: (`bool`) Whether to disable directory mounting for this import. Default is `false`. + +noVendor +: (`bool`) Whether to disable vendoring for this import. This setting is restricted to the main project. Default is `false`. + +path +: (`string`) The module path, either a valid Go module path (e.g., `github.com/gohugoio/myShortcodes`) or the directory name if stored in the [`themesDir`]. + +[`themesDir`]: /configuration/all#themesDir + +{{% include "/_common/gomodules-info.md" %}} + +## Mounts + +Before Hugo v0.56.0, custom component paths could only be configured by setting [`archetypeDir`], [`assetDir`], [`contentDir`], [`dataDir`], [`i18nDir`], [`layoutDi`], or [`staticDir`] in the site configuration. Module mounts offer greater flexibility than these legacy settings, but +you cannot use both. + +[`archetypeDir`]: /configuration/all/ +[`assetDir`]: /configuration/all/ +[`contentDir`]: /configuration/all/ +[`dataDir`]: /configuration/all/ +[`i18nDir`]: /configuration/all/ +[`layoutDi`]: /configuration/all/ +[`staticDir`]: /configuration/all/ + +> [!note] +> If you use module mounts do not use the legacy settings. + +### Default mounts + +> [!note] +> Adding a new mount to a target root will cause the existing default mount for that root to be ignored. If you still need the default mount, you must explicitly add it along with the new mount. + +The are the default mounts: + +{{< code-toggle config=module.mounts />}} + +source +: (`string`) The source directory of the mount. For the main project, this can be either project-relative or absolute. For other modules it must be project-relative. + +target +: (`string`) Where the mount will reside within Hugo's virtual file system. It must begin with one of Hugo's component directories: `archetypes`, `assets`, `content`, `data`, `i18n`, `layouts`, or `static`. For example, `content/blog`. + +disableWatch +: {{< new-in 0.128.0 />}} +: (`bool`) Whether to disable watching in watch mode for this mount. Default is `false`. + +lang +: (`string`) The language code, e.g. "en". Relevant for `content` mounts, and `static` mounts when in multihost mode. + +includeFiles +: (`string` or `[]string`) One or more [glob](g) patterns matching files or directories to include. If `excludeFiles` is not set, the files matching `includeFiles` will be the files mounted. + + The glob patterns are matched against file names relative to the source root. Use Unix-style forward slashes (`/`), even on Windows. A single forward slash (`/`) matches the mount root, and double asterisks (`**`) act as a recursive wildcard, matching all directories and files beneath a given point (e.g., `/posts/**.jpg`). The search is case-insensitive. + +excludeFiles +: (`string` or `[]string`) One or more [glob](g) patterns matching files to exclude. + +### Example + +{{< code-toggle file=hugo >}} +[module] +[[module.mounts]] + source="content" + target="content" + excludeFiles="docs/*" +[[module.mounts]] + source="node_modules" + target="assets" +[[module.mounts]] + source="assets" + target="assets" +{{< /code-toggle >}} diff --git a/content/en/configuration/output-formats.md b/content/en/configuration/output-formats.md new file mode 100644 index 000000000..2627c6df4 --- /dev/null +++ b/content/en/configuration/output-formats.md @@ -0,0 +1,209 @@ +--- +title: Configure output formats +linkTitle: Output formats +description: Configure output formats. +categories: [] +keywords: [] +--- + +{{% glossary-term "output format" %}} + +You can output a page in as many formats as you want. Define an infinite number of output formats, provided they each resolve to a unique file system path. + +This is the default output format configuration in tabular form: + +{{< datatable + "config" + "outputFormats" + "_key" + "mediaType" + "weight" + "baseName" + "isHTML" + "isPlainText" + "noUgly" + "notAlternative" + "path" + "permalinkable" + "protocol" + "rel" + "root" + "ugly" +>}} + +## Default configuration + +The following is the default configuration that matches the table above: + +{{< code-toggle config=outputFormats />}} + +baseName +: (`string`) The base name of the published file. Default is `index`. + +isHTML +: (`bool`) Whether to classify the output format as HTML. Hugo uses this value to determine when to create alias redirects and when to inject the LiveReload script. Default is `false`. + +isPlainText +: (`bool`) Whether to parse templates for this output format with Go's [text/template] package instead of the [html/template] package. Default is `false`. + +mediaType +: (`string`) The [media type](g) of the published file. This must match one of the [configured media types]. + +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`. + +path +: (`string`) The published file's directory path, relative to the root of the publish directory. If not specified, the file will be published using its content path. + +permalinkable +: (`bool`) Whether to return the rendering output format rather than main output format when invoking the [`Permalink`] and [`RelPermalink`] methods on a `Page` object. See [details](#link-to-output-formats). 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://`. + +rel +: (`string`) If provided, you can assign this value to `rel` attributes in `link` elements when iterating over output formats in your templates. Default is `alternate`. + +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`. + +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`. + +## Modify an output format + +You can modify any of the default output formats. For example, to prioritize `json` rendering over `html` rendering, when both are generated, adjust the [`weight`](#weight): + +{{< code-toggle file=hugo >}} +[outputFormats.json] +weight = 1 +[outputFormats.html] +weight = 2 +{{< /code-toggle >}} + +The example above shows that when you modify a default content format, you only need to define the properties that differ from their default values. + +## Create an output format + +You can create new output formats as needed. For example, you may wish to create an output format to support Atom feeds. + +### Step 1 + +Output formats require a specified media type. Because Atom feeds use `application/atom+xml`, which is not one of the [default media types], you must create it first. + +{{< code-toggle file=hugo >}} +[mediaTypes.'application/atom+xml'] +suffixes = ['atom'] +{{< /code-toggle >}} + +See [configure media types] for more information. + +### Step 2 + +Create a new output format: + +{{< code-toggle file=hugo >}} +[outputFormats.atom] +mediaType = 'application/atom+xml' +noUgly = true +{{< /code-toggle >}} + +Note that we use the default settings for all other output format properties. + +### Step 3 + +Specify the page [kinds](g) for which to render this output format: + +{{< code-toggle file=hugo >}} +[outputs] +home = ['html', 'rss', 'atom'] +section = ['html', 'rss', 'atom'] +taxonomy = ['html', 'rss', 'atom'] +term = ['html', 'rss', 'atom'] +{{< /code-toggle >}} + +See [configure outputs] for more information. + +### Step 4 + +Create a template to render the output format. Since Atom feeds are lists, you need to create a list template. Consult the [template lookup order] to find the correct template path: + +```text +layouts/_default/list.atom.atom +``` + +We leave writing the template code as an exercise for you. Aim for a result similar to the [embedded RSS template]. + +## 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: + +```go-html-template +{{ range .AlternativeOutputFormats }} + +{{ end }} +``` + +## Link to output formats + +By default, a `Page` object's [`Permalink`] and [`RelPermalink`] methods return the URL of the [primary output format](g), typically `html`. This behavior remains consistent regardless of the template used. + +For example, in `single.json.json`, you'll see: + +```go-html-template +{{ .RelPermalink }} → /that-page/ +{{ with .OutputFormats.Get "json" }} + {{ .RelPermalink }} → /that-page/index.json +{{ end }} +``` + +To make these methods return the URL of the _current_ template's output format, you must set the [`permalinkable`] setting to `true` for that format. + +With `permalinkable` set to true for `json` in the same `single.json.json` template: + +```go-html-template +{{ .RelPermalink }} → /that-page/index.json +{{ with .OutputFormats.Get "html" }} + {{ .RelPermalink }} → /that-page/ +{{ end }} +``` + +## Template lookup order + +Each output format requires a template conforming to the [template lookup order]. + +For the highest specificity in the template lookup order, include the page kind, output format, and suffix in the file name: + +```text +[page kind].[output format].[suffix] +``` + +For example, for section pages: + +Output format|Template path +:--|:-- +`html`|`layouts/_default/section.html.html` +`json`|`layouts/_default/section.json.json` +`rss`|`layouts/_default/section.rss.xml` + +[`AlternativeOutputFormats`]: /methods/page/alternativeoutputformats/ +[`OutputFormats`]: /methods/page/outputformats/ +[`Permalink`]: /methods/page/permalink/ +[`RelPermalink`]: /methods/page/relpermalink/ +[`baseURL`]: /configuration/all/#baseurl +[`permalinkable`]: #permalinkable +[`uglyURLs`]: /configuration/ugly-urls/ +[configure media types]: /configuration/media-types/ +[configure outputs]: /configuration/outputs/ +[configured media types]: /configuration/media-types/ +[default media types]: /configuration/media-types/ +[embedded RSS template]: {{% eturl rss %}} +[html/template]: https://pkg.go.dev/html/template +[template lookup order]: /templates/lookup-order/ +[text/template]: https://pkg.go.dev/text/template diff --git a/content/en/configuration/outputs.md b/content/en/configuration/outputs.md new file mode 100644 index 000000000..9a83cb6e9 --- /dev/null +++ b/content/en/configuration/outputs.md @@ -0,0 +1,49 @@ +--- +title: Configure outputs +linkTitle: Outputs +description: Configure which output formats to render for each page kind. +categories: [] +keywords: [] +--- + +{{% glossary-term "output format" %}} + +Learn more about creating and configuring output formats in the [configure output formats] section. + +## Outputs per page kind + +The following default configuration determines the output formats generated for each page kind: + +{{< code-toggle config=outputs />}} + +To render the built-in `json` output format for the `home` page kind, assuming you've already created the necessary template, add the following to your configuration: + +{{< code-toggle file=hugo >}} +[outputs] +home = ['html','rss','json'] +{{< /code-toggle >}} + +Notice in this example that we only specified the `home` page kind. You don't need to include entries for other page kinds unless you intend to modify their default output formats. + +> [!note] +> The order of the output formats in the arrays above is important. The first element will be the _primary output format_ for that page kind, and in most cases that should be `html` as shown in the default configuration. +> +> The primary output format for a given page kind determines the value returned by the [`Permalink`] and [`RelPermalink`] methods on a `Page` object. +> +> See the [link to output formats] section for details. + +## Outputs per page + +Add output formats to a page's rendering using the `outputs` field in its front matter. For example, to include `json` in the output formats rendered for a specific page: + +{{< code-toggle file=content/example.md fm=true >}} +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. + +[`Permalink`]: /methods/page/permalink/ +[`RelPermalink`]: /methods/page/relpermalink/ +[configure output formats]: /configuration/output-formats/ +[link to output formats]: configuration/output-formats/#link-to-output-formats diff --git a/content/en/configuration/page.md b/content/en/configuration/page.md new file mode 100644 index 000000000..81169e546 --- /dev/null +++ b/content/en/configuration/page.md @@ -0,0 +1,34 @@ +--- +title: Configure page +linkTitle: Page +description: Configure page behavior. +categories: [] +keywords: [] +--- + +{{< new-in 0.133.0 />}} + +{{% glossary-term "default sort order" %}} + +Hugo uses the default sort order to determine the _next_ and _previous_ page relative to the current page when calling these methods on a `Page` object: + +- [`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: + +{{< code-toggle config=page />}} + +To reverse the meaning of _next_ and _previous_: + +{{< code-toggle file=hugo >}} +[page] + nextPrevInSectionSortOrder = 'asc' + nextPrevSortOrder = 'asc' +{{< /code-toggle >}} + +> [!note] +> These settings do not apply to the [`Next`] or [`Prev`] methods on a `Pages` object. + +[`Next`]: /methods/pages/next +[`Prev`]: /methods/pages/next diff --git a/content/en/configuration/pagination.md b/content/en/configuration/pagination.md new file mode 100644 index 000000000..66b3b8cf4 --- /dev/null +++ b/content/en/configuration/pagination.md @@ -0,0 +1,45 @@ +--- +title: Configure pagination +linkTitle: Pagination +description: Configure pagination. +categories: [] +keywords: [] +--- + +This is the default configuration: + +{{< code-toggle config=pagination />}} + +disableAliases +: (`bool`) Whether to disable alias generation for the first pager. Default is `false`. + +pagerSize +: (`int`) The number of pages per pager. Default is `10`. + +path +: (`string`) The segment of each pager URL indicating that the target page is a pager. Default is `page`. + +With multilingual sites you can define the pagination behavior for each language: + +{{< code-toggle file=hugo >}} +[languages.en] +contentDir = 'content/en' +languageCode = 'en-US' +languageDirection = 'ltr' +languageName = 'English' +weight = 1 +[languages.en.pagination] +disableAliases = true +pagerSize = 10 +path = 'page' +[languages.de] +contentDir = 'content/de' +languageCode = 'de-DE' +languageDirection = 'ltr' +languageName = 'Deutsch' +weight = 2 +[languages.de.pagination] +disableAliases = true +pagerSize = 20 +path = 'blatt' +{{< /code-toggle >}} diff --git a/content/en/configuration/params.md b/content/en/configuration/params.md new file mode 100644 index 000000000..239b0c2da --- /dev/null +++ b/content/en/configuration/params.md @@ -0,0 +1,100 @@ +--- +title: Configure params +linkTitle: Params +description: Create custom site parameters. +categories: [] +keywords: [] +--- + +Use the `params` key for custom parameters: + +{{< code-toggle file=hugo >}} +baseURL = 'https://example.org/' +title = 'Project Documentation' +languageCode = 'en-US' +[params] +subtitle = 'Reference, Tutorials, and Explanations' +[params.contact] +email = 'info@example.org' +phone = '+1 206-555-1212' +{{< /code-toggle >}} + +Access the custom parameters from your templates using the [`Params`] method on a `Site` object: + +[`Params`]: /methods/site/params/ + +```go-html-template +{{ .Site.Params.subtitle }} → Reference, Tutorials, and Explanations +{{ .Site.Params.contact.email }} → info@example.org +``` + +Key names should use camelCase or snake_case. While TOML, YAML, and JSON allow kebab-case keys, they are not valid [identifiers](g) and cannot be used when [chaining](g) identifiers. + +For example, you can do either of these: + +```go-html-template +{{ .Site.params.camelCase.foo }} +{{ .Site.params.snake_case.foo }} +``` + +But you cannot do this: + +```go-html-template +{{ .Site.params.kebab-case.foo }} +``` + +## Multilingual sites + +For multilingual sites, create a `params` key under each language: + +{{< code-toggle file=hugo >}} +baseURL = 'https://example.org/' +defaultContentLanguage = 'en' + +[languages.de] +languageCode = 'de-DE' +languageDirection = 'ltr' +languageName = 'Deutsch' +title = 'Projekt Dokumentation' +weight = 1 + +[languages.de.params] +subtitle = 'Referenz, Tutorials und Erklärungen' + +[languages.de.params.contact] +email = 'info@de.example.org' +phone = '+49 30 1234567' + +[languages.en] +languageCode = 'en-US' +languageDirection = 'ltr' +languageName = 'English' +title = 'Project Documentation' +weight = 2 + +[languages.en.params] +subtitle = 'Reference, Tutorials, and Explanations' + +[languages.en.params.contact] +email = 'info@example.org' +phone = '+1 206-555-1212' +{{< /code-toggle >}} + +## Namespacing + +To prevent naming conflicts, module and theme developers should namespace any custom parameters specific to their module or theme. + +{{< code-toggle file=hugo >}} +[params.modules.myModule.colors] +background = '#efefef' +font = '#222222' +{{< /code-toggle >}} + +To access the module/theme settings: + +```go-html-template +{{ $cfg := .Site.Params.module.mymodule }} + +{{ $cfg.colors.background }} → #efefef +{{ $cfg.colors.font }} → #222222 +``` diff --git a/content/en/configuration/permalinks.md b/content/en/configuration/permalinks.md new file mode 100644 index 000000000..0810624a6 --- /dev/null +++ b/content/en/configuration/permalinks.md @@ -0,0 +1,162 @@ +--- +title: Configure permalinks +linkTitle: Permalinks +description: Configure permalinks. +categories: [] +keywords: [] +--- + +This is the default configuration: + +{{< code-toggle config=permalinks />}} + +Define a URL pattern for each top-level section. Each URL pattern can target a given language and/or page kind. + +> [!note] +> The [`url`] front matter field overrides any matching permalink pattern. + +## Monolingual example + +With this content structure: + +```text +content/ +├── posts/ +│ ├── bash-in-slow-motion.md +│ └── tls-in-a-nutshell.md +├── tutorials/ +│ ├── git-for-beginners.md +│ └── javascript-bundling-with-hugo.md +└── _index.md +``` + +Render tutorials under "training", and render the posts under "articles" with a date-base hierarchy: + +{{< code-toggle file=hugo >}} +[permalinks.page] +posts = '/articles/:year/:month/:slug/' +tutorials = '/training/:slug/' +[permalinks.section] +posts = '/articles/' +tutorials = '/training/' +{{< /code-toggle >}} + +The structure of the published site will be: + +```text +public/ +├── articles/ +│ ├── 2023/ +│ │ ├── 04/ +│ │ │ └── bash-in-slow-motion/ +│ │ │ └── index.html +│ │ └── 06/ +│ │ └── tls-in-a-nutshell/ +│ │ └── index.html +│ └── index.html +├── training/ +│ ├── git-for-beginners/ +│ │ └── index.html +│ ├── javascript-bundling-with-hugo/ +│ │ └── index.html +│ └── index.html +└── index.html +``` + +To create a date-based hierarchy for regular pages in the content root: + +{{< code-toggle file=hugo >}} +[permalinks.page] +"/" = "/:year/:month/:slug/" +{{< /code-toggle >}} + +Use the same approach with taxonomy terms. For example, to omit the taxonomy segment of the URL: + +{{< code-toggle file=hugo >}} +[permalinks.term] +'tags' = '/:slug/' +{{< /code-toggle >}} + +## Multilingual example + +Use the `permalinks` configuration as a component of your localization strategy. + +With this content structure: + +```text +content/ +├── en/ +│ ├── books/ +│ │ ├── les-miserables.md +│ │ └── the-hunchback-of-notre-dame.md +│ └── _index.md +└── es/ + ├── books/ + │ ├── les-miserables.md + │ └── the-hunchback-of-notre-dame.md + └── _index.md +``` + +And this site configuration: + +{{< code-toggle file=hugo >}} +defaultContentLanguage = 'en' +defaultContentLanguageInSubdir = true + +[languages.en] +contentDir = 'content/en' +languageCode = 'en-US' +languageDirection = 'ltr' +languageName = 'English' +weight = 1 + +[languages.en.permalinks.page] +books = "/books/:slug/" + +[languages.en.permalinks.section] +books = "/books/" + +[languages.es] +contentDir = 'content/es' +languageCode = 'es-ES' +languageDirection = 'ltr' +languageName = 'Español' +weight = 2 + +[languages.es.permalinks.page] +books = "/libros/:slug/" + +[languages.es.permalinks.section] +books = "/libros/" +{{< /code-toggle >}} + +The structure of the published site will be: + +```text +public/ +├── en/ +│ ├── books/ +│ │ ├── les-miserables/ +│ │ │ └── index.html +│ │ ├── the-hunchback-of-notre-dame/ +│ │ │ └── index.html +│ │ └── index.html +│ └── index.html +├── es/ +│ ├── libros/ +│ │ ├── les-miserables/ +│ │ │ └── index.html +│ │ ├── the-hunchback-of-notre-dame/ +│ │ │ └── index.html +│ │ └── index.html +│ └── index.html +└── index.html +``` + +## Tokens + +Use these tokens when defining a URL pattern. + +{{% include "/_common/permalink-tokens.md" %}} + +[`url`]: /content-management/front-matter/#url diff --git a/content/en/about/privacy.md b/content/en/configuration/privacy.md similarity index 79% rename from content/en/about/privacy.md rename to content/en/configuration/privacy.md index ef4faa793..c94f2c1c3 100644 --- a/content/en/about/privacy.md +++ b/content/en/configuration/privacy.md @@ -1,17 +1,10 @@ --- -title: Privacy +title: Configure privacy linkTitle: Privacy description: Configure your site to help comply with regional privacy regulations. -categories: [about] -keywords: ["GDPR", "Privacy", "Data Protection"] -menu: - docs: - parent: about - weight: 40 -weight: 40 -toc: true -aliases: [/gdpr/,/about/hugo-and-gdpr/] -toc: true +categories: [] +keywords: [] +aliases: [/about/privacy/] --- ## Responsibility @@ -31,12 +24,10 @@ Hugo provides [embedded templates](g) to simplify site and content creation. Som Some of these templates include settings to enhance privacy. - ## Configuration -{{% note %}} -These settings affect the behavior of some of Hugo's embedded templates. These settings may or may not affect the behavior of templates provided by third parties in their modules or themes. -{{% /note %}} +> [!note] +> These settings affect the behavior of some of Hugo's embedded templates. These settings may or may not affect the behavior of templates provided by third parties in their modules or themes. These are the default privacy settings for Hugo's embedded templates: diff --git a/content/en/configuration/related-content.md b/content/en/configuration/related-content.md new file mode 100644 index 000000000..c6e182fae --- /dev/null +++ b/content/en/configuration/related-content.md @@ -0,0 +1,111 @@ +--- +title: Configure related content +linkTitle: Related content +description: Configure related content. +categories: [] +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. + +## Default configuration + +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. + +## Top-level options + +threshold +: (`int`) A value between 0-100, inclusive. A lower value will return more, but maybe not so relevant, matches. + +includeNewer +: (`bool`) Whether to include pages newer than the current page in the related content listing. This will mean that the output for older posts may change as new related content gets added. Default is `false`. + +toLower +: (`bool`) Whether to transform keywords in both the indexes and the queries to lower case. This may give more accurate results at a slight performance penalty. Default is `false`. + +## Per-index options + +name +: (`string`) The index name. This value maps directly to a page parameter. Hugo supports string values (`author` in the example) and lists (`tags`, `keywords` etc.) and time and date objects. + +type +: (`string`) One of `basic` or `fragments`. Default is `basic`. + +applyFilter +: (`string`) Apply a `type` specific filter to the result of a search. This is currently only used for the `fragments` type. + +weight +: (`int`) An integer weight that indicates how important this parameter is relative to the other parameters. It can be `0`, which has the effect of turning this index off, or even negative. Test with different values to see what fits your content best. Default is `0`. + +cardinalityThreshold +: (`int`) If between 1 and 100, this is a percentage. All keywords that are used in more than this percentage of documents are removed. For example, setting this to `60` will remove all keywords that are used in more than 60% of the documents in the index. If `0`, no keyword is removed from the index. Default is `0`. + +pattern +: (`string`) This is currently only relevant for dates. When listing related content, we may want to list content that is also close in time. Setting "2006" (default value for date indexes) as the pattern for a date index will add weight to pages published in the same year. For busier blogs, "200601" (year and month) may be a better default. + +toLower +: (`bool`) Whether to transform keywords in both the indexes and the queries to lower case. This may give more accurate results at a slight performance penalty. Default is `false`. + +## Example + +Imagine we're building a book review site. Our main content will be book reviews, and we'll use genres and authors as taxonomies. When someone views a book review, we want to show a short list of related reviews based on shared authors and genres. + +Create the content: + +```text +content/ +└── book-reviews/ + ├── book-review-1.md + ├── book-review-2.md + ├── book-review-3.md + ├── book-review-4.md + └── book-review-5.md +``` + +Configure the taxonomies: + +{{< code-toggle file=hugo >}} +[taxonomies] +author = 'authors' +genre = 'genres' +{{< /code-toggle >}} + +Configure the related content identification: + +{{< code-toggle file=hugo >}} +[related] +includeNewer = true +threshold = 80 +toLower = true +[[related.indices]] +name = 'authors' +weight = 2 +[[related.indices]] +name = 'genres' +weight = 1 +{{< /code-toggle >}} + +We've configured the `authors` index with a weight of `2` and the `genres` index with a weight of `1`. This means Hugo prioritizes shared `authors` as twice as significant as shared `genres`. + +Then render a list of 5 related reviews with a partial template like this: + +```go-html-template {file="layouts/partials/related.html" copy=true} +{{ with site.RegularPages.Related . | first 5 }} +

Related content:

+ +{{ end }} +``` + +[related content]: /content-management/related-content/ diff --git a/content/en/configuration/security.md b/content/en/configuration/security.md new file mode 100644 index 000000000..f950dd233 --- /dev/null +++ b/content/en/configuration/security.md @@ -0,0 +1,50 @@ +--- +title: Configure security +linkTitle: Security +description: Configure security. +categories: [] +keywords: [] +--- + +Hugo's built-in security policy, which restricts access to `os/exec`, remote communication, and similar operations, is configured via allow lists. By default, access is restricted. If a build attempts to use a feature not included in the allow list, it will fail, providing a detailed message. + +This is the default security configuration: + +{{< code-toggle config=security />}} + +enableInlineShortcodes +: (`bool`) Whether to enable [inline shortcodes]. Default is `false`. + +exec.allow +: (`[]string`) A slice of [regular expressions](g) matching the names of external executables that Hugo is allowed to run. + +exec.osEnv +: (`[]string`) A slice of [regular expressions](g) matching the names of operating system environment variables that Hugo is allowed to access. + +funcs.getenv +: (`[]string`) A slice of [regular expressions](g) matching the names of operating system environment variables that Hugo is allowed to access with the [`os.Getenv`] function. + +http.methods +: (`[]string`) A slice of [regular expressions](g) matching the HTTP methods that the [`resources.GetRemote`] function is allowed to use. + +http.mediaTypes +: (`[]string`) Applicable to the `resources.GetRemote` function, a slice of [regular expressions](g) matching the `Content-Type` in HTTP responses that Hugo trusts, bypassing file content analysis for media type detection. + +http.urls +: (`[]string`) A slice of [regular expressions](g) matching the URLs that the `resources.GetRemote` function is allowed to access. + +> [!note] +> Setting an allow list 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: + +```txt +export HUGO_SECURITY_HTTP_URLS=none +``` + +Learn more about [using environment variables] to configure your site. + +[`os.Getenv`]: /functions/os/getenv +[`resources.GetRemote`]: /functions/resources/getremote +[inline shortcodes]: /content-management/shortcodes/#inline +[using environment variables]: /configuration/introduction/#environment-variables diff --git a/content/en/configuration/segments.md b/content/en/configuration/segments.md new file mode 100644 index 000000000..0c4098770 --- /dev/null +++ b/content/en/configuration/segments.md @@ -0,0 +1,77 @@ +--- +title: Configure segments +linkTitle: Segments +description: Configure your site for segmented rendering. +categories: [] +keywords: [] +--- + +{{< new-in 0.124.0 />}} + +> [!note] +> The `segments` configuration applies only to segmented rendering. While it controls when content is rendered, it doesn't restrict access to Hugo's complete object graph (sites and pages), which remains fully available. + +Segmented rendering offers several advantages: + +- Faster builds: Process large sites more efficiently. +- Rapid development: Render only a subset of your site for quicker iteration. +- Scheduled rebuilds: Rebuild specific sections at different frequencies (e.g., home page and news hourly, full site weekly). +- Targeted output: Generate specific output formats (like JSON for search indexes). + +## Segment definition + +Each segment is defined by include and exclude filters: + +- Filters: Each segment has zero or more exclude filters and zero or more include filters. +- Matchers: Each filter contains one or more field [glob](g) matchers. +- Logic: Matchers within a filter use AND logic. Filters within a section (include or exclude) use OR logic. + +## Filter fields + +Available fields for filtering: + +kind +: (`string`) A [glob](g) pattern matching the [page kind](g). For example: ` {taxonomy,term}`. + +lang +: (`string`) A [glob](g) pattern matching the [page language]. For example: `{en,de}`. + +output +: (`string`) A [glob](g) pattern matching the [output format](g) of the page. For example: `{html,json}`. + +path +: (`string`) A [glob](g) pattern matching the page's [logical path](g). For example: `{/books,/books/**}`. + +## Example + +Place broad filters, such as those for language or output format, in the excludes section. For example: + +{{< code-toggle file=hugo >}} +[segments.segment1] + [[segments.segment1.excludes]] + lang = "n*" + [[segments.segment1.excludes]] + lang = "en" + output = "rss" + [[segments.segment1.includes]] + kind = "{home,term,taxonomy}" + [[segments.segment1.includes]] + path = "{/docs,/docs/**}" +{{< /code-toggle >}} + +## Rendering segments + +Render specific segments using the [`renderSegments`] configuration or the `--renderSegments` flag: + +```bash +hugo --renderSegments segment1 +``` + +You can configure multiple segments and use a comma-separated list with `--renderSegments` to render them all. + +```bash +hugo --renderSegments segment1,segment2 +``` + +[`renderSegments`]: /configuration/all/#rendersegments +[page language]: /methods/page/language/ diff --git a/content/en/configuration/server.md b/content/en/configuration/server.md new file mode 100644 index 000000000..92f0f0cfa --- /dev/null +++ b/content/en/configuration/server.md @@ -0,0 +1,128 @@ +--- +title: Configure server +linkTitle: Server +description: Configure the development server. +categories: [] +keywords: [] +--- + +These settings are exclusive to Hugo's development server, so a dedicated [configuration directory] for development, where the server is configured accordingly, is the recommended approach. + +[configuration directory]: /configuration/introduction/#configuration-directory + +```text +project/ +└── config/ + ├── _default/ + │ └── hugo.toml + └── development/ + └── server.toml +``` + +## Default settings + +The development server defaults to redirecting to `/404.html` for any requests to URLs that don't exist. See the [404 errors](#404-errors) section below for details. + +{{< code-toggle config=server />}} + +force +: (`bool`) Whether to force a redirect even if there is existing content in the path. + +from +: (`string`) A [glob](g) pattern matching the requested URL. Either `from` or `fromRE` must be set. If both `from` and `fromRe` are specified, the URL must match both patterns. + +fromHeaders +: {{< new-in 0.144.0 />}} +: (`map[string][string]`) Headers to match for the redirect. This maps the HTTP header name to a [glob](g) pattern with values to match. If the map is empty, the redirect will always be triggered. + +fromRe +: {{< new-in 0.144.0 />}} +: (`string`) A [regular expression](g) used to match the requested URL. Either `from` or `fromRE` must be set. If both `from` and `fromRe` are specified, the URL must match both patterns. Capture groups from the regular expression are accessible in the `to` field as `$1`, `$2`, and so on. + +status +: (`string`) The HTTP status code to use for the redirect. A status code of 200 will trigger a URL rewrite. + +to +: (`string`) The URL to forward the request to. + +## Headers + +Include headers in every server response to facilitate testing, particularly for features like Content Security Policies. + +[Content Security Policies]: https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP + +{{< code-toggle file=config/development/server >}} +[[headers]] +for = "/**" + +[headers.values] +X-Frame-Options = "DENY" +X-XSS-Protection = "1; mode=block" +X-Content-Type-Options = "nosniff" +Referrer-Policy = "strict-origin-when-cross-origin" +Content-Security-Policy = "script-src localhost:1313" +{{< /code-toggle >}} + +## Redirects + +You can define simple redirect rules. + +{{< code-toggle file=config/development/server >}} +[[redirects]] +from = "/myspa/**" +to = "/myspa/" +status = 200 +force = false +{{< /code-toggle >}} + +The `200` status code in this example triggers a URL rewrite, which is typically the desired behavior for [single-page applications]. + +[single-page applications]: https://en.wikipedia.org/wiki/Single-page_application + +## 404 errors + +The development server defaults to redirecting to /404.html for any requests to URLs that don't exist. + +{{< code-toggle config=server />}} + +If you've already defined other redirects, you must explicitly add the 404 redirect. + +{{< code-toggle file=config/development/server >}} +[[redirects]] +force = false +from = "/**" +to = "/404.html" +status = 404 +{{< /code-toggle >}} + +For multilingual sites, ensure the default language 404 redirect is defined last: + +{{< code-toggle file=config/development/server >}} +defaultContentLanguage = 'en' +defaultContentLanguageInSubdir = false +[[redirects]] +from = '/fr/**' +to = '/fr/404.html' +status = 404 + +[[redirects]] # Default language must be last. +from = '/**' +to = '/404.html' +status = 404 +{{< /code-toggle >}} + +When the default language is served from a subdirectory: + +{{< code-toggle file=config/development/server >}} +defaultContentLanguage = 'en' +defaultContentLanguageInSubdir = true +[[redirects]] +from = '/fr/**' +to = '/fr/404.html' +status = 404 + +[[redirects]] # Default language must be last. +from = '/**' +to = '/en/404.html' +status = 404 +{{< /code-toggle >}} diff --git a/content/en/configuration/services.md b/content/en/configuration/services.md new file mode 100644 index 000000000..dbe3893a7 --- /dev/null +++ b/content/en/configuration/services.md @@ -0,0 +1,52 @@ +--- +title: Configure services +linkTitle: Services +description: Configure embedded templates. +categories: [] +keywords: [] +--- + +Hugo provides [embedded templates](g) to simplify site and content creation. Some of these templates are configurable. For example, the embedded Google Analytics template requires a Google tag ID. + +This is the default configuration: + +{{< code-toggle config=services />}} + +disqus.shortname +: (`string`) The `shortname` used with the Disqus commenting system. See [details](/templates/embedded/#disqus). To access this value from a template: + + ```go-html-template + {{ .Site.Config.Services.Disqus.Shortname }} + ``` + +googleAnalytics.id +: (`string`) The Google tag ID for Google Analytics 4 properties. See [details](/templates/embedded/#google-analytics). To access this value from a template: + + ```go-html-template + {{ .Site.Config.Services.GoogleAnalytics.ID }} + ``` + +instagram.accessToken +: (`string`) Do not use. Deprecated in [v0.123.0]. The embedded `instagram` shortcode no longer uses this setting. + +instagram.disableInlineCSS +: (`bool`) Do not use. Deprecated in [v0.123.0]. The embedded `instagram` shortcode no longer uses this setting. + +rss.limit +: (`int`) The maximum number of items to include in an RSS feed. Set to `-1` for no limit. Default is `-1`. See [details](/templates/rss/). To access this value from a template: + + ```go-html-template + {{ .Site.Config.Services.RSS.Limit }} + ``` + +twitter.disableInlineCSS +: (`bool`) Do not use. Deprecated in [v0.141.0]. Use the `x` shortcode instead. + +x.disableInlineCSS +: (`bool`) Whether to disable the inline CSS rendered by the embedded `x` shortode. See [details](/shortcodes/x/#privacy). Default is `false`. To access this value from a template: + + ```go-html-template + {{ .Site.Config.Services.X.DisableInlineCSS }} + +[v0.141.0]: https://github.com/gohugoio/hugo/releases/tag/v0.141.0 +[v0.123.0]: https://github.com/gohugoio/hugo/releases/tag/v0.123.0 diff --git a/content/en/configuration/sitemap.md b/content/en/configuration/sitemap.md new file mode 100644 index 000000000..bc972994c --- /dev/null +++ b/content/en/configuration/sitemap.md @@ -0,0 +1,24 @@ +--- +title: Configure sitemap +linkTitle: Sitemap +description: Configure the sitemap. +categories: [] +keywords: [] +--- + +These are the default sitemap configuration values. They apply to all pages unless overridden in front matter. + +{{< code-toggle config=sitemap />}} + +changefreq +: (`string`) How frequently a page is likely to change. Valid values are `always`, `hourly`, `daily`, `weekly`, `monthly`, `yearly`, and `never`. With the default value of `""` Hugo will omit this field from the sitemap. See [details](https://www.sitemaps.org/protocol.html#changefreqdef). + +disable +: {{< new-in 0.125.0 />}} +: (`bool`) Whether to disable page inclusion. Default is `false`. Set to `true` in front matter to exclude the page. + +filename +: (`string`) The name of the generated file. Default is `sitemap.xml`. + +priority +: (`float`) The priority of a page relative to any other page on the site. Valid values range from 0.0 to 1.0. With the default value of `-1` Hugo will omit this field from the sitemap. See [details](https://www.sitemaps.org/protocol.html#prioritydef). diff --git a/content/en/configuration/taxonomies.md b/content/en/configuration/taxonomies.md new file mode 100644 index 000000000..4b5ba97a5 --- /dev/null +++ b/content/en/configuration/taxonomies.md @@ -0,0 +1,68 @@ +--- +title: Configure taxonomies +linkTitle: Taxonomies +description: Configure taxonomies. +categories: [] +keywords: [] +--- + +The default configuration defines two [taxonomies](g), `categories` and `tags`. + +{{< code-toggle config=taxonomies />}} + +When creating a taxonomy: + +- Use the singular form for the key (e.g., `category`). +- Use the plural form for the value (e.g., `categories`). + +Then use the value as the key in front matter: + +{{< code-toggle file=content/example.md fm=true >}} +--- +title: Example +categories: + - vegetarian + - gluten-free +tags: + - appetizer + - main course +{{< /code-toggle >}} + +If you do not expect to assign more than one [term](g) from a given taxonomy to a content page, you may use the singular form for both key and value: + +{{< code-toggle file=hugo >}} +taxonomies: + author: author +{{< /code-toggle >}} + +Then in front matter: + +{{< code-toggle file=content/example.md fm=true >}} +--- +title: Example +author: + - Robert Smith +{{< /code-toggle >}} + +The example above illustrates that even with a single term, the value is still provided as an array. + +You must explicitly define the default taxonomies to maintain them when adding a new one: + +{{< code-toggle file=hugo >}} +taxonomies: + author: author + category: categories + 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). + +{{< code-toggle file=hugo >}} +disableKinds = ['categories','tags'] +{{< /code-toggle >}} + +[`disableKinds`]: /configuration/all/#disablekinds + +See the [taxonomies] section for more information. + +[taxonomies]: /content-management/taxonomies/ diff --git a/content/en/configuration/ugly-urls.md b/content/en/configuration/ugly-urls.md new file mode 100644 index 000000000..ec1dd8a49 --- /dev/null +++ b/content/en/configuration/ugly-urls.md @@ -0,0 +1,36 @@ +--- +title: Configure ugly URLs +linkTitle: Ugly URLs +description: Configure ugly URLs. +categories: [] +keywords: [] +--- + +{{% glossary-term "ugly url" %}} For example: + +```text +https://example.org/section/article.html +``` + +In its default configuration, Hugo generates [pretty URLs](g). For example: +```text +https://example.org/section/article/ +``` + +This is the default configuration: + +{{< code-toggle config=uglyURLs />}} + +To generate ugly URLs for the entire site: + +{{< code-toggle file=hugo >}} +uglyURLs = true +{{< /code-toggle >}} + +To generate ugly URLs for specific sections of your site: + +{{< code-toggle file=hugo >}} +[uglyURLs] +books = true +films = false +{{< /code-toggle >}} diff --git a/content/en/content-management/_common/_index.md b/content/en/content-management/_common/_index.md deleted file mode 100644 index 4328d4d14..000000000 --- a/content/en/content-management/_common/_index.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -cascade: - _build: - list: never - publishResources: false - render: never ---- - - diff --git a/content/en/content-management/_common/page-kinds.md b/content/en/content-management/_common/page-kinds.md deleted file mode 100644 index 8f10dcd79..000000000 --- a/content/en/content-management/_common/page-kinds.md +++ /dev/null @@ -1,17 +0,0 @@ ---- -_comment: Do not remove front matter. ---- - -| Kind | Description | Example | -|----------------|--------------------------------------------------------------------|-------------------------------------------------------------------------------| -| `home` | The landing page for the home page | `/index.html` | -| `page` | The landing page for a given page | `my-post` page (`/posts/my-post/index.html`) | -| `section` | The landing page of a given section | `posts` section (`/posts/index.html`) | -| `taxonomy` | The landing page for a taxonomy | `tags` taxonomy (`/tags/index.html`) | -| `term` | The landing page for one taxonomy's term | term `awesome` in `tags` taxonomy (`/tags/awesome/index.html`) | - -Four other page kinds unrelated to content are `robotsTXT`, `RSS`, `sitemap`, and `404`. Although primarily for internal use, you can specify the name when disabling one or more page kinds on your site. For example: - -{{< code-toggle file=hugo >}} -disableKinds = ['robotsTXT','404'] -{{< /code-toggle >}} diff --git a/content/en/content-management/_index.md b/content/en/content-management/_index.md index 21d0b8739..4e2060756 100644 --- a/content/en/content-management/_index.md +++ b/content/en/content-management/_index.md @@ -1,16 +1,8 @@ --- title: Content management - description: Hugo makes managing large static sites easy with support for archetypes, content types, menus, cross references, summaries, and more. categories: [] keywords: [] -menu: - docs: - identifier: content-management-in-this-section - parent: content-management - weight: 10 weight: 10 aliases: [/content/,/content/organization] --- - -A static site generator needs to extend beyond front matter and a couple of templates to be both scalable and *manageable*. Hugo was designed with not only developers in mind, but also content managers and authors. diff --git a/content/en/content-management/archetypes.md b/content/en/content-management/archetypes.md index 966c847db..db0838504 100644 --- a/content/en/content-management/archetypes.md +++ b/content/en/content-management/archetypes.md @@ -1,15 +1,8 @@ --- title: Archetypes description: An archetype is a template for new content. -categories: [content management] -keywords: [archetypes,generators,metadata,front matter] -menu: - docs: - parent: content-management - weight: 140 - quicklinks: -weight: 140 -toc: true +categories: [] +keywords: [] aliases: [/content/archetypes/] --- @@ -102,7 +95,7 @@ Although typically used as a front matter template, you can also use an archetyp For example, in a documentation site you might have a section (content type) for functions. Every page within this section should follow the same format: a brief description, the function signature, examples, and notes. We can pre-populate the page to remind content authors of the standard format. -{{< code file=archetypes/functions.md >}} +````text {file="archetypes/functions.md"} --- date: '{{ .Date }}' draft: true @@ -126,7 +119,7 @@ One or more practical examples, each within a fenced code block. ## Notes Additional information to clarify as needed. -{{< /code >}} +```` Although you can include [template actions](g) within the content body, remember that Hugo evaluates these once---at the time of content creation. In most cases, place template actions in a [template](g) where Hugo evaluates the actions every time you [build](g) the site. diff --git a/content/en/content-management/build-options.md b/content/en/content-management/build-options.md index e78462455..8c29a19b9 100644 --- a/content/en/content-management/build-options.md +++ b/content/en/content-management/build-options.md @@ -1,18 +1,18 @@ --- title: Build options description: Build options help define how Hugo must treat a given page when building the site. -categories: [content management,fundamentals] -keywords: [build,content,front matter, page resources] -menu: - docs: - parent: content-management - weight: 70 -weight: 70 -toc: true +categories: [] +keywords: [] aliases: [/content/build-options/] --- -Build options are stored in a reserved front matter object named `build` with these defaults: + + +Build options are stored in a reserved front matter object named `build`[^1] with these defaults: + +[^1]: The `_build` alias for `build` is deprecated and will be removed in a future release. {{< code-toggle file=content/example/index.md fm=true >}} [build] @@ -23,49 +23,26 @@ render = 'always' list : When to include the page within page collections. Specify one of: - - - `always` - : Include the page in _all_ page collections. For example, `site.RegularPages`, `.Pages`, etc. This is the default value. - - `local` - : Include the page in _local_ page collections. For example, `.RegularPages`, `.Pages`, etc. Use this option to create fully navigable but headless content sections. - - - `never` - : Do not include the page in _any_ page collection. + - `always`: Include the page in _all_ page collections. For example, `site.RegularPages`, `.Pages`, etc. This is the default value. + - `local`: Include the page in _local_ page collections. For example, `.RegularPages`, `.Pages`, etc. Use this option to create fully navigable but headless content sections. + - `never`: Do not include the page in _any_ page collection. publishResources : Applicable to [page bundles], determines whether to publish the associated [page resources]. Specify one of: - - `true` - : Always publish resources. This is the default value. - - - `false` - : Only publish a resource when invoking its [`Permalink`], [`RelPermalink`], or [`Publish`] method within a template. + - `true`: Always publish resources. This is the default value. + - `false`: Only publish a resource when invoking its [`Permalink`], [`RelPermalink`], or [`Publish`] method within a template. render : When to render the page. Specify one of: - - `always` - : Always render the page to disk. This is the default value. + - `always`: Always render the page to disk. This is the default value. + - `link`: Do not render the page to disk, but assign `Permalink` and `RelPermalink` values. + - `never`: Never render the page to disk, and exclude it from all page collections. - - `link` - : Do not render the page to disk, but assign `Permalink` and `RelPermalink` values. - - - `never` - : Never render the page to disk, and exclude it from all page collections. - -[page bundles]: /content-management/page-bundles/ -[page resources]: /content-management/page-resources/ -[`Permalink`]: /methods/resource/permalink/ -[`RelPermalink`]: /methods/resource/relpermalink/ -[`Publish`]: /methods/resource/publish/ - -{{% note %}} -Any page, regardless of its build options, will always be available by using the [`.Page.GetPage`] or [`.Site.GetPage`] method. - -[`.Page.GetPage`]: /methods/page/getpage/ -[`.Site.GetPage`]: /methods/site/getpage/ -{{% /note %}} +> [!note] +> Any page, regardless of its build options, will always be available by using the [`.Page.GetPage`] or [`.Site.GetPage`] method. ## Example -- headless page @@ -92,14 +69,14 @@ title = 'Headless page' To include the content and images on the home page: -{{< code file=layouts/_default/home.html >}} +```go-html-template {file="layouts/_default/home.html"} {{ with .Site.GetPage "/headless" }} {{ .Content }} {{ range .Resources.ByType "image" }} {{ end }} {{ end }} -{{< /code >}} +``` The published site will have this structure: @@ -120,8 +97,6 @@ In the example above, note that: Create a unpublished section whose content and resources can be included in other pages. -[branch bundle]: /content-management/page-bundles/ - ```text content/ ├── headless/ @@ -152,7 +127,7 @@ In the front matter above, note that we have set `list` to `local` to include th To include the content and images on the home page: -{{< code file=layouts/_default/home.html >}} +```go-html-template {file="layouts/_default/home.html"} {{ with .Site.GetPage "/headless" }} {{ range .Pages }} {{ .Content }} @@ -161,7 +136,7 @@ To include the content and images on the home page: {{ end }} {{ end }} {{ end }} -{{< /code >}} +``` The published site will have this structure: @@ -211,14 +186,14 @@ render = 'always' To render the glossary: -{{< code file=layouts/glossary/list.html >}} +```go-html-template {file="layouts/glossary/list.html"}
{{ range .Pages }}
{{ .Title }}
{{ .Content }}
{{ end }}
-{{< /code >}} +``` The published site will have this structure: @@ -253,7 +228,7 @@ list = 'never' The published site will have this structure: -```html +```text public/ ├── books/ │ ├── book-1/ @@ -296,13 +271,13 @@ title = 'Internal' [cascade.build] render = 'never' list = 'never' -[cascade._target] +[cascade.target] environment = 'production' {{< /code-toggle >}} The production site will have this structure: -```html +```text public/ ├── reference/ │ ├── reference-1/ @@ -318,3 +293,11 @@ public/ │ └── index.html └── index.html ``` + +[`.Page.GetPage`]: /methods/page/getpage/ +[`.Site.GetPage`]: /methods/site/getpage/ +[`Permalink`]: /methods/resource/permalink/ +[`Publish`]: /methods/resource/publish/ +[`RelPermalink`]: /methods/resource/relpermalink/ +[page bundles]: /content-management/page-bundles/ +[page resources]: /content-management/page-resources/ diff --git a/content/en/content-management/comments.md b/content/en/content-management/comments.md index 721f1fe5a..fee4fb372 100644 --- a/content/en/content-management/comments.md +++ b/content/en/content-management/comments.md @@ -1,14 +1,8 @@ --- title: Comments description: Hugo ships with an internal Disqus template, but this isn't the only commenting system that will work with your new Hugo website. -categories: [content management] -keywords: [sections,content,organization] -menu: - docs: - parent: content-management - weight: 220 -weight: 220 -toc: true +categories: [] +keywords: [] aliases: [/extras/comments/] --- @@ -31,9 +25,9 @@ shortname = 'your-disqus-shortname' For many websites, this is enough configuration. However, you also have the option to set the following in the [front matter] of a single content file: -* `disqus_identifier` -* `disqus_title` -* `disqus_url` +- `disqus_identifier` +- `disqus_title` +- `disqus_url` ### Render Hugo's built-in Disqus partial template @@ -67,7 +61,7 @@ Open-source commenting systems: - [Talkyard](https://blog-comments.talkyard.io/) - [Utterances](https://utteranc.es/) -[configuration]: /getting-started/configuration/ +[configuration]: /configuration/ [disquspartial]: /templates/embedded/#disqus [disqussetup]: https://disqus.com/profile/signup/ [forum]: https://discourse.gohugo.io diff --git a/content/en/content-management/content-adapters.md b/content/en/content-management/content-adapters.md index 420d49d9d..3468bb728 100644 --- a/content/en/content-management/content-adapters.md +++ b/content/en/content-management/content-adapters.md @@ -1,14 +1,8 @@ --- title: Content adapters description: Create content adapters to dynamically add content when building your site. -categories: [content management] +categories: [] keywords: [] -menu: - docs: - parent: content-management - weight: 290 -weight: 290 -toc: true --- {{< new-in 0.126.0 />}} @@ -39,11 +33,11 @@ Each content adapter is named _content.gotmpl and uses the same [syntax] as temp Use these methods within a content adapter. -###### AddPage +### AddPage Adds a page to the site. -{{< code file=content/books/_content.gotmpl >}} +```go-html-template {file="content/books/_content.gotmpl"} {{ $content := dict "mediaType" "text/markdown" "value" "The _Hunchback of Notre Dame_ was written by Victor Hugo." @@ -55,13 +49,13 @@ Adds a page to the site. "title" "The Hunchback of Notre Dame" }} {{ .AddPage $page }} -{{< /code >}} +``` -###### AddResource +### AddResource Adds a page resource to the site. -{{< code file=content/books/_content.gotmpl >}} +```go-html-template {file="content/books/_content.gotmpl"} {{ with resources.Get "images/a.jpg" }} {{ $content := dict "mediaType" .MediaType.Type @@ -73,42 +67,41 @@ Adds a page resource to the site. }} {{ $.AddResource $resource }} {{ end }} -{{< /code >}} +``` Then retrieve the new page resource with something like: -{{< code file=layouts/_default/single.html >}} +```go-html-template {file="layouts/_default/single.html"} {{ with .Resources.Get "cover.jpg" }} {{ end }} -{{< /code >}} +``` -###### Site +### Site Returns the `Site` to which the pages will be added. -{{< code file=content/books/_content.gotmpl >}} +```go-html-template {file="content/books/_content.gotmpl"} {{ .Site.Title }} -{{< /code >}} +``` -{{% note %}} -Note that the `Site` returned isn't fully built when invoked from the content adapters; if you try to call methods that depends on pages, e.g. `.Site.Pages`, you will get an error saying "this method cannot be called before the site is fully initialized". -{{% /note %}} +> [!note] +> Note that the `Site` returned isn't fully built when invoked from the content adapters; if you try to call methods that depends on pages, e.g. `.Site.Pages`, you will get an error saying "this method cannot be called before the site is fully initialized". -###### Store +### Store Returns a persistent “scratch pad” to store and manipulate data. The main use case for this is to transfer values between executions when [EnableAllLanguages](#enablealllanguages) is set. See [examples](/methods/page/store/). -{{< code file=content/books/_content.gotmpl >}} +```go-html-template {file="content/books/_content.gotmpl"} {{ .Store.Set "key" "value" }} {{ .Store.Get "key" }} -{{< /code >}} +``` -###### EnableAllLanguages +### EnableAllLanguages -By default, Hugo executes the content adapter for the language defined by the _content.gotmpl file . Use this method to activate the content adapter for all languages. +By default, Hugo executes the content adapter for the language defined by the _content.gotmpl file. Use this method to activate the content adapter for all languages. -{{< code file=content/books/_content.gotmpl >}} +```go-html-template {file="content/books/_content.gotmpl"} {{ .EnableAllLanguages }} {{ $content := dict "mediaType" "text/markdown" @@ -121,7 +114,7 @@ By default, Hugo executes the content adapter for the language defined by the _c "title" "The Hunchback of Notre Dame" }} {{ .AddPage $page }} -{{< /code >}} +``` ## Page map @@ -141,11 +134,10 @@ Key|Description|Required `path`|The page's [logical path](g) relative to the content adapter. Do not include a leading slash or file extension.|:heavy_check_mark: `title`|The page title.|  -{{% note %}} -While `path` is the only required field, we recommend setting `title` as well. - -When setting the `path`, Hugo transforms the given string to a logical path. For example, setting `path` to `A B C` produces a logical path of `/section/a-b-c`. -{{% /note %}} +> [!note] +> While `path` is the only required field, we recommend setting `title` as well. +> +> When setting the `path`, Hugo transforms the given string to a logical path. For example, setting `path` to `A B C` produces a logical path of `/section/a-b-c`. ## Resource map @@ -160,18 +152,18 @@ Key|Description|Required `path`|The resources's [logical path](g) relative to the content adapter. Do not include a leading slash.|:heavy_check_mark: `title`|The resource title.|  -{{% note %}} -If the `content.value` is a string Hugo creates a new resource. If the `content.value` is a resource, Hugo obtains the value from the existing resource. - -When setting the `path`, Hugo transforms the given string to a logical path. For example, setting `path` to `A B C/cover.jpg` produces a logical path of `/section/a-b-c/cover.jpg`. -{{% /note %}} +> [!note] +> If the `content.value` is a string Hugo creates a new resource. If the `content.value` is a resource, Hugo obtains the value from the existing resource. +> +> When setting the `path`, Hugo transforms the given string to a logical path. For example, setting `path` to `A B C/cover.jpg` produces a logical path of `/section/a-b-c/cover.jpg`. ## Example Create pages from remote data, where each page represents a book review. -Step 1 -: Create the content structure. +### Step 1 + +Create the content structure. ```text content/ @@ -180,15 +172,15 @@ content/ └── _index.md ``` -Step 2 -: Inspect the remote data to determine how to map key-value pairs to front matter fields. +### Step 2 +Inspect the remote data to determine how to map key-value pairs to front matter fields.\ + -: +### Step 3 -Step 3 -: Create the content adapter. +Create the content adapter. -{{< code file=content/books/_content.gotmpl copy=true >}} +```go-html-template {file="content/books/_content.gotmpl" copy=true} {{/* Get remote data. */}} {{ $data := dict }} {{ $url := "https://gohugo.io/shared/examples/data/books.json" }} @@ -241,12 +233,13 @@ Step 3 {{ end }} {{ end }} -{{< /code >}} +``` -Step 4 -: Create a single template to render each book review. +### Step 4 -{{< code file=layouts/books/single.html copy=true >}} +Create a single template to render each book review. + +```go-html-template {file="layouts/books/single.html" copy=true} {{ define "main" }}

{{ .Title }}

@@ -273,7 +266,7 @@ Step 4 {{ .Content }} {{ end }} -{{< /code >}} +``` ## Multilingual sites diff --git a/content/en/content-management/cross-references.md b/content/en/content-management/cross-references.md deleted file mode 100644 index 66a77924f..000000000 --- a/content/en/content-management/cross-references.md +++ /dev/null @@ -1,148 +0,0 @@ ---- -title: Links and cross references -description: Shortcodes for creating links to documents. -categories: [content management] -keywords: [cross references,references,anchors,urls] -menu: - docs: - parent: content-management - weight: 170 -weight: 170 -toc: true -aliases: [/extras/crossreferences/] ---- - -The `ref` and `relref` shortcodes display the absolute and relative permalinks to a document, respectively. - -## Use of `ref` and `relref` - -The `ref` and `relref` shortcodes require a single argument: the path to a content document, with or without a file extension, with or without an anchor. Paths without a leading `/` are first resolved relative to the current page, then to the remainder of the site. - -```text -. -└── content - ├── about - | ├── _index.md - | └── credits.md - ├── pages - | ├── document1.md - | └── document2.md // has anchor #anchor - ├── products - | └── index.md - └── blog - └── my-post.md -``` - -The pages can be referenced as follows: - -```text -{{}} <-- From pages/document1.md, relative path -{{}} -{{}} -{{}} -{{}} <-- From pages/document2.md -{{}} <-- From anywhere, absolute path -{{}} -{{}} -{{}} -{{}} -{{}} -``` - -`index.md` can be reference either by its path or by its containing directory without the ending `/`. `_index.md` can be referenced only by its containing directory: - -```text -{{}} <-- References /about/_index.md -{{}} <-- Raises REF_NOT_FOUND error -{{}} <-- References /about/credits.md - -{{}} <-- References /products/index.md -{{}} <-- References /products/index.md -``` - -To generate a hyperlink using `ref` or `relref` in Markdown: - -```text -[About]({{}} "About Us") -``` - -Hugo emits an error or warning if a document cannot be uniquely resolved. The error behavior is configurable; see below. - -### Link to another language version - -Using `ref` or `relref` without specifying a language, will make the reference resolve to the language of the current content page. - -To link to another language version of a document, use this syntax: - -```text -{{}} -``` - -### Get another output format - -To link to another Output Format of a document, use this syntax: - -```text -{{}} -``` - -### Heading IDs - -When using Markdown document types, Hugo generates element IDs for every heading on a page. For example: - -```text -## Reference -``` - -produces this HTML: - -```html -

Reference

-``` - -Get the permalink to a heading by appending the ID to the path when using the `ref` or `relref` shortcodes: - -```text -{{}} -{{}} -``` - -Generate a custom heading ID by including an attribute. For example: - -```text -## Reference A {#foo} -## Reference B {id="bar"} -``` - -produces this HTML: - -```html -

Reference A

-

Reference B

-``` - -Hugo will generate unique element IDs if the same heading appears more than once on a page. For example: - -```text -## Reference -## Reference -## Reference -``` - -produces this HTML: - -```html -

Reference

-

Reference

-

Reference

-``` - -## Ref and RelRef Configuration - -The behavior can be configured in `hugo.toml`: - -refLinksErrorLevel ("ERROR") -: When using `ref` or `relref` to resolve page links and a link cannot be resolved, it will be logged with this log level. Valid values are `ERROR` (default) or `WARNING`. Any `ERROR` will fail the build (`exit -1`). - -refLinksNotFoundURL -: URL to be used as a placeholder when a page reference cannot be found in `ref` or `relref`. Is used as-is. diff --git a/content/en/content-management/data-sources.md b/content/en/content-management/data-sources.md index 1237e4f4d..3fc98b36a 100644 --- a/content/en/content-management/data-sources.md +++ b/content/en/content-management/data-sources.md @@ -1,14 +1,8 @@ --- title: Data sources description: Use local and remote data sources to augment or create content. -categories: [content management] -keywords: [data,json,toml,yaml,xml] -menu: - docs: - parent: content-management - weight: 280 -weight: 280 -toc: true +categories: [] +keywords: [] aliases: [/extras/datafiles/,/extras/datadrivencontent/,/doc/datafiles/,/templates/data-templates/] --- @@ -22,9 +16,8 @@ The `data` directory in the root of your project may contain one or more data fi Hugo also merges data directories from themes and modules into this single data structure, where the `data` directory in the root of your project takes precedence. -{{% note %}} -Hugo reads the combined data structure into memory and keeps it there for the entire build. For data that is infrequently accessed, use global or page resources instead. -{{% /note %}} +> [!note] +> Hugo reads the combined data structure into memory and keeps it there for the entire build. For data that is infrequently accessed, use global or page resources instead. Theme and module authors may wish to namespace their data files to prevent collisions. For example: @@ -35,14 +28,11 @@ project/ └── foo.json ``` -{{% note %}} -Do not place CSV files in the `data` directory. Access CSV files as page, global, or remote resources. -{{% /note %}} +> [!note] +> Do not place CSV files in the `data` directory. Access CSV files as page, global, or remote resources. See the documentation for the [`Data`] method on a `Site` object for details and examples. -[`Data`]: /methods/site/data/ - ## Global resources Use the `resources.Get` and `transform.Unmarshal` functions to access data files that exist as global resources. @@ -65,17 +55,17 @@ See the [`transform.Unmarshal`](/functions/transform/unmarshal/#remote-resource) Use data sources to augment existing content. For example, create a shortcode to render an HTML table from a global CSV resource. -{{< code file=assets/pets.csv >}} +```csv {file="assets/pets.csv"} "name","type","breed","age" "Spot","dog","Collie","3" "Felix","cat","Malicious","7" -{{< /code >}} +``` -{{< code file=content/example.md lang=text >}} +```text {file="content/example.md"} {{}} -{{< /code >}} +``` -{{< code file=layouts/shortcodes/csv-to-table.html >}} +```go-html-template {file="layouts/shortcodes/csv-to-table.html"} {{ with $file := .Get 0 }} {{ with resources.Get $file }} {{ with . | transform.Unmarshal }} @@ -104,7 +94,7 @@ Use data sources to augment existing content. For example, create a shortcode to {{ else }} {{ errorf "The %q shortcode requires one positional argument, the path to the CSV file relative to the assets directory. See %s" .Name .Position }} {{ end }} -{{< /code >}} +``` Hugo renders this to: @@ -117,4 +107,5 @@ Felix|cat|Malicious|7 Use [content adapters] to create new content. +[`Data`]: /methods/site/data/ [content adapters]: /content-management/content-adapters/ diff --git a/content/en/content-management/diagrams.md b/content/en/content-management/diagrams.md index f9f3cd30f..0070ced59 100644 --- a/content/en/content-management/diagrams.md +++ b/content/en/content-management/diagrams.md @@ -1,23 +1,14 @@ --- title: Diagrams description: Use fenced code blocks and Markdown render hooks to include diagrams in your content. -categories: [content management] -keywords: [diagrams,drawing] -menu: - docs: - parent: content-management - weight: 260 -weight: 260 -toc: true +categories: [] +keywords: [] --- ## GoAT diagrams (ASCII) Hugo natively supports [GoAT] diagrams with an [embedded code block render hook]. This means that this code block: -[GoAT]: https://github.com/bep/goat -[embedded code block render hook]: {{% eturl render-codeblock-goat %}} - ````txt ```goat . . . .--- 1 .-- 1 / 1 @@ -48,18 +39,16 @@ Will be rendered as: Hugo does not provide a built-in template for Mermaid diagrams. Create your own using a [code block render hook]: -[code block render hook]: /render-hooks/code-blocks/ - -{{< code file=layouts/_default/_markup/render-codeblock-mermaid.html >}} +```go-html-template {file="layouts/_default/_markup/render-codeblock-mermaid.html" copy=true} 
-  {{- .Inner | htmlEscape | safeHTML }}
+  {{ .Inner | htmlEscape | safeHTML }}
{{ .Page.Store.Set "hasMermaid" true }} -{{< /code >}} +``` -And then include this snippet at the bottom of the content template: +Then include this snippet at the _bottom_ of your base template, before the closing `body` tag: -```go-html-template +```go-html-template {file="layouts/_default/baseof.html" copy=true} {{ if .Store.Get "hasMermaid" }} -{{< /code >}} +``` The delimiters above must match the delimiters in your site configuration. -###### Step 3 +### Step 3 Conditionally call the partial template from the base template. -{{< code file=layouts/_default/baseof.html >}} +```go-html-template {file="layouts/_default/baseof.html"} ... {{ if .Param "math" }} @@ -127,15 +116,15 @@ Conditionally call the partial template from the base template. {{ end }} ... -{{< /code >}} +``` 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. -###### Step 4 +### Step 4 Include mathematical equations and expressions in Markdown using LaTeX markup. -{{< code file=content/math-examples.md copy=true >}} +```text {file="content/math-examples.md" copy=true} This is an inline \(a^*=x-b^*\) equation. These are block equations: @@ -157,7 +146,7 @@ $$ a^*=x-b^* $$ $$ a^*=x-b^* $$ -{{< /code >}} +``` 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: @@ -178,23 +167,21 @@ If you add the `$...$` delimiter pair to your configuration and JavaScript, you A \\$5 bill _saved_ is a \\$5 bill _earned_. ``` -{{% note %}} -If you use the `$...$` delimiter pair for inline equations, and occasionally use the `$` symbol outside of math contexts, you must use MathJax instead of KaTeX to avoid unintended formatting caused by [this KaTeX limitation](https://github.com/KaTeX/KaTeX/issues/437). -{{% /note %}} +> [!note] +> If you use the `$...$` delimiter pair for inline equations, and occasionally use the `$` symbol outside of math contexts, you must use MathJax instead of KaTeX to avoid unintended formatting caused by [this KaTeX limitation](https://github.com/KaTeX/KaTeX/issues/437). ## Engines MathJax and KaTeX are open-source JavaScript display engines. Both engines are fast, but at the time of this writing MathJax v3.2.2 is slightly faster than KaTeX v0.16.11. -{{% note %}} -If you use the `$...$` delimiter pair for inline equations, and occasionally use the `$` symbol outside of math contexts, you must use MathJax instead of KaTeX to avoid unintended formatting caused by [this KaTeX limitation](https://github.com/KaTeX/KaTeX/issues/437). - -See the [inline delimiters](#inline-delimiters) section for details. -{{% /note %}} +> [!note] +> If you use the `$...$` delimiter pair for inline equations, and occasionally use the `$` symbol outside of math contexts, you must use MathJax instead of KaTeX to avoid unintended formatting caused by [this KaTeX limitation](https://github.com/KaTeX/KaTeX/issues/437). +> +>See the [inline delimiters](#inline-delimiters) section for details. To use KaTeX instead of MathJax, replace the partial template from [Step 2] with this: -{{< code file=layouts/partials/math.html copy=true >}} +```go-html-template {file="layouts/partials/math.html" copy=true} -{{< /code >}} +``` The delimiters above must match the delimiters in your site configuration. @@ -242,10 +229,10 @@ $$C_p[\ce{H2O(l)}] = \pu{75.3 J // mol K}$$ As shown in [Step 2] above, MathJax supports chemical equations without additional configuration. To add chemistry support to KaTeX, enable the mhchem extension as described in the KaTeX [documentation](https://katex.org/docs/libs). +[`transform.ToMath`]: /functions/transform/tomath/ [KaTeX]: https://katex.org/ [LaTeX]: https://www.latex-project.org/ [MathJax]: https://www.mathjax.org/ -[Step 1]: #step-1 +[passthrough extension]: /configuration/markup/#passthrough [Step 2]: #step-2 [Step 3]: #step-3 -[passthrough extension]: /getting-started/configuration-markup/#passthrough diff --git a/content/en/content-management/menus.md b/content/en/content-management/menus.md index 15cf505ea..ab1bcbfa1 100644 --- a/content/en/content-management/menus.md +++ b/content/en/content-management/menus.md @@ -1,14 +1,8 @@ --- title: Menus -description: Create menus by defining entries, localizing each entry, and rendering the resulting data structure. -categories: [content management] -keywords: [menus] -menu: - docs: - parent: content-management - weight: 190 -weight: 190 -toc: true +description: Create menus by defining entries, localizing each entry, and rendering the resulting data structure. +categories: [] +keywords: [] aliases: [/extras/menus/] --- @@ -28,9 +22,8 @@ There are three ways to define menu entries: 1. In front matter 1. In site 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. -{{% /note %}} +> [!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 @@ -62,39 +55,16 @@ menus = ['main','footer'] Access the entry with `site.Menus.main` and `site.Menus.footer` in your templates. See [menu templates] for details. -{{% note %}} -The configuration key in the examples above is `menus`. The `menu` (singular) configuration key is an alias for `menus`. -{{% /note %}} +> [!note] +> The configuration key in the examples above is `menus`. The `menu` (singular) configuration key is an alias for `menus`. -### Properties {#properties-front-matter} +### Properties Use these properties when defining menu entries in front matter: -identifier -: (`string`) Required when two or more menu entries have the same `name`, or when localizing the `name` using translation tables. Must start with a letter, followed by letters, digits, or underscores. +{{% include "/_common/menu-entry-properties.md" %}} -name -: (`string`) The text to display when rendering the menu entry. - -params -: (`map`) User-defined properties for the menu entry. - -parent -: (`string`) The `identifier` of the parent menu entry. If `identifier` is not defined, use `name`. Required for child entries in a nested menu. - -post -: (`string`) The HTML to append when rendering the menu entry. - -pre -: (`string`) The HTML to prepend when rendering the menu entry. - -title -: (`string`) The HTML `title` attribute of the rendered menu entry. - -weight -: (`int`) A non-zero integer indicating the entry's position relative the root of the menu, or to its parent for a child entry. Lighter entries float to the top, while heavier entries sink to the bottom. - -### Example {#example-front-matter} +### Example This front matter menu entry demonstrates some of the available properties: @@ -112,111 +82,7 @@ Access the entry with `site.Menus.main` in your templates. See [menu templates] ## Define in site configuration -To define entries for the "main" menu: - -{{< code-toggle file=hugo >}} -[[menus.main]] -name = 'Home' -pageRef = '/' -weight = 10 - -[[menus.main]] -name = 'Products' -pageRef = '/products' -weight = 20 - -[[menus.main]] -name = 'Services' -pageRef = '/services' -weight = 30 -{{< /code-toggle >}} - -This creates a menu structure that you can access with `site.Menus.main` in your templates. See [menu templates] for details. - -To define entries for the "footer" menu: - -{{< code-toggle file=hugo >}} -[[menus.footer]] -name = 'Terms' -pageRef = '/terms' -weight = 10 - -[[menus.footer]] -name = 'Privacy' -pageRef = '/privacy' -weight = 20 -{{< /code-toggle >}} - -This creates a menu structure that you can access with `site.Menus.footer` in your templates. See [menu templates] for details. - -{{% note %}} -The configuration key in the examples above is `menus`. The `menu` (singular) configuration key is an alias for `menus`. -{{% /note %}} - -### Properties {#properties-site-configuration} - -{{% note %}} -The [properties available to entries defined in front matter] are also available to entries defined in site configuration. - -[properties available to entries defined in front matter]: /content-management/menus/#properties-front-matter -{{% /note %}} - -Each menu entry defined in site configuration requires two or more properties: - -- Specify `name` and `pageRef` for internal links -- Specify `name` and `url` for external links - -pageRef -: (`string`) The logical path of the target page, relative to the `content` directory. Omit language code and file extension. Required for *internal* links. - -Kind|pageRef -:--|:-- -home|`/` -page|`/books/book-1` -section|`/books` -taxonomy|`/tags` -term|`/tags/foo` - -url -: (`string`) Required for *external* links. - -### Example {#example-site-configuration} - -This nested menu demonstrates some of the available properties: - -{{< code-toggle file=hugo >}} -[[menus.main]] -name = 'Products' -pageRef = '/products' -weight = 10 - -[[menus.main]] -name = 'Hardware' -pageRef = '/products/hardware' -parent = 'Products' -weight = 1 - -[[menus.main]] -name = 'Software' -pageRef = '/products/software' -parent = 'Products' -weight = 2 - -[[menus.main]] -name = 'Services' -pageRef = '/services' -weight = 20 - -[[menus.main]] -name = 'Hugo' -pre = '' -url = 'https://gohugo.io/' -weight = 30 -[menus.main.params] -rel = 'external' -{{< /code-toggle >}} - -This creates a menu structure that you can access with `site.Menus.main` in your templates. See [menu templates] for details. +See [configure menus](/configuration/menus/). ## Localize @@ -226,7 +92,6 @@ Hugo provides two methods to localize your menu entries. See [multilingual]. See [menu templates]. -[localize]: /content-management/multilingual/#menus [menu templates]: /templates/menu/ [multilingual]: /content-management/multilingual/#menus [template]: /templates/menu/ diff --git a/content/en/content-management/multilingual.md b/content/en/content-management/multilingual.md index 8233185d5..d419f4381 100644 --- a/content/en/content-management/multilingual.md +++ b/content/en/content-management/multilingual.md @@ -2,217 +2,14 @@ title: Multilingual mode linkTitle: Multilingual description: Localize your project for each language and region, including translations, images, dates, currencies, numbers, percentages, and collation sequence. Hugo's multilingual framework supports single-host and multihost configurations. -categories: [content management] -keywords: [multilingual,i18n,internationalization] -menu: - docs: - parent: content-management - weight: 230 -weight: 230 -toc: true +categories: [] +keywords: [] aliases: [/content/multilingual/,/tutorials/create-a-multilingual-site/] --- -## Configure languages +## Configuration -This is the default language configuration: - -{{< code-toggle config=languages />}} - -In the above, `en` is the language key. - -Language keys must conform to the syntax described in [RFC 5646]. For example: - -- `en` -- `en-US` - -Artificial languages with private use subtags as defined in [RFC 5646 § 2.2.7] are also supported. Omit the `art-x-` prefix from the language key. For example: - -- `hugolang` - -{{% note %}} -Private use subtags must not exceed 8 alphanumeric characters. -{{% /note %}} - -[RFC 5646]: https://datatracker.ietf.org/doc/html/rfc5646#section-2.1 -[RFC 5646 § 2.2.7]: https://datatracker.ietf.org/doc/html/rfc5646#section-2.2.7 - -This is an example of a site configuration for a multilingual project. Any key not defined in a `languages` object will fall back to the global value in the root of your site configuration. - -{{< code-toggle file=hugo >}} -defaultContentLanguage = 'de' -defaultContentLanguageInSubdir = true - -[languages.de] -contentDir = 'content/de' -disabled = false -languageCode = 'de-DE' -languageDirection = 'ltr' -languageName = 'Deutsch' -title = 'Projekt Dokumentation' -weight = 1 - -[languages.de.params] -subtitle = 'Referenz, Tutorials und Erklärungen' - -[languages.en] -contentDir = 'content/en' -disabled = false -languageCode = 'en-US' -languageDirection = 'ltr' -languageName = 'English' -title = 'Project Documentation' -weight = 2 - -[languages.en.params] -subtitle = 'Reference, Tutorials, and Explanations' -{{< /code-toggle >}} - -defaultContentLanguage -: (`string`) The project's default language key, conforming to the syntax described in [RFC 5646]. This value must match one of the defined language keys. Examples: - -- `en` -- `en-GB` -- `pt-BR` - -defaultContentLanguageInSubdir -: (`bool`) If `true`, Hugo renders the default language site in a subdirectory matching the `defaultContentLanguage`. Default is `false`. - -contentDir -: (`string`) The `content` directory for this language. Omit if [translating by file name]. - -disabled -: (`bool`) If `true`, Hugo will not render content for this language. Default is `false`. - -languageCode -: (`string`) The language tag as described in [RFC 5646]. This value does not affect localization or URLs. Hugo uses this value to populate the `language` element in the [built-in RSS template], and the `lang` attribute of the `html` element in the [built-in alias template]. Examples: - -- `en` -- `en-GB` -- `pt-BR` - -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. - -languageName -: (`string`) The language name, typically used when rendering a language switcher. - -title -: (`string`) The site title for this language (optional). - -weight -: (`int`) The language weight. When set to a non-zero value, this is the primary sort criteria for this language. - -[`dir`]: https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/dir -[built-in RSS template]: https://github.com/gohugoio/hugo/blob/master/tpl/tplimpl/embedded/templates/_default/rss.xml -[built-in alias template]: https://github.com/gohugoio/hugo/blob/master/tpl/tplimpl/embedded/templates/alias.html -[RFC 5646]: https://datatracker.ietf.org/doc/html/rfc5646#section-2.1 -[translating by file name]: #translation-by-file-name - -### Site parameters - -Set language-specific site parameters under each language's `params` key: - -{{< code-toggle file=hugo >}} -[params] -color = "red" - -[languages] - [languages.de] - languageCode = 'de-DE' - title = 'Projekt Dokumentation' - weight = 1 - [languages.de.params] - color = 'blue' - subtitle = 'Referenz, Tutorials und Erklärungen' - [languages.en] - languageCode = 'en-US' - title = 'Project Documentation' - weight = 2 - [languages.en.params] - subtitle = 'Reference, Tutorials, and Explanations' -{{< /code-toggle >}} - -When building the English site: - -```go-html-template -{{ site.Params.color }} --> red -{{ site.Params.subtitle }} --> Reference, Tutorials, and Explanations -``` - -When building the German site: - -```go-html-template -{{ site.Params.color }} --> blue -{{ site.Params.subtitle }} --> 'Referenz, Tutorials und Erklärungen' -``` - -### Disable a language - -To disable a language within a `languages` object in your site configuration: - -{{< code-toggle file=hugo >}} -[languages.es] -disabled = true -{{< /code-toggle >}} - -To disable one or more languages in the root of your site configuration: - -{{< code-toggle file=hugo >}} -disableLanguages = ["es", "fr"] -{{< /code-toggle >}} - -To disable one or more languages using an environment variable: - -```sh -HUGO_DISABLELANGUAGES="es fr" hugo -``` - -Note that you cannot disable the default content language. - -### Configure multilingual multihost - -Hugo supports multiple languages in a multihost configuration. This means you can configure a `baseURL` per `language`. - -{{% note %}} -If a `baseURL` is set on the `language` level, then all languages must have one and they must all be different. -{{% /note %}} - -Example: - -{{< code-toggle file=hugo >}} -[languages] - [languages.en] - baseURL = 'https://en.example.org/' - languageName = 'English' - title = 'In English' - weight = 2 - [languages.fr] - baseURL = 'https://fr.example.org' - languageName = 'Français' - title = 'En Français' - weight = 1 -{{}} - -With the above, the two sites will be generated into `public` with their own root: - -```text -public -├── en -└── fr -``` - -**All URLs (i.e `.Permalink` etc.) will be generated from that root. So the English home page above will have its `.Permalink` set to `https://example.org/`.** - -When you run `hugo server` we will start multiple HTTP servers. You will typically see something like this in the console: - -```text -Web Server is available at 127.0.0.1:1313 (bind address 127.0.0.1) fr -Web Server is available at 127.0.0.1:1314 (bind address 127.0.0.1) en -Press Ctrl+C to stop -``` - -Live reload and `--navigateToChanged` between the servers work as expected. +See [configure languages](/configuration/languages/). ## Translate your content @@ -232,9 +29,8 @@ Their language is __assigned__ according to the language code added as a __suffi By having the same **path and base file name**, the content pieces are __linked__ together as translated pages. -{{% note %}} -If a file has no language code, it will be assigned the default language. -{{% /note %}} +> [!note] +> If a file has no language code, it will be assigned the default language. ### Translation by content directory @@ -276,7 +72,7 @@ Considering the following example: 1. `/content/om.nn.md` 1. `/content/presentation/a-propos.fr.md` -{{< code-toggle >}} +{{< code-toggle file=hugo >}} translationKey: "about" {{< /code-toggle >}} @@ -291,9 +87,6 @@ To localize URLs: - For a regular page, set either [`slug`] or [`url`] in front matter - For a section page, set [`url`] in front matter -[`slug`]: /content-management/urls/#slug -[`url`]: /content-management/urls/#url - For example, a French translation can have its own localized slug. {{< code-toggle file=content/about.fr.md fm=true >}} @@ -305,24 +98,23 @@ At render, Hugo will build both `/about/` and `/fr/a-propos/` without affecting ### Page bundles -To avoid the burden of having to duplicate files, each Page Bundle inherits the resources of its linked translated pages' bundles except for the content files (Markdown files, HTML files etc...). +To avoid the burden of having to duplicate files, each Page Bundle inherits the resources of its linked translated pages' bundles except for the content files (Markdown files, HTML files etc.). Therefore, from within a template, the page will have access to the files from all linked pages' bundles. If, across the linked bundles, two or more files share the same basename, only one will be included and chosen as follows: -* File from current language bundle, if present. -* First file found across bundles by order of language `Weight`. +- File from current language bundle, if present. +- First file found across bundles by order of language `Weight`. -{{% note %}} -Page Bundle resources follow the same language assignment logic as content files, both by file name (`image.jpg`, `image.fr.jpg`) and by directory (`english/about/header.jpg`, `french/about/header.jpg`). -{{%/ note %}} +> [!note] +> Page Bundle resources follow the same language assignment logic as content files, both by file name (`image.jpg`, `image.fr.jpg`) and by directory (`english/about/header.jpg`, `french/about/header.jpg`). ## Reference translated content To create a list of links to translated content, use a template similar to the following: -{{< code file=layouts/partials/i18nlist.html >}} +```go-html-template {file="layouts/partials/i18nlist.html"} {{ if .IsTranslated }}

{{ i18n "translations" }}

    @@ -333,7 +125,7 @@ To create a list of links to translated content, use a template similar to the f {{ end }}
{{ end }} -{{< /code >}} +``` The above can be put in a `partial` (i.e., inside `layouts/partials/`) and included in any template. It will not print anything if there are no translations for a given page. @@ -343,20 +135,18 @@ The above also uses the [`i18n` function][i18func] described in the next section `.AllTranslations` on a `Page` can be used to list all translations, including the page itself. On the home page it can be used to build a language navigator: -{{< code file=layouts/partials/allLanguages.html >}} +```go-html-template {file="layouts/partials/allLanguages.html"} -{{< /code >}} +``` ## Translation of strings See the [`lang.Translate`] template function. -[`lang.Translate`]: /functions/lang/translate - ## Localization The following localization examples assume your site's primary language is English, with translations to French and German. @@ -384,7 +174,7 @@ weight = 3 With this front matter: -{{< code-toggle >}} +{{< code-toggle file=hugo >}} date = 2021-11-03T12:34:56+01:00 {{< /code-toggle >}} @@ -538,8 +328,6 @@ pageRef = '/services' weight = 20 {{< /code-toggle >}} -[configuration directory]: /getting-started/configuration/#configuration-directory - ### Use translation tables When rendering the text that appears in menu each entry, the [example menu template] does this: @@ -577,20 +365,14 @@ products = 'Produkte' services = 'Leistungen' {{< / code-toggle >}} -[example menu template]: /templates/menu/#example -[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 - ## Missing translations If a string does not have a translation for the current language, Hugo will use the value from the default language. If no default value is set, an empty string will be shown. While translating a Hugo website, it can be handy to have a visual indicator of missing translations. The [`enableMissingTranslationPlaceholders` configuration option][config] will flag all untranslated strings with the placeholder `[i18n] identifier`, where `identifier` is the id of the missing translation. -{{% note %}} -Hugo will generate your website with these missing translation placeholders. It might not be suitable for production environments. -{{% /note %}} +> [!note] +> Hugo will generate your website with these missing translation placeholders. It might not be suitable for production environments. For merging of content from other languages (i.e. missing content translations), see [lang.Merge]. @@ -605,8 +387,8 @@ i18n|MISSING_TRANSLATION|en|wordCount To support Multilingual mode in your themes, some considerations must be taken for the URLs in the templates. If there is more than one language, URLs must meet the following criteria: -* Come from the built-in `.Permalink` or `.RelPermalink` -* Be constructed with the [`relLangURL`] or [`absLangURL`] template function, or be prefixed with `{{ .LanguagePrefix }}` +- Come from the built-in `.Permalink` or `.RelPermalink` +- Be constructed with the [`relLangURL`] or [`absLangURL`] template function, or be prefixed with `{{ .LanguagePrefix }}` If there is more than one language defined, the `LanguagePrefix` method will return `/en` (or whatever the current language is). If not enabled, it will be an empty string (and is therefore harmless for single-language Hugo websites). @@ -626,19 +408,22 @@ hugo new content content/en/post/test.md hugo new content content/de/post/test.md ``` -[`abslangurl`]: /functions/urls/abslangurl/ -[config]: /getting-started/configuration/ -[go-i18n-source]: https://github.com/nicksnyder/go-i18n -[go-i18n]: https://github.com/nicksnyder/go-i18n -[Hugo Multilingual Part 1: Content translation]: https://regisphilibert.com/blog/2018/08/hugo-multilingual-part-1-managing-content-translation/ +[`absLangURL`]: /functions/urls/abslangurl/ +[`lang.Translate`]: /functions/lang/translate +[`relLangURL`]: /functions/urls/rellangurl/ +[`slug`]: /content-management/urls/#slug +[`time.Format`]: /functions/time/format/ +[`url`]: /content-management/urls/#url +[automatically]: /content-management/menus/#define-automatically +[config]: /configuration/ +[configuration directory]: /configuration/introduction/#configuration-directory +[example menu template]: /templates/menu/#example [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/ -[menus]: /content-management/menus/ -[OS environment]: /getting-started/configuration/#configure-with-environment-variables -[`rellangurl`]: /functions/urls/rellangurl/ -[`time.Format`]: /functions/time/format/ diff --git a/content/en/content-management/organization/1-featured-content-bundles.png b/content/en/content-management/organization/1-featured-content-bundles.png deleted file mode 100644 index 501e671e2f4cefe1789f168a7eee86222dff82ea..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 34394 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 Zo%#X@Iw*G^7J@!RR!T{-Sp22`{{lr$7?1z} diff --git a/content/en/content-management/organization/index.md b/content/en/content-management/organization/index.md index 99a3224bf..a7682bfad 100644 --- a/content/en/content-management/organization/index.md +++ b/content/en/content-management/organization/index.md @@ -2,14 +2,8 @@ title: Content organization linkTitle: Organization description: Hugo assumes that the same structure that works to organize your source content is used to organize the rendered site. -categories: [content management,fundamentals] -keywords: [sections,content,organization,bundle,resources] -menu: - docs: - parent: content-management - weight: 20 -weight: 20 -toc: true +categories: [] +keywords: [] aliases: [/content/sections/] --- @@ -71,11 +65,10 @@ The following demonstrates the relationships between your content organization a ### Index pages: `_index.md` -`_index.md` has a special role in Hugo. It allows you to add front matter and content to `home`, `section`, `taxonomy`, and `term` pages. +`_index.md` has a special role in Hugo. It allows you to add front matter and content to `home`, `section`, `taxonomy`, and `term` pages. -{{% note %}} -**Tip:** You can get a reference to the content and metadata in `_index.md` using the [`.Site.GetPage` function](/methods/page/getpage). -{{% /note %}} +> [!note] +> Access the content and metadata within an `_index.md` file by invoking the `GetPage` method on a `Site` or `Page` object. You can create one `_index.md` for your home page and one in each of your content sections, taxonomies, and terms. The following shows typical placement of an `_index.md` that would contain content and front matter for a `posts` section list page on a Hugo website: @@ -143,20 +136,16 @@ The `slug` is the last segment of the URL path, defined by the file name and opt ### `path` -A content's `path` is determined by the section's path to the file. The file `path` +A content's `path` is determined by the section's path to the file. The file `path`: -* is based on the path to the content's location AND -* does not include the slug +- Is based on the path to the content's location AND +- Does not include the slug ### `url` The `url` is the entire URL path, defined by the file path and optionally overridden by a `url` value in front matter. See [URL Management](/content-management/urls/#slug) for details. -[config]: /getting-started/configuration/ -[formats]: /content-management/formats/ -[front matter]: /content-management/front-matter/ -[getpage]: /methods/page/getpage/ +[config]: /configuration/ [pretty]: /content-management/urls/#appearance [sections]: /content-management/sections/ [single template]: /templates/types/#single -[urls]: /content-management/urls/ diff --git a/content/en/content-management/page-bundles.md b/content/en/content-management/page-bundles.md index 3638f2fb5..f6a5cf771 100644 --- a/content/en/content-management/page-bundles.md +++ b/content/en/content-management/page-bundles.md @@ -1,14 +1,8 @@ --- title: Page bundles description: Use page bundles to logically associate one or more resources with content. -categories: [content management] -keywords: [page,bundle,leaf,branch] -menu : - docs: - parent: content-management - weight: 30 -weight: 30 -toc: true +categories: [] +keywords: [] --- ## Introduction @@ -33,11 +27,10 @@ leaf bundle : A _leaf bundle_ is a directory that contains an `index.md` file and zero or more resources. Analogous to a physical leaf, a leaf bundle is at the end of a branch. It has no descendants. branch bundle -: A _branch bundle_ is a directory that contains an `_index.md` file and zero or more resources. Analogous to a physical branch, a branch bundle may have descendants including leaf bundles and other branch bundles. Top level directories with or without `_index.md` files are also branch bundles. This includes the home page. +: A _branch bundle_ is a directory that contains an `_index.md` file and zero or more resources. Analogous to a physical branch, a branch bundle may have descendants including leaf bundles and other branch bundles. Top-level directories with or without `_index.md` files are also branch bundles. This includes the home page. -{{% note %}} -In the definitions above and the examples below, the extension of the index file depends on the [content format](g). For example, use `index.md` for Markdown content, `index.html` for HTML content, `index.adoc` for AsciiDoc content, etc. -{{% /note %}} +> [!note] +> In the definitions above and the examples below, the extension of the index file depends on the [content format](g). For example, use `index.md` for Markdown content, `index.html` for HTML content, `index.adoc` for AsciiDoc content, etc. ## Comparison @@ -53,12 +46,6 @@ Page bundle characteristics vary by bundle type. | Resource location | Adjacent to the index file or in a nested subdirectory | Same as a leaf bundles, but excludes descendant bundles | | [Resource types](g) | `page`, `image`, `video`, etc. | all but `page` | -[single]: /templates/types/#single -[home]: /templates/types/#home -[section]: /templates/types/#section -[taxonomy]: /templates/types/#taxonomy -[term]: /templates/types/#term - Files with [resource type](g) `page` include content written in Markdown, HTML, AsciiDoc, Pandoc, reStructuredText, and Emacs Org Mode. In a leaf bundle, excluding the index file, these files are only accessible as page resources. In a branch bundle, these files are only accessible as content pages. ## Leaf bundles @@ -94,13 +81,13 @@ about my-post : This leaf bundle contains an index file, two resources of [resource type](g) `page`, and two resources of resource type `image`. -- content-1, content-2 + - content-1, content-2 - These are resources of resource type `page`, accessible via the [`Resources`] method on the `Page` object. Hugo will not render these as individual pages. + These are resources of resource type `page`, accessible via the [`Resources`] method on the `Page` object. Hugo will not render these as individual pages. -- image-1, image-2 + - image-1, image-2 - These are resources of resource type `image`, accessible via the `Resources` method on the `Page` object + These are resources of resource type `image`, accessible via the `Resources` method on the `Page` object my-other-post : This leaf bundle does not contain any page resources. @@ -108,13 +95,12 @@ my-other-post another-leaf-bundle : This leaf bundle does not contain any page resources. -{{% note %}} -Create leaf bundles at any depth within the `content` directory, but a leaf bundle may not contain another bundle. Leaf bundles do not have descendants. -{{% /note %}} +> [!note] +> Create leaf bundles at any depth within the `content` directory, but a leaf bundle may not contain another bundle. Leaf bundles do not have descendants. ## Branch bundles -A _branch bundle_ is a directory that contains an `_index.md` file and zero or more resources. Analogous to a physical branch, a branch bundle may have descendants including leaf bundles and other branch bundles. Top level directories with or without `_index.md` files are also branch bundles. This includes the home page. +A _branch bundle_ is a directory that contains an `_index.md` file and zero or more resources. Analogous to a physical branch, a branch bundle may have descendants including leaf bundles and other branch bundles. Top-level directories with or without `_index.md` files are also branch bundles. This includes the home page. ```text content/ @@ -142,9 +128,8 @@ branch-bundle-1 branch-bundle-2 : This branch bundle contains an index file and a leaf bundle. -{{% note %}} -Create branch bundles at any depth within the `content` directory. Branch bundles may have descendants. -{{% /note %}} +> [!note] +> Create branch bundles at any depth within the `content` directory. Branch bundles may have descendants. ## Headless bundles @@ -152,4 +137,9 @@ Use [build options] in front matter to create an unpublished leaf or branch bund [`Resources`]: /methods/page/resources/ [build options]: /content-management/build-options/ +[home]: /templates/types/#home [page resources]: /content-management/page-resources/ +[section]: /templates/types/#section +[single]: /templates/types/#single +[taxonomy]: /templates/types/#taxonomy +[term]: /templates/types/#term diff --git a/content/en/content-management/page-resources.md b/content/en/content-management/page-resources.md index 84c3309cd..204ca5301 100644 --- a/content/en/content-management/page-resources.md +++ b/content/en/content-management/page-resources.md @@ -1,14 +1,8 @@ --- title: Page resources description: Use page resources to logically associate assets with a page. -categories: [content management] -keywords: [bundle,content,resources] -menu: - docs: - parent: content-management - weight: 80 -weight: 80 -toc: true +categories: [] +keywords: [] --- Page resources are only accessible from [page bundles](/content-management/page-bundles), those directories with `index.md` or @@ -46,13 +40,7 @@ Use any of these methods on a `Page` object to capture page resources: - [`Resources.GetMatch`] - [`Resources.Match`] - Once you have captured a resource, use any of the applicable [`Resource`] methods to return a value or perform an action. - -[`Resource`]: /methods/resource -[`Resources.ByType`]: /methods/page/resources#bytype -[`Resources.GetMatch`]: /methods/page/resources#getmatch -[`Resources.Get`]: /methods/page/resources#get -[`Resources.Match`]: /methods/page/resources#match + Once you have captured a resource, use any of the applicable [`Resource`] methods to return a value or perform an action. The following examples assume this content structure: @@ -120,16 +108,14 @@ List the titles in the data file, and throw an error if the file does not exist. The page resources' metadata is managed from the corresponding page's front matter with an array/table parameter named `resources`. You can batch assign values using [wildcards](https://tldp.org/LDP/GNU-Linux-Tools-Summary/html/x11655.htm). -{{% note %}} -Resources of type `page` get `Title` etc. from their own front matter. -{{% /note %}} +> [!note] +> Resources of type `page` get `Title` etc. from their own front matter. name : (`string`) Sets the value returned in `Name`. -{{% note %}} -The methods `Match`, `Get` and `GetMatch` use `Name` to match the resources. -{{% /note %}} +> [!note] +> The methods `Match`, `Get` and `GetMatch` use `Name` to match the resources. title : (`string`) Sets the value returned in `Title` @@ -173,9 +159,8 @@ From the example above: - All `PDF` files will get a new `Name`. The `name` parameter contains a special placeholder [`:counter`](#the-counter-placeholder-in-name-and-title), so the `Name` will be `pdf-file-1`, `pdf-file-2`, `pdf-file-3`. - Every docx in the bundle will receive the `word` icon. -{{% note %}} -The order matters; only the first set values of the `title`, `name` and `params` keys will be used. Consecutive parameters will be set only for the ones not already set. In the above example, `.Params.icon` is first set to `"photo"` in `src = "documents/photo_specs.pdf"`. So that would not get overridden to `"pdf"` by the later set `src = "**.pdf"` rule. -{{% /note %}} +> [!note] +> The order matters; only the first set values of the `title`, `name` and `params` keys will be used. Consecutive parameters will be set only for the ones not already set. In the above example, `.Params.icon` is first set to `"photo"` in `src = "documents/photo_specs.pdf"`. So that would not get overridden to `"pdf"` by the later set `src = "**.pdf"` rule. ### The `:counter` placeholder in `name` and `title` @@ -210,11 +195,8 @@ the `Name` and `Title` will be assigned to the resource files as follows: By default, with a multilingual single-host site, Hugo does not duplicate shared page resources when building the site. -{{% note %}} -This behavior is limited to Markdown content. Shared page resources for other [content formats] are copied into each language bundle. - -[content formats]: /content-management/formats/ -{{% /note %}} +> [!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: @@ -289,18 +271,12 @@ public/ This approach reduces build times, storage requirements, bandwidth consumption, and deployment times, ultimately reducing cost. -{{% note %}} -To resolve Markdown link and image destinations to the correct location, you must use link and image render hooks that capture the page resource with the [`Resources.Get`] method, and then invoke its [`RelPermalink`] method. - -By default, with multilingual single-host sites, Hugo enables its [embedded link render hook] and [embedded image render hook] to resolve Markdown link and image destinations. - -You may override the embedded render hooks as needed, provided they capture the resource as described above. - -[embedded link render hook]: /render-hooks/links/#default -[embedded image render hook]: /render-hooks/images/#default -[`Resources.Get`]: /methods/page/resources/#get -[`RelPermalink`]: /methods/resource/relpermalink/ -{{% /note %}} +> [!note] +> To resolve Markdown link and image destinations to the correct location, you must use link and image render hooks that capture the page resource with the [`Resources.Get`] method, and then invoke its [`RelPermalink`] method. +> +> By default, with multilingual single-host sites, Hugo enables its [embedded link render hook] and [embedded image render hook] to resolve Markdown link and image destinations. +> +> You may override the embedded render hooks as needed, provided they capture the resource as described above. Although duplicating shared page resources is inefficient, you can enable this feature in your site configuration if desired: @@ -308,3 +284,14 @@ Although duplicating shared page resources is inefficient, you can enable this f [markup.goldmark] duplicateResourceFiles = true {{< /code-toggle >}} + +[`RelPermalink`]: /methods/resource/relpermalink/ +[`Resource`]: /methods/resource +[`Resources.ByType`]: /methods/page/resources#bytype +[`Resources.Get`]: /methods/page/resources#get +[`Resources.Get`]: /methods/page/resources/#get +[`Resources.GetMatch`]: /methods/page/resources#getmatch +[`Resources.Match`]: /methods/page/resources#match +[content formats]: /content-management/formats/ +[embedded image render hook]: /render-hooks/images/#default +[embedded link render hook]: /render-hooks/links/#default diff --git a/content/en/content-management/related-content.md b/content/en/content-management/related-content.md new file mode 100644 index 000000000..d7b18dab0 --- /dev/null +++ b/content/en/content-management/related-content.md @@ -0,0 +1,102 @@ +--- +title: Related content +description: List related content in "See Also" sections. +categories: [] +keywords: [] +aliases: [/content/related/,/related/,/content-management/related/] +--- + +Hugo uses a set of factors to identify a page's related content based on front matter parameters. This can be tuned to the desired set of indices and parameters or left to Hugo's default [related content configuration](/configuration/related-content/). + +## List related content + +To list up to 5 related pages (which share the same _date_ or _keyword_ parameters) is as simple as including something similar to this partial in your template: + +```go-html-template {file="layouts/partials/related.html" copy=true} +{{ with site.RegularPages.Related . | first 5 }} +

Related content:

+ +{{ end }} +``` + +The `Related` method takes one argument which may be a `Page` or an options map. The options map has these options: + +indices +: (`slice`) The indices to search within. + +document +: (`page`) The page for which to find related content. Required when specifying an options map. + +namedSlices +: (`slice`) The keywords to search for, expressed as a slice of `KeyValues` using the [`keyVals`] function. + +fragments +: (`slice`) A list of special keywords that is used for indices configured as type "fragments". This will match the [fragment](g) identifiers of the documents. + +A fictional example using all of the above options: + +```go-html-template +{{ $page := . }} +{{ $opts := dict + "indices" (slice "tags" "keywords") + "document" $page + "namedSlices" (slice (keyVals "tags" "hugo" "rocks") (keyVals "date" $page.Date)) + "fragments" (slice "heading-1" "heading-2") +}} +``` + +> [!note] +> We improved and simplified this feature in Hugo 0.111.0. Before this we had 3 different methods: `Related`, `RelatedTo` and `RelatedIndices`. Now we have only one method: `Related`. The old methods are still available but deprecated. Also see [this blog article](https://regisphilibert.com/blog/2018/04/hugo-optmized-relashionships-with-related-content/) for a great explanation of more advanced usage of this feature. + +## Index content headings + +Hugo can index the headings in your content and use this to find related content. You can enable this by adding a index of type `fragments` to your `related` configuration: + +{{< code-toggle file=hugo >}} +[related] +threshold = 20 +includeNewer = true +toLower = false +[[related.indices]] +name = "fragmentrefs" +type = "fragments" +applyFilter = true +weight = 80 +{{< /code-toggle >}} + +- The `name` maps to a optional front matter slice attribute that can be used to link from the page level down to the fragment/heading level. +- If `applyFilter` is enabled, the `.HeadingsFiltered` on each page in the result will reflect the filtered headings. This is useful if you want to show the headings in the related content listing: + +```go-html-template +{{ $related := .Site.RegularPages.Related . | first 5 }} +{{ with $related }} +

See Also

+
    + {{ range $i, $p := . }} +
  • + {{ .LinkTitle }} + {{ with .HeadingsFiltered }} +
      + {{ range . }} + {{ $link := printf "%s#%s" $p.RelPermalink .ID | safeURL }} +
    • + {{ .Title }} +
      • + {{ end }} +
    + {{ end }} +
    • + {{ end }} +
+{{ end }} +``` + +## Configuration + +See [configure related content](/configuration/related-content/). + +[`keyVals`]: /functions/collections/keyvals/ diff --git a/content/en/content-management/related.md b/content/en/content-management/related.md deleted file mode 100644 index 6431d12a3..000000000 --- a/content/en/content-management/related.md +++ /dev/null @@ -1,156 +0,0 @@ ---- -title: Related content -description: List related content in "See Also" sections. -categories: [content management] -keywords: [content] -menu: - docs: - parent: content-management - weight: 110 -weight: 110 -toc: true -aliases: [/content/related/,/related/] ---- - -Hugo uses a set of factors to identify a page's related content based on front matter parameters. This can be tuned to the desired set of indices and parameters or left to Hugo's default [Related Content configuration](#configure-related-content). - -## List related content - -To list up to 5 related pages (which share the same _date_ or _keyword_ parameters) is as simple as including something similar to this partial in your template: - -{{< code file=layouts/partials/related.html >}} -{{ $related := .Site.RegularPages.Related . | first 5 }} -{{ with $related }} -

See Also

- -{{ end }} -{{< /code >}} - -The `Related` method takes one argument which may be a `Page` or a options map. The options map have these options: - -indices -: (`slice`) The indices to search within. - -document -: (`page`) The page for which to find related content. Required when specifying an options map. - -namedSlices -: (`slice`) The keywords to search for, expressed as a slice of `KeyValues` using the [`keyVals`] function. - -fragments -: (`slice`) A list of special keywords that is used for indices configured as type "fragments". This will match the [fragment](g) identifiers of the documents. - -[`keyVals`]: /functions/collections/keyvals/ - -A fictional example using all of the above options: - -```go-html-template -{{ $page := . }} -{{ $opts := dict - "indices" (slice "tags" "keywords") - "document" $page - "namedSlices" (slice (keyVals "tags" "hugo" "rocks") (keyVals "date" $page.Date)) - "fragments" (slice "heading-1" "heading-2") -}} -``` - -{{% note %}} -We improved and simplified this feature in Hugo 0.111.0. Before this we had 3 different methods: `Related`, `RelatedTo` and `RelatedIndices`. Now we have only one method: `Related`. The old methods are still available but deprecated. Also see [this blog article](https://regisphilibert.com/blog/2018/04/hugo-optmized-relashionships-with-related-content/) for a great explanation of more advanced usage of this feature. -{{% /note %}} - -## Index content headings in related content - -Hugo can index the headings in your content and use this to find related content. You can enable this by adding a index of type `fragments` to your `related` configuration: - -{{< code-toggle file=hugo >}} -[related] -threshold = 20 -includeNewer = true -toLower = false -[[related.indices]] -name = "fragmentrefs" -type = "fragments" -applyFilter = true -weight = 80 -{{< /code-toggle >}} - -* The `name` maps to a optional front matter slice attribute that can be used to link from the page level down to the fragment/heading level. -* If `applyFilter` is enabled, the `.HeadingsFiltered` on each page in the result will reflect the filtered headings. This is useful if you want to show the headings in the related content listing: - -```go-html-template -{{ $related := .Site.RegularPages.Related . | first 5 }} -{{ with $related }} -

See Also

-
    - {{ range $i, $p := . }} -
  • - {{ .LinkTitle }} - {{ with .HeadingsFiltered }} -
      - {{ range . }} - {{ $link := printf "%s#%s" $p.RelPermalink .ID | safeURL }} -
    • - {{ .Title }} -
      • - {{ end }} -
    - {{ end }} -
    • - {{ end }} -
-{{ end }} -``` - -## Configure related content - -Hugo provides a sensible default configuration of Related Content, but you can fine-tune this in your configuration, on the global or language level if needed. - -### Default configuration - -Without any `related` configuration set on the project, Hugo's Related Content methods will use the following. - -{{< code-toggle config=related />}} - -Custom configuration should be set using the same syntax. - -{{% note %}} -If you add a `related` configuration section, you need to add a complete configuration. It is not possible to just set, say, `includeNewer` and use the rest from the Hugo defaults. -{{% /note %}} - -### Top level configuration options - -threshold -: (`int`) A value between 0-100. Lower value will give more, but maybe not so relevant, matches. - -includeNewer -: (`bool`) Set to `true` to include **pages newer than the current page** in the related content listing. This will mean that the output for older posts may change as new related content gets added. - -toLower -: (`bool`) Set to `true` to lower case keywords in both the indexes and the queries. This may give more accurate results at a slight performance penalty. Note that this can also be set per index. - -### Configuration options per index - -name -: (`string`) The index name. This value maps directly to a page parameter. Hugo supports string values (`author` in the example) and lists (`tags`, `keywords` etc.) and time and date objects. - -type -: (`string`) One of `basic`(default) or `fragments`. - -applyFilter -: (`string`) Apply a `type` specific filter to the result of a search. This is currently only used for the `fragments` type. - -weight -: (`int`) An integer weight that indicates _how important_ this parameter is relative to the other parameters. It can be `0`, which has the effect of turning this index off, or even negative. Test with different values to see what fits your content best. - -cardinalityThreshold -: (`int`) If between 1 and 100, this is a percentage. All keywords that are used in more than this percentage of documents are removed. For example, setting this to `60` will remove all keywords that are used in more than 60% of the documents in the index. If `0`, no keyword is removed from the index. Default is `0`. - -pattern -: (`string`) This is currently only relevant for dates. When listing related content, we may want to list content that is also close in time. Setting "2006" (default value for date indexes) as the pattern for a date index will add weight to pages published in the same year. For busier blogs, "200601" (year and month) may be a better default. - -toLower -: (`bool`) See above. diff --git a/content/en/content-management/sections.md b/content/en/content-management/sections.md index ce6916fd3..f7a2296f5 100644 --- a/content/en/content-management/sections.md +++ b/content/en/content-management/sections.md @@ -2,26 +2,14 @@ title: Sections description: Organize content into sections. -categories: [content management] -keywords: [lists,sections,content types,organization] -menu: - docs: - parent: content-management - weight: 120 -weight: 120 -toc: true +categories: [] +keywords: [] aliases: [/content/sections/] --- ## Overview -A section is a top-level content directory, or any content directory with an `_index.md` file. A content directory with an `_index.md` file is also known as a [branch bundle](g). Section templates receive one or more page [collections](g) in [context](g). - -{{% note %}} -Although top-level directories without `_index.md` files are sections, we recommend creating `_index.md` files in _all_ sections. -{{% /note %}} - -A typical site consists of one or more sections. For example: +{{% glossary-term "section" %}} ```text content/ @@ -74,14 +62,8 @@ Have list pages|:heavy_check_mark:|:x: With the file structure from the [example above](#overview): 1. The list page for the articles section includes all articles, regardless of directory structure; none of the subdirectories are sections. - 1. The articles/2022 and articles/2023 directories do not have list pages; they are not sections. - 1. The list page for the products section, by default, includes product-1 and product-2, but not their descendant pages. To include descendant pages, use the `RegularPagesRecursive` method instead of the `Pages` method in the list template. - -[`Pages`]: /methods/page/pages/ -[`RegularPagesRecursive`]: /methods/page/regularpagesrecursive/ - 1. All directories in the products section have list pages; each directory is a section. ## Template selection @@ -104,9 +86,6 @@ Content directory|Single template If you need to use a different template for a subsection, specify `type` and/or `layout` in front matter. -[lookup rules]: /templates/lookup-order/#lookup-rules -[lookup order]: /templates/lookup-order/ - ## Ancestors and descendants A section has one or more ancestors (including the home page), and zero or more descendants. With the file structure from the [example above](#overview): @@ -119,7 +98,7 @@ The content file (benefit-1.md) has four ancestors: benefits, product-1, product For example, use the `.Ancestors` method to render breadcrumb navigation. -{{< code file=layouts/partials/breadcrumb.html >}} +```go-html-template {file="layouts/partials/breadcrumb.html"} -{{< /code >}} +``` With this CSS: @@ -156,9 +135,5 @@ Hugo renders this, where each breadcrumb is a link to the corresponding page: Home » Products » Product 1 » Benefits » Benefit 1 ``` -[archetype]: /content-management/archetypes/ -[content type]: /content-management/types/ -[directory structure]: /getting-started/directory-structure/ -[section templates]: /templates/types/#section -[leaf bundles]: /content-management/page-bundles/#leaf-bundles -[branch bundles]: /content-management/page-bundles/#branch-bundles +[lookup order]: /templates/lookup-order/ +[lookup rules]: /templates/lookup-order/#lookup-rules diff --git a/content/en/content-management/shortcodes.md b/content/en/content-management/shortcodes.md index 1c5e2c99c..2de387f39 100644 --- a/content/en/content-management/shortcodes.md +++ b/content/en/content-management/shortcodes.md @@ -1,15 +1,9 @@ --- title: Shortcodes description: Use embedded, custom, or inline shortcodes to insert elements such as videos, images, and social media embeds into your content. -categories: [content management] +categories: [] keywords: [] -menu: - docs: - parent: content-management - weight: 100 -weight: 100 aliases: [/extras/shortcodes/] -toc: true --- ## Introduction @@ -20,55 +14,53 @@ There are three types of shortcodes: embedded, custom, and inline. ## Embedded -Hugo's embedded shortcodes are pre-defined templates within the application. Refer to each shortcode's documentation for specific usage instructions and available arguments. +Hugo's embedded shortcodes are pre-defined templates within the application. Refer to each shortcode's documentation for specific usage instructions and available arguments. -{{< list-pages-in-section path=/shortcodes >}} +{{% list-pages-in-section path=/shortcodes %}} ## Custom Create custom shortcodes to simplify and standardize content creation. For example, the following shortcode template generates an audio player using a [global resource](g): -{{< code file=layouts/shortcodes/audio.html >}} +```go-html-template {file="layouts/shortcodes/audio.html"} {{ with resources.Get (.Get "src") }} {{ end }} -{{< /code >}} +``` Then call the shortcode from within markup: -{{< code file=content/example.md >}} +```text {file="content/example.md"} {{}} -{{< /code >}} +``` Learn more about creating shortcodes in the [shortcode templates] section. -[shortcode templates]: /templates/shortcode/ - ## Inline 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 site's configuration: {{< code-toggle file=hugo >}} [security] enableInlineShortcodes = true {{< /code-toggle >}} +For more information see [configure security](/configuration/security). + The following example demonstrates an inline shortcode, `date.inline`, that accepts a single positional argument: a date/time [layout string]. -[layout string]: /functions/time/format/#layout-string - -{{< code file=content/example.md >}} +```text {file="content/example.md"} Today is {{}} {{- now | time.Format (.Get 0) -}} {{}}. -Today is {{}}. -{{< /code >}} +Today is {{}}. +``` In the example above, the inline shortcode is executed twice: once upon definition and again when subsequently called. Hugo renders this to: @@ -79,11 +71,8 @@ In the example above, the inline shortcode is executed twice: once upon definiti Inline shortcodes process their inner content within the same context as regular shortcode templates, allowing you to use any available [shortcode method]. -[shortcode method]: /templates/shortcode/#methods - -{{% note %}} -You cannot [nest](#nesting) inline shortcodes. -{{% /note %}} +> [!note] +> You cannot [nest](#nesting) inline shortcodes. Learn more about creating shortcodes in the [shortcode templates] section. @@ -121,31 +110,25 @@ Or use the self-closing syntax with a trailing slash to pass the text as an argu {{}} ``` -[`details`]: /shortcodes/details -[`instagram`]: /shortcodes/instagram -[`qr`]: /shortcodes/qr - Refer to each shortcode's documentation for specific usage instructions and available arguments. ### Arguments Shortcode arguments can be either _named_ or _positional_. -Named arguments are passed as case-sensitive key-value pairs, as seen in this example with the embedded [`figure`] shortcode. The `src` argument, for instance, is required. - -[`figure`]: /shortcodes/figure +Named arguments are passed as case-sensitive key-value pairs, as seen in this example with the embedded [`figure`] shortcode. The `src` argument, for instance, is required. ```text {{}} ``` -Positional arguments, on the other hand, are determined by their position. The embedded `instagram` shortcode, for example, expects the first argument to be the Instagram post ID. +Positional arguments, on the other hand, are determined by their position. The embedded `instagram` shortcode, for example, expects the first argument to be the Instagram post ID. ```text {{}} ``` -Shortcode arguments are space delimited, and arguments with internal spaces must be quoted. +Shortcode arguments are space-delimited, and arguments with internal spaces must be quoted. ```text {{}} @@ -171,7 +154,7 @@ You can optionally use multiple lines when providing several arguments to a shor Use a [raw string literal](g) if you need to pass a multiline string: ```text -{{HTML, +{{HTML, and a new line with a "quoted string".` */>}} ``` @@ -188,29 +171,27 @@ Notation|Example Markdown|`{{%/* foo */%}} ## Section 1 {{%/* /foo */%}}` Standard|`{{}} ## Section 2 {{}}` -###### Markdown notation +#### Markdown notation Hugo processes the shortcode before the page content is rendered by the Markdown renderer. This means, for instance, that Markdown headings inside a Markdown-notation shortcode will be included when invoking the [`TableOfContents`] method on the `Page` object. -[`TableOfContents`]: /methods/page/tableofcontents/ - -###### Standard notation +#### Standard notation With standard notation, Hugo processes the shortcode separately, merging the output into the page content after Markdown rendering. This means, for instance, that Markdown headings inside a standard-notation shortcode will be excluded when invoking the `TableOfContents` method on the `Page` object. By way of example, with this shortcode template: -{{< code file=layouts/shortcodes/foo.html >}} +```go-html-template {file="layouts/shortcodes/foo.html"} {{ .Inner }} -{{< /code >}} +``` And this markdown: -{{< code file=content/example.md >}} +```text {file="content/example.md"} {{%/* foo */%}} ## Section 1 {{%/* /foo */%}} {{}} ## Section 2 {{}} -{{< /code >}} +``` Hugo renders this HTML: @@ -222,20 +203,28 @@ Hugo renders this HTML: In the above, "Section 1" will be included when invoking the `TableOfContents` method, while "Section 2" will not. -The shortcode author determines which notation to use. Consult each shortcode's documentation for specific usage instructions and available arguments. +The shortcode author determines which notation to use. Consult each shortcode's documentation for specific usage instructions and available arguments. ## Nesting Shortcodes (excluding [inline](#inline) shortcodes) can be nested, creating parent-child relationships. For example, a gallery shortcode might contain several image shortcodes: -{{< code file=content/example.md >}} +```text {file="content/example.md"} {{}} {{}} {{}} {{}} {{}} -{{< /code >}} +``` The [shortcode templates][nesting] section provides a detailed explanation and examples. +[`details`]: /shortcodes/details +[`figure`]: /shortcodes/figure +[`instagram`]: /shortcodes/instagram +[`qr`]: /shortcodes/qr +[`TableOfContents`]: /methods/page/tableofcontents/ +[layout string]: /functions/time/format/#layout-string [nesting]: /templates/shortcode/#nesting +[shortcode method]: /templates/shortcode/#methods +[shortcode templates]: /templates/shortcode/ diff --git a/content/en/content-management/summaries.md b/content/en/content-management/summaries.md index dbe8ff248..da61c2c8e 100644 --- a/content/en/content-management/summaries.md +++ b/content/en/content-management/summaries.md @@ -2,14 +2,8 @@ title: Content summaries linkTitle: Summaries description: Create and render content summaries. -categories: [content management] -keywords: [summaries,abstracts,read more] -menu: - docs: - parent: content-management - weight: 160 -weight: 160 -toc: true +categories: [] +keywords: [] aliases: [/content/summaries/,/content-management/content-summaries/] --- @@ -26,7 +20,7 @@ Review the [comparison table](#comparison) below to understand the characteristi Use a `` divider to indicate the end of the summary. Hugo will not render the summary divider itself. -{{< code file=content/example.md >}} +```text {file="content/example.md"} +++ title: 'Example' date: 2024-05-26T09:10:33-07:00 @@ -37,7 +31,7 @@ This is the first paragraph. This is the second paragraph. -{{< /code >}} +``` When using the Emacs Org Mode [content format], use a `# more` divider to indicate the end of the summary. @@ -47,7 +41,7 @@ When using the Emacs Org Mode [content format], use a `# more` divider to indica Use front matter to define a summary independent of content. -{{< code file=content/example.md >}} +```text {file="content/example.md"} +++ title: 'Example' date: 2024-05-26T09:10:33-07:00 @@ -57,15 +51,15 @@ summary: 'This summary is independent of the content.' This is the first paragraph. This is the second paragraph. -{{< /code >}} +``` ## 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. -[`summaryLength`]: /getting-started/configuration/#summarylength +[`summaryLength`]: /configuration/all/#summarylength -{{< code file=content/example.md >}} +```text {file="content/example.md"} +++ title: 'Example' date: 2024-05-26T09:10:33-07:00 @@ -76,7 +70,7 @@ This is the first paragraph. This is the second paragraph. This is the third paragraph. -{{< /code >}} +``` For example, with a `summaryLength` of 7, the automatic summary will be: diff --git a/content/en/content-management/syntax-highlighting.md b/content/en/content-management/syntax-highlighting.md index b3e991a96..7e87efa49 100644 --- a/content/en/content-management/syntax-highlighting.md +++ b/content/en/content-management/syntax-highlighting.md @@ -1,138 +1,102 @@ --- title: Syntax highlighting -description: Hugo comes with really fast syntax highlighting from Chroma. -categories: [content management] -keywords: [highlighting,chroma,code blocks,syntax] -menu: - docs: - parent: content-management - weight: 250 -weight: 250 -toc: true +description: Add syntax highlighting to code examples. +categories: [] +keywords: [highlight] aliases: [/extras/highlighting/,/extras/highlight/,/tools/syntax-highlighting/] --- -Hugo uses [Chroma](https://github.com/alecthomas/chroma) as its code highlighter; it is built in Go and is really, really fast. +Hugo provides several methods to add syntax highlighting to code examples: -## Configure syntax highlighter +- Use the [`transform.Highlight`] function within your templates +- Use the [`highlight`] shortcode with any [content format](g) +- Use fenced code blocks with the Markdown content format -See [Configure Highlight](/getting-started/configuration-markup#highlight). +[`transform.Highlight`]: /functions/transform/highlight/ +[`highlight`]: /shortcodes/highlight/ -## Generate syntax highlighter CSS +## Fenced code blocks -If you run with `markup.highlight.noClasses=false` in your site configuration, you need a style sheet. The style sheet will override the style specified in [`markup.highlight.style`](/functions/transform/highlight/#options). +In its default configuration, Hugo highlights code examples within fenced code blocks, following this form: -You can generate one with Hugo: - -```sh -hugo gen chromastyles --style=monokai > syntax.css -``` - -Run `hugo gen chromastyles -h` for more options. See https://xyproto.github.io/splash/docs/ for a gallery of available styles. - -## Highlight shortcode - -Highlighting is carried out via the built-in [`highlight` shortcode](/shortcodes/highlight/). It takes exactly one required argument for the programming language to be highlighted and requires a closing tag. - -Options: - -* `linenos`: configure line numbers. Valid values are `true`, `false`, `table`, or `inline`. `false` will turn off line numbers if it's configured to be on in site configuration. `table` will give copy-and-paste friendly code blocks. -* `hl_lines`: lists a set of line numbers or line number ranges to be highlighted. -* `linenostart=199`: starts the line number count from 199. -* `anchorlinenos`: Configure anchors on line numbers. Valid values are `true` or `false`; -* `lineanchors`: Configure a prefix for the anchors on line numbers. Will be suffixed with `-`, so linking to the line number 1 with the option `lineanchors=prefix` adds the anchor `prefix-1` to the page. -* `hl_inline` Highlight inside a `` (inline HTML element) tag. Valid values are `true` or `false`. The `code` tag will get a class with name `code-inline`. - -### Example: highlight shortcode - -```go-html-template -{{}} -// ... code -{{}} -``` - -Gives this: - -{{< highlight go "linenos=table,hl_lines=8 15-17,linenostart=199" >}} -// GetTitleFunc returns a func that can be used to transform a string to -// title case. -// -// The supported styles are -// -// - "Go" (strings.Title) -// - "AP" (see https://www.apstylebook.com/) -// - "Chicago" (see https://www.chicagomanualofstyle.org/home.html) -// -// If an unknown or empty style is provided, AP style is what you get. -func GetTitleFunc(style string) func(s string) string { - switch strings.ToLower(style) { - case "go": - return strings.Title - case "chicago": - return transform.NewTitleConverter(transform.ChicagoStyle) - default: - return transform.NewTitleConverter(transform.APStyle) - } -} -{{< / highlight >}} - -## Highlight Hugo/Go template code - -For highlighting Hugo/Go template code on your page, add `/*` after the opening double curly braces and `*/` before closing curly braces. - -``` go -{{}} -``` - -Gives this: - -``` go -{{}} -``` - -## Highlight template function - -See [Highlight](/functions/transform/highlight/). - -## Highlighting in code fences - -Highlighting in code fences is enabled by default. - -````txt -```go {linenos=table,hl_lines=[8,"15-17"],linenostart=199} -// ... code +````text {file="content/example.md"} +```LANG [OPTIONS] +CODE ``` ```` -Gives this: +CODE +: The code to highlight. -```go {linenos=table,hl_lines=[8,"15-17"],linenostart=199} -// GetTitleFunc returns a func that can be used to transform a string to -// title case. -// -// The supported styles are -// -// - "Go" (strings.Title) -// - "AP" (see https://www.apstylebook.com/) -// - "Chicago" (see https://www.chicagomanualofstyle.org/home.html) -// -// If an unknown or empty style is provided, AP style is what you get. -func GetTitleFunc(style string) func(s string) string { - switch strings.ToLower(style) { - case "go": - return strings.Title - case "chicago": - return transform.NewTitleConverter(transform.ChicagoStyle) - default: - return transform.NewTitleConverter(transform.APStyle) - } +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. + +[supported languages]: #languages +[site configuration]: /configuration/markup/#highlight + +For example, with this Markdown: + +````text {file="content/example.md"} +```go {linenos=inline hl_lines=[3,"6-8"] style=emacs} +package main + +import "fmt" + +func main() { + for i := 0; i < 3; i++ { + fmt.Println("Value of i:", i) + } +} +``` +```` + +Hugo renders this: + +```go {linenos=inline, hl_lines=[3, "6-8"], style=emacs} +package main + +import "fmt" + +func main() { + for i := 0; i < 3; i++ { + fmt.Println("Value of i:", i) + } } ``` -The options are the same as in the [highlighting shortcode](/content-management/syntax-highlighting/#highlight-shortcode), including `linenos=false`, but note the slightly different Markdown attribute syntax. +## Options -## List of Chroma highlighting languages +{{% include "_common/syntax-highlighting-options.md" %}} -The full list of Chroma lexers and their aliases (which is the identifier used in the `highlight` template func or when doing highlighting in code fences): +## Escaping + +When documenting shortcode usage, escape the tag delimiters: + +````text {file="content/example.md"} +```text {linenos=inline} +{{}} + +{{%/*/* shortcode-2 */*/%}} +``` +```` + +Hugo renders this to: + +```text {linenos=inline} +{{}} + +{{%/* shortcode-2 */%}} +``` + +## Languages + +These are the supported languages. Use one of the identifiers, not the language name, when specifying a language for: + +- The [`transform.Highlight`] function +- The [`highlight`] shortcode +- Fenced code blocks {{< chroma-lexers >}} diff --git a/content/en/content-management/taxonomies.md b/content/en/content-management/taxonomies.md index 6ba9e2a25..e8ba04c28 100644 --- a/content/en/content-management/taxonomies.md +++ b/content/en/content-management/taxonomies.md @@ -1,14 +1,8 @@ --- title: Taxonomies description: Hugo includes support for user-defined taxonomies. -categories: [content management] -keywords: [taxonomies,metadata,front matter,terms] -menu: - docs: - parent: content-management - weight: 150 -weight: 150 -toc: true +categories: [] +keywords: [] aliases: [/taxonomies/overview/,/taxonomies/usage/,/indexes/overview/,/doc/indexes/,/extras/indexes] --- @@ -19,24 +13,24 @@ Hugo includes support for user-defined groupings of content called **taxonomies* ### Definitions Taxonomy -: a categorization that can be used to classify content +: A categorization that can be used to classify content Term -: a key within the taxonomy +: A key within the taxonomy Value -: a piece of content assigned to a term +: A piece of content assigned to a term ## Example taxonomy: movie website Let's assume you are making a website about movies. You may want to include the following taxonomies: -* Actors -* Directors -* Studios -* Genre -* Year -* Awards +- Actors +- Directors +- Studios +- Genre +- Year +- Awards Then, in each of the movies, you would specify terms for each of these taxonomies (i.e., in the [front matter] of each of your movie content files). From these terms, Hugo would automatically create pages for each Actor, Director, Studio, Genre, Year, and Award, with each listing all of the Movies that matched that specific Actor, Director, Studio, Genre, Year, and Award. @@ -75,60 +69,16 @@ Moonrise Kingdom <- Value ... ``` -## Default taxonomies - -Hugo natively supports taxonomies. - -Without adding a single line to your [site configuration] file, Hugo will automatically create taxonomies for `tags` and `categories`. That would be the same as manually [configuring your taxonomies](#configure-taxonomies) as below: - -{{< code-toggle config=taxonomies />}} - -If you do not want Hugo to create any taxonomies, set `disableKinds` in your [site configuration] to the following: - -{{< code-toggle file=hugo >}} -disableKinds = ["taxonomy","term"] -{{}} - -{{% include "content-management/_common/page-kinds.md" %}} - ### Default destinations When taxonomies are used---and [taxonomy templates] are provided---Hugo will automatically create both a page listing all the taxonomy's terms and individual pages with lists of content associated with each term. For example, a `categories` taxonomy declared in your configuration and used in your content front matter will create the following pages: -* A single page at `example.com/categories/` that lists all the terms within the taxonomy -* [Individual taxonomy list pages][taxonomy templates] (e.g., `/categories/development/`) for each of the terms that shows a listing of all pages marked as part of that taxonomy within any content file's [front matter] +- A single page at `example.com/categories/` that lists all the terms within the taxonomy +- [Individual taxonomy list pages][taxonomy templates] (e.g., `/categories/development/`) for each of the terms that shows a listing of all pages marked as part of that taxonomy within any content file's [front matter] -## Configure taxonomies +## Configuration -Custom taxonomies other than the [defaults](#default-taxonomies) must be defined in your [site configuration] before they can be used throughout the site. You need to provide both the plural and singular labels for each taxonomy. For example, `singular key = "plural value"` for TOML and `singular key: "plural value"` for YAML. - -### Example: adding a custom taxonomy named "series" - -{{% note %}} -While adding custom taxonomies, you need to put in the default taxonomies too, _if you want to keep them_. -{{% /note %}} - -{{< code-toggle file=hugo >}} -[taxonomies] - tag = "tags" - category = "categories" - series = "series" -{{}} - -### Example: removing default taxonomies - -If you want to have just the default `tags` taxonomy, and remove the `categories` taxonomy for your site, you can do so by modifying the `taxonomies` value in your [site configuration]. - -{{< code-toggle file=hugo >}} -[taxonomies] - tag = "tags" -{{}} - -If you want to disable all taxonomies altogether, see the use of `disableKinds` in [Hugo Taxonomy Defaults](#default-taxonomies). - -{{% note %}} -You can add content and front matter to your taxonomy list and taxonomy terms pages. See [Content Organization](/content-management/organization/) for more information on how to add an `_index.md` for this purpose. -{{% /note %}} +See [configure taxonomies](/configuration/taxonomies/). ## Assign terms to content @@ -148,7 +98,7 @@ The following show a piece of content that has a weight of 22, which can be used ### Example: taxonomic `weight` -{{< code-toggle >}} +{{< code-toggle file=hugo >}} title = "foo" tags = [ "a", "b", "c" ] tags_weight = 22 @@ -172,4 +122,4 @@ wikipedia: "https://en.wikipedia.org/wiki/Bruce_Willis" [documentation on archetypes]: /content-management/archetypes/ [front matter]: /content-management/front-matter/ [taxonomy templates]: /templates/types/#taxonomy -[site configuration]: /getting-started/configuration/ +[site configuration]: /configuration/ diff --git a/content/en/content-management/types.md b/content/en/content-management/types.md index 9b44645e9..08e9adda2 100644 --- a/content/en/content-management/types.md +++ b/content/en/content-management/types.md @@ -1,14 +1,8 @@ --- title: Content types description: Hugo is built around content organized in sections. -categories: [content management] -keywords: [lists,sections,content types,types,organization] -menu: - docs: - parent: content-management - weight: 130 -weight: 130 -toc: true +categories: [] +keywords: [] aliases: [/content/types] --- diff --git a/content/en/content-management/urls.md b/content/en/content-management/urls.md index ab0c7148a..2630105e5 100644 --- a/content/en/content-management/urls.md +++ b/content/en/content-management/urls.md @@ -1,14 +1,8 @@ --- title: URL management description: Control the structure and appearance of URLs through front matter entries and settings in your site configuration. -categories: [content management] -keywords: [aliases,redirects,permalinks,urls] -menu: - docs: - parent: content-management - weight: 180 -weight: 180 -toc: true +categories: [] +keywords: [] aliases: [/extras/permalinks/,/extras/aliases/,/extras/urls/,/doc/redirects/,/doc/alias/,/doc/aliases/] --- @@ -43,14 +37,10 @@ https://example.org/posts/my-first-post/ Set the `url` in front matter to override the entire path. Use this with either regular pages or section pages. -{{% note %}} -Hugo does not sanitize the `url` front matter field, allowing you to generate: - -- File paths that contain characters reserved by the operating system. For example, file paths on Windows may not contain any of these [reserved characters]. Hugo throws an error if a file path includes a character reserved by the current operating system. -- URLs that contain disallowed characters. For example, the less than sign (`<`) is not allowed in a URL. - -[reserved characters]: https://learn.microsoft.com/en-us/windows/win32/fileio/naming-a-file#naming-conventions -{{% /note %}} +> [!note] +> Hugo does not sanitize the `url` front matter field, allowing you to generate: +> - File paths that contain characters reserved by the operating system. For example, file paths on Windows may not contain any of these [reserved characters]. Hugo throws an error if a file path includes a character reserved by the current operating system. +> - URLs that contain disallowed characters. For example, the less than sign (`<`) is not allowed in a URL. If you set both `slug` and `url` in front matter, the `url` value takes precedence. @@ -107,8 +97,6 @@ https://example.org/articles/my-first-article.html With monolingual sites, `url` values with or without a leading slash are relative to the [`baseURL`]. With multilingual sites, `url` values with a leading slash are relative to the `baseURL`, and `url` values without a leading slash are relative to the `baseURL` plus the language prefix. -[`baseURL`]: /getting-started/configuration/#baseurl - Site type|Front matter `url`|Resulting URL :--|:--|:-- monolingual|`/about`|`https://example.org/about/` @@ -120,7 +108,7 @@ multilingual|`about`|`https://example.org/de/about/` {{< new-in 0.131.0 />}} -You can also use [tokens](#tokens) when setting the `url` value. This is typically used in `cascade` sections: +You can also usetokens when setting the `url` value. This is typically used in `cascade` sections: {{< code-toggle file=content/foo/bar/_index.md fm=true >}} title ="Bar" @@ -128,226 +116,19 @@ title ="Bar" url = "/:sections[last]/:slug" {{< /code-toggle >}} +Use any of these tokens: + +{{% include "/_common/permalink-tokens.md" %}} + ## Site configuration ### Permalinks -In your site configuration, define a URL pattern for each top-level section. Each URL pattern can target a given language and/or page kind. - -Front matter `url` values override the URL patterns defined in the `permalinks` section of your site configuration. - -#### Monolingual examples {#permalinks-monolingual-examples} - -With this content structure: - -```text -content/ -├── posts/ -│ ├── bash-in-slow-motion.md -│ └── tls-in-a-nutshell.md -├── tutorials/ -│ ├── git-for-beginners.md -│ └── javascript-bundling-with-hugo.md -└── _index.md -``` - -Render tutorials under "training", and render the posts under "articles" with a date-base hierarchy: - -{{< code-toggle file=hugo >}} -[permalinks.page] -posts = '/articles/:year/:month/:slug/' -tutorials = '/training/:slug/' -[permalinks.section] -posts = '/articles/' -tutorials = '/training/' -{{< /code-toggle >}} - -The structure of the published site will be: - -```text -public/ -├── articles/ -│ ├── 2023/ -│ │ ├── 04/ -│ │ │ └── bash-in-slow-motion/ -│ │ │ └── index.html -│ │ └── 06/ -│ │ └── tls-in-a-nutshell/ -│ │ └── index.html -│ └── index.html -├── training/ -│ ├── git-for-beginners/ -│ │ └── index.html -│ ├── javascript-bundling-with-hugo/ -│ │ └── index.html -│ └── index.html -└── index.html -``` - -To create a date-based hierarchy for regular pages in the content root: - -{{< code-toggle file=hugo >}} -[permalinks.page] -"/" = "/:year/:month/:slug/" -{{< /code-toggle >}} - -Use the same approach with taxonomy terms. For example, to omit the taxonomy segment of the URL: - -{{< code-toggle file=hugo >}} -[permalinks.term] -'tags' = '/:slug/' -{{< /code-toggle >}} - -#### Multilingual example {#permalinks-multilingual-example} - -Use the `permalinks` configuration as a component of your localization strategy. - -With this content structure: - -```text -content/ -├── en/ -│ ├── books/ -│ │ ├── les-miserables.md -│ │ └── the-hunchback-of-notre-dame.md -│ └── _index.md -└── es/ - ├── books/ - │ ├── les-miserables.md - │ └── the-hunchback-of-notre-dame.md - └── _index.md -``` - -And this site configuration: - -{{< code-toggle file=hugo >}} -defaultContentLanguage = 'en' -defaultContentLanguageInSubdir = true - -[languages.en] -contentDir = 'content/en' -languageCode = 'en-US' -languageDirection = 'ltr' -languageName = 'English' -weight = 1 - -[languages.en.permalinks.page] -books = "/books/:slug/" - -[languages.en.permalinks.section] -books = "/books/" - -[languages.es] -contentDir = 'content/es' -languageCode = 'es-ES' -languageDirection = 'ltr' -languageName = 'Español' -weight = 2 - -[languages.es.permalinks.page] -books = "/libros/:slug/" - -[languages.es.permalinks.section] -books = "/libros/" -{{< /code-toggle >}} - -The structure of the published site will be: - -```text -public/ -├── en/ -│ ├── books/ -│ │ ├── les-miserables/ -│ │ │ └── index.html -│ │ ├── the-hunchback-of-notre-dame/ -│ │ │ └── index.html -│ │ └── index.html -│ └── index.html -├── es/ -│ ├── libros/ -│ │ ├── les-miserables/ -│ │ │ └── index.html -│ │ ├── the-hunchback-of-notre-dame/ -│ │ │ └── index.html -│ │ └── index.html -│ └── index.html -└── index.html -```` - -#### Tokens - -Use these tokens when defining the URL pattern. You can also use these tokens when setting the [`url`](#permalinks-tokens-in-front-matter) value in front matter. - -`:year` -: The 4-digit year as defined in the front matter `date` field. - -`:month` -: The 2-digit month as defined in the front matter `date` field. - -`:monthname` -: The name of the month as defined in the front matter `date` field. - -`:day` -: The 2-digit day as defined in the front matter `date` field. - -`:weekday` -: The 1-digit day of the week as defined in the front matter `date` field (Sunday = 0). - -`:weekdayname` -: The name of the day of the week as defined in the front matter `date` field. - -`:yearday` -: The 1- to 3-digit day of the year as defined in the front matter `date` field. - -`:section` -: The content's section. - -`:sections` -: The content's sections hierarchy. You can use a selection of the sections using _slice syntax_: `:sections[1:]` includes all but the first, `:sections[:last]` includes all but the last, `:sections[last]` includes only the last, `:sections[1:2]` includes section 2 and 3. Note that this slice access will not throw any out-of-bounds errors, so you don't have to be exact. - -`:title` -: The title as defined in front matter, else the automatic title. Hugo generates titles automatically for section, taxonomy, and term pages that are not backed by a file. - -`:slug` -: The slug as defined in front matter, else the title as defined in front matter, else the automatic title. Hugo generates titles automatically for section, taxonomy, and term pages that are not backed by a file. - -`:filename` -: The content's file name without extension, applicable to the `page` page kind. - -`:slugorfilename` -: The slug as defined in front matter, else the content's file name without extension, applicable to the `page` page kind. - -For time-related values, you can also use the layout string components defined in Go's [time package]. For example: - -[time package]: https://pkg.go.dev/time#pkg-constants - -{{< code-toggle file=hugo >}} -permalinks: - posts: /:06/:1/:2/:title/ -{{< /code-toggle >}} +See [configure permalinks](/configuration/permalinks). ### Appearance -The appearance of a URL is either ugly or pretty. - -Type|Path|URL -:--|:--|:-- -ugly|content/about.md|`https://example.org/about.html` -pretty|content/about.md|`https://example.org/about/` - -By default, Hugo produces pretty URLs. To generate ugly URLs, change your site configuration: - -{{< code-toggle file=hugo >}} -uglyURLs = true -{{< /code-toggle >}} - -You can also enable uglyURLs by section. For example, with a site that contains sections for books and films: - -{{< code-toggle file=hugo >}} -[uglyURLs] -books = true -films = false -{{< /code-toggle >}} +See [configure ugly URLs](/configuration/ugly-urls/). ### Post-processing @@ -355,11 +136,9 @@ Hugo provides two mutually exclusive configuration options to alter URLs _after_ #### Canonical URLs -{{% note %}} -This is a legacy configuration option, superseded by template functions and Markdown render hooks, and will likely be [removed in a future release]. - -[removed in a future release]: https://github.com/gohugoio/hugo/issues/4733 -{{% /note %}} +> [!caution] +> This is a legacy configuration option, superseded by template functions and Markdown render hooks, and will likely be [removed in a future release]. +{class="!mt-6"} If enabled, Hugo performs a search and replace _after_ it renders the page. It searches for site-relative URLs (those with a leading slash) associated with `action`, `href`, `src`, `srcset`, and `url` attributes. It then prepends the `baseURL` to create absolute URLs. @@ -378,9 +157,9 @@ canonifyURLs = true #### Relative URLs -{{% note %}} -Do not enable this option unless you are creating a serverless site, navigable via the file system. -{{% /note %}} +> [!caution] +> Do not enable this option unless you are creating a serverless site, navigable via the file system. +{class="!mt-6"} If enabled, Hugo performs a search and replace _after_ it renders the page. It searches for site-relative URLs (those with a leading slash) associated with `action`, `href`, `src`, `srcset`, and `url` attributes. It then transforms the URL to be relative to the current page. @@ -410,7 +189,7 @@ Create redirects from old URLs to new URLs with aliases: Change the file name of an existing page, and create an alias from the previous URL to the new URL: -{{< code-toggle file=content/posts/new-file-name.md >}} +{{< code-toggle file=content/posts/new-file-name.md fm=true >}} aliases = ['/posts/previous-file-name'] {{< /code-toggle >}} @@ -422,13 +201,13 @@ Each of these directory-relative aliases is equivalent to the site-relative alia You can create more than one alias to the current page: -{{< code-toggle file=content/posts/new-file-name.md >}} +{{< code-toggle file=content/posts/new-file-name.md fm=true >}} aliases = ['previous-file-name','original-file-name'] {{< /code-toggle >}} In a multilingual site, use a directory-relative alias, or include the language prefix with a site-relative alias: -{{< code-toggle file=content/posts/new-file-name.de.md >}} +{{< code-toggle file=content/posts/new-file-name.de.md fm=true >}} aliases = ['/de/posts/previous-file-name'] {{< /code-toggle >}} @@ -449,7 +228,7 @@ public/ The alias from the previous URL to the new URL is a client-side redirect: -{{< code file=posts/previous-file-name/index.html >}} +```html {file="posts/previous-file-name/index.html"} @@ -460,7 +239,7 @@ The alias from the previous URL to the new URL is a client-side redirect: -{{< /code >}} +``` Collectively, the elements in the `head` section: @@ -480,4 +259,7 @@ Permalink Page : The Page data for the page being aliased. +[`baseURL`]: /configuration/all/#baseurl +[removed in a future release]: https://github.com/gohugoio/hugo/issues/4733 +[reserved characters]: https://learn.microsoft.com/en-us/windows/win32/fileio/naming-a-file#naming-conventions [source code]: {{% eturl alias %}} diff --git a/content/en/contribute/_index.md b/content/en/contribute/_index.md index a8ffaf4fa..d0ae954b0 100644 --- a/content/en/contribute/_index.md +++ b/content/en/contribute/_index.md @@ -1,16 +1,9 @@ --- title: Contribute to the Hugo project -linktitle: Contribute +linkTitle: Contribute description: Contribute to development, documentation, and themes. categories: [] keywords: [] -menu: - docs: - identifier: contribute-in-this-section - parent: contribute - weight: 10 weight: 10 aliases: [/tutorials/how-to-contribute-to-hugo/,/community/contributing/] --- - -Hugo relies heavily on the enthusiasm and participation of the open-source community. We need your support. diff --git a/content/en/contribute/development.md b/content/en/contribute/development.md index ef6fd9d37..78ca5ec5c 100644 --- a/content/en/contribute/development.md +++ b/content/en/contribute/development.md @@ -1,14 +1,8 @@ --- title: Development description: Contribute to the development of Hugo. -categories: [contribute] -keywords: [development] -menu: - docs: - parent: contribute - weight: 20 -weight: 20 -toc: true +categories: [] +keywords: [] --- ## Introduction @@ -33,16 +27,6 @@ If there is sufficient interest, [create a proposal]. Do not submit a pull reque For a complete guide to contributing to Hugo, see the [Contribution Guide]. -[bugs]: https://github.com/gohugoio/hugo/issues?q=is%3Aopen+is%3Aissue+label%3ABug -[contributing]: CONTRIBUTING.md -[create a proposal]: https://github.com/gohugoio/hugo/issues/new?labels=Proposal%2C+NeedsTriage&template=feature_request.md -[documentation repository]: https://github.com/gohugoio/hugoDocs -[documentation]: /documentation -[forum]: https://discourse.gohugo.io -[issue queue]: https://github.com/gohugoio/hugo/issues -[themes]: https://themes.gohugo.io/ -[contribution guide]: https://github.com/gohugoio/hugo/blob/master/CONTRIBUTING.md - ## Prerequisites To build the extended or extended/deploy edition from source you must: @@ -52,34 +36,27 @@ To build the extended or extended/deploy edition from source you must: 1. Install a C compiler, either [GCC] or [Clang] 1. Update your `PATH` environment variable as described in the [Go documentation] -[Clang]: https://clang.llvm.org/ -[GCC]: https://gcc.gnu.org/ -[Git]: https://git-scm.com/book/en/v2/Getting-Started-Installing-Git -[Go documentation]: https://go.dev/doc/code#Command -[Go]: https://go.dev/doc/install - -{{% note %}} -See these [detailed instructions](https://discourse.gohugo.io/t/41370) to install GCC on Windows. -{{% /note %}} +> [!note] +> See these [detailed instructions](https://discourse.gohugo.io/t/41370) to install GCC on Windows. ## GitHub workflow -{{% note %}} -This section assumes that you have a working knowledge of Go, Git and GitHub, and are comfortable working on the command line. -{{% /note %}} +> [!note] +> This section assumes that you have a working knowledge of Go, Git and GitHub, and are comfortable working on the command line. Use this workflow to create and submit pull requests. -Step 1 -: Fork the [project repository]. +### Step 1 -[project repository]: https://github.com/gohugoio/hugo/ +Fork the [project repository]. -Step 2 -: Clone your fork. +### Step 2 -Step 3 -: Create a new branch with a descriptive name that includes the corresponding issue number. +Clone your fork. + +### Step 3 + +Create a new branch with a descriptive name that includes the corresponding issue number. For a new feature: @@ -93,11 +70,13 @@ For a bug fix: git checkout -b fix/fix-some-bug-99999 ``` -Step 4 -: Make changes. +### Step 4 -Step 5 -: Compile and install. +Make changes. + +### Step 5 + +Compile and install. To compile and install the standard edition: @@ -117,22 +96,25 @@ To compile and install the extended/deploy edition: CGO_ENABLED=1 go install -tags extended,withdeploy ``` -Step 6 -: Test your changes: +### Step 6 + +Test your changes: ```text go test ./... ``` -Step 7 -: Commit your changes with a descriptive commit message: +### Step 7 + +Commit your changes with a descriptive commit message: - Provide a summary on the first line, typically 50 characters or less, followed by a blank line. -- Optionally, provide a detailed description where each line is 80 characters or less, followed by a blank line. + - Begin the summary with one of content, theme, config, all, or misc, followed by a colon, a space, and a brief description of the change beginning with a capital letter + - Use imperative present tense + - See the [commit message guidelines] for requirements +- Optionally, provide a detailed description where each line is 72 characters or less, followed by a blank line. - Add one or more "Fixes" or "Closes" keywords, each on its own line, referencing the [issues] addressed by this change. -[issues]: https://github.com/gohugoio/hugo/issues - For example: ```sh @@ -146,18 +128,17 @@ Fixes #99998 Closes #99999" ``` -See the [commit message guidelines] for details. +### Step 8 -[commit message guidelines]: https://github.com/gohugoio/hugo/blob/master/CONTRIBUTING.md#git-commit-message-guidelines +Push the new branch to your fork of the documentation repository. -Step 8 -: Push the new branch to your fork of the documentation repository. +### Step 9 -Step 9 -: Visit the [project repository] and create a pull request (PR). +Visit the [project repository] and create a pull request (PR). -Step 10 -: A project maintainer will review your PR and may request changes. You may delete your branch after the maintainer merges your PR. +### Step 10 + +A project maintainer will review your PR and may request changes. You may delete your branch after the maintainer merges your PR. ## Building from source @@ -172,7 +153,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.141.0 +CGO_ENABLED=1 go install -tags extended github.com/gohugoio/hugo@v0.144.2 ``` To build and install at the latest commit on the master branch: @@ -186,3 +167,20 @@ To build and install at a specific commit: ```sh CGO_ENABLED=1 go install -tags extended github.com/gohugoio/hugo@0851c17 ``` + +[bugs]: https://github.com/gohugoio/hugo/issues?q=is%3Aopen+is%3Aissue+label%3ABug +[Clang]: https://clang.llvm.org/ +[commit message guidelines]: https://github.com/gohugoio/hugo/blob/master/CONTRIBUTING.md#git-commit-message-guidelines +[Contribution Guide]: https://github.com/gohugoio/hugo/blob/master/CONTRIBUTING.md +[create a proposal]: https://github.com/gohugoio/hugo/issues/new?labels=Proposal%2C+NeedsTriage&template=feature_request.md +[documentation]: /documentation +[documentation repository]: https://github.com/gohugoio/hugoDocs +[forum]: https://discourse.gohugo.io +[GCC]: https://gcc.gnu.org/ +[Git]: https://git-scm.com/book/en/v2/Getting-Started-Installing-Git +[Go]: https://go.dev/doc/install +[Go documentation]: https://go.dev/doc/code#Command +[issue queue]: https://github.com/gohugoio/hugo/issues +[issues]: https://github.com/gohugoio/hugo/issues +[project repository]: https://github.com/gohugoio/hugo/ +[themes]: https://themes.gohugo.io/ diff --git a/content/en/contribute/documentation.md b/content/en/contribute/documentation.md index 285985b3d..1d185d21d 100644 --- a/content/en/contribute/documentation.md +++ b/content/en/contribute/documentation.md @@ -1,59 +1,46 @@ --- title: Documentation description: Help us to improve the documentation by identifying issues and suggesting changes. -categories: [contribute] -keywords: [documentation] -menu: - docs: - parent: contribute - weight: 30 -weight: 30 -toc: true +categories: [] +keywords: [] aliases: [/contribute/docs/] --- ## Introduction -We welcome corrections and improvements to the documentation. Please note that the documentation resides in its own repository, separate from the project repository. +We welcome corrections and improvements to the documentation. The documentation lives in a separate repository from the main project. To contribute: -For corrections and improvements to the current documentation, please submit issues and pull requests to the [documentation repository]. - -For documentation related to a new feature, please include the documentation changes when you submit a pull request to the [project repository]. +- For corrections and improvements to existing documentation, submit issues and pull requests to the [documentation repository]. +- For documentation of new features, include the documentation changes in your pull request to the [project repository]. ## Guidelines ### Style -Please adhere to Google's [developer documentation style guide]. - -[developer documentation style guide]: https://developers.google.com/style +Follow Google's [developer documentation style guide]. ### Markdown -Please follow these guidelines: +Adhere to these Markdown conventions: -- Use [ATX] headings, not [setext] headings, levels 2 through 4 -- Use [fenced code blocks], not [indented code blocks] -- Use hyphens, not asterisks, with unordered [list items] -- Use the [note shortcode] instead of blockquotes or bold text -- Do not mix [raw HTML] within Markdown -- Do not use bold text instead of a heading or description term (`dt`) -- Remove consecutive blank lines (maximum of two) -- Remove trailing spaces +- Use [ATX] headings (levels 2-4), not [setext] headings. +- Use [fenced code blocks], not [indented code blocks]. +- Use hyphens, not asterisks, for unordered [list items]. +- Use [callouts](#callouts) instead of bold text for emphasis. +- Do not mix [raw HTML] within Markdown. +- Do not use bold text in place of a heading or description term (`dt`). +- Remove consecutive blank lines. +- Remove trailing spaces. ### Glossary -Glossary terms are maintained on individual pages. While not directly accessible to site visitors, these pages act as a central repository for term definitions. +[Glossary] terms are defined on individual pages, providing a central repository for definitions, though these pages are not directly linked from the site. -Definitions must be presented in complete sentences, with the first sentence always introducing the term being defined. To enhance readability and consistency, the first occurrence of the term and any other referenced glossary terms should be italicized. +Definitions must be complete sentences, with the first sentence defining the term. Italicize the first occurrence of the term and any referenced glossary terms for consistency. -To link to a term definition on the glossary page, use this custom link syntax: +Link to glossary terms using this syntax: `[term](g)` -```text -[term](g) -``` - -Lookups are case-insensitive, ignore formatting, and support both singular and plural forms. For example, all of these variations will link to the same glossary term: +Term lookups are case-insensitive, ignore formatting, and support singular and plural forms. For example, all of these variations will link to the same glossary term: ```text [global resource](g) @@ -62,7 +49,7 @@ Lookups are case-insensitive, ignore formatting, and support both singular and p [`Global Resources`](g) ``` -To insert a term definition, use the [`glossary-term`] shortcode: +Use the [glossary-term shortcode](#glossary-term) to insert a term definition: ```text {{%/* glossary-term "global resource" */%}} @@ -70,29 +57,38 @@ To insert a term definition, use the [`glossary-term`] shortcode: ### Terminology -Please link to the glossary (see above) when necessary, and use the terms consistently throughout the documentation. Of special note: +Link to the [glossary] as needed and use terms consistently. Pay particular attention to: -- The term "front matter" is two words unless you are referring to the configuration key -- The term "home page" is two words -- The term "website" is one word -- The term "standalone" is one word, not hyphenated -- Use the word "map" instead of "dictionary" -- Use the word "flag" instead of "option" when referring to a command line flag -- Use "client side" as a noun, and "client-side" as an adjective -- Capitalize the word "Markdown" -- Hyphenate the term "open-source" when used an adjective. +- "front matter" (two words, except when referring to the configuration key) +- "home page" (two words) +- "website" (one word) +- "standalone" (one word, no hyphen) +- "map" (instead of "dictionary") +- "flag" (instead of "option" for command-line flags) +- "client side" (noun), "client-side" (adjective) +- "server side" (noun), "server-side" (adjective) +- "Markdown" (capitalized) +- "open-source" (hyphenated adjective) -### Page titles and headings +### Titles and headings -Please follow these guidelines for page titles and headings: +- Use sentence-style capitalization. +- Avoid formatted strings. +- Keep them concise. -- Use sentence-style capitalization -- Avoid formatted strings in headings and page titles -- Shorter is better +### Page descriptions -### Use active voice with present tense +When writing the page `description` use imperative present tense when possible. For example: -In software documentation, passive voice is unavoidable in some cases. Please use active voice when possible. +{{< code-toggle file=content/en/functions/data/_index.md" fm=true >}} +title: Data functions +linkTitle: data +description: Use these functions to read local or remote data files. +{{< /code-toggle >}} + +### Writing style + +Use active voice and present tense wherever possible. No → With Hugo you can build a static site.\ Yes → Build a static site with Hugo. @@ -100,65 +96,124 @@ Yes → Build a static site with Hugo. No → This will cause Hugo to generate HTML files in the `public` directory.\ Yes → Hugo generates HTML files in the `public` directory. -### Use second person instead of third person +Use second person instead of third person. No → Users should exercise caution when deleting files.\ Better → You must be cautious when deleting files.\ Best → Be cautious when deleting files. -### Avoid adverbs when possible +Minimize adverbs. No → Hugo is extremely fast.\ Yes → Hugo is fast. -{{% note %}} -"It's an adverb, Sam. It's a lazy tool of a weak mind." (Outbreak, 1995). -{{% /note %}} - -### Level 6 headings - -Level 6 headings are styled as `dt` elements. This was implemented to support a [glossary] with linkable terms. +> [!note] +> "It's an adverb, Sam. It's a lazy tool of a weak mind." (Outbreak, 1995). ### Function and method descriptions -When adding a page to the [functions] or [methods] section, begin the description with the word "Returns". With functions and methods that return a boolean value, begin the description with the phrase "Reports whether". +Start descriptions in the functions and methods sections with "Returns", of for booelan values, "Reports whether". -For example: +### File paths and names -- `Returns the URL aliases as defined in front matter.` -- `Reports whether the given page is in the given section.` - -[functions]: /functions -[methods]: /methods - -### Directory names, file names, and file paths - -Enclose directory names, file names, and file paths within backticks, with the following exceptions: +Enclose directory names, file names, and file paths in backticks, except when used in: - Page titles - Section headings (h1-h6) - Definition list terms -- The description field in front matter +- The `description` field in front matter ### Miscellaneous -Other guidelines to consider: +Other best practices: -- Do not place list items directly under a heading; include an introductory sentence or phrase before the list. -- Avoid use of **bold** text. Use the [note shortcode] to draw attention to important content. -- Do not place description terms (`dt`) within backticks unless required for syntactic clarity. -- Do not use Hugo's `ref` or `relref` shortcodes. We use a link render hook to resolve and validate link destinations, including fragments. -- Shorter is better. If there is more than one way to do something, describe the current best practice. For example, avoid phrases such as "you can also do..." and "in older versions you had to..." -- When including code samples, use short snippets that demonstrate the concept. -- The Hugo user community is global; use [basic english](https://simple.wikipedia.org/wiki/Basic_English) when possible. +- Introduce lists with a sentence or phrase, not directly under a heading. +- Avoid bold text; use [callouts](#callouts) for emphasis. +- Do not put description terms (`dt`) in backticks unless syntactically necessary. +- Do not use Hugo's `ref` or `relref` shortcodes. +- Prioritize current best practices over multiple options or historical information. +- Use short, focused code examples. +- Use [basic english] where possible for a global audience. + +## Front matter fields + +This site uses the front matter fields listed in the table below. + +Of the four required fields, only `title` and `description` require data. + +```text +title: The title +description: The description +categories: [] +keywords: [] +``` + +This example demonstrates the minimum required front matter fields. + +If quotation marks are required, prefer single quotes to double quotes when possible. + +Seq|Field|Description|Required +--:|:--|:--|:-- +1|`title`|The page title|:heavy_check_mark:| +2|`linkTitle`|A short version of the page title|| +3|`description`|A complete sentence describing the page|:heavy_check_mark:| +4|`categories`|An array of terms in the categories taxonomy|:heavy_check_mark: [^1]| +5|`keywords`|An array of keywords used to identify related content|:heavy_check_mark: [^1]| +6|`publishDate`|Applicable to news items: the publication date|| +7|`params.altTitle`|An alternate title: used in the "see also" panel if provided|| +8|`params.functions_and_methods.aliases`|Applicable to function and method pages: an array of alias names|| +9|`params.functions_and_methods.returnType`|Applicable to function and method pages: the data type returned|| +10|`params.functions_and_methods.signatures`|Applicable to function and method pages: an array of signatures|| +11|`params.hide_in_this_section`|Whether to hide the "in this section" panel|| +12|`params.minversion`|Applicable to the quick start page: the minimum Hugo version required|| +13|`params.permalink`|Reserved for use by the news content adapter|| +14|`params.reference (used in glossary term)`|Applicable to glossary entries: a URL for additional information|| +15|`params.show_publish_date`|Whether to show the `publishDate` when rendering the page|| +16|`weight`|The page weight|| +17|`aliases`|Previous URLs used to access this page|| +18|`expirydate`|The expiration date|| + +[^1]: The field is required, but its data is not. + +## Related content + +When available, the "See also" sidebar displays related pages using Hugo's [related content] feature, based on front matter keywords. We ensure consistent keyword usage by validating them against `data/keywords.yaml` during the build process. If a keyword is not found, you'll be alerted and must either modify the keyword or update the data file. This validation process helps to refine the related content for better results. + +If the title in the "See also" sidebar is ambiguous or the same as another page, you can define an alternate title in the front matter: + +{{< code-toggle file=hugo >}} +title = "Long descriptive title" +linkTitle = "Short title" +[params] +altTitle = "Whatever you want" +{{< /code-toggle >}} + +Use of the alternate title is limited to the "See also" sidebar. + +> [!note] +> Think carefully before setting the `altTitle`. Use it only when absolutely necessary. ## Code examples -Indent code by two spaces. With examples of template code, include a space after opening action delimiters, and include a space before closing action delimiters. +With examples of template code: + +- Indent with two spaces. +- Insert a space after an opening action delimiter. +- Insert a space before a closing action delimiter. +- Do not add white space removal syntax to action delimiters unless required. For example, inline elements like `img` and `a` require whitespace removal on both sides. + +```go-html-template +{{ if eq $foo $bar }} + {{ fmt.Printf "%s is %s" $foo $bar }} +{{ end }} +``` ### Fenced code blocks -Always include the language code when using a fenced code block: +Always specify the language. + +When providing a Mardown example, set the code language to "text" to prevent +erroneous lexing/highlighting of shortcode calls. ````text ```go-html-template @@ -168,29 +223,40 @@ Always include the language code when using a fenced code block: ``` ```` -```go-html-template +To include a filename header and copy-to-clipboard button: + +````text +```go-html-template {file="layouts/partials/foo.html" copy=true} {{ if eq $foo "bar" }} {{ print "foo is bar" }} {{ end }} ``` +```` + +To wrap the code block within an initially-opened `details` element using a non-default summary: + +````text +```go-html-template {details=true open=true summary="layouts/partials/foo.html" copy=true} +{{ if eq $foo "bar" }} + {{ print "foo is bar" }} +{{ end }} +``` +```` ### Shortcode calls -Use this syntax to include shortcodes calls within your code examples: +Use this syntax : +````text ```text {{}} {{%/*/* foo */*/%}} ``` - -```text -{{}} -{{%/* foo */%}} -``` +```` ### Site configuration -Use the [code-toggle shortcode] to include site configuration examples: +Use the [code-toggle shortcode](#code-toggle) to include site configuration examples: ```text {{}} @@ -200,15 +266,9 @@ title = 'My Site' {{}} ``` -{{< code-toggle file=hugo >}} -baseURL = 'https://example.org/' -languageCode = 'en-US' -title = 'My Site' -{{< /code-toggle >}} - ### Front matter -Use the [code-toggle shortcode] to include front matter examples: +Use the [code-toggle shortcode](#code-toggle) to include front matter examples: ```text {{}} @@ -218,60 +278,65 @@ draft = false {{}} ``` -{{< code-toggle file=content/posts/my-first-post.md fm=true >}} -title = 'My first post' -date = 2023-11-09T12:56:07-08:00 -draft = false -{{< /code-toggle >}} +## Callouts -### Other code examples +To visually emphasize important information, use callouts (admonitions). Callout types are case-insensitive. Effective March 8, 2025, we utilize only three of the five available types. -Use the [code shortcode] for other code examples that require a file name: +- note (272 instances) +- warning (2 instances) +- caution (1 instance) + +Limiting the number of callout types helps us to use them consistently. ```text -{{}} -{{ range .Site.RegularPages }} -

{{ .LinkTitle }}

-{{ end }} -{{}} +> [!note] +> Useful information that users should know, even when skimming content. ``` -{{< code file=layouts/_default/single.html >}} -{{ range .Site.RegularPages }} -

{{ .LinkTitle }}

-{{ end }} -{{< /code >}} +> [!note] +> Useful information that users should know, even when skimming content. + +```text +> [!warning] +> Urgent info that needs immediate user attention to avoid problems. +``` + +> [!warning] +> Urgent info that needs immediate user attention to avoid problems. + +```text +> [!caution] +> Advises about risks or negative outcomes of certain actions. +``` + +> [!caution] +> Advises about risks or negative outcomes of certain actions. + +```text +> [!tip] +> Helpful advice for doing things better or more easily. +``` + +> [!tip] +> Helpful advice for doing things better or more easily. + +```text +> [!important] +> Key information users need to know to achieve their goal. +``` + +> [!important] +> Key information users need to know to achieve their goal. + + ## Shortcodes These shortcodes are commonly used throughout the documentation. Other shortcodes are available for specialized use. -### code - -Use the `code` shortcode for other code examples that require a file name. See the [code examples] above. This shortcode takes these arguments: - -copy -: (`bool`) Whether to display a copy-to-clipboard button. Default is `false`. - -file -: (`string`) The file name to display. - -lang -: (`string`) The code language. If you do not provide a `lang` argument, the code language is determined by the file extension. If the file extension is `html`, sets the code language to `go-html-template`. Default is `text`. - -```text -{{}} -Some code here -{{}} -``` - -{{< code file=content/something/foo.md lang=text copy=true >}} -Some code here -{{< /code >}} - ### code-toggle -Use the `code-toggle` shortcode to display examples of site configuration, front matter, or data files. See the [code examples] above. This shortcode takes these arguments: +Use the `code-toggle` shortcode to display examples of site configuration, front matter, or data files. This shortcode takes these arguments: config : (`string`) The section of `site.Data.docs.config` to render. @@ -279,45 +344,39 @@ config copy : (`bool`) Whether to display a copy-to-clipboard button. Default is `false`. +datakey: +: (`string`) The section of `site.Data.docs` to render. + file -: (`string`) The file name to display. Omit the file extension for site configuration examples. Default is `hugo` +: (`string`) The file name to display above the rendered code. Omit the file extension for site configuration examples. fm -: (`bool`) Whether the example is front matter. Default is `false`. +: (`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 `site.Data.docs.config`. ```text -{{}} -title: Example -draft: false +{{}} +baseURL = 'https://example.org/' +languageCode = 'en-US' +title = 'My Site' {{}} ``` -{{< code-toggle >}} -title: Example -draft: false -{{< /code-toggle >}} - ### deprecated-in Use the `deprecated-in` shortcode to indicate that a feature is deprecated: ```text -{{%/* deprecated-in 0.127.0 */%}} +{{}} + Use [`hugo.IsServer`] instead. [`hugo.IsServer`]: /functions/hugo/isserver/ -{{%/* /deprecated-in */%}} +{{}} ``` -{{% deprecated-in 0.127.0 %}} -Use [`hugo.IsServer`] instead. - -[`hugo.IsServer`]: /functions/hugo/isserver/ -{{% /deprecated-in %}} - ### eturl Use the embedded template URL (`eturl`) shortcode to insert an absolute URL to the source code for an embedded template. The shortcode takes a single argument, the base file name of the template (omit the file extension). @@ -328,10 +387,6 @@ This is a link to the [embedded alias template]. [embedded alias template]: {{%/* eturl alias */%}} ``` -This is a link to the [embedded alias template]. - -[embedded alias template]: {{% eturl alias %}} - ### glossary-term Use the `glossary-term` shortcode to insert the definition of the given glossary term. @@ -340,14 +395,12 @@ Use the `glossary-term` shortcode to insert the definition of the given glossary {{%/* glossary-term scalar */%}} ``` -{{% glossary-term scalar %}} - ### include Use the `include` shortcode to include content from another page. ```text -{{%/* include "functions/_common/glob-patterns" */%}} +{{%/* include "_common/glob-patterns.md" */%}} ``` ### new-in @@ -355,97 +408,92 @@ Use the `include` shortcode to include content from another page. Use the `new-in` shortcode to indicate a new feature: ```text -{{}} +{{}} ``` -{{< new-in 0.127.0 />}} - -### note - -Use the `note` shortcode with `{{%/* */%}}` delimiters to call attention to important content: +You can also include details: ```text -{{%/* note */%}} -Use the [`math.Mod`] function to control... - -[`math.Mod`]: /functions/math/mod/ -{{%/* /note */%}} +{{}} +This is a new feature. +{{}} ``` -{{% note %}} -Use the [`math.Mod`] function to control... - -[`math.Mod`]: /functions/math/mod/ -{{% /note %}} - ## New features -Use the "new-in" shortcode to indicate a new feature: +Use the [new-in shortcode](#new-in) to indicate a new feature: -{{< code file=content/something/foo.md lang=text >}} -{{}} -{{< /code >}} +```text +{{}} +``` The "new in" label will be hidden if the specified version is older than a predefined threshold, based on differences in major and minor versions. See [details](https://github.com/gohugoio/hugoDocs/blob/master/_vendor/github.com/gohugoio/gohugoioTheme/layouts/shortcodes/new-in.html). ## Deprecated features -Use the "deprecated-in" shortcode to indicate that a feature is deprecated: +Use the [deprecated-in shorcode](#deprecated-in) shortcode to indicate that a feature is deprecated: -{{< code file=content/something/foo.md >}} -{{%/* deprecated-in 0.120.0 */%}} +```text +{{}} Use [`hugo.IsServer`] instead. [`hugo.IsServer`]: /functions/hugo/isserver/ -{{%/* /deprecated-in */%}} -{{< /code >}} +{{}} +``` When deprecating a function or method, add something like this to front matter: {{< code-toggle file=content/something/foo.md fm=true >}} -expiryDate: 2024-10-30 # deprecated 2022-10-30 in v0.123.0 +expiryDate: 2027-02-17 # deprecated 2025-02-17 in v0.144.0 {{< /code-toggle >}} Set the `expiryDate` to two years from the date of deprecation, and add a brief front matter comment to explain the setting. ## GitHub workflow -{{% note %}} -This section assumes that you have a working knowledge of Git and GitHub, and are comfortable working on the command line. -{{% /note %}} +> [!note] +> This section assumes that you have a working knowledge of Git and GitHub, and are comfortable working on the command line. Use this workflow to create and submit pull requests. -Step 1 -: Fork the [documentation repository]. +### Step 1 -Step 2 -: Clone your fork. +Fork the [documentation repository]. -Step 3 -: Create a new branch with a descriptive name that includes the corresponding issue number, if any: +### Step 2 + +Clone your fork. + +### Step 3 + +Create a new branch with a descriptive name that includes the corresponding issue number, if any: ```sh git checkout -b restructure-foo-page-99999 ``` -Step 4 -: Make changes. +### Step 4 -Step 5 -: Build the site locally to preview your changes. +Make changes. -Step 6 -: Commit your changes with a descriptive commit message: +### Step 5 + +Build the site locally to preview your changes. + +### Step 6 + +Commit your changes with a descriptive commit message: - Provide a summary on the first line, typically 50 characters or less, followed by a blank line. -- Optionally, provide a detailed description where each line is 80 characters or less, followed by a blank line. + - Begin the summary with one of `content`, `theme`, `config`, `all`, or `misc`, followed by a colon, a space, and a brief description of the change beginning with a capital letter + - Use imperative present tense +- Optionally, provide a detailed description where each line is 72 characters or less, followed by a blank line. - Optionally, add one or more "Fixes" or "Closes" keywords, each on its own line, referencing the [issues] addressed by this change. For example: -```sh -git commit -m "Restructure the taxonomy page +```text +git commit -m "content: Restructure the taxonomy page This restructures the taxonomy page by splitting topics into logical sections, each with one or more examples. @@ -454,29 +502,29 @@ Fixes #9999 Closes #9998" ``` -Step 7 -: Push the new branch to your fork of the documentation repository. +### Step 7 -Step 8 -: Visit the [documentation repository] and create a pull request (PR). +Push the new branch to your fork of the documentation repository. -Step 9 -: A project maintainer will review your PR and may request changes. You may delete your branch after the maintainer merges your PR. +### Step 8 + +Visit the [documentation repository] and create a pull request (PR). + +### Step 9 + +A project maintainer will review your PR and may request changes. You may delete your branch after the maintainer merges your PR. [ATX]: https://spec.commonmark.org/0.30/#atx-headings -[Microsoft Writing Style Guide]: https://learn.microsoft.com/en-us/style-guide/welcome/ -[`glossary-term`]: #glossary-term [basic english]: https://simple.wikipedia.org/wiki/Basic_English -[code examples]: #code-examples -[code shortcode]: #code -[code-toggle shortcode]: #code-toggle +[basic english]: https://simple.wikipedia.org/wiki/Basic_English +[developer documentation style guide]: https://developers.google.com/style [documentation repository]: https://github.com/gohugoio/hugoDocs/ [fenced code blocks]: https://spec.commonmark.org/0.30/#fenced-code-blocks [glossary]: /quick-reference/glossary/ [indented code blocks]: https://spec.commonmark.org/0.30/#indented-code-blocks [issues]: https://github.com/gohugoio/hugoDocs/issues [list items]: https://spec.commonmark.org/0.30/#list-items -[note shortcode]: #note [project repository]: https://github.com/gohugoio/hugo [raw HTML]: https://spec.commonmark.org/0.30/#raw-html +[related content]: /content-management/related-content/ [setext]: https://spec.commonmark.org/0.30/#setext-heading diff --git a/content/en/contribute/themes.md b/content/en/contribute/themes.md index 7277e2927..8a3457ba3 100644 --- a/content/en/contribute/themes.md +++ b/content/en/contribute/themes.md @@ -1,13 +1,8 @@ --- title: Themes description: If you've built a Hugo theme and want to contribute back to the Hugo Community, please share it with us. -categories: [contribute] -keywords: [themes] -menu: - docs: - parent: contribute - weight: 40 -weight: 40 +categories: [] +keywords: [] aliases: [/contribute/theme/] --- diff --git a/content/en/documentation.md b/content/en/documentation.md index 11f843f91..6f96c1f9c 100644 --- a/content/en/documentation.md +++ b/content/en/documentation.md @@ -2,21 +2,19 @@ title: Hugo Documentation linkTitle: Docs description: Hugo is the world's fastest static website engine. It's written in Go (aka Golang) and developed by bep, spf13 and friends. -menu: - main: - weight: 1 -weight: 1 layout: list --- -A fast and flexible [static site generator] built with love by [bep], [spf13], and [friends] in [Go]. + diff --git a/content/en/functions/_common/_index.md b/content/en/functions/_common/_index.md deleted file mode 100644 index 4328d4d14..000000000 --- a/content/en/functions/_common/_index.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -cascade: - _build: - list: never - publishResources: false - render: never ---- - - diff --git a/content/en/functions/_common/locales.md b/content/en/functions/_common/locales.md deleted file mode 100644 index 42d008776..000000000 --- a/content/en/functions/_common/locales.md +++ /dev/null @@ -1,10 +0,0 @@ ---- -_comment: Do not remove front matter. ---- - -{{% note %}} - -Localization of dates, currencies, numbers, and percentages is performed by the [gohugoio/locales] package. The language tag of the current site must match one of the listed locales. - -[gohugoio/locales]: https://github.com/gohugoio/locales -{{% /note %}} diff --git a/content/en/functions/_index.md b/content/en/functions/_index.md index 95d766b13..d3081210b 100644 --- a/content/en/functions/_index.md +++ b/content/en/functions/_index.md @@ -1,17 +1,8 @@ --- title: Functions - description: Use these functions within your templates and archetypes. categories: [] keywords: [] -menu: - docs: - identifier: functions-in-this-section - parent: functions - weight: 10 weight: 10 -showSectionMenu: true aliases: [/layout/functions/,/templates/functions] --- - -Use these functions within your templates and archetypes. diff --git a/content/en/functions/cast/ToFloat.md b/content/en/functions/cast/ToFloat.md index 51bc908b6..572042937 100644 --- a/content/en/functions/cast/ToFloat.md +++ b/content/en/functions/cast/ToFloat.md @@ -3,13 +3,11 @@ title: cast.ToFloat description: Converts a value to a decimal floating-point number (base 10). categories: [] keywords: [] -action: - aliases: [float] - related: - - functions/cast/ToInt - - functions/cast/ToString - returnType: float64 - signatures: [cast.ToFloat INPUT] +params: + functions_and_methods: + aliases: [float] + returnType: float64 + signatures: [cast.ToFloat INPUT] aliases: [/functions/float] --- diff --git a/content/en/functions/cast/ToInt.md b/content/en/functions/cast/ToInt.md index c4bb10268..4ede69229 100644 --- a/content/en/functions/cast/ToInt.md +++ b/content/en/functions/cast/ToInt.md @@ -2,13 +2,11 @@ title: cast.ToInt description: Converts a value to a decimal integer (base 10). keywords: [] -action: - aliases: [int] - related: - - functions/cast/ToFloat - - functions/cast/ToString - returnType: int - signatures: [cast.ToInt INPUT] +params: + functions_and_methods: + aliases: [int] + returnType: int + signatures: [cast.ToInt INPUT] aliases: [/functions/int] --- @@ -46,8 +44,7 @@ With a hexadecimal (base 16) input: {{ int "0x11" }} → 17 (int) ``` -{{% note %}} -Values with a leading zero are octal (base 8). When casting a string representation of a decimal (base 10) number, remove leading zeros: +> [!note] +> Values with a leading zero are octal (base 8). When casting a string representation of a decimal (base 10) number, remove leading zeros: `{{ strings.TrimLeft "0" "0011" | int }} → 11` -{{% /note %}} diff --git a/content/en/functions/cast/ToString.md b/content/en/functions/cast/ToString.md index a701c9421..1bba001c9 100644 --- a/content/en/functions/cast/ToString.md +++ b/content/en/functions/cast/ToString.md @@ -3,13 +3,11 @@ title: cast.ToString description: Converts a value to a string. categories: [] keywords: [] -action: - aliases: [string] - related: - - functions/cast/ToFloat - - functions/cast/ToInt - returnType: string - signatures: [cast.ToString INPUT] +params: + functions_and_methods: + aliases: [string] + returnType: string + signatures: [cast.ToString INPUT] aliases: [/functions/string] --- diff --git a/content/en/functions/cast/_index.md b/content/en/functions/cast/_index.md index 82389237a..1584ab159 100644 --- a/content/en/functions/cast/_index.md +++ b/content/en/functions/cast/_index.md @@ -1,12 +1,7 @@ --- title: Cast functions linkTitle: cast -description: Template functions to cast a value from one data type to another. +description: Use these functions to cast a value from one data type to another. categories: [] keywords: [] -menu: - docs: - parent: functions --- - -Use these functions to cast a value from one data type to another. diff --git a/content/en/functions/collections/After.md b/content/en/functions/collections/After.md index 1f2759da6..c8a822846 100644 --- a/content/en/functions/collections/After.md +++ b/content/en/functions/collections/After.md @@ -3,13 +3,11 @@ title: collections.After description: Slices an array to the items after the Nth item. categories: [] keywords: [] -action: - aliases: [after] - related: - - functions/collections/First - - functions/collections/Last - returnType: any - signatures: [collections.After INDEX COLLECTION] +params: + functions_and_methods: + aliases: [after] + returnType: any + signatures: [collections.After INDEX COLLECTION] aliases: [/functions/after] --- @@ -40,7 +38,7 @@ You can use `after` in combination with the [`first`] function and Hugo's [power 1. The top row is titled "Featured" and shows only the most recently published article (i.e. by `publishdate` in the content files' front matter). 1. The second row is titled "Recent Articles" and shows only the 2nd- to 4th-most recently published articles. -{{< code file=layouts/section/articles.html >}} +```go-html-template {file="layouts/section/articles.html"} {{ define "main" }}

Featured Article

@@ -63,7 +61,7 @@ You can use `after` in combination with the [`first`] function and Hugo's [power {{ end }} {{ end }} -{{< /code >}} +``` [`first`]: /functions/collections/first/ [`slice`]: /functions/collections/slice/ diff --git a/content/en/functions/collections/Append.md b/content/en/functions/collections/Append.md index 7189c9068..cf1d1a3f5 100644 --- a/content/en/functions/collections/Append.md +++ b/content/en/functions/collections/Append.md @@ -3,14 +3,13 @@ title: collections.Append description: Appends one or more elements to a slice and returns the resulting slice. categories: [] keywords: [] -action: - aliases: [append] - related: - - functions/collections/Merge - returnType: any - signatures: - - collections.Append ELEMENT [ELEMENT...] COLLECTION - - collections.Append COLLECTION1 COLLECTION2 +params: + functions_and_methods: + aliases: [append] + returnType: any + signatures: + - collections.Append ELEMENT [ELEMENT...] COLLECTION + - collections.Append COLLECTION1 COLLECTION2 aliases: [/functions/append] --- diff --git a/content/en/functions/collections/Apply.md b/content/en/functions/collections/Apply.md index 9153e546a..7ffe49053 100644 --- a/content/en/functions/collections/Apply.md +++ b/content/en/functions/collections/Apply.md @@ -3,11 +3,11 @@ title: collections.Apply description: Returns a new collection with each element transformed by the given function. categories: [] keywords: [] -action: - aliases: [apply] - related: [] - returnType: '[]any' - signatures: [collections.Apply COLLECTION FUNCTION PARAM...] +params: + functions_and_methods: + aliases: [apply] + returnType: '[]any' + signatures: [collections.Apply COLLECTION FUNCTION PARAM...] aliases: [/functions/apply] --- diff --git a/content/en/functions/collections/Complement.md b/content/en/functions/collections/Complement.md index 1c785de0b..ce810dc00 100644 --- a/content/en/functions/collections/Complement.md +++ b/content/en/functions/collections/Complement.md @@ -3,14 +3,11 @@ title: collections.Complement description: Returns the elements of the last collection that are not in any of the others. categories: [] keywords: [] -action: - aliases: [complement] - related: - - functions/collections/Intersect - - functions/collections/SymDiff - - functions/collections/Union - returnType: any - signatures: ['collections.Complement COLLECTION [COLLECTION...]'] +params: + functions_and_methods: + aliases: [complement] + returnType: any + signatures: ['collections.Complement COLLECTION [COLLECTION...]'] aliases: [/functions/complement] --- @@ -24,11 +21,8 @@ To find the elements within `$c3` that do not exist in `$c1` or `$c2`: {{ complement $c1 $c2 $c3 }} → [1 2] ``` -{{% note %}} -Make your code simpler to understand by using a [chained pipeline]: - -[chained pipeline]: https://pkg.go.dev/text/template#hdr-Pipelines -{{% /note %}} +> [!note] +> Make your code simpler to understand by using a [chained pipeline]: ```go-html-template {{ $c3 | complement $c1 $c2 }} → [1 2] @@ -55,11 +49,8 @@ To list everything except blog articles (`blog`) and frequently asked questions {{ end }} ``` -{{% note %}} -Although the example above demonstrates the `complement` function, you could use the [`where`] function as well: - -[`where`]: /functions/collections/where/ -{{% /note %}} +> [!note] +> Although the example above demonstrates the `complement` function, you could use the [`where`] function as well: ```go-html-template {{ range where site.RegularPages "Type" "not in" (slice "blog" "faqs") }} @@ -77,4 +68,6 @@ In this example we use the `complement` function to remove [stop words] from a s {{ delimit $filtered " " }} → The quick brown fox jumps lazy dog ``` +[`where`]: /functions/collections/where/ +[chained pipeline]: https://pkg.go.dev/text/template#hdr-Pipelines [stop words]: https://en.wikipedia.org/wiki/Stop_word diff --git a/content/en/functions/collections/Delimit.md b/content/en/functions/collections/Delimit.md index b85059d4b..9d09620aa 100644 --- a/content/en/functions/collections/Delimit.md +++ b/content/en/functions/collections/Delimit.md @@ -3,12 +3,11 @@ title: collections.Delimit description: Loops through any array, slice, or map and returns a string of all the values separated by a delimiter. categories: [] keywords: [] -action: - aliases: [delimit] - related: - - functions/strings/Split - returnType: string - signatures: ['collections.Delimit COLLECTION DELIMITER [LAST]'] +params: + functions_and_methods: + aliases: [delimit] + returnType: string + signatures: ['collections.Delimit COLLECTION DELIMITER [LAST]'] aliases: [/functions/delimit] --- @@ -22,9 +21,8 @@ Delimit a slice: Delimit a map: -{{% note %}} -The `delimit` function sorts maps by key, returning the values. -{{% /note %}} +> [!note] +> The `delimit` function sorts maps by key, returning the values. ```go-html-template {{ $m := dict "b" 2 "a" 1 "c" 3 }} diff --git a/content/en/functions/collections/Dictionary.md b/content/en/functions/collections/Dictionary.md index a55838e27..8aa428106 100644 --- a/content/en/functions/collections/Dictionary.md +++ b/content/en/functions/collections/Dictionary.md @@ -3,12 +3,11 @@ title: collections.Dictionary description: Returns a map composed of the given key-value pairs. categories: [] keywords: [] -action: - aliases: [dict] - related: - - functions/collections/Slice - returnType: map[string]any - signatures: ['collections.Dictionary [VALUE...]'] +params: + functions_and_methods: + aliases: [dict] + returnType: map[string]any + signatures: ['collections.Dictionary [VALUE...]'] aliases: [/functions/dict] --- diff --git a/content/en/functions/collections/First.md b/content/en/functions/collections/First.md index 07634d6b8..9a672278d 100644 --- a/content/en/functions/collections/First.md +++ b/content/en/functions/collections/First.md @@ -3,14 +3,11 @@ title: collections.First description: Returns the given collection, limited to the first N elements. categories: [] keywords: [] -action: - aliases: [first] - related: - - functions/collections/After - - functions/collections/Last - - methods/pages/Limit - returnType: any - signatures: [collections.First N COLLECTION] +params: + functions_and_methods: + aliases: [first] + returnType: any + signatures: [collections.First N COLLECTION] aliases: [/functions/first] --- @@ -23,7 +20,7 @@ aliases: [/functions/first] Set `N` to zero to return an empty collection. ```go-html-template -{{ $emptyPageCollection := first 0 .Pages}} +{{ $emptyPageCollection := first 0 .Pages }} ``` Use `first` and [`where`] together. diff --git a/content/en/functions/collections/Group.md b/content/en/functions/collections/Group.md index 0ec45516c..4b269b92a 100644 --- a/content/en/functions/collections/Group.md +++ b/content/en/functions/collections/Group.md @@ -3,11 +3,11 @@ title: collections.Group description: Groups the given page collection by the given key. categories: [] keywords: [] -action: - aliases: [group] - related: [] - returnType: any - signatures: [collections.Group KEY PAGES] +params: + functions_and_methods: + aliases: [group] + returnType: any + signatures: [collections.Group KEY PAGES] aliases: [/functions/group] --- diff --git a/content/en/functions/collections/In.md b/content/en/functions/collections/In.md index 754c65f83..e94b4b0ed 100644 --- a/content/en/functions/collections/In.md +++ b/content/en/functions/collections/In.md @@ -3,16 +3,11 @@ title: collections.In description: Reports whether the given value is a member of the given set. categories: [] keywords: [] -action: - aliases: [in] - related: - - functions/strings/Contains - - functions/strings/ContainsAny - - functions/strings/ContainsNonSpace - - functions/strings/HasPrefix - - functions/strings/HasSuffix - returnType: bool - signatures: [collections.In SET VALUE] +params: + functions_and_methods: + aliases: [in] + returnType: bool + signatures: [collections.In SET VALUE] aliases: [/functions/in] --- diff --git a/content/en/functions/collections/IndexFunction.md b/content/en/functions/collections/IndexFunction.md index 977e14d1e..248595961 100644 --- a/content/en/functions/collections/IndexFunction.md +++ b/content/en/functions/collections/IndexFunction.md @@ -3,12 +3,11 @@ title: collections.Index description: Returns the object, element, or value associated with the given key or keys. categories: [] keywords: [] -action: - aliases: [index] - related: [] - returnType: any - signatures: - - collections.Index COLLECTION KEY... +params: + functions_and_methods: + aliases: [index] + returnType: any + signatures: [collections.Index COLLECTION KEY...] aliases: [/functions/index,/functions/index-function] --- diff --git a/content/en/functions/collections/Intersect.md b/content/en/functions/collections/Intersect.md index 9e9cc0c76..ffa9c8196 100644 --- a/content/en/functions/collections/Intersect.md +++ b/content/en/functions/collections/Intersect.md @@ -3,14 +3,11 @@ title: collections.Intersect description: Returns the common elements of two arrays or slices, in the same order as the first array. categories: [] keywords: [] -action: - aliases: [intersect] - related: - - functions/collections/Complement - - functions/collections/SymDiff - - functions/collections/Union - returnType: any - signatures: [collections.Intersect SET1 SET2] +params: + functions_and_methods: + aliases: [intersect] + returnType: any + signatures: [collections.Intersect SET1 SET2] aliases: [/functions/intersect] --- diff --git a/content/en/functions/collections/IsSet.md b/content/en/functions/collections/IsSet.md index 62b81b712..5457df5d4 100644 --- a/content/en/functions/collections/IsSet.md +++ b/content/en/functions/collections/IsSet.md @@ -3,13 +3,11 @@ title: collections.IsSet description: Reports whether the key exists within the collection. categories: [] keywords: [] -action: - aliases: [isset] - related: - - functions/go-template/if - - functions/go-template/with - returnType: bool - signatures: [collections.IsSet COLLECTION KEY] +params: + functions_and_methods: + aliases: [isset] + returnType: bool + signatures: [collections.IsSet COLLECTION KEY] aliases: [/functions/isset] --- @@ -40,6 +38,5 @@ But if the value of `showHeroImage` is `false`, we can't use either `if` or `wit {{ end }} ``` -{{% note %}} -When using the `isset` function you must reference the key using lower case. See the previous example. -{{% /note %}} +> [!note] +> When using the `isset` function you must reference the key using lower case. See the previous example. diff --git a/content/en/functions/collections/KeyVals.md b/content/en/functions/collections/KeyVals.md index 6a2109e78..bd58caea0 100644 --- a/content/en/functions/collections/KeyVals.md +++ b/content/en/functions/collections/KeyVals.md @@ -3,12 +3,11 @@ title: collections.KeyVals description: Returns a KeyVals struct. categories: [] keywords: [] -action: - aliases: [keyVals] - related: - - methods/pages/Related - returnType: types.KeyValues - signatures: [collections.KeyVals KEY VALUE...] +params: + functions_and_methods: + aliases: [keyVals] + returnType: types.KeyValues + signatures: [collections.KeyVals KEY VALUE...] aliases: [/functions/keyvals] --- @@ -16,7 +15,7 @@ The primary application for this function is the definition of the `namedSlices` [`Related`]: /methods/pages/related/ -See [related content](/content-management/related). +See [related content](/content-management/related-content/). ```go-html-template {{ $kv := keyVals "foo" "a" "b" "c" }} diff --git a/content/en/functions/collections/Last.md b/content/en/functions/collections/Last.md index 7739b8726..f0cfff219 100644 --- a/content/en/functions/collections/Last.md +++ b/content/en/functions/collections/Last.md @@ -3,13 +3,11 @@ title: collections.Last description: Returns the given collection, limited to the last N elements. categories: [] keywords: [] -action: - aliases: [last] - related: - - functions/collections/After - - functions/collections/First - returnType: any - signatures: [collections.Last N COLLECTION] +params: + functions_and_methods: + aliases: [last] + returnType: any + signatures: [collections.Last N COLLECTION] aliases: [/functions/last] --- @@ -22,7 +20,7 @@ aliases: [/functions/last] Set `N` to zero to return an empty collection. ```go-html-template -{{ $emptyPageCollection := last 0 .Pages}} +{{ $emptyPageCollection := last 0 .Pages }} ``` Use `last` and [`where`] together. diff --git a/content/en/functions/collections/Merge.md b/content/en/functions/collections/Merge.md index 3f5208cfc..c9998be39 100644 --- a/content/en/functions/collections/Merge.md +++ b/content/en/functions/collections/Merge.md @@ -3,12 +3,11 @@ title: collections.Merge description: Returns the result of merging two or more maps. categories: [] keywords: [] -action: - aliases: [merge] - related: - - functions/collections/Append - returnType: any - signatures: [collections.Merge MAP MAP...] +params: + functions_and_methods: + aliases: [merge] + returnType: any + signatures: [collections.Merge MAP MAP...] aliases: [/functions/merge] --- @@ -64,6 +63,5 @@ Example 4 {{ $merged.z.a }} → huey ``` -{{% note %}} -Regardless of depth, merging only applies to maps. For slices, use [append](/functions/collections/append). -{{% /note %}} +> [!note] +> Regardless of depth, merging only applies to maps. For slices, use [append](/functions/collections/append). diff --git a/content/en/functions/collections/NewScratch.md b/content/en/functions/collections/NewScratch.md index a76168961..34fc7f5d6 100644 --- a/content/en/functions/collections/NewScratch.md +++ b/content/en/functions/collections/NewScratch.md @@ -3,23 +3,18 @@ title: collections.NewScratch description: Returns a locally scoped "scratch pad" to store and manipulate data. categories: [] keywords: [] -action: - aliases: [newScratch] - related: - - methods/page/Store - - methods/site/Store - - methods/shortcode/Store - - functions/hugo/Store - returnType: maps.Scratch - signatures: [collections.NewScratch ] -toc: true +params: + functions_and_methods: + aliases: [newScratch] + returnType: maps.Scratch + signatures: [collections.NewScratch ] --- Use the `collections.NewScratch` function to create a locally scoped [scratch pad](g) to store and manipulate data. To create a scratch pad with a different [scope](g), refer to the [scope](#scope) section below. ## Methods -###### Set +### Set Sets the value of the given key. @@ -28,7 +23,7 @@ Sets the value of the given key. {{ $s.Set "greeting" "Hello" }} ``` -###### Get +### Get Gets the value of the given key. @@ -38,7 +33,7 @@ Gets the value of the given key. {{ $s.Get "greeting" }} → Hello ``` -###### Add +### Add Adds the given value to existing value(s) of the given key. @@ -65,7 +60,7 @@ For single values, `Add` accepts values that support Go's `+` operator. If the f {{ $s.Get "greetings" }} → [Hello Welcome Cheers] ``` -###### SetInMap +### SetInMap Takes a `key`, `mapKey` and `value` and adds a map of `mapKey` and `value` to the given `key`. @@ -76,7 +71,7 @@ Takes a `key`, `mapKey` and `value` and adds a map of `mapKey` and `value` to th {{ $s.Get "greetings" }} → map[english:Hello french:Bonjour] ``` -###### DeleteInMap +### DeleteInMap Takes a `key` and `mapKey` and removes the map of `mapKey` from the given `key`. @@ -88,7 +83,7 @@ Takes a `key` and `mapKey` and removes the map of `mapKey` from the given `key`. {{ $s.Get "greetings" }} → map[french:Bonjour] ``` -###### GetSortedMapValues +### GetSortedMapValues Returns an array of values from `key` sorted by `mapKey`. @@ -99,7 +94,7 @@ Returns an array of values from `key` sorted by `mapKey`. {{ $s.GetSortedMapValues "greetings" }} → [Hello Bonjour] ``` -###### Delete +### Delete Removes the given key. @@ -109,9 +104,9 @@ Removes the given key. {{ $s.Delete "greeting" }} ``` -###### Values +### Values -Returns the raw backing map. Do not use with `Scratch` or `Store` methods on a `Page` object due to concurrency issues. +Returns the raw backing map. Do not use with `Store` methods on a `Page` object due to concurrency issues. ```go-html-template {{ $s := newScratch }} diff --git a/content/en/functions/collections/Querify.md b/content/en/functions/collections/Querify.md index 0eb409421..fd74935b7 100644 --- a/content/en/functions/collections/Querify.md +++ b/content/en/functions/collections/Querify.md @@ -3,13 +3,11 @@ title: collections.Querify description: Returns a URL query string composed of the given key-value pairs, encoded and sorted by key. categories: [] keywords: [] -action: - aliases: [querify] - related: - - functions/go-template/urlquery.md - returnType: string - signatures: - - collections.Querify [VALUE...] +params: + functions_and_methods: + aliases: [querify] + returnType: string + signatures: ['collections.Querify [VALUE...]'] aliases: [/functions/querify] --- diff --git a/content/en/functions/collections/Reverse.md b/content/en/functions/collections/Reverse.md index d0a449763..ee455939c 100644 --- a/content/en/functions/collections/Reverse.md +++ b/content/en/functions/collections/Reverse.md @@ -3,14 +3,11 @@ title: collections.Reverse description: Reverses the order of a collection. categories: [] keywords: [] -action: - aliases: [] - related: - - functions/collections/Sort - - functions/collections/Shuffle - - functions/collections/Uniq - returnType: any - signatures: [collections.Reverse COLLECTION] +params: + functions_and_methods: + aliases: [] + returnType: any + signatures: [collections.Reverse COLLECTION] aliases: [/functions/collections.reverse] --- diff --git a/content/en/functions/collections/Seq.md b/content/en/functions/collections/Seq.md index b572bd7c0..e396f07e3 100644 --- a/content/en/functions/collections/Seq.md +++ b/content/en/functions/collections/Seq.md @@ -3,14 +3,14 @@ title: collections.Seq description: Returns a slice of integers. categories: [] keywords: [] -action: - aliases: [seq] - related: [] - returnType: '[]int' - signatures: - - collections.Seq LAST - - collections.Seq FIRST LAST - - collections.Seq FIRST INCREMENT LAST +params: + functions_and_methods: + aliases: [seq] + returnType: '[]int' + signatures: + - collections.Seq LAST + - collections.Seq FIRST LAST + - collections.Seq FIRST INCREMENT LAST aliases: [/functions/seq] --- @@ -31,6 +31,5 @@ A contrived example of iterating over a sequence of integers: {{ $product }} → 24 ``` -{{% note %}} -The slice created by the `seq` function is limited to 2000 elements. -{{% /note %}} +> [!note] +> The slice created by the `seq` function is limited to 2000 elements. diff --git a/content/en/functions/collections/Shuffle.md b/content/en/functions/collections/Shuffle.md index 0f28eb4d8..3a27c099a 100644 --- a/content/en/functions/collections/Shuffle.md +++ b/content/en/functions/collections/Shuffle.md @@ -3,14 +3,11 @@ title: collections.Shuffle description: Returns a random permutation of a given array or slice. categories: [] keywords: [] -action: - aliases: [shuffle] - related: - - functions/collections/Reverse - - functions/collections/Sort - - functions/collections/Uniq - returnType: any - signatures: [collections.Shuffle COLLECTION] +params: + functions_and_methods: + aliases: [shuffle] + returnType: any + signatures: [collections.Shuffle COLLECTION] aliases: [/functions/shuffle] --- diff --git a/content/en/functions/collections/Slice.md b/content/en/functions/collections/Slice.md index 385f9b658..76180fabe 100644 --- a/content/en/functions/collections/Slice.md +++ b/content/en/functions/collections/Slice.md @@ -3,12 +3,11 @@ title: collections.Slice description: Returns a slice composed of the given values. categories: [] keywords: [] -action: - aliases: [slice] - related: - - functions/collections/Dictionary - returnType: any - signatures: ['collections.Slice [VALUE...]'] +params: + functions_and_methods: + aliases: [slice] + returnType: any + signatures: ['collections.Slice [VALUE...]'] aliases: [/functions/slice] --- diff --git a/content/en/functions/collections/Sort.md b/content/en/functions/collections/Sort.md index 815260f20..67e5de5cb 100644 --- a/content/en/functions/collections/Sort.md +++ b/content/en/functions/collections/Sort.md @@ -3,15 +3,11 @@ title: collections.Sort description: Sorts slices, maps, and page collections. categories: [] keywords: [] -action: - aliases: [sort] - related: - - functions/collections/Reverse - - functions/collections/Shuffle - - functions/collections/Uniq - returnType: any - signatures: ['collections.Sort COLLECTION [KEY] [ORDER]'] -toc: true +params: + functions_and_methods: + aliases: [sort] + returnType: any + signatures: ['collections.Sort COLLECTION [KEY] [ORDER]'] aliases: [/functions/sort] --- @@ -65,9 +61,8 @@ firstName = "Jean" lastName = "Valjean" {{< /code-toggle >}} -{{% note %}} -When sorting maps, the `KEY` argument must be lowercase. -{{% /note %}} +> [!note] +> When sorting maps, the `KEY` argument must be lowercase. ### Ascending order {#map-ascending-order} @@ -141,11 +136,8 @@ After sorting: ## Sort a page collection -{{% note %}} -Although you can use the `sort` function to sort a page collection, Hugo provides [sorting and grouping methods] as well. - -[sorting and grouping methods]: /methods/pages/ -{{% /note %}} +> [!note] +> Although you can use the `sort` function to sort a page collection, Hugo provides [sorting and grouping methods] as well. In this contrived example, sort the site's regular pages by `.Type` in descending order: @@ -154,3 +146,5 @@ In this contrived example, sort the site's regular pages by `.Type` in descendin

{{ .LinkTitle }}

{{ end }} ``` + +[sorting and grouping methods]: /methods/pages/ diff --git a/content/en/functions/collections/SymDiff.md b/content/en/functions/collections/SymDiff.md index 7eba3ef42..8974d2d3e 100644 --- a/content/en/functions/collections/SymDiff.md +++ b/content/en/functions/collections/SymDiff.md @@ -3,15 +3,11 @@ title: collections.SymDiff description: Returns the symmetric difference of two collections. categories: [] keywords: [] -action: - aliases: [symdiff] - related: - - functions/collections/Complement - - functions/collections/Intersect - - functions/collections/SymDiff - - functions/collections/Union - returnType: any - signatures: [COLLECTION | collections.SymDiff COLLECTION] +params: + functions_and_methods: + aliases: [symdiff] + returnType: any + signatures: [COLLECTION | collections.SymDiff COLLECTION] aliases: [/functions/symdiff] --- diff --git a/content/en/functions/collections/Union.md b/content/en/functions/collections/Union.md index 7fed49a10..ce6d6d010 100644 --- a/content/en/functions/collections/Union.md +++ b/content/en/functions/collections/Union.md @@ -3,32 +3,24 @@ title: collections.Union description: Given two arrays or slices, returns a new array that contains the elements that belong to either or both arrays/slices. categories: [] keywords: [] -action: - aliases: [union] - related: - - functions/collections/Complement - - functions/collections/Intersect - - functions/collections/SymDiff - - functions/collections/Union - returnType: any - signatures: [collections.Union SET1 SET2] +params: + functions_and_methods: + aliases: [union] + returnType: any + signatures: [collections.Union SET1 SET2] aliases: [/functions/union] --- Given two arrays (or slices) A and B, this function will return a new array that contains the elements or objects that belong to either A or to B or to both. ```go-html-template -{{ union (slice 1 2 3) (slice 3 4 5) }} - +{{ union (slice 1 2 3) (slice 3 4 5) }} → [1 2 3 4 5] -{{ union (slice 1 2 3) nil }} - +{{ union (slice 1 2 3) nil }} → [1 2 3] -{{ union nil (slice 1 2 3) }} - +{{ union nil (slice 1 2 3) }} → [1 2 3] -{{ union nil nil }} - +{{ union nil nil }} → [] ``` ## OR filter in where query diff --git a/content/en/functions/collections/Uniq.md b/content/en/functions/collections/Uniq.md index 02b590c18..d19298b21 100644 --- a/content/en/functions/collections/Uniq.md +++ b/content/en/functions/collections/Uniq.md @@ -3,15 +3,11 @@ title: collections.Uniq description: Returns the given collection, removing duplicate elements. categories: [] keywords: [] -action: - aliases: [uniq] - related: - - functions/collections/Reverse - - functions/collections/Shuffle - - functions/collections/Sort - - functions/collections/Uniq - returnType: any - signatures: [collections.Uniq COLLECTION] +params: + functions_and_methods: + aliases: [uniq] + returnType: any + signatures: [collections.Uniq COLLECTION] aliases: [/functions/uniq] --- diff --git a/content/en/functions/collections/Where.md b/content/en/functions/collections/Where.md index 014a063a1..1df84afc4 100644 --- a/content/en/functions/collections/Where.md +++ b/content/en/functions/collections/Where.md @@ -3,12 +3,11 @@ title: collections.Where description: Returns the given collection, removing elements that do not satisfy the comparison condition. categories: [] keywords: [] -action: - aliases: [where] - related: [] - returnType: any - signatures: ['collections.Where COLLECTION KEY [OPERATOR] VALUE'] -toc: true +params: + functions_and_methods: + aliases: [where] + returnType: any + signatures: ['collections.Where COLLECTION KEY [OPERATOR] VALUE'] aliases: [/functions/where] --- @@ -87,12 +86,12 @@ Use any of the following logical operators: `intersect` : (`bool`) Reports whether the given field value (a slice) contains one or more elements in common with `VALUE`. See [details](/functions/collections/intersect). -`like` {{< new-in 0.116.0 />}} -: (`bool`) Reports whether the given field value matches the regular expression specified in `VALUE`. Use the `like` operator to compare `string` values. The `like` operator returns `false` when comparing other data types to the regular expression. +`like` +: {{< new-in 0.116.0 />}} +: (`bool`) Reports whether the given field value matches the [regular expression](g) specified in `VALUE`. Use the `like` operator to compare `string` values. The `like` operator returns `false` when comparing other data types to the regular expression. -{{% note %}} -The examples below perform comparisons within a page collection, but the same comparisons are applicable to a slice of maps. -{{% /note %}} +> [!note] +> The examples below perform comparisons within a page collection, but the same comparisons are applicable to a slice of maps. ## String comparison @@ -155,7 +154,7 @@ To return a collection of pages where the "color" page parameter is neither "red ## Intersection comparison -Compare a [`slice`] to a [`slice`], returning collection elements with common values. This is frequently used when comparing taxonomy terms. +Compare a `slice` to a `slice`, returning collection elements with common values. This is frequently used when comparing taxonomy terms. For example, to return a collection of pages where any of the terms in the "genres" taxonomy are "suspense" or "romance": @@ -176,11 +175,10 @@ To return a collection of pages where the "author" page parameter begins with ei {{ $pages := where .Site.RegularPages "Params.author" "like" `(?i)^victor` }} ``` -{{% include "functions/_common/regular-expressions.md" %}} +{{% include "/_common/functions/regular-expressions.md" %}} -{{% note %}} -Use the `like` operator to compare string values. Comparing other data types will result in an empty collection. -{{% /note %}} +> [!note] +> Use the `like` operator to compare string values. Comparing other data types will result in an empty collection. ## Date comparison @@ -188,12 +186,6 @@ Use the `like` operator to compare string values. Comparing other data types wil There are four predefined front matter dates: [`date`], [`publishDate`], [`lastmod`], and [`expiryDate`]. Regardless of the front matter data format (TOML, YAML, or JSON) these are [`time.Time`] values, allowing precise comparisons. -[`date`]: /methods/page/date/ -[`publishdate`]: /methods/page/publishdate/ -[`lastmod`]: /methods/page/lastmod/ -[`expirydate`]: /methods/page/expirydate/ -[`time.Time`]: https://pkg.go.dev/time#Time - For example, to return a collection of pages that were created before the current year: ```go-html-template @@ -205,20 +197,19 @@ For example, to return a collection of pages that were created before the curren With custom front matter dates, the comparison depends on the front matter data format (TOML, YAML, or JSON). -{{% note %}} -Using TOML for pages with custom front matter dates enables precise date comparisons. -{{% /note %}} +> [!note] +> Using TOML for pages with custom front matter dates enables precise date comparisons. With TOML, date values are first-class citizens. TOML has a date data type while JSON and YAML do not. If you quote a TOML date, it is a string. If you do not quote a TOML date value, it is [`time.Time`] value, enabling precise comparisons. In the TOML example below, note that the event date is not quoted. -{{< code file="content/events/2024-user-conference.md" >}} +```text {file="content/events/2024-user-conference.md"} +++ title = '2024 User Conference" eventDate = 2024-04-01 +++ -{{< /code >}} +``` To return a collection of future events: @@ -272,8 +263,6 @@ These are equivalent: Useful for theme authors, avoid hardcoding section names by using the `where` function with the [`MainSections`] method on a `Site` object. -[`MainSections`]: /methods/site/mainsections/ - ```go-html-template {{ $pages := where .Site.RegularPages "Section" "in" .Site.MainSections }} ``` @@ -281,11 +270,10 @@ Useful for theme authors, avoid hardcoding section names by using the `where` fu With this construct, a theme author can instruct users to specify their main sections in the site configuration: {{< code-toggle file=hugo >}} -[params] mainSections = ['blog','galleries'] {{< /code-toggle >}} -If `params.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 the site configuration, the `MainSections` method returns a slice with one element---the top-level section with the most pages. ## Boolean/undefined comparison @@ -387,13 +375,11 @@ To exclude a page with an undefined field from a boolean _inequality_ test: 1. Create a collection using a nil comparison 1. Subtract the second collection from the first collection using the [`collections.Complement`] function. -[`collections.Complement`]: /functions/collections/complement/ - This template: ```go-html-template {{ $p1 := where .Site.RegularPages "Params.exclude" "ne" true }} -{{ $p2 := where .Site.RegularPages "Params.exclude" "eq" nil }} +{{ $p2 := where .Site.RegularPages "Params.exclude" "eq" nil }}
    {{ range $p1 | complement $p2 }}
  • {{ .LinkTitle }}
    • @@ -413,7 +399,7 @@ This template: ```go-html-template {{ $p1 := where .Site.RegularPages "Params.exclude" "ne" false }} -{{ $p2 := where .Site.RegularPages "Params.exclude" "eq" nil }} +{{ $p2 := where .Site.RegularPages "Params.exclude" "eq" nil }} ``` + +[`collections.Complement`]: /functions/collections/complement/ +[`date`]: /methods/page/date/ +[`lastmod`]: /methods/page/lastmod/ +[`MainSections`]: /methods/site/mainsections/ +[`time.Time`]: https://pkg.go.dev/time#Time diff --git a/content/en/functions/collections/_index.md b/content/en/functions/collections/_index.md index 51981f79b..c7b856f4f 100644 --- a/content/en/functions/collections/_index.md +++ b/content/en/functions/collections/_index.md @@ -1,12 +1,7 @@ --- title: Collections functions linkTitle: collections -description: Template functions to work with arrays, slices, maps, and page collections. +description: Use these functions to work with arrays, slices, maps, and page collections. categories: [] keywords: [] -menu: - docs: - parent: functions --- - -Use these functions to work with arrays, slices, maps, and page collections. diff --git a/content/en/functions/compare/Conditional.md b/content/en/functions/compare/Conditional.md index 997b71e94..c004bf4e6 100644 --- a/content/en/functions/compare/Conditional.md +++ b/content/en/functions/compare/Conditional.md @@ -3,12 +3,11 @@ title: compare.Conditional description: Returns one of two arguments depending on the value of the control argument. categories: [] keywords: [] -action: - aliases: [cond] - related: - - functions/compare/Default - returnType: any - signatures: [compare.Conditional CONTROL ARG1 ARG2] +params: + functions_and_methods: + aliases: [cond] + returnType: any + signatures: [compare.Conditional CONTROL ARG1 ARG2] aliases: [/functions/cond] --- diff --git a/content/en/functions/compare/Default.md b/content/en/functions/compare/Default.md index bf859d51c..f8bd06f06 100644 --- a/content/en/functions/compare/Default.md +++ b/content/en/functions/compare/Default.md @@ -2,27 +2,24 @@ title: compare.Default description: Returns the second argument if set, else the first argument. keywords: [] -action: - aliases: [default] - related: - - functions/compare/Conditional - - functions/go-template/Or - returnType: any - signatures: [compare.Default DEFAULT INPUT] +params: + functions_and_methods: + aliases: [default] + returnType: any + signatures: [compare.Default DEFAULT INPUT] aliases: [/functions/default] --- The `default` function returns the second argument if set, else the first argument. -{{% note %}} -When the second argument is the boolean `false` value, the `default` function returns `false`. All _other_ falsy values are considered unset. - -{{% include "functions/go-template/_common/truthy-falsy.md" %}} - -To set a default value based on truthiness, use the [`or`] operator instead. - -[`or`]: /functions/go-template/or/ -{{% /note %}} +> [!note] +> When the second argument is the boolean `false` value, the `default` function returns `false`. All _other_ falsy values are considered unset. +> +> The falsy values are `false`, `0`, any `nil` pointer or interface value, any array, slice, map, or string of length zero, and zero `time.Time` values. +> +> Everything else is truthy. +> +> To set a default value based on truthiness, use the [`or`] operator instead. The `default` function returns the second argument if set: @@ -46,3 +43,5 @@ The `default` function returns the first argument if the second argument is not {{ default 42 slice }} → 42 {{ default 42 }} → 42 ``` + +[`or`]: /functions/go-template/or/ diff --git a/content/en/functions/compare/Eq.md b/content/en/functions/compare/Eq.md index a877aeddf..583e2e495 100644 --- a/content/en/functions/compare/Eq.md +++ b/content/en/functions/compare/Eq.md @@ -3,16 +3,11 @@ title: compare.Eq description: Returns the boolean truth of arg1 == arg2 || arg1 == arg3. categories: [] keywords: [] -action: - aliases: [eq] - related: - - functions/compare/Ge - - functions/compare/Gt - - functions/compare/Le - - functions/compare/Lt - - functions/compare/Ne - returnType: bool - signatures: ['compare.Eq ARG1 ARG2 [ARG...]'] +params: + functions_and_methods: + aliases: [eq] + returnType: bool + signatures: ['compare.Eq ARG1 ARG2 [ARG...]'] aliases: [/functions/eq] --- diff --git a/content/en/functions/compare/Ge.md b/content/en/functions/compare/Ge.md index ce1fd2302..fd793f0c9 100644 --- a/content/en/functions/compare/Ge.md +++ b/content/en/functions/compare/Ge.md @@ -3,16 +3,11 @@ title: compare.Ge description: Returns the boolean truth of arg1 >= arg2 && arg1 >= arg3. categories: [] keywords: [] -action: - aliases: [ge] - related: - - functions/compare/Eq - - functions/compare/Gt - - functions/compare/Le - - functions/compare/Lt - - functions/compare/Ne - returnType: bool - signatures: ['compare.Ge ARG1 ARG2 [ARG...]'] +params: + functions_and_methods: + aliases: [ge] + returnType: bool + signatures: ['compare.Ge ARG1 ARG2 [ARG...]'] aliases: [/functions/ge] --- diff --git a/content/en/functions/compare/Gt.md b/content/en/functions/compare/Gt.md index 9ff3b0c89..f48312cf7 100644 --- a/content/en/functions/compare/Gt.md +++ b/content/en/functions/compare/Gt.md @@ -3,16 +3,11 @@ title: compare.Gt description: Returns the boolean truth of arg1 > arg2 && arg1 > arg3. categories: [] keywords: [] -action: - aliases: [gt] - related: - - functions/compare/Eq - - functions/compare/Ge - - functions/compare/Le - - functions/compare/Lt - - functions/compare/Ne - returnType: bool - signatures: ['compare.Gt ARG1 ARG2 [ARG...]'] +params: + functions_and_methods: + aliases: [gt] + returnType: bool + signatures: ['compare.Gt ARG1 ARG2 [ARG...]'] aliases: [/functions/gt] --- diff --git a/content/en/functions/compare/Le.md b/content/en/functions/compare/Le.md index a0fbed29d..b490d6807 100644 --- a/content/en/functions/compare/Le.md +++ b/content/en/functions/compare/Le.md @@ -3,16 +3,11 @@ title: compare.Le description: Returns the boolean truth of arg1 <= arg2 && arg1 <= arg3. categories: [] keywords: [] -action: - aliases: [le] - related: - - functions/compare/Eq - - functions/compare/Ge - - functions/compare/Gt - - functions/compare/Lt - - functions/compare/Ne - returnType: bool - signatures: ['compare.Le ARG1 ARG2 [ARG...]'] +params: + functions_and_methods: + aliases: [le] + returnType: bool + signatures: ['compare.Le ARG1 ARG2 [ARG...]'] aliases: [/functions/le] --- diff --git a/content/en/functions/compare/Lt.md b/content/en/functions/compare/Lt.md index b306a97b5..a5578cc84 100644 --- a/content/en/functions/compare/Lt.md +++ b/content/en/functions/compare/Lt.md @@ -3,16 +3,11 @@ title: compare.Lt description: Returns the boolean truth of arg1 < arg2 && arg1 < arg3. categories: [] keywords: [] -action: - aliases: [lt] - related: - - functions/compare/Eq - - functions/compare/Ge - - functions/compare/Gt - - functions/compare/Le - - functions/compare/Ne - returnType: bool - signatures: ['compare.Lt ARG1 ARG2 [ARG...]'] +params: + functions_and_methods: + aliases: [lt] + returnType: bool + signatures: ['compare.Lt ARG1 ARG2 [ARG...]'] aliases: [/functions/lt] --- diff --git a/content/en/functions/compare/Ne.md b/content/en/functions/compare/Ne.md index dbe0a3898..8839983f8 100644 --- a/content/en/functions/compare/Ne.md +++ b/content/en/functions/compare/Ne.md @@ -3,16 +3,11 @@ title: compare.Ne description: Returns the boolean truth of arg1 != arg2 && arg1 != arg3. categories: [] keywords: [] -action: - aliases: [ne] - related: - - functions/compare/Eq - - functions/compare/Ge - - functions/compare/Gt - - functions/compare/Le - - functions/compare/Lt - returnType: bool - signatures: ['compare.Ne ARG1 ARG2 [ARG...]'] +params: + functions_and_methods: + aliases: [ne] + returnType: bool + signatures: ['compare.Ne ARG1 ARG2 [ARG...]'] aliases: [/functions/ne] --- diff --git a/content/en/functions/compare/_index.md b/content/en/functions/compare/_index.md index a9b3a7b27..59673a2c8 100644 --- a/content/en/functions/compare/_index.md +++ b/content/en/functions/compare/_index.md @@ -1,12 +1,7 @@ --- title: Compare functions linkTitle: compare -description: Template functions to compare two or more values. +description: Use these functions to compare two or more values. categories: [] keywords: [] -menu: - docs: - parent: functions --- - -Use these functions to compare two or more values. diff --git a/content/en/functions/crypto/FNV32a.md b/content/en/functions/crypto/FNV32a.md index 0255349a3..03bcc57e7 100644 --- a/content/en/functions/crypto/FNV32a.md +++ b/content/en/functions/crypto/FNV32a.md @@ -1,18 +1,18 @@ --- title: crypto.FNV32a -description: Returns the 32-bit FNV (Fowler–Noll–Vo) non-cryptographic hash of the given string. +description: Returns the 32-bit FNV (Fowler-Noll-Vo) non-cryptographic hash of the given string. categories: [] keywords: [] -action: - aliases: [] - related: [] - returnType: int - signatures: [crypto.FNV32a STRING] +params: + functions_and_methods: + aliases: [] + returnType: int + signatures: [crypto.FNV32a STRING] expiryDate: 2026-07-31 # deprecated 2024-07-31 in v0.129.0 --- -{{% deprecated-in 0.129.0 %}} +{{< deprecated-in 0.129.0 >}} Use [`hash.FNV32a`] instead. [`hash.FNV32a`]: /functions/hash/FNV32a/ -{{% /deprecated-in %}} +{{< /deprecated-in >}} diff --git a/content/en/functions/crypto/HMAC.md b/content/en/functions/crypto/HMAC.md index 1906689a2..5929826dd 100644 --- a/content/en/functions/crypto/HMAC.md +++ b/content/en/functions/crypto/HMAC.md @@ -3,15 +3,11 @@ title: crypto.HMAC description: Returns a cryptographic hash that uses a key to sign a message. categories: [] keywords: [] -action: - aliases: [hmac] - related: - - functions/crypto/FNV32a - - functions/crypto/MD5 - - functions/crypto/SHA1 - - functions/crypto/SHA256 - returnType: string - signatures: ['crypto.HMAC HASH_TYPE KEY MESSAGE [ENCODING]'] +params: + functions_and_methods: + aliases: [hmac] + returnType: string + signatures: ['crypto.HMAC HASH_TYPE KEY MESSAGE [ENCODING]'] aliases: [/functions/hmac] --- diff --git a/content/en/functions/crypto/MD5.md b/content/en/functions/crypto/MD5.md index ba44660df..89bb8cc1b 100644 --- a/content/en/functions/crypto/MD5.md +++ b/content/en/functions/crypto/MD5.md @@ -3,15 +3,11 @@ title: crypto.MD5 description: Hashes the given input and returns its MD5 checksum encoded to a hexadecimal string. categories: [] keywords: [] -action: - aliases: [md5] - related: - - functions/crypto/FNV32a - - functions/crypto/HMAC - - functions/crypto/SHA1 - - functions/crypto/SHA256 - returnType: string - signatures: [crypto.MD5 INPUT] +params: + functions_and_methods: + aliases: [md5] + returnType: string + signatures: [crypto.MD5 INPUT] aliases: [/functions/md5] --- diff --git a/content/en/functions/crypto/SHA1.md b/content/en/functions/crypto/SHA1.md index 204ff0384..c80dac0a4 100644 --- a/content/en/functions/crypto/SHA1.md +++ b/content/en/functions/crypto/SHA1.md @@ -3,15 +3,11 @@ title: crypto.SHA1 description: Hashes the given input and returns its SHA1 checksum encoded to a hexadecimal string. categories: [] keywords: [] -action: - aliases: [sha1] - related: - - functions/crypto/FNV32a - - functions/crypto/HMAC - - functions/crypto/MD5 - - functions/crypto/SHA256 - returnType: string - signatures: [crypto.SHA1 INPUT] +params: + functions_and_methods: + aliases: [sha1] + returnType: string + signatures: [crypto.SHA1 INPUT] aliases: [/functions/sha,/functions/sha1] --- diff --git a/content/en/functions/crypto/SHA256.md b/content/en/functions/crypto/SHA256.md index 6fb657767..d0a66c069 100644 --- a/content/en/functions/crypto/SHA256.md +++ b/content/en/functions/crypto/SHA256.md @@ -3,15 +3,11 @@ title: crypto.SHA256 description: Hashes the given input and returns its SHA256 checksum encoded to a hexadecimal string. categories: [] keywords: [] -action: - aliases: [sha256] - related: - - functions/crypto/FNV32a - - functions/crypto/HMAC - - functions/crypto/MD5 - - functions/crypto/SHA1 - returnType: string - signatures: [crypto.SHA256 INPUT] +params: + functions_and_methods: + aliases: [sha256] + returnType: string + signatures: [crypto.SHA256 INPUT] aliases: [/functions/sha256] --- diff --git a/content/en/functions/crypto/_index.md b/content/en/functions/crypto/_index.md index 5c95aab6e..5771630d4 100644 --- a/content/en/functions/crypto/_index.md +++ b/content/en/functions/crypto/_index.md @@ -1,12 +1,7 @@ --- title: Crypto functions linkTitle: crypto -description: Template functions to create cryptographic hashes. +description: Use these functions to create cryptographic hashes. categories: [] keywords: [] -menu: - docs: - parent: functions --- - -Use these functions to create cryptographic hashes. diff --git a/content/en/functions/css/PostCSS.md b/content/en/functions/css/PostCSS.md index 1a1a792ec..9cc698248 100644 --- a/content/en/functions/css/PostCSS.md +++ b/content/en/functions/css/PostCSS.md @@ -3,14 +3,11 @@ title: css.PostCSS description: Processes the given resource with PostCSS using any PostCSS plugin. categories: [] keywords: [] -action: - aliases: [postCSS] - related: - - functions/css/Sass - - functions/css/TailwindCSS - returnType: resource.Resource - signatures: ['css.PostCSS [OPTIONS] RESOURCE'] -toc: true +params: + functions_and_methods: + aliases: [postCSS] + returnType: resource.Resource + signatures: ['css.PostCSS [OPTIONS] RESOURCE'] --- {{< new-in 0.128.0 />}} @@ -25,40 +22,40 @@ toc: true Follow the steps below to transform CSS using any of the available [PostCSS plugins]. -[postcss plugins]: https://postcss.org/docs/postcss-plugins +### Step 1 -Step 1 -: Install [Node.js]. +Install [Node.js]. -[node.js]: https://nodejs.org/en/download +### Step 2 -Step 2 -: Install the required Node.js packages in the root of your project. For example, to add vendor prefixes to your CSS rules: +Install the required Node.js packages in the root of your project. For example, to add vendor prefixes to your CSS rules: ```sh npm i -D postcss postcss-cli autoprefixer ``` -Step 3 -: Create a PostCSS configuration file in the root of your project. +### Step 3 -{{< code file=postcss.config.js >}} +Create a PostCSS configuration file in the root of your project. + +```js {file="postcss.config.js"} module.exports = { plugins: [ require('autoprefixer') ] }; -{{< /code >}} +``` -{{% note %}} -{{% include "functions/resources/_common/postcss-windows-warning.md" %}} -{{% /note %}} +> [!note] +> If you are a Windows user, and the path to your project contains a space, you must place the PostCSS configuration within the package.json file. See [this example] and issue [#7333]. -Step 4 -: Place your CSS file within the `assets/css` directory. +### Step 4 -Step 5 -: Process the resource with PostCSS: +Place your CSS file within the `assets/css` directory. + +### Step 5 + +Process the resource with PostCSS: ```go-html-template {{ with resources.Get "css/main.css" | postCSS }} @@ -74,13 +71,13 @@ config : (`string`) The directory that contains the PostCSS configuration file. Default is the root of the project directory. noMap -: (`bool`) Default is `false`. If `true`, disables inline sourcemaps. +: (`bool`) Whether to disable inline source maps. Default is `false`. inlineImports -: (`bool`) Default is `false`. Enable inlining of @import statements. It does so recursively, but will only import a file once. URL imports (e.g. `@import url('https://fonts.googleapis.com/css?family=Open+Sans&display=swap');`) and imports with media queries will be ignored. Note that this import routine does not care about the CSS spec, so you can have @import anywhere in the file. Hugo will look for imports relative to the module mount and will respect theme overrides. +: (`bool`) Whether to enable inlining of import statements. It does so recursively, but will only import a file once. URL imports (e.g. `@import url('https://fonts.googleapis.com/css?family=Open+Sans&display=swap');`) and imports with media queries will be ignored. Note that this import routine does not care about the CSS spec, so you can have @import anywhere in the file. Hugo will look for imports relative to the module mount and will respect theme overrides. Default is `false`. skipInlineImportsNotFound -: (`bool`) Default is `false`. Before Hugo 0.99.0 when `inlineImports` was enabled and we failed to resolve an import, we logged it as a warning. We now fail the build. If you have regular CSS imports in your CSS that you want to preserve, you can either use imports with URL or media queries (Hugo does not try to resolve those) or set `skipInlineImportsNotFound` to true. +: (`bool`) Whether to allow the build process to continue despite unresolved import statements, preserving the original import declarations. If you have regular CSS imports in your CSS that you want to preserve, you can either use imports with URL or media queries (Hugo does not try to resolve those) or set this option to `true`. Default is `false`." ```go-html-template {{ $opts := dict "config" "config-directory" "noMap" true }} @@ -124,3 +121,8 @@ module.exports = { ] } ``` + +[#7333]: https://github.com/gohugoio/hugo/issues/7333 +[Node.js]: https://nodejs.org/en +[PostCSS plugins]: https://postcss.org/docs/postcss-plugins +[this example]: https://github.com/postcss/postcss-load-config#packagejson diff --git a/content/en/functions/css/Sass.md b/content/en/functions/css/Sass.md index 73f7af1ea..1d5487130 100644 --- a/content/en/functions/css/Sass.md +++ b/content/en/functions/css/Sass.md @@ -3,16 +3,11 @@ title: css.Sass description: Transpiles Sass to CSS. categories: [] keywords: [] -action: - aliases: [toCSS] - related: - - functions/resources/Fingerprint - - functions/resources/Minify - - functions/css/PostCSS - - functions/resources/PostProcess - returnType: resource.Resource - signatures: ['css.Sass [OPTIONS] RESOURCE'] -toc: true +params: + functions_and_methods: + aliases: [toCSS] + returnType: resource.Resource + signatures: ['css.Sass [OPTIONS] RESOURCE'] --- {{< new-in 0.128.0 />}} @@ -70,10 +65,10 @@ precision : (`int`) Precision of floating point math. Not applicable to Dart Sass. enableSourceMap -: (`bool`) If `true`, generates a source map. +: (`bool`) Whether to generate a source map. Default is `false`. sourceMapIncludeSources -: (`bool`) If `true`, embeds sources in the generated source map. Not applicable to LibSass. +: (`bool`) Whether to embed sources in the generated source map. Not applicable to LibSass. Default is `false`. includePaths : (`slice`) A slice of paths, relative to the project root, that the transpiler will use when resolving `@use` and `@import` statements. @@ -128,7 +123,7 @@ Run `hugo env` to list the active transpilers. ### Installing in a production environment -For [CI/CD] deployments (e.g., GitHub Pages, GitLab Pages, Netlify, etc.) you must edit the workflow to install Dart Sass before Hugo builds the site[^2]. Some providers allow you to use one of the package managers above, or you can download and extract one of the prebuilt binaries. +For [CI/CD](g) deployments (e.g., GitHub Pages, GitLab Pages, Netlify, etc.) you must edit the workflow to install Dart Sass before Hugo builds the site[^2]. Some providers allow you to use one of the package managers above, or you can download and extract one of the prebuilt binaries. [^2]: You do not have to do this if (a) you have not modified the assets cache location, and (b) you have not set `useResourceCacheWhen` to `never` in your [site configuration], and (c) you add and commit your `resources` directory to your repository. @@ -149,8 +144,8 @@ To install Dart Sass for your builds on GitLab Pages, the `.gitlab-ci.yml` file ```yaml variables: - HUGO_VERSION: 0.141.0 - DART_SASS_VERSION: 1.83.4 + HUGO_VERSION: 0.144.2 + DART_SASS_VERSION: 1.85.0 GIT_DEPTH: 0 GIT_STRATEGY: clone GIT_SUBMODULE_STRATEGY: recursive @@ -183,8 +178,8 @@ To install Dart Sass for your builds on Netlify, the `netlify.toml` file should ```toml [build.environment] -HUGO_VERSION = "0.141.0" -DART_SASS_VERSION = "1.83.4" +HUGO_VERSION = "0.144.2" +DART_SASS_VERSION = "1.85.0" NODE_VERSION = "22" TZ = "America/Los_Angeles" @@ -229,12 +224,11 @@ If you build Hugo from source and run `mage test -v`, the test will fail if you [brew.sh]: https://brew.sh/ [chocolatey.org]: https://community.chocolatey.org/packages/sass -[ci/cd]: https://en.wikipedia.org/wiki/CI/CD [dart sass]: https://sass-lang.com/dart-sass [libsass]: https://sass-lang.com/libsass [prebuilt binaries]: https://github.com/sass/dart-sass/releases/latest [scoop.sh]: https://scoop.sh/#/apps?q=sass -[site configuration]: /getting-started/configuration/#configure-build +[site configuration]: /configuration/build/ [snap package]: /installation/linux/#snap [snapcraft.io]: https://snapcraft.io/dart-sass [starter workflow]: https://github.com/actions/starter-workflows/blob/main/pages/hugo.yml diff --git a/content/en/functions/css/TailwindCSS.md b/content/en/functions/css/TailwindCSS.md index 44c549196..6add7373a 100644 --- a/content/en/functions/css/TailwindCSS.md +++ b/content/en/functions/css/TailwindCSS.md @@ -3,28 +3,27 @@ title: css.TailwindCSS description: Processes the given resource with the Tailwind CSS CLI. categories: [] keywords: [] -action: - aliases: [] - related: - - functions/resources/Fingerprint - - functions/resources/Minify - - functions/css/PostCSS - returnType: resource.Resource - signatures: ['css.TailwindCSS [OPTIONS] RESOURCE'] -toc: true +params: + functions_and_methods: + aliases: [] + returnType: resource.Resource + signatures: ['css.TailwindCSS [OPTIONS] RESOURCE'] --- {{< new-in 0.128.0 />}} -Use the `css.TailwindCSS` function to process your Tailwind CSS files. This function uses the Tailwind CSS CLI to: +Use the `css.TailwindCSS` function to process your Tailwind CSS files. This function uses the Tailwind CSS CLI to: 1. Scan your templates for Tailwind CSS utility class usage. 1. Compile those utility classes into standard CSS. 1. Generate an optimized CSS output file. +> [!caution] +> Tailwind CSS v4.0 and later requires a relatively [modern browser](https://tailwindcss.com/docs/compatibility#browser-support) to render correctly. + ## Setup -###### Step 1 +### Step 1 Install the Tailwind CSS CLI v4.0 or later: @@ -36,7 +35,7 @@ The TailwindCSS CLI is also available as a [standalone executable] if you want t [standalone executable]: https://github.com/tailwindlabs/tailwindcss/releases/latest -###### Step 2 +### Step 2 Add this to your site configuration: @@ -58,23 +57,22 @@ source = "(postcss|tailwind)\\.config\\.js" target = "css" {{< /code-toggle >}} - -###### Step 3 +### Step 3 Create a CSS entry file: -{{< code file=assets/css/main.css copy=true >}} +```css {file="assets/css/main.css" copy=true} @import "tailwindcss"; @source "hugo_stats.json"; -{{< /code >}} +``` Tailwind CSS respects `.gitignore` files. This means that if `hugo_stats.json` is listed in your `.gitignore` file, Tailwind CSS will ignore it. To make `hugo_stats.json` available to Tailwind CSS you must explicitly source it as shown in the example above. -###### Step 4 +### Step 4 Create a partial template to process the CSS with the Tailwind CSS CLI: -{{< code file=layouts/partials/css.html copy=true >}} +```go-html-template {file="layouts/partials/css.html" copy=true} {{ with (templates.Defer (dict "key" "global")) }} {{ with resources.Get "css/main.css" }} {{ $opts := dict @@ -92,21 +90,21 @@ Create a partial template to process the CSS with the Tailwind CSS CLI: {{ end }} {{ end }} {{ end }} -{{< /code >}} +``` -###### Step 5 +### Step 5 Call the partial template from your base template: -{{< code file=layouts/default/baseof.html >}} +```go-html-template {file="layouts/_default/baseof.html"} ... {{ partialCached "css.html" . }} ... -{{< /code >}} +``` -###### Step 6 +### Step 6 Optionally create a `tailwind.config.js` file in the root of your project as shown below. This is necessary if you use the [Tailwind CSS IntelliSense extension] for Visual Studio Code. @@ -114,7 +112,7 @@ extension] for Visual Studio Code. [Tailwind CSS IntelliSense extension]: https://marketplace.visualstudio.com/items?itemName=bradlc.vscode-tailwindcss -{{< code file=tailwind.config.js copy=true >}} +```js {file="tailwind.config.js" copy=true} /* This file is present to satisfy a requirement of the Tailwind CSS IntelliSense extension for Visual Studio Code. @@ -123,7 +121,7 @@ https://marketplace.visualstudio.com/items?itemName=bradlc.vscode-tailwindcss The rest of this file is intentionally empty. */ -{{< /code >}} +``` ## Options @@ -137,4 +135,4 @@ inlineImports : (`bool`) Whether to enable inlining of `@import` statements. Inlining is performed recursively, but currently once only per file. It is not possible to import the same file in different scopes (root, media query, etc.). Note that this import routine does not care about the CSS specification, so you can have `@import` statements anywhere in the file. Default is `false`. skipInlineImportsNotFound -: (`bool`) When `inlineImports` is enabled, we fail the build if an import cannot be resolved. Enable this option to allow the build to continue and leave the import statement in place. Note that the inline importer does not process URL location or imports with media queries, so those will be left as-is even without enabling this option. Default is `false`. +: (`bool`) Whether to allow the build process to continue despite unresolved import statements, preserving the original import declarations. It is important to note that the inline importer does not process URL-based imports or those with media queries, and these will remain unaltered even when this option is disabled. Default is `false`. diff --git a/content/en/functions/css/_index.md b/content/en/functions/css/_index.md index a83a23819..9faabbbe9 100644 --- a/content/en/functions/css/_index.md +++ b/content/en/functions/css/_index.md @@ -1,12 +1,7 @@ --- title: CSS functions linkTitle: css -description: Template functions to work with CSS and Sass files. +description: Use these functions to work with CSS and Sass files. categories: [] keywords: [] -menu: - docs: - parent: functions --- - -Use these functions to work with CSS and Sass files. diff --git a/content/en/functions/data/GetCSV.md b/content/en/functions/data/GetCSV.md index be848bce5..39c71b06c 100644 --- a/content/en/functions/data/GetCSV.md +++ b/content/en/functions/data/GetCSV.md @@ -3,23 +3,22 @@ title: data.GetCSV description: Returns an array of arrays from a local or remote CSV file, or an error if the file does not exist. categories: [] keywords: [] -action: - aliases: [getCSV] - related: [] - returnType: '[][]string' - signatures: ['data.GetCSV SEPARATOR INPUT... [OPTIONS]'] -toc: true +params: + functions_and_methods: + aliases: [getCSV] + returnType: '[][]string' + signatures: ['data.GetCSV SEPARATOR INPUT... [OPTIONS]'] expiryDate: 2026-02-19 # deprecated 2024-02-19 in v0.123.0 --- -{{% deprecated-in 0.123.0 %}} +{{< deprecated-in 0.123.0 >}} Instead, use [`transform.Unmarshal`] with a [global resource](g), [page resource](g), or [remote resource](g). See the [remote data example]. [`transform.Unmarshal`]: /functions/transform/unmarshal/ [remote data example]: /functions/resources/getremote/#remote-data -{{% /deprecated-in %}} +{{< /deprecated-in >}} Given the following directory structure: @@ -36,11 +35,10 @@ Access the data with either of the following: {{ $data := getCSV "," "other-files/" "pets.csv" }} ``` -{{% note %}} -When working with local data, the file path is relative to the working directory. - -You must not place CSV files in the project's `data` directory. -{{% /note %}} +> [!note] +> When working with local data, the file path is relative to the working directory. +> +> You must not place CSV files in the project's `data` directory. Access remote data with either of the following: diff --git a/content/en/functions/data/GetJSON.md b/content/en/functions/data/GetJSON.md index 1b42cbf16..9cdea9287 100644 --- a/content/en/functions/data/GetJSON.md +++ b/content/en/functions/data/GetJSON.md @@ -3,23 +3,22 @@ title: data.GetJSON description: Returns a JSON object from a local or remote JSON file, or an error if the file does not exist. categories: [] keywords: [] -action: - aliases: [getJSON] - related: [] - returnType: any - signatures: ['data.GetJSON INPUT... [OPTIONS]'] -toc: true +params: + functions_and_methods: + aliases: [getJSON] + returnType: any + signatures: ['data.GetJSON INPUT... [OPTIONS]'] expiryDate: 2026-02-19 # deprecated 2024-02-19 in v0.123.0 --- -{{% deprecated-in 0.123.0 %}} +{{< deprecated-in 0.123.0 >}} Instead, use [`transform.Unmarshal`] with a [global resource](g), [page resource](g), or [remote resource](g). See the [remote data example]. [`transform.Unmarshal`]: /functions/transform/unmarshal/ [remote data example]: /functions/resources/getremote/#remote-data -{{% /deprecated-in %}} +{{< /deprecated-in >}} Given the following directory structure: @@ -36,9 +35,8 @@ Access the data with either of the following: {{ $data := getJSON "other-files/" "books.json" }} ``` -{{% note %}} -When working with local data, the file path is relative to the working directory. -{{% /note %}} +> [!note] +> When working with local data, the file path is relative to the working directory. Access remote data with either of the following: diff --git a/content/en/functions/data/_index.md b/content/en/functions/data/_index.md index 142d6b528..2177bc528 100644 --- a/content/en/functions/data/_index.md +++ b/content/en/functions/data/_index.md @@ -1,12 +1,7 @@ --- title: Data functions linkTitle: data -description: Template functions to read local or remote data files. +description: Use these functions to read local or remote data files. categories: [] keywords: [] -menu: - docs: - parent: functions --- - -Use these functions to read local or remote data files. diff --git a/content/en/functions/debug/Dump.md b/content/en/functions/debug/Dump.md index 67b264bed..df846ac3d 100644 --- a/content/en/functions/debug/Dump.md +++ b/content/en/functions/debug/Dump.md @@ -3,11 +3,11 @@ title: debug.Dump description: Returns an object dump as a string. categories: [] keywords: [] -action: - aliases: [] - related: [] - returnType: string - signatures: [debug.Dump VALUE] +params: + functions_and_methods: + aliases: [] + returnType: string + signatures: [debug.Dump VALUE] --- ```go-html-template @@ -29,6 +29,5 @@ action: ] ``` -{{% note %}} -Output from this function may change from one release to the next. Use for debugging only. -{{% /note %}} +> [!note] +> Output from this function may change from one release to the next. Use for debugging only. diff --git a/content/en/functions/debug/Timer.md b/content/en/functions/debug/Timer.md index 519c195c1..c2cd59211 100644 --- a/content/en/functions/debug/Timer.md +++ b/content/en/functions/debug/Timer.md @@ -3,11 +3,11 @@ title: debug.Timer description: Creates a named timer that reports elapsed time to the console. categories: [] keywords: [] -action: - aliases: [] - related: [] - returnType: debug.Timer - signatures: [debug.Timer NAME] +params: + functions_and_methods: + aliases: [] + returnType: debug.Timer + signatures: [debug.Timer NAME] --- {{< new-in 0.120.0 />}} diff --git a/content/en/functions/debug/_index.md b/content/en/functions/debug/_index.md index 418828515..49fe416ed 100644 --- a/content/en/functions/debug/_index.md +++ b/content/en/functions/debug/_index.md @@ -1,12 +1,7 @@ --- title: Debug functions linkTitle: debug -description: Template functions to debug your templates. +description: Use these functions to debug your templates. categories: [] keywords: [] -menu: - docs: - parent: functions --- - -Use these functions to debug your templates. diff --git a/content/en/functions/diagrams/Goat.md b/content/en/functions/diagrams/Goat.md index 69a099bb7..e2f55eee0 100644 --- a/content/en/functions/diagrams/Goat.md +++ b/content/en/functions/diagrams/Goat.md @@ -1,20 +1,20 @@ --- title: diagrams.Goat -description: Converts ASCII art to an SVG diagram, returning a GoAT diagram object. +description: Returns an SVGDiagram object created from the given GoAT markup and options. categories: [] keywords: [] -action: - aliases: [] - related: [] - returnType: diagrams.goatDiagram - signatures: ['diagrams.Goat INPUT'] -toc: true +params: + functions_and_methods: + aliases: [] + returnType: diagrams.SVGDiagram + signatures: [diagrams.Goat MARKUP] --- -Useful in a [code block render hook], the `diagram.Goat` function converts ASCII art to an SVG diagram, returning a [GoAT] diagram object with the following methods: +Useful in a [code block render hook], the `diagrams.Goat` function returns an SVGDiagram object created from the given [GoAT] markup. -[GoAT]: https://github.com/blampe/goat#readme -[code block render hook]: /render-hooks/code-blocks/ +## Methods + +The SVGDiagram object has the following methods: Inner : (`template.HTML`) Returns the SVG child elements without a wrapping `svg` element, allowing you to create your own wrapper. @@ -30,13 +30,11 @@ Height ## GoAT Diagrams -Hugo natively supports [GoAT](https://github.com/bep/goat) diagrams with an [embedded code block render hook]. - -[embedded code block render hook]: {{% eturl render-codeblock-goat %}} +Hugo natively supports GoAT diagrams with an [embedded code block render hook]. This Markdown: -```` +````text ```goat .---. .-. .-. .-. .---. | A +--->| 1 |<--->| 2 |<--->| 3 |<---+ B | @@ -68,7 +66,7 @@ To customize rendering, override Hugo's [embedded code block render hook] for Go By way of example, let's create a code block render hook to render GoAT diagrams as `figure` elements with an optional caption. -{{< code file=layouts/_default/_markup/render-codeblock-goat.html >}} +```go-html-template {file="layouts/_default/_markup/render-codeblock-goat.html"} {{ $caption := or .Attributes.caption "" }} {{ $class := or .Attributes.class "diagram" }} {{ $id := or .Attributes.id (printf "diagram-%d" (add 1 .Ordinal)) }} @@ -81,17 +79,17 @@ By way of example, let's create a code block render hook to render GoAT diagrams {{ end }}
    {{ $caption }}
    -{{< /code >}} +``` This Markdown: -{{< code file=content/example.md lang=text >}} +````text {file="content/example.md" } ```goat {class="foo" caption="Diagram 1: Example"} .---. .-. .-. .-. .---. | A +--->| 1 |<--->| 2 |<--->| 3 |<---+ B | '---' '-' '+' '+' '---' ``` -{{< /code >}} +```` Is rendered to: @@ -111,3 +109,7 @@ svg.foo { font-family: "Segoe UI","Noto Sans",Helvetica,Arial,sans-serif } ``` + +[code block render hook]: /render-hooks/code-blocks/ +[embedded code block render hook]: {{% eturl render-codeblock-goat %}} +[GoAT]: https://github.com/bep/goat diff --git a/content/en/functions/diagrams/_index.md b/content/en/functions/diagrams/_index.md index e136b4f33..6aa407071 100644 --- a/content/en/functions/diagrams/_index.md +++ b/content/en/functions/diagrams/_index.md @@ -1,12 +1,7 @@ --- title: Diagram functions linkTitle: diagrams -description: Template functions to render diagrams. +description: Use these functions to render diagrams. categories: [] keywords: [] -menu: - docs: - parent: functions --- - -Use these functions to render diagrams. diff --git a/content/en/functions/encoding/Base64Decode.md b/content/en/functions/encoding/Base64Decode.md index 0745718bb..5237e904f 100644 --- a/content/en/functions/encoding/Base64Decode.md +++ b/content/en/functions/encoding/Base64Decode.md @@ -3,12 +3,11 @@ title: encoding.Base64Decode description: Returns the base64 decoding of the given content. categories: [] keywords: [] -action: - aliases: [base64Decode] - related: - - functions/encoding/Base64Encode - returnType: string - signatures: [encoding.Base64Decode INPUT] +params: + functions_and_methods: + aliases: [base64Decode] + returnType: string + signatures: [encoding.Base64Decode INPUT] aliases: [/functions/base64Decode] --- @@ -29,7 +28,7 @@ To retrieve and render the content: {{ with try (resources.GetRemote $url) }} {{ with .Err }} {{ errorf "%s" . }} - {{ else with .Value}} + {{ else with .Value }} {{ with . | transform.Unmarshal }} {{ .content | base64Decode | markdownify }} {{ end }} diff --git a/content/en/functions/encoding/Base64Encode.md b/content/en/functions/encoding/Base64Encode.md index 14f67a132..e19d6773c 100644 --- a/content/en/functions/encoding/Base64Encode.md +++ b/content/en/functions/encoding/Base64Encode.md @@ -3,12 +3,11 @@ title: encoding.Base64Encode description: Returns the base64 decoding of the given content. categories: [] keywords: [] -action: - aliases: [base64Encode] - related: - - functions/encoding/Base64Decode - returnType: string - signatures: [encoding.Base64Encode INPUT] +params: + functions_and_methods: + aliases: [base64Encode] + returnType: string + signatures: [encoding.Base64Encode INPUT] aliases: [/functions/base64, /functions/base64Encode] --- diff --git a/content/en/functions/encoding/Jsonify.md b/content/en/functions/encoding/Jsonify.md index 475f8a76a..1d60dd68d 100644 --- a/content/en/functions/encoding/Jsonify.md +++ b/content/en/functions/encoding/Jsonify.md @@ -3,14 +3,11 @@ title: encoding.Jsonify description: Encodes the given object to JSON. categories: [] keywords: [] -action: - aliases: [jsonify] - returnType: template.HTML - related: - - functions/transform/Remarshal - - functions/transform/Unmarshal - signatures: - - encoding.Jsonify [OPTIONS] INPUT +params: + functions_and_methods: + aliases: [jsonify] + returnType: template.HTML + signatures: ['encoding.Jsonify [OPTIONS] INPUT'] aliases: [/functions/jsonify] --- @@ -34,4 +31,4 @@ prefix : (`string`) Indentation prefix. Default is "". noHTMLEscape -: (`bool`) Disable escaping of problematic HTML characters inside JSON quoted strings. The default behavior is to escape `&`, `<`, and `>` to `\u0026`, `\u003c`, and `\u003e` to avoid certain safety problems that can arise when embedding JSON in HTML. Default is `false`. +: (`bool`) Whether to disable escaping of problematic HTML characters inside JSON quoted strings. The default behavior is to escape `&`, `<`, and `>` to `\u0026`, `\u003c`, and `\u003e` to avoid certain safety problems that can arise when embedding JSON in HTML. Default is `false`. diff --git a/content/en/functions/encoding/_index.md b/content/en/functions/encoding/_index.md index 3c4c4519e..f2819f0a7 100644 --- a/content/en/functions/encoding/_index.md +++ b/content/en/functions/encoding/_index.md @@ -1,12 +1,7 @@ --- title: Encoding functions linkTitle: encoding -description: Template functions to encode and decode data. +description: Use these functions to encode and decode data. categories: [] keywords: [] -menu: - docs: - parent: functions --- - -Use these functions to encode and decode data. diff --git a/content/en/functions/fmt/Errorf.md b/content/en/functions/fmt/Errorf.md index 93f546351..799622f0e 100644 --- a/content/en/functions/fmt/Errorf.md +++ b/content/en/functions/fmt/Errorf.md @@ -3,18 +3,15 @@ title: fmt.Errorf description: Log an ERROR from a template. categories: [] keywords: [] -action: - aliases: [errorf] - related: - - functions/fmt/Erroridf - - functions/fmt/Warnf - - functions/fmt/Warnidf - returnType: string - signatures: ['fmt.Errorf FORMAT [INPUT]'] +params: + functions_and_methods: + aliases: [errorf] + returnType: string + signatures: ['fmt.Errorf FORMAT [INPUT]'] aliases: [/functions/errorf] --- -{{% include "functions/fmt/_common/fmt-layout.md" %}} +{{% include "/_common/functions/fmt/format-string.md" %}} The `errorf` function evaluates the format string, then prints the result to the ERROR log and fails the build. diff --git a/content/en/functions/fmt/Erroridf.md b/content/en/functions/fmt/Erroridf.md index f442f09bf..97d628bac 100644 --- a/content/en/functions/fmt/Erroridf.md +++ b/content/en/functions/fmt/Erroridf.md @@ -3,18 +3,15 @@ title: fmt.Erroridf description: Log a suppressible ERROR from a template. categories: [] keywords: [] -action: - aliases: [erroridf] - related: - - functions/fmt/Errorf - - functions/fmt/Warnf - - functions/fmt/Warnidf - returnType: string - signatures: ['fmt.Erroridf ID FORMAT [INPUT]'] +params: + functions_and_methods: + aliases: [erroridf] + returnType: string + signatures: ['fmt.Erroridf ID FORMAT [INPUT]'] aliases: [/functions/erroridf] --- -{{% include "functions/fmt/_common/fmt-layout.md" %}} +{{% 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. diff --git a/content/en/functions/fmt/Print.md b/content/en/functions/fmt/Print.md index 6f3128e5f..f1d169cfa 100644 --- a/content/en/functions/fmt/Print.md +++ b/content/en/functions/fmt/Print.md @@ -3,13 +3,11 @@ title: fmt.Print description: Prints the default representation of the given arguments using the standard `fmt.Print` function. categories: [] keywords: [] -action: - aliases: [print] - related: - - functions/fmt/Printf - - functions/fmt/Println - returnType: string - signatures: [fmt.Print INPUT] +params: + functions_and_methods: + aliases: [print] + returnType: string + signatures: [fmt.Print INPUT] aliases: [/functions/print] --- diff --git a/content/en/functions/fmt/Printf.md b/content/en/functions/fmt/Printf.md index 5d0127460..68df98609 100644 --- a/content/en/functions/fmt/Printf.md +++ b/content/en/functions/fmt/Printf.md @@ -3,17 +3,15 @@ title: fmt.Printf description: Formats a string using the standard `fmt.Sprintf` function. categories: [] keywords: [] -action: - aliases: [printf] - related: - - functions/fmt/Print - - functions/fmt/Println - returnType: string - signatures: ['fmt.Printf FORMAT [INPUT]'] +params: + functions_and_methods: + aliases: [printf] + returnType: string + signatures: ['fmt.Printf FORMAT [INPUT]'] aliases: [/functions/printf] --- -{{% include "functions/fmt/_common/fmt-layout.md" %}} +{{% include "/_common/functions/fmt/format-string.md" %}} ```go-html-template {{ $var := "world" }} diff --git a/content/en/functions/fmt/Println.md b/content/en/functions/fmt/Println.md index a4db56ffb..b7fe608ff 100644 --- a/content/en/functions/fmt/Println.md +++ b/content/en/functions/fmt/Println.md @@ -3,13 +3,11 @@ title: fmt.Println description: Prints the default representation of the given argument using the standard `fmt.Print` function and enforces a line break. categories: [] keywords: [] -action: - aliases: [println] - related: - - functions/fmt/Print - - functions/fmt/Printf - returnType: string - signatures: [fmt.Println INPUT] +params: + functions_and_methods: + aliases: [println] + returnType: string + signatures: [fmt.Println INPUT] aliases: [/functions/println] --- diff --git a/content/en/functions/fmt/Warnf.md b/content/en/functions/fmt/Warnf.md index 643defd30..887a8d47f 100644 --- a/content/en/functions/fmt/Warnf.md +++ b/content/en/functions/fmt/Warnf.md @@ -3,18 +3,15 @@ title: fmt.Warnf description: Log a WARNING from a template. categories: [] keywords: [] -action: - aliases: [warnf] - related: - - functions/fmt/Errorf - - functions/fmt/Erroridf - - functions/fmt/Warnidf - returnType: string - signatures: ['fmt.Warnf FORMAT [INPUT]'] +params: + functions_and_methods: + aliases: [warnf] + returnType: string + signatures: ['fmt.Warnf FORMAT [INPUT]'] aliases: [/functions/warnf] --- -{{% include "functions/fmt/_common/fmt-layout.md" %}} +{{% include "/_common/functions/fmt/format-string.md" %}} The `warnf` function evaluates the format string, then prints the result to the WARNING log. Hugo prints each unique message once to avoid flooding the log with duplicate warnings. diff --git a/content/en/functions/fmt/Warnidf.md b/content/en/functions/fmt/Warnidf.md index 70c109b5b..79ebf81e6 100644 --- a/content/en/functions/fmt/Warnidf.md +++ b/content/en/functions/fmt/Warnidf.md @@ -3,20 +3,17 @@ title: fmt.Warnidf description: Log a suppressible WARNING from a template. categories: [] keywords: [] -action: - aliases: [warnidf] - related: - - functions/fmt/Errorf - - functions/fmt/Erroridf - - functions/fmt/Warnf - returnType: string - signatures: ['fmt.Warnidf ID FORMAT [INPUT]'] +params: + functions_and_methods: + aliases: [warnidf] + returnType: string + signatures: ['fmt.Warnidf ID FORMAT [INPUT]'] aliases: [/functions/warnidf] --- {{< new-in 0.123.0 />}} -{{% include "functions/fmt/_common/fmt-layout.md" %}} +{{% 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. diff --git a/content/en/functions/fmt/_common/_index.md b/content/en/functions/fmt/_common/_index.md deleted file mode 100644 index 4328d4d14..000000000 --- a/content/en/functions/fmt/_common/_index.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -cascade: - _build: - list: never - publishResources: false - render: never ---- - - diff --git a/content/en/functions/fmt/_index.md b/content/en/functions/fmt/_index.md index 51ef847ca..d388df112 100644 --- a/content/en/functions/fmt/_index.md +++ b/content/en/functions/fmt/_index.md @@ -1,12 +1,7 @@ --- title: Fmt functions linkTitle: fmt -description: Template functions to print strings within a template or to print messages to the terminal +description: Use these functions to print strings within a template or to print messages to the terminal. categories: [] keywords: [] -menu: - docs: - parent: functions --- - -Use these functions to print strings within a template or to print messages to the terminal. diff --git a/content/en/functions/global/_index.md b/content/en/functions/global/_index.md index 1e609b56e..3d935176c 100644 --- a/content/en/functions/global/_index.md +++ b/content/en/functions/global/_index.md @@ -1,11 +1,6 @@ --- title: Global functions linkTitle: global -description: Global template functions to access page and site data. +description: Use these global functions to access page and site data. categories: [] -menu: - docs: - parent: functions --- - -Use these global functions to access page and site data. diff --git a/content/en/functions/global/page.md b/content/en/functions/global/page.md index 1dc8be515..0d4b8070f 100644 --- a/content/en/functions/global/page.md +++ b/content/en/functions/global/page.md @@ -3,13 +3,11 @@ title: page description: Provides global access to a Page object. categories: [] keywords: [] -action: - aliases: [] - related: - - functions/global/site - returnType: - signatures: [page] -toc: true +params: + functions_and_methods: + aliases: [] + returnType: + signatures: [page] aliases: [/functions/page] --- @@ -27,13 +25,12 @@ When a `Page` object is not in context, you can use the global `page` function: {{ page.Params.foo }} ``` -{{% note %}} -Do not use the global `page` function in shortcodes, partials called by shortcodes, or cached partials. See [warnings](#warnings) below. -{{% /note %}} +> [!note] +> Do not use the global `page` function in shortcodes, partials called by shortcodes, or cached partials. See [warnings](#warnings) below. ## Explanation -Hugo almost always passes a `Page` as the data context into the top level template (e.g., `single.html`). The one exception is the multihost sitemap template. This means that you can access the current page with the `.` in the template. +Hugo almost always passes a `Page` as the data context into the top-level template (e.g., `single.html`). The one exception is the multihost sitemap template. This means that you can access the current page with the `.` in the template. But when you are deeply nested inside of a [content view](g), [partial](g), or [render hook](g), it is not always practical or possible to access the `Page` object. @@ -99,5 +96,5 @@ When you call the [`Summary`] method, Hugo renders the page content including sh If Hugo renders the section page before a content page, the cached rendered shortcode will be incorrect. You cannot control the rendering sequence due to concurrency. -[`Summary`]: /methods/page/summary/ [`partialCached`]: /functions/partials/includecached/ +[`Summary`]: /methods/page/summary/ diff --git a/content/en/functions/global/site.md b/content/en/functions/global/site.md index a4879fee0..be0c6730e 100644 --- a/content/en/functions/global/site.md +++ b/content/en/functions/global/site.md @@ -3,12 +3,11 @@ title: site description: Provides global access to the current Site object. categories: [] keywords: [] -action: - aliases: [] - related: - - functions/global/page - returnType: - signatures: [site] +params: + functions_and_methods: + aliases: [] + returnType: + signatures: [site] aliases: [/functions/site] --- @@ -27,6 +26,5 @@ When the `Site` object is in context you can use the `Site` property: {{ $.Site.Params.foo }} ``` -{{% note %}} -To simplify your templates, use the global `site` function regardless of whether the `Site` object is in context. -{{% /note %}} +> [!note] +> To simplify your templates, use the global `site` function regardless of whether the `Site` object is in context. diff --git a/content/en/functions/go-template/_common/_index.md b/content/en/functions/go-template/_common/_index.md deleted file mode 100644 index 4328d4d14..000000000 --- a/content/en/functions/go-template/_common/_index.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -cascade: - _build: - list: never - publishResources: false - render: never ---- - - diff --git a/content/en/functions/go-template/_index.md b/content/en/functions/go-template/_index.md index 9075756aa..627dc2849 100644 --- a/content/en/functions/go-template/_index.md +++ b/content/en/functions/go-template/_index.md @@ -1,14 +1,7 @@ --- title: Go template functions, operators, and statements linkTitle: go template -description: Template functions, operators, and statements provided by Go's text/template package. +description: These are the functions, operators, and statements provided by Go's text/template package. categories: [] keywords: [] -menu: - docs: - parent: functions --- - -These are the functions, operators, and statements provided by Go's [text/template] package. - -[text/template]: https://pkg.go.dev/text/template diff --git a/content/en/functions/go-template/and.md b/content/en/functions/go-template/and.md index 6bc8c60a5..77906df52 100644 --- a/content/en/functions/go-template/and.md +++ b/content/en/functions/go-template/and.md @@ -3,16 +3,14 @@ title: and description: Returns the first falsy argument. If all arguments are truthy, returns the last argument. categories: [] keywords: [] -action: - aliases: [] - related: - - functions/go-template/not - - functions/go-template/or - returnType: any - signatures: [and VALUE...] +params: + functions_and_methods: + aliases: [] + returnType: any + signatures: [and VALUE...] --- -{{% include "functions/go-template/_common/truthy-falsy.md" %}} +{{% include "/_common/functions/truthy-falsy.md" %}} ```go-html-template {{ and 1 0 "" }} → 0 (int) @@ -22,5 +20,3 @@ action: {{ and "a" "b" "c" }} → c (string) {{ and "a" 1 true }} → true (bool) ``` - -{{% include "functions/go-template/_common/text-template.md" %}} diff --git a/content/en/functions/go-template/block.md b/content/en/functions/go-template/block.md index f8a082037..bffab1f8c 100644 --- a/content/en/functions/go-template/block.md +++ b/content/en/functions/go-template/block.md @@ -3,13 +3,11 @@ title: block description: Defines a template and executes it in place. categories: [] keywords: [] -action: - aliases: [] - related: - - functions/go-template/define - - functions/go-template/end - returnType: - signatures: [block NAME CONTEXT] +params: + functions_and_methods: + aliases: [] + returnType: + signatures: [block NAME CONTEXT] --- A block is shorthand for defining a template: @@ -25,7 +23,7 @@ and then executing it in place: ``` The typical use is to define a set of root templates that are then customized by redefining the block templates within. -{{< code file=layouts/_default/baseof.html >}} +```go-html-template {file="layouts/_default/baseof.html"}
    {{ block "main" . }} @@ -33,16 +31,16 @@ The typical use is to define a set of root templates that are then customized by {{ end }}
    -{{< /code >}} +``` -{{< code file=layouts/_default/single.html >}} +```go-html-template {file="layouts/_default/single.html"} {{ define "main" }}

    {{ .Title }}

    {{ .Content }} {{ end }} -{{< /code >}} +``` -{{< code file=layouts/_default/list.html >}} +```go-html-template {file="layouts/_default/list.html"} {{ define "main" }}

    {{ .Title }}

    {{ .Content }} @@ -50,6 +48,6 @@ The typical use is to define a set of root templates that are then customized by

    {{ .LinkTitle }}

    {{ end }} {{ end }} -{{< /code >}} +``` -{{% include "functions/go-template/_common/text-template.md" %}} +{{% include "/_common/functions/go-template/text-template.md" %}} diff --git a/content/en/functions/go-template/break.md b/content/en/functions/go-template/break.md index 14074d7c0..9236ec91e 100644 --- a/content/en/functions/go-template/break.md +++ b/content/en/functions/go-template/break.md @@ -3,13 +3,11 @@ title: break description: Used with the range statement, stops the innermost iteration and bypasses all remaining iterations. categories: [] keywords: [] -action: - aliases: [] - related: - - functions/go-template/continue - - functions/go-template/range - returnType: - signatures: [break] +params: + functions_and_methods: + aliases: [] + returnType: + signatures: [break] --- This template code: @@ -30,4 +28,4 @@ Is rendered to:

    foo

    ``` -{{% include "functions/go-template/_common/text-template.md" %}} +{{% include "/_common/functions/go-template/text-template.md" %}} diff --git a/content/en/functions/go-template/continue.md b/content/en/functions/go-template/continue.md index c8030b8b7..0b9339bf4 100644 --- a/content/en/functions/go-template/continue.md +++ b/content/en/functions/go-template/continue.md @@ -3,13 +3,11 @@ title: continue description: Used with the range statement, stops the innermost iteration and continues to the next iteration. categories: [] keywords: [] -action: - aliases: [] - related: - - functions/go-template/break - - functions/go-template/range - returnType: - signatures: [continue] +params: + functions_and_methods: + aliases: [] + returnType: + signatures: [continue] --- This template code: @@ -31,4 +29,4 @@ Is rendered to:

    baz

    ``` -{{% include "functions/go-template/_common/text-template.md" %}} +{{% include "/_common/functions/go-template/text-template.md" %}} diff --git a/content/en/functions/go-template/define.md b/content/en/functions/go-template/define.md index f15dd6ff0..19762a3d6 100644 --- a/content/en/functions/go-template/define.md +++ b/content/en/functions/go-template/define.md @@ -3,16 +3,11 @@ title: define description: Defines a template. categories: [] keywords: [] -action: - aliases: [] - related: - - functions/go-template/block - - functions/go-template/end - - functions/go-template/template - - functions/partials/Include - - functions/partials/IncludeCached - returnType: - signatures: [define NAME] +params: + functions_and_methods: + aliases: [] + returnType: + signatures: [define NAME] --- Use with the [`block`] statement: @@ -52,4 +47,4 @@ Use with the [`template`] function: [`template`]: /functions/go-template/block/ [`partial`]: /functions/partials/include/ -{{% include "functions/go-template/_common/text-template.md" %}} +{{% include "/_common/functions/go-template/text-template.md" %}} diff --git a/content/en/functions/go-template/else.md b/content/en/functions/go-template/else.md index 698998bd8..db3980070 100644 --- a/content/en/functions/go-template/else.md +++ b/content/en/functions/go-template/else.md @@ -3,15 +3,11 @@ title: else description: Begins an alternate block for if, with, and range statements. categories: [] keywords: [] -action: - aliases: [] - related: - - functions/go-template/if - - functions/go-template/range - - functions/go-template/with - - functions/go-template/end - returnType: - signatures: [else VALUE] +params: + functions_and_methods: + aliases: [] + returnType: + signatures: [else VALUE] --- Use with the [`if`] statement: @@ -62,7 +58,7 @@ Use `else if` to check multiple conditions. {{ end }} ``` -{{% include "functions/go-template/_common/text-template.md" %}} +{{% include "/_common/functions/go-template/text-template.md" %}} [`if`]: /functions/go-template/if/ [`with`]: /functions/go-template/with/ diff --git a/content/en/functions/go-template/end.md b/content/en/functions/go-template/end.md index 6fb5bbfd6..6de120724 100644 --- a/content/en/functions/go-template/end.md +++ b/content/en/functions/go-template/end.md @@ -3,16 +3,11 @@ title: end description: Terminates if, with, range, block, and define statements. categories: [] keywords: [] -action: - aliases: [] - related: - - functions/go-template/block - - functions/go-template/define - - functions/go-template/if - - functions/go-template/range - - functions/go-template/with - returnType: - signatures: [end] +params: + functions_and_methods: + aliases: [] + returnType: + signatures: [end] --- Use with the [`if`] statement: @@ -56,7 +51,7 @@ Use with the [`define`] statement: {{ end }} ``` -{{% include "functions/go-template/_common/text-template.md" %}} +{{% include "/_common/functions/go-template/text-template.md" %}} [`block`]: /functions/go-template/block/ [`define`]: /functions/go-template/define/ diff --git a/content/en/functions/go-template/if.md b/content/en/functions/go-template/if.md index 9fdf80e99..af2989cca 100644 --- a/content/en/functions/go-template/if.md +++ b/content/en/functions/go-template/if.md @@ -3,18 +3,14 @@ title: if description: Executes the block if the expression is truthy. categories: [] keywords: [] -action: - aliases: [] - related: - - functions/go-template/with - - functions/go-template/else - - functions/go-template/end - - functions/collections/IsSet - returnType: - signatures: [if EXPR] +params: + functions_and_methods: + aliases: [] + returnType: + signatures: [if EXPR] --- -{{% include "functions/go-template/_common/truthy-falsy.md" %}} +{{% include "/_common/functions/truthy-falsy.md" %}} ```go-html-template {{ $var := "foo" }} @@ -49,6 +45,6 @@ Use `else if` to check multiple conditions: {{ end }} ``` -{{% include "functions/go-template/_common/text-template.md" %}} +{{% include "/_common/functions/go-template/text-template.md" %}} [`else`]: /functions/go-template/else/ diff --git a/content/en/functions/go-template/len.md b/content/en/functions/go-template/len.md index 43f150a5f..6a13784e3 100644 --- a/content/en/functions/go-template/len.md +++ b/content/en/functions/go-template/len.md @@ -3,15 +3,11 @@ title: len description: Returns the length of a string, slice, map, or collection. categories: [] keywords: [] -action: - aliases: [] - related: - - functions/strings/Count - - functions/strings/CountRunes - - functions/strings/CountWords - - functions/strings/RuneCount - returnType: int - signatures: [len VALUE] +params: + functions_and_methods: + aliases: [] + returnType: int + signatures: [len VALUE] aliases: [/functions/len] --- @@ -48,4 +44,4 @@ You may also determine the number of pages in a collection with: {{ site.RegularPages.Len }} → 42 ``` -{{% include "functions/go-template/_common/text-template.md" %}} +{{% include "/_common/functions/go-template/text-template.md" %}} diff --git a/content/en/functions/go-template/not.md b/content/en/functions/go-template/not.md index 4c7747c7b..fd8b9afae 100644 --- a/content/en/functions/go-template/not.md +++ b/content/en/functions/go-template/not.md @@ -3,13 +3,11 @@ title: not description: Returns the boolean negation of its single argument. categories: [] keywords: [] -action: - aliases: [] - related: - - functions/go-template/and - - functions/go-template/or - returnType: bool - signatures: [not VALUE] +params: + functions_and_methods: + aliases: [] + returnType: bool + signatures: [not VALUE] --- Unlike the `and` and `or` operators, the `not` operator always returns a boolean value. @@ -32,4 +30,4 @@ Use the `not` operator, twice in succession, to cast any value to a boolean valu {{ "" | not | not }} → false ``` -{{% include "functions/go-template/_common/text-template.md" %}} +{{% include "/_common/functions/go-template/text-template.md" %}} diff --git a/content/en/functions/go-template/or.md b/content/en/functions/go-template/or.md index 0d8619608..2f55fe479 100644 --- a/content/en/functions/go-template/or.md +++ b/content/en/functions/go-template/or.md @@ -3,16 +3,14 @@ title: or description: Returns the first truthy argument. If all arguments are falsy, returns the last argument. categories: [] keywords: [] -action: - aliases: [] - related: - - functions/go-template/and - - functions/go-template/not - returnType: any - signatures: [or VALUE...] +params: + functions_and_methods: + aliases: [] + returnType: any + signatures: [or VALUE...] --- -{{% include "functions/go-template/_common/truthy-falsy.md" %}} +{{% include "/_common/functions/truthy-falsy.md" %}} ```go-html-template {{ or 0 1 2 }} → 1 @@ -23,4 +21,4 @@ action: {{ or 0 "" false }} → false ``` -{{% include "functions/go-template/_common/text-template.md" %}} +{{% include "/_common/functions/go-template/text-template.md" %}} diff --git a/content/en/functions/go-template/range.md b/content/en/functions/go-template/range.md index 96713c4b7..a06907c79 100644 --- a/content/en/functions/go-template/range.md +++ b/content/en/functions/go-template/range.md @@ -3,20 +3,15 @@ title: range description: Iterates over a non-empty collection, binds context (the dot) to successive elements, and executes the block. categories: [] keywords: [] -action: - aliases: [] - related: - - functions/go-template/break - - functions/go-template/continue - - functions/go-template/else - - functions/go-template/end - returnType: - signatures: [range COLLECTION] +params: + functions_and_methods: + aliases: [] + returnType: + signatures: [range COLLECTION] aliases: [/functions/range] -toc: true --- -{{% include "functions/go-template/_common/truthy-falsy.md" %}} +{{% include "/_common/functions/truthy-falsy.md" %}} ```go-html-template {{ $s := slice "foo" "bar" "baz" }} @@ -59,9 +54,8 @@ Hugo will throw an error: The error occurs because we are trying to use the `.Title` method on an integer instead of a `Page` object. Within the `range` block, if we want to render the page title, we need to get the context passed into the template. -{{% note %}} -Use the `$` to get the context passed into the template. -{{% /note %}} +> [!note] +> Use the `$` to get the context passed into the template. This template will render the page title three times: @@ -71,11 +65,8 @@ This template will render the page title three times: {{ end }} ``` -{{% note %}} -Gaining a thorough understanding of context is critical for anyone writing template code. -{{% /note %}} - -[`seq`]: /functions/collections/seq/ +> [!note] +> Gaining a thorough understanding of context is critical for anyone writing template code. ## Array or slice of scalars @@ -191,8 +182,9 @@ Is rendered to: Unlike ranging over an array or slice, Hugo sorts by key when ranging over a map. -{{% include "functions/go-template/_common/text-template.md" %}} +{{% include "/_common/functions/go-template/text-template.md" %}} -[`else`]: /functions/go-template/else/ [`break`]: /functions/go-template/break/ [`continue`]: /functions/go-template/continue/ +[`else`]: /functions/go-template/else/ +[`seq`]: /functions/collections/seq/ diff --git a/content/en/functions/go-template/return.md b/content/en/functions/go-template/return.md index df5b2496e..eb6ba30cd 100644 --- a/content/en/functions/go-template/return.md +++ b/content/en/functions/go-template/return.md @@ -3,14 +3,11 @@ title: return description: Used within partial templates, terminates template execution and returns the given value, if any. categories: [] keywords: [] -action: - aliases: [] - related: - - functions/partials/Include - - functions/partials/IncludeCached - returnType: any - signatures: ['return [VALUE]'] -toc: true +params: + functions_and_methods: + aliases: [] + returnType: any + signatures: ['return [VALUE]'] --- The `return` statement is a non-standard extension to Go's [text/template package]. Used within partial templates, the `return` statement terminates template execution and returns the given value, if any. @@ -19,21 +16,20 @@ The returned value may be of any data type including, but not limited to, [`bool A `return` statement without a value returns an empty string of type `template.HTML`. -{{% note %}} -Unlike `return` statements in other languages, Hugo executes the first occurrence of the `return` statement regardless of its position within logical blocks. See [usage](#usage) notes below. -{{% /note %}} +> [!note] +> Unlike `return` statements in other languages, Hugo executes the first occurrence of the `return` statement regardless of its position within logical blocks. See [usage](#usage) notes below. ## Example By way of example, let's create a partial template that _renders_ HTML, describing whether the given number is odd or even: -{{< code file="layouts/partials/odd-or-even.html" >}} +```go-html-template {file="layouts/partials/odd-or-even.html"} {{ if math.ModBool . 2 }}

    {{ . }} is even

    {{ else }}

    {{ . }} is odd

    {{ end }} -{{< /code >}} +``` When called, the partial renders HTML: @@ -43,9 +39,9 @@ When called, the partial renders HTML: Instead of rendering HTML, let's create a partial that _returns_ a boolean value, reporting whether the given number is even: -{{< code file="layouts/partials/is-even.html" >}} +```go-html-template {file="layouts/partials/is-even.html"} {{ return math.ModBool . 2 }} -{{< /code >}} +``` With this template: @@ -66,19 +62,16 @@ Hugo renders: See additional examples in the [partial templates] section. -[partial templates]: /templates/partial/#returning-a-value-from-a-partial - ## Usage -{{% note %}} -Unlike `return` statements in other languages, Hugo executes the first occurrence of the `return` statement regardless of its position within logical blocks. -{{% /note %}} +> [!note] +> Unlike `return` statements in other languages, Hugo executes the first occurrence of the `return` statement regardless of its position within logical blocks. A partial that returns a value must contain only one `return` statement, placed at the end of the template. For example: -{{< code file="layouts/partials/is-even.html" >}} +```go-html-template {file="layouts/partials/is-even.html"} {{ $result := false }} {{ if math.ModBool . 2 }} {{ $result = "even" }} @@ -86,16 +79,18 @@ For example: {{ $result = "odd" }} {{ end }} {{ return $result }} -{{< /code >}} +``` -{{% note %}} -The construct below is incorrect; it contains more than one `return` statement. -{{% /note %}} +> [!note] +> The construct below is incorrect; it contains more than one `return` statement. -{{< code file="layouts/partials/do-not-do-this.html" >}} +```go-html-template {file="layouts/partials/do-not-do-this.html"} {{ if math.ModBool . 2 }} {{ return "even" }} {{ else }} {{ return "odd" }} {{ end }} -{{< /code >}} +``` + +[partial templates]: /templates/partial/#returning-a-value-from-a-partial +[text/template package]: https://pkg.go.dev/text/template diff --git a/content/en/functions/go-template/template.md b/content/en/functions/go-template/template.md index 0a72acdaa..dac1fa3be 100644 --- a/content/en/functions/go-template/template.md +++ b/content/en/functions/go-template/template.md @@ -3,14 +3,11 @@ title: template description: Executes the given template, optionally passing context. categories: [] keywords: [] -action: - aliases: [] - related: - - functions/go-template/define - - functions/partials/Include - - functions/partials/IncludeCached - returnType: - signatures: ['template NAME [CONTEXT]'] +params: + functions_and_methods: + aliases: [] + returnType: + signatures: ['template NAME [CONTEXT]'] --- Use the `template` function to execute [embedded templates]. For example: @@ -42,7 +39,7 @@ The example above can be rewritten using an [inline partial] template: {{ end }} ``` -{{% include "functions/go-template/_common/text-template.md" %}} +{{% include "/_common/functions/go-template/text-template.md" %}} [`partial`]: /functions/partials/include/ [inline partial]: /templates/partial/#inline-partials diff --git a/content/en/functions/go-template/try.md b/content/en/functions/go-template/try.md index f3385a04c..6aef4da36 100644 --- a/content/en/functions/go-template/try.md +++ b/content/en/functions/go-template/try.md @@ -3,29 +3,28 @@ title: try description: Returns a TryValue object after evaluating the given expression. categories: [] keywords: [] -action: - aliases: [] - related: [] - returnType: TryValue - signatures: ['try EXPRESSION'] -toc: true +params: + functions_and_methods: + aliases: [] + returnType: TryValue + signatures: ['try EXPRESSION'] --- {{< new-in 0.141.0 />}} The `try` statement is a non-standard extension to Go's [text/template] package. It introduces a mechanism for handling errors within templates, mimicking the `try-catch` constructs found in other programming languages. -[text/template]: https://pkg.go.dev/text/template - ## Methods The `TryValue` object encapsulates the result of evaluating the expression, and provides two methods: -Err -: (`string`) Returns a string representation of the error thrown by the expression, if an error occurred, or returns `nil` if the expression evaluated without errors. +### Err -Value -: (`any`) Returns the result of the expression if the evaluation was successful, or returns `nil` if an error occurred while evaluating the expression. +(`string`) Returns a string representation of the error thrown by the expression, if an error occurred, or returns `nil` if the expression evaluated without errors. + +### Value + +(`any`) Returns the result of the expression if the evaluation was successful, or returns `nil` if an error occurred while evaluating the expression. ## Explanation @@ -88,8 +87,6 @@ Hugo renders the above to: Error handling is essential when using the [`resources.GetRemote`] function to capture remote resources such as data or images. When calling this function, if the HTTP request fails, Hugo will fail the build. -[`resources.GetRemote`]: /functions/resources/getremote/ - Instead of failing the build, we can catch the error and emit a warning: ```go-html-template @@ -106,8 +103,9 @@ Instead of failing the build, we can catch the error and emit a warning: ``` In the above, note that the [context](g) within the last conditional block is the `TryValue` object returned by the `try` statement. At this point neither the `Err` nor `Value` methods returned anything, so the current context is not useful. Use the `$` to access the [template context] if needed. -[template context]: /templates/introduction/#template-context +> [!note] +> Hugo does not classify an HTTP response with status code 404 as an error. In this case `resources.GetRemote` returns nil. -{{% note %}} -Hugo does not classify an HTTP response with status code 404 as an error. In this case `resources.GetRemote` returns nil. -{{% /note %}} +[`resources.GetRemote`]: /functions/resources/getremote/ +[template context]: /templates/introduction/#template-context +[text/template]: https://pkg.go.dev/text/template diff --git a/content/en/functions/go-template/urlquery.md b/content/en/functions/go-template/urlquery.md index 946828f56..dc97f867e 100644 --- a/content/en/functions/go-template/urlquery.md +++ b/content/en/functions/go-template/urlquery.md @@ -3,12 +3,11 @@ title: urlquery description: Returns the escaped value of the textual representation of its arguments in a form suitable for embedding in a URL query. categories: [] keywords: [] -action: - aliases: [] - related: - - functions/collections/Querify - returnType: string - signatures: ['urlquery VALUE [VALUE...]'] +params: + functions_and_methods: + aliases: [] + returnType: string + signatures: ['urlquery VALUE [VALUE...]'] aliases: [/functions/urlquery] --- @@ -25,4 +24,4 @@ Is rendered to: Link ``` -{{% include "functions/go-template/_common/text-template.md" %}} +{{% include "/_common/functions/go-template/text-template.md" %}} diff --git a/content/en/functions/go-template/with.md b/content/en/functions/go-template/with.md index a730f4d2c..c25ce3fba 100644 --- a/content/en/functions/go-template/with.md +++ b/content/en/functions/go-template/with.md @@ -3,20 +3,15 @@ title: with description: Binds context (the dot) to the expression and executes the block if expression is truthy. categories: [] keywords: [] -action: - aliases: [] - related: - - functions/go-template/if - - functions/go-template/else - - functions/go-template/end - - functions/collections/IsSet - returnType: - signatures: [with EXPR] +params: + functions_and_methods: + aliases: [] + returnType: + signatures: [with EXPR] aliases: [/functions/with] -toc: true --- -{{% include "functions/go-template/_common/truthy-falsy.md" %}} +{{% include "/_common/functions/truthy-falsy.md" %}} ```go-html-template {{ $var := "foo" }} @@ -78,9 +73,8 @@ Hugo will throw an error: The error occurs because we are trying to use the `.Title` method on an integer instead of a `Page` object. Inside of the `with` block, if we want to render the page title, we need to get the context passed into the template. -{{% note %}} -Use the `$` to get the context passed into the template. -{{% /note %}} +> [!note] +> Use the `$` to get the context passed into the template. This template will render the page title as desired: @@ -90,10 +84,9 @@ This template will render the page title as desired: {{ end }} ``` -{{% note %}} -Gaining a thorough understanding of context is critical for anyone writing template code. -{{% /note %}} +> [!note] +> Gaining a thorough understanding of context is critical for anyone writing template code. -{{% include "functions/go-template/_common/text-template.md" %}} +{{% include "/_common/functions/go-template/text-template.md" %}} [`else`]: /functions/go-template/else/ diff --git a/content/en/functions/hash/FNV32a.md b/content/en/functions/hash/FNV32a.md index b5af77519..b108acff8 100644 --- a/content/en/functions/hash/FNV32a.md +++ b/content/en/functions/hash/FNV32a.md @@ -1,18 +1,13 @@ --- title: hash.FNV32a -description: Returns the 32-bit FNV (Fowler–Noll–Vo) non-cryptographic hash of the given string. +description: Returns the 32-bit FNV (Fowler-Noll-Vo) non-cryptographic hash of the given string. categories: [] keywords: [] -action: - aliases: [] - related: - - functions/hash/Xxhash - - functions/crypto/HMAC - - functions/crypto/MD5 - - functions/crypto/SHA1 - - functions/crypto/SHA256 - returnType: int - signatures: [hash.FNV32a STRING] +params: + functions_and_methods: + aliases: [] + returnType: int + signatures: [hash.FNV32a STRING] aliases: [/functions/crypto.fnv32a] --- diff --git a/content/en/functions/hash/XxHash.md b/content/en/functions/hash/XxHash.md index 7d35c18e5..6a92b2bdc 100644 --- a/content/en/functions/hash/XxHash.md +++ b/content/en/functions/hash/XxHash.md @@ -3,18 +3,15 @@ title: hash.XxHash description: Returns the 64-bit xxHash non-cryptographic hash of the given string. categories: [] keywords: [] -action: - aliases: [xxhash] - related: - - functions/hash/FNV32a - - functions/crypto/HMAC - - functions/crypto/MD5 - - functions/crypto/SHA1 - - functions/crypto/SHA256 - returnType: string - signatures: [hash.XxHash STRING] +params: + functions_and_methods: + aliases: [xxhash] + returnType: string + signatures: [hash.XxHash STRING] --- ```go-html-template {{ hash.XxHash "Hello world" }} → c500b0c912b376d8 ``` + +[xxHash](https://xxhash.com/) is a very fast non-cryptographic hash algorithm. Hugo uses [this Go implementation](https://github.com/cespare/xxhash). diff --git a/content/en/functions/hash/_index.md b/content/en/functions/hash/_index.md index bf21c5b7b..956f7fb8d 100644 --- a/content/en/functions/hash/_index.md +++ b/content/en/functions/hash/_index.md @@ -1,12 +1,7 @@ --- title: Hash functions linkTitle: hash -description: Template functions to create non-cryptographic hashes. +description: Use these functions to create non-cryptographic hashes. categories: [] keywords: [] -menu: - docs: - parent: functions --- - -Use these functions to create non-cryptographic hashes. diff --git a/content/en/functions/hugo/BuildDate.md b/content/en/functions/hugo/BuildDate.md index 1fbdbeac6..a592283b9 100644 --- a/content/en/functions/hugo/BuildDate.md +++ b/content/en/functions/hugo/BuildDate.md @@ -3,11 +3,11 @@ title: hugo.BuildDate description: Returns the compile date of the Hugo binary. categories: [] keywords: [] -action: - aliases: [] - related: [] - returnType: string - signatures: [hugo.BuildDate] +params: + functions_and_methods: + aliases: [] + returnType: string + signatures: [hugo.BuildDate] --- The `hugo.BuildDate` function returns the compile date of the Hugo binary, formatted per [RFC 3339]. diff --git a/content/en/functions/hugo/CommitHash.md b/content/en/functions/hugo/CommitHash.md index cd4f2ce92..324e985d1 100644 --- a/content/en/functions/hugo/CommitHash.md +++ b/content/en/functions/hugo/CommitHash.md @@ -3,11 +3,11 @@ title: hugo.CommitHash description: Returns the Git commit hash of the Hugo binary. categories: [] keywords: [] -action: - aliases: [] - related: [] - returnType: string - signatures: [hugo.CommitHash] +params: + functions_and_methods: + aliases: [] + returnType: string + signatures: [hugo.CommitHash] --- ```go-html-template diff --git a/content/en/functions/hugo/Deps.md b/content/en/functions/hugo/Deps.md index 2f3f75e65..9d8667ee5 100644 --- a/content/en/functions/hugo/Deps.md +++ b/content/en/functions/hugo/Deps.md @@ -3,11 +3,11 @@ title: hugo.Deps description: Returns a slice of project dependencies, either Hugo Modules or local theme components. categories: [] keywords: [] -action: - aliases: [] - related: [] - returnType: '[]hugo.Dependency' - signatures: [hugo.Deps] +params: + functions_and_methods: + aliases: [] + returnType: '[]hugo.Dependency' + signatures: [hugo.Deps] --- The `hugo.Deps` function returns a slice of project dependencies, either Hugo Modules or local theme components. Each dependency contains: diff --git a/content/en/functions/hugo/Environment.md b/content/en/functions/hugo/Environment.md index 374a39f6c..551306255 100644 --- a/content/en/functions/hugo/Environment.md +++ b/content/en/functions/hugo/Environment.md @@ -3,13 +3,11 @@ title: hugo.Environment description: Returns the current running environment. categories: [] keywords: [] -action: - aliases: [] - related: - - functions/hugo/IsDevelopment - - functions/hugo/IsProduction - returnType: string - signatures: [hugo.Environment] +params: + functions_and_methods: + aliases: [] + returnType: string + signatures: [hugo.Environment] --- The `hugo.Environment` function returns the current running [environment](g) as defined through the `--environment` command line flag. diff --git a/content/en/functions/hugo/Generator.md b/content/en/functions/hugo/Generator.md index 17eb47e1d..dc72a7af2 100644 --- a/content/en/functions/hugo/Generator.md +++ b/content/en/functions/hugo/Generator.md @@ -1,15 +1,15 @@ --- title: hugo.Generator -description: Renders an HTML meta element identifying the software that generated the site. +description: Renders an HTML meta element identifying the software that generated the site. categories: [] keywords: [] -action: - aliases: [] - related: [] - returnType: template.HTML - signatures: [hugo.Generator] +params: + functions_and_methods: + aliases: [] + returnType: template.HTML + signatures: [hugo.Generator] --- ```go-html-template -{{ hugo.Generator }} → +{{ hugo.Generator }} → ``` diff --git a/content/en/functions/hugo/GoVersion.md b/content/en/functions/hugo/GoVersion.md index 34c6266bf..94e310deb 100644 --- a/content/en/functions/hugo/GoVersion.md +++ b/content/en/functions/hugo/GoVersion.md @@ -3,11 +3,11 @@ title: hugo.GoVersion description: Returns the Go version used to compile the Hugo binary categories: [] keywords: [] -action: - aliases: [] - related: [] - returnType: string - signatures: [hugo.GoVersion] +params: + functions_and_methods: + aliases: [] + returnType: string + signatures: [hugo.GoVersion] --- ```go-html-template diff --git a/content/en/functions/hugo/IsDevelopment.md b/content/en/functions/hugo/IsDevelopment.md index bfbc0eaa1..cea923acd 100644 --- a/content/en/functions/hugo/IsDevelopment.md +++ b/content/en/functions/hugo/IsDevelopment.md @@ -3,13 +3,11 @@ title: hugo.IsDevelopment description: Reports whether the current running environment is "development". categories: [] keywords: [] -action: - aliases: [] - related: - - functions/hugo/IsProduction - - functions/hugo/Environment - returnType: bool - signatures: [hugo.IsDevelopment] +params: + functions_and_methods: + aliases: [] + returnType: bool + signatures: [hugo.IsDevelopment] --- {{< new-in 0.120.0 />}} diff --git a/content/en/functions/hugo/IsExtended.md b/content/en/functions/hugo/IsExtended.md index 9beac6e49..ab7e0f7b1 100644 --- a/content/en/functions/hugo/IsExtended.md +++ b/content/en/functions/hugo/IsExtended.md @@ -3,11 +3,11 @@ title: hugo.IsExtended description: Reports whether the Hugo binary is either the extended or extended/deploy edition. categories: [] keywords: [] -action: - aliases: [] - related: [] - returnType: bool - signatures: [hugo.IsExtended] +params: + functions_and_methods: + aliases: [] + returnType: bool + signatures: [hugo.IsExtended] --- ```go-html-template diff --git a/content/en/functions/hugo/IsMultihost.md b/content/en/functions/hugo/IsMultihost.md index 5c1cb9f83..605afa79a 100644 --- a/content/en/functions/hugo/IsMultihost.md +++ b/content/en/functions/hugo/IsMultihost.md @@ -3,12 +3,11 @@ title: hugo.IsMultihost description: Reports whether each configured language has a unique base URL. categories: [] keywords: [] -action: - aliases: [] - related: - - /functions/hugo/IsMultilingual - returnType: bool - signatures: [hugo.IsMultihost] +params: + functions_and_methods: + aliases: [] + returnType: bool + signatures: [hugo.IsMultihost] --- {{< new-in 0.124.0 />}} diff --git a/content/en/functions/hugo/IsMultilingual.md b/content/en/functions/hugo/IsMultilingual.md index 91beb0d52..85fc6550f 100644 --- a/content/en/functions/hugo/IsMultilingual.md +++ b/content/en/functions/hugo/IsMultilingual.md @@ -3,11 +3,11 @@ title: hugo.IsMultilingual description: Reports whether there are two or more configured languages. categories: [] keywords: [] -action: - related: - - /functions/hugo/IsMultihost - returnType: bool - signatures: [hugo.IsMultilingual] +params: + functions_and_methods: + aliases: [] + returnType: bool + signatures: [hugo.IsMultilingual] --- {{< new-in 0.124.0 />}} diff --git a/content/en/functions/hugo/IsProduction.md b/content/en/functions/hugo/IsProduction.md index 7e9bda0e3..e5433c239 100644 --- a/content/en/functions/hugo/IsProduction.md +++ b/content/en/functions/hugo/IsProduction.md @@ -3,13 +3,11 @@ title: hugo.IsProduction description: Reports whether the current running environment is "production". categories: [] keywords: [] -action: - aliases: [] - related: - - functions/hugo/IsDevelopment - - functions/hugo/Environment - returnType: bool - signatures: [hugo.IsProduction] +params: + functions_and_methods: + aliases: [] + returnType: bool + signatures: [hugo.IsProduction] --- ```go-html-template diff --git a/content/en/functions/hugo/IsServer.md b/content/en/functions/hugo/IsServer.md index 0fa42fc15..840ff060d 100644 --- a/content/en/functions/hugo/IsServer.md +++ b/content/en/functions/hugo/IsServer.md @@ -3,11 +3,11 @@ title: hugo.IsServer description: Reports whether the built-in development server is running. categories: [] keywords: [] -action: - aliases: [] - related: [] - returnType: bool - signatures: [hugo.IsServer] +params: + functions_and_methods: + aliases: [] + returnType: bool + signatures: [hugo.IsServer] --- {{< new-in 0.120.0 />}} diff --git a/content/en/functions/hugo/Store.md b/content/en/functions/hugo/Store.md index 4f3250954..08c684146 100644 --- a/content/en/functions/hugo/Store.md +++ b/content/en/functions/hugo/Store.md @@ -3,15 +3,10 @@ title: hugo.Store description: Returns a globally scoped "scratch pad" to store and manipulate data. categories: [] keywords: [] -action: - related: - - methods/page/Store - - methods/site/Store - - methods/shortcode/Store - - functions/collections/NewScratch - returnType: maps.Scratch - signatures: [hugo.Store] -toc: true +params: + functions_and_methods: + returnType: maps.Scratch + signatures: [hugo.Store] --- {{< new-in 0.139.0 />}} @@ -20,7 +15,7 @@ Use the `hugo.Store` function to create a globally scoped [scratch pad](g) to st ## Methods -###### Set +### Set Sets the value of the given key. @@ -28,7 +23,7 @@ Sets the value of the given key. {{ hugo.Store.Set "greeting" "Hello" }} ``` -###### Get +### Get Gets the value of the given key. @@ -37,7 +32,7 @@ Gets the value of the given key. {{ hugo.Store.Get "greeting" }} → Hello ``` -###### Add +### Add Adds the given value to the existing value(s) of the given key. @@ -61,7 +56,7 @@ For single values, `Add` accepts values that support Go's `+` operator. If the f {{ hugo.Store.Get "greetings" }} → [Hello Welcome Cheers] ``` -###### SetInMap +### SetInMap Takes a `key`, `mapKey` and `value` and adds a map of `mapKey` and `value` to the given `key`. @@ -71,7 +66,7 @@ Takes a `key`, `mapKey` and `value` and adds a map of `mapKey` and `value` to th {{ hugo.Store.Get "greetings" }} → map[english:Hello french:Bonjour] ``` -###### DeleteInMap +### DeleteInMap Takes a `key` and `mapKey` and removes the map of `mapKey` from the given `key`. @@ -80,9 +75,9 @@ Takes a `key` and `mapKey` and removes the map of `mapKey` from the given `key`. {{ hugo.Store.SetInMap "greetings" "french" "Bonjour" }} {{ hugo.Store.DeleteInMap "greetings" "english" }} {{ hugo.Store.Get "greetings" }} → map[french:Bonjour] -``` + ``` -###### GetSortedMapValues +### GetSortedMapValues Returns an array of values from `key` sorted by `mapKey`. @@ -92,7 +87,7 @@ Returns an array of values from `key` sorted by `mapKey`. {{ hugo.Store.GetSortedMapValues "greetings" }} → [Hello Bonjour] ``` -###### Delete +### Delete Removes the given key. diff --git a/content/en/functions/hugo/Version.md b/content/en/functions/hugo/Version.md index e6e1207b8..7925af981 100644 --- a/content/en/functions/hugo/Version.md +++ b/content/en/functions/hugo/Version.md @@ -3,13 +3,13 @@ title: hugo.Version description: Returns the current version of the Hugo binary. categories: [] keywords: [] -action: - aliases: [] - related: [] - returnType: hugo.VersionString - signatures: [hugo.Version] +params: + functions_and_methods: + aliases: [] + returnType: hugo.VersionString + signatures: [hugo.Version] --- ```go-html-template -{{ hugo.Version }} → 0.141.0 +{{ hugo.Version }} → 0.144.2 ``` diff --git a/content/en/functions/hugo/WorkingDir.md b/content/en/functions/hugo/WorkingDir.md index ac3835ea8..e50102558 100644 --- a/content/en/functions/hugo/WorkingDir.md +++ b/content/en/functions/hugo/WorkingDir.md @@ -3,11 +3,11 @@ title: hugo.WorkingDir description: Returns the project working directory. categories: [] keywords: [] -action: - aliases: [] - related: [] - returnType: string - signatures: [hugo.WorkingDir] +params: + functions_and_methods: + aliases: [] + returnType: string + signatures: [hugo.WorkingDir] --- ```go-html-template diff --git a/content/en/functions/hugo/_index.md b/content/en/functions/hugo/_index.md index c3ad686da..b1c9216c4 100644 --- a/content/en/functions/hugo/_index.md +++ b/content/en/functions/hugo/_index.md @@ -1,12 +1,7 @@ --- title: Hugo functions linkTitle: hugo -description: Template functions to access information about the Hugo application and the current environment. +description: Use these functions to access information about the Hugo application and the current environment. categories: [] keywords: [] -menu: - docs: - parent: functions --- - -Use these functions to access information about the Hugo application and the current environment. diff --git a/content/en/functions/images/AutoOrient.md b/content/en/functions/images/AutoOrient.md index 8e3708eea..fd8d2ed14 100644 --- a/content/en/functions/images/AutoOrient.md +++ b/content/en/functions/images/AutoOrient.md @@ -3,14 +3,11 @@ title: images.AutoOrient description: Returns an image filter that rotates and flips an image as needed per its EXIF orientation tag. categories: [] keywords: [] -action: - aliases: [] - related: - - functions/images/Filter - - methods/resource/Filter - returnType: images.filter - signatures: [images.AutoOrient] -toc: true +params: + functions_and_methods: + aliases: [] + returnType: images.filter + signatures: [images.AutoOrient] --- {{< new-in 0.121.2 />}} @@ -23,11 +20,10 @@ Create the filter: {{ $filter := images.AutoOrient }} ``` -{{% include "functions/images/_common/apply-image-filter.md" %}} +{{% include "/_common/functions/images/apply-image-filter.md" %}} -{{% note %}} -When using with other filters, specify `images.AutoOrient` first. -{{% /note %}} +> [!note] +> When using with other filters, specify `images.AutoOrient` first. ```go-html-template {{ $filters := slice diff --git a/content/en/functions/images/Brightness.md b/content/en/functions/images/Brightness.md index 0001bcba8..0ddfcba55 100644 --- a/content/en/functions/images/Brightness.md +++ b/content/en/functions/images/Brightness.md @@ -3,14 +3,11 @@ title: images.Brightness description: Returns an image filter that changes the brightness of an image. categories: [] keywords: [] -action: - aliases: [] - related: - - functions/images/Filter - - methods/resource/Filter - returnType: images.filter - signatures: [images.Brightness PERCENTAGE] -toc: true +params: + functions_and_methods: + aliases: [] + returnType: images.filter + signatures: [images.Brightness PERCENTAGE] --- The percentage must be in the range [-100, 100] where 0 has no effect. A value of `-100` produces a solid black image, and a value of `100` produces a solid white image. @@ -23,7 +20,7 @@ Create the image filter: {{ $filter := images.Brightness 12 }} ``` -{{% include "functions/images/_common/apply-image-filter.md" %}} +{{% include "/_common/functions/images/apply-image-filter.md" %}} ## Example diff --git a/content/en/functions/images/ColorBalance.md b/content/en/functions/images/ColorBalance.md index 29829f9e6..be4a2bce8 100644 --- a/content/en/functions/images/ColorBalance.md +++ b/content/en/functions/images/ColorBalance.md @@ -3,14 +3,11 @@ title: images.ColorBalance description: Returns an image filter that changes the color balance of an image. categories: [] keywords: [] -action: - aliases: [] - related: - - functions/images/Filter - - methods/resource/Filter - returnType: images.filter - signatures: [images.ColorBalance PCTRED PCTGREEN PCTBLUE] -toc: true +params: + functions_and_methods: + aliases: [] + returnType: images.filter + signatures: [images.ColorBalance PCTRED PCTGREEN PCTBLUE] --- The percentage for each channel (red, green, blue) must be in the range [-100, 500]. @@ -23,7 +20,7 @@ Create the filter: {{ $filter := images.ColorBalance -10 10 50 }} ``` -{{% include "functions/images/_common/apply-image-filter.md" %}} +{{% include "/_common/functions/images/apply-image-filter.md" %}} ## Example diff --git a/content/en/functions/images/Colorize.md b/content/en/functions/images/Colorize.md index c974103b9..6b8cd5966 100644 --- a/content/en/functions/images/Colorize.md +++ b/content/en/functions/images/Colorize.md @@ -3,14 +3,11 @@ title: images.Colorize description: Returns an image filter that produces a colorized version of an image. categories: [] keywords: [] -action: - aliases: [] - related: - - functions/images/Filter - - methods/resource/Filter - returnType: images.filter - signatures: [images.Colorize HUE SATURATION PERCENTAGE] -toc: true +params: + functions_and_methods: + aliases: [] + returnType: images.filter + signatures: [images.Colorize HUE SATURATION PERCENTAGE] --- The hue is the angle on the color wheel, typically in the range [0, 360]. @@ -27,7 +24,7 @@ Create the filter: {{ $filter := images.Colorize 180 50 20 }} ``` -{{% include "functions/images/_common/apply-image-filter.md" %}} +{{% include "/_common/functions/images/apply-image-filter.md" %}} ## Example diff --git a/content/en/functions/images/Config.md b/content/en/functions/images/Config.md index 8f79a65f8..59242fb95 100644 --- a/content/en/functions/images/Config.md +++ b/content/en/functions/images/Config.md @@ -3,18 +3,16 @@ title: images.Config description: Returns an image.Config structure from the image at the specified path, relative to the working directory. categories: [] keywords: [] -action: - aliases: [] - related: [] - returnType: image.Config - signatures: [images.Config PATH] +params: + functions_and_methods: + aliases: [] + returnType: image.Config + signatures: [images.Config PATH] aliases: [/functions/imageconfig] --- See [image processing] for an overview of Hugo's image pipeline. -[image processing]: /content-management/image-processing/ - ```go-html-template {{ $ic := images.Config "/static/images/a.jpg" }} @@ -24,10 +22,9 @@ See [image processing] for an overview of Hugo's image pipeline. Supported image formats include GIF, JPEG, PNG, TIFF, and WebP. -{{% note %}} -This is a legacy function, superseded by the [`Width`] and [`Height`] methods for [global resources](g), [page resources](g), and [remote resources](g). See the [image processing] section for details. +> [!note] +> This is a legacy function, superseded by the [`Width`] and [`Height`] methods for [global resources](g), [page resources](g), and [remote resources](g). See the [image processing] section for details. -[`Width`]: /methods/resource/width/ [`Height`]: /methods/resource/height/ +[`Width`]: /methods/resource/width/ [image processing]: /content-management/image-processing/ -{{% /note %}} diff --git a/content/en/functions/images/Contrast.md b/content/en/functions/images/Contrast.md index 532ae8c9c..f5d607440 100644 --- a/content/en/functions/images/Contrast.md +++ b/content/en/functions/images/Contrast.md @@ -3,14 +3,11 @@ title: images.Contrast description: Returns an image filter that changes the contrast of an image. categories: [] keywords: [] -action: - aliases: [] - related: - - functions/images/Filter - - methods/resource/Filter - returnType: images.filter - signatures: [images.Contrast PERCENTAGE] -toc: true +params: + functions_and_methods: + aliases: [] + returnType: images.filter + signatures: [images.Contrast PERCENTAGE] --- The percentage must be in the range [-100, 100] where 0 has no effect. A value of `-100` produces a solid grey image, and a value of `100` produces an over-contrasted image. @@ -23,7 +20,7 @@ Create the filter: {{ $filter := images.Contrast -20 }} ``` -{{% include "functions/images/_common/apply-image-filter.md" %}} +{{% include "/_common/functions/images/apply-image-filter.md" %}} ## Example diff --git a/content/en/functions/images/Dither.md b/content/en/functions/images/Dither.md index d6ae603a8..eab7743f7 100644 --- a/content/en/functions/images/Dither.md +++ b/content/en/functions/images/Dither.md @@ -3,16 +3,11 @@ title: images.Dither description: Returns an image filter that dithers an image. categories: [] keywords: [] -action: - aliases: [] - related: - - functions/images/Filter - - functions/images/Process - - methods/resource/Colors - - methods/resource/Filter - returnType: images.filter - signatures: ['images.Dither [OPTIONS]'] -toc: true +params: + functions_and_methods: + aliases: [] + returnType: images.filter + signatures: ['images.Dither [OPTIONS]'] --- {{< new-in 0.123.0 />}} @@ -28,7 +23,7 @@ method : (`string`) The dithering method. See the [dithering methods](#dithering-methods) section below for a list of the available methods. Default is `FloydSteinberg`. serpentine -: (`bool`) Applicable to error diffusion dithering methods, serpentine controls whether the error diffusion matrix is applied in a serpentine manner, meaning that it goes right-to-left every other line. This greatly reduces line-type artifacts. Default is `true`. +: (`bool`) Applicable to error diffusion dithering methods, whether to apply the error diffusion matrix in a serpentine manner, meaning that it goes right-to-left every other line. This greatly reduces line-type artifacts. Default is `true`. strength : (`float`) The strength at which to apply the dithering matrix, typically a value in the range [0, 1]. A value of `1.0` applies the dithering matrix at 100% strength (no modification of the dither matrix). The `strength` is inversely proportional to contrast; reducing the strength increases the contrast. Setting `strength` to a value such as `0.8` can be useful to reduce noise in the dithered image. Default is `1.0`. @@ -57,13 +52,13 @@ Or create the filter using the default settings: {{ $filter := images.Dither }} ``` -{{% include "functions/images/_common/apply-image-filter.md" %}} +{{% include "/_common/functions/images/apply-image-filter.md" %}} ## Dithering methods See the [Go documentation] for descriptions of each of the dithering methods below. -[Go documentation]: https://pkg.go.dev/github.com/makeworld-the-better-one/dither/v2#pkg-variables +[Go documentation]: https://pkg.go.dev/github.com/makeworld-the-better-one/dither/v2#pkg-variables Error diffusion dithering methods: diff --git a/content/en/functions/images/Filter.md b/content/en/functions/images/Filter.md index 2961d7f47..1f2c268be 100644 --- a/content/en/functions/images/Filter.md +++ b/content/en/functions/images/Filter.md @@ -3,13 +3,11 @@ title: images.Filter description: Applies one or more image filters to the given image resource. categories: [] keywords: [] -action: - aliases: [] - related: - - methods/resource/Filter - returnType: images.ImageResource - signatures: [images.Filter FILTERS... IMAGE] -toc: true +params: + functions_and_methods: + aliases: [] + returnType: images.ImageResource + signatures: [images.Filter FILTERS... IMAGE] --- Apply one or more [image filters](#image-filters) to the given image. @@ -64,4 +62,4 @@ You can also apply image filters using the [`Filter`] method on a `Resource` obj Use any of these filters with the `images.Filter` function, or with the `Filter` method on a `Resource` object. -{{< list-pages-in-section path=/functions/images filter=functions_images_no_filters filterType=exclude >}} +{{% list-pages-in-section path=/functions/images filter=functions_images_no_filters filterType=exclude %}} diff --git a/content/en/functions/images/Gamma.md b/content/en/functions/images/Gamma.md index affbdcfa8..d8cb076f1 100644 --- a/content/en/functions/images/Gamma.md +++ b/content/en/functions/images/Gamma.md @@ -3,14 +3,11 @@ title: images.Gamma description: Returns an image filter that performs gamma correction on an image. categories: [] keywords: [] -action: - aliases: [] - related: - - functions/images/Filter - - methods/resource/Filter - returnType: images.filter - signatures: [images.Gamma GAMMA] -toc: true +params: + functions_and_methods: + aliases: [] + returnType: images.filter + signatures: [images.Gamma GAMMA] --- The gamma value must be positive. A value greater than 1 lightens the image, while a value less than 1 darkens the image. The filter has no effect when the gamma value is 1. @@ -23,7 +20,7 @@ Create the filter: {{ $filter := images.Gamma 1.667 }} ``` -{{% include "functions/images/_common/apply-image-filter.md" %}} +{{% include "/_common/functions/images/apply-image-filter.md" %}} ## Example diff --git a/content/en/functions/images/GaussianBlur.md b/content/en/functions/images/GaussianBlur.md index e2f49a847..c5eb136e2 100644 --- a/content/en/functions/images/GaussianBlur.md +++ b/content/en/functions/images/GaussianBlur.md @@ -3,14 +3,11 @@ title: images.GaussianBlur description: Returns an image filter that applies a gaussian blur to an image. categories: [] keywords: [] -action: - aliases: [] - related: - - functions/images/Filter - - methods/resource/Filter - returnType: images.filter - signatures: [images.GaussianBlur SIGMA] -toc: true +params: + functions_and_methods: + aliases: [] + returnType: images.filter + signatures: [images.GaussianBlur SIGMA] --- The sigma value must be positive, and indicates how much the image will be blurred. The blur-affected radius is approximately 3 times the sigma value. @@ -23,7 +20,7 @@ Create the filter: {{ $filter := images.GaussianBlur 5 }} ``` -{{% include "functions/images/_common/apply-image-filter.md" %}} +{{% include "/_common/functions/images/apply-image-filter.md" %}} ## Example diff --git a/content/en/functions/images/Grayscale.md b/content/en/functions/images/Grayscale.md index d8a89b7f2..d3651b8dc 100644 --- a/content/en/functions/images/Grayscale.md +++ b/content/en/functions/images/Grayscale.md @@ -3,14 +3,11 @@ title: images.Grayscale description: Returns an image filter that produces a grayscale version of an image. categories: [] keywords: [] -action: - aliases: [] - related: - - functions/images/Filter - - methods/resource/Filter - returnType: images.filter - signatures: [images.Grayscale] -toc: true +params: + functions_and_methods: + aliases: [] + returnType: images.filter + signatures: [images.Grayscale] --- ## Usage @@ -21,7 +18,7 @@ Create the filter: {{ $filter := images.Grayscale }} ``` -{{% include "functions/images/_common/apply-image-filter.md" %}} +{{% include "/_common/functions/images/apply-image-filter.md" %}} ## Example diff --git a/content/en/functions/images/Hue.md b/content/en/functions/images/Hue.md index 6eafac437..f334eebd8 100644 --- a/content/en/functions/images/Hue.md +++ b/content/en/functions/images/Hue.md @@ -3,14 +3,11 @@ title: images.Hue description: Returns an image filter that rotates the hue of an image. categories: [] keywords: [] -action: - aliases: [] - related: - - functions/images/Filter - - methods/resource/Filter - returnType: images.filter - signatures: [images.Hue SHIFT] -toc: true +params: + functions_and_methods: + aliases: [] + returnType: images.filter + signatures: [images.Hue SHIFT] --- The hue angle shift is typically in the range [-180, 180] where 0 has no effect. @@ -23,7 +20,7 @@ Create the filter: {{ $filter := images.Hue -15 }} ``` -{{% include "functions/images/_common/apply-image-filter.md" %}} +{{% include "/_common/functions/images/apply-image-filter.md" %}} ## Example diff --git a/content/en/functions/images/Invert.md b/content/en/functions/images/Invert.md index 1ee85e514..0f9f9a9d2 100644 --- a/content/en/functions/images/Invert.md +++ b/content/en/functions/images/Invert.md @@ -3,14 +3,11 @@ title: images.Invert description: Returns an image filter that negates the colors of an image. categories: [] keywords: [] -action: - aliases: [] - related: - - functions/images/Filter - - methods/resource/Filter - returnType: images.filter - signatures: [images.Invert] -toc: true +params: + functions_and_methods: + aliases: [] + returnType: images.filter + signatures: [images.Invert] --- ## Usage @@ -21,7 +18,7 @@ Create the filter: {{ $filter := images.Invert }} ``` -{{% include "functions/images/_common/apply-image-filter.md" %}} +{{% include "/_common/functions/images/apply-image-filter.md" %}} ## Example diff --git a/content/en/functions/images/Mask.md b/content/en/functions/images/Mask.md index 8116e8946..4f3b4aa3f 100644 --- a/content/en/functions/images/Mask.md +++ b/content/en/functions/images/Mask.md @@ -3,23 +3,19 @@ title: images.Mask description: Returns an image filter that applies a mask to the source image. categories: [] keywords: [] -action: - aliases: [] - related: - - functions/images/Filter - - methods/resource/Filter - returnType: images.filter - signatures: [images.Mask RESOURCE] -toc: true +params: + functions_and_methods: + aliases: [] + returnType: images.filter + signatures: [images.Mask RESOURCE] --- {{< new-in 0.141.0 />}} The `images.Mask` filter applies a mask to an image. Black pixels in the mask make the corresponding areas of the base image transparent, while white pixels keep them opaque. Color images are converted to grayscale for masking purposes. The mask is automatically resized to match the dimensions of the base image. -{{% note %}} -Of the formats supported by Hugo's imaging pipelie, 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. -{{% /note %}} +> [!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: @@ -27,8 +23,6 @@ When applying a mask to a non-transparent image format such as JPEG, the masked {{ $filter := images.Process "#00ff00" }} ``` -[site configuration]: /content-management/image-processing/#imaging-configuration - ## Usage Create a slice of filters, one for WebP conversion and the other for mask application: @@ -59,9 +53,6 @@ You can also apply the filter using the [`Filter`] method on a 'Resource' object {{ end }} ``` -[`images.Filter`]: /functions/images/filter/ -[`Filter`]: /methods/resource/filter/ - ## Example Mask @@ -78,3 +69,7 @@ Mask filterArgs="images/examples/mask.png" example=true >}} + +[`Filter`]: /methods/resource/filter/ +[`images.Filter`]: /functions/images/filter/ +[site configuration]: /configuration/imaging/ diff --git a/content/en/functions/images/Opacity.md b/content/en/functions/images/Opacity.md index 32b1bd23c..b9dcf3fd2 100644 --- a/content/en/functions/images/Opacity.md +++ b/content/en/functions/images/Opacity.md @@ -3,14 +3,11 @@ title: images.Opacity description: Returns an image filter that changes the opacity of an image. categories: [] keywords: [] -action: - aliases: [] - related: - - functions/images/Filter - - methods/resource/Filter - returnType: images.filter - signatures: [images.Opacity OPACITY] -toc: true +params: + functions_and_methods: + aliases: [] + returnType: images.filter + signatures: [images.Opacity OPACITY] --- {{< new-in 0.119.0 />}} @@ -25,7 +22,7 @@ Create the filter: {{ $filter := images.Opacity 0.65 }} ``` -{{% include "functions/images/_common/apply-image-filter.md" %}} +{{% include "/_common/functions/images/apply-image-filter.md" %}} The `images.Opacity` filter is most useful for target formats such as PNG and WebP that support transparency. If the source image does not support transparency, combine this filter with the `images.Process` filter: diff --git a/content/en/functions/images/Overlay.md b/content/en/functions/images/Overlay.md index d1cd7cf3f..8e5eec3d1 100644 --- a/content/en/functions/images/Overlay.md +++ b/content/en/functions/images/Overlay.md @@ -3,14 +3,11 @@ title: images.Overlay description: Returns an image filter that overlays the source image at the given coordinates, relative to the upper left corner. categories: [] keywords: [] -action: - aliases: [] - related: - - functions/images/Filter - - methods/resource/Filter - returnType: images.filter - signatures: [images.Overlay RESOURCE X Y] -toc: true +params: + functions_and_methods: + aliases: [] + returnType: images.filter + signatures: [images.Overlay RESOURCE X Y] --- ## Usage @@ -35,7 +32,7 @@ Create the filter: {{ $filter := images.Overlay $overlay 20 20 }} ``` -{{% include "functions/images/_common/apply-image-filter.md" %}} +{{% include "/_common/functions/images/apply-image-filter.md" %}} ## Example diff --git a/content/en/functions/images/Padding.md b/content/en/functions/images/Padding.md index e2c2695a1..da15a44ca 100644 --- a/content/en/functions/images/Padding.md +++ b/content/en/functions/images/Padding.md @@ -3,14 +3,11 @@ title: images.Padding description: Returns an image filter that resizes the image canvas without resizing the image. categories: [] keywords: [] -action: - aliases: [] - related: - - functions/images/Filter - - methods/resource/Filter - returnType: images.filter - signatures: ['images.Padding V1 [V2] [V3] [V4] [COLOR]'] -toc: true +params: + functions_and_methods: + aliases: [] + returnType: images.filter + signatures: ['images.Padding V1 [V2] [V3] [V4] [COLOR]'] --- {{< new-in 0.120.0 />}} @@ -28,7 +25,7 @@ Create the filter: {{ $filter := images.Padding 20 40 "#976941" }} ``` -{{% include "functions/images/_common/apply-image-filter.md" %}} +{{% include "/_common/functions/images/apply-image-filter.md" %}} Combine with the [`Colors`] method to create a border with one of the image's most dominant colors: diff --git a/content/en/functions/images/Pixelate.md b/content/en/functions/images/Pixelate.md index 2016877ed..954950c8b 100644 --- a/content/en/functions/images/Pixelate.md +++ b/content/en/functions/images/Pixelate.md @@ -3,14 +3,11 @@ title: images.Pixelate description: Returns an image filter that applies a pixelation effect to an image. categories: [] keywords: [] -action: - aliases: [] - related: - - functions/images/Filter - - methods/resource/Filter - returnType: images.filter - signatures: [images.Pixelate SIZE] -toc: true +params: + functions_and_methods: + aliases: [] + returnType: images.filter + signatures: [images.Pixelate SIZE] --- ## Usage @@ -21,7 +18,7 @@ Create the filter: {{ $filter := images.Pixelate 4 }} ``` -{{% include "functions/images/_common/apply-image-filter.md" %}} +{{% include "/_common/functions/images/apply-image-filter.md" %}} ## Example diff --git a/content/en/functions/images/Process.md b/content/en/functions/images/Process.md index 959770c65..134c40c5a 100644 --- a/content/en/functions/images/Process.md +++ b/content/en/functions/images/Process.md @@ -3,15 +3,11 @@ title: images.Process description: Returns an image filter that processes the given image using the given specification. categories: [] keywords: [] -action: - aliases: [] - related: - - functions/images/Filter - - methods/resource/Filter - - methods/resource/Process - returnType: images.filter - signatures: [images.Process SPEC] -toc: true +params: + functions_and_methods: + aliases: [] + returnType: images.filter + signatures: [images.Process SPEC] --- {{< new-in 0.119.0 />}} @@ -101,7 +97,7 @@ Create a filter: {{ $filter := images.Process "resize 256x q40 webp" }} ``` -{{% include "functions/images/_common/apply-image-filter.md" %}} +{{% include "/_common/functions/images/apply-image-filter.md" %}} ## Example diff --git a/content/en/functions/images/QR.md b/content/en/functions/images/QR.md index e3f914fd1..eee2dff14 100644 --- a/content/en/functions/images/QR.md +++ b/content/en/functions/images/QR.md @@ -2,13 +2,11 @@ title: images.QR description: Encodes the given text into a QR code using the specified options, returning an image resource. keywords: [] -action: - aliases: [] - related: [] - returnType: images.ImageResource - signatures: ['images.QR TEXT [OPTIONS]'] -toc: true -math: true +params: + functions_and_methods: + aliases: [] + returnType: images.ImageResource + signatures: ['images.QR TEXT [OPTIONS]'] --- {{< new-in 0.141.0 />}} @@ -21,19 +19,17 @@ The `images.QR` function encodes the given text into a [QR code] using the speci Although the default option values are sufficient for most applications, you should test the rendered QR code both on-screen and in print. -[QR code]: https://en.wikipedia.org/wiki/QR_code - ## Options level : (`string`) The error correction level to use when encoding the text, one of `low`, `medium`, `quartile`, or `high`. Default is `medium`. -Error correction level|Redundancy -:--|:--|:-- -low|20% -medium|38% -quartile|55% -high|65% + Error correction level|Redundancy + :--|:--|:-- + low|20% + medium|38% + quartile|55% + high|65% scale : (`int`) The number of image pixels per QR code module. Must be greater than or equal to `2`. Default is `4`. @@ -41,8 +37,6 @@ scale targetDir : (`string`) The subdirectory within the [`publishDir`] where Hugo will place the generated image. Use Unix-style slashes (`/`) to separarate path segments. If empty or not provided, the image is placed directly in the `publishDir` root. Hugo automatically creates the necessary subdirectories if they don't exist. -[`publishDir`]: /getting-started/configuration/#publishdir - ## Examples To create a QR code using the default values for `level` and `scale`: @@ -74,7 +68,7 @@ Specify `level`, `scale`, and `targetDir` as needed to achieve the desired resul To include a QR code that points to the `Permalink` of the current page: -{{< code file=layouts/_default/single.html >}} +```go-html-template {file="layouts/_default/single.html"} {{ with images.QR .Permalink }} {{ end }} -{{< /code >}} +``` Then hide the QR code with CSS unless printing the page: @@ -116,9 +110,8 @@ If the QR code will be printed, use the default `scale` value of `4` pixels per Avoid using Hugo's image processing methods to resize QR codes. Resizing can introduce blurring due to anti-aliasing when a QR code module occupies a fractional number of pixels. -{{% note %}} -Always test the rendered QR code both on-screen and in print. -{{% /note %}} +> [!note] +> Always test the rendered QR code both on-screen and in print. ## Shortcode @@ -140,4 +133,6 @@ https://gohugo.io The `qr` shortcode accepts several arguments including `level` and `scale`. See the [related documentation] for details. +[`publishDir`]: /configuration/all/#publishdir +[QR code]: https://en.wikipedia.org/wiki/QR_code [related documentation]: /shortcodes/qr/ diff --git a/content/en/functions/images/Saturation.md b/content/en/functions/images/Saturation.md index 118bd0213..d1dd48b24 100644 --- a/content/en/functions/images/Saturation.md +++ b/content/en/functions/images/Saturation.md @@ -3,14 +3,11 @@ title: images.Saturation description: Returns an image filter that changes the saturation of an image. categories: [] keywords: [] -action: - aliases: [] - related: - - functions/images/Filter - - methods/resource/Filter - returnType: images.filter - signatures: [images.Saturation PERCENTAGE] -toc: true +params: + functions_and_methods: + aliases: [] + returnType: images.filter + signatures: [images.Saturation PERCENTAGE] --- The percentage must be in the range [-100, 500] where 0 has no effect. @@ -23,7 +20,7 @@ Create the filter: {{ $filter := images.Saturation 65 }} ``` -{{% include "functions/images/_common/apply-image-filter.md" %}} +{{% include "/_common/functions/images/apply-image-filter.md" %}} ## Example diff --git a/content/en/functions/images/Sepia.md b/content/en/functions/images/Sepia.md index 9f0b7adfb..ae43045db 100644 --- a/content/en/functions/images/Sepia.md +++ b/content/en/functions/images/Sepia.md @@ -3,14 +3,11 @@ title: images.Sepia description: Returns an image filter that produces a sepia-toned version of an image. categories: [] keywords: [] -action: - aliases: [] - related: - - functions/images/Filter - - methods/resource/Filter - returnType: images.filter - signatures: [images.Sepia PERCENTAGE] -toc: true +params: + functions_and_methods: + aliases: [] + returnType: images.filter + signatures: [images.Sepia PERCENTAGE] --- The percentage must be in the range [0, 100] where 0 has no effect. @@ -23,7 +20,7 @@ Create the filter: {{ $filter := images.Sepia 75 }} ``` -{{% include "functions/images/_common/apply-image-filter.md" %}} +{{% include "/_common/functions/images/apply-image-filter.md" %}} ## Example diff --git a/content/en/functions/images/Sigmoid.md b/content/en/functions/images/Sigmoid.md index 32765f923..9bfcaf91b 100644 --- a/content/en/functions/images/Sigmoid.md +++ b/content/en/functions/images/Sigmoid.md @@ -3,14 +3,11 @@ title: images.Sigmoid description: Returns an image filter that changes the contrast of an image using a sigmoidal function. categories: [] keywords: [] -action: - aliases: [] - related: - - functions/images/Filter - - methods/resource/Filter - returnType: images.filter - signatures: [images.Sigmoid MIDPOINT FACTOR] -toc: true +params: + functions_and_methods: + aliases: [] + returnType: images.filter + signatures: [images.Sigmoid MIDPOINT FACTOR] --- This is a non-linear contrast change useful for photo adjustments; it preserves highlight and shadow detail. @@ -27,7 +24,7 @@ Create the filter: {{ $filter := images.Sigmoid 0.6 -4 }} ``` -{{% include "functions/images/_common/apply-image-filter.md" %}} +{{% include "/_common/functions/images/apply-image-filter.md" %}} ## Example diff --git a/content/en/functions/images/Text.md b/content/en/functions/images/Text.md index c8d23565c..94cdb4e9d 100644 --- a/content/en/functions/images/Text.md +++ b/content/en/functions/images/Text.md @@ -3,14 +3,11 @@ title: images.Text description: Returns an image filter that adds text to an image. categories: [] keywords: [] -action: - aliases: [] - related: - - functions/images/Filter - - methods/resource/Filter - returnType: images.filter - signatures: ['images.Text TEXT [OPTIONS]'] -toc: true +params: + functions_and_methods: + aliases: [] + returnType: images.filter + signatures: ['images.Text TEXT [OPTIONS]'] --- ## Options @@ -18,7 +15,7 @@ toc: true Although none of the options are required, at a minimum you will want to set the `size` to be some reasonable percentage of the image height. alignx - {{< new-in 0.141.0 />}} +: {{< new-in 0.141.0 />}} : (`string`) The horizontal alignment of the text relative to the horizontal offset, one of `left`, `center`, or `right`. Default is `left`. color @@ -27,8 +24,6 @@ color font : (`resource.Resource`) The font can be a [global resource](g), a [page resource](g), or a [remote resource](g). Default is [Go Regular], a proportional sans-serif TrueType font. -[Go Regular]: https://go.dev/blog/go-fonts#sans-serif - linespacing : (`int`) The number of pixels between each line. For a line height of 1.4, set the `linespacing` to 0.4 multiplied by the `size`. Default is `2`. @@ -41,6 +36,8 @@ x y : (`int`) The vertical offset, in pixels, relative to the top of the image. Default is `10`. +[Go Regular]: https://go.dev/blog/go-fonts#sans-serif + ## Usage Set the text and paths: diff --git a/content/en/functions/images/UnsharpMask.md b/content/en/functions/images/UnsharpMask.md index 9ea58f2b6..9c06eb5e1 100644 --- a/content/en/functions/images/UnsharpMask.md +++ b/content/en/functions/images/UnsharpMask.md @@ -3,14 +3,11 @@ title: images.UnsharpMask description: Returns an image filter that sharpens an image. categories: [] keywords: [] -action: - aliases: [] - related: - - functions/images/Filter - - methods/resource/Filter - returnType: images.filter - signatures: [images.UnsharpMask SIGMA AMOUNT THRESHOLD] -toc: true +params: + functions_and_methods: + aliases: [] + returnType: images.filter + signatures: [images.UnsharpMask SIGMA AMOUNT THRESHOLD] --- The sigma argument is used in a gaussian function and affects the radius of effect. Sigma must be positive. The sharpen radius is approximately 3 times the sigma value. @@ -27,7 +24,7 @@ Create the filter: {{ $filter := images.UnsharpMask 10 0.4 0.03 }} ``` -{{% include "functions/images/_common/apply-image-filter.md" %}} +{{% include "/_common/functions/images/apply-image-filter.md" %}} ## Example diff --git a/content/en/functions/images/_common/_index.md b/content/en/functions/images/_common/_index.md deleted file mode 100644 index 4328d4d14..000000000 --- a/content/en/functions/images/_common/_index.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -cascade: - _build: - list: never - publishResources: false - render: never ---- - - diff --git a/content/en/functions/images/_index.md b/content/en/functions/images/_index.md index 13542ea73..f92e16e7a 100644 --- a/content/en/functions/images/_index.md +++ b/content/en/functions/images/_index.md @@ -4,9 +4,4 @@ linkTitle: images description: Use these functions to create an image filter, apply an image filter to an image, and to retrieve image information. categories: [] keywords: [] -menu: - docs: - parent: functions --- - -Use these functions to create an image filter, apply an image filter to an image, and to retrieve image information. diff --git a/content/en/functions/inflect/Humanize.md b/content/en/functions/inflect/Humanize.md index 71b4a5fd2..d3d785243 100644 --- a/content/en/functions/inflect/Humanize.md +++ b/content/en/functions/inflect/Humanize.md @@ -3,13 +3,11 @@ title: inflect.Humanize description: Returns the humanized version of the input with the first letter capitalized. categories: [] keywords: [] -action: - aliases: [humanize] - related: - - functions/inflect/Pluralize - - functions/inflect/Singularize - returnType: string - signatures: [inflect.Humanize INPUT] +params: + functions_and_methods: + aliases: [humanize] + returnType: string + signatures: [inflect.Humanize INPUT] aliases: [/functions/humanize] --- diff --git a/content/en/functions/inflect/Pluralize.md b/content/en/functions/inflect/Pluralize.md index c25f89617..f168770d3 100644 --- a/content/en/functions/inflect/Pluralize.md +++ b/content/en/functions/inflect/Pluralize.md @@ -3,13 +3,11 @@ title: inflect.Pluralize description: Pluralizes the given word according to a set of common English pluralization rules. categories: [] keywords: [] -action: - aliases: [pluralize] - related: - - functions/inflect/Humanize - - functions/inflect/Singularize - returnType: string - signatures: [inflect.Pluralize INPUT] +params: + functions_and_methods: + aliases: [pluralize] + returnType: string + signatures: [inflect.Pluralize INPUT] aliases: [/functions/pluralize] --- diff --git a/content/en/functions/inflect/Singularize.md b/content/en/functions/inflect/Singularize.md index d2a8572f6..41e05b784 100644 --- a/content/en/functions/inflect/Singularize.md +++ b/content/en/functions/inflect/Singularize.md @@ -3,13 +3,11 @@ title: inflect.Singularize description: Singularizes the given word according to a set of common English singularization rules. categories: [] keywords: [] -action: - aliases: [singularize] - related: - - functions/inflect/Humanize - - functions/inflect/Pluralize - returnType: string - signatures: [inflect.Singularize INPUT] +params: + functions_and_methods: + aliases: [singularize] + returnType: string + signatures: [inflect.Singularize INPUT] aliases: [/functions/singularize] --- diff --git a/content/en/functions/inflect/_index.md b/content/en/functions/inflect/_index.md index 601b409e6..2afe4fe33 100644 --- a/content/en/functions/inflect/_index.md +++ b/content/en/functions/inflect/_index.md @@ -1,12 +1,7 @@ --- title: Inflect functions linkTitle: inflect -description: Template functions to inflect English nouns. +description: These functions provide word inflection features such as singularization and pluralization of English nouns. categories: [] keywords: [] -menu: - docs: - parent: functions --- - -These functions provide word inflection features such as singularization and pluralization of English nouns. diff --git a/content/en/functions/js/Babel.md b/content/en/functions/js/Babel.md index 08bce47e5..d0007aaa0 100644 --- a/content/en/functions/js/Babel.md +++ b/content/en/functions/js/Babel.md @@ -3,17 +3,11 @@ title: js.Babel description: Compile the given JavaScript resource with Babel. categories: [] keywords: [] -action: - aliases: [babel] - related: - - functions/js/Batch - - functions/js/Build - - functions/resources/Fingerprint - - functions/resources/Minify - returnType: resource.Resource - signatures: ['js.Babel [OPTIONS] RESOURCE'] -weight: 30 -toc: true +params: + functions_and_methods: + aliases: [babel] + returnType: resource.Resource + signatures: ['js.Babel [OPTIONS] RESOURCE'] --- ```go-html-template @@ -37,18 +31,21 @@ toc: true ## Setup -Step 1 -: Install [Node.js](https://nodejs.org/en/download) +### Step 1 -Step 2 -: Install the required Node.js packages in the root of your project. +Install [Node.js](https://nodejs.org/en/download) + +### Step 2 + +Install the required Node.js packages in the root of your project. ```sh npm install --save-dev @babel/core @babel/cli ``` -Step 3 -: Add the babel executable to Hugo's `security.exec.allow` list in your site configuration: +### Step 3 + +Add the babel executable to Hugo's `security.exec.allow` list in your site configuration: {{< code-toggle file=hugo >}} [security.exec] @@ -75,32 +72,28 @@ module.exports = { ## Options -###### compact +compact +: (`bool`) Whether to remove optional newlines and whitespace. Enabled when `minified` is `true`. Default is `false` -(`bool`) Whether to remove optional newlines and whitespace. Enabled when `minified` is `true`. Default is `false` +config +: (`string`) Path to the Babel configuration file. Hugo will, by default, look for a `babel.config.js` file in the root of your project. See [details](https://babeljs.io/docs/en/configuration). -###### config +minified +: (`bool`) Whether to minify the compiled code. Enables the `compact` option. Default is `false`. -(`string`) Path to the Babel configuration file. Hugo will, by default, look for a `babel.config.js` file in the root of your project. See [details](https://babeljs.io/docs/en/configuration). +noBabelrc +: (`string`) Whether to ignore `.babelrc` and `.babelignore` files. Default is `false`. -###### minified +noComments +: (`bool`) Whether to remove comments. Default is `false`. -(`bool`) Whether to minify the compiled code. Enables the `compact` option. Default is `false`. +sourceMap +: (`string`) Whether to generate source maps, one of `external`, `inline`, or `none`. Default is `none`. -###### noBabelrc +verbose +: (`bool`) Whether to enable verbose logging. Default is `false` -(`string`) Whether to ignore `.babelrc` and `.babelignore` files. Default is `false`. - -###### noComments - -(`bool`) Whether to remove comments. Default is `false`. - -###### sourceMap - -(`string`) Whether to generate source maps, one of `external`, `inline`, or `none`. Default is `none`. - - - -###### verbose - -(`bool`) Whether to enable verbose logging. Default is `false` + diff --git a/content/en/functions/js/Batch.md b/content/en/functions/js/Batch.md index 08913f61f..a2c8bb893 100644 --- a/content/en/functions/js/Batch.md +++ b/content/en/functions/js/Batch.md @@ -3,40 +3,33 @@ title: js.Batch description: Build JavaScript bundle groups with global code splitting and flexible hooks/runners setup. categories: [] keywords: [] -action: - aliases: [] - related: - - functions/js/Build - - functions/js/Babel - - functions/resources/Fingerprint - - functions/resources/Minify - returnType: js.Batcher - signatures: ['js.Batch [ID]'] -weight: 20 -toc: true +params: + functions_and_methods: + aliases: [] + returnType: js.Batcher + signatures: ['js.Batch [ID]'] --- -{{% note %}} -For a runnable example of this feature, see [this test and demo repo](https://github.com/bep/hugojsbatchdemo/). -{{% /note %}} +> [!note] +> For a runnable example of this feature, see [this test and demo repo](https://github.com/bep/hugojsbatchdemo/). The Batch `ID` is used to create the base directory for this batch. Forward slashes are allowed. `js.Batch` returns an object with an API with this structure: -* [Group] - * [Script] - * [SetOptions] - * [Instance] - * [SetOptions] - * [Runner] - * [SetOptions] - * [Config] - * [SetOptions] +- [Group] + - [Script] + - [SetOptions] + - [Instance] + - [SetOptions] + - [Runner] + - [SetOptions] + - [Config] + - [SetOptions] ## Group The `Group` method take an `ID` (`string`) as argument. No slashes. It returns an object with these methods: -#### Script +### Script The `Script` method takes an `ID` (`string`) as argument. No slashes. It returns an [OptionsSetter] that can be used to set [script options] for this script. @@ -50,9 +43,9 @@ The `Script` method takes an `ID` (`string`) as argument. No slashes. It returns {{ end }} ``` -`SetOptions` takes a [script options] map. Note that if you want the script to be handled by a [runner], you need to set the `export` option to match what you want to pass on to the runner (default is `*`). +`SetOptions` takes a [script options] map. Note that if you want the script to be handled by a [runner], you need to set the `export` option to match what you want to pass on to the runner (default is `*`). -#### Instance +### Instance The `Instance` method takes two `string` arguments `SCRIPT_ID` and `INSTANCE_ID`. No slashes. It returns an [OptionsSetter] that can be used to set [params options] for this instance. @@ -68,7 +61,7 @@ The `Instance` method takes two `string` arguments `SCRIPT_ID` and `INSTANCE_ID` `SetOptions` takes a [params options] map. The instance options will be passed to any [runner] script in the same group, as JSON. -#### Runner +### Runner The `Runner` method takes an `ID` (`string`) as argument. No slashes. It returns an [OptionsSetter] that can be used to set [script options] for this runner. @@ -131,34 +124,34 @@ import * as ReactDOM from 'react-dom/client'; import * as React from 'react'; export default function Run(group) { - console.log('Running react-create-elements.js', group); - const scripts = group.scripts; - for (const script of scripts) { - for (const instance of script.instances) { - /* This is a convention in this project. */ - let elId = `${script.id}-${instance.id}`; - let el = document.getElementById(elId); - if (!el) { - console.warn(`Element with id ${elId} not found`); - continue; - } - const root = ReactDOM.createRoot(el); - const reactEl = React.createElement(script.binding, instance.params); - root.render(reactEl); - } - } + console.log('Running react-create-elements.js', group); + const scripts = group.scripts; + for (const script of scripts) { + for (const instance of script.instances) { + /* This is a convention in this project. */ + let elId = `${script.id}-${instance.id}`; + let el = document.getElementById(elId); + if (!el) { + console.warn(`Element with id ${elId} not found`); + continue; + } + const root = ReactDOM.createRoot(el); + const reactEl = React.createElement(script.binding, instance.params); + root.render(reactEl); + } + } } ``` -#### Config +### Config Returns an [OptionsSetter] that can be used to set [build options] for the batch. These are mostly the same as for `js.Build`, but note that: -* `targetPath` is set automatically (there may be multiple outputs). -* `format` must be `esm`, currently the only format supporting [code splitting]. -* `params` will be available in the `@params/config` namespace in the scripts. This way you can import both the [script] or [runner] params and the [config] params with: +- `targetPath` is set automatically (there may be multiple outputs). +- ``format` must be `esm`, currently the only format supporting [code splitting]. +- ``params` will be available in the `@params/config` namespace in the scripts. This way you can import both the [script] or [runner] params and the [config] params with: ```js import * as params from "@params"; @@ -185,14 +178,14 @@ Setting the `Config` for a batch can be done from any template (including shortc ## Options -### Build Options +### Build options format -: (`string`) Currently only `esm` is supported in [ESBuild's code splitting]. +: (`string`) Currently only `esm` is supported in ESBuild's [code splitting]. -{{% include "./_common/options.md" %}} +{{% include "/_common/functions/js/options.md" %}} -### Script Options +### Script options resource : The resource to build. This can be a file resource or a virtual resource. @@ -205,18 +198,17 @@ importContext params : A map of parameters that will be passed to the script as JSON. These gets bound to the `@params` namespace: -```js -import * as params from '@params'; -``` -### Script Options + ```js + import * as params from '@params'; + ``` -### Params Options +### Params options params -: A map of parameters that will be passed to the script as JSON. +: A map of parameters that will be passed to the script as JSON. -### Import Context +### Import context Hugo will, by default, first try to resolve any import in [assets](/hugo-pipes/introduction/#asset-directory) and, if not found, let [ESBuild] resolve it (e.g. from `node_modules`). The `importContext` option can be used to set the first context for resolving imports. A common use of this is to resolve imports inside a [page bundle](/content-management/page-bundles/). @@ -243,20 +235,17 @@ An `OptionsSetter` is a special object that is returned once only. This means th The `Build` method returns an object with the following structure: -* Groups (map) - * [`Resources`] +- Groups (map) + - [`Resources`] -Eeach [`Resource`] will be of media type `application/javascript` or `text/css`. +Each [`Resource`] will be of media type `application/javascript` or `text/css`. - In a template you would typically handle one group with a given `ID` (e.g. scripts for the current section). Because of the concurrent build, this needs to be done in a [`templates.Defer`] block: +In a template you would typically handle one group with a given `ID` (e.g. scripts for the current section). Because of the concurrent build, this needs to be done in a [`templates.Defer`] block: -{{% note %}} -The [`templates.Defer`] acts as a synchronisation point to handle scripts added concurrently by different templates. If you have a setup with where the batch is created in one go (in one template), you don't need it. - -See [this discussion](https://discourse.gohugo.io/t/js-batch-with-simple-global-script/53002/5?u=bep) for more. - -[`templates.Defer`]: /functions/templates/defer/ -{{% /note %}} +> [!note] +> The [`templates.Defer`] acts as a synchronisation point to handle scripts added concurrently by different templates. If you have a setup with where the batch is created in one go (in one template), you don't need it. +> +> See [this discussion](https://discourse.gohugo.io/t/js-batch-with-simple-global-script/53002/5?u=bep) for more. ```go-html-template {{ $group := .group }} @@ -279,10 +268,10 @@ See [this discussion](https://discourse.gohugo.io/t/js-batch-with-simple-global- ## Known Issues -In the official documentation for [ESBuild's code splitting], there's a warning note in the header. The two issues are: +In the official documentation for ESBuild's [code splitting], there's a warning note in the header. The two issues are: -* `esm` is currently the only implemented output format. This means that it will not work for very old browsers. See [caniuse](https://caniuse.com/?search=ESM). -* There's a known import ordering issue. + - `esm` is currently the only implemented output format. This means that it will not work for very old browsers. See [caniuse](https://caniuse.com/?search=ESM). + - There's a known import ordering issue. We have not seen the ordering issue as a problem during our [extensive testing](https://github.com/bep/hugojsbatchdemo) of this new feature with different libraries. There are two main cases: @@ -296,28 +285,23 @@ import './lib2.js'; import './lib1.js'; console.log('entrypoints-workaround.js'); - ``` -[build options]: #build-options [`Resource`]: /methods/resource/ -[`Resources`]: /methods/page/resources/ [`Resources.Mount`]: /methods/page/resources/#mount +[`Resources`]: /methods/page/resources/ [`templates.Defer`]: /functions/templates/defer/ +[`templates.Defer`]: /functions/templates/defer/ +[build options]: #build-options [code splitting]: https://esbuild.github.io/api/#splitting [config]: #config -[ESBuild's code splitting]: https://esbuild.github.io/api/#splitting [ESBuild]: https://github.com/evanw/esbuild -[group]: #group -[instance]: #instance [JavaScript import]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/import [js.Batch Demo Repo]: https://github.com/bep/hugojsbatchdemo/ -[map]: /functions/collections/dictionary/ [OptionsSetter]: #optionssetter -[page bundles]: /content-management/page-bundles/ [params options]: #params-options [runner]: #runner -[script options]: #script-options [script]: #script +[script options]: #script-options [SetOptions]: #optionssetter [with]: /functions/go-template/with/ diff --git a/content/en/functions/js/Build.md b/content/en/functions/js/Build.md index 9bdc2454a..1bec6b16f 100644 --- a/content/en/functions/js/Build.md +++ b/content/en/functions/js/Build.md @@ -3,17 +3,11 @@ title: js.Build description: Bundle, transpile, tree shake, and minify JavaScript resources. categories: [] keywords: [] -action: - aliases: [] - related: - - functions/js/Batch - - functions/js/Babel - - functions/resources/Fingerprint - - functions/resources/Minify - returnType: resource.Resource - signatures: ['js.Build [OPTIONS] RESOURCE'] -weight: 10 -toc: true +params: + functions_and_methods: + aliases: [] + returnType: resource.Resource + signatures: ['js.Build [OPTIONS] RESOURCE'] --- The `js.Build` function uses the [evanw/esbuild] package to: @@ -24,8 +18,6 @@ The `js.Build` function uses the [evanw/esbuild] package to: - Minify - Create source maps -[evanw/esbuild]: https://github.com/evanw/esbuild - ```go-html-template {{ with resources.Get "js/main.js" }} {{ $opts := dict @@ -47,16 +39,13 @@ The `js.Build` function uses the [evanw/esbuild] package to: ## Options -###### targetPath +targetPath +: (`string`) If not set, the source path will be used as the base target path. Note that the target path's extension may change if the target MIME type is different, e.g. when the source is TypeScript. -(`string`) If not set, the source path will be used as the base target path. -Note that the target path's extension may change if the target MIME type is different, e.g. when the source is TypeScript. +format +: (`string`) The output format. One of: `iife`, `cjs`, `esm`. Default is `iife`, a self-executing function, suitable for inclusion as a ` ``` + +[evanw/esbuild]: https://github.com/evanw/esbuild diff --git a/content/en/functions/js/_common/_index.md b/content/en/functions/js/_common/_index.md deleted file mode 100644 index 4328d4d14..000000000 --- a/content/en/functions/js/_common/_index.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -cascade: - _build: - list: never - publishResources: false - render: never ---- - - diff --git a/content/en/functions/js/_common/options.md b/content/en/functions/js/_common/options.md deleted file mode 100644 index e2b6566ad..000000000 --- a/content/en/functions/js/_common/options.md +++ /dev/null @@ -1,121 +0,0 @@ ---- -_comment: Do not remove front matter. ---- - -###### params - -(`map` or `slice`) Params that can be imported as JSON in your JS files, e.g. - -```go-html-template -{{ $js := resources.Get "js/main.js" | js.Build (dict "params" (dict "api" "https://example.org/api")) }} -``` -And then in your JS file: - -```js -import * as params from '@params'; -``` - -Note that this is meant for small data sets, e.g. configuration settings. For larger data, please put/mount the files into `assets` and import them directly. - -###### minify - -(`bool`) Let `js.Build` handle the minification. - -###### loaders - -{{< new-in 0.140.0 />}} - -(`map`) Configuring a loader for a given file type lets you load that file type with an import statement or a require call. For example configuring the .png file extension to use the data URL loader means importing a .png file gives you a data URLcontaining the contents of that image. Loaders available are `none`, `base64`, `binary`, `copy`, `css`, `dataurl`, `default`, `empty`, `file`, `global-css`, `js`, `json`, `jsx`, `local-css`, `text`, `ts`, `tsx`. See https://esbuild.github.io/api/#loader. - -###### inject - -(`slice`) This option allows you to automatically replace a global variable with an import from another file. The path names must be relative to `assets`. See https://esbuild.github.io/api/#inject. - -###### shims - -(`map`) This option allows swapping out a component with another. A common use case is to load dependencies like React from a CDN (with _shims_) when in production, but running with the full bundled `node_modules` dependency during development: - -```go-html-template -{{ $shims := dict "react" "js/shims/react.js" "react-dom" "js/shims/react-dom.js" }} -{{ $js = $js | js.Build dict "shims" $shims }} -``` - -The _shim_ files may look like these: - -```js -// js/shims/react.js -module.exports = window.React; -``` - -```js -// js/shims/react-dom.js -module.exports = window.ReactDOM; -``` - -With the above, these imports should work in both scenarios: - -```js -import * as React from 'react'; -import * as ReactDOM from 'react-dom/client'; -``` - -###### target - -(`string`) The language target. One of: `es5`, `es2015`, `es2016`, `es2017`, `es2018`, `es2019`, `es2020` or `esnext`. Default is `esnext`. - -###### platform - -{{< new-in 0.140.0 />}} - -(`string`) One of `browser`, `node`, `neutral`. Default is `browser`. See https://esbuild.github.io/api/#platform. - -###### externals - -(`slice`) External dependencies. Use this to trim dependencies you know will never be executed. See https://esbuild.github.io/api/#external. - -###### defines - -(`map`) Allow to define a set of string replacement to be performed when building. Should be a map where each key is to be replaced by its value. - -```go-html-template -{{ $defines := dict "process.env.NODE_ENV" `"development"` }} -``` - -###### sourceMap - -(`string`) Whether to generate `inline`, `linked` or `external` source maps from esbuild. Linked and external source maps will be written to the target with the output file name + ".map". When `linked` a `sourceMappingURL` will also be written to the output file. By default, source maps are not created. Note that the `linked` option was added in Hugo 0.140.0. - -###### sourcesContent - -{{< new-in 0.140.0 />}} - -(`bool`) Whether to include the content of the source files in the source map. By default, this is `true`. - -###### JSX - -{{< new-in 0.124.0 />}} - -(`string`) How to handle/transform JSX syntax. One of: `transform`, `preserve`, `automatic`. Default is `transform`. Notably, the `automatic` transform was introduced in React 17+ and will cause the necessary JSX helper functions to be imported automatically. See https://esbuild.github.io/api/#jsx. - -###### JSXImportSource - -{{< new-in 0.124.0 />}} - -(`string`) Which library to use to automatically import its JSX helper functions from. This only works if `JSX` is set to `automatic`. The specified library needs to be installed through npm and expose certain exports. See https://esbuild.github.io/api/#jsx-import-source. - -The combination of `JSX` and `JSXImportSource` is helpful if you want to use a non-React JSX library like Preact, e.g.: - -```go-html-template -{{ $js := resources.Get "js/main.jsx" | js.Build (dict "JSX" "automatic" "JSXImportSource" "preact") }} -``` - -With the above, you can use Preact components and JSX without having to manually import `h` and `Fragment` every time: - -```jsx -import { render } from 'preact'; - -const App = () => <>Hello world!; - -const container = document.getElementById('app'); -if (container) render(, container); -``` diff --git a/content/en/functions/js/_index.md b/content/en/functions/js/_index.md index 3356e7c7b..d3557a2d3 100644 --- a/content/en/functions/js/_index.md +++ b/content/en/functions/js/_index.md @@ -1,12 +1,7 @@ --- title: JavaScript functions linkTitle: js -description: Template functions to work with JavaScript and TypeScript files. +description: Use these functions to work with JavaScript and TypeScript files. categories: [] keywords: [] -menu: - docs: - parent: functions --- - -Use these functions to work with JavaScript and TypeScript files. diff --git a/content/en/functions/lang/FormatAccounting.md b/content/en/functions/lang/FormatAccounting.md index 70365c216..d2a1d76f6 100644 --- a/content/en/functions/lang/FormatAccounting.md +++ b/content/en/functions/lang/FormatAccounting.md @@ -3,19 +3,15 @@ title: lang.FormatAccounting description: Returns a currency representation of a number for the given currency and precision for the current language and region in accounting notation. categories: [] keywords: [] -action: - aliases: [] - related: - - functions/lang/FormatCurrency - - functions/lang/FormatNumber - - functions/lang/FormatNumberCustom - - functions/lang/FormatPercent - returnType: string - signatures: [lang.FormatAccounting PRECISION CURRENCY NUMBER] +params: + functions_and_methods: + aliases: [] + returnType: string + signatures: [lang.FormatAccounting PRECISION CURRENCY NUMBER] --- ```go-html-template {{ 512.5032 | lang.FormatAccounting 2 "NOK" }} → NOK512.50 ``` -{{% include "functions/_common/locales.md" %}} +{{% include "/_common/functions/locales.md" %}} diff --git a/content/en/functions/lang/FormatCurrency.md b/content/en/functions/lang/FormatCurrency.md index bd83c2ec5..327413c07 100644 --- a/content/en/functions/lang/FormatCurrency.md +++ b/content/en/functions/lang/FormatCurrency.md @@ -3,19 +3,15 @@ title: lang.FormatCurrency description: Returns a currency representation of a number for the given currency and precision for the current language and region. categories: [] keywords: [] -action: - aliases: [] - related: - - functions/lang/FormatAccounting - - functions/lang/FormatNumber - - functions/lang/FormatNumberCustom - - functions/lang/FormatPercent - returnType: string - signatures: [lang.FormatCurrency PRECISION CURRENCY NUMBER] +params: + functions_and_methods: + aliases: [] + returnType: string + signatures: [lang.FormatCurrency PRECISION CURRENCY NUMBER] --- ```go-html-template {{ 512.5032 | lang.FormatCurrency 2 "USD" }} → $512.50 ``` -{{% include "functions/_common/locales.md" %}} +{{% include "/_common/functions/locales.md" %}} diff --git a/content/en/functions/lang/FormatNumber.md b/content/en/functions/lang/FormatNumber.md index 597df742a..5bf37996a 100644 --- a/content/en/functions/lang/FormatNumber.md +++ b/content/en/functions/lang/FormatNumber.md @@ -3,19 +3,15 @@ title: lang.FormatNumber description: Returns a numeric representation of a number with the given precision for the current language and region. categories: [] keywords: [] -action: - aliases: [] - related: - - functions/lang/FormatAccounting - - functions/lang/FormatCurrency - - functions/lang/FormatNumberCustom - - functions/lang/FormatPercent - returnType: string - signatures: [lang.FormatNumber PRECISION NUMBER] +params: + functions_and_methods: + aliases: [] + returnType: string + signatures: [lang.FormatNumber PRECISION NUMBER] --- ```go-html-template {{ 512.5032 | lang.FormatNumber 2 }} → 512.50 ``` -{{% include "functions/_common/locales.md" %}} +{{% include "/_common/functions/locales.md" %}} diff --git a/content/en/functions/lang/FormatNumberCustom.md b/content/en/functions/lang/FormatNumberCustom.md index 603f42087..0a70cd938 100644 --- a/content/en/functions/lang/FormatNumberCustom.md +++ b/content/en/functions/lang/FormatNumberCustom.md @@ -3,15 +3,11 @@ title: lang.FormatNumberCustom description: Returns a numeric representation of a number with the given precision using negative, decimal, and grouping options. categories: [] keywords: [] -action: - aliases: [] - related: - - functions/lang/FormatAccounting - - functions/lang/FormatCurrency - - functions/lang/FormatNumber - - functions/lang/FormatPercent - returnType: string - signatures: ['lang.FormatNumberCustom PRECISION NUMBER [OPTIONS...]'] +params: + functions_and_methods: + aliases: [] + returnType: string + signatures: ['lang.FormatNumberCustom PRECISION NUMBER [OPTIONS...]'] aliases: ['/functions/numfmt/'] --- @@ -29,6 +25,6 @@ For a simpler function that adapts to the current language, see [`lang.FormatNum {{ lang.FormatNumberCustom 0 -12345.6789 "-|.| " "|" }} → -12 346 ``` -{{% include "functions/_common/locales.md" %}} +{{% include "/_common/functions/locales.md" %}} [`lang.FormatNumber`]: /functions/lang/formatnumber/ diff --git a/content/en/functions/lang/FormatPercent.md b/content/en/functions/lang/FormatPercent.md index 529ada67b..aef1fb64c 100644 --- a/content/en/functions/lang/FormatPercent.md +++ b/content/en/functions/lang/FormatPercent.md @@ -3,19 +3,15 @@ title: lang.FormatPercent description: Returns a percentage representation of a number with the given precision for the current language and region. categories: [] keywords: [] -action: - aliases: [] - related: - - functions/lang/FormatAccounting - - functions/lang/FormatCurrency - - functions/lang/FormatNumber - - functions/lang/FormatNumberCustom - returnType: string - signatures: [lang.FormatPercent PRECISION NUMBER] +params: + functions_and_methods: + aliases: [] + returnType: string + signatures: [lang.FormatPercent PRECISION NUMBER] --- ```go-html-template {{ 512.5032 | lang.FormatPercent 2 }} → 512.50% ``` -{{% include "functions/_common/locales.md" %}} +{{% include "/_common/functions/locales.md" %}} diff --git a/content/en/functions/lang/Merge.md b/content/en/functions/lang/Merge.md index 75f5cdf01..db40c2669 100644 --- a/content/en/functions/lang/Merge.md +++ b/content/en/functions/lang/Merge.md @@ -3,11 +3,11 @@ title: lang.Merge description: Merge missing translations from other languages. categories: [] keywords: [] -action: - aliases: [] - related: [] - returnType: any - signatures: [lang.Merge FROM TO] +params: + functions_and_methods: + aliases: [] + returnType: any + signatures: [lang.Merge FROM TO] aliases: [/functions/lang.merge] --- diff --git a/content/en/functions/lang/Translate.md b/content/en/functions/lang/Translate.md index 48c1345e2..00bb0e3f3 100644 --- a/content/en/functions/lang/Translate.md +++ b/content/en/functions/lang/Translate.md @@ -3,31 +3,24 @@ title: lang.Translate description: Translates a string using the translation tables in the i18n directory. categories: [] keywords: [] -action: - aliases: [T, i18n] - related: [] - returnType: string - signatures: ['lang.Translate KEY [CONTEXT]'] -toc: true +params: + functions_and_methods: + aliases: [T, i18n] + returnType: string + signatures: ['lang.Translate KEY [CONTEXT]'] aliases: [/functions/i18n] --- -The `lang.Translate` function returns the value associated with given key as defined in the translation table for the current language. +The `lang.Translate` function returns the value associated with given key as defined in the translation table for the current language. If the key is not found in the translation table for the current language, the `lang.Translate` function falls back to the translation table for the [`defaultContentLanguage`]. -[`defaultContentLanguage`]: /getting-started/configuration/#defaultcontentlanguage - 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, use the `--printI18nWarnings` flag when building your site. - -To render placeholders for missing and fallback translations, set -[`enableMissingTranslationPlaceholders`] to `true` in your site configuration. - -[`enableMissingTranslationPlaceholders`]: /getting-started/configuration/#enablemissingtranslationplaceholders -{{% /note %}} +> [!note] +> To list missing and fallback translations, use the `--printI18nWarnings` flag when building your site. +> +> To render placeholders for missing and fallback translations, set [`enableMissingTranslationPlaceholders`] to `true` in your site configuration. ## Translation tables @@ -38,7 +31,7 @@ i18n/en.toml i18n/en-US.toml ``` -The base name must match the language key as defined in your site configuration. +The base name must match the [language key] as defined in your site configuration. 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: @@ -47,10 +40,8 @@ i18n/art-x-hugolang.toml i18n/hugolang.toml ``` -Private use subtags must not exceed 8 alphanumeric characters. - -[RFC 5646]: https://datatracker.ietf.org/doc/html/rfc5646 -[RFC 5646 § 2.2.7]: https://datatracker.ietf.org/doc/html/rfc5646#section-2.2.7 +> [!note] +> Private use subtags must not exceed 8 alphanumeric characters. ## Simple translations @@ -76,9 +67,8 @@ privacy = 'prywatność' security = 'bezpieczeństwo' {{< /code-toggle >}} -{{% note %}} -The examples below use the `T` alias for brevity. -{{% /note %}} +> [!note] +> The examples below use the `T` alias for brevity. When viewing the English language site: @@ -106,8 +96,6 @@ i18n/ The Unicode [CLDR Plural Rules chart] describes the pluralization categories for each language. -[CLDR Plural Rules chart]: https://www.unicode.org/cldr/charts/43/supplemental/language_plural_rules.html - The English translation table: {{< code-toggle file=i18n/en >}} @@ -136,9 +124,8 @@ many = '{{ . }} miesięcy' other = '{{ . }} miesiąca' {{< /code-toggle >}} -{{% note %}} -The examples below use the `T` alias for brevity. -{{% /note %}} +> [!note] +> The examples below use the `T` alias for brevity. When viewing the English language site: @@ -185,16 +172,13 @@ Template code: {{ T "age" (dict "name" "John" "count" 3) }} → John is 3 years old. ``` -{{% note %}} -Translation tables may contain both simple translations and translations with pluralization. -{{% /note %}} +> [!note] +> Translation tables may contain both simple translations and translations with pluralization. ## Reserved keys Hugo uses the [go-i18n] package to look up values in translation tables. This package reserves the following keys for internal use: -[go-i18n]: https://github.com/nicksnyder/go-i18n - id : (`string`) Uniquely identifies the message. @@ -228,8 +212,6 @@ many other : (`string`) The content of the message for the [CLDR] plural form "other". -[CLDR]: https://www.unicode.org/cldr/charts/43/supplemental/language_plural_rules.html - If you need to provide a translation for one of the reserved keys, you can prepend the word with an underscore. For example: {{< code-toggle file=i18n/es >}} @@ -253,3 +235,12 @@ Then in your templates: {{ T "_zero" }} → cero {{ T "_other" }} → otro ``` + +[`defaultContentLanguage`]: /configuration/all/#defaultcontentlanguage +[`enableMissingTranslationPlaceholders`]: /configuration/all/#enablemissingtranslationplaceholders +[CLDR]: https://www.unicode.org/cldr/charts/43/supplemental/language_plural_rules.html +[CLDR Plural Rules chart]: https://www.unicode.org/cldr/charts/43/supplemental/language_plural_rules.html +[go-i18n]: https://github.com/nicksnyder/go-i18n +[language key]: /configuration/languages/#language-keys +[RFC 5646]: https://datatracker.ietf.org/doc/html/rfc5646 +[RFC 5646 § 2.2.7]: https://datatracker.ietf.org/doc/html/rfc5646#section-2.2.7 diff --git a/content/en/functions/lang/_index.md b/content/en/functions/lang/_index.md index 934d97bff..de75cad45 100644 --- a/content/en/functions/lang/_index.md +++ b/content/en/functions/lang/_index.md @@ -1,12 +1,7 @@ --- title: Lang functions linkTitle: lang -description: Template functions to adapt your site to meet language and regional requirements. +description: Use these functions to adapt your site to meet language and regional requirements. categories: [] keywords: [] -menu: - docs: - parent: functions --- - -Use these functions to adapt your site to meet language and regional requirements. diff --git a/content/en/functions/math/Abs.md b/content/en/functions/math/Abs.md index 6e907d564..60d8d6d64 100644 --- a/content/en/functions/math/Abs.md +++ b/content/en/functions/math/Abs.md @@ -3,11 +3,11 @@ title: math.Abs description: Returns the absolute value of the given number. categories: [] keywords: [] -action: - aliases: [] - related: [] - returnType: float64 - signatures: [math.Abs VALUE] +params: + functions_and_methods: + aliases: [] + returnType: float64 + signatures: [math.Abs VALUE] --- ```go-html-template diff --git a/content/en/functions/math/Acos.md b/content/en/functions/math/Acos.md index abdae4f74..32537e2dd 100644 --- a/content/en/functions/math/Acos.md +++ b/content/en/functions/math/Acos.md @@ -3,18 +3,11 @@ title: math.Acos description: Returns the arccosine, in radians, of the given number. categories: [] keywords: [] -action: - aliases: [] - related: - - functions/math/Asin - - functions/math/Atan - - functions/math/Atan2 - - functions/math/Pi - - functions/math/Sin - - functions/math/Cos - - functions/math/Tan - returnType: float64 - signatures: [math.Acos VALUE] +params: + functions_and_methods: + aliases: [] + returnType: float64 + signatures: [math.Acos VALUE] --- {{< new-in 0.130.0 />}} diff --git a/content/en/functions/math/Add.md b/content/en/functions/math/Add.md index 25de514e0..cd137c6c7 100644 --- a/content/en/functions/math/Add.md +++ b/content/en/functions/math/Add.md @@ -3,16 +3,11 @@ title: math.Add description: Adds two or more numbers. categories: [] keywords: [] -action: - aliases: [add] - related: - - functions/math/Div - - functions/math/Mul - - functions/math/Product - - functions/math/Sub - - functions/math/Sum - returnType: any - signatures: [math.Add VALUE VALUE...] +params: + functions_and_methods: + aliases: [add] + returnType: any + signatures: [math.Add VALUE VALUE...] --- If one of the numbers is a [`float`](g), the result is a `float`. diff --git a/content/en/functions/math/Asin.md b/content/en/functions/math/Asin.md index 0496a1b45..76114a72e 100644 --- a/content/en/functions/math/Asin.md +++ b/content/en/functions/math/Asin.md @@ -3,18 +3,11 @@ title: math.Asin description: Returns the arcsine, in radians, of the given number. categories: [] keywords: [] -action: - aliases: [] - related: - - functions/math/Acos - - functions/math/Atan - - functions/math/Atan2 - - functions/math/Pi - - functions/math/Sin - - functions/math/Cos - - functions/math/Tan - returnType: float64 - signatures: [math.Asin VALUE] +params: + functions_and_methods: + aliases: [] + returnType: float64 + signatures: [math.Asin VALUE] --- {{< new-in 0.130.0 />}} diff --git a/content/en/functions/math/Atan.md b/content/en/functions/math/Atan.md index 942b3d2f2..5c8268b47 100644 --- a/content/en/functions/math/Atan.md +++ b/content/en/functions/math/Atan.md @@ -3,18 +3,11 @@ title: math.Atan description: Returns the arctangent, in radians, of the given number. categories: [] keywords: [] -action: - aliases: [] - related: - - functions/math/Atan2 - - functions/math/Asin - - functions/math/Acos - - functions/math/Pi - - functions/math/Sin - - functions/math/Cos - - functions/math/Tan - returnType: float64 - signatures: [math.Atan VALUE] +params: + functions_and_methods: + aliases: [] + returnType: float64 + signatures: [math.Atan VALUE] --- {{< new-in 0.130.0 />}} diff --git a/content/en/functions/math/Atan2.md b/content/en/functions/math/Atan2.md index efa13b166..942fffdf8 100644 --- a/content/en/functions/math/Atan2.md +++ b/content/en/functions/math/Atan2.md @@ -3,18 +3,11 @@ title: math.Atan2 description: Returns the arctangent, in radians, of the given number pair, determining the correct quadrant from their signs. categories: [] keywords: [] -action: - aliases: [] - related: - - functions/math/Atan - - functions/math/Asin - - functions/math/Acos - - functions/math/Pi - - functions/math/Sin - - functions/math/Cos - - functions/math/Tan - returnType: float64 - signatures: [math.Atan2 VALUE VALUE] +params: + functions_and_methods: + aliases: [] + returnType: float64 + signatures: [math.Atan2 VALUE VALUE] --- {{< new-in 0.130.0 />}} diff --git a/content/en/functions/math/Ceil.md b/content/en/functions/math/Ceil.md index 9f74991c3..22a9d0299 100644 --- a/content/en/functions/math/Ceil.md +++ b/content/en/functions/math/Ceil.md @@ -3,13 +3,11 @@ title: math.Ceil description: Returns the least integer value greater than or equal to the given number. categories: [] keywords: [] -action: - aliases: [] - related: - - functions/math/Floor - - functions/math/Round - returnType: float64 - signatures: [math.Ceil VALUE] +params: + functions_and_methods: + aliases: [] + returnType: float64 + signatures: [math.Ceil VALUE] --- ```go-html-template diff --git a/content/en/functions/math/Cos.md b/content/en/functions/math/Cos.md index 3291b24f8..249a064bb 100644 --- a/content/en/functions/math/Cos.md +++ b/content/en/functions/math/Cos.md @@ -3,18 +3,11 @@ title: math.Cos description: Returns the cosine of the given radian number. categories: [] keywords: [] -action: - aliases: [] - related: - - functions/math/Pi - - functions/math/Sin - - functions/math/Tan - - functions/math/Asin - - functions/math/Acos - - functions/math/Atan - - functions/math/Atan2 - returnType: float64 - signatures: [math.Cos VALUE] +params: + functions_and_methods: + aliases: [] + returnType: float64 + signatures: [math.Cos VALUE] --- {{< new-in 0.130.0 />}} diff --git a/content/en/functions/math/Counter.md b/content/en/functions/math/Counter.md index 457806b8e..16456cec6 100644 --- a/content/en/functions/math/Counter.md +++ b/content/en/functions/math/Counter.md @@ -3,11 +3,11 @@ title: math.Counter description: Increments and returns a global counter. categories: [] keywords: [] -action: - aliases: [] - related: [] - returnType: uint64 - signatures: [math.Counter] +params: + functions_and_methods: + aliases: [] + returnType: uint64 + signatures: [math.Counter] --- The counter is global for both monolingual and multilingual sites, and its initial value for each build is 1. @@ -27,9 +27,7 @@ Use this function to: - Create unique warnings as shown above; the [`warnf`] function suppresses duplicate messages - Create unique target paths for the `resources.FromString` function where the target path is also the cache key -[`warnf`]: /functions/fmt/warnf/ -[`resources.FromString`]: /functions/resources/fromstring/ +> [!note] +> Due to concurrency, the value returned in a given template for a given page will vary from one build to the next. You cannot use this function to assign a static id to each page. -{{% note %}} -Due to concurrency, the value returned in a given template for a given page will vary from one build to the next. You cannot use this function to assign a static id to each page. -{{% /note %}} +[`warnf`]: /functions/fmt/warnf/ diff --git a/content/en/functions/math/Div.md b/content/en/functions/math/Div.md index b9f7a0a53..0e338a9e9 100644 --- a/content/en/functions/math/Div.md +++ b/content/en/functions/math/Div.md @@ -3,16 +3,11 @@ title: math.Div description: Divides the first number by one or more numbers. categories: [] keywords: [] -action: - aliases: [div] - related: - - functions/math/Add - - functions/math/Mul - - functions/math/Product - - functions/math/Sub - - functions/math/Sum - returnType: any - signatures: [math.Div VALUE VALUE...] +params: + functions_and_methods: + aliases: [div] + returnType: any + signatures: [math.Div VALUE VALUE...] --- If one of the numbers is a [`float`](g), the result is a `float`. diff --git a/content/en/functions/math/Floor.md b/content/en/functions/math/Floor.md index 10ad758b6..dbfd8620e 100644 --- a/content/en/functions/math/Floor.md +++ b/content/en/functions/math/Floor.md @@ -3,13 +3,11 @@ title: math.Floor description: Returns the greatest integer value less than or equal to the given number. categories: [] keywords: [] -action: - aliases: [] - related: - - functions/math/Ceil - - functions/math/Round - returnType: float64 - signatures: [math.Floor VALUE] +params: + functions_and_methods: + aliases: [] + returnType: float64 + signatures: [math.Floor VALUE] --- ```go-html-template diff --git a/content/en/functions/math/Log.md b/content/en/functions/math/Log.md index 84edcb288..123ffacd7 100644 --- a/content/en/functions/math/Log.md +++ b/content/en/functions/math/Log.md @@ -3,11 +3,11 @@ title: math.Log description: Returns the natural logarithm of the given number. categories: [] keywords: [] -action: - aliases: [] - related: [] - returnType: float64 - signatures: [math.Log VALUE] +params: + functions_and_methods: + aliases: [] + returnType: float64 + signatures: [math.Log VALUE] --- ```go-html-template diff --git a/content/en/functions/math/Max.md b/content/en/functions/math/Max.md index 9beff5630..d3a7676fc 100644 --- a/content/en/functions/math/Max.md +++ b/content/en/functions/math/Max.md @@ -3,12 +3,11 @@ title: math.Max description: Returns the greater of all numbers. Accepts scalars, slices, or both. categories: [] keywords: [] -action: - aliases: [] - related: - - functions/math/Min - returnType: float64 - signatures: [math.Max VALUE...] +params: + functions_and_methods: + aliases: [] + returnType: float64 + signatures: [math.Max VALUE...] --- ```go-html-template diff --git a/content/en/functions/math/Min.md b/content/en/functions/math/Min.md index 79e464c74..4f7d7b85a 100644 --- a/content/en/functions/math/Min.md +++ b/content/en/functions/math/Min.md @@ -3,12 +3,11 @@ title: math.Min description: Returns the smaller of all numbers. Accepts scalars, slices, or both. categories: [] keywords: [] -action: - aliases: [] - related: - - functions/math/Max - returnType: float64 - signatures: [math.Min VALUE...] +params: + functions_and_methods: + aliases: [] + returnType: float64 + signatures: [math.Min VALUE...] --- ```go-html-template diff --git a/content/en/functions/math/Mod.md b/content/en/functions/math/Mod.md index d312730c5..6035a361e 100644 --- a/content/en/functions/math/Mod.md +++ b/content/en/functions/math/Mod.md @@ -3,12 +3,11 @@ title: math.Mod description: Returns the modulus of two integers. categories: [] keywords: [] -action: - aliases: [mod] - related: - - functions/math/ModBool - returnType: int64 - signatures: [math.Mod VALUE1 VALUE2] +params: + functions_and_methods: + aliases: [mod] + returnType: int64 + signatures: [math.Mod VALUE1 VALUE2] --- ```go-html-template diff --git a/content/en/functions/math/ModBool.md b/content/en/functions/math/ModBool.md index d915ff614..fc7813d67 100644 --- a/content/en/functions/math/ModBool.md +++ b/content/en/functions/math/ModBool.md @@ -3,12 +3,11 @@ title: math.ModBool description: Reports whether the modulus of two integers equals 0. categories: [] keywords: [] -action: - aliases: [modBool] - related: - - functions/math/Mod - returnType: bool - signatures: [math.ModBool VALUE1 VALUE2] +params: + functions_and_methods: + aliases: [modBool] + returnType: bool + signatures: [math.ModBool VALUE1 VALUE2] --- ```go-html-template diff --git a/content/en/functions/math/Mul.md b/content/en/functions/math/Mul.md index bc143c5ef..69f2dbe1b 100644 --- a/content/en/functions/math/Mul.md +++ b/content/en/functions/math/Mul.md @@ -3,16 +3,11 @@ title: math.Mul description: Multiplies two or more numbers. categories: [] keywords: [] -action: - aliases: [mul] - related: - - functions/math/Add - - functions/math/Div - - functions/math/Product - - functions/math/Sub - - functions/math/Sum - returnType: any - signatures: [math.Mul VALUE VALUE...] +params: + functions_and_methods: + aliases: [mul] + returnType: any + signatures: [math.Mul VALUE VALUE...] --- If one of the numbers is a [`float`](g), the result is a `float`. diff --git a/content/en/functions/math/Pi.md b/content/en/functions/math/Pi.md index f2cf92c7a..0bc74bf03 100644 --- a/content/en/functions/math/Pi.md +++ b/content/en/functions/math/Pi.md @@ -3,18 +3,11 @@ title: math.Pi description: Returns the mathematical constant pi. categories: [] keywords: [] -action: - aliases: [] - related: - - functions/math/Sin - - functions/math/Cos - - functions/math/Tan - - functions/math/Asin - - functions/math/Acos - - functions/math/Atan - - functions/math/Atan2 - returnType: float64 - signatures: [math.Pi] +params: + functions_and_methods: + aliases: [] + returnType: float64 + signatures: [math.Pi] --- {{< new-in 0.130.0 />}} diff --git a/content/en/functions/math/Pow.md b/content/en/functions/math/Pow.md index 5a1482d73..a4384305d 100644 --- a/content/en/functions/math/Pow.md +++ b/content/en/functions/math/Pow.md @@ -3,12 +3,11 @@ title: math.Pow description: Returns the first number raised to the power of the second number. categories: [] keywords: [] -action: - aliases: [pow] - related: - - functions/math/Sqrt - returnType: float64 - signatures: [math.Pow VALUE1 VALUE2] +params: + functions_and_methods: + aliases: [pow] + returnType: float64 + signatures: [math.Pow VALUE1 VALUE2] --- ```go-html-template diff --git a/content/en/functions/math/Product.md b/content/en/functions/math/Product.md index 1809c560d..ffb1afe46 100644 --- a/content/en/functions/math/Product.md +++ b/content/en/functions/math/Product.md @@ -3,20 +3,13 @@ title: math.Product description: Returns the product of all numbers. Accepts scalars, slices, or both. categories: [] keywords: [] -action: - aliases: [] - related: - - functions/math/Add - - functions/math/Div - - functions/math/Mul - - functions/math/Sub - - functions/math/Sum - returnType: float64 - signatures: [math.Product VALUE...] +params: + functions_and_methods: + aliases: [] + returnType: float64 + signatures: [math.Product VALUE...] --- -{{< new-in 0.114.0 />}} - ```go-html-template {{ math.Product 1 (slice 2 3) 4 }} → 24 ``` diff --git a/content/en/functions/math/Rand.md b/content/en/functions/math/Rand.md index cae6455c0..d659e651f 100644 --- a/content/en/functions/math/Rand.md +++ b/content/en/functions/math/Rand.md @@ -3,11 +3,11 @@ title: math.Rand description: Returns a pseudo-random number in the half-open interval [0.0, 1.0). categories: [] keywords: [] -action: - aliases: [] - related: [] - returnType: float64 - signatures: [math.Rand] +params: + functions_and_methods: + aliases: [] + returnType: float64 + signatures: [math.Rand] --- {{< new-in 0.121.2 />}} diff --git a/content/en/functions/math/Round.md b/content/en/functions/math/Round.md index e0678eb78..6bc015ce7 100644 --- a/content/en/functions/math/Round.md +++ b/content/en/functions/math/Round.md @@ -3,13 +3,11 @@ title: math.Round description: Returns the nearest integer, rounding half away from zero. categories: [] keywords: [] -action: - aliases: [] - related: - - functions/math/Ceil - - functions/math/Floor - returnType: float64 - signatures: [math.Round VALUE] +params: + functions_and_methods: + aliases: [] + returnType: float64 + signatures: [math.Round VALUE] --- ```go-html-template diff --git a/content/en/functions/math/Sin.md b/content/en/functions/math/Sin.md index 37936d714..b5ab86bb8 100644 --- a/content/en/functions/math/Sin.md +++ b/content/en/functions/math/Sin.md @@ -3,18 +3,11 @@ title: math.Sin description: Returns the sine of the given radian number. categories: [] keywords: [] -action: - aliases: [] - related: - - functions/math/Pi - - functions/math/Cos - - functions/math/Tan - - functions/math/Asin - - functions/math/Acos - - functions/math/Atan - - functions/math/Atan2 - returnType: float64 - signatures: [math.Sin VALUE] +params: + functions_and_methods: + aliases: [] + returnType: float64 + signatures: [math.Sin VALUE] --- {{< new-in 0.130.0 />}} diff --git a/content/en/functions/math/Sqrt.md b/content/en/functions/math/Sqrt.md index 436cb31c3..b2f49fdbd 100644 --- a/content/en/functions/math/Sqrt.md +++ b/content/en/functions/math/Sqrt.md @@ -3,12 +3,11 @@ title: math.Sqrt description: Returns the square root of the given number. categories: [] keywords: [] -action: - aliases: [] - related: - - functions/math/Pow - returnType: float64 - signatures: [math.Sqrt VALUE] +params: + functions_and_methods: + aliases: [] + returnType: float64 + signatures: [math.Sqrt VALUE] --- ```go-html-template diff --git a/content/en/functions/math/Sub.md b/content/en/functions/math/Sub.md index 9f211ef1b..49459cd71 100644 --- a/content/en/functions/math/Sub.md +++ b/content/en/functions/math/Sub.md @@ -1,18 +1,13 @@ --- title: math.Sub -description: Subtracts one or more numbers from the first number. +description: Subtracts one or more numbers from the first number. categories: [] keywords: [] -action: - aliases: [sub] - related: - - functions/math/Add - - functions/math/Div - - functions/math/Mul - - functions/math/Product - - functions/math/Sum - returnType: any - signatures: [math.Sub VALUE VALUE...] +params: + functions_and_methods: + aliases: [sub] + returnType: any + signatures: [math.Sub VALUE VALUE...] --- If one of the numbers is a [`float`](g), the result is a `float`. diff --git a/content/en/functions/math/Sum.md b/content/en/functions/math/Sum.md index 5cf882bee..e14bc924b 100644 --- a/content/en/functions/math/Sum.md +++ b/content/en/functions/math/Sum.md @@ -2,20 +2,13 @@ title: math.Sum description: Returns the sum of all numbers. Accepts scalars, slices, or both. categories: [] -action: - aliases: [] - related: - - functions/math/Add - - functions/math/Div - - functions/math/Mul - - functions/math/Product - - functions/math/Sub - returnType: float64 - signatures: [math.Sum VALUE...] +params: + functions_and_methods: + aliases: [] + returnType: float64 + signatures: [math.Sum VALUE...] --- -{{< new-in 0.114.0 />}} - ```go-html-template {{ math.Sum 1 (slice 2 3) 4 }} → 10 ``` diff --git a/content/en/functions/math/Tan.md b/content/en/functions/math/Tan.md index a8691fbca..c4f861c05 100644 --- a/content/en/functions/math/Tan.md +++ b/content/en/functions/math/Tan.md @@ -3,18 +3,11 @@ title: math.Tan description: Returns the tangent of the given radian number. categories: [] keywords: [] -action: - aliases: [] - related: - - functions/math/Pi - - functions/math/Sin - - functions/math/Cos - - functions/math/Asin - - functions/math/Acos - - functions/math/Atan - - functions/math/Atan2 - returnType: float64 - signatures: [math.Tan VALUE] +params: + functions_and_methods: + aliases: [] + returnType: float64 + signatures: [math.Tan VALUE] --- {{< new-in 0.130.0 />}} diff --git a/content/en/functions/math/ToDegrees.md b/content/en/functions/math/ToDegrees.md index 54473be72..f01cd4728 100644 --- a/content/en/functions/math/ToDegrees.md +++ b/content/en/functions/math/ToDegrees.md @@ -3,13 +3,11 @@ title: math.ToDegrees description: ToDegrees converts radians into degrees. categories: [] keywords: [] -action: - aliases: [] - related: - - functions/math/ToRadians - - functions/math/Pi - returnType: float64 - signatures: [math.ToDegrees VALUE] +params: + functions_and_methods: + aliases: [] + returnType: float64 + signatures: [math.ToDegrees VALUE] --- {{< new-in 0.130.0 />}} diff --git a/content/en/functions/math/ToRadians.md b/content/en/functions/math/ToRadians.md index c587c023c..b5acbb65b 100644 --- a/content/en/functions/math/ToRadians.md +++ b/content/en/functions/math/ToRadians.md @@ -3,13 +3,11 @@ title: math.ToRadians description: ToRadians converts degrees into radians. categories: [] keywords: [] -action: - aliases: [] - related: - - functions/math/ToDegrees - - functions/math/Pi - returnType: float64 - signatures: [math.ToRadians VALUE] +params: + functions_and_methods: + aliases: [] + returnType: float64 + signatures: [math.ToRadians VALUE] --- {{< new-in 0.130.0 />}} diff --git a/content/en/functions/math/_index.md b/content/en/functions/math/_index.md index 76713bc99..c58a5a704 100644 --- a/content/en/functions/math/_index.md +++ b/content/en/functions/math/_index.md @@ -1,11 +1,6 @@ --- title: Math functions linkTitle: math -description: Template functions to perform mathematical operations. +description: Use these functions to perform mathematical operations. categories: [] -menu: - docs: - parent: functions --- - -Use these functions to perform mathematical operations. diff --git a/content/en/functions/openapi3/Unmarshal.md b/content/en/functions/openapi3/Unmarshal.md index 6ee1519e5..d1f928aeb 100644 --- a/content/en/functions/openapi3/Unmarshal.md +++ b/content/en/functions/openapi3/Unmarshal.md @@ -3,11 +3,11 @@ title: openapi3.Unmarshal description: Unmarshals the given resource into an OpenAPI 3 document. categories: [] keywords: [] -action: - aliases: [] - related: [] - returnType: openapi3.OpenAPIDocument - signatures: ['openapi3.Unmarshal RESOURCE'] +params: + functions_and_methods: + aliases: [] + returnType: openapi3.OpenAPIDocument + signatures: ['openapi3.Unmarshal RESOURCE'] --- Use the `openapi3.Unmarshal` function with [global resources](g), [page resources](g), or [remote resources](g). diff --git a/content/en/functions/openapi3/_index.md b/content/en/functions/openapi3/_index.md index 9b6aa9584..852daf7b5 100644 --- a/content/en/functions/openapi3/_index.md +++ b/content/en/functions/openapi3/_index.md @@ -1,12 +1,7 @@ --- title: OpenAPI functions linkTitle: openapi3 -description: Template functions to work with OpenAPI 3 definitions. +description: Use these functions to work with OpenAPI 3 definitions. categories: [] keywords: [] -menu: - docs: - parent: functions --- - -Use these functions to work with OpenAPI 3 definitions. diff --git a/content/en/functions/os/FileExists.md b/content/en/functions/os/FileExists.md index b8104a066..b8a01a3e7 100644 --- a/content/en/functions/os/FileExists.md +++ b/content/en/functions/os/FileExists.md @@ -3,19 +3,15 @@ title: os.FileExists description: Reports whether the file or directory exists. categories: [] keywords: [] -action: - aliases: [fileExists] - related: - - functions/os/Getenv - - functions/os/ReadDir - - functions/os/ReadFile - - functions/os/Stat - returnType: bool - signatures: [os.FileExists PATH] +params: + functions_and_methods: + aliases: [fileExists] + returnType: bool + signatures: [os.FileExists PATH] aliases: [/functions/fileexists] --- -The `os.FileExists` function attempts to resolve the path relative to the root of your project directory. If a matching file or directory is not found, it will attempt to resolve the path relative to the [`contentDir`](/getting-started/configuration#contentdir). A leading path separator (`/`) is optional. +The `os.FileExists` function attempts to resolve the path relative to the root of your project directory. If a matching file or directory is not found, it will attempt to resolve the path relative to the [`contentDir`](/configuration/all/#contentdir). A leading path separator (`/`) is optional. With this directory structure: diff --git a/content/en/functions/os/Getenv.md b/content/en/functions/os/Getenv.md index 2b7a08881..04215e6c3 100644 --- a/content/en/functions/os/Getenv.md +++ b/content/en/functions/os/Getenv.md @@ -3,17 +3,12 @@ title: os.Getenv description: Returns the value of an environment variable, or an empty string if the environment variable is not set. categories: [] keywords: [] -action: - aliases: [getenv] - related: - - functions/os/FileExists - - functions/os/ReadDir - - functions/os/ReadFile - - functions/os/Stat - returnType: string - signatures: [os.Getenv VARIABLE] +params: + functions_and_methods: + aliases: [getenv] + returnType: string + signatures: [os.Getenv VARIABLE] aliases: [/functions/getenv] -toc: true --- ## Security @@ -30,9 +25,7 @@ To access other environment variables, adjust your site configuration. For examp getenv = ['^HUGO_', '^CI$', '^USER$', '^HOME$'] {{< /code-toggle >}} -Read more about Hugo's [security policy]. - -[security policy]: /about/security/#security-policy +For more information see [configure security](/configuration/security). ## Examples diff --git a/content/en/functions/os/ReadDir.md b/content/en/functions/os/ReadDir.md index f4a5389d9..65c398a31 100644 --- a/content/en/functions/os/ReadDir.md +++ b/content/en/functions/os/ReadDir.md @@ -3,15 +3,11 @@ title: os.ReadDir description: Returns an array of FileInfo structures sorted by file name, one element for each directory entry. categories: [] keywords: [] -action: - aliases: [readDir] - related: - - functions/os/FileExists - - functions/os/Getenv - - functions/os/ReadFile - - functions/os/Stat - returnType: os.FileInfo - signatures: [os.ReadDir PATH] +params: + functions_and_methods: + aliases: [readDir] + returnType: os.FileInfo + signatures: [os.ReadDir PATH] aliases: [/functions/readdir] --- diff --git a/content/en/functions/os/ReadFile.md b/content/en/functions/os/ReadFile.md index 5e733ef2d..7f25327c8 100644 --- a/content/en/functions/os/ReadFile.md +++ b/content/en/functions/os/ReadFile.md @@ -3,19 +3,15 @@ title: os.ReadFile description: Returns the contents of a file. categories: [] keywords: [] -action: - aliases: [readFile] - related: - - functions/os/FileExists - - functions/os/Getenv - - functions/os/ReadDir - - functions/os/Stat - returnType: string - signatures: [os.ReadFile PATH] +params: + functions_and_methods: + aliases: [readFile] + returnType: string + signatures: [os.ReadFile PATH] aliases: [/functions/readfile] --- -The `os.ReadFile` function attempts to resolve the path relative to the root of your project directory. If a matching file is not found, it will attempt to resolve the path relative to the [`contentDir`](/getting-started/configuration#contentdir). A leading path separator (`/`) is optional. +The `os.ReadFile` function attempts to resolve the path relative to the root of your project directory. If a matching file is not found, it will attempt to resolve the path relative to the [`contentDir`](/configuration/all/#contentdir). A leading path separator (`/`) is optional. With a file named README.md in the root of your project directory: diff --git a/content/en/functions/os/Stat.md b/content/en/functions/os/Stat.md index 6b6f668de..63cb3f26a 100644 --- a/content/en/functions/os/Stat.md +++ b/content/en/functions/os/Stat.md @@ -3,19 +3,15 @@ title: os.Stat description: Returns a FileInfo structure describing a file or directory. categories: [] keywords: [] -action: - aliases: [] - related: - - functions/os/FileExists - - functions/os/Getenv - - functions/os/ReadDir - - functions/os/ReadFile - returnType: os.FileInfo - signatures: [os.Stat PATH] +params: + functions_and_methods: + aliases: [] + returnType: os.FileInfo + signatures: [os.Stat PATH] aliases: [/functions/os.stat] --- -The `os.Stat` function attempts to resolve the path relative to the root of your project directory. If a matching file or directory is not found, it will attempt to resolve the path relative to the [`contentDir`](/getting-started/configuration#contentdir). A leading path separator (`/`) is optional. +The `os.Stat` function attempts to resolve the path relative to the root of your project directory. If a matching file or directory is not found, it will attempt to resolve the path relative to the [`contentDir`](/configuration/all/#contentdir). A leading path separator (`/`) is optional. ```go-html-template {{ $f := os.Stat "README.md" }} diff --git a/content/en/functions/os/_index.md b/content/en/functions/os/_index.md index c080d0092..b125f7004 100644 --- a/content/en/functions/os/_index.md +++ b/content/en/functions/os/_index.md @@ -1,12 +1,7 @@ --- title: OS functions linkTitle: os -description: Template functions to interact with the operating system. +description: Use these functions to interact with the operating system. categories: [] keywords: [] -menu: - docs: - parent: functions --- - -Use these functions to interact with the operating system. diff --git a/content/en/functions/partials/Include.md b/content/en/functions/partials/Include.md index aa93b4090..eb7eeafdc 100644 --- a/content/en/functions/partials/Include.md +++ b/content/en/functions/partials/Include.md @@ -3,15 +3,11 @@ title: partials.Include description: Executes the given partial template, optionally passing context. If the partial template contains a return statement, returns the given value, else returns the rendered output. categories: [] keywords: [] -action: - aliases: [partial] - related: - - functions/go-template/return - - functions/partials/IncludeCached - - functions/go-template/template - - methods/page/Render - returnType: any - signatures: ['partials.Include NAME [CONTEXT]'] +params: + functions_and_methods: + aliases: [partial] + returnType: any + signatures: ['partials.Include NAME [CONTEXT]'] aliases: [/functions/partial] --- diff --git a/content/en/functions/partials/IncludeCached.md b/content/en/functions/partials/IncludeCached.md index 8b57c3399..3905ee15e 100644 --- a/content/en/functions/partials/IncludeCached.md +++ b/content/en/functions/partials/IncludeCached.md @@ -3,18 +3,11 @@ title: partials.IncludeCached description: Executes the given template and caches the result, optionally passing context. If the partial template contains a return statement, returns the given value, else returns the rendered output. categories: [] keywords: [] -action: - aliases: [partialCached] - related: - - functions/go-template/return - - functions/partials/Include - - functions/go-template/template - - methods/page/Render - returnType: any - signatures: ['partials.IncludeCached LAYOUT CONTEXT [VARIANT...]'] -signatures: - - partials.IncludeCached NAME CONTEXT [VARIANT...] - - partialCached NAME CONTEXT [VARIANT...] +params: + functions_and_methods: + aliases: [partialCached] + returnType: any + signatures: ['partials.IncludeCached LAYOUT CONTEXT [VARIANT...]'] aliases: [/functions/partialcached] --- @@ -22,11 +15,10 @@ Without a [`return`] statement, the `partialCached` function returns a string of The `partialCached` function can offer significant performance gains for complex templates that don't need to be re-rendered on every invocation. -{{% note %}} -Each Site (or language) has its own `partialCached` cache, so each site will execute a partial once. - -Hugo renders pages in parallel, and will render the partial more than once with concurrent calls to the `partialCached` function. After Hugo caches the rendered partial, new pages entering the build pipeline will use the cached result. -{{% /note %}} +> [!note] +> Each Site (or language) has its own `partialCached` cache, so each site will execute a partial once. +> +> Hugo renders pages in parallel, and will render the partial more than once with concurrent calls to the `partialCached` function. After Hugo caches the rendered partial, new pages entering the build pipeline will use the cached result. Here is the simplest usage: @@ -36,9 +28,9 @@ Here is the simplest usage: Pass additional arguments to `partialCached` to create variants of the cached partial. For example, if you have a complex partial that should be identical when rendered for pages within the same section, use a variant based on section so that the partial is only rendered once per section: -{{< code file=partial-cached-example.html >}} +```go-html-template {file="layouts/_default/baseof.html"} {{ partialCached "footer.html" . .Section }} -{{< /code >}} +``` Pass additional arguments, of any data type, as needed to create unique variants: @@ -46,7 +38,7 @@ Pass additional arguments, of any data type, as needed to create unique variants {{ partialCached "footer.html" . .Params.country .Params.province }} ``` -The variant arguments are not available to the underlying partial template; they are only used to create unique cache keys. +The variant arguments are not available to the underlying partial template; they are only used to create unique cache keys. To return a value from a partial template, it must contain only one `return` statement, placed at the end of the template: diff --git a/content/en/functions/partials/_index.md b/content/en/functions/partials/_index.md index 0a7d4d6d0..09b467399 100644 --- a/content/en/functions/partials/_index.md +++ b/content/en/functions/partials/_index.md @@ -1,12 +1,7 @@ --- title: Partial functions linkTitle: partials -description: Template functions to call partial templates. +description: Use these functions to call partial templates. categories: [] keywords: [] -menu: - docs: - parent: functions --- - -Use these functions to call partial templates. diff --git a/content/en/functions/path/Base.md b/content/en/functions/path/Base.md index 2071f8bea..39d52bfcb 100644 --- a/content/en/functions/path/Base.md +++ b/content/en/functions/path/Base.md @@ -1,19 +1,13 @@ --- title: path.Base -description: Replaces path separators with slashes (`/`) and returns the last element of the given path. +description: Replaces path separators with slashes (`/`) and returns the last element of the given path. categories: [] keywords: [] -action: - aliases: [] - related: - - functions/path/BaseName - - functions/path/Clean - - functions/path/Dir - - functions/path/Ext - - functions/path/Join - - functions/path/Split - returnType: string - signatures: [path.Base PATH] +params: + functions_and_methods: + aliases: [] + returnType: string + signatures: [path.Base PATH] aliases: [/functions/path.base] --- diff --git a/content/en/functions/path/BaseName.md b/content/en/functions/path/BaseName.md index 477c8d319..468898a6f 100644 --- a/content/en/functions/path/BaseName.md +++ b/content/en/functions/path/BaseName.md @@ -3,17 +3,11 @@ title: path.BaseName description: Replaces path separators with slashes (`/`) and returns the last element of the given path, removing the extension if present. categories: [] keywords: [] -action: - aliases: [] - related: - - functions/path/Base - - functions/path/Clean - - functions/path/Dir - - functions/path/Ext - - functions/path/Join - - functions/path/Split - returnType: string - signatures: [path.BaseName PATH] +params: + functions_and_methods: + aliases: [] + returnType: string + signatures: [path.BaseName PATH] aliases: [/functions/path.basename] --- diff --git a/content/en/functions/path/Clean.md b/content/en/functions/path/Clean.md index 57a665c03..b9f2de038 100644 --- a/content/en/functions/path/Clean.md +++ b/content/en/functions/path/Clean.md @@ -3,17 +3,11 @@ title: path.Clean description: Replaces path separators with slashes (`/`) and returns the shortest path name equivalent to the given path. categories: [] keywords: [] -action: - aliases: [] - related: - - functions/path/Base - - functions/path/BaseName - - functions/path/Dir - - functions/path/Ext - - functions/path/Join - - functions/path/Split - returnType: string - signatures: [path.Clean PATH] +params: + functions_and_methods: + aliases: [] + returnType: string + signatures: [path.Clean PATH] aliases: [/functions/path.clean] --- diff --git a/content/en/functions/path/Dir.md b/content/en/functions/path/Dir.md index 6d5e5c975..04d5500f5 100644 --- a/content/en/functions/path/Dir.md +++ b/content/en/functions/path/Dir.md @@ -3,17 +3,11 @@ title: path.Dir description: Replaces path separators with slashes (/) and returns all but the last element of the given path. categories: [] keywords: [] -action: - aliases: [] - related: - - functions/path/Base - - functions/path/BaseName - - functions/path/Clean - - functions/path/Ext - - functions/path/Join - - functions/path/Split - returnType: string - signatures: [path.Dir PATH] +params: + functions_and_methods: + aliases: [] + returnType: string + signatures: [path.Dir PATH] aliases: [/functions/path.dir] --- diff --git a/content/en/functions/path/Ext.md b/content/en/functions/path/Ext.md index f3e47aecd..3646d02d0 100644 --- a/content/en/functions/path/Ext.md +++ b/content/en/functions/path/Ext.md @@ -3,17 +3,11 @@ title: path.Ext description: Replaces path separators with slashes (`/`) and returns the file name extension of the given path. categories: [] keywords: [] -action: - aliases: [] - related: - - functions/path/Base - - functions/path/BaseName - - functions/path/Clean - - functions/path/Dir - - functions/path/Join - - functions/path/Split - returnType: string - signatures: [path.Ext PATH] +params: + functions_and_methods: + aliases: [] + returnType: string + signatures: [path.Ext PATH] aliases: [/functions/path.ext] --- diff --git a/content/en/functions/path/Join.md b/content/en/functions/path/Join.md index 394389780..bda46737f 100644 --- a/content/en/functions/path/Join.md +++ b/content/en/functions/path/Join.md @@ -3,18 +3,11 @@ title: path.Join description: Replaces path separators with slashes (`/`), joins the given path elements into a single path, and returns the shortest path name equivalent to the result. categories: [] keywords: [] -action: - aliases: [] - related: - - functions/path/Base - - functions/path/BaseName - - functions/path/Clean - - functions/path/Dir - - functions/path/Ext - - functions/path/Split - - functions/urls/JoinPath - returnType: string - signatures: [path.Join ELEMENT...] +params: + functions_and_methods: + aliases: [] + returnType: string + signatures: [path.Join ELEMENT...] aliases: [/functions/path.join] --- diff --git a/content/en/functions/path/Split.md b/content/en/functions/path/Split.md index 329d73954..d4f8d08e0 100644 --- a/content/en/functions/path/Split.md +++ b/content/en/functions/path/Split.md @@ -1,19 +1,13 @@ --- title: path.Split -description: Replaces path separators with slashes (`/`) and splits the resulting path immediately following the final slash, separating it into a directory and file name component. +description: Replaces path separators with slashes (`/`) and splits the resulting path immediately following the final slash, separating it into a directory and file name component. categories: [] keywords: [] -action: - aliases: [] - related: - - functions/path/Base - - functions/path/BaseName - - functions/path/Clean - - functions/path/Dir - - functions/path/Ext - - functions/path/Join - returnType: paths.DirFile - signatures: [path.Split PATH] +params: + functions_and_methods: + aliases: [] + returnType: paths.DirFile + signatures: [path.Split PATH] aliases: [/functions/path.split] --- diff --git a/content/en/functions/path/_index.md b/content/en/functions/path/_index.md index 2d7ce8e90..49b2927ce 100644 --- a/content/en/functions/path/_index.md +++ b/content/en/functions/path/_index.md @@ -1,12 +1,7 @@ --- title: Path functions linkTitle: path -description: Template functions to work with file paths. +description: Use these functions to work with file paths. categories: [] keywords: [] -menu: - docs: - parent: functions --- - -Use these functions to work with file paths. diff --git a/content/en/functions/reflect/IsMap.md b/content/en/functions/reflect/IsMap.md index ada5a221d..55b9811d7 100644 --- a/content/en/functions/reflect/IsMap.md +++ b/content/en/functions/reflect/IsMap.md @@ -3,12 +3,11 @@ title: reflect.IsMap description: Reports whether the given value is a map. categories: [] keywords: [] -action: - aliases: [] - related: - - functions/reflect/IsSlice - returnType: bool - signatures: [reflect.IsMap INPUT] +params: + functions_and_methods: + aliases: [] + returnType: bool + signatures: [reflect.IsMap INPUT] aliases: [/functions/reflect.ismap] --- diff --git a/content/en/functions/reflect/IsSlice.md b/content/en/functions/reflect/IsSlice.md index cda24a5e1..3a5c1229b 100644 --- a/content/en/functions/reflect/IsSlice.md +++ b/content/en/functions/reflect/IsSlice.md @@ -3,12 +3,11 @@ title: reflect.IsSlice description: Reports whether the given value is a slice. categories: [] keywords: [] -action: - aliases: [] - related: - - functions/reflect/IsMap - returnType: bool - signatures: [reflect.IsSlice INPUT] +params: + functions_and_methods: + aliases: [] + returnType: bool + signatures: [reflect.IsSlice INPUT] aliases: [/functions/reflect.isslice] --- diff --git a/content/en/functions/reflect/_index.md b/content/en/functions/reflect/_index.md index 711908ee2..58f00c3de 100644 --- a/content/en/functions/reflect/_index.md +++ b/content/en/functions/reflect/_index.md @@ -1,12 +1,7 @@ --- title: Reflect functions linkTitle: reflect -description: Template functions to determine a value's data type. +description: Use these functions to determine a value's data type. categories: [] keywords: [] -menu: - docs: - parent: functions --- - -Use these functions to determine a value's data type. diff --git a/content/en/functions/resources/Babel.md b/content/en/functions/resources/Babel.md index 757aff780..799823fc5 100644 --- a/content/en/functions/resources/Babel.md +++ b/content/en/functions/resources/Babel.md @@ -3,15 +3,16 @@ title: resources.Babel description: Compiles the given JavaScript resource with Babel. categories: [] keywords: [] -action: - related: [] - returnType: resource.Resource - signatures: ['resources.Babel [OPTIONS] RESOURCE'] +params: + functions_and_methods: + aliases: [] + returnType: resource.Resource + signatures: ['resources.Babel [OPTIONS] RESOURCE'] expiryDate: 2026-06-24 # deprecated 2024-06-24 in v0.128.0 --- -{{% deprecated-in 0.128.0 %}} +{{< deprecated-in 0.128.0 >}} Use [`js.Babel`] instead. [`js.Babel`]: /functions/js/babel/ -{{% /deprecated-in %}} +{{< /deprecated-in >}} diff --git a/content/en/functions/resources/ByType.md b/content/en/functions/resources/ByType.md index ba9dcde0c..99e2b9771 100644 --- a/content/en/functions/resources/ByType.md +++ b/content/en/functions/resources/ByType.md @@ -3,16 +3,11 @@ title: resources.ByType description: Returns a collection of global resources of the given media type, or nil if none found. categories: [] keywords: [] -action: - aliases: [] - related: - - functions/resources/Get - - functions/resources/GetMatch - - functions/resources/GetRemote - - functions/resources/Match - - methods/page/Resources - returnType: resource.Resources - signatures: [resources.ByType MEDIATYPE] +params: + functions_and_methods: + aliases: [] + returnType: resource.Resources + signatures: [resources.ByType MEDIATYPE] --- The [media type] is typically one of `image`, `text`, `audio`, `video`, or `application`. @@ -23,12 +18,10 @@ The [media type] is typically one of `image`, `text`, `audio`, `video`, or `appl {{ end }} ``` -{{% note %}} -This function operates on global resources. A global resource is a file within the `assets` directory, or within any directory mounted to the `assets` directory. - -For page resources, use the [`Resources.ByType`] method on a `Page` object. +> [!note] +> This function operates on global resources. A global resource is a file within the `assets` directory, or within any directory mounted to the `assets` directory. +> +> For page resources, use the [`Resources.ByType`] method on a `Page` object. [`Resources.ByType`]: /methods/page/resources/ -{{% /note %}} - [media type]: https://en.wikipedia.org/wiki/Media_type diff --git a/content/en/functions/resources/Concat.md b/content/en/functions/resources/Concat.md index 6e81f3f44..fe7226e1b 100644 --- a/content/en/functions/resources/Concat.md +++ b/content/en/functions/resources/Concat.md @@ -3,11 +3,11 @@ title: resources.Concat description: Returns a concatenated slice of resources. categories: [] keywords: [] -action: - aliases: [] - related: [] - returnType: resource.Resource - signatures: ['resources.Concat TARGETPATH [RESOURCE...]'] +params: + functions_and_methods: + aliases: [] + returnType: resource.Resource + signatures: ['resources.Concat TARGETPATH [RESOURCE...]'] --- The `resources.Concat` function returns a concatenated slice of resources, caching the result using the target path as its cache key. Each resource must have the same [media type]. diff --git a/content/en/functions/resources/Copy.md b/content/en/functions/resources/Copy.md index 3be3dfd57..220a3db4c 100644 --- a/content/en/functions/resources/Copy.md +++ b/content/en/functions/resources/Copy.md @@ -2,11 +2,11 @@ title: resources.Copy description: Copies the given resource to the target path. categories: [] -action: - aliases: [] - related: [] - returnType: resource.Resource - signatures: [resources.Copy TARGETPATH RESOURCE] +params: + functions_and_methods: + aliases: [] + returnType: resource.Resource + signatures: [resources.Copy TARGETPATH RESOURCE] --- ```go-html-template @@ -23,6 +23,5 @@ The relative URL of the new published resource will be: /img/new-image-name.jpg ``` -{{% note %}} -Use the `resources.Copy` function with global, page, and remote resources. -{{% /note %}} +> [!note] +> Use the `resources.Copy` function with global, page, and remote resources. diff --git a/content/en/functions/resources/ExecuteAsTemplate.md b/content/en/functions/resources/ExecuteAsTemplate.md index 0c90a03b3..bff83832e 100644 --- a/content/en/functions/resources/ExecuteAsTemplate.md +++ b/content/en/functions/resources/ExecuteAsTemplate.md @@ -3,30 +3,25 @@ title: resources.ExecuteAsTemplate description: Returns a resource created from a Go template, parsed and executed with the given context. categories: [] keywords: [] -action: - aliases: [] - related: - - functions/resources/FromString - returnType: resource.Resource - signatures: [resources.ExecuteAsTemplate TARGETPATH CONTEXT RESOURCE] +params: + functions_and_methods: + aliases: [] + returnType: resource.Resource + signatures: [resources.ExecuteAsTemplate TARGETPATH CONTEXT RESOURCE] --- The `resources.ExecuteAsTemplate` function returns a resource created from a Go template, parsed and executed with the given context, caching the result using the target path as its cache key. Hugo publishes the resource to the target path when you call its [`Publish`], [`Permalink`], or [`RelPermalink`] methods. -[`publish`]: /methods/resource/publish/ -[`permalink`]: /methods/resource/permalink/ -[`relpermalink`]: /methods/resource/relpermalink/ - Let's say you have a CSS file that you wish to populate with values from your site configuration: -{{< code file=assets/css/template.css lang=go-html-template >}} +```go-html-template {file="assets/css/template.css"} body { background-color: {{ site.Params.style.bg_color }}; color: {{ site.Params.style.text_color }}; } -{{< /code >}} +``` And your site configuration contains: @@ -54,9 +49,13 @@ The example above: The result is: -{{< code file=public/css/main.css >}} +```css {file="public/css/main.css"} body { background-color: #fefefe; color: #222; } -{{< /code >}} +``` + +[`publish`]: /methods/resource/publish/ +[`permalink`]: /methods/resource/permalink/ +[`relpermalink`]: /methods/resource/relpermalink/ diff --git a/content/en/functions/resources/Fingerprint.md b/content/en/functions/resources/Fingerprint.md index 17222784e..6757a0b6f 100644 --- a/content/en/functions/resources/Fingerprint.md +++ b/content/en/functions/resources/Fingerprint.md @@ -3,16 +3,11 @@ title: resources.Fingerprint description: Cryptographically hashes the content of the given resource. categories: [] keywords: [] -action: - aliases: [fingerprint] - related: - - functions/resources/Minify - - functions/css/Sass - - functions/css/TailwindCSS - - functions/js/Build - - functions/js/Babel - returnType: resource.Resource - signatures: ['resources.Fingerprint [ALGORITHM] RESOURCE'] +params: + functions_and_methods: + aliases: [fingerprint] + returnType: resource.Resource + signatures: ['resources.Fingerprint [ALGORITHM] RESOURCE'] --- ```go-html-template diff --git a/content/en/functions/resources/FromString.md b/content/en/functions/resources/FromString.md index c13db35d6..4cd04f609 100644 --- a/content/en/functions/resources/FromString.md +++ b/content/en/functions/resources/FromString.md @@ -3,12 +3,11 @@ title: resources.FromString description: Returns a resource created from a string. categories: [] keywords: [] -action: - aliases: [] - related: - - functions/resources/ExecuteAsTemplate - returnType: resource.Resource - signatures: [resources.FromString TARGETPATH STRING] +params: + functions_and_methods: + aliases: [] + returnType: resource.Resource + signatures: [resources.FromString TARGETPATH STRING] --- The `resources.FromString` function returns a resource created from a string, caching the result using the target path as its cache key. diff --git a/content/en/functions/resources/Get.md b/content/en/functions/resources/Get.md index c6450febf..db91f0a9a 100644 --- a/content/en/functions/resources/Get.md +++ b/content/en/functions/resources/Get.md @@ -3,16 +3,11 @@ title: resources.Get description: Returns a global resource from the given path, or nil if none found. categories: [] keywords: [] -action: - aliases: [] - related: - - functions/resources/ByType - - functions/resources/GetMatch - - functions/resources/GetRemote - - functions/resources/Match - - methods/page/Resources - returnType: resource.Resource - signatures: [resources.Get PATH] +params: + functions_and_methods: + aliases: [] + returnType: resource.Resource + signatures: [resources.Get PATH] --- ```go-html-template @@ -21,10 +16,9 @@ action: {{ end }} ``` -{{% note %}} -This function operates on global resources. A global resource is a file within the `assets` directory, or within any directory mounted to the `assets` directory. - -For page resources, use the [`Resources.Get`] method on a `Page` object. +> [!note] +> This function operates on global resources. A global resource is a file within the `assets` directory, or within any directory mounted to the `assets` directory. +> +> For page resources, use the [`Resources.Get`] method on a `Page` object. [`Resources.Get`]: /methods/page/resources/ -{{% /note %}} diff --git a/content/en/functions/resources/GetMatch.md b/content/en/functions/resources/GetMatch.md index 7af2e7be8..8f1b004fe 100644 --- a/content/en/functions/resources/GetMatch.md +++ b/content/en/functions/resources/GetMatch.md @@ -3,16 +3,11 @@ title: resources.GetMatch description: Returns the first global resource from paths matching the given glob pattern, or nil if none found. categories: [] keywords: [] -action: - aliases: [] - related: - - functions/resources/ByType - - functions/resources/Get - - functions/resources/GetRemote - - functions/resources/Match - - methods/page/Resources - returnType: resource.Resource - signatures: [resources.GetMatch PATTERN] +params: + functions_and_methods: + aliases: [] + returnType: resource.Resource + signatures: [resources.GetMatch PATTERN] --- ```go-html-template @@ -21,16 +16,13 @@ action: {{ end }} ``` -{{% note %}} -This function operates on global resources. A global resource is a file within the `assets` directory, or within any directory mounted to the `assets` directory. +> [!note] +> This function operates on global resources. A global resource is a file within the `assets` directory, or within any directory mounted to the `assets` directory. +> +> For page resources, use the [`Resources.GetMatch`] method on a `Page` object. -For page resources, use the [`Resources.GetMatch`] method on a `Page` object. +Hugo determines a match using a case-insensitive [glob](g) pattern. + +{{% include "/_common/glob-patterns.md" %}} [`Resources.GetMatch`]: /methods/page/resources/ -{{% /note %}} - -Hugo determines a match using a case-insensitive [glob pattern]. - -{{% include "functions/_common/glob-patterns.md" %}} - -[glob pattern]: https://github.com/gobwas/glob#example diff --git a/content/en/functions/resources/GetRemote.md b/content/en/functions/resources/GetRemote.md index 3b294e5a1..c6f6742b3 100644 --- a/content/en/functions/resources/GetRemote.md +++ b/content/en/functions/resources/GetRemote.md @@ -3,19 +3,11 @@ title: resources.GetRemote description: Returns a remote resource from the given URL, or nil if none found. categories: [] keywords: [] -action: - aliases: [] - related: - - functions/data/GetCSV - - functions/data/GetJSON - - functions/resources/ByType - - functions/resources/Get - - functions/resources/GetMatch - - functions/resources/Match - - methods/page/Resources - returnType: resource.Resource - signatures: ['resources.GetRemote URL [OPTIONS]'] -toc: true +params: + functions_and_methods: + aliases: [] + returnType: resource.Resource + signatures: ['resources.GetRemote URL [OPTIONS]'] --- {{< new-in 0.141.0 >}} @@ -69,11 +61,10 @@ The `resources.GetRemote` function takes an optional map of options. ## Options examples -{{% note %}} -For brevity, the examples below do not include [error handling]. +> [!note] +> For brevity, the examples below do not include [error handling]. [error handling]: #error-handling -{{% /note %}} To include a header: @@ -148,15 +139,12 @@ When retrieving remote data, use the [`transform.Unmarshal`] function to [unmars {{ end }} ``` -{{% note %}} -When retrieving remote data, a misconfigured server may send a response header with an incorrect [Content-Type]. For example, the server may set the Content-Type header to `application/octet-stream` instead of `application/json`. - -In these cases, pass the resource `Content` through the `transform.Unmarshal` function instead of passing the resource itself. For example, in the above, do this instead: - -`{{ $data = .Content | transform.Unmarshal }}` - -[Content-Type]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Type -{{% /note %}} +> [!note] +> When retrieving remote data, a misconfigured server may send a response header with an incorrect [Content-Type]. For example, the server may set the Content-Type header to `application/octet-stream` instead of `application/json`. +> +> In these cases, pass the resource `Content` through the `transform.Unmarshal` function instead of passing the resource itself. For example, in the above, do this instead: +> +> `{{ $data = .Content | transform.Unmarshal }}` ## Error handling @@ -164,9 +152,8 @@ Use the [`try`] statement to capture HTTP request errors. If you do not handle t [`try`]: /functions/go-template/try -{{% note %}} -Hugo does not classify an HTTP response with status code 404 as an error. In this case `resources.GetRemote` returns nil. -{{% /note %}} +> [!note] +> Hugo does not classify an HTTP response with status code 404 as an error. In this case `resources.GetRemote` returns nil. ```go-html-template {{ $url := "https://broken-example.org/images/a.jpg" }} @@ -206,9 +193,7 @@ The [`Data`] method on a resource returned by the `resources.GetRemote` function Resources returned from `resources.GetRemote` are cached to disk. See [configure file caches] for details. -By default, Hugo derives the cache key from the arguments passed to the function, the URL and the options map, if any. - -Override the cache key by setting a `key` in the options map. Use this approach to have more control over how often Hugo fetches a remote resource. +By default, Hugo derives the cache key from the arguments passed to the function. Override the cache key by setting a `key` in the options map. Use this approach to have more control over how often Hugo fetches a remote resource. ```go-html-template {{ $url := "https://example.org/images/a.jpg" }} @@ -217,7 +202,7 @@ Override the cache key by setting a `key` in the options map. Use this approach {{ $resource := resources.GetRemote $url $opts }} ``` -[configure file caches]: /getting-started/configuration/#configure-file-caches +[configure file caches]: /configuration/caches/ ## Security @@ -245,7 +230,7 @@ mediaTypes = ['^image/avif$','^application/vnd\.api\+json$'] Note that the entry above is: - An _addition_ to the allowlist; it does not _replace_ the allowlist -- An array of regular expressions +- 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 diff --git a/content/en/functions/resources/Match.md b/content/en/functions/resources/Match.md index 3e65555ba..6c7d83649 100644 --- a/content/en/functions/resources/Match.md +++ b/content/en/functions/resources/Match.md @@ -3,16 +3,11 @@ title: resources.Match description: Returns a collection of global resources from paths matching the given glob pattern, or nil if none found. categories: [] keywords: [] -action: - aliases: [] - related: - - functions/resources/ByType - - functions/resources/Get - - functions/resources/GetMatch - - functions/resources/GetRemote - - methods/page/Resources - returnType: resource.Resources - signatures: [resources.Match PATTERN] +params: + functions_and_methods: + aliases: [] + returnType: resource.Resources + signatures: [resources.Match PATTERN] --- ```go-html-template @@ -21,16 +16,14 @@ action: {{ end }} ``` -{{% note %}} -This function operates on global resources. A global resource is a file within the `assets` directory, or within any directory mounted to the `assets` directory. - -For page resources, use the [`Resources.Match`] method on a `Page` object. - -[`Resources.Match`]: /methods/page/resources/ -{{% /note %}} +> [!note] +> This function operates on global resources. A global resource is a file within the `assets` directory, or within any directory mounted to the `assets` directory. +> +> For page resources, use the [`Resources.Match`] method on a `Page` object. Hugo determines a match using a case-insensitive [glob pattern]. -{{% include "functions/_common/glob-patterns.md" %}} +{{% include "/_common/glob-patterns.md" %}} +[`Resources.Match`]: /methods/page/resources/ [glob pattern]: https://github.com/gobwas/glob#example diff --git a/content/en/functions/resources/Minify.md b/content/en/functions/resources/Minify.md index 25314fd6a..183e6671a 100644 --- a/content/en/functions/resources/Minify.md +++ b/content/en/functions/resources/Minify.md @@ -3,16 +3,11 @@ title: resources.Minify description: Minifies the given resource. categories: [] keywords: [] -action: - aliases: [minify] - related: - - functions/resources/Fingerprint - - functions/css/Sass - - functions/css/TailwindCSS - - functions/js/Build - - functions/js/Babel - returnType: resource.Resource - signatures: [resources.Minify RESOURCE] +params: + functions_and_methods: + aliases: [minify] + returnType: resource.Resource + signatures: [resources.Minify RESOURCE] --- ```go-html-template diff --git a/content/en/functions/resources/PostCSS.md b/content/en/functions/resources/PostCSS.md index 5d3f85a30..3ec0b84cf 100644 --- a/content/en/functions/resources/PostCSS.md +++ b/content/en/functions/resources/PostCSS.md @@ -3,15 +3,16 @@ title: resources.PostCSS description: Processes the given resource with PostCSS using any PostCSS plugin. categories: [] keywords: [] -action: - related: [] - returnType: resource.Resource - signatures: ['resources.PostCSS [OPTIONS] RESOURCE'] +params: + functions_and_methods: + aliases: [] + returnType: resource.Resource + signatures: ['resources.PostCSS [OPTIONS] RESOURCE'] expiryDate: 2026-06-24 # deprecated 2024-06-24 in v0.128.0 --- -{{% deprecated-in 0.128.0 %}} +{{< deprecated-in 0.128.0 >}} Use [`css.PostCSS`] instead. [`css.PostCSS`]: /functions/css/postcss/ -{{% /deprecated-in %}} +{{< /deprecated-in >}} diff --git a/content/en/functions/resources/PostProcess.md b/content/en/functions/resources/PostProcess.md index b157d5fd9..d70437694 100644 --- a/content/en/functions/resources/PostProcess.md +++ b/content/en/functions/resources/PostProcess.md @@ -3,14 +3,11 @@ title: resources.PostProcess description: Processes the given resource after the build. categories: [] keywords: [] -action: - aliases: [] - related: - - functions/css/PostCSS - - functions/css/Sass - returnType: postpub.PostPublishedResource - signatures: [resources.PostProcess RESOURCE] -toc: true +params: + functions_and_methods: + aliases: [] + returnType: postpub.PostPublishedResource + signatures: [resources.PostProcess RESOURCE] --- The `resources.PostProcess` function delays resource transformation steps until the build is complete, primarily for tasks like removing unused CSS rules. @@ -22,19 +19,11 @@ In this example, after the build is complete, Hugo will: 1. Purge unused CSS using the [PurgeCSS] plugin for [PostCSS] 2. Add vendor prefixes to CSS rules using the [Autoprefixer] plugin for PostCSS 3. [Minify] the CSS -4. [Fingerprint] the CSS - -[autoprefixer]: https://github.com/postcss/autoprefixer -[fingerprint]: /functions/resources/fingerprint/ -[minify]: /functions/resources/minify/ -[postcss]: /functions/css/postcss/ -[purgecss]: https://purgecss.com/plugins/postcss.html +4. [Fingerprint] the CSS Step 1 : Install [Node.js]. -[node.js]: https://nodejs.org/en/download - Step 2 : Install the required Node.js packages in the root of your project: @@ -45,8 +34,6 @@ npm i -D postcss postcss-cli autoprefixer @fullhuman/postcss-purgecss Step 3 : Enable creation of the `hugo_stats.json` file when building the site. If you are only using this for the production build, consider placing it below [`config/production`]. -[`config/production`]: /getting-started/configuration/#configuration-directory - {{< code-toggle file=hugo >}} [build.buildStats] enable = true @@ -54,12 +41,10 @@ enable = true See the [configure build] documentation for details and options. -[configure build]: /getting-started/configuration/#configure-build - Step 4 : Create a PostCSS configuration file in the root of your project. -{{< code file="postcss.config.js" copy=true >}} +```js {file="postcss.config.js" copy=true} const autoprefixer = require('autoprefixer'); const purgeCSSPlugin = require('@fullhuman/postcss-purgecss').default; @@ -83,11 +68,10 @@ module.exports = { autoprefixer, ] }; -{{< /code >}} +``` -{{% note %}} -{{% include "functions/resources/_common/postcss-windows-warning.md" %}} -{{% /note %}} +> [!note] +> If you are a Windows user, and the path to your project contains a space, you must place the PostCSS configuration within the package.json file. See [this example] and issue [#7333]. Step 5 : Place your CSS file within the `assets/css` directory. @@ -132,7 +116,7 @@ HUGO_FILE_X - `postcss.config.js` - `tailwind.config.js` -For each file, Hugo creates a corresponding environment variable named `HUGO_FILE_:filename:`, where `:filename:` is the uppercase version of the filename with periods replaced by underscores. This allows you to access these files within your JavaScript, for example: +For each file, Hugo creates a corresponding environment variable named `HUGO_FILE_:filename:`, where `:filename:` is the uppercase version of the filename with periods replaced by underscores. This allows you to access these files within your JavaScript, for example: ```js let tailwindConfig = process.env.HUGO_FILE_TAILWIND_CONFIG_JS || './tailwind.config.js'; @@ -144,10 +128,21 @@ Do not use `resources.PostProcess` when running Hugo's built-in development serv The `resources.PostProcess` function only works within templates that produce HTML files. -You cannot manipulate the values returned from the resource’s methods. For example, the `strings.ToUpper` function in this example will not work as expected: +You cannot manipulate the values returned from the resource's methods. For example, the `strings.ToUpper` function in this example will not work as expected: ```go-html-template {{ $css := resources.Get "css/main.css" }} {{ $css = $css | css.PostCSS | minify | fingerprint | resources.PostProcess }} {{ $css.RelPermalink | strings.ToUpper }} ``` + +[#7333]: https://github.com/gohugoio/hugo/issues/7333 +[`config/production`]: /configuration/introduction/#configuration-directory +[Autoprefixer]: https://github.com/postcss/autoprefixer +[configure build]: /configuration/build/ +[Fingerprint]: /functions/resources/fingerprint/ +[Minify]: /functions/resources/minify/ +[Node.js]: https://nodejs.org/en +[PostCSS]: https://postcss.org/ +[PurgeCSS]: https://github.com/FullHuman/purgecss +[this example]: https://github.com/postcss/postcss-load-config#packagejson diff --git a/content/en/functions/resources/ToCSS.md b/content/en/functions/resources/ToCSS.md index 54c34a6b0..7be1b8d45 100644 --- a/content/en/functions/resources/ToCSS.md +++ b/content/en/functions/resources/ToCSS.md @@ -3,15 +3,16 @@ title: resources.ToCSS description: Transpiles Sass to CSS. categories: [] keywords: [] -action: - related: [] - returnType: resource.Resource - signatures: ['resources.ToCSS [OPTIONS] RESOURCE'] +params: + functions_and_methods: + aliases: [] + returnType: resource.Resource + signatures: ['resources.ToCSS [OPTIONS] RESOURCE'] expiryDate: 2026-06-24 # deprecated 2024-06-24 in v0.128.0 --- -{{% deprecated-in 0.128.0 %}} +{{< deprecated-in 0.128.0 >}} Use [`css.Sass`] instead. [`css.Sass`]: /functions/css/sass/ -{{% /deprecated-in %}} +{{< /deprecated-in >}} diff --git a/content/en/functions/resources/_common/_index.md b/content/en/functions/resources/_common/_index.md deleted file mode 100644 index cb36fea41..000000000 --- a/content/en/functions/resources/_common/_index.md +++ /dev/null @@ -1,12 +0,0 @@ ---- -_build: - list: never - publishResources: false - render: never ---- - - diff --git a/content/en/functions/resources/_common/postcss-windows-warning.md b/content/en/functions/resources/_common/postcss-windows-warning.md deleted file mode 100644 index e2d97850b..000000000 --- a/content/en/functions/resources/_common/postcss-windows-warning.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -_comment: Do not remove front matter. ---- - -If you are a Windows user, and the path to your project contains a space, you must place the PostCSS configuration within the package.json file. See [this example] and issue [#7333]. - -[this example]: https://github.com/postcss/postcss-load-config#packagejson -[#7333]: https://github.com/gohugoio/hugo/issues/7333 diff --git a/content/en/functions/resources/_index.md b/content/en/functions/resources/_index.md index 364b9448d..030cafd42 100644 --- a/content/en/functions/resources/_index.md +++ b/content/en/functions/resources/_index.md @@ -1,12 +1,7 @@ --- title: Resource functions linkTitle: resources -description: Template functions to work with resources. +description: Use these functions to work with resources. categories: [] keywords: [] -menu: - docs: - parent: functions --- - -Use these functions to work with resources. diff --git a/content/en/functions/safe/CSS.md b/content/en/functions/safe/CSS.md index 5d67789b6..12ebbf8aa 100644 --- a/content/en/functions/safe/CSS.md +++ b/content/en/functions/safe/CSS.md @@ -3,23 +3,17 @@ title: safe.CSS description: Declares the given string as a safe CSS string. categories: [] keywords: [] -action: - aliases: [safeCSS] - related: - - functions/safe/HTML - - functions/safe/HTMLAttr - - functions/safe/JS - - functions/safe/JSStr - - functions/safe/URL - returnType: template.CSS - signatures: [safe.CSS INPUT] -toc: true +params: + functions_and_methods: + aliases: [safeCSS] + returnType: template.CSS + signatures: [safe.CSS INPUT] aliases: [/functions/safecss] --- ## Introduction -{{% include "functions/_common/go-html-template-package.md" %}} +{{% include "/_common/functions/go-html-template-package.md" %}} ## Usage @@ -34,8 +28,6 @@ Use of this type presents a security risk: the encapsulated content should come See the [Go documentation] for details. -[Go documentation]: https://pkg.go.dev/html/template#CSS - ## Example Without a safe declaration: @@ -51,9 +43,8 @@ Hugo renders the above to:

    foo

    ``` -{{% note %}} -`ZgotmplZ` is a special value that indicates that unsafe content reached a CSS or URL context at runtime. -{{% /note %}} +> [!note] +> `ZgotmplZ` is a special value that indicates that unsafe content reached a CSS or URL context at runtime. To declare the string as safe: @@ -67,3 +58,5 @@ Hugo renders the above to: ```html

    foo

    ``` + +[Go documentation]: https://pkg.go.dev/html/template#CSS diff --git a/content/en/functions/safe/HTML.md b/content/en/functions/safe/HTML.md index ad1b3a681..25ffb3318 100644 --- a/content/en/functions/safe/HTML.md +++ b/content/en/functions/safe/HTML.md @@ -3,23 +3,17 @@ title: safe.HTML description: Declares the given string as a safeHTML string. categories: [] keywords: [] -action: - aliases: [safeHTML] - related: - - functions/safe/CSS - - functions/safe/HTMLAttr - - functions/safe/JS - - functions/safe/JSStr - - functions/safe/URL - returnType: template.HTML - signatures: [safe.HTML INPUT] -toc: true +params: + functions_and_methods: + aliases: [safeHTML] + returnType: template.HTML + signatures: [safe.HTML INPUT] aliases: [/functions/safehtml] --- ## Introduction -{{% include "functions/_common/go-html-template-package.md" %}} +{{% include "/_common/functions/go-html-template-package.md" %}} ## Usage diff --git a/content/en/functions/safe/HTMLAttr.md b/content/en/functions/safe/HTMLAttr.md index d01a3908a..7cfefdfb2 100644 --- a/content/en/functions/safe/HTMLAttr.md +++ b/content/en/functions/safe/HTMLAttr.md @@ -3,28 +3,22 @@ title: safe.HTMLAttr description: Declares the given key-value pair as a safe HTML attribute. categories: [] keywords: [] -action: - aliases: [safeHTMLAttr] - related: - - functions/safe/CSS - - functions/safe/HTML - - functions/safe/JS - - functions/safe/JSStr - - functions/safe/URL - returnType: template.HTMLAttr - signatures: [safe.HTMLAttr INPUT] -toc: true +params: + functions_and_methods: + aliases: [safeHTMLAttr] + returnType: template.HTMLAttr + signatures: [safe.HTMLAttr INPUT] aliases: [/functions/safehtmlattr] --- ## Introduction -{{% include "functions/_common/go-html-template-package.md" %}} +{{% include "/_common/functions/go-html-template-package.md" %}} ## Usage Use the `safe.HTMLAttr` function to encapsulate an HTML attribute from a trusted source. - + Use of this type presents a security risk: the encapsulated content should come from a trusted source, as it will be included verbatim in the template output. See the [Go documentation] for details. diff --git a/content/en/functions/safe/JS.md b/content/en/functions/safe/JS.md index d0d3a227a..0c4d9009d 100644 --- a/content/en/functions/safe/JS.md +++ b/content/en/functions/safe/JS.md @@ -3,23 +3,17 @@ title: safe.JS description: Declares the given string as a safe JavaScript expression. categories: [] keywords: [] -action: - aliases: [safeJS] - related: - - functions/safe/CSS - - functions/safe/HTML - - functions/safe/HTMLAttr - - functions/safe/JSStr - - functions/safe/URL - returnType: template.JS - signatures: [safe.JS INPUT] -toc: true +params: + functions_and_methods: + aliases: [safeJS] + returnType: template.JS + signatures: [safe.JS INPUT] aliases: [/functions/safejs] --- ## Introduction -{{% include "functions/_common/go-html-template-package.md" %}} +{{% include "/_common/functions/go-html-template-package.md" %}} ## Usage diff --git a/content/en/functions/safe/JSStr.md b/content/en/functions/safe/JSStr.md index e7e232d1b..81946a14c 100644 --- a/content/en/functions/safe/JSStr.md +++ b/content/en/functions/safe/JSStr.md @@ -3,23 +3,17 @@ title: safe.JSStr description: Declares the given string as a safe JavaScript string. categories: [] keywords: [] -action: - aliases: [safeJSStr] - related: - - functions/safe/CSS - - functions/safe/HTML - - functions/safe/HTMLAttr - - functions/safe/JS - - functions/safe/URL - returnType: template.JSStr - signatures: [safe.JSStr INPUT] -toc: true +params: + functions_and_methods: + aliases: [safeJSStr] + returnType: template.JSStr + signatures: [safe.JSStr INPUT] aliases: [/functions/safejsstr] --- ## Introduction -{{% include "functions/_common/go-html-template-package.md" %}} +{{% include "/_common/functions/go-html-template-package.md" %}} ## Usage diff --git a/content/en/functions/safe/URL.md b/content/en/functions/safe/URL.md index e4b3224da..44bed8064 100644 --- a/content/en/functions/safe/URL.md +++ b/content/en/functions/safe/URL.md @@ -3,23 +3,17 @@ title: safe.URL description: Declares the given string as a safe URL or URL substring. categories: [] keywords: [] -action: - aliases: [safeURL] - related: - - functions/safe/CSS - - functions/safe/HTML - - functions/safe/HTMLAttr - - functions/safe/JS - - functions/safe/JSStr - returnType: template.URL - signatures: [safe.URL INPUT] -toc: true +params: + functions_and_methods: + aliases: [safeURL] + returnType: template.URL + signatures: [safe.URL INPUT] aliases: [/functions/safeurl] --- ## Introduction -{{% include "functions/_common/go-html-template-package.md" %}} +{{% include "/_common/functions/go-html-template-package.md" %}} ## Usage @@ -33,8 +27,6 @@ Use of this type presents a security risk: the encapsulated content should come See the [Go documentation] for details. -[Go documentation]: https://pkg.go.dev/html/template#URL - ## Example Without a safe declaration: @@ -50,9 +42,8 @@ Hugo renders the above to: IRC ``` -{{% note %}} -`ZgotmplZ` is a special value that indicates that unsafe content reached a CSS or URL context at runtime. -{{% /note %}} +> [!note] +> `ZgotmplZ` is a special value that indicates that unsafe content reached a CSS or URL context at runtime. To declare the string as safe: @@ -66,3 +57,5 @@ Hugo renders the above to: ```html IRC ``` + +[Go documentation]: https://pkg.go.dev/html/template#URL diff --git a/content/en/functions/safe/_index.md b/content/en/functions/safe/_index.md index f80a2cff4..8d5697b8d 100644 --- a/content/en/functions/safe/_index.md +++ b/content/en/functions/safe/_index.md @@ -1,14 +1,7 @@ --- title: Safe functions linkTitle: safe -description: Template functions to declare a value as safe in the context of Go's html/template package. +description: Use these functions to declare a value as safe in the context of Go's html/template package. categories: [] keywords: [] -menu: - docs: - parent: functions --- - -Use these functions to declare a value as safe in the context of Go's [html/template] package. - -[html/template]: https://pkg.go.dev/html/template diff --git a/content/en/functions/strings/Chomp.md b/content/en/functions/strings/Chomp.md index 8024758ba..1ff2b7f47 100644 --- a/content/en/functions/strings/Chomp.md +++ b/content/en/functions/strings/Chomp.md @@ -3,17 +3,11 @@ title: strings.Chomp description: Returns the given string, removing all trailing newline characters and carriage returns. categories: [] keywords: [] -action: - aliases: [chomp] - related: - - functions/strings/Trim - - functions/strings/TrimSpace - - functions/strings/TrimLeft - - functions/strings/TrimPrefix - - functions/strings/TrimRight - - functions/strings/TrimSuffix - returnType: any - signatures: [strings.Chomp STRING] +params: + functions_and_methods: + aliases: [chomp] + returnType: any + signatures: [strings.Chomp STRING] aliases: [/functions/chomp] --- diff --git a/content/en/functions/strings/Contains.md b/content/en/functions/strings/Contains.md index 0344b2981..e0e3b087c 100644 --- a/content/en/functions/strings/Contains.md +++ b/content/en/functions/strings/Contains.md @@ -3,16 +3,11 @@ title: strings.Contains description: Reports whether the given string contains the given substring. categories: [] keywords: [] -action: - aliases: [] - related: - - functions/strings/ContainsAny - - functions/strings/ContainsNonSpace - - functions/strings/HasPrefix - - functions/strings/HasSuffix - - functions/collections/In - returnType: bool - signatures: [strings.Contains STRING SUBSTRING] +params: + functions_and_methods: + aliases: [] + returnType: bool + signatures: [strings.Contains STRING SUBSTRING] aliases: [/functions/strings.contains] --- diff --git a/content/en/functions/strings/ContainsAny.md b/content/en/functions/strings/ContainsAny.md index f331d09f7..521ff3421 100644 --- a/content/en/functions/strings/ContainsAny.md +++ b/content/en/functions/strings/ContainsAny.md @@ -3,16 +3,11 @@ title: strings.ContainsAny description: Reports whether the given string contains any character within the given set. categories: [] keywords: [] -action: - aliases: [] - related: - - functions/strings/Contains - - functions/strings/ContainsNonSpace - - functions/strings/HasPrefix - - functions/strings/HasSuffix - - functions/collections/In - returnType: bool - signatures: [strings.ContainsAny STRING SET] +params: + functions_and_methods: + aliases: [] + returnType: bool + signatures: [strings.ContainsAny STRING SET] aliases: [/functions/strings.containsany] --- diff --git a/content/en/functions/strings/ContainsNonSpace.md b/content/en/functions/strings/ContainsNonSpace.md index eea86f396..7b8dcb730 100644 --- a/content/en/functions/strings/ContainsNonSpace.md +++ b/content/en/functions/strings/ContainsNonSpace.md @@ -3,16 +3,11 @@ title: strings.ContainsNonSpace description: Reports whether the given string contains any non-space characters as defined by Unicode. categories: [] keywords: [] -action: - aliases: [] - related: - - functions/strings/Contains - - functions/strings/ContainsAny - - functions/strings/HasPrefix - - functions/strings/HasSuffix - - functions/collections/In - returnType: bool - signatures: [strings.ContainsNonSpace STRING] +params: + functions_and_methods: + aliases: [] + returnType: bool + signatures: [strings.ContainsNonSpace STRING] aliases: [/functions/strings.containsnonspace] --- diff --git a/content/en/functions/strings/Count.md b/content/en/functions/strings/Count.md index 43b5baeff..76378b27d 100644 --- a/content/en/functions/strings/Count.md +++ b/content/en/functions/strings/Count.md @@ -3,15 +3,11 @@ title: strings.Count description: Returns the number of non-overlapping instances of the given substring within the given string. categories: [] keywords: [] -action: - aliases: [] - related: - - functions/go-template/len - - functions/strings/CountRunes - - functions/strings/CountWords - - functions/strings/RuneCount - returnType: int - signatures: [strings.Count SUBSTR STRING] +params: + functions_and_methods: + aliases: [] + returnType: int + signatures: [strings.Count SUBSTR STRING] aliases: [/functions/strings.count] --- diff --git a/content/en/functions/strings/CountRunes.md b/content/en/functions/strings/CountRunes.md index 87d9da680..8ad6b00da 100644 --- a/content/en/functions/strings/CountRunes.md +++ b/content/en/functions/strings/CountRunes.md @@ -3,15 +3,11 @@ title: strings.CountRunes description: Returns the number of runes in the given string excluding whitespace. categories: [] keywords: [] -action: - aliases: [countrunes] - related: - - functions/go-template/len - - functions/strings/Count - - functions/strings/CountWords - - functions/strings/RuneCount - returnType: int - signatures: [strings.CountRunes INPUT] +params: + functions_and_methods: + aliases: [countrunes] + returnType: int + signatures: [strings.CountRunes INPUT] aliases: [/functions/countrunes] --- diff --git a/content/en/functions/strings/CountWords.md b/content/en/functions/strings/CountWords.md index 3e4ec0465..e50febf69 100644 --- a/content/en/functions/strings/CountWords.md +++ b/content/en/functions/strings/CountWords.md @@ -3,15 +3,11 @@ title: strings.CountWords description: Returns the number of words in the given string. categories: [] keywords: [] -action: - aliases: [countwords] - related: - - functions/go-template/len - - functions/strings/Count - - functions/strings/CountRunes - - functions/strings/RuneCount - returnType: int - signatures: [strings.CountWords INPUT] +params: + functions_and_methods: + aliases: [countwords] + returnType: int + signatures: [strings.CountWords INPUT] aliases: [/functions/countwords] --- diff --git a/content/en/functions/strings/Diff/index.md b/content/en/functions/strings/Diff/index.md index 281b76763..1426764a9 100644 --- a/content/en/functions/strings/Diff/index.md +++ b/content/en/functions/strings/Diff/index.md @@ -3,10 +3,10 @@ title: strings.Diff description: Returns an anchored diff of the two texts OLD and NEW in the unified diff format. If OLD and NEW are identical, returns an empty string. categories: [] keywords: [] -action: - related: [] - returnType: string - signatures: [strings.Diff OLDNAME OLD NEWNAME NEW] +params: + functions_and_methods: + returnType: string + signatures: [strings.Diff OLDNAME OLD NEWNAME NEW] --- {{< new-in 0.125.0 />}} diff --git a/content/en/functions/strings/FindRESubmatch.md b/content/en/functions/strings/FindRESubmatch.md index 3feb15bbd..d039607fb 100644 --- a/content/en/functions/strings/FindRESubmatch.md +++ b/content/en/functions/strings/FindRESubmatch.md @@ -3,20 +3,17 @@ title: strings.FindRESubmatch description: Returns a slice of all successive matches of the regular expression. 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. categories: [] keywords: [] -action: - aliases: [findRESubmatch] - related: - - functions/strings/FindRE - - functions/strings/Replace - - functions/strings/ReplaceRE - returnType: '[][]string' - signatures: ['strings.FindRESubmatch PATTERN INPUT [LIMIT]'] +params: + functions_and_methods: + aliases: [findRESubmatch] + returnType: '[][]string' + signatures: ['strings.FindRESubmatch PATTERN INPUT [LIMIT]'] aliases: [/functions/findresubmatch] --- By default, `findRESubmatch` finds all matches. You can limit the number of matches with an optional LIMIT argument. A return value of nil indicates no match. -{{% include "functions/_common/regular-expressions.md" %}} +{{% include "/_common/functions/regular-expressions.md" %}} ## Demonstrative examples @@ -85,6 +82,5 @@ https://example.org https://gohugo.io ``` -{{% note %}} -You can write and test your regular expression using [regex101.com](https://regex101.com/). Be sure to select the Go flavor before you begin. -{{% /note %}} +> [!note] +> You can write and test your regular expression using [regex101.com](https://regex101.com/). Be sure to select the Go flavor before you begin. diff --git a/content/en/functions/strings/FindRe.md b/content/en/functions/strings/FindRe.md index 861f38a12..45129ec91 100644 --- a/content/en/functions/strings/FindRe.md +++ b/content/en/functions/strings/FindRe.md @@ -3,19 +3,16 @@ title: strings.FindRE description: Returns a slice of strings that match the regular expression. categories: [] keywords: [] -action: - aliases: [findRE] - related: - - functions/strings/FindRESubmatch - - functions/strings/Replace - - functions/strings/ReplaceRE - returnType: '[]string' - signatures: ['strings.FindRE PATTERN INPUT [LIMIT]'] +params: + functions_and_methods: + aliases: [findRE] + returnType: '[]string' + signatures: ['strings.FindRE PATTERN INPUT [LIMIT]'] aliases: [/functions/findre] --- By default, `findRE` finds all matches. You can limit the number of matches with an optional LIMIT argument. -{{% include "functions/_common/regular-expressions.md" %}} +{{% include "/_common/functions/regular-expressions.md" %}} This example returns a slice of all second level headings (`h2` elements) within the rendered `.Content`: @@ -31,6 +28,5 @@ To limit the number of matches to one: {{ findRE `(?s).*?` .Content 1 }} ``` -{{% note %}} -You can write and test your regular expression using [regex101.com](https://regex101.com/). Be sure to select the Go flavor before you begin. -{{% /note %}} +> [!note] +> You can write and test your regular expression using [regex101.com](https://regex101.com/). Be sure to select the Go flavor before you begin. diff --git a/content/en/functions/strings/FirstUpper.md b/content/en/functions/strings/FirstUpper.md index 8826b4f18..41bf1f70a 100644 --- a/content/en/functions/strings/FirstUpper.md +++ b/content/en/functions/strings/FirstUpper.md @@ -3,14 +3,11 @@ title: strings.FirstUpper description: Returns the given string, capitalizing the first character. categories: [] keywords: [] -action: - aliases: [] - related: - - functions/strings/Title - - functions/strings/ToLower - - functions/strings/ToUpper - returnType: string - signatures: [strings.FirstUpper STRING] +params: + functions_and_methods: + aliases: [] + returnType: string + signatures: [strings.FirstUpper STRING] aliases: [/functions/strings.firstupper] --- diff --git a/content/en/functions/strings/HasPrefix.md b/content/en/functions/strings/HasPrefix.md index 455de0586..2babe8552 100644 --- a/content/en/functions/strings/HasPrefix.md +++ b/content/en/functions/strings/HasPrefix.md @@ -3,16 +3,11 @@ title: strings.HasPrefix description: Reports whether the given string begins with the given prefix. categories: [] keywords: [] -action: - aliases: [hasPrefix] - related: - - functions/strings/Contains - - functions/strings/ContainsAny - - functions/strings/ContainsNonSpace - - functions/strings/HasSuffix - - functions/collections/In - returnType: bool - signatures: [strings.HasPrefix STRING PREFIX] +params: + functions_and_methods: + aliases: [hasPrefix] + returnType: bool + signatures: [strings.HasPrefix STRING PREFIX] aliases: [/functions/hasprefix,/functions/strings.hasprefix] --- diff --git a/content/en/functions/strings/HasSuffix.md b/content/en/functions/strings/HasSuffix.md index 8fb12c527..c6b5f4ded 100644 --- a/content/en/functions/strings/HasSuffix.md +++ b/content/en/functions/strings/HasSuffix.md @@ -3,16 +3,11 @@ title: strings.HasSuffix description: Reports whether the given string ends with the given suffix. categories: [] keywords: [] -action: - aliases: [hasSuffix] - related: - - functions/strings/Contains - - functions/strings/ContainsAny - - functions/strings/ContainsNonSpace - - functions/strings/HasPrefix - - functions/collections/In - returnType: bool - signatures: [strings.HasSuffix STRING SUFFIX] +params: + functions_and_methods: + aliases: [hasSuffix] + returnType: bool + signatures: [strings.HasSuffix STRING SUFFIX] aliases: [/functions/hassuffix,/functions/strings/hassuffix] --- diff --git a/content/en/functions/strings/Repeat.md b/content/en/functions/strings/Repeat.md index 530b0d14b..b6027368e 100644 --- a/content/en/functions/strings/Repeat.md +++ b/content/en/functions/strings/Repeat.md @@ -3,11 +3,11 @@ title: strings.Repeat description: Returns a new string consisting of zero or more copies of another string. categories: [] keywords: [] -action: - aliases: [] - related: [] - returnType: string - signatures: [strings.Repeat COUNT INPUT] +params: + functions_and_methods: + aliases: [] + returnType: string + signatures: [strings.Repeat COUNT INPUT] aliases: [/functions/strings.repeat] --- diff --git a/content/en/functions/strings/Replace.md b/content/en/functions/strings/Replace.md index 9add6e12b..b449ea84d 100644 --- a/content/en/functions/strings/Replace.md +++ b/content/en/functions/strings/Replace.md @@ -3,14 +3,11 @@ title: strings.Replace description: Returns a copy of INPUT, replacing all occurrences of OLD with NEW. categories: [] keywords: [] -action: - aliases: [replace] - related: - - functions/strings/FindRE - - functions/strings/FindRESubmatch - - functions/strings/ReplaceRE - returnType: string - signatures: ['strings.Replace INPUT OLD NEW [LIMIT]'] +params: + functions_and_methods: + aliases: [replace] + returnType: string + signatures: ['strings.Replace INPUT OLD NEW [LIMIT]'] aliases: [/functions/replace] --- diff --git a/content/en/functions/strings/ReplaceRE.md b/content/en/functions/strings/ReplaceRE.md index 1c32c34fb..dba4bd15a 100644 --- a/content/en/functions/strings/ReplaceRE.md +++ b/content/en/functions/strings/ReplaceRE.md @@ -3,18 +3,15 @@ title: strings.ReplaceRE description: Returns a copy of INPUT, replacing all occurrences of a regular expression with a replacement pattern. categories: [] keywords: [] -action: - aliases: [replaceRE] - related: - - functions/strings/FindRE - - functions/strings/FindRESubmatch - - functions/strings/Replace - returnType: string - signatures: ['strings.ReplaceRE PATTERN REPLACEMENT INPUT [LIMIT]'] +params: + functions_and_methods: + aliases: [replaceRE] + returnType: string + signatures: ['strings.ReplaceRE PATTERN REPLACEMENT INPUT [LIMIT]'] aliases: [/functions/replacere] --- -{{% include "functions/_common/regular-expressions.md" %}} +{{% include "/_common/functions/regular-expressions.md" %}} ```go-html-template {{ $s := "a-b--c---d" }} @@ -35,9 +32,7 @@ Use `$1`, `$2`, etc. within the replacement string to insert the content of each {{ replaceRE "^https?://([^/]+).*" "$1" $s }} → gohugo.io ``` -{{% note %}} -You can write and test your regular expression using [regex101.com](https://regex101.com/). Be sure to select the Go flavor before you begin. -{{% /note %}} +> [!note] +> You can write and test your regular expression using [regex101.com]. Be sure to select the Go flavor before you begin. -[RE2]: https://github.com/google/re2/wiki/Syntax -[string literal]: https://go.dev/ref/spec#String_literals +[regex101.com]: https://regex101.com/ diff --git a/content/en/functions/strings/RuneCount.md b/content/en/functions/strings/RuneCount.md index 86aab0c64..8c0e24342 100644 --- a/content/en/functions/strings/RuneCount.md +++ b/content/en/functions/strings/RuneCount.md @@ -3,15 +3,11 @@ title: strings.RuneCount description: Returns the number of runes in the given string. categories: [] keywords: [] -action: - aliases: [] - related: - - functions/go-template/len - - functions/strings/Count - - functions/strings/CountRunes - - functions/strings/CountWords - returnType: int - signatures: [strings.RuneCount INPUT] +params: + functions_and_methods: + aliases: [] + returnType: int + signatures: [strings.RuneCount INPUT] aliases: [/functions/strings.runecount] --- diff --git a/content/en/functions/strings/SliceString.md b/content/en/functions/strings/SliceString.md index 377a5eb37..69e4f6f33 100644 --- a/content/en/functions/strings/SliceString.md +++ b/content/en/functions/strings/SliceString.md @@ -3,12 +3,11 @@ title: strings.SliceString description: Returns a substring of the given string, beginning with the start position and ending before the end position. categories: [] keywords: [] -action: - aliases: [slicestr] - related: - - functions/strings/Substr - returnType: string - signatures: ['strings.SliceString STRING [START] [END]'] +params: + functions_and_methods: + aliases: [slicestr] + returnType: string + signatures: ['strings.SliceString STRING [START] [END]'] aliases: [/functions/slicestr] --- diff --git a/content/en/functions/strings/Split.md b/content/en/functions/strings/Split.md index e3e0ee13e..bcab1b4d7 100644 --- a/content/en/functions/strings/Split.md +++ b/content/en/functions/strings/Split.md @@ -3,12 +3,11 @@ title: strings.Split description: Returns a slice of strings by splitting the given string by a delimiter. categories: [] keywords: [] -action: - aliases: [split] - related: - - functions/collections/Delimit - returnType: string - signatures: [strings.Split STRING DELIM] +params: + functions_and_methods: + aliases: [split] + returnType: '[]string' + signatures: [strings.Split STRING DELIM] aliases: [/functions/split] --- @@ -19,8 +18,7 @@ Examples: {{ split "abc" "" }} → ["a", "b", "c"] ``` -{{% note %}} -The `strings.Split` function essentially does the opposite of the [`collections.Delimit`] function. While `split` creates a slice from a string, `delimit` creates a string from a slice. +> [!note] +> The `strings.Split` function essentially does the opposite of the [`collections.Delimit`] function. While `split` creates a slice from a string, `delimit` creates a string from a slice. [`collections.Delimit`]: /functions/collections/delimit/ -{{% /note %}} diff --git a/content/en/functions/strings/Substr.md b/content/en/functions/strings/Substr.md index 19a029e28..a4c779f7d 100644 --- a/content/en/functions/strings/Substr.md +++ b/content/en/functions/strings/Substr.md @@ -3,16 +3,15 @@ title: strings.Substr description: Returns a substring of the given string, beginning with the start position and ending after the given length. categories: [] keywords: [] -action: - aliases: [substr] - related: - - functions/strings/SliceString - returnType: string - signatures: ['strings.Substr STRING [START] [LENGTH]'] +params: + functions_and_methods: + aliases: [substr] + returnType: string + signatures: ['strings.Substr STRING [START] [LENGTH]'] aliases: [/functions/substr] --- -The start position is zero-based, where `0` represents the first character of the string. If START is not specified, the substring will begin at position `0`. Specify a negative START position to extract characters from the end of the string. +The start position is zero-based, where `0` represents the first character of the string. If START is not specified, the substring will begin at position `0`. Specify a negative START position to extract characters from the end of the string. If LENGTH is not specified, the substring will include all characters from the START position to the end of the string. If negative, that number of characters will be omitted from the end of string. diff --git a/content/en/functions/strings/Title.md b/content/en/functions/strings/Title.md index b7f1f9e5c..d1b4aca01 100644 --- a/content/en/functions/strings/Title.md +++ b/content/en/functions/strings/Title.md @@ -3,14 +3,11 @@ title: strings.Title description: Returns the given string, converting it to title case. categories: [] keywords: [] -action: - aliases: [title] - related: - - functions/strings/FirstUpper - - functions/strings/ToLower - - functions/strings/ToUpper - returnType: string - signatures: [strings.Title STRING] +params: + functions_and_methods: + aliases: [title] + returnType: string + signatures: [strings.Title STRING] aliases: [/functions/title] --- @@ -29,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]: /getting-started/configuration/#configure-title-case +[site configuration]: /configuration/all/#title-case-style diff --git a/content/en/functions/strings/ToLower.md b/content/en/functions/strings/ToLower.md index 3da047ae4..c329b5e55 100644 --- a/content/en/functions/strings/ToLower.md +++ b/content/en/functions/strings/ToLower.md @@ -3,14 +3,11 @@ title: strings.ToLower description: Returns the given string, converting all characters to lowercase. categories: [] keywords: [] -action: - aliases: [lower] - related: - - functions/strings/FirstUpper - - functions/strings/Title - - functions/strings/ToUpper - returnType: string - signatures: [strings.ToLower INPUT] +params: + functions_and_methods: + aliases: [lower] + returnType: string + signatures: [strings.ToLower INPUT] aliases: [/functions/lower] --- diff --git a/content/en/functions/strings/ToUpper.md b/content/en/functions/strings/ToUpper.md index 617e1e68a..acccb4124 100644 --- a/content/en/functions/strings/ToUpper.md +++ b/content/en/functions/strings/ToUpper.md @@ -3,14 +3,11 @@ title: strings.ToUpper description: Returns the given string, converting all characters to uppercase. categories: [] keywords: [] -action: - aliases: [upper] - related: - - functions/strings/FirstUpper - - functions/strings/Title - - functions/strings/ToLower - returnType: string - signatures: [strings.ToUpper INPUT] +params: + functions_and_methods: + aliases: [upper] + returnType: string + signatures: [strings.ToUpper INPUT] aliases: [/functions/upper] --- diff --git a/content/en/functions/strings/Trim.md b/content/en/functions/strings/Trim.md index a8c4cf92d..1afa0627f 100644 --- a/content/en/functions/strings/Trim.md +++ b/content/en/functions/strings/Trim.md @@ -3,17 +3,11 @@ title: strings.Trim description: Returns the given string, removing leading and trailing characters specified in the cutset. categories: [] keywords: [] -action: - aliases: [trim] - related: - - functions/strings/Chomp - - functions/strings/TrimSpace - - functions/strings/TrimLeft - - functions/strings/TrimPrefix - - functions/strings/TrimRight - - functions/strings/TrimSuffix - returnType: string - signatures: [strings.Trim INPUT CUTSET] +params: + functions_and_methods: + aliases: [trim] + returnType: string + signatures: [strings.Trim INPUT CUTSET] aliases: [/functions/trim] --- diff --git a/content/en/functions/strings/TrimLeft.md b/content/en/functions/strings/TrimLeft.md index d94aa05a3..c5d6ba60f 100644 --- a/content/en/functions/strings/TrimLeft.md +++ b/content/en/functions/strings/TrimLeft.md @@ -3,17 +3,11 @@ title: strings.TrimLeft description: Returns the given string, removing leading characters specified in the cutset. categories: [] keywords: [] -action: - aliases: [] - related: - - functions/strings/Chomp - - functions/strings/Trim - - functions/strings/TrimSpace - - functions/strings/TrimPrefix - - functions/strings/TrimRight - - functions/strings/TrimSuffix - returnType: string - signatures: [strings.TrimLeft CUTSET STRING] +params: + functions_and_methods: + aliases: [] + returnType: string + signatures: [strings.TrimLeft CUTSET STRING] aliases: [/functions/strings.trimleft] --- diff --git a/content/en/functions/strings/TrimPrefix.md b/content/en/functions/strings/TrimPrefix.md index 331c52a03..b897d8777 100644 --- a/content/en/functions/strings/TrimPrefix.md +++ b/content/en/functions/strings/TrimPrefix.md @@ -3,17 +3,11 @@ title: strings.TrimPrefix description: Returns the given string, removing the prefix from the beginning of the string. categories: [] keywords: [] -action: - aliases: [] - related: - - functions/strings/Chomp - - functions/strings/Trim - - functions/strings/TrimSpace - - functions/strings/TrimLeft - - functions/strings/TrimRight - - functions/strings/TrimSuffix - returnType: string - signatures: [strings.TrimPrefix PREFIX STRING] +params: + functions_and_methods: + aliases: [] + returnType: string + signatures: [strings.TrimPrefix PREFIX STRING] aliases: [/functions/strings.trimprefix] --- diff --git a/content/en/functions/strings/TrimRight.md b/content/en/functions/strings/TrimRight.md index f36597d3d..05c2ed324 100644 --- a/content/en/functions/strings/TrimRight.md +++ b/content/en/functions/strings/TrimRight.md @@ -3,17 +3,11 @@ title: strings.TrimRight description: Returns the given string, removing trailing characters specified in the cutset. categories: [] keywords: [] -action: - aliases: [] - related: - - functions/strings/Chomp - - functions/strings/Trim - - functions/strings/TrimSpace - - functions/strings/TrimLeft - - functions/strings/TrimPrefix - - functions/strings/TrimSuffix - returnType: string - signatures: [strings.TrimRight CUTSET STRING] +params: + functions_and_methods: + aliases: [] + returnType: string + signatures: [strings.TrimRight CUTSET STRING] aliases: [/functions/strings.trimright] --- diff --git a/content/en/functions/strings/TrimSpace.md b/content/en/functions/strings/TrimSpace.md index 7cb293674..cb38b5ab1 100644 --- a/content/en/functions/strings/TrimSpace.md +++ b/content/en/functions/strings/TrimSpace.md @@ -3,16 +3,10 @@ title: strings.TrimSpace description: Returns the given string, removing leading and trailing whitespace as defined by Unicode. categories: [] keywords: [] -action: - related: - - functions/strings/Chomp - - functions/strings/Trim - - functions/strings/TrimLeft - - functions/strings/TrimPrefix - - functions/strings/TrimRight - - functions/strings/TrimSuffix - returnType: string - signatures: [strings.TrimSpace INPUT] +params: + functions_and_methods: + returnType: string + signatures: [strings.TrimSpace INPUT] --- {{< new-in 0.136.3 />}} diff --git a/content/en/functions/strings/TrimSuffix.md b/content/en/functions/strings/TrimSuffix.md index d612ae695..802842105 100644 --- a/content/en/functions/strings/TrimSuffix.md +++ b/content/en/functions/strings/TrimSuffix.md @@ -3,17 +3,11 @@ title: strings.TrimSuffix description: Returns the given string, removing the suffix from the end of the string. categories: [] keywords: [] -action: - aliases: [] - related: - - functions/strings/Chomp - - functions/strings/Trim - - functions/strings/TrimSpace - - functions/strings/TrimLeft - - functions/strings/TrimPrefix - - functions/strings/TrimRight - returnType: string - signatures: [strings.TrimSuffix SUFFIX STRING] +params: + functions_and_methods: + aliases: [] + returnType: string + signatures: [strings.TrimSuffix SUFFIX STRING] aliases: [/functions/strings.trimsuffix] --- diff --git a/content/en/functions/strings/Truncate.md b/content/en/functions/strings/Truncate.md index 2e7693eb5..c4198229e 100644 --- a/content/en/functions/strings/Truncate.md +++ b/content/en/functions/strings/Truncate.md @@ -3,11 +3,11 @@ title: strings.Truncate description: Returns the given string, truncating it to a maximum length without cutting words or leaving unclosed HTML tags. categories: [] keywords: [] -action: - aliases: [truncate] - related: [] - returnType: template.HTML - signatures: ['strings.Truncate SIZE [ELLIPSIS] INPUT'] +params: + functions_and_methods: + aliases: [truncate] + returnType: template.HTML + signatures: ['strings.Truncate SIZE [ELLIPSIS] INPUT'] aliases: [/functions/truncate] --- @@ -17,8 +17,7 @@ Since Go templates are HTML-aware, `truncate` will intelligently handle normal s {{ "Keep my HTML" | safeHTML | truncate 10 }} → Keep my … ``` -{{% note %}} -If you have a raw string that contains HTML tags you want to remain treated as HTML, you will need to convert the string to HTML using the [`safeHTML`]function before sending the value to `truncate`. Otherwise, the HTML tags will be escaped when passed through the `truncate` function. +> [!note] +> If you have a raw string that contains HTML tags you want to remain treated as HTML, you will need to convert the string to HTML using the [`safeHTML`]function before sending the value to `truncate`. Otherwise, the HTML tags will be escaped when passed through the `truncate` function. [`safeHTML`]: /functions/safe/html/ -{{% /note %}} diff --git a/content/en/functions/strings/_index.md b/content/en/functions/strings/_index.md index 364522a3a..28f26f170 100644 --- a/content/en/functions/strings/_index.md +++ b/content/en/functions/strings/_index.md @@ -1,12 +1,7 @@ --- title: String functions linkTitle: strings -description: Template functions to work with strings. +description: Use these functions to work with strings. categories: [] keywords: [] -menu: - docs: - parent: functions --- - -Use these functions to work with strings. diff --git a/content/en/functions/templates/Defer.md b/content/en/functions/templates/Defer.md index c43ef43bf..6a9ca56ae 100644 --- a/content/en/functions/templates/Defer.md +++ b/content/en/functions/templates/Defer.md @@ -3,18 +3,20 @@ title: templates.Defer description: Defer execution of a template until after all sites and output formats have been rendered. categories: [] keywords: [] -toc: true -action: - aliases: [] - related: [] - returnType: string - signatures: [templates.Defer OPTIONS] +params: + functions_and_methods: + aliases: [] + returnType: string + signatures: [templates.Defer OPTIONS] aliases: [/functions/templates.defer] --- {{< new-in 0.128.0 />}} -In some rare use cases, you may need to defer the execution of a template until after all sites and output formats have been rendered. One such example could be [TailwindCSS](/functions/css/tailwindcss/) using the output of [hugo_stats.json](/getting-started/configuration/#configure-build) to determine which classes and other HTML identifiers are being used in the final output: +> [!note] +> This feature is meant to be used in the main page layout files/templates, and has undefined behavior when used from shortcodes, partials or render hook templates. See [this issue](https://github.com/gohugoio/hugo/issues/13492#issuecomment-2734700391) for more info. + +In some rare use cases, you may need to defer the execution of a template until after all sites and output formats have been rendered. One such example could be [TailwindCSS](/functions/css/tailwindcss/) using the output of [hugo_stats.json](/configuration/build/) to determine which classes and other HTML identifiers are being used in the final output: ```go-html-template {{ with (templates.Defer (dict "key" "global")) }} @@ -42,13 +44,10 @@ In some rare use cases, you may need to defer the execution of a template until {{ end }} ``` -{{% note %}} -This function only works in combination with the `with` keyword. -{{% /note %}} - -{{% note %}} -Variables defined on the outside are not visible on the inside and vice versa. To pass in data, use the `data` [option](#options). -{{% /note %}} +> [!note] +> This function only works in combination with the `with` keyword. +> +> Variables defined on the outside are not visible on the inside and vice versa. To pass in data, use the `data` [option](#options). For the above to work well when running the server (or `hugo -w`), you want to have a configuration similar to this: @@ -75,7 +74,7 @@ The `templates.Defer` function takes a single argument, a map with the following key (`string`) : The key to use for the deferred template. This will, combined with a hash of the template content, be used as a cache key. If this is not set, Hugo will execute the deferred template on every render. This is not what you want for shared resources like CSS and JavaScript. -data (`map`) +data (`map`) : Optional map to pass as data to the deferred template. This will be available in the deferred template as `.` or `$`. ```go-html-template @@ -90,4 +89,4 @@ I18n Outside: {{ i18n "hello" }} {{ end }} ``` -The [Output Format](/templates/output-formats/), [Site](/methods/page/site/), and [language](/methods/site/language) will be the same, even if the execution is deferred. In the example above, this means that the `site.Language.Lang` and `.RelPermalink` will be the same on the inside and the outside of the deferred template. +The [output format](/configuration/output-formats/), [site](/methods/page/site/), and [language](/methods/site/language) will be the same, even if the execution is deferred. In the example above, this means that the `site.Language.Lang` and `.RelPermalink` will be the same on the inside and the outside of the deferred template. diff --git a/content/en/functions/templates/Exists.md b/content/en/functions/templates/Exists.md index e57610488..79fc561c8 100644 --- a/content/en/functions/templates/Exists.md +++ b/content/en/functions/templates/Exists.md @@ -3,11 +3,11 @@ title: templates.Exists description: Reports whether a template file exists under the given path relative to the layouts directory. categories: [] keywords: [] -action: - aliases: [] - related: [] - returnType: bool - signatures: [templates.Exists PATH] +params: + functions_and_methods: + aliases: [] + returnType: bool + signatures: [templates.Exists PATH] aliases: [/functions/templates.exists] --- diff --git a/content/en/functions/templates/_index.md b/content/en/functions/templates/_index.md index 89da6c38f..a385604ea 100644 --- a/content/en/functions/templates/_index.md +++ b/content/en/functions/templates/_index.md @@ -1,13 +1,7 @@ --- title: Template functions linkTitle: templates -description: +description: Use these functions to query the template system. categories: [] keywords: [] -menu: - docs: - identifier: templates-functions - parent: functions --- - -Use these functions to query the template system. diff --git a/content/en/functions/time/AsTime.md b/content/en/functions/time/AsTime.md index 92040f924..760329a13 100644 --- a/content/en/functions/time/AsTime.md +++ b/content/en/functions/time/AsTime.md @@ -3,17 +3,12 @@ title: time.AsTime description: Returns the given string representation of a date/time value as a time.Time value. categories: [] keywords: [] -action: - aliases: [time] - related: - - functions/time/Duration - - functions/time/Format - - functions/time/Now - - functions/time/ParseDuration - returnType: time.Time - signatures: ['time.AsTime INPUT [TIMEZONE]'] +params: + functions_and_methods: + aliases: [time] + returnType: time.Time + signatures: ['time.AsTime INPUT [TIMEZONE]'] aliases: [/functions/time] -toc: true --- ## Overview @@ -29,7 +24,7 @@ Hugo provides [functions] and [methods] to format, localize, parse, compare, and As shown above, the first argument must be a parsable string representation of a date/time value. For example: -{{% include "functions/time/_common/parsable-date-time-strings.md" %}} +{{% 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: @@ -48,6 +43,6 @@ The order of precedence for determining the time zone is: [IANA Time Zone database]: https://en.wikipedia.org/wiki/List_of_tz_database_time_zones [`time.Time`]: https://pkg.go.dev/time#Time -[`timeZone`]: /getting-started/configuration/#timezone +[`timeZone`]: /configuration/all/#timezone [functions]: /functions/time/ [methods]: /methods/time/ diff --git a/content/en/functions/time/Duration.md b/content/en/functions/time/Duration.md index 09e5d6725..bd6adfbfa 100644 --- a/content/en/functions/time/Duration.md +++ b/content/en/functions/time/Duration.md @@ -1,17 +1,13 @@ --- title: time.Duration -description: Returns a time.Duration value using the given time unit and number. +description: Returns a time.Duration value using the given time unit and number. categories: [] keywords: [] -action: - aliases: [duration] - related: - - functions/time/AsTime - - functions/time/Format - - functions/time/Now - - functions/time/ParseDuration - returnType: time.Duration - signatures: [time.Duration TIME_UNIT NUMBER] +params: + functions_and_methods: + aliases: [duration] + returnType: time.Duration + signatures: [time.Duration TIME_UNIT NUMBER] aliases: [/functions/duration] --- diff --git a/content/en/functions/time/Format.md b/content/en/functions/time/Format.md index cf7721376..f1b0d6d83 100644 --- a/content/en/functions/time/Format.md +++ b/content/en/functions/time/Format.md @@ -3,17 +3,12 @@ title: time.Format description: Returns the given date/time as a formatted and localized string. categories: [] keywords: [] -action: - aliases: [dateFormat] - related: - - functions/time/AsTime - - functions/time/Duration - - functions/time/Now - - functions/time/ParseDuration - returnType: string - signatures: [time.Format LAYOUT INPUT] +params: + functions_and_methods: + aliases: [dateFormat] + returnType: string + signatures: [time.Format LAYOUT INPUT] aliases: [/functions/dateformat] -toc: true --- Use the `time.Format` function with `time.Time` values: @@ -32,7 +27,7 @@ Or use `time.Format` with a parsable string representation of a date/time value: Examples of parsable string representations: -{{% include "functions/time/_common/parsable-date-time-strings.md" %}} +{{% 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: @@ -40,17 +35,17 @@ To override the default time zone, set the [`timeZone`] in your site configurati 1. The time zone specified in your site configuration 1. The `Etc/UTC` time zone -[`timeZone`]: /getting-started/configuration/#timezone +[`timeZone`]: /configuration/all/#timezone ## Layout string -{{% include "functions/_common/time-layout-string.md" %}} +{{% include "/_common/time-layout-string.md" %}} ## Localization Use the `time.Format` function to localize `time.Time` values for the current language and region. -{{% include "functions/_common/locales.md" %}} +{{% include "/_common/functions/locales.md" %}} Use the layout string as described above, or one of the tokens below. For example: diff --git a/content/en/functions/time/Now.md b/content/en/functions/time/Now.md index 2994a9728..9b6fa4692 100644 --- a/content/en/functions/time/Now.md +++ b/content/en/functions/time/Now.md @@ -3,15 +3,11 @@ title: time.Now description: Returns the current local time. categories: [] keywords: [] -action: - aliases: [now] - related: - - functions/time/AsTime - - functions/time/Duration - - functions/time/Format - - functions/time/ParseDuration - returnType: time.Time - signatures: [time.Now] +params: + functions_and_methods: + aliases: [now] + returnType: time.Time + signatures: [time.Now] aliases: [/functions/now] --- diff --git a/content/en/functions/time/ParseDuration.md b/content/en/functions/time/ParseDuration.md index abb516361..af5d73ad5 100644 --- a/content/en/functions/time/ParseDuration.md +++ b/content/en/functions/time/ParseDuration.md @@ -3,15 +3,11 @@ title: time.ParseDuration description: Returns a time.Duration value by parsing the given duration string. categories: [] keywords: [] -action: - aliases: [] - related: - - functions/time/AsTime - - functions/time/Duration - - functions/time/Format - - functions/time/Now - returnType: time.Duration - signatures: [time.ParseDuration DURATION] +params: + functions_and_methods: + aliases: [] + returnType: time.Duration + signatures: [time.ParseDuration DURATION] aliases: [/functions/time.parseduration] --- diff --git a/content/en/functions/time/_common/_index.md b/content/en/functions/time/_common/_index.md deleted file mode 100644 index 4328d4d14..000000000 --- a/content/en/functions/time/_common/_index.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -cascade: - _build: - list: never - publishResources: false - render: never ---- - - diff --git a/content/en/functions/time/_index.md b/content/en/functions/time/_index.md index 7e0b82f91..9c2ff2161 100644 --- a/content/en/functions/time/_index.md +++ b/content/en/functions/time/_index.md @@ -1,12 +1,7 @@ --- title: Time functions linkTitle: time -description: Template functions to work with time values. +description: Use these functions to work with time values. categories: [] keywords: [] -menu: - docs: - parent: functions --- - -Use these functions to work with time values. diff --git a/content/en/functions/transform/CanHighlight.md b/content/en/functions/transform/CanHighlight.md index 039cb12b7..c00445605 100644 --- a/content/en/functions/transform/CanHighlight.md +++ b/content/en/functions/transform/CanHighlight.md @@ -3,13 +3,11 @@ title: transform.CanHighlight description: Reports whether the given code language is supported by the Chroma highlighter. categories: [] keywords: [] -action: - aliases: [] - related: - - functions/transform/Highlight - - functions/transform/HighlightCodeBlock - returnType: bool - signatures: [transform.CanHighlight LANGUAGE] +params: + functions_and_methods: + aliases: [] + returnType: bool + signatures: [transform.CanHighlight LANGUAGE] --- ```go-html-template diff --git a/content/en/functions/transform/Emojify.md b/content/en/functions/transform/Emojify.md index 5ca562db9..31c5dce70 100644 --- a/content/en/functions/transform/Emojify.md +++ b/content/en/functions/transform/Emojify.md @@ -3,11 +3,11 @@ title: transform.Emojify description: Runs a string through the Emoji emoticons processor. categories: [] keywords: [] -action: - aliases: [emojify] - related: [] - returnType: template.HTML - signatures: [transform.Emojify INPUT] +params: + functions_and_methods: + aliases: [emojify] + returnType: template.HTML + signatures: [transform.Emojify INPUT] aliases: [/functions/emojify] --- @@ -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 site's configuration. Then you can write emoji shorthand directly into your content files; ```text I :heart: Hugo! @@ -23,7 +23,5 @@ I :heart: Hugo! I :heart: Hugo! -[configuration]: /getting-started/configuration/ +[`enableEmoji`]: /configuration/all/#enableemoji [emoji shortcodes]: /quick-reference/emojis/ -[sc]: /templates/shortcode/ -[scsource]: https://github.com/gohugoio/hugo/tree/master/docs/layouts/shortcodes diff --git a/content/en/functions/transform/HTMLEscape.md b/content/en/functions/transform/HTMLEscape.md index bb522769c..069fd92f2 100644 --- a/content/en/functions/transform/HTMLEscape.md +++ b/content/en/functions/transform/HTMLEscape.md @@ -3,12 +3,11 @@ title: transform.HTMLEscape description: Returns the given string, escaping special characters by replacing them with HTML entities. categories: [] keywords: [] -action: - aliases: [htmlEscape] - related: - - functions/transform/HTMLUnescape - returnType: string - signatures: [transform.HTMLEscape INPUT] +params: + functions_and_methods: + aliases: [htmlEscape] + returnType: string + signatures: [transform.HTMLEscape INPUT] aliases: [/functions/htmlescape] --- diff --git a/content/en/functions/transform/HTMLUnescape.md b/content/en/functions/transform/HTMLUnescape.md index 1c88de672..563e63cf6 100644 --- a/content/en/functions/transform/HTMLUnescape.md +++ b/content/en/functions/transform/HTMLUnescape.md @@ -3,12 +3,11 @@ title: transform.HTMLUnescape description: Returns the given string, replacing each HTML entity with its corresponding character. categories: [] keywords: [] -action: - aliases: [htmlUnescape] - related: - - functions/transform/HTMLEscape - returnType: string - signatures: [transform.HTMLUnescape INPUT] +params: + functions_and_methods: + aliases: [htmlUnescape] + returnType: string + signatures: [transform.HTMLUnescape INPUT] aliases: [/functions/htmlunescape] --- diff --git a/content/en/functions/transform/Highlight.md b/content/en/functions/transform/Highlight.md index 5eaa53939..5633f2256 100644 --- a/content/en/functions/transform/Highlight.md +++ b/content/en/functions/transform/Highlight.md @@ -2,22 +2,19 @@ title: transform.Highlight description: Renders code with a syntax highlighter. categories: [] -keywords: [] -action: - aliases: [highlight] - related: - - functions/transform/CanHighlight - - functions/transform/HighlightCodeBlock - returnType: template.HTML - signatures: ['transform.Highlight CODE LANG [OPTIONS]'] +keywords: [highlight] +params: + functions_and_methods: + aliases: [highlight] + returnType: template.HTML + signatures: ['transform.Highlight CODE LANG [OPTIONS]'] aliases: [/functions/highlight] -toc: true --- -The `highlight` function uses the [Chroma] syntax highlighter, supporting over 200 languages with more than 40 [available styles]. +The `highlight` function uses the [Chroma] syntax highlighter, supporting over 200 languages with more than 40 [highlighting styles]. [chroma]: https://github.com/alecthomas/chroma -[available styles]: https://xyproto.github.io/splash/docs/ +[highlighting styles]: /quick-reference/syntax-highlighting-styles/ ## Arguments @@ -30,10 +27,10 @@ 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 space-separate 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 [site configuration]. The key names are case-insensitive. -[site configuration]: /getting-started/configuration-markup#highlight -[supported languages]: /content-management/syntax-highlighting#list-of-chroma-highlighting-languages +[site configuration]: /configuration/markup#highlight +[supported languages]: /content-management/syntax-highlighting#languages ## Examples @@ -53,4 +50,4 @@ OPTIONS ## Options -{{% include "functions/_common/highlighting-options" %}} +{{% include "_common/syntax-highlighting-options.md" %}} diff --git a/content/en/functions/transform/HighlightCodeBlock.md b/content/en/functions/transform/HighlightCodeBlock.md index dc396bad0..bbebf9459 100644 --- a/content/en/functions/transform/HighlightCodeBlock.md +++ b/content/en/functions/transform/HighlightCodeBlock.md @@ -3,13 +3,11 @@ title: transform.HighlightCodeBlock description: Highlights code received in context within a code block render hook. categories: [] keywords: [] -action: - aliases: [] - related: - - functions/transform/CanHighlight - - functions/transform/Highlight - returnType: highlight.HighlightResult - signatures: ['transform.HighlightCodeBlock CONTEXT [OPTIONS]'] +params: + functions_and_methods: + aliases: [] + returnType: highlight.HighlightResult + signatures: ['transform.HighlightCodeBlock CONTEXT [OPTIONS]'] --- This function is only useful within a code block render hook. diff --git a/content/en/functions/transform/Markdownify.md b/content/en/functions/transform/Markdownify.md index 7a84f43b7..c22de1efe 100644 --- a/content/en/functions/transform/Markdownify.md +++ b/content/en/functions/transform/Markdownify.md @@ -3,13 +3,11 @@ title: transform.Markdownify description: Renders Markdown to HTML. categories: [] keywords: [] -action: - aliases: [markdownify] - related: - - methods/page/RenderString - - methods/page/RenderShortcodes - returnType: template.HTML - signatures: [transform.Markdownify INPUT] +params: + functions_and_methods: + aliases: [markdownify] + returnType: template.HTML + signatures: [transform.Markdownify INPUT] aliases: [/functions/markdownify] --- @@ -21,11 +19,9 @@ If the resulting HTML is a single paragraph, Hugo removes the wrapping `p` tags To keep the wrapping `p` tags for a single paragraph, use the [`RenderString`] method on the `Page` object, setting the `display` option to `block`. -[`RenderString`]: /methods/page/renderstring/ +> [!note] +> Although the `markdownify` function honors [Markdown render hooks] when rendering Markdown to HTML, use the `RenderString` method instead of `markdownify` if a render hook accesses `.Page` context. See issue [#9692] for details. -{{% note %}} -Although the `markdownify` function honors [Markdown render hooks] when rendering Markdown to HTML, use the `RenderString` method instead of `markdownify` if a render hook accesses `.Page` context. See issue [#9692] for details. - -[Markdown render hooks]: /render-hooks/ [#9692]: https://github.com/gohugoio/hugo/issues/9692 -{{% /note %}} +[`RenderString`]: /methods/page/renderstring/ +[Markdown render hooks]: /render-hooks/ diff --git a/content/en/functions/transform/Plainify.md b/content/en/functions/transform/Plainify.md index 681d41f72..780cf461a 100644 --- a/content/en/functions/transform/Plainify.md +++ b/content/en/functions/transform/Plainify.md @@ -3,11 +3,11 @@ title: transform.Plainify description: Returns a string with all HTML tags removed. categories: [] keywords: [] -action: - aliases: [plainify] - related: [] - returnType: template.HTML - signatures: [transform.Plainify INPUT] +params: + functions_and_methods: + aliases: [plainify] + returnType: template.HTML + signatures: [transform.Plainify INPUT] aliases: [/functions/plainify] --- diff --git a/content/en/functions/transform/PortableText.md b/content/en/functions/transform/PortableText.md new file mode 100644 index 000000000..7baba99d4 --- /dev/null +++ b/content/en/functions/transform/PortableText.md @@ -0,0 +1,213 @@ +--- +title: transform.PortableText +description: Converts Portable Text to Markdown. +categories: [] +keywords: [] +params: + functions_and_methods: + returnType: string + signatures: [transform.PortableText MAP] +--- + +{{< new-in "0.145.0" />}} + +[Portable Text](https://www.portabletext.org/) is a JSON structure that represent rich text content in the [Sanity](https://www.sanity.io/) CMS. In Hugo, this function is typically used in a [Content Adapter](https://gohugo.io/content-management/content-adapters/) that creates pages from Sanity data. + +## Types supported + +- `block` and `span` +- `image`. Note that the image handling is currently very simple; we link to the `asset.url` using `asset.altText` as the image alt text and `asset.title` as the title. For more fine grained control you may want to process the images in a [image render hook](/render-hooks/images/). +- `code` (see the [code-input](https://www.sanity.io/plugins/code-input) plugin). Code will be rendered as [fenced code blocks](/contribute/documentation/#fenced-code-blocks) with any file name provided passed on as a markdown attribute. + +> [!note] +> Since the Portable Text gets converted to Markdown before it gets passed to Hugo, rendering of links, headings, images and code blocks can be controlled with [Render Hooks](https://gohugo.io/render-hooks/). + +## Example + +### Content Adapter + +```go-html-template {file="content/_content.gotmpl" copy=true} +{{ $projectID := "mysanityprojectid" }} +{{ $useCached := true }} +{{ $api := "api" }} +{{ if $useCached }} + {{/* See https://www.sanity.io/docs/api-cdn */}} + {{ $api = "apicdn" }} +{{ end }} +{{ $url := printf "https://%s.%s.sanity.io/v2021-06-07/data/query/production" $projectID $api }} + +{{/* prettier-ignore-start */ -}} +{{ $q := `*[_type == 'post']{ + title, publishedAt, summary, slug, body[]{ + ..., + _type == "image" => { + ..., + asset->{ + _id, + path, + url, + altText, + title, + description, + metadata { + dimensions { + aspectRatio, + width, + height + } + } + } + } + }, + }` +}} +{{/* prettier-ignore-end */ -}} +{{ $body := dict "query" $q | jsonify }} +{{ $opts := dict "method" "post" "body" $body }} +{{ $r := resources.GetRemote $url $opts }} +{{ $m := $r | transform.Unmarshal }} +{{ $result := $m.result }} +{{ range $result }} + {{ if not .slug }} + {{ continue }} + {{ end }} + {{ $markdown := transform.PortableText .body }} + {{ $content := dict + "mediaType" "text/markdown" + "value" $markdown + }} + {{ $params := dict + "portabletext" (.body | jsonify (dict "indent" " ")) + }} + {{ $page := dict + "content" $content + "kind" "page" + "path" .slug.current + "title" .title + "date" (.publishedAt | time ) + "summary" .summary + "params" $params + }} + {{ $.AddPage $page }} +{{ end }} +``` + +### Sanity setup + +Below outlines a suitable Sanity studio setup for the above example. + +```ts {file="sanity.config.ts" copy=true} +import {defineConfig} from 'sanity' +import {structureTool} from 'sanity/structure' +import {visionTool} from '@sanity/vision' +import {schemaTypes} from './schemaTypes' +import {media} from 'sanity-plugin-media' +import {codeInput} from '@sanity/code-input' + +export default defineConfig({ + name: 'default', + title: 'my-sanity-project', + + projectId: 'mysanityprojectid', + dataset: 'production', + + plugins: [structureTool(), visionTool(), media(),codeInput()], + + schema: { + types: schemaTypes, + }, +}) +``` + +Type/schema definition: + +```ts {file="schemaTypes/postType.ts" copy=true} +import {defineField, defineType} from 'sanity' + +export const postType = defineType({ + name: 'post', + title: 'Post', + type: 'document', + fields: [ + defineField({ + name: 'title', + type: 'string', + validation: (rule) => rule.required(), + }), + defineField({ + name: 'summary', + type: 'string', + validation: (rule) => rule.required(), + }), + defineField({ + name: 'slug', + type: 'slug', + options: {source: 'title'}, + validation: (rule) => rule.required(), + }), + defineField({ + name: 'publishedAt', + type: 'datetime', + initialValue: () => new Date().toISOString(), + validation: (rule) => rule.required(), + }), + defineField({ + name: 'body', + type: 'array', + of: [ + { + type: 'block', + }, + { + type: 'image' + }, + { + type: 'code', + options: { + language: 'css', + languageAlternatives: [ + {title: 'HTML', value: 'html'}, + {title: 'CSS', value: 'css'}, + ], + withFilename: true, + }, + }, + ], + }), + ], +}) +``` + +Note that the above requires some additional plugins to be installed: + +```bash +npm i sanity-plugin-media @sanity/code-input +``` + +```ts {file="schemaTypes/index.ts" copy=true} +import {postType} from './postType' + +export const schemaTypes = [postType] +``` + +## Server setup + +Unfortunately, Sanity's API does not support [RFC 7234](https://tools.ietf.org/html/rfc7234) and their output changes even if the data has not. A recommended setup is therefore to use their cached `apicdn` endpoint (see above) and then set up a reasonable polling and file cache strategy in your Hugo configuration, e.g: + +{{< code-toggle file=hugo >}} +[HTTPCache] + [[HTTPCache.polls]] + disable = false + low = '30s' + high = '3m' + [HTTPCache.polls.for] + includes = ['https://*.*.sanity.io/**'] + +[caches.getresource] + dir = ':cacheDir/:project' + maxAge = "5m" +{{< /code-toggle >}} + +The polling above will be used when running the server/watch mode and rebuild when you push new content in Sanity. + +See [Caching in resources.GetRemote](/functions/resources/getremote/#caching) for more fine grained control. diff --git a/content/en/functions/transform/Remarshal.md b/content/en/functions/transform/Remarshal.md index 24ef4381d..ecf7fc905 100644 --- a/content/en/functions/transform/Remarshal.md +++ b/content/en/functions/transform/Remarshal.md @@ -3,23 +3,20 @@ title: transform.Remarshal description: Marshals a string of serialized data, or a map, into a string of serialized data in the specified format. categories: [] keywords: [] -action: - aliases: [] - related: - - functions/encoding/Jsonify - - functions/transform/Unmarshal - returnType: string - signatures: [transform.Remarshal FORMAT INPUT] +params: + functions_and_methods: + aliases: [] + returnType: string + signatures: [transform.Remarshal FORMAT INPUT] aliases: [/functions/transform.remarshal] --- The format must be one of `json`, `toml`, `yaml`, or `xml`. If the input is a string of serialized data, it must be valid JSON, TOML, YAML, or XML. -{{% note %}} -This function is primarily a helper for Hugo's documentation, used to convert configuration and front matter examples to JSON, TOML, and YAML. - -This is not a general purpose converter, and may change without notice if required for Hugo's documentation site. -{{% /note %}} +> [!note] +> This function is primarily a helper for Hugo's documentation, used to convert configuration and front matter examples to JSON, TOML, and YAML. +> +> This is not a general purpose converter, and may change without notice if required for Hugo's documentation site. Example 1 : Convert a string of TOML to JSON. diff --git a/content/en/functions/transform/ToMath.md b/content/en/functions/transform/ToMath.md index 10cd256c5..a9f12c546 100644 --- a/content/en/functions/transform/ToMath.md +++ b/content/en/functions/transform/ToMath.md @@ -2,35 +2,27 @@ title: transform.ToMath description: Renders mathematical equations and expressions written in the LaTeX markup language. categories: [] -keywords: [katex,latex,math,typesetting] -action: - aliases: [] - related: - - content-management/mathematics - returnType: types.Result[template.HTML] - signatures: ['transform.ToMath INPUT [OPTIONS]'] +keywords: [] +params: + functions_and_methods: + aliases: [] + returnType: types.Result[template.HTML] + signatures: ['transform.ToMath INPUT [OPTIONS]'] aliases: [/functions/tomath] -toc: true --- {{< new-in 0.132.0 />}} Hugo uses an embedded instance of the [KaTeX] display engine to render mathematical markup to HTML. You do not need to install the KaTeX display engine. -[KaTeX]: https://katex.org/ - ```go-html-template {{ transform.ToMath "c = \\pm\\sqrt{a^2 + b^2}" }} ``` -{{% note %}} -By default, Hugo renders mathematical markup to [MathML], and does not require any CSS to display the result. - -[MathML]: https://developer.mozilla.org/en-US/docs/Web/MathML - -To optimize rendering quality and accessibility, use the `htmlAndMathml` output option as described below. This approach requires an external stylesheet. - -{{% /note %}} +> [!note] +> By default, Hugo renders mathematical markup to [MathML], and does not require any CSS to display the result. +> +> To optimize rendering quality and accessibility, use the `htmlAndMathml` output option as described below. This approach requires an external stylesheet. ```go-html-template {{ $opts := dict "output" "htmlAndMathml" }} @@ -41,18 +33,14 @@ To optimize rendering quality and accessibility, use the `htmlAndMathml` output Pass a map of options as the second argument to the `transform.ToMath` function. The options below are a subset of the KaTeX [rendering options]. -[rendering options]: https://katex.org/docs/options.html - displayMode -: (`bool`) If `true` render in display mode, else render in inline mode. Default is `false`. +: (`bool`) Whether to render in display mode instead of inline mode. Default is `false`. errorColor : (`string`) The color of the error messages expressed as an RGB [hexadecimal color]. Default is `#cc0000`. -[hexadecimal color]: https://developer.mozilla.org/en-US/docs/Web/CSS/hex-color - fleqn -: (`bool`) If `true` render flush left with a 2em left margin. Default is `false`. +: (`bool`) Whether to render flush left with a 2em left margin. Default is `false`. macros : (`map`) A map of macros to be used in the math expression. Default is `{}`. @@ -78,7 +66,7 @@ output throwOnError -: (`bool`) If `true` throw a `ParseError` when KaTeX encounters an unsupported command or invalid LaTeX. Default is `true`. +: (`bool`) Whether to throw a `ParseError` when KaTeX encounters an unsupported command or invalid LaTeX. Default is `true`. ## Error handling @@ -94,12 +82,10 @@ 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 +### 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. -[passthrough extension]: /getting-started/configuration-markup/#passthrough - {{< code-toggle file=hugo copy=true >}} [markup.goldmark.extensions.passthrough] enable = true @@ -109,48 +95,45 @@ block = [['\[', '\]'], ['$$', '$$']] inline = [['\(', '\)']] {{< /code-toggle >}} -{{% note %}} -The configuration above precludes the use of the `$...$` delimiter pair for inline equations. Although you can add this delimiter pair to the configuration, you will need to double-escape the `$` symbol when used outside of math contexts to avoid unintended formatting. -{{% /note %}} +> [!note] +> The configuration above precludes the use of the `$...$` delimiter pair for inline equations. Although you can add this delimiter pair to the configuration, you will need to double-escape the `$` symbol when used outside of math contexts to avoid unintended formatting. -###### Step 2 +### Step 2 Create a [passthrough render hook] to capture and render the LaTeX markup. -[passthrough render hook]: /render-hooks/passthrough/ - -{{< code file=layouts/_default/_markup/render-passthrough.html copy=true >}} +```go-html-template {file="layouts/_default/_markup/render-passthrough.html" copy=true} {{- $opts := dict "output" "htmlAndMathml" "displayMode" (eq .Type "block") }} {{- with try (transform.ToMath .Inner $opts) }} {{- with .Err }} - {{ errorf "Unable to render mathematical markup to HTML using the transform.ToMath function. The KaTeX display engine threw the following error: %s: see %s." . $.Position }} + {{- errorf "Unable to render mathematical markup to HTML using the transform.ToMath function. The KaTeX display engine threw the following error: %s: see %s." . $.Position }} {{- else }} {{- .Value }} {{- $.Page.Store.Set "hasMath" true }} {{- end }} {{- end -}} -{{< /code >}} +``` -###### Step 3 +### Step 3 In your base template, conditionally include the KaTeX CSS within the head element. -{{< code file=layouts/_default/baseof.html copy=true >}} +```go-html-template {file="layouts/_default/baseof.html" copy=true} {{ $noop := .WordCount }} {{ if .Page.Store.Get "hasMath" }} {{ end }} -{{< /code >}} +``` In the above, note the use of a [noop](g) statement to force content rendering before we check the value of `hasMath` with the `Store.Get` method. -#### Step 4 +### Step 4 Add some mathematical markup to your content, then test. -{{< code file=content/example.md >}} +```text {file="content/example.md"} This is an inline \(a^*=x-b^*\) equation. These are block equations: @@ -158,4 +141,24 @@ These are block equations: \[a^*=x-b^*\] $$a^*=x-b^*$$ -{{< /code >}} +``` + +## Chemistry + +{{< new-in 0.144.0 />}} + +You can also use the `transform.ToMath` function to render chemical equations, leveraging the `\ce` and `\pu` functions from the [mhchem] package. + +```text +$$C_p[\ce{H2O(l)}] = \pu{75.3 J // mol K}$$ +``` + +$$C_p[\ce{H2O(l)}] = \pu{75.3 J // mol K}$$ + +[hexadecimal color]: https://developer.mozilla.org/en-US/docs/Web/CSS/hex-color +[KaTeX]: https://katex.org/ +[MathML]: https://developer.mozilla.org/en-US/docs/Web/MathML +[mhchem]: https://mhchem.github.io/MathJax-mhchem/ +[passthrough extension]: /configuration/markup/#passthrough +[passthrough render hook]: /render-hooks/passthrough/ +[rendering options]: https://katex.org/docs/options.html diff --git a/content/en/functions/transform/Unmarshal.md b/content/en/functions/transform/Unmarshal.md index e50fc0ee0..d159122f5 100644 --- a/content/en/functions/transform/Unmarshal.md +++ b/content/en/functions/transform/Unmarshal.md @@ -3,16 +3,11 @@ title: transform.Unmarshal description: Parses serialized data and returns a map or an array. Supports CSV, JSON, TOML, YAML, and XML. categories: [] keywords: [] -action: - aliases: [unmarshal] - related: - - functions/transform/Remarshal - - functions/resources/Get - - functions/resources/GetRemote - - functions/encoding/Jsonify - returnType: any - signatures: ['transform.Unmarshal [OPTIONS] INPUT'] -toc: true +params: + functions_and_methods: + aliases: [unmarshal] + returnType: any + signatures: ['transform.Unmarshal [OPTIONS] INPUT'] aliases: [/functions/transform.unmarshal] --- @@ -112,15 +107,12 @@ A remote resource is a file on a remote server, accessible via HTTP or HTTPS. {{ end }} ``` -{{% note %}} -When retrieving remote data, a misconfigured server may send a response header with an incorrect [Content-Type]. For example, the server may set the Content-Type header to `application/octet-stream` instead of `application/json`. - -In these cases, pass the resource `Content` through the `transform.Unmarshal` function instead of passing the resource itself. For example, in the above, do this instead: - -`{{ $data = .Content | transform.Unmarshal }}` - -[Content-Type]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Type -{{% /note %}} +> [!note] +> When retrieving remote data, a misconfigured server may send a response header with an incorrect [Content-Type]. For example, the server may set the Content-Type header to `application/octet-stream` instead of `application/json`. +> +> In these cases, pass the resource `Content` through the `transform.Unmarshal` function instead of passing the resource itself. For example, in the above, do this instead: +> +> `{{ $data = .Content | transform.Unmarshal }}` ## Options @@ -132,8 +124,9 @@ delimiter comment : (`string`) The comment character used in the CSV. If set, lines beginning with the comment character without preceding whitespace are ignored. -lazyQuotes {{< new-in 0.122.0 />}} -: (`bool`) If true, a quote may appear in an unquoted field and a non-doubled quote may appear in a quoted field. Default is `false`. +lazyQuotes +: {{< new-in 0.122.0 />}} +: (`bool`) Whether to allow a quote in an unquoted field, or to allow a non-doubled quote in a quoted field. Default is `false`. ```go-html-template {{ $csv := "a;b;c" | transform.Unmarshal (dict "delimiter" ";") }} @@ -296,4 +289,5 @@ Hugo renders this to: ``` [`index`]: /functions/collections/indexfunction/ +[Content-Type]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Type [page bundle]: /content-management/page-bundles/ diff --git a/content/en/functions/transform/XMLEscape.md b/content/en/functions/transform/XMLEscape.md index 291f0f622..9e6c77927 100644 --- a/content/en/functions/transform/XMLEscape.md +++ b/content/en/functions/transform/XMLEscape.md @@ -3,11 +3,11 @@ title: transform.XMLEscape description: Returns the given string, removing disallowed characters then escaping the result to its XML equivalent. categories: [] keywords: [] -action: - aliases: [] - related: [] - returnType: string - signatures: [transform.XMLEscape INPUT] +params: + functions_and_methods: + aliases: [] + returnType: string + signatures: [transform.XMLEscape INPUT] --- {{< new-in 0.121.0 />}} @@ -31,9 +31,9 @@ For example: When using `transform.XMLEscape` in a template rendered by Go's [html/template] package, declare the string to be safe HTML to avoid double escaping. For example, in an RSS template: -{{< code file="layouts/_default/rss.xml" >}} +```xml {file="layouts/_default/rss.xml"} {{ .Summary | transform.XMLEscape | safeHTML }} -{{< /code >}} +``` [disallowed characters]: https://www.w3.org/TR/xml/#charsets [html entities]: https://developer.mozilla.org/en-us/docs/glossary/entity diff --git a/content/en/functions/transform/_index.md b/content/en/functions/transform/_index.md index 70e286b24..19c271b65 100644 --- a/content/en/functions/transform/_index.md +++ b/content/en/functions/transform/_index.md @@ -1,12 +1,7 @@ --- title: Transform functions linkTitle: transform -description: Template functions to transform values from one format to another. +description: Use these functions to transform values from one format to another. categories: [] keywords: [] -menu: - docs: - parent: functions --- - -Use these functions to transform values from one format to another. diff --git a/content/en/functions/urls/AbsLangURL.md b/content/en/functions/urls/AbsLangURL.md index 67e1781e7..da45ca224 100644 --- a/content/en/functions/urls/AbsLangURL.md +++ b/content/en/functions/urls/AbsLangURL.md @@ -3,50 +3,56 @@ title: urls.AbsLangURL description: Returns an absolute URL with a language prefix, if any. categories: [] keywords: [] -action: - aliases: [absLangURL] - related: - - functions/urls/AbsURL - - functions/urls/RelLangURL - - functions/urls/RelURL - returnType: string - signatures: [urls.AbsLangURL INPUT] +params: + functions_and_methods: + aliases: [absLangURL] + returnType: string + signatures: [urls.AbsLangURL INPUT] 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 site configuration +- Whether the input begins with a slash (`/`) +- The `baseURL` in your site configuration - The language prefix, if any -In examples that follow, the project is multilingual with content in both English (`en`) and Spanish (`es`). The returned values are from the English site. +This is the site configuration for the examples that follow: -### Input does not begin with a slash +{{< code-toggle file=hugo >}} +defaultContentLanguage = 'en' +defaultContentLanguageInSubdir = true +[languages.en] +weight = 1 +[languages.es] +weight = 2 +{{< /code-toggle >}} + +## 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. -With `baseURL = https://example.org/` +When rendering the `en` site with `baseURL = https://example.org/` ```go-html-template -{{ absLangURL "" }} → https://example.org/en/ -{{ absLangURL "articles" }} → https://example.org/en/articles -{{ absLangURL "style.css" }} → https://example.org/en/style.css +{{ absLangURL "" }} → https://example.org/en/ +{{ absLangURL "articles" }} → https://example.org/en/articles +{{ absLangURL "style.css" }} → https://example.org/en/style.css ``` -With `baseURL = https://example.org/docs/` +When rendering the `en` site with `baseURL = https://example.org/docs/` ```go-html-template -{{ absLangURL "" }} → https://example.org/docs/en/ -{{ absLangURL "articles" }} → https://example.org/docs/en/articles -{{ absLangURL "style.css" }} → https://example.org/docs/en/style.css +{{ absLangURL "" }} → https://example.org/docs/en/ +{{ absLangURL "articles" }} → https://example.org/docs/en/articles +{{ absLangURL "style.css" }} → https://example.org/docs/en/style.css ``` -### Input begins with a slash +## 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. -With `baseURL = https://example.org/` +When rendering the `en` site with `baseURL = https://example.org/` ```go-html-template {{ absLangURL "/" }} → https://example.org/en/ @@ -54,10 +60,13 @@ With `baseURL = https://example.org/` {{ absLangURL "/style.css" }} → https://example.org/en/style.css ``` -With `baseURL = https://example.org/docs/` +When rendering the `en` site with `baseURL = https://example.org/docs/` ```go-html-template {{ absLangURL "/" }} → https://example.org/en/ {{ absLangURL "/articles" }} → https://example.org/en/articles {{ absLangURL "/style.css" }} → https://example.org/en/style.css ``` + +> [!note] +> As illustrated by the previous example, using a leading slash is rarely desirable and can lead to unexpected outcomes. In nearly all cases, omit the leading slash. diff --git a/content/en/functions/urls/AbsURL.md b/content/en/functions/urls/AbsURL.md index 1120eac42..72613cd0b 100644 --- a/content/en/functions/urls/AbsURL.md +++ b/content/en/functions/urls/AbsURL.md @@ -3,23 +3,20 @@ title: urls.AbsURL description: Returns an absolute URL. categories: [] keywords: [] -action: - aliases: [absURL] - related: - - functions/urls/AbsLangURL - - functions/urls/RelLangURL - - functions/urls/RelURL - returnType: string - signatures: [urls.AbsURL INPUT] +params: + functions_and_methods: + aliases: [absURL] + returnType: string + signatures: [urls.AbsURL INPUT] 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 site configuration +- Whether the input begins with a slash (`/`) +- The `baseURL` in your site configuration -### Input does not begin with a slash +## 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. @@ -39,7 +36,7 @@ With `baseURL = https://example.org/docs/` {{ absURL "style.css" }} → https://example.org/docs/style.css ``` -#### Input begins with a slash +## 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. @@ -59,4 +56,7 @@ With `baseURL = https://example.org/docs/` {{ absURL "/style.css" }} → https://example.org/style.css ``` +> [!note] +> As illustrated by the previous example, using a leading slash is rarely desirable and can lead to unexpected outcomes. In nearly all cases, omit the leading slash. + [`urls.AbsLangURL`]: /functions/urls/abslangurl/ diff --git a/content/en/functions/urls/Anchorize.md b/content/en/functions/urls/Anchorize.md index d8866ae05..d18bd9a4d 100644 --- a/content/en/functions/urls/Anchorize.md +++ b/content/en/functions/urls/Anchorize.md @@ -3,16 +3,15 @@ title: urls.Anchorize description: Returns the given string, sanitized for usage in an HTML id attribute. categories: [] keywords: [] -action: - aliases: [anchorize] - related: - - functions/urls/URLize - returnType: string - signatures: [urls.Anchorize INPUT] +params: + functions_and_methods: + aliases: [anchorize] + returnType: string + signatures: [urls.Anchorize INPUT] aliases: [/functions/anchorize] --- -{{% include "/functions/urls/_common/anchorize-vs-urlize.md" %}} +{{% include "/_common/functions/urls/anchorize-vs-urlize.md" %}} ## Sanitizing logic @@ -31,7 +30,7 @@ github : Compatible with GitHub. This is the default. github-ascii -: Similar to the `github` setting, but removes non-ASCII characters. +: Similar to the `github` setting, but removes non-ASCII characters. blackfriday : Provided for backwards compatibility with Hugo v0.59.1 and earlier. This option will be removed in a future release. diff --git a/content/en/functions/urls/JoinPath.md b/content/en/functions/urls/JoinPath.md index bdff5f4b2..b9da7e437 100644 --- a/content/en/functions/urls/JoinPath.md +++ b/content/en/functions/urls/JoinPath.md @@ -3,12 +3,11 @@ title: urls.JoinPath description: Joins the provided elements into a URL string and cleans the result of any ./ or ../ elements. If the argument list is empty, JoinPath returns an empty string. categories: [] keywords: [] -action: - aliases: [] - related: - - functions/path/Join - returnType: string - signatures: [urls.JoinPath ELEMENT...] +params: + functions_and_methods: + aliases: [] + returnType: string + signatures: [urls.JoinPath ELEMENT...] aliases: [/functions/urls.joinpath] --- diff --git a/content/en/functions/urls/Parse.md b/content/en/functions/urls/Parse.md index a64116254..7def5fb1d 100644 --- a/content/en/functions/urls/Parse.md +++ b/content/en/functions/urls/Parse.md @@ -3,11 +3,11 @@ title: urls.Parse description: Parses a URL into a URL structure. categories: [] keywords: [] -action: - aliases: [] - related: [] - returnType: url.URL - signatures: [urls.Parse URL] +params: + functions_and_methods: + aliases: [] + returnType: url.URL + signatures: [urls.Parse URL] aliases: [/functions/urls.parse] --- @@ -26,6 +26,7 @@ The `urls.Parse` function parses a URL into a [URL structure](https://godoc.org/ {{ $u.Hostname }} → example.org {{ $u.RequestURI }} → /foo?a=6&b=7 {{ $u.Path }} → /foo +{{ $u.RawQuery }} → a=6&b=7 {{ $u.Query }} → map[a:[6] b:[7]] {{ $u.Query.a }} → [6] {{ $u.Query.Get "a" }} → 6 diff --git a/content/en/functions/urls/Ref.md b/content/en/functions/urls/Ref.md index d8fe6f26c..92abed91a 100644 --- a/content/en/functions/urls/Ref.md +++ b/content/en/functions/urls/Ref.md @@ -1,63 +1,46 @@ --- title: urls.Ref -description: Returns the absolute permalink to a page at the given path. +description: Returns the absolute URL of the page with the given path, language, and output format. categories: [] keywords: [] -action: - aliases: [ref] - related: - - functions/urls/RelRef - - methods/page/Ref - - methods/page/RelRef - returnType: string - signatures: - - urls.Ref PAGE PATH - - urls.Ref PAGE OPTIONS +params: + functions_and_methods: + aliases: [ref] + returnType: string + signatures: + - urls.Ref PAGE PATH + - urls.Ref PAGE OPTIONS aliases: [/functions/ref] --- -The first argument is the context of the page from which to resolve relative paths, typically the current page. +## Usage -The second argument is a path to a page, with or without a file extension, with or without an anchor. A path without a leading `/` is first resolved relative to the given context, then to the remainder of the site. Alternatively, provide an [options map](#options) instead of a path. +The `ref` function takes two arguments: -```go-html-template -{{ ref . "about" }} -{{ ref . "about#anchor" }} -{{ ref . "about.md" }} -{{ ref . "about.md#anchor" }} -{{ ref . "#anchor" }} -{{ ref . "/blog/my-post" }} -{{ ref . "/blog/my-post.md" }} -``` +1. The context for resolving relative paths (typically the current page). +1. Either the target page's path or an options map (see below). ## Options -Instead of specifying a path, you can also provide an options map: +{{% include "_common/ref-and-relref-options.md" %}} -path -: (`string`) The path to the page, relative to the `content` directory. Required. +## Examples -lang -: (`string`) The language (site) to search for the page. Default is the current language. Optional. - -outputFormat -: (`string`) The output format to search for the page. Default is the current output format. Optional. - -To return the absolute permalink to another language version of a page: +The following examples show the rendered output for a page on the English version of the site: ```go-html-template -{{ ref . (dict "path" "about.md" "lang" "fr") }} +{{ ref . "/books/book-1" }} → https://example.org/en/books/book-1/ + +{{ $opts := dict "path" "/books/book-1" }} +{{ ref . $opts }} → https://example.org/en/books/book-1/ + +{{ $opts := dict "path" "/books/book-1" "lang" "de" }} +{{ ref . $opts }} → https://example.org/de/books/book-1/ + +{{ $opts := dict "path" "/books/book-1" "lang" "de" "outputFormat" "json" }} +{{ ref . $opts }} → https://example.org/de/books/book-1/index.json ``` -To return the absolute permalink to another Output Format of a page: +## Error handling -```go-html-template -{{ ref . (dict "path" "about.md" "outputFormat" "rss") }} -``` - -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. - -{{< code-toggle file=hugo >}} -refLinksErrorLevel = 'warning' -refLinksNotFoundURL = '/some/other/url' -{{< /code-toggle >}} +{{% include "_common/ref-and-relref-error-handling.md" %}} diff --git a/content/en/functions/urls/RelLangURL.md b/content/en/functions/urls/RelLangURL.md index 883e7dda2..af8bff3d7 100644 --- a/content/en/functions/urls/RelLangURL.md +++ b/content/en/functions/urls/RelLangURL.md @@ -3,52 +3,66 @@ title: urls.RelLangURL description: Returns a relative URL with a language prefix, if any. categories: [] keywords: [] -action: - aliases: [relLangURL] - related: - - functions/urls/AbsLangURL - - functions/urls/AbsURL - - functions/urls/RelURL - returnType: string - signatures: [urls.RelLangURL INPUT] +params: + functions_and_methods: + aliases: [relLangURL] + returnType: string + signatures: [urls.RelLangURL INPUT] 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 +- Whether the input begins with a slash (`/`) - The `baseURL` in your site configuration - The language prefix, if any -In examples that follow, the project is multilingual with content in both English (`en`) and Spanish (`es`). The returned values are from the English site. +This is the site configuration for the examples that follow: -### Input does not begin with a slash +{{< code-toggle file=hugo >}} +defaultContentLanguage = 'en' +defaultContentLanguageInSubdir = true +[languages.en] +weight = 1 +[languages.es] +weight = 2 +{{< /code-toggle >}} + +## 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. -With `baseURL = https://example.org/` +When rendering the `en` site with `baseURL = https://example.org/` ```go-html-template -{{ relLangURL "" }} → /en/ -{{ relLangURL "articles" }} → /en/articles -{{ relLangURL "style.css" }} → /en/style.css -{{ relLangURL "https://example.org/foo" }} → /en/foo +{{ relLangURL "" }} → /en/ +{{ relLangURL "articles" }} → /en/articles +{{ relLangURL "style.css" }} → /en/style.css +{{ relLangURL "https://example.org" }} → https://example.org +{{ relLangURL "https://example.org/" }} → /en +{{ relLangURL "https://www.example.org" }} → https://www.example.org +{{ relLangURL "https://www.example.org/" }} → https://www.example.org/ ``` -With `baseURL = https://example.org/docs/` +When rendering the `en` site with `baseURL = https://example.org/docs/` ```go-html-template -{{ relLangURL "" }} → /docs/en/ -{{ relLangURL "articles" }} → /docs/en/articles -{{ relLangURL "style.css" }} → /docs/en/style.css -{{ relLangURL "https://example.org/docs/foo" }} → /docs/en/foo +{{ relLangURL "" }} → /docs/en/ +{{ relLangURL "articles" }} → /docs/en/articles +{{ relLangURL "style.css" }} → /docs/en/style.css +{{ relLangURL "https://example.org" }} → https://example.org +{{ relLangURL "https://example.org/" }} → https://example.org/ +{{ relLangURL "https://example.org/docs" }} → https://example.org/docs +{{ relLangURL "https://example.org/docs/" }} → /docs/en +{{ relLangURL "https://www.example.org" }} → https://www.example.org +{{ relLangURL "https://www.example.org/" }} → https://www.example.org/ ``` -#### Input begins with a slash +## 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. -With `baseURL = https://example.org/` +When rendering the `en` site with `baseURL = https://example.org/` ```go-html-template {{ relLangURL "/" }} → /en/ @@ -56,10 +70,13 @@ With `baseURL = https://example.org/` {{ relLangURL "/style.css" }} → /en/style.css ``` -With `baseURL = https://example.org/docs/` +When rendering the `en` site with `baseURL = https://example.org/docs/` ```go-html-template {{ relLangURL "/" }} → /en/ {{ relLangURL "/articles" }} → /en/articles {{ relLangURL "/style.css" }} → /en/style.css ``` + +> [!note] +> As illustrated by the previous example, using a leading slash is rarely desirable and can lead to unexpected outcomes. In nearly all cases, omit the leading slash. diff --git a/content/en/functions/urls/RelRef.md b/content/en/functions/urls/RelRef.md index 74e1b5650..aa7acf50b 100644 --- a/content/en/functions/urls/RelRef.md +++ b/content/en/functions/urls/RelRef.md @@ -1,70 +1,46 @@ --- title: urls.RelRef -description: Returns the relative permalink to a page at the given path. +description: Returns the relative URL of the page with the given path, language, and output format. categories: [] keywords: [] -action: - aliases: [relref] - related: - - functions/urls/Ref - - methods/page/Ref - - methods/page/RelRef - returnType: string - signatures: - - urls.RelRef PAGE PATH - - urls.RelRef PAGE OPTIONS +params: + functions_and_methods: + aliases: [relref] + returnType: string + signatures: + - urls.RelRef PAGE PATH + - urls.RelRef PAGE OPTIONS aliases: [/functions/relref] --- -The first argument is the context of the page from which to resolve relative paths, typically the current page. +## Usage -The second argument is a path to a page, with or without a file extension, with or without an anchor. A path without a leading `/` is first resolved relative to the given context, then to the remainder of the site. Alternatively, provide an [options map](#options) instead of a path. -. -```go-html-template -{{ relref . "about" }} -{{ relref . "about#anchor" }} -{{ relref . "about.md" }} -{{ relref . "about.md#anchor" }} -{{ relref . "#anchor" }} -{{ relref . "/blog/my-post" }} -{{ relref . "/blog/my-post.md" }} -``` +The `relref` function takes two arguments: -The permalink returned is relative to the protocol+host portion of the baseURL specified in the site configuration. For example: - -Code|baseURL|Permalink -:--|:--|:-- -`{{ relref . "/about" }}`|`https://example.org/`|`/about/` -`{{ relref . "/about" }}`|`https://example.org/x/`|`/x/about/` +1. The context for resolving relative paths (typically the current page). +1. Either the target page's path or an options map (see below). ## Options -Instead of specifying a path, you can also provide an options map: +{{% include "_common/ref-and-relref-options.md" %}} -path -: (`string`) The path to the page, relative to the `content` directory. Required. +## Examples -lang -: (`string`) The language (site) to search for the page. Default is the current language. Optional. - -outputFormat -: (`string`) The output format to search for the page. Default is the current output format. Optional. - -To return the relative permalink to another language version of a page: +The following examples show the rendered output for a page on the English version of the site: ```go-html-template -{{ relref . (dict "path" "about.md" "lang" "fr") }} +{{ relref . "/books/book-1" }} → /en/books/book-1/ + +{{ $opts := dict "path" "/books/book-1" }} +{{ relref . $opts }} → /en/books/book-1/ + +{{ $opts := dict "path" "/books/book-1" "lang" "de" }} +{{ relref . $opts }} → /de/books/book-1/ + +{{ $opts := dict "path" "/books/book-1" "lang" "de" "outputFormat" "json" }} +{{ relref . $opts }} → /de/books/book-1/index.json ``` -To return the relative permalink to another Output Format of a page: +## Error handling -```go-html-template -{{ relref . (dict "path" "about.md" "outputFormat" "rss") }} -``` - -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. - -{{< code-toggle file=hugo >}} -refLinksErrorLevel = 'warning' -refLinksNotFoundURL = '/some/other/url' -{{< /code-toggle >}} +{{% include "_common/ref-and-relref-error-handling.md" %}} diff --git a/content/en/functions/urls/RelURL.md b/content/en/functions/urls/RelURL.md index 18ac24d10..0aef4043f 100644 --- a/content/en/functions/urls/RelURL.md +++ b/content/en/functions/urls/RelURL.md @@ -3,45 +3,50 @@ title: urls.RelURL description: Returns a relative URL. categories: [] keywords: [] -action: - aliases: [relURL] - related: - - functions/urls/AbsLangURL - - functions/urls/AbsURL - - functions/urls/RelLangURL - returnType: string - signatures: [urls.RelURL INPUT] +params: + functions_and_methods: + aliases: [relURL] + returnType: string + signatures: [urls.RelURL INPUT] 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 +- Whether the input begins with a slash (`/`) - The `baseURL` in your site configuration -### Input does not begin with a slash +## 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. With `baseURL = https://example.org/` ```go-html-template -{{ relURL "" }} → / -{{ relURL "articles" }} → /articles -{{ relURL "style.css" }} → /style.css -{{ relURL "https://example.org/foo" }} → /foo +{{ relURL "" }} → / +{{ relURL "articles" }} → /articles +{{ relURL "style.css" }} → /style.css +{{ relURL "https://example.org" }} → https://example.org +{{ relURL "https://example.org/" }} → / +{{ relURL "https://www.example.org" }} → https://www.example.org +{{ relURL "https://www.example.org/" }} → https://www.example.org/ ``` With `baseURL = https://example.org/docs/` ```go-html-template -{{ relURL "" }} → /docs/ -{{ relURL "articles" }} → /docs/articles -{{ relURL "style.css" }} → /docs/style.css -{{ relURL "https://example.org/docs/foo" }} → /docs/foo +{{ relURL "" }} → /docs/ +{{ relURL "articles" }} → /docs/articles +{{ relURL "style.css" }} → /docs/style.css +{{ relURL "https://example.org" }} → https://example.org +{{ relURL "https://example.org/" }} → https://example.org/ +{{ relURL "https://example.org/docs" }} → https://example.org/docs +{{ relURL "https://example.org/docs/" }} → /docs +{{ relURL "https://www.example.org" }} → https://www.example.org +{{ relURL "https://www.example.org/" }} → https://www.example.org/ ``` -#### Input begins with a slash +## 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. @@ -61,4 +66,7 @@ With `baseURL = https://example.org/docs/` {{ relURL "/style.css" }} → /style.css ``` +> [!note] +> As illustrated by the previous example, using a leading slash is rarely desirable and can lead to unexpected outcomes. In nearly all cases, omit the leading slash. + [`urls.RelLangURL`]: /functions/urls/rellangurl/ diff --git a/content/en/functions/urls/URLize.md b/content/en/functions/urls/URLize.md index 12e5203c4..b0cc812ec 100644 --- a/content/en/functions/urls/URLize.md +++ b/content/en/functions/urls/URLize.md @@ -3,16 +3,15 @@ title: urls.URLize description: Returns the given string, sanitized for usage in a URL. categories: [] keywords: [] -action: - aliases: [urlize] - related: - - functions/urls/Anchorize - returnType: string - signatures: [urls.URLize INPUT] +params: + functions_and_methods: + aliases: [urlize] + returnType: string + signatures: [urls.URLize INPUT] aliases: [/functions/urlize] --- -{{% include "/functions/urls/_common/anchorize-vs-urlize.md" %}} +{{% include "/_common/functions/urls/anchorize-vs-urlize.md" %}} ## Example diff --git a/content/en/functions/urls/_common/_index.md b/content/en/functions/urls/_common/_index.md deleted file mode 100644 index 4328d4d14..000000000 --- a/content/en/functions/urls/_common/_index.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -cascade: - _build: - list: never - publishResources: false - render: never ---- - - diff --git a/content/en/functions/urls/_index.md b/content/en/functions/urls/_index.md index 5f16feeeb..3a1962d7a 100644 --- a/content/en/functions/urls/_index.md +++ b/content/en/functions/urls/_index.md @@ -1,12 +1,7 @@ --- title: URL functions linkTitle: urls -description: Template functions to work with URLs. +description: Use these functions to work with URLs. categories: [] keywords: [] -menu: - docs: - parent: functions --- - -Use these functions to work with URLs. diff --git a/content/en/getting-started/_index.md b/content/en/getting-started/_index.md index ca180d999..2e2f57127 100644 --- a/content/en/getting-started/_index.md +++ b/content/en/getting-started/_index.md @@ -1,20 +1,8 @@ --- title: Getting started - description: How to get started with Hugo. categories: [] keywords: [] -menu: - docs: - identifier: getting-started-in-this-section - parent: getting-started - weight: 10 weight: 10 aliases: [/overview/introduction/] --- - -If this is your first time using Hugo and you've [already installed Hugo on your machine][installed], we recommend the [quick start]. You can also use [external learning resources] to learn Hugo. - -[installed]: /installation/ -[quick start]: /getting-started/quick-start/ -[external learning resources]: /getting-started/external-learning-resources/ diff --git a/content/en/getting-started/configuration-build.md b/content/en/getting-started/configuration-build.md deleted file mode 100644 index 791d4bb99..000000000 --- a/content/en/getting-started/configuration-build.md +++ /dev/null @@ -1,85 +0,0 @@ ---- -title: Configure build -description: Configure global build options. -categories: [getting started,fundamentals] -keywords: [build,buildStats,cache] -menu: - docs: - parent: getting-started - weight: 70 -weight: 70 -slug: configuration-build -toc: true ---- - -The `build` configuration section contains global build-related configuration options. - -{{< code-toggle config=build />}} - -###### buildStats - -See [Configure buildStats](#configure-build-stats). - -###### cachebusters - -See [Configure Cache Busters](#configure-cache-busters). - -###### noJSConfigInAssets - -(`bool`) If `true`, turns off writing a `jsconfig.json` into your `assets` directory with mapping of imports from running [js.Build](/hugo-pipes/js). This file is intended to help with intellisense/navigation inside code editors such as [VS Code](https://code.visualstudio.com/). Note that if you do not use `js.Build`, no file will be written. - -###### useResourceCacheWhen - -(`string`) When to use the resource file cache, one of `never`, `fallback`, or `always`. Applicable when transpiling Sass to CSS. Default is `fallback`. - -## Configure cache busters - -The `build.cachebusters` configuration option was added to support development using Tailwind 3.x's JIT compiler where a `build` configuration may look like this: - -{{< code-toggle file=hugo >}} -[build] - [build.buildStats] - enable = true - [[build.cachebusters]] - source = "assets/watching/hugo_stats\\.json" - target = "styles\\.css" - [[build.cachebusters]] - source = "(postcss|tailwind)\\.config\\.js" - target = "css" - [[build.cachebusters]] - source = "assets/.*\\.(js|ts|jsx|tsx)" - target = "js" - [[build.cachebusters]] - source = "assets/.*\\.(.*)$" - target = "$1" -{{< /code-toggle >}} - -When `buildStats` {{< new-in 0.115.1 />}} is enabled, Hugo writes a `hugo_stats.json` file on each build with HTML classes etc. that's used in the rendered output. Changes to this file will trigger a rebuild of the `styles.css` file. You also need to add `hugo_stats.json` to Hugo's server watcher. See [Hugo Starter Tailwind Basic](https://github.com/bep/hugo-starter-tailwind-basic) for a running example. - -source -: A regexp matching file(s) relative to one of the virtual component directories in Hugo, typically `assets/...`. - -target -: A regexp matching the keys in the resource cache that should be expired when `source` changes. You can use the matching regexp groups from `source` in the expression, e.g. `$1`. - -## Configure build stats - -{{< code-toggle config=build.buildStats />}} - -{{< new-in 0.115.1 />}} - -If `enable` is set to `true`, creates a `hugo_stats.json` file in the root of your project. This file contains arrays of the `class` attributes, `id` attributes, and tags of every HTML element within your published site. Use this file as data source when [removing unused CSS] from your site. This process is also known as pruning, purging, or tree shaking. - -[removing unused CSS]: /functions/resources/postprocess/ - -Exclude `class` attributes, `id` attributes, or tags from `hugo_stats.json` with the `disableClasses`, `disableIDs`, and `disableTags` keys. - -{{% note %}} -Given that CSS purging is typically limited to production builds, place the `buildStats` object below [`config/production`]. - -[`config/production`]: /getting-started/configuration/#configuration-directory - -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. -{{% /note %}} - -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. diff --git a/content/en/getting-started/configuration-markup.md b/content/en/getting-started/configuration-markup.md deleted file mode 100644 index ef885e44b..000000000 --- a/content/en/getting-started/configuration-markup.md +++ /dev/null @@ -1,387 +0,0 @@ ---- -title: Configure markup -description: Configure rendering of markup to HTML. -categories: [getting started,fundamentals] -keywords: [markup,markdown,goldmark,asciidoc,asciidoctor,highlighting] -menu: - docs: - parent: getting-started - weight: 60 -weight: 60 -slug: configuration-markup -toc: true ---- - -## Default handler - -Hugo uses [Goldmark] to render Markdown to HTML. - -{{< code-toggle file=hugo >}} -[markup] -defaultMarkdownHandler = 'goldmark' -{{< /code-toggle >}} - -Files with a `.md`, `.mdown`, or `.markdown` extension are processed as Markdown, provided that you have not specified a different [content format] using the `markup` field in front matter. - -To use a different renderer for Markdown files, specify one of `asciidocext`, `org`, `pandoc`, or `rst` in your site configuration. - -defaultMarkdownHandler|Description -:--|:-- -`asciidocext`|[AsciiDoc] -`goldmark`|[Goldmark] -`org`|[Emacs Org Mode] -`pandoc`|[Pandoc] -`rst`|[reStructuredText] - -To use AsciiDoc, Pandoc, or reStructuredText you must install the relevant renderer and update your [security policy]. - -{{% note %}} -Unless you need a unique capability provided by one of the alternative Markdown handlers, we strongly recommend that you use the default setting. Goldmark is fast, well maintained, conforms to the [CommonMark] specification, and is compatible with [GitHub Flavored Markdown] (GFM). - -[commonmark]: https://spec.commonmark.org/0.30/ -[github flavored markdown]: https://github.github.com/gfm/ -{{% /note %}} - -[asciidoc]: https://asciidoc.org/ -[content format]: /content-management/formats/#formats -[emacs org mode]: https://orgmode.org/ -[goldmark]: https://github.com/yuin/goldmark/ -[pandoc]: https://pandoc.org/ -[restructuredtext]: https://docutils.sourceforge.io/rst.html -[security policy]: /about/security/#security-policy - -## Goldmark - -This is the default configuration for the Goldmark Markdown renderer: - -{{< code-toggle config=markup.goldmark />}} - -### Goldmark extensions - -The extensions below, excluding Extras and Passthrough, are enabled by default. - -Extension|Documentation|Enabled -:--|:--|:-: -cjk|[Goldmark Extensions: CJK]|:heavy_check_mark: -definitionList|[PHP Markdown Extra: Definition lists]|:heavy_check_mark: -extras|[Hugo Goldmark Extensions: Extras]| -footnote|[PHP Markdown Extra: Footnotes]|:heavy_check_mark: -linkify|[GitHub Flavored Markdown: Autolinks]|:heavy_check_mark: -passthrough|[Hugo Goldmark Extensions: Passthrough]| -strikethrough|[GitHub Flavored Markdown: Strikethrough]|:heavy_check_mark: -table|[GitHub Flavored Markdown: Tables]|:heavy_check_mark: -taskList|[GitHub Flavored Markdown: Task list items]|:heavy_check_mark: -typographer|[Goldmark Extensions: Typographer]|:heavy_check_mark: - -[GitHub Flavored Markdown: Autolinks]: https://github.github.com/gfm/#autolinks-extension- -[GitHub Flavored Markdown: Strikethrough]: https://github.github.com/gfm/#strikethrough-extension- -[GitHub Flavored Markdown: Tables]: https://github.github.com/gfm/#tables-extension- -[GitHub Flavored Markdown: Task list items]: https://github.github.com/gfm/#task-list-items-extension- -[Goldmark Extensions: CJK]: https://github.com/yuin/goldmark?tab=readme-ov-file#cjk-extension -[Goldmark Extensions: Typographer]: https://github.com/yuin/goldmark?tab=readme-ov-file#typographer-extension -[Hugo Goldmark Extensions: Extras]: https://github.com/gohugoio/hugo-goldmark-extensions?tab=readme-ov-file#extras-extension -[Hugo Goldmark Extensions: Passthrough]: https://github.com/gohugoio/hugo-goldmark-extensions?tab=readme-ov-file#passthrough-extension -[PHP Markdown Extra: Definition lists]: https://michelf.ca/projects/php-markdown/extra/#def-list -[PHP Markdown Extra: Footnotes]: https://michelf.ca/projects/php-markdown/extra/#footnotes - -#### Extras - -{{< new-in 0.126.0 />}} - -Enable [deleted text], [inserted text], [mark text], [subscript], and [superscript] elements in Markdown. - -Element|Markdown|Rendered -:--|:--|:-- -Deleted text|`~~foo~~`|`foo` -Inserted text|`++bar++`|`bar` -Mark text|`==baz==`|`baz` -Subscript|`H~2~O`|`H2O` -Superscript|`1^st^`|`1st` - -[deleted text]: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/del -[inserted text]: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/ins -[mark text]: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/mark -[subscript]: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/sub -[superscript]: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/sup - -To avoid a conflict when enabling the Hugo Goldmark Extras subscript extension, if you want to render subscript and strikethrough text concurrently you must: - -1. Disable the Goldmark strikethrough extension -1. Enable the Hugo Goldmark Extras delete extension - -For example: - -{{< code-toggle file=hugo >}} -[markup.goldmark.extensions] -strikethrough = false - -[markup.goldmark.extensions.extras.delete] -enable = true - -[markup.goldmark.extensions.extras.subscript] -enable = true -{{< /code-toggle >}} - -#### Passthrough - -{{< new-in 0.122.0 />}} - -Enable the passthrough extension to include mathematical equations and expressions in Markdown using LaTeX markup. See [mathematics in Markdown] for details. - -[mathematics in Markdown]: content-management/mathematics/ - -#### Typographer - -The Typographer extension replaces certain character combinations with HTML entities as specified below: - -Markdown|Replaced by|Description -:--|:--|:-- -`...`|`…`|horizontal ellipsis -`'`|`’`|apostrophe -`--`|`–`|en dash -`---`|`—`|em dash -`«`|`«`|left angle quote -`“`|`“`|left double quote -`‘`|`‘`|left single quote -`»`|`»`|right angle quote -`”`|`”`|right double quote -`’`|`’`|right single quote - -### Goldmark settings explained - -Most of the Goldmark settings above are self-explanatory, but some require explanation. - -###### duplicateResourceFiles - -{{< new-in 0.123.0 />}} - -(`bool`) If `true`, shared page resources on multilingual single-host sites will be duplicated for each language. See [multilingual page resources] for details. Default is `false`. - -[multilingual page resources]: /content-management/page-resources/#multilingual - -{{% note %}} -With multilingual single-host sites, setting this parameter to `false` will enable Hugo's [embedded link render hook] and [embedded image render hook]. This is the default configuration for multilingual single-host sites. - -[embedded image render hook]: /render-hooks/images/#default -[embedded link render hook]: /render-hooks/links/#default -{{% /note %}} - -###### parser.wrapStandAloneImageWithinParagraph - -(`bool`) If `true`, image elements without adjacent content will be wrapped within a `p` element when rendered. This is the default Markdown behavior. Set to `false` when using an [image render hook] to render standalone images as `figure` elements. Default is `true`. - -[image render hook]: /render-hooks/images/ - -###### parser.autoHeadingIDType - -(`string`) The strategy used to automatically generate heading `id` attributes, one of `github`, `github-ascii` or `blackfriday`. - -- `github` produces GitHub-compatible `id` attributes -- `github-ascii` drops any non-ASCII characters after accent normalization -- `blackfriday` produces `id` attributes compatible with the Blackfriday Markdown renderer - -This is also the strategy used by the [anchorize](/functions/urls/anchorize) template function. Default is `github`. - -###### parser.attribute.block - -(`bool`) If `true`, enables [Markdown attributes] for block elements. Default is `false`. - -[Markdown attributes]: /content-management/markdown-attributes/ - -###### parser.attribute.title - -(`bool`) If `true`, enables [Markdown attributes] for headings. Default is `true`. - -###### renderHooks.image.enableDefault - -{{< new-in 0.123.0 />}} - -(`bool`) If `true`, enables Hugo's [embedded image render hook]. Default is `false`. - -[embedded image render hook]: /render-hooks/images/#default - -{{% note %}} -The embedded image render hook is automatically enabled for multilingual single-host sites if [duplication of shared page resources] is disabled. This is the default configuration for multilingual single-host sites. - -[duplication of shared page resources]: /getting-started/configuration-markup/#duplicateresourcefiles -{{% /note %}} - -###### renderHooks.link.enableDefault - -{{< new-in 0.123.0 />}} - -(`bool`) If `true`, enables Hugo's [embedded link render hook]. Default is `false`. - -[embedded link render hook]: /render-hooks/links/#default - -{{% note %}} -The embedded link render hook is automatically enabled for multilingual single-host sites if [duplication of shared page resources] is disabled. This is the default configuration for multilingual single-host sites. - -[duplication of shared page resources]: /getting-started/configuration-markup/#duplicateresourcefiles -{{% /note %}} - -###### renderer.hardWraps - -(`bool`) If `true`, Goldmark replaces newline characters within a paragraph with `br` elements. Default is `false`. - -###### renderer.unsafe - -(`bool`) If `true`, Goldmark renders raw HTML mixed within the Markdown. This is unsafe unless the content is under your control. Default is `false`. - -## AsciiDoc - -This is the default configuration for the AsciiDoc renderer: - -{{< code-toggle config=markup.asciidocExt />}} - -### AsciiDoc settings explained - -###### attributes - -(`map`) A map of key-value pairs, each a document attribute. See Asciidoctor’s [attributes]. - -[attributes]: https://asciidoctor.org/docs/asciidoc-syntax-quick-reference/#attributes-and-substitutions - -###### backend - -(`string`) The backend output file format. Default is `html5`. - -###### extensions - -(`string array`) An array of enabled extensions, one or more of `asciidoctor-html5s`, `asciidoctor-bibtex`, `asciidoctor-diagram`, `asciidoctor-interdoc-reftext`, `asciidoctor-katex`, `asciidoctor-latex`, `asciidoctor-mathematical`, or `asciidoctor-question`. - -{{% note %}} -To mitigate security risks, entries in the extension array may not contain forward slashes (`/`), backslashes (`\`), or periods. Due to this restriction, extensions must be in Ruby's `$LOAD_PATH`. -{{% /note %}} - -###### failureLevel - -(`string`) The minimum logging level that triggers a non-zero exit code (failure). Default is `fatal`. - -###### noHeaderOrFooter - -(`bool`) If `true`, outputs an embeddable document, which excludes the header, the footer, and everything outside the body of the document. Default is `true`. - -###### preserveTOC - -(`bool`) If `true`, preserves the table of contents (TOC) rendered by Asciidoctor. By default, to make the TOC compatible with existing themes, Hugo removes the TOC rendered by Asciidoctor. To render the TOC, use the [`TableOfContents`] method on a `Page` object in your templates. Default is `false`. - -[`TableOfContents`]: /methods/page/tableofcontents/ - -###### safeMode - -(`string`) The safe mode level, one of `unsafe`, `safe`, `server`, or `secure`. Default is `unsafe`. - -###### sectionNumbers - -(`bool`) If `true`, numbers each section title. Default is `false`. - -###### trace - -(`bool`) If `true`, include backtrace information on errors. Default is `false`. - -###### verbose - -(`bool`)If `true`, verbosely prints processing information and configuration file checks to stderr. Default is `false`. - -###### workingFolderCurrent - -(`bool`) If `true`, sets the working directory to be the same as that of the AsciiDoc file being processed, allowing [includes] to work with relative paths. Set to `true` to render diagrams with the [asciidoctor-diagram] extension. Default is `false`. - -[asciidoctor-diagram]: https://asciidoctor.org/docs/asciidoctor-diagram/ -[includes]: https://docs.asciidoctor.org/asciidoc/latest/syntax-quick-reference/#includes - -### AsciiDoc configuration example - -{{< code-toggle file=hugo >}} -[markup.asciidocExt] - extensions = ["asciidoctor-html5s", "asciidoctor-diagram"] - workingFolderCurrent = true - [markup.asciidocExt.attributes] - my-base-url = "https://example.com/" - my-attribute-name = "my value" -{{< /code-toggle >}} - -### AsciiDoc syntax highlighting - -Follow the steps below to enable syntax highlighting. - -Step 1 -: Set the `source-highlighter` attribute in your site configuration. For example: - -{{< code-toggle file=hugo >}} -[markup.asciidocExt.attributes] -source-highlighter = 'rouge' -{{< /code-toggle >}} - -Step 2 -: Generate the highlighter CSS. For example: - -```text -rougify style monokai.sublime > assets/css/syntax.css -``` - -Step 3 -: In your base template add a link to the CSS file: - -{{< code file=layouts/_default/baseof.html >}} - - ... - {{ with resources.Get "css/syntax.css" }} - - {{ end }} - ... - -{{< /code >}} - -Then add the code to be highlighted to your markup: - -```text -[#hello,ruby] ----- -require 'sinatra' - -get '/hi' do - "Hello World!" -end ----- -``` - -### AsciiDoc troubleshooting - -Run `hugo --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 -] ... -``` - -## Highlight - -This is the default `highlight` configuration. Note that some of these settings can be set per code block, see [Syntax Highlighting](/content-management/syntax-highlighting/). - -{{< code-toggle config=markup.highlight />}} - -For `style`, see these galleries: - -* [Short snippets](https://xyproto.github.io/splash/docs/all.html) -* [Long snippets](https://xyproto.github.io/splash/docs/longer/all.html) - -For CSS, see [Generate Syntax Highlighter CSS](/content-management/syntax-highlighting/#generate-syntax-highlighter-css). - -## Table of contents - -This is the default configuration for the table of contents, applicable to Goldmark and Asciidoctor: - -{{< code-toggle config=markup.tableOfContents />}} - -###### startLevel - -(`int`) Heading levels less than this value will be excluded from the table of contents. For example, to exclude `h1` elements from the table of contents, set this value to `2`. Default is `2`. - -###### endLevel - -(`int`) Heading levels greater than this value will be excluded from the table of contents. For example, to exclude `h4`, `h5`, and `h6` elements from the table of contents, set this value to `3`. Default is `3`. - -###### ordered - -(`bool`) If `true`, generates an ordered list instead of an unordered list. Default is `false`. diff --git a/content/en/getting-started/configuration.md b/content/en/getting-started/configuration.md deleted file mode 100644 index 23376f68f..000000000 --- a/content/en/getting-started/configuration.md +++ /dev/null @@ -1,996 +0,0 @@ ---- -title: Configure Hugo -linkTitle: Configuration -description: How to configure your Hugo site. -categories: [getting started,fundamentals] -keywords: [configuration,toml,yaml,json] -menu: - docs: - parent: getting-started - weight: 50 -weight: 50 -toc: true -aliases: [/overview/source-directory/,/overview/configuration/] ---- - -## 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. - -```text -my-project/ -└── hugo.toml -``` - -{{% note %}} -With v0.109.0 and earlier the basename of the site configuration file was `config` instead of `hugo`. You can use either, but should transition to the new naming convention when practical. -{{% /note %}} - -A simple example: - -{{< code-toggle file=hugo >}} -baseURL = 'https://example.org/' -languageCode = 'en-us' -title = 'ABC Widgets, Inc.' -[params] -subtitle = 'The Best Widgets on Earth' -[params.contact] -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: - -```sh -hugo --config other.toml -``` - -Combine two or more configuration files, with left-to-right precedence: - -```sh -hugo --config a.toml,b.yaml,c.json -``` - -{{% note %}} -See the specifications for each file format: [TOML], [YAML], and [JSON]. - -[TOML]: https://toml.io/en/latest -[YAML]: https://yaml.org/spec/ -[JSON]: https://datatracker.ietf.org/doc/html/rfc7159 -{{% /note %}} - -## Configuration directory - -Instead of a single site configuration file, split your configuration by [environment](g), root configuration key, and language. For example: - -```text -my-project/ -└── config/ - ├── _default/ - │ ├── hugo.toml - │ ├── menus.en.toml - │ ├── menus.de.toml - │ └── params.toml - └── production/ - └── params.toml -``` - -The root configuration keys are `build`, `caches`, `cascade`, `deployment`, `frontmatter`, `imaging`, `languages`, `markup`, `mediatypes`, `menus`, `minify`, `module`, `outputformats`, `outputs`, `params`, `permalinks`, `privacy`, `related`, `security`, `segments`, `server`, `services`, `sitemap`, and `taxonomies`. - -### Omit the root key - -When splitting the configuration by root key, omit the root key in the given file. For example, these are equivalent: - -{{< code-toggle file=hugo >}} -[params] -foo = 'bar' -{{< /code-toggle >}} - -{{< code-toggle file=params >}} -foo = 'bar' -{{< /code-toggle >}} - -### Recursive parsing - -Hugo parses the `config` directory recursively, allowing you to organize the files into subdirectories. For example: - -```text -my-project/ -└── config/ - └── _default/ - ├── navigation/ - │ ├── menus.de.toml - │ └── menus.en.toml - └── hugo.toml -``` - -### Example - -```text -my-project/ -└── config/ - ├── _default/ - │ ├── hugo.toml - │ ├── menus.en.toml - │ ├── menus.de.toml - │ └── params.toml - ├── production/ - │ ├── hugo.toml - │ └── params.toml - └── staging/ - ├── hugo.toml - └── 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. - -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: - -[Google tag ID]: https://support.google.com/tagmanager/answer/12326985?hl=en - -{{< code-toggle file=hugo copy=false >}} -[services.googleAnalytics] -ID = 'G-XXXXXXXXX' -{{< /code-toggle >}} - -Now consider the following scenario: - -1. You don't want to load the analytics code when running `hugo server`. -1. You want to use different Google tag IDs for your production and staging environments. For example: - - - `G-PPPPPPPPP` for production - - `G-SSSSSSSSS` for staging - -To satisfy these requirements, configure your site as follows: - -1. `config/_default/hugo.toml` - - Exclude the `services.googleAnalytics` section. This will prevent loading of the analytics code when you run `hugo server`. - - By default, Hugo sets its `environment` to `development` when running `hugo server`. In the absence of a `config/development` directory, Hugo uses the `config/_default` directory. - -1. `config/production/hugo.toml` - - Include this section only: - - {{< code-toggle file=hugo copy=false >}} - [services.googleAnalytics] - ID = 'G-PPPPPPPPP' - {{< /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. - -1. `config/staging/hugo.toml` - - Include this section only: - - {{< code-toggle file=hugo copy=false >}} - [services.googleAnalytics] - ID = 'G-SSSSSSSSS' - {{< /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. - -## Merge configuration from themes - -The configuration value for `_merge` can be one of: - -none -: No merge. - -shallow -: Only add values for new keys. - -deep -: Add values for new keys, merge existing. - -Note that you don't need to be so verbose as in the default setup below; a `_merge` value higher up will be inherited if not set. - -{{< code-toggle file=hugo dataKey="config_helpers.mergeStrategy" skipHeader=true />}} - -## All configuration settings - -###### archetypeDir - -(`string`) The directory where Hugo finds archetype files (content templates). Default is `archetypes`. {{% module-mounts-note %}} - -###### assetDir - -(`string`) The directory where Hugo finds asset files used in [Hugo Pipes](/hugo-pipes/). Default is `assets`. {{% module-mounts-note %}} - -###### baseURL - -(`string`) The absolute URL (protocol, host, path, and trailing slash) of your published site (e.g., `https://www.example.org/docs/`). - -###### build - -See [Configure Build](#configure-build). - -###### buildDrafts - -(`bool`) Include drafts when building. Default is `false`. - -###### buildExpired - -(`bool`) Include content already expired. Default is `false`. - -###### buildFuture - -(`bool`) Include content with a future publication date. Default is `false`. - -###### caches - -See [Configure File Caches](#configure-file-caches). - -###### canonifyURLs - -(`bool`) See [details](/content-management/urls/#canonical-urls) before enabling this feature. Default is `false`. - -###### capitalizeListTitles - -{{< new-in 0.123.3 />}} - -(`bool`) Whether to capitalize automatic list titles. Applicable to section, taxonomy, and term pages. Default is `true`. You can change the capitalization style in your site configuration to one of `ap`, `chicago`, `go`, `firstupper`, or `none`. See [details]. - -[details]: /getting-started/configuration/#configure-title-case - -###### cascade - -Pass down default configuration values (front matter) to pages in the content tree. The options in site config is the same as in page front matter, see [Front Matter Cascade](/content-management/front-matter#cascade). - -{{% note %}} -For a website in a single language, define the `[[cascade]]` in [Front Matter](/content-management/front-matter#cascade). For a multilingual website, define the `[[cascade]]` in [Site Config](/getting-started/configuration/#cascade). - -To remain consistent and prevent unexpected behavior, do not mix these strategies. -{{% /note %}} - -###### cleanDestinationDir - -(`bool`) When building, removes files from destination not found in static directories. Default is `false`. - -###### contentDir - -(`string`) The directory from where Hugo reads content files. Default is `content`. {{% module-mounts-note %}} - -###### copyright - -(`string`) Copyright notice for your site, typically displayed in the footer. - -###### dataDir - -(`string`) The directory from where Hugo reads data files. Default is `data`. {{% module-mounts-note %}} - -###### defaultOutputFormat -(`string`) The default output format for the site. If unspecified, the first available format in the defined order (by weight, then alphabetically) will be used. - -###### defaultContentLanguage - -(`string`) Content without language indicator will default to this language. Default is `en`. - -###### defaultContentLanguageInSubdir - -(`bool`) Render the default content language in subdir, e.g. `content/en/`. The site root `/` will then redirect to `/en/`. Default is `false`. - -###### disableAliases - -(`bool`) Will disable generation of alias redirects. Note that even if `disableAliases` is set, the aliases themselves are preserved on the page. The motivation with this is to be able to generate 301 redirects in an `.htaccess`, a Netlify `_redirects` file or similar using a custom output format. Default is `false`. - -###### disableDefaultLanguageRedirect - -{{< new-in 0.140.0 />}} - -(`bool`) Disables generation of redirect to the default language when DefaultContentLanguageInSubdir is `true`. Default is `false`. - -###### disableHugoGeneratorInject - -(`bool`) Hugo will, by default, inject a generator meta tag in the HTML head on the _home page only_. You can turn it off, but we would really appreciate if you don't, as this is a good way to watch Hugo's popularity on the rise. Default is `false`. - -###### disableKinds - -(`[]string`) Disable rendering of the specified page [kinds](g), any of `404`, `home`, `page`, `robotstxt`, `rss`, `section`, `sitemap`, `taxonomy`, or `term`. - -###### disableLanguages - -See [disable a language](/content-management/multilingual/#disable-a-language). - -###### disableLiveReload - -(`bool`) Disable automatic live reloading of browser window. Default is `false`. - -###### disablePathToLower - -(`bool`) Do not convert the url/path to lowercase. Default is `false`. - -###### enableEmoji - -(`bool`) Enable Emoji emoticons support for page content; see the [emoji shortcode quick reference guide](/quick-reference/emojis/). Default is `false`. - -###### enableGitInfo - -(`bool`) Enable `.GitInfo` object for each page (if the Hugo site is versioned by Git). This will then update the `Lastmod` parameter for each page using the last git commit date for that content file. Default is `false`. - -###### enableMissingTranslationPlaceholders - -(`bool`) Show a placeholder instead of the default value or an empty string if a translation is missing. Default is `false`. - -###### enableRobotsTXT - -(`bool`) Enable generation of `robots.txt` file. Default is `false`. - -###### environment - -(`string`) Build environment. Default is `production` when running `hugo` and `development` when running `hugo server`. See [Configuration directory](https://gohugo.io/getting-started/configuration/#configuration-directory). -###### frontmatter - -See [Front matter Configuration](#configure-front-matter). - -###### hasCJKLanguage - -(`bool`) If true, auto-detect Chinese/Japanese/Korean Languages in the content. This will make `.Summary` and `.WordCount` behave correctly for CJK languages. Default is `false`. - -###### ignoreCache - -(`bool`) Ignore the cache directory. Default is `false`. - -###### ignoreLogs -(`[]string`) A slice of message identifiers corresponding to warnings and errors you wish to suppress. See [`erroridf`] and [`warnidf`]. - -[`erroridf`]: /functions/fmt/erroridf/ -[`warnidf`]: /functions/fmt/warnidf/ - -###### ignoreVendorPaths - -(`string`) Ignore vendored modules that match the given [Glob] pattern within the `_vendor` directory. - -[Glob]: https://github.com/gobwas/glob?tab=readme-ov-file#example] - -###### imaging - -See [image processing configuration](/content-management/image-processing/#imaging-configuration). - -###### languageCode - -(`string`) A language tag as defined by [RFC 5646](https://datatracker.ietf.org/doc/html/rfc5646). This value is used to populate: - -- The `` element in the embedded [RSS template]({{% eturl rss %}}) -- The `lang` attribute of the `` element in the embedded [alias template]({{% eturl alias %}}) -- The `og:locale` `meta` element in the embedded [Open Graph template]({{% eturl opengraph %}}) - -When present in the root of the configuration, this value is ignored if one or more language keys exists. Please specify this value independently for each language key. - -###### languages - -See [Configure Languages](/content-management/multilingual/#configure-languages). - -###### layoutDir - -(`string`) The directory that contains templates. Default is `layouts`. - -###### markup - -See [Configure Markup](/getting-started/configuration-markup). - -###### mediaTypes - -See [Configure Media Types](/templates/output-formats/#media-types). - -###### menus - -See [Menus](/content-management/menus/#define-in-site-configuration). - -###### minify - -See [Configure Minify](#configure-minify). - -###### module - -Module configuration see [module configuration](/hugo-modules/configuration/). - -###### newContentEditor - -(`string`) The editor to use when creating new content. - -###### noBuildLock - -(`bool`) Don't create `.hugo_build.lock` file. Default is `false`. - -###### noChmod - -(`bool`) Don't sync permission mode of files. Default is `false`. - -###### noTimes - -(`bool`) Don't sync modification time of files. Default is `false`. - -###### outputFormats - -See [custom output formats]. - -###### page - -See [configure page](#configure-page). - -###### pagination - -See [configure pagination](/templates/pagination/#configuration). - -###### panicOnWarning - -(`bool`) Whether to panic on first WARNING. Default is `false`. - -###### permalinks - -See [Content Management](/content-management/urls/#permalinks). - -###### pluralizeListTitles - -(`bool`) Whether to pluralize automatic list titles. Applicable to section pages. Default is `true`. - -###### printI18nWarnings - -(`bool`) Whether to log WARNINGs for each missing translation. Default is `false`. - -###### printPathWarnings - -(`bool`) Whether to log WARNINGs when Hugo publishes two or more files to the same path. Default is `false`. - -###### printUnusedTemplates - -(`bool`) Whether to log WARNINGs for each unused template. Default is `false`. - -###### publishDir - -(`string`) The directory where Hugo will write the final static site (the HTML files etc.). Default is `public`. - -###### refLinksErrorLevel - -(`string`) When using `ref` or `relref` to resolve page links and a link cannot be resolved, it will be logged with this log level. Valid values are `ERROR` (default) or `WARNING`. Any `ERROR` will fail the build (`exit -1`). Default is `ERROR`. - -###### refLinksNotFoundURL - -(`string`) URL to be used as a placeholder when a page reference cannot be found in `ref` or `relref`. Is used as-is. - -###### related - -See [Related Content](/content-management/related/#configure-related-content). - -###### relativeURLs - -(`bool`) See [details](/content-management/urls/#relative-urls) before enabling this feature. Default is `false`. - -###### removePathAccents - -(`bool`) Removes [non-spacing marks](https://www.compart.com/en/unicode/category/Mn) from [composite characters](https://en.wikipedia.org/wiki/Precomposed_character) in content paths. Default is `false`. - -```text -content/post/hügó.md → https://example.org/post/hugo/ -``` - -###### renderSegments - -{{< new-in 0.124.0 />}} - -(`[]string`) A list of segments to render. If not set, everything will be rendered. This is more commonly set in a CLI flag, e.g. `hugo --renderSegments segment1,segment2`. The segment names must match the names in the [segments](#configure-segments) configuration. - -###### sectionPagesMenu - -See [Menus](/content-management/menus/#define-automatically). - -###### security - -See [Security Policy](/about/security/#security-policy). - -###### segments - -See [Segments](#configure-segments). - -###### sitemap - -Default [sitemap configuration](/templates/sitemap/#configuration). - -###### summaryLength - -(`int`) Applicable to [automatic summaries], the minimum number of words to render when calling the [`Summary`] method on a `Page` object. In this case the `Summary` method returns the content, truncated to the paragraph closest to the `summaryLength`. - -[automatic summaries]: /content-management/summaries/#automatic-summary -[`Summary`]: /methods/page/summary/ - -###### taxonomies - -See [Configure Taxonomies](/content-management/taxonomies#configure-taxonomies). - -###### templateMetrics - -(`bool`) Whether to print template execution metrics to the console. Default is `false`. See [Template metrics](/troubleshooting/performance/#template-metrics). - -###### templateMetricsHints - -(`bool`) Whether to print template execution improvement hints to the console. Applicable when `templateMetrics` is `true`. Default is `false`. See [Template metrics](/troubleshooting/performance/#template-metrics). - -###### theme - -See [module configuration](/hugo-modules/configuration/#module-configuration-imports) for how to import a theme. - -###### themesDir - -(`string`) The directory where Hugo reads the themes from. Default is `themes`. - -###### timeout - -(`string`) Timeout for generating page contents, specified as a [duration](https://pkg.go.dev/time#Duration) or in seconds. *Note:* this is used to bail out of recursive content generation. You might need to raise this limit if your pages are slow to generate (e.g., because they require large image processing or depend on remote contents). Default is `30s`. - -###### timeZone - -(`string`) The time zone used to parse dates without time zone offsets, including front matter date fields and values passed to the [`time.AsTime`] and [`time.Format`] template functions. The list of valid values may be system dependent, but should include `UTC`, `Local`, and any location in the [IANA Time Zone Database]. For example, `America/Los_Angeles` and `Europe/Oslo` are valid time zones. - -[`time.AsTime`]: /functions/time/astime/ -[`time.Format`]: /functions/time/format/ -[IANA Time Zone Database]: https://en.wikipedia.org/wiki/List_of_tz_database_time_zones - -###### title - -(`string`) Site title. - -###### titleCaseStyle - -(`string`) Default is `ap`. See [Configure Title Case](#configure-title-case). - -###### uglyURLs - -(`bool` or `map`) Whether to generate uglyURLs. Default is `false`. See [details](/content-management/urls/#appearance). - -###### watch - -(`bool`) Watch filesystem for changes and recreate as needed. Default is `false`. - -{{% note %}} -If you are developing your site on a \*nix machine, here is a handy shortcut for finding a configuration option from the command line: -```txt -cd ~/sites/yourhugosite -hugo config | grep emoji -``` - -which shows output like - -```txt -enableemoji: true -``` -{{% /note %}} - -## Configure page - -{{< new-in 0.133.0 />}} - -These methods on a `Page` object navigate to the next or previous page within a page collection, relative to the current page: - -- [Next](/methods/page/next/) -- [NextInSection](/methods/page/nextinsection/) -- [Prev](/methods/page/prev/) -- [PrevInSection](/methods/page/previnsection/) - -Hugo determines the _next_ and _previous_ page by sorting a page collection according to this sorting hierarchy: - -Field|Precedence|Sort direction -:--|:--|:-- -[`weight`]|1|descending -[`date`]|2|descending -[`linkTitle`]|3|descending -[`path`]|4|descending - -[`date`]: /methods/page/date/ -[`weight`]: /methods/page/weight/ -[`linkTitle`]: /methods/page/linktitle/ -[`path`]: /methods/page/path/ - -The sort direction in the table above corresponds to these default site configuration values: - -{{< code-toggle config=page />}} - -To sort all fields in ascending order: - -{{< code-toggle file=hugo >}} -[page] - nextPrevInSectionSortOrder = 'asc' - nextPrevSortOrder = 'asc' -{{< /code-toggle >}} - -{{% note %}} -These settings do not apply to the [`Next`] or [`Prev`] methods on a `Pages` object. - -[`Next`]: /methods/pages/next -[`Prev`]: /methods/pages/next -{{% /note %}} - -## Configure build - -See [Configure Build](/getting-started/configuration-build/). - -## Configure server - -This is only relevant when running `hugo server`, and it allows to set HTTP headers during development, which allows you to test out your Content Security Policy and similar. The configuration format matches [Netlify's](https://docs.netlify.com/routing/headers/#syntax-for-the-netlify-configuration-file) with slightly more powerful [Glob matching](https://github.com/gobwas/glob): - -{{< code-toggle file=hugo >}} -[server] -[[server.headers]] -for = "/**" - -[server.headers.values] -X-Frame-Options = "DENY" -X-XSS-Protection = "1; mode=block" -X-Content-Type-Options = "nosniff" -Referrer-Policy = "strict-origin-when-cross-origin" -Content-Security-Policy = "script-src localhost:1313" -{{< /code-toggle >}} - -Since this is "development only", it may make sense to put it below the `development` environment: - -{{< code-toggle file=config/development/server >}} -[[headers]] -for = "/**" - -[headers.values] -X-Frame-Options = "DENY" -X-XSS-Protection = "1; mode=block" -X-Content-Type-Options = "nosniff" -Referrer-Policy = "strict-origin-when-cross-origin" -Content-Security-Policy = "script-src localhost:1313" -{{< /code-toggle >}} - -You can also specify simple redirects rules for the server. The syntax is again similar to Netlify's. - -Note that a `status` code of 200 will trigger a [URL rewrite](https://docs.netlify.com/routing/redirects/rewrites-proxies/), which is what you want in SPA situations, e.g: - -{{< code-toggle file=config/development/server >}} -[[redirects]] -from = "/myspa/**" -to = "/myspa/" -status = 200 -force = false -{{< /code-toggle >}} - -Setting `force=true` will make a redirect even if there is existing content in the path. Note that before Hugo 0.76 `force` was the default behavior, but this is inline with how Netlify does it. - -## 404 server error page {#_404-server-error-page} - -Hugo will, by default, render all 404 errors when running `hugo server` with the `404.html` template. Note that if you have already added one or more redirects to your [server configuration](#configure-server), you need to add the 404 redirect explicitly, e.g: - -{{< code-toggle file=config/development/server >}} -[[redirects]] -from = "/**" -to = "/404.html" -status = 404 -{{< /code-toggle >}} - -With a multilingual site, define the redirect for the default content language last: - -{{< code-toggle file=config/development/server >}} -defaultContentLanguage = 'en' -defaultContentLanguageInSubdir = false -[[redirects]] -from = '/fr/**' -to = '/fr/404.html' -status = 404 - -[[redirects]] # Default language must be last. -from = '/**' -to = '/404.html' -status = 404 -{{< /code-toggle >}} - -If you are serving the default content language from a subdirectory: - -{{< code-toggle file=config/development/server >}} -defaultContentLanguage = 'en' -defaultContentLanguageInSubdir = true -[[redirects]] -from = '/fr/**' -to = '/fr/404.html' -status = 404 - -[[redirects]] # Default language must be last. -from = '/**' -to = '/en/404.html' -status = 404 -{{< /code-toggle >}} - -## Configure title case - -By default, Hugo follows the capitalization rules published in the [Associated Press Stylebook] when creating automatic section titles, and when transforming strings with the [`strings.Title`] function. - -Change this behavior by setting `titleCaseStyle` in your site configuration to any of the values below: - -ap -: Use the capitalization rules published in the [Associated Press Stylebook]. - -chicago -: Use the capitalization rules published in the [Chicago Manual of Style]. - -go -: Capitalize the first letter of every word. - -firstupper -: Capitalize the first letter of the first word. - -none -: Disable transformation of automatic section titles, and disable the transformation performed by the `strings.Title` function. This is useful if you would prefer to manually capitalize section titles as needed, and to bypass opinionated theme usage of the `strings.Title` function. - -[`strings.Title`]: /functions/strings/title/ -[Associated Press Stylebook]: https://www.apstylebook.com/ -[Chicago Manual of Style]: https://www.chicagomanualofstyle.org/home.html -[site configuration]: /getting-started/configuration/#configure-title-case - -## Configuration environment variables - -DART_SASS_BINARY -: (`string`) The absolute path to the Dart Sass executable. By default, Hugo searches for the executable in each of the paths in the `PATH` environment variable. - -HUGO_ENVIRONMENT -: (`string`) Overrides the default [environment](g), typically one of `development`, `staging`, or `production`. - -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`. - -{{< new-in 0.123.0 />}} - -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. - -HUGO_NUMWORKERMULTIPLIER -: (`int`) The number of workers used in parallel processing. Default is the number of logical CPUs. - -## Configure with environment variables - -Configuration key-values can be defined through operating system environment variables. - -For example, the following command will effectively set a website's title on Unix-like systems: - -```txt -$ env HUGO_TITLE="Some Title" hugo -``` - -This is really useful if you use a service such as Netlify to deploy your site. Look at the Hugo docs [Netlify configuration file](https://github.com/gohugoio/hugoDocs/blob/master/netlify.toml) for an example. - -{{% note %}} -Names must be prefixed with `HUGO_` and the configuration key must be set in uppercase when setting operating system environment variables. - -To set configuration parameters, prefix the name with `HUGO_PARAMS_` -{{% /note %}} - -If you are using snake_cased variable names, the above will not work. Hugo determines the delimiter to use by the first character after `HUGO`. This allows you to define environment variables on the form `HUGOxPARAMSxAPI_KEY=abcdefgh`, using any [allowed](https://stackoverflow.com/questions/2821043/allowed-characters-in-linux-environment-variable-names#:~:text=So%20names%20may%20contain%20any,not%20begin%20with%20a%20digit.) delimiter. - -## Ignore content and data files when rendering - -{{% note %}} -This works, but we recommend you use the newer and more powerful [includeFiles and excludeFiles](/hugo-modules/configuration/#module-configuration-mounts) mount options. -{{% /note %}} - -To exclude specific files from the `content`, `data`, and `i18n` directories when rendering your site, set `ignoreFiles` to one or more regular expressions to match against the absolute file path. - -To ignore files ending with `.foo` or `.boo`: - -{{< code-toggle file=hugo >}} -ignoreFiles = ['\.foo$', '\.boo$'] -{{< /code-toggle >}} - -To ignore a file using the absolute file path: - -{{< code-toggle file=hugo >}} -ignoreFiles = ['^/home/user/project/content/test\.md$'] -{{< /code-toggle >}} - -## Configure front matter - -### Configure dates - -Dates are important in Hugo, and you can configure how Hugo assigns dates to your content pages. You do this by adding a `frontmatter` section to your `hugo.toml`. - -The default configuration is: - -{{< code-toggle config=frontmatter />}} - -If you, as an example, have a non-standard date parameter in some of your content, you can override the setting for `date`: - -{{< code-toggle file=hugo >}} -[frontmatter] -date = ["myDate", ":default"] -{{< /code-toggle >}} - -The `:default` is a shortcut to the default settings. The above will set `.Date` to the date value in `myDate` if present, if not we will look in `date`,`publishDate`, `lastmod` and pick the first valid date. - -In the list to the right, values starting with ":" are date handlers with a special meaning (see below). The others are just names of date parameters (case insensitive) in your front matter configuration. Also note that Hugo have some built-in aliases to the above: `lastmod` => `modified`, `publishDate` => `pubdate`, `published` and `expiryDate` => `unpublishdate`. With that, as an example, using `pubDate` as a date in front matter, will, by default, be assigned to `.PublishDate`. - -The special date handlers are: - -`:fileModTime` -: Fetches the date from the content file's last modification timestamp. - -An example: - -{{< code-toggle file=hugo >}} -[frontmatter] -lastmod = ["lastmod", ":fileModTime", ":default"] -{{< /code-toggle >}} - -The above will try first to extract the value for `.Lastmod` starting with the `lastmod` front matter parameter, then the content file's modification timestamp. The last, `:default` should not be needed here, but Hugo will finally look for a valid date in `:git`, `date` and then `publishDate`. - -`:filename` -: Fetches the date from the content file's file name. For example, `2018-02-22-mypage.md` will extract the date `2018-02-22`. Also, if `slug` is not set, `mypage` will be used as the value for `.Slug`. - -An example: - -{{< code-toggle file=hugo >}} -[frontmatter] -date = [":filename", ":default"] -{{< /code-toggle >}} - -The above will try first to extract the value for `.Date` from the file name, then it will look in front matter parameters `date`, `publishDate` and lastly `lastmod`. - -`:git` -: This is the Git author date for the last revision of this content file. This will only be set if `--enableGitInfo` is set or `enableGitInfo = true` is set in site configuration. - -## Configure minify - -See the [tdewolff/minify] project page for details. - -[tdewolff/minify]: https://github.com/tdewolff/minify - -Default configuration: - -{{< code-toggle config=minify />}} - -## Configure file caches - -Since Hugo 0.52 you can configure more than just the `cacheDir`. This is the default configuration: - -{{< code-toggle config=caches />}} - -You can override any of these cache settings in your own `hugo.toml`. - -### The keywords explained - -cacheDir -: (`string`) See [Configure cacheDir](#configure-cachedir). - -project -: (`string`) The base directory name of the current Hugo project. This means that, in its default setting, every project will have separated file caches, which means that when you do `hugo --gc` you will not touch files related to other Hugo projects running on the same PC. - -resourceDir -: (`string`) This is the value of the `resourceDir` configuration option. - -maxAge -: (`string`) This is the duration before a cache entry will be evicted, -1 means forever and 0 effectively turns that particular cache off. Uses Go's `time.Duration`, so valid values are `"10s"` (10 seconds), `"10m"` (10 minutes) and `"10h"` (10 hours). - -dir -: (`string`) The absolute path to where the files for this cache will be stored. Allowed starting placeholders are `:cacheDir` and `:resourceDir` (see above). - -## Configure cacheDir - -This is the directory where Hugo by default will store its file caches. See [Configure File Caches](#configure-file-caches). - -This can be set using the `cacheDir` config option or via the OS environment variable `HUGO_CACHEDIR`. - -If this is not set, Hugo will use, in order of preference: - -1. If running on Netlify: `/opt/build/cache/hugo_cache/`. This means that if you run your builds on Netlify, all caches configured with `:cacheDir` will be saved and restored on the next build. For other CI vendors, please read their documentation. For an CircleCI example, see [this configuration](https://github.com/bep/hugo-sass-test/blob/6c3960a8f4b90e8938228688bc49bdcdd6b2d99e/.circleci/config.yml). -1. In a `hugo_cache` directory below the OS user cache directory as defined by Go's [os.UserCacheDir](https://pkg.go.dev/os#UserCacheDir). On Unix systems, this is `$XDG_CACHE_HOME` as specified by [basedir-spec-latest](https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html) if non-empty, else `$HOME/.cache`. On MacOS, this is `$HOME/Library/Caches`. On Windows, this is`%LocalAppData%`. On Plan 9, this is `$home/lib/cache`. {{< new-in 0.116.0 />}} -1. In a `hugo_cache_$USER` directory below the OS temp dir. - -If you want to know the current value of `cacheDir`, you can run `hugo config`, e.g: `hugo config | grep cachedir`. - -[`.Site.Params`]: /method/site/params/ -[directory structure]: /getting-started/directory-structure/ -[lookup order]: /templates/lookup-order/ -[custom output formats]: /templates/output-formats/ -[templates]: /templates/ -[static-files]: /content-management/static-files/ - -## Configure HTTP cache - -{{< new-in 0.127.0 />}} - -Note that this configuration is currently only relevant when using the [resources.GetRemote] function. - -The caching in Hugo is layered: - -```goat {.w-40} - .-----------. -| dynacache | - '-----+-----' - | - v - .----------. -| HTTP cache | - '-----+----' - | - v - .----------. -| file cache | - '-----+----' -``` - -Dynacache -: A in memory LRU cache that gets evicted on changes, [Cache Buster](/getting-started/configuration-build/#configure-cache-busters) matches and in low memory situations. - -HTTP Cache -: Enables HTTP cache behavior (RFC 9111) for remote resources. This works best for resources with properly set up HTTP cache headers. The HTTP cache uses the [file cache] to store and serve cached resources. - -File Cache -: See [file cache]. - -The default HTTP cache disables everything: - -{{< code-toggle config=HTTPCache />}} - -caching -: Enabled RFC 9111 cache behavior _for_ a configured set of resources. Stale resources will be refreshed from the [file cache] even if their configured TTL isn't reached. - -polling -: Enables polling _for_ a set of resources. Note that you can enable polling for resources even if HTTP caching is disabled. This setting is only used when in watch mode (e.g. `hugo server`). When a changed resource is detected, that change triggers a rebuild of pages using that resource. - -[resources.GetRemote]: /functions/resources/getremote/ -[file cache]: #configure-file-caches - -## Configure segments - -{{< new-in 0.124.0 />}} - -{{% note %}} -The `segments` configuration is currently only used to configure partitioned rendering. -This feature is only about what gets rendered when, Hugo's entire object graph (sites and pages) is -always available. -{{% /note %}} - -* Each segment consists of zero or more `exclude` filters and zero or more `include` filters. -* Each filter consists of one or more field Glob matchers. -* Each filter in a section (`exclude` or `include`) is ORed together, each matcher in a filter is ANDed together. - -The fields that can be used in the filters are: - -path -: The logical page [path]. - -lang -: The [page language]. - -kind -: The [kind](g) of the page. - -output -: The [output format](g) of the page. - -It is recommended to put coarse grained filters (e.g. for language and output format) in the excludes section, e.g.: - -{{< code-toggle file=hugo >}} -[segments.segment1] - [[segments.segment1.excludes]] - lang = "n*" - [[segments.segment1.excludes]] - lang = "en" - output = "rss" - [[segments.segment1.includes]] - kind = "{home,term,taxonomy}" - [[segments.segment1.includes]] - path = "{/docs,/docs/**}" -{{< /code-toggle >}} - -With the above you can render only the pages in `segment1` by configuring the [renderSegments](#rendersegments) or setting the `--renderSegments` flag: - -```bash -hugo --renderSegments segment1 -``` - -Multiple segments can be configured, and the `--renderSegments` flag can take a comma separated list of segments. - -Some use cases for this feature: - -* Splitting builds of big sites. -* Enable faster builds during development by only rendering a subset of the site. -* Partial rebuilds, e.g. render the home page and the "news section" every hour, render the entire site once a week. -* Render only e.g. the JSON output format to push to e.g. a search index. - -[path]: /methods/page/path/ -[page language]: /methods/page/language/ diff --git a/content/en/getting-started/directory-structure.md b/content/en/getting-started/directory-structure.md index ce1df600f..3feecd135 100644 --- a/content/en/getting-started/directory-structure.md +++ b/content/en/getting-started/directory-structure.md @@ -1,17 +1,14 @@ --- title: Directory structure -description: Each Hugo project is a directory, with subdirectories that contribute to the content, structure, behavior, and presentation of your site. -categories: [getting started,fundamentals] -keywords: [source, organization, directories] -menu: - docs: - parent: getting-started - weight: 40 -weight: 40 -toc: true +description: An overview of Hugo's directory structure. +categories: [] +keywords: [] +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. + ## Site skeleton Hugo generates a project skeleton when you create a new site. For example, this command: @@ -78,49 +75,38 @@ my-site/ Each of the subdirectories contributes to the content, structure, behavior, or presentation of your site. -###### archetypes +archetypes +: The `archetypes` directory contains templates for new content. See [details](/content-management/archetypes/). -The `archetypes` directory contains templates for new content. See [details](/content-management/archetypes/). +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/). -###### assets +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 `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/). +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/). -###### config +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/). -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](/getting-started/configuration/#configuration-directory). +i18n +: The `i18n` directory contains translation tables for multilingual sites. See [details](/content-management/multilingual/). -###### content +layouts +: The `layouts` directory contains templates to transform content, data, and resources into a complete website. See [details](/templates/). -The `content` directory contains the markup files (typically Markdown) and page resources that comprise the content of your site. See [details](/content-management/organization/). +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). -###### data +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 `data` directory contains data files (JSON, TOML, YAML, or XML) that augment content, configuration, localization, and navigation. See [details](/content-management/data-sources/). +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. -###### i18n - -The `i18n` directory contains translation tables for multilingual sites. 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). - -###### 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. - -###### 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. - -###### themes - -The `themes` directory contains one or more [themes](g), each in its own subdirectory. +themes +: The `themes` directory contains one or more [themes](g), each in its own subdirectory. ## Union file system @@ -158,11 +144,10 @@ source = '/home/user/shared-content' target = 'content' {{< /code-toggle >}} -{{% note %}} -When you overlay one directory on top of another, you must mount both directories. - -Hugo does not follow symbolic links. If you need the functionality provided by symbolic links, use Hugo's union file system instead. -{{% /note %}} +> [!note] +> When you overlay one directory on top of another, you must mount both directories. +> +> Hugo does not follow symbolic links. If you need the functionality provided by symbolic links, use Hugo's union file system instead. After mounting, the union file system has this structure: @@ -185,11 +170,10 @@ home/ └── hugo.toml ``` -{{% note %}} -When two or more files have the same path, the order of precedence follows the order of the mounts. For example, if the shared content directory contains `books/book-1.md`, it will be ignored because the project's `content` directory was mounted first. -{{% /note %}} +> [!note] +> When two or more files have the same path, the order of precedence follows the order of the mounts. For example, if the shared content directory contains `books/book-1.md`, it will be ignored because the project's `content` directory was mounted first. -You can mount directories to `archetypes`, `assets`, `content`, `data`, `i18n`, `layouts`, and `static`. See [details](/hugo-modules/configuration/#module-configuration-mounts). +You can mount directories to `archetypes`, `assets`, `content`, `data`, `i18n`, `layouts`, and `static`. See [details](/configuration/module/#mounts). You can also mount directories from Git repositories using Hugo Modules. See [details](/hugo-modules/). diff --git a/content/en/getting-started/external-learning-resources/index.md b/content/en/getting-started/external-learning-resources/index.md index 80805d4a6..7838b6810 100644 --- a/content/en/getting-started/external-learning-resources/index.md +++ b/content/en/getting-started/external-learning-resources/index.md @@ -2,19 +2,14 @@ title: External learning resources linkTitle: External resources description: Use these third-party resources to learn Hugo. -categories: [getting started] -keywords: [books, tutorials, learning, usage] -menu: - docs: - parent: getting-started - weight: 90 -weight: 90 -toc: true +categories: [] +keywords: [] +weight: 40 --- ## Books -### Hugo In Action +### Hugo in Action Hugo in Action is a step-by-step guide to using Hugo to create static websites. Working with a complete example website and source code samples, you'll learn how to build and host a low-maintenance, high-performance site that will wow your users and stay stable without relying on a third-party server. @@ -28,7 +23,7 @@ ISBN: 9781617297007 ### Build Websites with Hugo -In this book, you'll use Hugo to build a personal portfolio site that you can use to showcase your skills and thoughts to the world. You'll build the basic skeleton, develop a custom theme, and use content templates to generate new pages quickly. You'll use internal and external data sources to embed content into your site, and render some of your content in JSON and RSS. You'll add a blog section with posts and integrate Disqus with your site, and then make your site searchable. +In this book, you'll use Hugo to build a personal portfolio site that you can use to showcase your skills and thoughts to the world. You'll build the basic skeleton, develop a custom theme, and use content templates to generate new pages quickly. You'll use internal and external data sources to embed content into your site and render some of your content in JSON and RSS. You'll add a blog section with posts and integrate Disqus with your site, and then make your site searchable. [{{< img src="build-websites-with-hugo.png" alt="Book cover: Build Websites with Hugo" filter="process" filterArgs="resize x350 webp">}}](https://pragprog.com/titles/bhhugo/build-websites-with-hugo/) @@ -42,7 +37,7 @@ ISBN: 9781680507263 ### Hugo Beginner Tutorial Series -Welcome to this introduction to Hugo tutorial. The goal of this series is to take you from a lion cub with basic web design knowledge to creating your first Hugo website. In this series you’ll learn how to set up a Hugo site, the basics of usingHugo layouts, partials, and templating, set up a blog, and finally use data files. By the end of this series you’ll have the foundational knowledge to build your own Hugo sites. +Welcome to this introduction to Hugo tutorial. This series aims to take you from a lion cub with basic web design knowledge to creating your first Hugo website. In this series, you'll learn how to set up a Hugo site, the basics of using Hugo layouts, partials, and templating, set up a blog, and finally, use data files. By the end of this series, you'll have the foundational knowledge to build your own Hugo sites. 1. [Getting set up in Hugo](https://cloudcannon.com/tutorials/hugo-beginner-tutorial/) 1. [Layouts in Hugo](https://cloudcannon.com/tutorials/hugo-beginner-tutorial/layouts-in-hugo/) @@ -55,9 +50,9 @@ Creator: Mike Neumegen\ Affiliation: [CloudCannon](https://cloudcannon.com/)\ Creation date: April 2022 -#### Hugo Static Site Generator +### Hugo Static Site Generator -This course covers the basics of using the Hugo static site generator. Work your way through the articles and we'll teach you everything you need to know to create a professional and scalable website or blog! +This course covers the basics of using the Hugo static site generator. Work your way through the articles, and we'll teach you everything you need to know to create a professional and scalable website or blog! 1. [Introduction](https://www.giraffeacademy.com/static-site-generators/hugo/) 1. [Windows Installation](https://www.giraffeacademy.com/static-site-generators/hugo/installing-hugo-on-windows/) diff --git a/content/en/getting-started/quick-start.md b/content/en/getting-started/quick-start.md index cb22e0121..dfb78f42e 100644 --- a/content/en/getting-started/quick-start.md +++ b/content/en/getting-started/quick-start.md @@ -1,16 +1,12 @@ --- title: Quick start -description: Learn to create a Hugo site in minutes. -categories: [getting started] -keywords: [quick start,usage] -menu: - docs: - parent: getting-started - weight: 20 -weight: 20 -toc: true +description: Create a Hugo site in minutes. +categories: [] +keywords: [] +params: + minVersion: v0.128.0 +weight: 10 aliases: [/quickstart/,/overview/quickstart/] -minVersion: v0.128.0 --- In this tutorial you will: @@ -33,18 +29,14 @@ You must also be comfortable working from the command line. ### Commands -{{% note %}} -**If you are a Windows user:** - -- 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 - -PowerShell and Windows PowerShell [are different applications]. - -[PowerShell]: https://learn.microsoft.com/en-us/powershell/scripting/install/installing-powershell-on-windows -[are different applications]: https://learn.microsoft.com/en-us/powershell/scripting/whats-new/differences-from-windows-powershell?view=powershell-7.3 -{{% /note %}} +> [!note] +> **If you are a Windows user:** +> +> - 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 +> +> PowerShell and Windows PowerShell [are different applications]. Verify that you have installed Hugo {{% param "minVersion" %}} or later. @@ -127,8 +119,6 @@ Notice the `draft` value in the [front matter] is `true`. By default, Hugo does Add some [Markdown] to the body of the post, but do not change the `draft` value. -[markdown]: https://commonmark.org/help/ - ```text +++ title = 'My First Post' @@ -142,7 +132,7 @@ 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 to view the site. You can run either of the following commands to include draft content. ```text hugo server --buildDrafts @@ -153,12 +143,8 @@ View your site at the URL displayed in your terminal. Keep the development serve 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. - -[live testing tool]: https://spec.commonmark.org/dingus/ -[specification]: https://spec.commonmark.org/ -{{% /note %}} +> [!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. ## Configure the site @@ -183,15 +169,10 @@ Start Hugo's development server to see your changes, remembering to include draf 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]. - -[demonstration site]: https://gohugo-ananke-theme-demo.netlify.app/ -[documentation]: https://github.com/theNewDynamic/gohugo-theme-ananke#readme -[The New Dynamic]: https://www.thenewdynamic.com/ -{{% /note %}} +> [!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]. ## Publish the site @@ -205,7 +186,7 @@ When you publish your site, you typically do _not_ want to include [draft, futur hugo ``` -To learn how to _deploy_ your site, see the [hosting and deployment] section. +To learn how to _deploy_ your site, see the [host and deploy] section. ## Ask for help @@ -216,17 +197,22 @@ Hugo's [forum] is an active community of users and developers who answer questio For other resources to help you learn Hugo, including books and video tutorials, see the [external learning resources](/getting-started/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/ [directory structure]: /getting-started/directory-structure/ +[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/ [forum]: https://discourse.gohugo.io/ [front matter]: /content-management/front-matter/ [Git submodule]: https://git-scm.com/book/en/v2/Git-Tools-Submodules -[hosting and deployment]: /hosting-and-deployment/ +[host and deploy]: /host-and-deploy/ [Install Git]: https://git-scm.com/book/en/v2/Getting-Started-Installing-Git [Install Hugo]: /installation/ -[Requesting Help]: https://discourse.gohugo.io/t/requesting-help/9132 -[Requesting Help]: https://discourse.gohugo.io/t/requesting-help/9132 -[site configuration]: /getting-started/configuration/ +[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 +[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 3380b0ff2..d6bc42550 100644 --- a/content/en/getting-started/usage.md +++ b/content/en/getting-started/usage.md @@ -1,14 +1,9 @@ --- title: Basic usage -description: Hugo's command line interface (CLI) is fully featured but simple to use, even for those with limited experience working from the command line. -categories: [getting started] -keywords: [usage,livereload,command,flags] -menu: - docs: - parent: getting-started - weight: 30 -weight: 30 -toc: true +description: Use the command-line interface (CLI) to perform basic tasks. +categories: [] +keywords: [] +weight: 20 aliases: [/overview/usage/,/extras/livereload/,/doc/usage/,/usage/] --- @@ -50,11 +45,10 @@ hugo 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. -{{% 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. - -Depending on your needs, you may wish to manually clear the contents of the `public` directory before every build. -{{% /note %}} +> [!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. +> +> Depending on your needs, you may wish to manually clear the contents of the `public` directory before every build. ## Draft, future, and expired content @@ -67,12 +61,8 @@ Hugo allows you to set `draft`, `date`, `publishDate`, and `expiryDate` in the [ {{< new-in 0.123.0 />}} -{{% 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. - -[build options]: /content-management/build-options/ -[`cascade`]: /content-management/front-matter/#cascade-field -{{% /note %}} +> [!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: @@ -84,11 +74,10 @@ hugo --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. -{{% 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. - -A common practice is to manually clear the contents of the `public` directory before each build to remove draft, expired, and future content. -{{% /note %}} +> [!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. +> +> A common practice is to manually clear the contents of the `public` directory before each build to remove draft, expired, and future content. ## Develop and test your site @@ -122,9 +111,8 @@ 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. -{{% /note %}} +> [!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. When you are ready to deploy your site, run: @@ -154,25 +142,25 @@ public/ In a simple hosting environment, where you typically `ftp`, `rsync`, or `scp` your files to the root of a virtual host, the contents of the `public` directory are all that you need. -Most of our users deploy their sites using a CI/CD workflow, where a push[^1] to their GitHub or GitLab repository triggers a build and deployment. Popular providers include [AWS Amplify], [CloudCannon], [Cloudflare Pages], [GitHub Pages], [GitLab Pages], and [Netlify]. +Most of our users deploy their sites using a [CI/CD](g) workflow, where a push[^1] to their GitHub or GitLab repository triggers a build and deployment. Popular providers include [AWS Amplify], [CloudCannon], [Cloudflare Pages], [GitHub Pages], [GitLab Pages], and [Netlify]. -Learn more in the [hosting and deployment] section. +Learn more in the [host and deploy] section. [^1]: The Git repository contains the entire project directory, typically excluding the `public` directory because the site is built _after_ the push. [`--destination`]: /commands/hugo/#options +[`cascade`]: /content-management/front-matter/#cascade [`hugo server`]: /commands/hugo_server/ [`hugo`]: /commands/hugo/ -[`publishDir`]: /getting-started/configuration/#publishdir +[`publishDir`]: /configuration/all/#publishdir [AWS Amplify]: https://aws.amazon.com/amplify/ +[build options]: /content-management/build-options/ [CloudCannon]: https://cloudcannon.com/ [Cloudflare Pages]: https://pages.cloudflare.com/ -[commands]: /commands/ [front matter]: /content-management/front-matter/ [GitHub Pages]: https://pages.github.com/ [GitLab Pages]: https://docs.gitlab.com/ee/user/project/pages/ -[hosting and deployment]: /hosting-and-deployment/ -[hosting]: /hosting-and-deployment/ +[host and deploy]: /host-and-deploy/ [installing]: /installation/ [LiveReload]: https://github.com/livereload/livereload-js [Netlify]: https://www.netlify.com/ diff --git a/content/en/host-and-deploy/_index.md b/content/en/host-and-deploy/_index.md new file mode 100644 index 000000000..627f12c36 --- /dev/null +++ b/content/en/host-and-deploy/_index.md @@ -0,0 +1,8 @@ +--- +title: Host and deploy +description: Services and tools to host and deploy your site. +categories: [] +keywords: [] +weight: 10 +aliases: [/hosting-and-deployment/] +--- diff --git a/content/en/host-and-deploy/deploy-with-hugo-deploy.md b/content/en/host-and-deploy/deploy-with-hugo-deploy.md new file mode 100644 index 000000000..8feeccbae --- /dev/null +++ b/content/en/host-and-deploy/deploy-with-hugo-deploy.md @@ -0,0 +1,97 @@ +--- +title: Deploy with hugo +description: Deploy your site with the hugo CLI. +categories: [] +keywords: [] +aliases: [/hosting-and-deployment/hugo-deploy/] +--- + +Use the `hugo deploy` command to deploy your site Amazon S3, Azure Blob Storage, or Google Cloud Storage. + +> [!note] +> This feature requires the Hugo extended/deploy edition. See the [installation] section for details. + +## Assumptions + +1. You have completed the [Quick Start] or have a Hugo website you are ready to deploy and share with the world. +1. You have an account with the service provider ([AWS], [Azure], or [Google Cloud]) that you want to deploy to. +1. You have authenticated. + - AWS: [Install the CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-install.html) and run [`aws configure`](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-configure.html). + - Azure: [Install the CLI](https://docs.microsoft.com/en-us/cli/azure/install-azure-cli) and run [`az login`](https://docs.microsoft.com/en-us/cli/azure/authenticate-azure-cli). + - Google Cloud: [Install the CLI](https://cloud.google.com/sdk) and run [`gcloud auth login`](https://cloud.google.com/sdk/gcloud/reference/auth/login). + + Each service supports various authentication methods, including environment variables. See [details](https://gocloud.dev/howto/blob/#services). + +1. You have created a bucket to deploy to. If you want your site to be + public, be sure to configure the bucket to be publicly readable as a static website. + - AWS: [create a bucket](https://docs.aws.amazon.com/AmazonS3/latest/gsg/CreatingABucket.html) and [host a static website](https://docs.aws.amazon.com/AmazonS3/latest/userguide/WebsiteHosting.html) + - Azure: [create a storage container](https://docs.microsoft.com/en-us/azure/storage/blobs/storage-quickstart-blobs-portal) and [host a static website](https://learn.microsoft.com/en-us/azure/storage/blobs/storage-blob-static-website) + + - Google Cloud: [create a bucket](https://cloud.google.com/storage/docs/creating-buckets) and [host a static website](https://cloud.google.com/storage/docs/hosting-static-website) + +## Configuration + +Create a deployment target in your [site configuration]. The only required parameters are [`name`] and [`url`]: + +{{< code-toggle file=hugo >}} +[deployment] + [[deployment.targets]] + name = 'production' + url = 's3://my_bucket?region=us-west-1' +{{< /code-toggle >}} + +## Deploy + +To deploy to a target: + +```bash +hugo deploy [--target=] +``` + +This command syncs the contents of your local `public` directory (the default publish directory) with the destination bucket. If no target is specified, Hugo deploys to the first configured target. + +For more command-line options, see `hugo help deploy` or the [CLI documentation]. + +### File list creation + +`hugo deploy` creates local and remote file lists by traversing the local publish directory and the remote bucket. Inclusion and exclusion are determined by the deployment target's [configuration]: + +- `include`: All files are skipped by default except those that match the pattern. +- `exclude`: Files matching the pattern are skipped. + +> [!note] +> During local file list creation, Hugo skips `.DS_Store` files and hidden directories (those starting with a period, like `.git`), except for the [`.well-known`] directory, which is traversed if present. + +### File list comparison + +Hugo compares the local and remote file lists to identify necessary changes. It first compares file names. If both exist, it compares sizes and MD5 checksums. Any difference triggers a re-upload, and remote files not present locally are deleted. + +> [!note] +> Excluded remote files (due to `include`/`exclude` configuration) won't be deleted. + +The `--force` flag forces all files to be re-uploaded, even if Hugo detects no local/remote differences. + +The `--confirm` or `--dryRun` flags cause Hugo to display the detected differences and then pause or stop. + +### Synchronization + +Hugo applies the changes to the remote bucket: uploading missing or changed files and deleting remote files not present locally. Uploaded file headers are configured remotely based on the matchers configuration. + +> [!note] +> To prevent accidental data loss, Hugo will not delete more than 256 remote files by default. Use the `--maxDeletes` flag to override this limit. + +## Advanced configuration + +See [configure deployment](/configuration/deployment/). + +[`.well-known`]: https://en.wikipedia.org/wiki/Well-known_URI +[`name`]: /configuration/deployment/#name +[`url`]: /configuration/deployment/#url +[AWS]: https://aws.amazon.com +[Azure]: https://azure.microsoft.com +[CLI documentation]: /commands/hugo_deploy/ +[configuration]: /configuration/deployment/#targets-1 +[Google Cloud]: https://cloud.google.com/ +[installation]: /installation/ +[Quick Start]: /getting-started/quick-start/ +[site configuration]: /configuration/deployment/ diff --git a/content/en/hosting-and-deployment/deployment-with-rclone.md b/content/en/host-and-deploy/deploy-with-rclone.md similarity index 64% rename from content/en/hosting-and-deployment/deployment-with-rclone.md rename to content/en/host-and-deploy/deploy-with-rclone.md index 410851553..8f641bc5d 100644 --- a/content/en/hosting-and-deployment/deployment-with-rclone.md +++ b/content/en/host-and-deploy/deploy-with-rclone.md @@ -1,22 +1,18 @@ --- -title: Deploy with Rclone -description: If you have access to your web host with SFTP/FTP/SSH/HTTP(DAV), you can use rclone to incrementally deploy your entire Hugo website. -categories: [hosting and deployment] -keywords: [deployment,rclone,sftp] -menu: - docs: - parent: hosting-and-deployment -toc: true -aliases: [/tutorials/deployment-with-rclone/] +title: Deploy with rclone +description: Deploy your site with the rclone CLI. +categories: [] +keywords: [] +aliases: [/hosting-and-deployment/deployment-with-rclone/] --- ## Assumptions -* A web host running a web server. This could be a shared hosting environment or a VPS. -* Access to your web host with any of the [protocols supported by rclone](https://rclone.org/#providers), such as SFTP. -* A functional static website built with Hugo -* Deploying from an [Rclone](https://rclone.org) compatible operating system -* You have [installed Rclone](https://rclone.org/install/). +- A web host running a web server. This could be a shared hosting environment or a VPS. +- Access to your web host with any of the [protocols supported by rclone](https://rclone.org/#providers), such as SFTP. +- A functional static website built with Hugo +- 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. diff --git a/content/en/hosting-and-deployment/deployment-with-rsync.md b/content/en/host-and-deploy/deploy-with-rsync.md similarity index 87% rename from content/en/hosting-and-deployment/deployment-with-rsync.md rename to content/en/host-and-deploy/deploy-with-rsync.md index 8fb428686..d073107fe 100644 --- a/content/en/hosting-and-deployment/deployment-with-rsync.md +++ b/content/en/host-and-deploy/deploy-with-rsync.md @@ -1,20 +1,16 @@ --- -title: Deploy with Rsync -description: If you have access to your web host with SSH, you can use a simple rsync one-liner to incrementally deploy your entire Hugo website. -categories: [hosting and deployment] -keywords: [deployment,rsync] -menu: - docs: - parent: hosting-and-deployment -toc: true -aliases: [/tutorials/deployment-with-rsync/] +title: Deploy with rsync +description: Deploy your site with the rsync CLI. +categories: [] +keywords: [] +aliases: [/hosting-and-deployment/deployment-with-rsync/] --- ## Assumptions -* A web host running a web server. This could be a shared hosting environment or a VPS. -* Access to your web host with SSH -* A functional static website built with Hugo +- A web host running a web server. This could be a shared hosting environment or a VPS. +- Access to your web host with SSH +- A functional static website built with Hugo The spoiler is that you can deploy your entire website with a command that looks like the following: @@ -30,9 +26,9 @@ To make logging in to your server more secure and less interactive, you can uplo First, install the ssh client. On Debian distributions, use the following command: -{{< code file=install-openssh.sh >}} +```sh {file="install-openssh.sh"} sudo apt-get install openssh-client -{{< /code >}} +``` Then generate your ssh key. First, create the `.ssh` directory in your home directory if it doesn't exist: diff --git a/content/en/hosting-and-deployment/hosting-on-21yunbox.md b/content/en/host-and-deploy/host-on-21yunbox.md similarity index 51% rename from content/en/hosting-and-deployment/hosting-on-21yunbox.md rename to content/en/host-and-deploy/host-on-21yunbox.md index 4b02995e0..9ef684fd8 100644 --- a/content/en/hosting-and-deployment/hosting-on-21yunbox.md +++ b/content/en/host-and-deploy/host-on-21yunbox.md @@ -1,22 +1,19 @@ --- title: Host on 21YunBox -description: Host your Hugo site with 21YunBox's blazing fast Chinese CDN, fully-managed SSL and auto deploys from Gitee. -categories: [hosting and deployment] -keywords: [hosting,21yunbox] -menu: - docs: - parent: hosting-and-deployment -toc: true +description: Host your site on 21YunBox. +categories: [] +keywords: [] +aliases: [/hosting-and-deployment/hosting-on-21yunbox/] --- -[21YunBox](https://www.21yunbox.com) is a fully-managed cloud platform dedicated to make web deployment easy within the Chinese Great Firewall where you can host static sites, backend APIs, databases, cron jobs, and all your other apps in one place. It provides blazing fast Chinese CDN, continuous deployment, one-click HTTPS and [other services like managed databases and backend web services](https://www.21yunbox.com/docs/), providing an avenue to launch web projects in China. +[21YunBox](https://www.21cloudbox.com/) is a fully-managed cloud platform dedicated to make web deployment easy within the Chinese Great Firewall where you can host static sites, backend APIs, databases, cron jobs, and all your other apps in one place. It provides blazing fast Chinese CDN, continuous deployment, one-click HTTPS and [other services like managed databases and backend web services](https://www.21cloudbox.com/docs/), providing an avenue to launch web projects in China. 21YunBox includes the following features: - Continuous, automatic builds & deploys from GitHub and Gitee - Automatic SSL certificates through [Let's Encrypt](https://letsencrypt.org) - Instant cache invalidation with a blazing fast, Chinese CDN -- Unlimited [custom domains](https://www.21yunbox.com/docs/#/custom-domains) +- Unlimited [custom domains](https://www.21cloudbox.com/dns-configuration.html) - Automatic [Brotli compression](https://en.wikipedia.org/wiki/Brotli) for faster sites - Native HTTP/2 support - Automatic HTTP → HTTPS redirects @@ -31,13 +28,12 @@ This guide assumes you already have a Hugo project to deploy. If you need a proj You can set up a Hugo site on 21YunBox in two quick steps: 1. Create a new web service on 21YunBox, and give 21YunBox permission to access your GitHub or Gitee repo. -1. Use the following values during creation: - - | Field | Value | - | --------------------- | ------------------------------------------------ | - | **Environment** | `Static Site` | - | **Build Command** | `hugo --gc --minify` (or your own build command) | - | **Publish Directory** | `./public` (or your own output directory) | +1. Use the following values during creation: + | Field | Value | + | ----------------- | ------------------------------------------------ | + | Environment | `Static Site` | + | Build Command | `hugo --gc --minify` (or your own build command) | + | Publish Directory | `./public` (or your own output directory) | That's it! Your site will be live on your 21YunBox URL (which looks like `yoursite.21yunbox.com`) as soon as the build is done. @@ -49,8 +45,8 @@ Every deploy automatically and instantly invalidates the CDN cache, so your user ## Custom domains -Add your own domains to your site easily using 21YunBox's [custom domains](https://www.21yunbox.com/docs/#/custom-domains) guide. +Add your own domains to your site easily using 21YunBox's [custom domains](https://www.21cloudbox.com/dns-configuration.html) guide. ## Support -Click [here](https://www.21yunbox.com/docs/#/contact) to contact with 21YunBox' experts if you need help. +Click [here](https://www.21cloudbox.com/contact.html) to contact with 21YunBox' experts if you need help. diff --git a/content/en/hosting-and-deployment/hosting-on-aws-amplify/amplify-step-05.png b/content/en/host-and-deploy/host-on-aws-amplify/amplify-step-05.png similarity index 100% rename from content/en/hosting-and-deployment/hosting-on-aws-amplify/amplify-step-05.png rename to content/en/host-and-deploy/host-on-aws-amplify/amplify-step-05.png diff --git a/content/en/hosting-and-deployment/hosting-on-aws-amplify/amplify-step-06.png b/content/en/host-and-deploy/host-on-aws-amplify/amplify-step-06.png similarity index 100% rename from content/en/hosting-and-deployment/hosting-on-aws-amplify/amplify-step-06.png rename to content/en/host-and-deploy/host-on-aws-amplify/amplify-step-06.png diff --git a/content/en/hosting-and-deployment/hosting-on-aws-amplify/amplify-step-07.png b/content/en/host-and-deploy/host-on-aws-amplify/amplify-step-07.png similarity index 100% rename from content/en/hosting-and-deployment/hosting-on-aws-amplify/amplify-step-07.png rename to content/en/host-and-deploy/host-on-aws-amplify/amplify-step-07.png diff --git a/content/en/hosting-and-deployment/hosting-on-aws-amplify/amplify-step-08.png b/content/en/host-and-deploy/host-on-aws-amplify/amplify-step-08.png similarity index 100% rename from content/en/hosting-and-deployment/hosting-on-aws-amplify/amplify-step-08.png rename to content/en/host-and-deploy/host-on-aws-amplify/amplify-step-08.png diff --git a/content/en/hosting-and-deployment/hosting-on-aws-amplify/amplify-step-09.png b/content/en/host-and-deploy/host-on-aws-amplify/amplify-step-09.png similarity index 100% rename from content/en/hosting-and-deployment/hosting-on-aws-amplify/amplify-step-09.png rename to content/en/host-and-deploy/host-on-aws-amplify/amplify-step-09.png diff --git a/content/en/hosting-and-deployment/hosting-on-aws-amplify/amplify-step-11.png b/content/en/host-and-deploy/host-on-aws-amplify/amplify-step-11.png similarity index 100% rename from content/en/hosting-and-deployment/hosting-on-aws-amplify/amplify-step-11.png rename to content/en/host-and-deploy/host-on-aws-amplify/amplify-step-11.png diff --git a/content/en/hosting-and-deployment/hosting-on-aws-amplify/index.md b/content/en/host-and-deploy/host-on-aws-amplify/index.md similarity index 68% rename from content/en/hosting-and-deployment/hosting-on-aws-amplify/index.md rename to content/en/host-and-deploy/host-on-aws-amplify/index.md index 3172ecb83..aadb89116 100644 --- a/content/en/hosting-and-deployment/hosting-on-aws-amplify/index.md +++ b/content/en/host-and-deploy/host-on-aws-amplify/index.md @@ -1,12 +1,9 @@ --- title: Host on AWS Amplify -description: Host your site on AWS Amplify with continuous deployment. -categories: [hosting and deployment] -keywords: [hosting] -menu: - docs: - parent: hosting-and-deployment -toc: true +description: Host your site on AWS Amplify. +categories: [] +keywords: [] +aliases: [/hosting-and-deployment/hosting-on-aws-amplify/] --- ## Prerequisites @@ -30,24 +27,26 @@ Please complete the following tasks before continuing: This procedure will enable continuous deployment from a GitHub repository. The procedure is essentially the same if you are using GitLab or Bitbucket. -Step 1 -: Create a file named `amplify.yml` in the root of your project. +### Step 1 + +Create a file named `amplify.yml` in the root of your project. ```sh touch amplify.yml ``` -Step 2 -: Copy and paste the YAML below into the file you created. Change the application versions and time zone as needed. +### Step 2 -{{< code file=amplify.yml copy=true >}} +Copy and paste the YAML below into the file you created. Change the application versions and time zone as needed. + +```yaml {file="amplify.yml" copy=true} version: 1 env: variables: # Application versions - DART_SASS_VERSION: 1.81.0 + DART_SASS_VERSION: 1.85.0 GO_VERSION: 1.23.3 - HUGO_VERSION: 0.139.3 + HUGO_VERSION: 0.144.2 # Time zone TZ: America/Los_Angeles # Cache @@ -98,10 +97,11 @@ frontend: paths: - ${HUGO_CACHEDIR}/**/* - ${NPM_CONFIG_CACHE}/**/* -{{< /code >}} +``` -Step 3 -: Commit and push the change to your GitHub repository. +### Step 3 + +Commit and push the change to your GitHub repository. ```sh git add -A @@ -109,43 +109,52 @@ git commit -m "Create amplify.yml" git push ``` -Step 4 -: Log in to your AWS account, navigate to the [Amplify Console], then press the **Deploy an app** button. +### Step 4 + +Log in to your AWS account, navigate to the [Amplify Console], then press the **Deploy an app** button. [Amplify Console]: https://console.aws.amazon.com/amplify/apps -Step 5 -: Choose a source code provider, then press the **Next** button. +### Step 5 + +Choose a source code provider, then press the **Next** button. ![screen capture](amplify-step-05.png) -Step 6 -: Authorize AWS Amplify to access your GitHub account. +### Step 6 + +Authorize AWS Amplify to access your GitHub account. ![screen capture](amplify-step-06.png) -Step 7 -: Select your personal account or relevant organization. +### Step 7 + +Select your personal account or relevant organization. ![screen capture](amplify-step-07.png) -Step 8 -: Authorize access to one or more repositories. +### Step 8 + +Authorize access to one or more repositories. ![screen capture](amplify-step-08.png) -Step 9 -: Select a repository and branch, then press the **Next** button. +### Step 9 + +Select a repository and branch, then press the **Next** button. ![screen capture](amplify-step-09.png) -Step 10 -: On the "App settings" page, scroll to the bottom then press the **Next** button. Amplify reads the `amplify.yml` file you created in Steps 1-3 instead of using the values on this page. +### Step 10 -Step 11 -: On the "Review" page, scroll to the bottom then press the **Save and deploy** button. +On the "App settings" page, scroll to the bottom then press the **Next** button. Amplify reads the `amplify.yml` file you created in Steps 1-3 instead of using the values on this page. -Step 12 -: When your site has finished deploying, press the **Visit deployed URL** button to view your published site. +### Step 11 + +On the "Review" page, scroll to the bottom then press the **Save and deploy** button. + +### Step 12 + +When your site has finished deploying, press the **Visit deployed URL** button to view your published site. ![screen capture](amplify-step-11.png) diff --git a/content/en/hosting-and-deployment/hosting-on-azure-static-web-apps.md b/content/en/host-and-deploy/host-on-azure-static-web-apps.md similarity index 73% rename from content/en/hosting-and-deployment/hosting-on-azure-static-web-apps.md rename to content/en/host-and-deploy/host-on-azure-static-web-apps.md index 922cbfef2..68fe145ab 100644 --- a/content/en/hosting-and-deployment/hosting-on-azure-static-web-apps.md +++ b/content/en/host-and-deploy/host-on-azure-static-web-apps.md @@ -1,12 +1,9 @@ --- title: Host on Azure Static Web Apps -description: Publish a Hugo site to Azure Static Web Apps. -categories: [hosting and deployment] -keywords: [hosting,azure] -menu: - docs: - parent: hosting-and-deployment -toc: true +description: Host your site on Azure Static Web Apps. +categories: [] +keywords: [] +aliases: [/hosting-and-deployment/hosting-on-azure-static-web-apps/] --- You can create and deploy a Hugo web application to Azure Static Web Apps. The final result is a new Azure Static Web App with associated GitHub Actions that give you control over how the app is built and published. You'll learn how to create a Hugo app, set up an Azure Static Web App and deploy the Hugo app to Azure. diff --git a/content/en/hosting-and-deployment/hosting-on-cloudflare-pages.md b/content/en/host-and-deploy/host-on-cloudflare-pages.md similarity index 60% rename from content/en/hosting-and-deployment/hosting-on-cloudflare-pages.md rename to content/en/host-and-deploy/host-on-cloudflare-pages.md index e50143db7..1c3627288 100644 --- a/content/en/hosting-and-deployment/hosting-on-cloudflare-pages.md +++ b/content/en/host-and-deploy/host-on-cloudflare-pages.md @@ -1,12 +1,9 @@ --- title: Host on Cloudflare Pages -description: Cloudflare Pages can host your Hugo site with CDN, continuous deployment, 1-click HTTPS, an admin GUI, and its own environment variables. -categories: [hosting and deployment] -keywords: [hosting,cloudflare] -menu: - docs: - parent: hosting-and-deployment -toc: true +description: Host your site on Cloudflare Pages. +categories: [] +keywords: [] +aliases: [/hosting-and-deployment/hosting-on-cloudflare-pages/] --- [Cloudflare Pages](https://developers.cloudflare.com/pages/) are super fast, always up-to-date, and deployed directly from your [Git provider](https://developers.cloudflare.com/pages/get-started/#connect-your-git-provider-to-pages). diff --git a/content/en/host-and-deploy/host-on-codeberg-pages.md b/content/en/host-and-deploy/host-on-codeberg-pages.md new file mode 100644 index 000000000..cd137c420 --- /dev/null +++ b/content/en/host-and-deploy/host-on-codeberg-pages.md @@ -0,0 +1,82 @@ +--- +title: Host on Codeberg Pages +description: Host your site on Codeberg Pages. +categories: [] +keywords: [] +aliases: [/hosting-and-deployment/hosting-on-codeberg/] +--- + +## Assumptions + +- Working familiarity with [Git] for version control +- Completion of the Hugo [Quick Start] +- A [Codeberg account] +- A Hugo website on your local machine that you are ready to publish + +[Codeberg account]: https://codeberg.org/user/login/ +[Git]: https://git-scm.com/ +[Quick Start]: /getting-started/quick-start/ + +Any and all mentions of `` refer to your actual Codeberg username and must be substituted accordingly. Likewise, `` represents your actual website name. + +## BaseURL + +The [`baseURL`] in your site configuration must reflect the full URL provided by Codeberg Pages if using the default address (e.g. `https://.codeberg.page/`). If you want to use another domain, follow the instructions in the [custom domain section] of the official documentation. + +[`baseURL`]: /configuration/all/#baseurl +[custom domain section]: https://docs.codeberg.org/codeberg-pages/using-custom-domain/ + +For more details regarding the URL of your deployed website, refer to Codeberg Pages' [quickstart instructions]. + +[quickstart instructions]: https://codeberg.page/ + +## Manual deployment + +Create a public repository on your Codeberg account titled `pages` or create a branch of the same name in an existing public repository. Finally, push the contents of Hugo's output directory (by default, `public`) to it. Here's an example: + +```sh +# build the website +hugo + +# access the output directory +cd public + +# initialize new git repository +git init + +# commit and push code to main branch +git add . +git commit -m "Initial commit" +git remote add origin https://codeberg.org//pages.git +git push -u origin main +``` + +## Automated deployment + +In order to automatically deploy your Hugo website, you need to have or [request] access to Codeberg's CI, as well as add a `.woodpecker.yaml` file in the root of your project. A template and additional instructions are available in the official [examples repository]. + +[request]: https://codeberg.org/Codeberg-e.V./requests/issues/new?template=ISSUE_TEMPLATE%2fWoodpecker-CI.yaml +[examples repository]: https://codeberg.org/Codeberg-CI/examples/src/branch/main/Hugo/.woodpecker.yaml + +In this case, you must create a public repository on Codeberg (e.g. ``) and push your local project to it. Here's an example: + +```sh +# initialize new git repository +git init + +# add /public directory to our .gitignore file +echo "/public" >> .gitignore + +# commit and push code to main branch +git add . +git commit -m "Initial commit" +git remote add origin https://codeberg.org//.git +git push -u origin main +``` + +Your project will then be built and deployed by Codeberg's CI. + +## Other resources + +- [Codeberg Pages](https://codeberg.page/) +- [Codeberg Pages official documentation](https://docs.codeberg.org/codeberg-pages/) diff --git a/content/en/hosting-and-deployment/hosting-on-firebase.md b/content/en/host-and-deploy/host-on-firebase.md similarity index 75% rename from content/en/hosting-and-deployment/hosting-on-firebase.md rename to content/en/host-and-deploy/host-on-firebase.md index 028964bcf..267c8d127 100644 --- a/content/en/hosting-and-deployment/hosting-on-firebase.md +++ b/content/en/host-and-deploy/host-on-firebase.md @@ -1,18 +1,15 @@ --- title: Host on Firebase -description: You can use Firebase's free tier to host your static website; this also gives you access to Firebase's NoSQL API. -categories: [hosting and deployment] -keywords: [hosting,firebase] -menu: - docs: - parent: hosting-and-deployment -toc: true +description: Host your site on Firebase. +categories: [] +keywords: [] +aliases: [/hosting-and-deployment/hosting-on-firebase/] --- ## Assumptions 1. You have an account with [Firebase][signup]. (If you don't, you can sign up for free using your Google account.) -2. You have completed the [Quick Start] or have a completed Hugo website ready for deployment. +1. You have completed the [Quick Start] or have a completed Hugo website ready for deployment. ## Initial setup @@ -37,10 +34,10 @@ firebase init From here: 1. Choose Hosting in the feature question -2. Choose the project you just set up -3. Accept the default for your database rules file -4. Accept the default for the publish directory, which is `public` -5. Choose "No" in the question if you are deploying a single-page app +1. Choose the project you just set up +1. Accept the default for your database rules file +1. Accept the default for the publish directory, which is `public` +1. Choose "No" in the question if you are deploying a single-page app ## Using Firebase & GitHub CI/CD @@ -63,7 +60,7 @@ Here is your opportunity to include some commands before you run the deploy. You can let in the default option (main) -After that Firebase has been set in your project with CI/CD. After that run: +After that Firebase has been set in your project with [CI/CD](g). After that run: ```sh hugo && firebase deploy @@ -91,9 +88,8 @@ firebase login:ci You can also set up your CI and add the token to a private variable like `$FIREBASE_DEPLOY_TOKEN`. -{{% note %}} -This is a private secret and it should not appear in a public repository. Make sure you understand your chosen CI and that it's not visible to others. -{{% /note %}} +> [!note] +> This is a private secret and it should not appear in a public repository. Make sure you understand your chosen CI and that it's not visible to others. You can then add a step in your build to do the deployment using the token: @@ -103,7 +99,7 @@ firebase deploy --token $FIREBASE_DEPLOY_TOKEN ## Reference links -* [Firebase CLI Reference](https://firebase.google.com/docs/cli/#administrative_commands) +- [Firebase CLI Reference](https://firebase.google.com/docs/cli/#administrative_commands) [console]: https://console.firebase.google.com/ [Quick Start]: /getting-started/quick-start/ diff --git a/content/en/hosting-and-deployment/hosting-on-github/gh-pages-1.png b/content/en/host-and-deploy/host-on-github-pages/gh-pages-1.png similarity index 100% rename from content/en/hosting-and-deployment/hosting-on-github/gh-pages-1.png rename to content/en/host-and-deploy/host-on-github-pages/gh-pages-1.png diff --git a/content/en/hosting-and-deployment/hosting-on-github/gh-pages-2.png b/content/en/host-and-deploy/host-on-github-pages/gh-pages-2.png similarity index 100% rename from content/en/hosting-and-deployment/hosting-on-github/gh-pages-2.png rename to content/en/host-and-deploy/host-on-github-pages/gh-pages-2.png diff --git a/content/en/hosting-and-deployment/hosting-on-github/gh-pages-3.png b/content/en/host-and-deploy/host-on-github-pages/gh-pages-3.png similarity index 100% rename from content/en/hosting-and-deployment/hosting-on-github/gh-pages-3.png rename to content/en/host-and-deploy/host-on-github-pages/gh-pages-3.png diff --git a/content/en/hosting-and-deployment/hosting-on-github/gh-pages-4.png b/content/en/host-and-deploy/host-on-github-pages/gh-pages-4.png similarity index 100% rename from content/en/hosting-and-deployment/hosting-on-github/gh-pages-4.png rename to content/en/host-and-deploy/host-on-github-pages/gh-pages-4.png diff --git a/content/en/hosting-and-deployment/hosting-on-github/gh-pages-5.png b/content/en/host-and-deploy/host-on-github-pages/gh-pages-5.png similarity index 100% rename from content/en/hosting-and-deployment/hosting-on-github/gh-pages-5.png rename to content/en/host-and-deploy/host-on-github-pages/gh-pages-5.png diff --git a/content/en/hosting-and-deployment/hosting-on-github/index.md b/content/en/host-and-deploy/host-on-github-pages/index.md similarity index 62% rename from content/en/hosting-and-deployment/hosting-on-github/index.md rename to content/en/host-and-deploy/host-on-github-pages/index.md index 81d6a4c87..4c00fbc8e 100644 --- a/content/en/hosting-and-deployment/hosting-on-github/index.md +++ b/content/en/host-and-deploy/host-on-github-pages/index.md @@ -1,13 +1,9 @@ --- title: Host on GitHub Pages -description: Host your site on GitHub Pages with continuous deployment using project, user, or organization pages. -categories: [hosting and deployment] -keywords: [hosting] -menu: - docs: - parent: hosting-and-deployment -toc: true -aliases: [/tutorials/github-pages-blog/] +description: Host your site on GitHub Pages. +categories: [] +keywords: [] +aliases: [/hosting-and-deployment/hosting-on-github/] --- ## Prerequisites @@ -18,54 +14,65 @@ Please complete the following tasks before continuing: 1. [Install Git] 1. [Create a Hugo site] and test it locally with `hugo server`. -[Create a GitHub account]: https://github.com/signup -[Install Git]: https://git-scm.com/book/en/v2/Getting-Started-Installing-Git -[Create a Hugo site]: /getting-started/quick-start/ - ## Types of sites There are three types of GitHub Pages sites: project, user, and organization. Project sites are connected to a specific project hosted on GitHub. User and organization sites are connected to a specific account on GitHub.com. -{{% note %}} -See the [GitHub Pages documentation] to understand the requirements for repository ownership and naming. - -[GitHub Pages documentation]: https://docs.github.com/en/pages/getting-started-with-github-pages/about-github-pages#types-of-github-pages-sites -{{% /note %}} - -[GitHub Pages documentation]: https://docs.github.com/en/pages/getting-started-with-github-pages/about-github-pages#types-of-github-pages-sites +> [!note] +> See the [GitHub Pages documentation] to understand the requirements for repository ownership and naming. ## Procedure -Step 1 -: Create a GitHub repository. +### Step 1 -Step 2 -: Push your local repository to GitHub. +Create a GitHub repository. -Step 3 -: Visit your GitHub repository. From the main menu choose **Settings** > **Pages**. In the center of your screen you will see this: +### Step 2 + +Push your local repository to GitHub. + +### Step 3 + +Visit your GitHub repository. From the main menu choose **Settings** > **Pages**. In the center of your screen you will see this: ![screen capture](gh-pages-1.png) {style="max-width: 280px"} -Step 4 -: Change the **Source** to `GitHub Actions`. The change is immediate; you do not have to press a Save button. +### Step 4 + +Change the **Source** to `GitHub Actions`. The change is immediate; you do not have to press a Save button. ![screen capture](gh-pages-2.png) {style="max-width: 280px"} -Step 5 -: Create a file named `hugo.yaml` in a directory named `.github/workflows`. +### Step 5 + +In your site configuration, change the location of the image cache to the [`cacheDir`] as shown below: + +{{< code-toggle file=hugo >}} +[caches.images] +dir = ":cacheDir/images" +{{< /code-toggle >}} + +See [configure file caches] for more information. + +### Step 6 + +Create a file named `hugo.yaml` in a directory named `.github/workflows`. ```text mkdir -p .github/workflows -touch hugo.yaml +touch .github/workflows/hugo.yaml ``` -Step 6 -: Copy and paste the YAML below into the file you created. Change the branch name and Hugo version as needed. +### Step 7 -{{< code file=.github/workflows/hugo.yaml copy=true >}} +> [!note] +> The workflow below ensures Hugo's `cacheDir` is persistent, preserving modules, processed images, and [`resources.GetRemote`] data between builds. + +Copy and paste the YAML below into the file you created. Change the branch name and Hugo version as needed. + +```yaml {file=".github/workflows/hugo.yaml" copy=true} # Sample workflow for building and deploying a Hugo site to GitHub Pages name: Deploy Hugo site to Pages @@ -100,7 +107,9 @@ jobs: build: runs-on: ubuntu-latest env: - HUGO_VERSION: 0.141.0 + HUGO_VERSION: 0.145.0 + HUGO_ENVIRONMENT: production + TZ: America/Los_Angeles steps: - name: Install Hugo CLI run: | @@ -118,16 +127,29 @@ jobs: uses: actions/configure-pages@v5 - name: Install Node.js dependencies run: "[[ -f package-lock.json || -f npm-shrinkwrap.json ]] && npm ci || true" + - name: Cache Restore + id: cache-restore + uses: actions/cache/restore@v4 + with: + path: | + ${{ runner.temp }}/hugo_cache + key: hugo-${{ github.run_id }} + restore-keys: + hugo- - name: Build with Hugo - env: - HUGO_CACHEDIR: ${{ runner.temp }}/hugo_cache - HUGO_ENVIRONMENT: production - TZ: America/Los_Angeles run: | hugo \ --gc \ --minify \ - --baseURL "${{ steps.pages.outputs.base_url }}/" + --baseURL "${{ steps.pages.outputs.base_url }}/" \ + --cacheDir "${{ runner.temp }}/hugo_cache" + - name: Cache Save + id: cache-save + uses: actions/cache/save@v4 + with: + path: | + ${{ runner.temp }}/hugo_cache + key: ${{ steps.cache-restore.outputs.cache-primary-key }} - name: Upload artifact uses: actions/upload-pages-artifact@v3 with: @@ -144,10 +166,11 @@ jobs: - name: Deploy to GitHub Pages id: deployment uses: actions/deploy-pages@v4 -{{< /code >}} +``` -Step 7 -: Commit and push the change to your GitHub repository. +### Step 8 + +Commit and push the change to your GitHub repository. ```sh git add -A @@ -155,20 +178,23 @@ git commit -m "Create hugo.yaml" git push ``` -Step 8 -: From GitHub's main menu, choose **Actions**. You will see something like this: +### Step 9 + +From GitHub's main menu, choose **Actions**. You will see something like this: ![screen capture](gh-pages-3.png) {style="max-width: 350px"} -Step 9 -: When GitHub has finished building and deploying your site, the color of the status indicator will change to green. +### Step 10 + +When GitHub has finished building and deploying your site, the color of the status indicator will change to green. ![screen capture](gh-pages-4.png) {style="max-width: 350px"} -Step 10 -: Click on the commit message as shown above. You will see this: +### Step 11 + +Click on the commit message as shown above. You will see this: ![screen capture](gh-pages-5.png) {style="max-width: 611px"} @@ -188,10 +214,17 @@ The example workflow above includes this step, which typically takes 10‑15 You may remove this step if your site, themes, and modules do not transpile Sass to CSS using the [Dart Sass] transpiler. -[Dart Sass]: /functions/css/sass/#dart-sass - ## Other resources - [Learn more about GitHub Actions](https://docs.github.com/en/actions) - [Caching dependencies to speed up workflows](https://docs.github.com/en/actions/using-workflows/caching-dependencies-to-speed-up-workflows) - [Manage a custom domain for your GitHub Pages site](https://docs.github.com/en/pages/configuring-a-custom-domain-for-your-github-pages-site/about-custom-domains-and-github-pages) + +[Create a GitHub account]: https://github.com/signup +[Create a Hugo site]: /getting-started/quick-start/ +[Dart Sass]: /functions/css/sass/#dart-sass +[GitHub Pages documentation]: https://docs.github.com/en/pages/getting-started-with-github-pages/about-github-pages#types-of-github-pages-sites +[Install Git]: https://git-scm.com/book/en/v2/Getting-Started-Installing-Git +[`cacheDir`]: /configuration/all/#cachedir +[`resources.GetRemote`]: /functions/resources/getremote/ +[configure file caches]: /configuration/caches/ diff --git a/content/en/hosting-and-deployment/hosting-on-gitlab.md b/content/en/host-and-deploy/host-on-gitlab-pages.md similarity index 72% rename from content/en/hosting-and-deployment/hosting-on-gitlab.md rename to content/en/host-and-deploy/host-on-gitlab-pages.md index 55ac23663..4b308cc19 100644 --- a/content/en/hosting-and-deployment/hosting-on-gitlab.md +++ b/content/en/host-and-deploy/host-on-gitlab-pages.md @@ -1,37 +1,33 @@ --- title: Host on GitLab Pages -description: GitLab makes it easy to build, deploy, and host your Hugo website via their free GitLab Pages service, which provides native support for Hugo. -categories: [hosting and deployment] -keywords: [hosting,gitlab] -menu: - docs: - parent: hosting-and-deployment -toc: true -aliases: [/tutorials/hosting-on-gitlab/] +description: Host your site on GitLab Pages. +categories: [] +keywords: [] +aliases: [/hosting-and-deployment/hosting-on-gitlab/] --- ## Assumptions -* Working familiarity with Git for version control -* Completion of the Hugo [Quick Start] -* A [GitLab account](https://gitlab.com/users/sign_in) -* A Hugo website on your local machine that you are ready to publish +- Working familiarity with Git for version control +- Completion of the Hugo [Quick Start] +- A [GitLab account](https://gitlab.com/users/sign_in) +- A Hugo website on your local machine that you are ready to publish ## BaseURL -The `baseURL` in your [site configuration](/getting-started/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 [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. ## Configure GitLab CI/CD -Define your [CI/CD](https://docs.gitlab.com/ee/ci/quick_start/) jobs by creating a `.gitlab-ci.yml` file in the root of your project. +Define your [CI/CD](g) jobs by creating a `.gitlab-ci.yml` file in the root of your project. -{{< code file=.gitlab-ci.yml copy=true >}} +```yaml {file=".gitlab-ci.yml" copy=true} variables: - DART_SASS_VERSION: 1.81.1 + DART_SASS_VERSION: 1.85.0 GIT_DEPTH: 0 GIT_STRATEGY: clone GIT_SUBMODULE_STRATEGY: recursive - HUGO_VERSION: 0.140.2 + HUGO_VERSION: 0.144.2 NODE_VERSION: 23.x TZ: America/Los_Angeles image: @@ -67,7 +63,7 @@ pages: - public rules: - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH -{{% /code %}} +``` ## Push your Hugo website to GitLab diff --git a/content/en/hosting-and-deployment/hosting-on-keycdn/index.md b/content/en/host-and-deploy/host-on-keycdn/index.md similarity index 70% rename from content/en/hosting-and-deployment/hosting-on-keycdn/index.md rename to content/en/host-and-deploy/host-on-keycdn/index.md index 3073c7172..828e250c6 100644 --- a/content/en/hosting-and-deployment/hosting-on-keycdn/index.md +++ b/content/en/host-and-deploy/host-on-keycdn/index.md @@ -1,11 +1,9 @@ --- title: Host on KeyCDN -description: "Accelerate your Hugo site globally with a KeyCDN integration. This tutorial shows you how to set up your static site as a GitLab page behind a KeyCDN pull zone." -categories: [hosting and deployment] -keywords: [hosting,keycdn] -menu: - docs: - parent: hosting-and-deployment +description: Host your site on KeyCDN. +categories: [] +keywords: [] +aliases: [/hosting-and-deployment/hosting-on-keycdn/] --- [KeyCDN](https://www.keycdn.com/) provides a multitude of features to help accelerate and secure your Hugo site globally including Brotli compression, Let's Encrypt support, Origin Shield, and more. @@ -22,7 +20,7 @@ The first step will be to log in to your KeyCDN account and create a new zone. N ![Screenshot of KeyCDN's pull zone creation page](keycdn-pull-zone.png) -While the origin location doesn’t exist yet, you will need to use your new Zone URL address (or [Zone Alias](https://www.keycdn.com/support/create-a-zone-alias/)) in the `.gitlab-ci.yml` file that will be uploaded to your GitLab project. +While the origin location doesn't exist yet, you will need to use your new Zone URL address (or [Zone Alias](https://www.keycdn.com/support/create-a-zone-alias/)) in the `.gitlab-ci.yml` file that will be uploaded to your GitLab project. Ensure that you use your Zone URL or Zone alias as the `BASEURL` variable in the example below. This will be the user-visible website address. @@ -60,7 +58,7 @@ pages: - master ``` -Using this integration method, you will have to specify the Zone ID and your [KeyCDN API](https://www.keycdn.com/api) key as secret variables. To do this, navigate to the top-left menu bar in GitLab and select Projects. Then, select your project and click on the Settings page. Finally, select Pipelines from the sub-menu and scroll down to the Secret Variable section. +Using this integration method, you will have to specify the Zone ID and your [KeyCDN API](https://www.keycdn.com/api) key as secret variables. To do this, navigate to the top-left menu bar in GitLab and select Projects. Then, select your project and click on the Settings page. Finally, select Pipelines from the sub-menu and scroll down to the Secret Variable section. The Secret Variable for your Zone ID should look similar to: @@ -70,7 +68,7 @@ While the Secret Variable for your API Key will look similar to: ![Screenshot of setting the API Key secret variable](secret-api-key.png) -The Zone ID and API key are used to purge your zone – it’s not strictly needed but otherwise, the CDN might deliver older versions of your assets for quite a while. +While not strictly required, providing your Zone ID and API key is recommended for purging your zone. Without them, the CDN may continue serving outdated versions of your assets for an extended period. ## Push your changes to GitLab @@ -83,6 +81,6 @@ git push -u origin master You can watch the progress and CI job output in your GitLab project under “Pipelines”. -After verifying your CI job ran without issues, first check that your GitLab page shows up under `https://youruser.gitlab.io/reponame/` (it might look broken depending on your browser settings as all links point to your KeyCDN zone – don’t worry about that) and then by heading to whatever Zone alias / Zone URL you defined. +After verifying your CI job ran without issues, first check that your GitLab page shows up under `https://youruser.gitlab.io/reponame/` (it might look broken depending on your browser settings as all links point to your KeyCDN zone---don't worry about that) and then by heading to whatever Zone alias / Zone URL you defined. To learn more about Hugo hosting options with KeyCDN, check out the complete [Hugo hosting with KeyCDN integration guide](https://www.keycdn.com/support/hugo-hosting/). diff --git a/content/en/hosting-and-deployment/hosting-on-keycdn/keycdn-pull-zone.png b/content/en/host-and-deploy/host-on-keycdn/keycdn-pull-zone.png similarity index 100% rename from content/en/hosting-and-deployment/hosting-on-keycdn/keycdn-pull-zone.png rename to content/en/host-and-deploy/host-on-keycdn/keycdn-pull-zone.png diff --git a/content/en/hosting-and-deployment/hosting-on-keycdn/secret-api-key.png b/content/en/host-and-deploy/host-on-keycdn/secret-api-key.png similarity index 100% rename from content/en/hosting-and-deployment/hosting-on-keycdn/secret-api-key.png rename to content/en/host-and-deploy/host-on-keycdn/secret-api-key.png diff --git a/content/en/hosting-and-deployment/hosting-on-keycdn/secret-zone-id.png b/content/en/host-and-deploy/host-on-keycdn/secret-zone-id.png similarity index 100% rename from content/en/hosting-and-deployment/hosting-on-keycdn/secret-zone-id.png rename to content/en/host-and-deploy/host-on-keycdn/secret-zone-id.png diff --git a/content/en/hosting-and-deployment/hosting-on-netlify/index.md b/content/en/host-and-deploy/host-on-netlify/index.md similarity index 51% rename from content/en/hosting-and-deployment/hosting-on-netlify/index.md rename to content/en/host-and-deploy/host-on-netlify/index.md index 97694f210..f3601331a 100644 --- a/content/en/hosting-and-deployment/hosting-on-netlify/index.md +++ b/content/en/host-and-deploy/host-on-netlify/index.md @@ -1,12 +1,9 @@ --- title: Host on Netlify -description: Host your site on Netlify with continuous deployment. -categories: [hosting and deployment] -keywords: [hosting] -menu: - docs: - parent: hosting-and-deployment -toc: true +description: Host your site on Netlify. +categories: [] +keywords: [] +aliases: [/hosting-and-deployment/hosting-on-netlify/] --- ## Prerequisites @@ -30,70 +27,83 @@ Please complete the following tasks before continuing: This procedure will enable continuous deployment from a GitHub repository. The procedure is essentially the same if you are using GitLab or Bitbucket. -Step 1 -: Log in to your Netlify account, navigate to the Sites page, press the **Add new site** button, and choose "Import an existing project" from the dropdown menu. +### Step 1 -Step 2 -: Select your deployment method. +Log in to your Netlify account, navigate to the Sites page, press the **Add new site** button, and choose "Import an existing project" from the dropdown menu. + +### Step 2 + +Select your deployment method. ![screen capture](netlify-step-02.png) -Step 3 -: Authorize Netlify to connect with your GitHub account by pressing the **Authorize Netlify** button. +### Step 3 - ![screen capture](netlify-step-03.png) +Authorize Netlify to connect with your GitHub account by pressing the **Authorize Netlify** button. -Step 4 -: Press the **Configure Netlify on GitHub** button. +![screen capture](netlify-step-03.png) - ![screen capture](netlify-step-04.png) +### Step 4 -Step 5 -: Install the Netlify app by selecting your GitHub account. +Press the **Configure Netlify on GitHub** button. - ![screen capture](netlify-step-05.png) +![screen capture](netlify-step-04.png) -Step 6 -: Press the **Install** button. +### Step 5 - ![screen capture](netlify-step-06.png) +Install the Netlify app by selecting your GitHub account. -Step 7 -: Click on the site's repository from the list. +![screen capture](netlify-step-05.png) - ![screen capture](netlify-step-07.png) +### Step 6 -Step 8 -: Set the site name and branch from which to deploy. +Press the **Install** button. - ![screen capture](netlify-step-08.png) +![screen capture](netlify-step-06.png) -Step 9 -: Define the build settings, press the **Add environment variables** button, then press the **New variable** button. +### Step 7 - ![screen capture](netlify-step-09.png) +Click on the site's repository from the list. -Step 10 -: Create a new environment variable named `HUGO_VERSION` and set the value to the [latest version]. +![screen capture](netlify-step-07.png) + +### Step 8 + +Set the site name and branch from which to deploy. + +![screen capture](netlify-step-08.png) + +### Step 9 + +Define the build settings, press the **Add environment variables** button, then press the **New variable** button. + +![screen capture](netlify-step-09.png) + +### Step 10 + +Create a new environment variable named `HUGO_VERSION` and set the value to the [latest version]. [latest version]: https://github.com/gohugoio/hugo/releases/latest - ![screen capture](netlify-step-10.png) +![screen capture](netlify-step-10.png) -Step 11 -: Press the "Deploy my new site" button at the bottom of the page. +### Step 11 - ![screen capture](netlify-step-11.png) +Press the "Deploy my new site" button at the bottom of the page. -Step 12 -: At the bottom of the screen, wait for the deploy to complete, then click on the deploy log entry. +![screen capture](netlify-step-11.png) - ![screen capture](netlify-step-12.png) +### Step 12 -Step 13 -: Press the **Open production deploy** button to view the live site. +At the bottom of the screen, wait for the deploy to complete, then click on the deploy log entry. - ![screen capture](netlify-step-13.png) +![screen capture](netlify-step-12.png) + +### Step 13 + +Press the **Open production deploy** button to view the live site. + +![screen capture](netlify-step-13.png) ## Configuration file @@ -101,23 +111,23 @@ In the procedure above we configured our site using the Netlify user interface. Create a new file named netlify.toml in the root of your project directory. In its simplest form, the configuration file might look like this: -{{< code file=netlify.toml >}} +```toml {file="netlify.toml"} [build.environment] -HUGO_VERSION = "0.141.0" +HUGO_VERSION = "0.144.2" NODE_VERSION = "22" TZ = "America/Los_Angeles" [build] publish = "public" command = "hugo --gc --minify" -{{< /code >}} +``` If your site requires Dart Sass to transpile Sass to CSS, the configuration file should look something like this: -{{< code file=netlify.toml >}} +```toml {file="netlify.toml"} [build.environment] -HUGO_VERSION = "0.141.0" -DART_SASS_VERSION = "1.83.4" +HUGO_VERSION = "0.144.2" +DART_SASS_VERSION = "1.85.0" NODE_VERSION = "22" TZ = "America/Los_Angeles" @@ -130,4 +140,4 @@ command = """\ export PATH=/opt/build/repo/dart-sass:$PATH && \ hugo --gc --minify \ """ -{{< /code >}} +``` diff --git a/content/en/hosting-and-deployment/hosting-on-netlify/netlify-step-02.png b/content/en/host-and-deploy/host-on-netlify/netlify-step-02.png similarity index 100% rename from content/en/hosting-and-deployment/hosting-on-netlify/netlify-step-02.png rename to content/en/host-and-deploy/host-on-netlify/netlify-step-02.png diff --git a/content/en/hosting-and-deployment/hosting-on-netlify/netlify-step-03.png b/content/en/host-and-deploy/host-on-netlify/netlify-step-03.png similarity index 100% rename from content/en/hosting-and-deployment/hosting-on-netlify/netlify-step-03.png rename to content/en/host-and-deploy/host-on-netlify/netlify-step-03.png diff --git a/content/en/hosting-and-deployment/hosting-on-netlify/netlify-step-04.png b/content/en/host-and-deploy/host-on-netlify/netlify-step-04.png similarity index 100% rename from content/en/hosting-and-deployment/hosting-on-netlify/netlify-step-04.png rename to content/en/host-and-deploy/host-on-netlify/netlify-step-04.png diff --git a/content/en/hosting-and-deployment/hosting-on-netlify/netlify-step-05.png b/content/en/host-and-deploy/host-on-netlify/netlify-step-05.png similarity index 100% rename from content/en/hosting-and-deployment/hosting-on-netlify/netlify-step-05.png rename to content/en/host-and-deploy/host-on-netlify/netlify-step-05.png diff --git a/content/en/hosting-and-deployment/hosting-on-netlify/netlify-step-06.png b/content/en/host-and-deploy/host-on-netlify/netlify-step-06.png similarity index 100% rename from content/en/hosting-and-deployment/hosting-on-netlify/netlify-step-06.png rename to content/en/host-and-deploy/host-on-netlify/netlify-step-06.png diff --git a/content/en/hosting-and-deployment/hosting-on-netlify/netlify-step-07.png b/content/en/host-and-deploy/host-on-netlify/netlify-step-07.png similarity index 100% rename from content/en/hosting-and-deployment/hosting-on-netlify/netlify-step-07.png rename to content/en/host-and-deploy/host-on-netlify/netlify-step-07.png diff --git a/content/en/hosting-and-deployment/hosting-on-netlify/netlify-step-08.png b/content/en/host-and-deploy/host-on-netlify/netlify-step-08.png similarity index 100% rename from content/en/hosting-and-deployment/hosting-on-netlify/netlify-step-08.png rename to content/en/host-and-deploy/host-on-netlify/netlify-step-08.png diff --git a/content/en/hosting-and-deployment/hosting-on-netlify/netlify-step-09.png b/content/en/host-and-deploy/host-on-netlify/netlify-step-09.png similarity index 100% rename from content/en/hosting-and-deployment/hosting-on-netlify/netlify-step-09.png rename to content/en/host-and-deploy/host-on-netlify/netlify-step-09.png diff --git a/content/en/hosting-and-deployment/hosting-on-netlify/netlify-step-10.png b/content/en/host-and-deploy/host-on-netlify/netlify-step-10.png similarity index 100% rename from content/en/hosting-and-deployment/hosting-on-netlify/netlify-step-10.png rename to content/en/host-and-deploy/host-on-netlify/netlify-step-10.png diff --git a/content/en/hosting-and-deployment/hosting-on-netlify/netlify-step-11.png b/content/en/host-and-deploy/host-on-netlify/netlify-step-11.png similarity index 100% rename from content/en/hosting-and-deployment/hosting-on-netlify/netlify-step-11.png rename to content/en/host-and-deploy/host-on-netlify/netlify-step-11.png diff --git a/content/en/hosting-and-deployment/hosting-on-netlify/netlify-step-12.png b/content/en/host-and-deploy/host-on-netlify/netlify-step-12.png similarity index 100% rename from content/en/hosting-and-deployment/hosting-on-netlify/netlify-step-12.png rename to content/en/host-and-deploy/host-on-netlify/netlify-step-12.png diff --git a/content/en/hosting-and-deployment/hosting-on-netlify/netlify-step-13.png b/content/en/host-and-deploy/host-on-netlify/netlify-step-13.png similarity index 100% rename from content/en/hosting-and-deployment/hosting-on-netlify/netlify-step-13.png rename to content/en/host-and-deploy/host-on-netlify/netlify-step-13.png diff --git a/content/en/hosting-and-deployment/hosting-on-render.md b/content/en/host-and-deploy/host-on-render.md similarity index 85% rename from content/en/hosting-and-deployment/hosting-on-render.md rename to content/en/host-and-deploy/host-on-render.md index b43261c8d..ac486fcbf 100644 --- a/content/en/hosting-and-deployment/hosting-on-render.md +++ b/content/en/host-and-deploy/host-on-render.md @@ -1,12 +1,9 @@ --- title: Host on Render -description: Host your Hugo site for free with Render's global CDN, fully-managed SSL and auto deploys from GitHub. -categories: [hosting and deployment] -keywords: [hosting] -menu: - docs: - parent: hosting-and-deployment -toc: true +description: Host your on Render. +categories: [] +keywords: [] +aliases: [/hosting-and-deployment/hosting-on-render/] --- ## Introduction @@ -37,12 +34,12 @@ Static sites are **completely free** on Render and include the following: You can set up a Hugo site on Render in two quick steps: 1. Create a new **Static Site** on Render, and give Render permission to access your GitHub/GitLab repo. -2. Use the following values during creation: +1. Use the following values during creation: - Field | Value - ------------------- | ------------------- - **Build Command** | `hugo --gc --minify` (or your own build command) - **Publish Directory** | `public` (or your own output directory) +Field | Value +------------------- | ------------------- +**Build Command** | `hugo --gc --minify` (or your own build command) +**Publish Directory** | `public` (or your own output directory) That's it! Your site will be live on your Render URL (which looks like `yoursite.onrender.com`) as soon as the build is done. diff --git a/content/en/host-and-deploy/host-on-sourcehut-pages.md b/content/en/host-and-deploy/host-on-sourcehut-pages.md new file mode 100644 index 000000000..6b092fbf2 --- /dev/null +++ b/content/en/host-and-deploy/host-on-sourcehut-pages.md @@ -0,0 +1,94 @@ +--- +title: Host on SourceHut Pages +description: Host your site on SourceHut Pages. +categories: [] +keywords: [] +aliases: [/hosting-and-deployment/hosting-on-sourcehut/] +--- + +## Assumptions + +- Working familiarity with [Git] or [Mercurial] for version control +- Completion of the Hugo [Quick Start] +- A [SourceHut account] +- A Hugo website on your local machine that you are ready to publish + +[Git]: https://git-scm.com/ +[Mercurial]: https://www.mercurial-scm.org/ +[SourceHut account]: https://meta.sr.ht/login +[Quick Start]: /getting-started/quick-start/ + +Any and all mentions of `` refer to your actual SourceHut username and must be substituted accordingly. + +## 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. + +[`baseURL`]: /configuration/all/#baseurl +[custom domain section]: https://srht.site/custom-domains + +## Manual deployment + +This method does not require a paid account. To proceed you will need to create a [SourceHut personal access token] and install and configure the [hut]CLI tool: + +[SourceHut personal access token]: https://meta.sr.ht/oauth2/personal-token/ +[hut]: https://sr.ht/~xenrox/hut/ + +```sh +hugo +tar -C public -cvz . > site.tar.gz +hut init +hut pages publish -d .srht.site site.tar.gz +``` + +A TLS certificate will be automatically obtained for you, and your new website will be available at `https://.srht.site/` (or the provided custom domain). + +## Automated deployment + +This method requires a paid account and relies on the SourceHut build system. + +First, define your [build manifest] by creating a `.build.yml` file in the root of your project. The following is a bare-bones template: + +[build manifest]: https://man.sr.ht/builds.sr.ht/#build-manifests + +```yaml {file=".build.yml" copy=true} +image: alpine/edge +packages: + - hugo + - hut +oauth: pages.sr.ht/PAGES:RW +environment: + site: .srht.site +tasks: +- package: | + cd $site + hugo + tar -C public -cvz . > ../site.tar.gz +- upload: | + hut pages publish -d $site site.tar.gz +``` + +Now what's left is creating a repository titled `.srht.site` (or your custom domain, if applicable) and pushing your local project. Here's an example using Git: + +```sh +# initialize new git repository +git init + +# add /public directory to our .gitignore file +echo "/public" >> .gitignore + +# commit and push code to main branch +git add . +git commit -m "Initial commit" +git remote add origin https://git.sr.ht/~/.srht.site +git push -u origin main +``` + +You can now follow the build progress of your page at `https://builds.sr.ht/`. + +After the build has passed, a TLS certificate will be automatically obtained for you and your new website will be available at `https://.srht.site/` (or the provided custom domain). + +## Other resources + +- [SourceHut Pages](https://srht.site/) +- [SourceHut Builds user manual](https://man.sr.ht/builds.sr.ht/) diff --git a/content/en/hosting-and-deployment/_index.md b/content/en/hosting-and-deployment/_index.md deleted file mode 100644 index a99ffd69c..000000000 --- a/content/en/hosting-and-deployment/_index.md +++ /dev/null @@ -1,15 +0,0 @@ ---- -title: Hosting and deployment - -description: Services and tools to host and deploy your site. -categories: [] -keywords: [] -menu: - docs: - identifier: hosting-and-deployment-in-this-section - parent: hosting-and-deployment - weight: 1 -weight: 10 ---- - -Because Hugo renders *static* websites, you can host your new Hugo website virtually anywhere. The following represent only a few of the more popular hosting and automated deployment solutions used by the Hugo community. diff --git a/content/en/hosting-and-deployment/hugo-deploy.md b/content/en/hosting-and-deployment/hugo-deploy.md deleted file mode 100644 index f33dab50e..000000000 --- a/content/en/hosting-and-deployment/hugo-deploy.md +++ /dev/null @@ -1,261 +0,0 @@ ---- -title: Hugo Deploy -description: Deploy your site directly to a Google Cloud Storage bucket, an AWS S3 bucket, or an Azure Storage container. -categories: [hosting and deployment] -keywords: [deployment,s3,gcs,azure] -menu: - docs: - parent: hosting-and-deployment - weight: 20 -weight: 20 -toc: true ---- - -Use the `hugo deploy` command to deploy your site directly to a Google Cloud Storage bucket, an AWS S3 bucket, or an Azure Storage container - -{{% note %}} -This feature requires the Hugo extended/deploy edition. See the [installation] section for details. - -[installation]: /installation/ -{{% /note %}} - -## Assumptions - -* You have completed the [Quick Start] or have a Hugo website you are ready to deploy and share with the world. -* You have an account with the service provider ([Google Cloud](https://cloud.google.com/), [AWS](https://aws.amazon.com), or [Azure](https://azure.microsoft.com)) that you want to deploy to. -* You have authenticated. - * Google Cloud: [Install the CLI](https://cloud.google.com/sdk) and run [`gcloud auth login`](https://cloud.google.com/sdk/gcloud/reference/auth/login). - * AWS: [Install the CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-install.html) and run [`aws configure`](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-configure.html). - * Azure: [Install the CLI](https://docs.microsoft.com/en-us/cli/azure/install-azure-cli) and run [`az login`](https://docs.microsoft.com/en-us/cli/azure/authenticate-azure-cli). - * NOTE: Each service supports alternatives for authentication, including using environment variables. See [here](https://gocloud.dev/howto/blob/#services) for more details. -* You have created a bucket to deploy to. If you want your site to be - public, be sure to configure the bucket to be publicly readable as a static website. - * Google Cloud: [create a bucket](https://cloud.google.com/storage/docs/creating-buckets) and [host a static website](https://cloud.google.com/storage/docs/hosting-static-website) - * Amazon S3: [create a bucket](https://docs.aws.amazon.com/AmazonS3/latest/gsg/CreatingABucket.html) and [host a static website](https://docs.aws.amazon.com/AmazonS3/latest/userguide/WebsiteHosting.html) - * Microsoft Azure: [create a storage container](https://docs.microsoft.com/en-us/azure/storage/blobs/storage-quickstart-blobs-portal) and [host a static website](https://learn.microsoft.com/en-us/azure/storage/blobs/storage-blob-static-website) - -## Configuring your first deployment - -In the configuration file for your site, add a `[deployment]` section -and a `[[deployment.targets]]` subsection. The only required parameters are -the name and URL: - -```toml -[deployment] - -[[deployment.targets]] -# An arbitrary name for this target. -name = "production" - -# URL specifies the Go Cloud Development Kit URL to deploy to. Examples: -URL = "" - -# Google Cloud Storage -- see https://gocloud.dev/howto/blob/#gcs -#URL = "gs://" - -# Amazon Web Services S3; see https://gocloud.dev/howto/blob/#s3 -#URL = "s3://?region=" - -# For S3-compatible endpoints, see https://gocloud.dev/howto/blob/#s3-compatible -#URL = "s3://?endpoint=https://my.minio.instance&awssdk=v2&use_path_style=true&disable_https=false - -# Microsoft Azure Blob Storage; see https://gocloud.dev/howto/blob/#azure -#URL = "azblob://$web" - -``` - -## Deploy - -To deploy to a target: - -```bash -hugo deploy [--target=] -``` - -The deploy process recursively walks through your local publish directory -(`public` by default) and syncs it to the destination bucket, to ensure -that the local and remote contents match. - -If you don't specify a target, Hugo will deploy to the first target in your -configuration. - -See `hugo help deploy` or [the deploy command-line documentation][commandline] for more command-line options. - -### How the file list works - -The first thing `hugo deploy` does is create file lists for local and remote by -traversing the local publish directory and remote bucket. - -For both local and remote, the file list includes and excludes files according to -the [deployment target's configuration][config] -- -* If the configuration specifies an `include` pattern, all files - are skipped by default except those matching the pattern. -* If the configuration specifies an `exclude` pattern, files matching the - pattern are skipped. - -{{% note %}} -When creating the local file list, a few additional skips apply: first, Hugo always -skips files named `.DS_Store`. - -Second, Hugo always skips local hidden directories -(directories with names starting with a period, e.g. `.git`) and does not -traverse into them, except for the special [hidden directory named -`.well-known`](https://en.wikipedia.org/wiki/Well-known_URI), which is -traversed if it exists. -{{% /note %}} - -### How the local and remote file lists are compared - -In the second step, Hugo compares the two file lists to figure out what changes -actually need to be made on the remote. File names are compared first; if the -local and remote files both exist then the sizes and md5sums are compared. Any -difference means that the file will be (re-)uploaded. - -Specifying the `--force` flag will ensure all files are re-uploaded even -if Hugo cannot detect any differences between local and remote. - -Files are deleted from the remote bucket if they are not present in the local -file list. - -{{% note %}} -If a remote file is excluded from the file list generation using the -exclude/include configs, then the comparison step will not know to delete the -file -- so it will remain on the remote even if it isn't present locally. -{{% /note %}} - -If the [`--confirm` or `--dryRun` flags][commandline] are given, Hugo displays -what differences it has found and either pauses or stops here. - -### How synchronization works - -Hugo applies the list of changes to the remote storage bucket. Missing and/or -changed files are uploaded, and files missing locally but present remotely are -deleted. As files are uploaded, their headers are also configured on the remote -according to the matchers configuration. - -{{% note %}} -As a safety measure to help prevent accidents, if there are more than 256 files -to delete, Hugo won't delete any files from the remote. Use the `--maxDeletes` -command line flag to override this. -{{% /note %}} - -## Advanced configuration - -Here's a full example deployment configuration: - -```toml -[deployment] - -# By default, files are uploaded in an arbitrary order. -# If you specify an `order` list, files that match regular expressions -# in this list will be uploaded first, in the specified order. -order = [".jpg$", ".gif$"] - -[[deployment.targets]] -# Define one or more targets, e.g., staging and production. -# Each target gets its own [[deployment.targets]] section. - -# An arbitrary name for this target. -name = "mydeployment" -# The Go Cloud Development Kit URL to deploy to. Examples: -URL = "" - -# GCS; see https://gocloud.dev/howto/blob/#gcs -#URL = "gs://" - -# S3; see https://gocloud.dev/howto/blob/#s3 -# For S3-compatible endpoints, see https://gocloud.dev/howto/blob/#s3-compatible -#URL = "s3://?region=" - -# Azure Blob Storage; see https://gocloud.dev/howto/blob/#azure -#URL = "azblob://$web" - -# You can use a "prefix=" query parameter to target a subdirectory of the bucket: -#URL = "gs://?prefix=a/subdirectory/" - -# If you are using a CloudFront CDN, deploy will invalidate the cache as needed. -#cloudFrontDistributionID = "" - -# Include or exclude specific files when deploying to this target: -# If exclude is non-empty, and a local or remote file's path matches it, that file is not synced. -# If include is non-empty, and a local or remote file's path does not match it, that file is not synced. -# Note: local files that don't pass the include/exclude filters are not uploaded to remote, -# and remote files that don't pass the include/exclude filters are not deleted. -# -# The pattern syntax is documented here: https://godoc.org/github.com/gobwas/glob#Glob -# Patterns should be written with forward slashes as separator. -# -#include = "**.html" # would only include files with ".html" suffix -#exclude = "**.{jpg, png}" # would exclude files with ".jpg" or ".png" suffix - -# Map any file named "/index.html" to the remote file "/". This does -# not affect the root "index.html" file, and it does not affect matchers below. -# This works when deploying to key-value cloud storage systems, such as Amazon -# S3 (general purpose buckets, not directory buckets), Google Cloud Storage, and -# Azure Blob Storage. This makes it so the canonical URL will match the object -# key in cloud storage, except for the root index.html file. -# -#stripIndexHTML = true - - -####################### -[[deployment.matchers]] -# Matchers enable special caching, content type and compression behavior for -# specified file types. You can include any number of matcher blocks; the first one -# matching a given file pattern will be used. - -# See https://golang.org/pkg/regexp/syntax/ for pattern syntax. -# Pattern searching is stopped on first match. -# This is not affected by stripIndexHTML, above. -pattern = "" - -# If true, Hugo will gzip the file before uploading it to the bucket. -# With many storage services, this will save on storage and bandwidth costs -# for uncompressed file types. -#gzip = false - -# If true, Hugo always re-uploads this file even if size and md5 match. -# This is useful if Hugo isn't reliably able to determine whether to re-upload -# the file on its own. -#force = false - -# Content-type header to configure for this file when served. -# By default this can be determined from the file extension. -#contentType = "" - -# Cache-control header to configure for this file when served. -# The default is the empty string. -#cacheControl = "" - -# Content-encoding header to configure for this file when served. -# By default, if gzip is True, this will be filled with "gzip". -#contentEncoding = "" - - -# Samples: - -[[deployment.matchers]] -# Cache static assets for 1 year. -pattern = "^.+\\.(js|css|svg|ttf)$" -cacheControl = "max-age=31536000, no-transform, public" -gzip = true - -[[deployment.matchers]] -pattern = "^.+\\.(png|jpg)$" -cacheControl = "max-age=31536000, no-transform, public" -gzip = false - -[[deployment.matchers]] -# Set custom content type for /sitemap.xml -pattern = "^sitemap\\.xml$" -contentType = "application/xml" -gzip = true - -[[deployment.matchers]] -pattern = "^.+\\.(html|xml|json)$" -gzip = true -``` - -[Quick Start]: /getting-started/quick-start/ -[commandline]: /commands/hugo_deploy/ -[config]: #advanced-configuration diff --git a/content/en/hugo-modules/_index.md b/content/en/hugo-modules/_index.md index b6f38924f..7a538ea15 100644 --- a/content/en/hugo-modules/_index.md +++ b/content/en/hugo-modules/_index.md @@ -1,29 +1,8 @@ --- title: Hugo Modules - description: Use Hugo Modules to manage the content, presentation, and behavior of your site. categories: [] keywords: [] -menu: - docs: - identifier: hugo-modules-in-this-section - parent: modules - weight: 10 weight: 10 -toc: true aliases: [/themes/overview/,/themes/] --- - -**Hugo Modules** are the core building blocks in Hugo. A _module_ can be your main project or a smaller module providing one or more of the 7 component types defined in Hugo: **static**, **content**, **layouts**, **data**, **assets**, **i18n**, and **archetypes**. - -You can combine modules in any combination you like, and even mount directories from non-Hugo projects, forming a big, virtual union file system. - -Hugo Modules are powered by Go Modules. For more information about Go Modules, see: - -- [https://go.dev/wiki/Modules](https://go.dev/wiki/Modules) -- [https://go.dev/blog/using-go-modules](https://go.dev/blog/using-go-modules) - -Some example projects: - -- [https://github.com/bep/docuapi](https://github.com/bep/docuapi) is a theme that has been ported to Hugo Modules while testing this feature. It is a good example of a non-Hugo-project mounted into Hugo's directory structure. It even shows a JS Bundler implementation in regular Go templates. -- [https://github.com/bep/my-modular-site](https://github.com/bep/my-modular-site) is a very simple site used for testing. diff --git a/content/en/hugo-modules/configuration.md b/content/en/hugo-modules/configuration.md deleted file mode 100644 index 0bc1b47d8..000000000 --- a/content/en/hugo-modules/configuration.md +++ /dev/null @@ -1,187 +0,0 @@ ---- -title: Configure Hugo modules -description: This page describes the configuration options for a module. -categories: [hugo modules] -keywords: [modules,themes] -menu: - docs: - parent: modules - weight: 20 -weight: 20 -toc: true ---- - -## Module configuration: top level - -{{< code-toggle file=hugo >}} -[module] -noProxy = 'none' -noVendor = '' -private = '*.*' -proxy = 'direct' -replacements = '' -vendorClosest = false -workspace = 'off' -{{< /code-toggle >}} - -noProxy -: (`string`) Comma separated glob list matching paths that should not use the proxy configured above. - -noVendor -: (`string`) A optional Glob pattern matching module paths to skip when vendoring, e.g. "github.com/**" - -private -: (`string`) Comma separated glob list matching paths that should be treated as private. - -proxy -: (`string`) Defines the proxy server to use to download remote modules. Default is `direct`, which means "git clone" and similar. - -vendorClosest -: (`bool`) When enabled, we will pick the vendored module closest to the module using it. The default behavior is to pick the first. Note that there can still be only one dependency of a given module path, so once it is in use it cannot be redefined. Default is `false`. - -workspace -: (`string`) The workspace file to use. This enables Go workspace mode. Note that this can also be set via OS env, e.g. `export HUGO_MODULE_WORKSPACE=/my/hugo.work` This only works with Go 1.18+. In Hugo `v0.109.0` we changed the default to `off` and we now resolve any relative work file names relative to the working directory. - -replacements -: (`string`) A comma-separated list of mappings from module paths to directories, e.g. `github.com/bep/my-theme -> ../..,github.com/bep/shortcodes -> /some/path`. This is mostly useful for temporary local development of a module, in which case you might want to save it as an environment variable, e.g: `env HUGO_MODULE_REPLACEMENTS="github.com/bep/my-theme -> ../.."`. Relative paths are relative to [themesDir](/getting-started/configuration/#all-configuration-settings). Absolute paths are allowed. - -Note that the above terms maps directly to their counterparts in Go Modules. Some of these setting may be natural to set as OS environment variables. To set the proxy server to use, as an example: - -```txt -env HUGO_MODULE_PROXY=https://proxy.example.org hugo -``` - -{{< gomodules-info >}} - -## Module configuration: hugoVersion - -If your module requires a particular version of Hugo to work, you can indicate that in the `module` section and the user will be warned if using a too old/new version. - -{{< code-toggle file=hugo >}} -[module] -[module.hugoVersion] - min = "" - max = "" - extended = false - -{{< /code-toggle >}} - -Any of the above can be omitted. - -min -: (`string`) The minimum Hugo version supported, e.g. `0.55.0` - -max -: (`string`) The maximum Hugo version supported, e.g. `0.55.0` - -extended -: (`bool`) Whether the extended edition of Hugo is required, satisfied by installing either the extended or extended/deploy edition. - -## Module configuration: imports - -{{< code-toggle file=hugo >}} -[module] -[[module.imports]] - path = "github.com/gohugoio/hugoTestModules1_linux/modh1_2_1v" - ignoreConfig = false - ignoreImports = false - disable = false -[[module.imports]] - path = "my-shortcodes" -{{< /code-toggle >}} - -path -: Can be either a valid Go Module module path, e.g. `github.com/gohugoio/myShortcodes`, or the directory name for the module as stored in your `themes` directory. - -ignoreConfig -: If enabled, any module configuration file, e.g. `hugo.toml`, will not be loaded. Note that this will also stop the loading of any transitive module dependencies. - -ignoreImports -: If enabled, module imports will not be followed. - -disable -: Set to `true` to disable the module while keeping any version info in the `go.*` files. - -noMounts -: Do not mount any directory in this import. - -noVendor -: Never vendor this import (only allowed in main project). - -{{< gomodules-info >}} - -## Module configuration: mounts - -{{% note %}} -When the `mounts` configuration was introduced in Hugo 0.56.0, we were careful to preserve the existing `contentDir`, `staticDir`, and similar configuration to make sure all existing sites just continued to work. But you should not have both: if you add a `mounts` section you should remove the old `contentDir`, `staticDir`, etc. settings. -{{% /note %}} - -{{% note %}} -When you add a mount, the default mount for the concerned target root is ignored: be sure to explicitly add it. -{{% /note %}} - -### Default mounts - -{{< code-toggle file=hugo >}} -[module] -[[module.mounts]] - source="content" - target="content" -[[module.mounts]] - source="static" - target="static" -[[module.mounts]] - source="layouts" - target="layouts" -[[module.mounts]] - source="data" - target="data" -[[module.mounts]] - source="assets" - target="assets" -[[module.mounts]] - source="i18n" - target="i18n" -[[module.mounts]] - source="archetypes" - target="archetypes" -{{< /code-toggle >}} - -source -: (`string`) The source directory of the mount. For the main project, this can be either project-relative or absolute. For other modules it must be project-relative. - -target -: (`string`) Where it should be mounted into Hugo's virtual filesystem. It must start with one of Hugo's component directories: `static`, `content`, `layouts`, `data`, `assets`, `i18n`, or `archetypes`. E.g. `content/blog`. - -disableWatch -{{< new-in 0.128.0 />}} -: (`bool`) Whether to disable watching in watch mode for this mount. Default is `false`. - -lang -: (`string`) The language code, e.g. "en". Only relevant for `content` mounts, and `static` mounts when in multihost mode. - -includeFiles -: (`string` or `[]string`) One or more [glob](https://github.com/gobwas/glob) patterns matching files or directories to include. If `excludeFiles` is not set, the files matching `includeFiles` will be the files mounted. - -The glob patterns are matched to the file names starting from the `source` root, they should have Unix styled slashes even on Windows, `/` matches the mount root and `**` can be used as a super-asterisk to match recursively down all directories, e.g `/posts/**.jpg`. - -The search is case-insensitive. - -excludeFiles -: (`string` or `[]string`) One or more glob patterns matching files to exclude. - -### Example - -{{< code-toggle file=hugo >}} -[module] -[[module.mounts]] - source="content" - target="content" - excludeFiles="docs/*" -[[module.mounts]] - source="node_modules" - target="assets" -[[module.mounts]] - source="assets" - target="assets" -{{< /code-toggle >}} diff --git a/content/en/hugo-modules/introduction.md b/content/en/hugo-modules/introduction.md new file mode 100644 index 000000000..b45607dc0 --- /dev/null +++ b/content/en/hugo-modules/introduction.md @@ -0,0 +1,19 @@ +--- +title: Introduction +description: A brief introduction to Hugo Modules. +categories: [] +keywords: [] +weight: 10 +--- + +Hugo uses modules as its fundamental organizational units. A module can be a full Hugo project or a smaller, reusable piece providing one or more of Hugo's seven component types: static files, content, layouts, data, assets, internationalization (i18n) resources, and archetypes. + +Modules are combinable in any arrangement, and external directories (including those from non-Hugo projects) can be mounted, effectively creating a single, unified file system. + +Some example projects: + +[https://github.com/bep/docuapi](https://github.com/bep/docuapi) +: A theme that has been ported to Hugo Modules while testing this feature. It is a good example of a non-Hugo-project mounted into Hugo's directory structure. It even shows a JS Bundler implementation in regular Go templates. + +[https://github.com/bep/my-modular-site](https://github.com/bep/my-modular-site) +: A simple site used for testing. diff --git a/content/en/hugo-modules/theme-components.md b/content/en/hugo-modules/theme-components.md index 9e52620ce..03891ed7a 100644 --- a/content/en/hugo-modules/theme-components.md +++ b/content/en/hugo-modules/theme-components.md @@ -1,27 +1,19 @@ --- title: Theme components -description: Hugo provides advanced theming support with Theme Components. -categories: [hugo modules] -keywords: [modules,themes] -menu: - docs: - parent: modules - weight: 40 -weight: 40 +description: Hugo provides advanced theming support with theme components. +categories: [] +keywords: [] +weight: 30 aliases: [/themes/customize/,/themes/customizing/] -toc: true --- -{{% note %}} -This section contain information that may be outdated and is in the process of being rewritten. -{{% /note %}} -Since Hugo `0.42` a project can configure a theme as a composite of as many theme components you need: +A project can configure a theme as a composite of as many theme components as you need: {{< code-toggle file=hugo >}} theme = ["my-shortcodes", "base-theme", "hyde"] {{< /code-toggle >}} -You can even nest this, and have the theme component itself include theme components in its own `hugo.toml` (theme inheritance).[^1] +You can even nest this, and have the theme component itself include theme components in its own `hugo.toml` (theme inheritance). The theme definition example above in `hugo.toml` creates a theme with 3 theme components with precedence from left to right. @@ -29,17 +21,15 @@ For any given file, data entry, etc., Hugo will look first in the project and th Hugo uses two different algorithms to merge the file systems, depending on the file type: -* For `i18n` and `data` files, Hugo merges deeply using the translation ID and data key inside the files. -* For `static`, `layouts` (templates), and `archetypes` files, these are merged on file level. So the left-most file will be chosen. +- For `i18n` and `data` files, Hugo merges deeply using the translation ID and data key inside the files. +- For `static`, `layouts` (templates), and `archetypes` files, these are merged on file level. So the left-most file will be chosen. -The name used in the `theme` definition above must match a directory in `/your-site/themes`, e.g. `/your-site/themes/my-shortcodes`. There are plans to improve on this and get a URL scheme so this can be resolved automatically. +The name used in the `theme` definition above must match a directory in `/your-site/themes`, e.g. `/your-site/themes/my-shortcodes`. Also note that a component that is part of a theme can have its own configuration file, e.g. `hugo.toml`. There are currently some restrictions to what a theme component can configure: -* `params` (global and per language) -* `menu` (global and per language) -* `outputformats` and `mediatypes` +- `params` (global and per language) +- `menu` (global and per language) +- `outputformats` and `mediatypes` The same rules apply here: The left-most parameter/menu etc. with the same ID will win. There are some hidden and experimental namespace support in the above, which we will work to improve in the future, but theme authors are encouraged to create their own namespaces to avoid naming conflicts. - -[^1]: For themes hosted on the [Hugo Themes Showcase](https://themes.gohugo.io/) components need to be added as git submodules that point to the directory `exampleSite/themes` diff --git a/content/en/hugo-modules/use-modules.md b/content/en/hugo-modules/use-modules.md index f29d4b198..86d2ad1cc 100644 --- a/content/en/hugo-modules/use-modules.md +++ b/content/en/hugo-modules/use-modules.md @@ -1,20 +1,15 @@ --- title: Use Hugo Modules -description: How to use Hugo Modules to build and manage your site. -categories: [hugo modules] -keywords: [modules,themes] -menu: - docs: - parent: modules - weight: 30 -weight: 30 +description: How to use Hugo Modules. +categories: [] +keywords: [] +weight: 20 aliases: [/themes/usage/,/themes/installing/,/installing-and-using-themes/] -toc: true --- ## Prerequisite -{{< gomodules-info >}} +{{% include "/_common/gomodules-info.md" %}} ## Initialize a new module @@ -33,15 +28,15 @@ The easiest way to use a Module for a theme is to import it in the configuration 1. Initialize the hugo module system: `hugo mod init github.com//` 1. Import the theme: -{{< code-toggle file=hugo >}} -[module] - [[module.imports]] - path = "github.com/spf13/hyde" -{{< /code-toggle >}} + {{< code-toggle file=hugo >}} + [module] + [[module.imports]] + path = "github.com/spf13/hyde" + {{< /code-toggle >}} ## Update modules -Modules will be downloaded and added when you add them as imports to your configuration, see [Module Imports](/hugo-modules/configuration/#module-configuration-imports). +Modules will be downloaded and added when you add them as imports to your configuration. See [configure modules](/configuration/module/#imports). To update or manage versions, you can use `hugo mod get`. @@ -83,7 +78,7 @@ replace github.com/bep/hugotestmods/mypartials => /Users/bep/hugotestmods/mypart If you have the `hugo server` running, the configuration will be reloaded and `/Users/bep/hugotestmods/mypartials` put on the watch list. -Instead of modifying the `go.mod` files, you can also use the modules configuration [`replacements`](/hugo-modules/configuration/#module-configuration-top-level) option. +Instead of modifying the `go.mod` files, you can also use the modules configuration [`replacements`](/configuration/module/#top-level-options) option. ## Print dependency graph @@ -111,9 +106,9 @@ Also see the [CLI Doc](/commands/hugo_mod_graph/). Note that: -* 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 [Glob](https://github.com/gobwas/glob) pattern given. +- 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](g) pattern. Also see the [CLI Doc](/commands/hugo_mod_vendor/). @@ -127,7 +122,7 @@ Also see the [CLI Doc](/commands/hugo_mod_clean/). Run `hugo mod clean` to delete the entire modules cache. -Note that you can also configure the `modules` cache with a `maxAge`, see [File Caches](/getting-started/configuration/#configure-file-caches). +Note that you can also configure the `modules` cache with a `maxAge`. See [configure caches](/configuration/caches/). Also see the [CLI Doc](/commands/hugo_mod_clean/). @@ -137,7 +132,7 @@ Workspace support was added in [Go 1.18](https://go.dev/blog/get-familiar-with-w A common use case for a workspace is to simplify local development of a site with its theme modules. -A workspace can be configured in a `*.work` file and activated with the [module.workspace](/hugo-modules/configuration/) setting, which for this use is commonly controlled via the `HUGO_MODULE_WORKSPACE` OS environment variable. +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. See the [hugo.work](https://github.com/gohugoio/hugo/blob/master/docs/hugo.work) file in the Hugo Docs repo for an example: diff --git a/content/en/hugo-pipes/_index.md b/content/en/hugo-pipes/_index.md index 5e2d1d416..51028152b 100755 --- a/content/en/hugo-pipes/_index.md +++ b/content/en/hugo-pipes/_index.md @@ -3,10 +3,5 @@ title: Hugo Pipes description: Use asset pipelines to transform and optimize images, stylesheets, and JavaScript. categories: [] keywords: [] -menu: - docs: - identifier: hugo-pipes-in-this-section - parent: hugo-pipes - weight: 10 weight: 10 --- diff --git a/content/en/hugo-pipes/bundling.md b/content/en/hugo-pipes/bundling.md index 1e0908737..335cc5cae 100755 --- a/content/en/hugo-pipes/bundling.md +++ b/content/en/hugo-pipes/bundling.md @@ -2,13 +2,8 @@ title: Concat linkTitle: Concatenating assets description: Bundle any number of assets into one resource. -categories: [asset management] +categories: [] keywords: [] -menu: - docs: - parent: hugo-pipes - weight: 90 -weight: 90 --- See the [`resources.Concat`](/functions/resources/concat/) function. diff --git a/content/en/hugo-pipes/fingerprint.md b/content/en/hugo-pipes/fingerprint.md index 78fb18081..d38dfc106 100755 --- a/content/en/hugo-pipes/fingerprint.md +++ b/content/en/hugo-pipes/fingerprint.md @@ -2,13 +2,8 @@ title: Fingerprint linkTitle: Fingerprinting and SRI hashing description: Cryptographically hash the content of the given resource. -categories: [asset management] +categories: [] keywords: [] -menu: - docs: - parent: hugo-pipes - weight: 100 -weight: 100 --- See the [`resources.Fingerprint`](/functions/resources/fingerprint/) function. diff --git a/content/en/hugo-pipes/introduction.md b/content/en/hugo-pipes/introduction.md index 645171153..d1b93094f 100755 --- a/content/en/hugo-pipes/introduction.md +++ b/content/en/hugo-pipes/introduction.md @@ -2,14 +2,9 @@ title: Hugo Pipes linkTitle: Introduction description: Hugo Pipes is Hugo's asset processing set of functions. -categories: [asset management] +categories: [] keywords: [] -menu: - docs: - parent: hugo-pipes - weight: 20 -weight: 20 -toc: true +weight: 10 aliases: [/assets/] --- @@ -25,7 +20,7 @@ remote resource For `.Page` scoped resources, see the [page resources] section. -[mounted]: /hugo-modules/configuration/#module-configuration-mounts +[mounted]: /configuration/module/#mounts [page resources]: /content-management/page-resources/ ## Get a resource diff --git a/content/en/hugo-pipes/js.md b/content/en/hugo-pipes/js.md index 88b0f005f..18572d538 100644 --- a/content/en/hugo-pipes/js.md +++ b/content/en/hugo-pipes/js.md @@ -2,13 +2,8 @@ title: JavaScript linkTitle: JavaScript building description: Bundle, transpile, tree shake, code split, and minify JavaScript resources. -categories: [asset management] +categories: [] keywords: [] -menu: - docs: - parent: hugo-pipes - weight: 60 -weight: 60 --- See [JS functions](/functions/js/). diff --git a/content/en/hugo-pipes/minification.md b/content/en/hugo-pipes/minification.md index 3943d87d0..4ba1ea641 100755 --- a/content/en/hugo-pipes/minification.md +++ b/content/en/hugo-pipes/minification.md @@ -2,13 +2,8 @@ title: Minify linkTitle: Asset minification description: Minify a given resource. -categories: [asset management] +categories: [] keywords: [] -menu: - docs: - parent: hugo-pipes - weight: 80 -weight: 80 --- See the [`resources.Minify`](/functions/resources/minify/) function. diff --git a/content/en/hugo-pipes/postcss.md b/content/en/hugo-pipes/postcss.md index 72a091c8f..1b47e8aef 100755 --- a/content/en/hugo-pipes/postcss.md +++ b/content/en/hugo-pipes/postcss.md @@ -1,13 +1,8 @@ --- title: PostCSS description: Process the given resource with PostCSS using any PostCSS plugin. -categories: [asset management] +categories: [] keywords: [] -menu: - docs: - parent: hugo-pipes - weight: 40 -weight: 40 --- See the [`css.PostCSS`](/functions/css/postcss/) function. diff --git a/content/en/hugo-pipes/postprocess.md b/content/en/hugo-pipes/postprocess.md index e916dfc4d..72540fd5d 100755 --- a/content/en/hugo-pipes/postprocess.md +++ b/content/en/hugo-pipes/postprocess.md @@ -1,13 +1,8 @@ --- title: PostProcess description: Process the given resource after the build. -categories: [asset management] +categories: [] keywords: [] -menu: - docs: - parent: hugo-pipes - weight: 50 -weight: 50 --- See the [`resources.PostProcess`](/functions/resources/postprocess/) function. diff --git a/content/en/hugo-pipes/resource-from-string.md b/content/en/hugo-pipes/resource-from-string.md index 9c943591c..ed5eaff80 100755 --- a/content/en/hugo-pipes/resource-from-string.md +++ b/content/en/hugo-pipes/resource-from-string.md @@ -2,13 +2,8 @@ title: FromString linkTitle: Resource from string description: Create a resource from a string. -categories: [asset management] +categories: [] keywords: [] -menu: - docs: - parent: hugo-pipes - weight: 110 -weight: 110 --- See the [`resources.FromString`](/functions/resources/fromstring/) function. diff --git a/content/en/hugo-pipes/resource-from-template.md b/content/en/hugo-pipes/resource-from-template.md index 76303822d..bc50f630b 100755 --- a/content/en/hugo-pipes/resource-from-template.md +++ b/content/en/hugo-pipes/resource-from-template.md @@ -2,13 +2,8 @@ title: ExecuteAsTemplate linkTitle: Resource from template description: Create a resource from a Go template, parsed and executed with the given context. -categories: [asset management] +categories: [] keywords: [] -menu: - docs: - parent: hugo-pipes - weight: 120 -weight: 120 --- See the [`resources.ExecuteAsTemplate`](/functions/resources/executeastemplate/) function. diff --git a/content/en/hugo-pipes/transpile-sass-to-css.md b/content/en/hugo-pipes/transpile-sass-to-css.md index 918687b17..756914297 100644 --- a/content/en/hugo-pipes/transpile-sass-to-css.md +++ b/content/en/hugo-pipes/transpile-sass-to-css.md @@ -2,13 +2,8 @@ title: ToCSS linkTitle: Transpile Sass to CSS description: Transpile Sass to CSS. -categories: [asset management] +categories: [] keywords: [] -menu: - docs: - parent: hugo-pipes - weight: 30 -weight: 30 aliases: [/hugo-pipes/transform-to-css/] --- diff --git a/content/en/installation/_common/_index.md b/content/en/installation/_common/_index.md deleted file mode 100644 index 4328d4d14..000000000 --- a/content/en/installation/_common/_index.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -cascade: - _build: - list: never - publishResources: false - render: never ---- - - diff --git a/content/en/installation/_index.md b/content/en/installation/_index.md index 69b3e197e..fdcb8f9eb 100644 --- a/content/en/installation/_index.md +++ b/content/en/installation/_index.md @@ -1,16 +1,8 @@ --- title: Installation - description: Install Hugo on macOS, Linux, Windows, BSD, and on any machine that can run the Go compiler tool chain. -aliases: [/getting-started/installing/] categories: [] keywords: [] -menu: - docs: - identifier: installation-in-this-section - parent: installation - weight: 10 weight: 10 +aliases: [/getting-started/installing/] --- - -Install Hugo on macOS, Linux, Windows, BSD, and on any machine that can run the Go compiler tool chain. diff --git a/content/en/installation/bsd.md b/content/en/installation/bsd.md index 1b2589c75..2f6519e6d 100644 --- a/content/en/installation/bsd.md +++ b/content/en/installation/bsd.md @@ -1,25 +1,20 @@ --- title: BSD description: Install Hugo on BSD derivatives. -categories: [installation] +categories: [] keywords: [] -menu: - docs: - parent: installation - weight: 50 -weight: 50 -toc: true +weight: 40 --- ## Editions -{{% include "installation/_common/01-editions.md" %}} +{{% include "/_common/installation/01-editions.md" %}} Unless your specific deployment needs require the extended/deploy edition, we recommend the extended edition. -{{% include "installation/_common/02-prerequisites.md" %}} +{{% include "/_common/installation/02-prerequisites.md" %}} -{{% include "installation/_common/03-prebuilt-binaries.md" %}} +{{% include "/_common/installation/03-prebuilt-binaries.md" %}} ## Repository packages @@ -67,7 +62,7 @@ doas pkg_add hugo [OpenBSD]: https://www.openbsd.org/ -{{% include "installation/_common/04-build-from-source.md" %}} +{{% include "/_common/installation/04-build-from-source.md" %}} ## Comparison diff --git a/content/en/installation/linux.md b/content/en/installation/linux.md index ba59d0f2a..731cfce4c 100644 --- a/content/en/installation/linux.md +++ b/content/en/installation/linux.md @@ -1,25 +1,20 @@ --- title: Linux description: Install Hugo on Linux. -categories: [installation] +categories: [] keywords: [] -menu: - docs: - parent: installation - weight: 30 -weight: 30 -toc: true +weight: 20 --- ## Editions -{{% include "installation/_common/01-editions.md" %}} +{{% include "/_common/installation/01-editions.md" %}} Unless your specific deployment needs require the extended/deploy edition, we recommend the extended edition. -{{% include "installation/_common/02-prerequisites.md" %}} +{{% include "/_common/installation/02-prerequisites.md" %}} -{{% include "installation/_common/03-prebuilt-binaries.md" %}} +{{% include "/_common/installation/03-prebuilt-binaries.md" %}} ## Package managers @@ -27,7 +22,7 @@ Unless your specific deployment needs require the extended/deploy edition, we re [Snap] is a free and open-source package manager for Linux. Available for [most distributions], snap packages are simple to install and are automatically updated. -The Hugo snap package is [strictly confined]. Strictly confined snaps run in complete isolation, up to a minimal access level that’s deemed always safe. The sites you create and build must be located within your home directory, or on removable media. +The Hugo snap package is [strictly confined]. Strictly confined snaps run in complete isolation, up to a minimal access level that's deemed always safe. The sites you create and build must be located within your home directory, or on removable media. To install the extended edition of Hugo: @@ -49,23 +44,16 @@ sudo snap connect hugo:ssh-keys sudo snap disconnect hugo:ssh-keys ``` -[most distributions]: https://snapcraft.io/docs/installing-snapd -[strictly confined]: https://snapcraft.io/docs/snap-confinement -[Snap]: https://snapcraft.io/ - -{{% include "installation/_common/homebrew.md" %}} +{{% include "/_common/installation/homebrew.md" %}} ## Repository packages Most Linux distributions maintain a repository for commonly installed applications. -{{% note %}} -The Hugo version available in package repositories varies based on Linux distribution and release, and in some cases will not be the [latest version]. - -Use one of the other installation methods if your package repository does not provide the desired version. - -[latest version]: https://github.com/gohugoio/hugo/releases/latest -{{% /note %}} +> [!note] +> The Hugo version available in package repositories varies based on Linux distribution and release, and in some cases will not be the [latest version]. +> +> Use one of the other installation methods if your package repository does not provide the desired version. ### Alpine Linux @@ -75,8 +63,6 @@ To install the extended edition of Hugo on [Alpine Linux]: doas apk add --no-cache --repository=https://dl-cdn.alpinelinux.org/alpine/edge/community hugo ``` -[Alpine Linux]: https://alpinelinux.org/ - ### Arch Linux Derivatives of the [Arch Linux] distribution of Linux include [EndeavourOS], [Garuda Linux], [Manjaro], and others. To install the extended edition of Hugo: @@ -85,11 +71,6 @@ Derivatives of the [Arch Linux] distribution of Linux include [EndeavourOS], [Ga sudo pacman -S hugo ``` -[Arch Linux]: https://archlinux.org/ -[EndeavourOS]: https://endeavouros.com/ -[Manjaro]: https://manjaro.org/ -[Garuda Linux]: https://garudalinux.org/ - ### Debian Derivatives of the [Debian] distribution of Linux include [elementary OS], [KDE neon], [Linux Lite], [Linux Mint], [MX Linux], [Pop!_OS], [Ubuntu], [Zorin OS], and others. To install the extended edition of Hugo: @@ -100,33 +81,22 @@ sudo apt install hugo You can also download Debian packages from the [latest release] page. -[Debian]: https://www.debian.org/ -[Exherbo]: https://www.exherbolinux.org/ -[elementary OS]: https://elementary.io/ -[KDE neon]: https://neon.kde.org/ -[Linux Lite]: https://www.linuxliteos.com/ -[Linux Mint]: https://linuxmint.com/ -[MX Linux]: https://mxlinux.org/ -[Pop!_OS]: https://pop.system76.com/ -[Ubuntu]: https://ubuntu.com/ -[Zorin OS]: https://zorin.com/os/ - ### Exherbo To install the extended edition of Hugo on [Exherbo]: 1. Add this line to /etc/paludis/options.conf: - ```text - www-apps/hugo extended - ``` + ```text + www-apps/hugo extended + ``` 1. Install using the Paludis package manager: - ```sh - cave resolve -x repository/heirecka - cave resolve -x hugo - ``` + ```sh + cave resolve -x repository/heirecka + cave resolve -x hugo + ``` ### Fedora @@ -136,10 +106,6 @@ Derivatives of the [Fedora] distribution of Linux include [CentOS], [Red Hat Ent sudo dnf install hugo ``` -[CentOS]: https://www.centos.org/ -[Fedora]: https://getfedora.org/ -[Red Hat Enterprise Linux]: https://www.redhat.com/ - ### Gentoo Derivatives of the [Gentoo] distribution of Linux include [Calculate Linux], [Funtoo], and others. To install the extended edition of Hugo: @@ -156,11 +122,6 @@ Derivatives of the [Gentoo] distribution of Linux include [Calculate Linux], [Fu sudo emerge www-apps/hugo ``` -[Calculate Linux]: https://www.calculate-linux.org/ -[Funtoo]: https://www.funtoo.org/ -[Gentoo]: https://www.gentoo.org/ -[USE]: https://packages.gentoo.org/packages/www-apps/hugo - ### NixOS The NixOS distribution of Linux includes Hugo in its package repository. To install the extended edition of Hugo: @@ -177,10 +138,6 @@ Derivatives of the [openSUSE] distribution of Linux include [GeckoLinux], [Linux sudo zypper install hugo ``` -[GeckoLinux]: https://geckolinux.github.io/ -[Linux Karmada]: https://linuxkamarada.com/ -[openSUSE]: https://www.opensuse.org/ - ### Solus The [Solus] distribution of Linux includes Hugo in its package repository. To install the extended edition of Hugo: @@ -189,8 +146,6 @@ The [Solus] distribution of Linux includes Hugo in its package repository. To in sudo eopkg install hugo ``` -[Solus]: https://getsol.us/ - ### Void Linux To install the extended edition of Hugo on [Void Linux]: @@ -199,9 +154,7 @@ To install the extended edition of Hugo on [Void Linux]: sudo xbps-install -S hugo ``` -[Void Linux]: https://voidlinux.org/ - -{{% include "installation/_common/04-build-from-source.md" %}} +{{% include "/_common/installation/04-build-from-source.md" %}} ## Comparison @@ -215,3 +168,35 @@ Latest version available?|:heavy_check_mark:|:heavy_check_mark:|varies|:heavy_ch [^1]: Easy if a previous version is still installed. [^2]: Snap packages are automatically updated. Homebrew requires advanced configuration. + +[Alpine Linux]: https://alpinelinux.org/ +[Arch Linux]: https://archlinux.org/ +[Calculate Linux]: https://www.calculate-linux.org/ +[CentOS]: https://www.centos.org/ +[Debian]: https://www.debian.org/ +[elementary OS]: https://elementary.io/ +[EndeavourOS]: https://endeavouros.com/ +[Exherbo]: https://www.exherbolinux.org/ +[Fedora]: https://getfedora.org/ +[Funtoo]: https://www.funtoo.org/ +[Garuda Linux]: https://garudalinux.org/ +[GeckoLinux]: https://geckolinux.github.io/ +[Gentoo]: https://www.gentoo.org/ +[KDE neon]: https://neon.kde.org/ +[latest version]: https://github.com/gohugoio/hugo/releases/latest +[Linux Karmada]: https://linuxkamarada.com/ +[Linux Lite]: https://www.linuxliteos.com/ +[Linux Mint]: https://linuxmint.com/ +[Manjaro]: https://manjaro.org/ +[most distributions]: https://snapcraft.io/docs/installing-snapd +[MX Linux]: https://mxlinux.org/ +[openSUSE]: https://www.opensuse.org/ +[Pop!_OS]: https://pop.system76.com/ +[Red Hat Enterprise Linux]: https://www.redhat.com/ +[Snap]: https://snapcraft.io/ +[Solus]: https://getsol.us/ +[strictly confined]: https://snapcraft.io/docs/snap-confinement +[Ubuntu]: https://ubuntu.com/ +[USE]: https://packages.gentoo.org/packages/www-apps/hugo +[Void Linux]: https://voidlinux.org/ +[Zorin OS]: https://zorin.com/os/ diff --git a/content/en/installation/macos.md b/content/en/installation/macos.md index dace545db..a873b512a 100644 --- a/content/en/installation/macos.md +++ b/content/en/installation/macos.md @@ -1,29 +1,24 @@ --- title: macOS description: Install Hugo on macOS. -categories: [installation] +categories: [] keywords: [] -menu: - docs: - parent: installation - weight: 20 -weight: 20 -toc: true +weight: 10 --- ## Editions -{{% include "installation/_common/01-editions.md" %}} +{{% include "/_common/installation/01-editions.md" %}} Unless your specific deployment needs require the extended/deploy edition, we recommend the extended edition. -{{% include "installation/_common/02-prerequisites.md" %}} +{{% include "/_common/installation/02-prerequisites.md" %}} -{{% include "installation/_common/03-prebuilt-binaries.md" %}} +{{% include "/_common/installation/03-prebuilt-binaries.md" %}} ## Package managers -{{% include "installation/_common/homebrew.md" %}} +{{% include "/_common/installation/homebrew.md" %}} ### MacPorts @@ -35,7 +30,7 @@ sudo port install hugo [MacPorts]: https://www.macports.org/ -{{% include "installation/_common/04-build-from-source.md" %}} +{{% include "/_common/installation/04-build-from-source.md" %}} ## Comparison diff --git a/content/en/installation/windows.md b/content/en/installation/windows.md index e66878d70..a5920d45f 100644 --- a/content/en/installation/windows.md +++ b/content/en/installation/windows.md @@ -1,29 +1,23 @@ --- title: Windows description: Install Hugo on Windows. -categories: [installation] +categories: [] keywords: [] -menu: - docs: - parent: installation - weight: 40 -weight: 40 -toc: true +weight: 30 --- -{{% note %}} -Hugo v0.121.1 and later require at least Windows 10 or Windows Server 2016. -{{% /note %}} +> [!note] +> Hugo v0.121.1 and later require at least Windows 10 or Windows Server 2016. ## Editions -{{% include "installation/_common/01-editions.md" %}} +{{% include "/_common/installation/01-editions.md" %}} Unless your specific deployment needs require the extended/deploy edition, we recommend the extended edition. -{{% include "installation/_common/02-prerequisites.md" %}} +{{% include "/_common/installation/02-prerequisites.md" %}} -{{% include "installation/_common/03-prebuilt-binaries.md" %}} +{{% include "/_common/installation/03-prebuilt-binaries.md" %}} ## Package managers @@ -35,8 +29,6 @@ Unless your specific deployment needs require the extended/deploy edition, we re choco install hugo-extended ``` -[Chocolatey]: https://chocolatey.org/ - ### Scoop [Scoop] is a free and open-source package manager for Windows. To install the extended edition of Hugo: @@ -45,8 +37,6 @@ choco install hugo-extended scoop install hugo-extended ``` -[Scoop]: https://scoop.sh/ - ### Winget [Winget] is Microsoft's official free and open-source package manager for Windows. To install the extended edition of Hugo: @@ -61,13 +51,10 @@ To uninstall the extended edition of Hugo: winget uninstall --name "Hugo (Extended)" ``` -[Winget]: https://learn.microsoft.com/en-us/windows/package-manager/ +{{% include "/_common/installation/04-build-from-source.md" %}} -{{% include "installation/_common/04-build-from-source.md" %}} - -{{% note %}} -See these [detailed instructions](https://discourse.gohugo.io/t/41370) to install GCC on Windows. -{{% /note %}} +> [!note] +> See these [detailed instructions](https://discourse.gohugo.io/t/41370) to install GCC on Windows. ## Comparison @@ -81,3 +68,7 @@ Latest version available?|:heavy_check_mark:|:heavy_check_mark:|:heavy_check_mar [^1]: Possible but requires advanced configuration. [^2]: Easy if a previous version is still installed. + +[Chocolatey]: https://chocolatey.org/ +[Scoop]: https://scoop.sh/ +[Winget]: https://learn.microsoft.com/en-us/windows/package-manager/ diff --git a/content/en/methods/_index.md b/content/en/methods/_index.md index e45f2fef7..39f2b6146 100644 --- a/content/en/methods/_index.md +++ b/content/en/methods/_index.md @@ -1,17 +1,8 @@ --- title: Methods - description: Use these methods within your templates. categories: [] keywords: [] -menu: - docs: - identifier: methods-in-this-section - parent: methods - weight: 10 weight: 10 -showSectionMenu: true aliases: ['/variables/'] --- - -Use these methods within your templates. diff --git a/content/en/methods/duration/Abs.md b/content/en/methods/duration/Abs.md index d035f97b6..2e85797ea 100644 --- a/content/en/methods/duration/Abs.md +++ b/content/en/methods/duration/Abs.md @@ -3,12 +3,10 @@ title: Abs description: Returns the absolute value of the given time.Duration value. categories: [] keywords: [] -action: - related: - - functions/time/Duration - - functions/time/ParseDuration - returnType: time.Duration - signatures: [DURATION.Abs] +params: + functions_and_methods: + returnType: time.Duration + signatures: [DURATION.Abs] --- ```go-html-template diff --git a/content/en/methods/duration/Hours.md b/content/en/methods/duration/Hours.md index 5b2d893b9..23655510e 100644 --- a/content/en/methods/duration/Hours.md +++ b/content/en/methods/duration/Hours.md @@ -3,12 +3,10 @@ title: Hours description: Returns the time.Duration value as a floating point number of hours. categories: [] keywords: [] -action: - related: - - functions/time/Duration - - functions/time/ParseDuration - returnType: float64 - signatures: [DURATION.Hours] +params: + functions_and_methods: + returnType: float64 + signatures: [DURATION.Hours] --- ```go-html-template diff --git a/content/en/methods/duration/Microseconds.md b/content/en/methods/duration/Microseconds.md index c8b210c94..c090316d0 100644 --- a/content/en/methods/duration/Microseconds.md +++ b/content/en/methods/duration/Microseconds.md @@ -3,12 +3,10 @@ title: Microseconds description: Returns the time.Duration value as an integer microsecond count. categories: [] keywords: [] -action: - related: - - functions/time/Duration - - functions/time/ParseDuration - returnType: int64 - signatures: [DURATION.Microseconds] +params: + functions_and_methods: + returnType: int64 + signatures: [DURATION.Microseconds] --- ```go-html-template diff --git a/content/en/methods/duration/Milliseconds.md b/content/en/methods/duration/Milliseconds.md index 32809027a..288f3695a 100644 --- a/content/en/methods/duration/Milliseconds.md +++ b/content/en/methods/duration/Milliseconds.md @@ -3,12 +3,10 @@ title: Milliseconds description: Returns the time.Duration value as an integer millisecond count. categories: [] keywords: [] -action: - related: - - functions/time/Duration - - functions/time/ParseDuration - returnType: int64 - signatures: [DURATION.Milliseconds] +params: + functions_and_methods: + returnType: int64 + signatures: [DURATION.Milliseconds] --- ```go-html-template diff --git a/content/en/methods/duration/Minutes.md b/content/en/methods/duration/Minutes.md index d3e57fba5..aec904fa7 100644 --- a/content/en/methods/duration/Minutes.md +++ b/content/en/methods/duration/Minutes.md @@ -3,12 +3,10 @@ title: Minutes description: Returns the time.Duration value as a floating point number of minutes. categories: [] keywords: [] -action: - related: - - functions/time/Duration - - functions/time/ParseDuration - returnType: float64 - signatures: [DURATION.Minutes] +params: + functions_and_methods: + returnType: float64 + signatures: [DURATION.Minutes] --- ```go-html-template diff --git a/content/en/methods/duration/Nanoseconds.md b/content/en/methods/duration/Nanoseconds.md index 66d2981f2..fd1b9e496 100644 --- a/content/en/methods/duration/Nanoseconds.md +++ b/content/en/methods/duration/Nanoseconds.md @@ -3,12 +3,10 @@ title: Nanoseconds description: Returns the time.Duration value as an integer nanosecond count. categories: [] keywords: [] -action: - related: - - functions/time/Duration - - functions/time/ParseDuration - returnType: int64 - signatures: [DURATION.Nanoseconds] +params: + functions_and_methods: + returnType: int64 + signatures: [DURATION.Nanoseconds] --- ```go-html-template diff --git a/content/en/methods/duration/Round.md b/content/en/methods/duration/Round.md index 0722a6076..dfd06253f 100644 --- a/content/en/methods/duration/Round.md +++ b/content/en/methods/duration/Round.md @@ -3,12 +3,10 @@ title: Round description: Returns the result of rounding DURATION1 to the nearest multiple of DURATION2. categories: [] keywords: [] -action: - related: - - functions/time/Duration - - functions/time/ParseDuration - returnType: - signatures: [DURATION1.Round DURATION2] +params: + functions_and_methods: + returnType: + signatures: [DURATION1.Round DURATION2] --- ```go-html-template diff --git a/content/en/methods/duration/Seconds.md b/content/en/methods/duration/Seconds.md index d23d5ec15..8b6d060b9 100644 --- a/content/en/methods/duration/Seconds.md +++ b/content/en/methods/duration/Seconds.md @@ -3,12 +3,10 @@ title: Seconds description: Returns the time.Duration value as a floating point number of seconds. categories: [] keywords: [] -action: - related: - - functions/time/Duration - - functions/time/ParseDuration - returnType: float64 - signatures: [DURATION.Seconds] +params: + functions_and_methods: + returnType: float64 + signatures: [DURATION.Seconds] --- ```go-html-template diff --git a/content/en/methods/duration/Truncate.md b/content/en/methods/duration/Truncate.md index 78cddc27a..5a785a77a 100644 --- a/content/en/methods/duration/Truncate.md +++ b/content/en/methods/duration/Truncate.md @@ -3,12 +3,10 @@ title: Truncate description: Returns the result of rounding DURATION1 toward zero to a multiple of DURATION2. categories: [] keywords: [] -action: - related: - - functions/time/Duration - - functions/time/ParseDuration - returnType: time.Duration - signatures: [DURATION1.Truncate DURATION2] +params: + functions_and_methods: + returnType: time.Duration + signatures: [DURATION1.Truncate DURATION2] --- ```go-html-template diff --git a/content/en/methods/duration/_index.md b/content/en/methods/duration/_index.md index 9fc4f814c..aeb113820 100644 --- a/content/en/methods/duration/_index.md +++ b/content/en/methods/duration/_index.md @@ -4,9 +4,4 @@ linkTitle: Duration description: Use these methods with time.Duration values. categories: [] keywords: [] -menu: - docs: - parent: methods --- - -Use these methods with time.Duration values. diff --git a/content/en/methods/menu-entry/Children.md b/content/en/methods/menu-entry/Children.md index ad671b2d0..ecad415fa 100644 --- a/content/en/methods/menu-entry/Children.md +++ b/content/en/methods/menu-entry/Children.md @@ -3,11 +3,10 @@ title: Children description: Returns a collection of child menu entries, if any, under the given menu entry. categories: [] keywords: [] -action: - related: - - methods/menu-entry/HasChildren - returnType: navigation.Menu - signatures: [MENUENTRY.Children] +params: + functions_and_methods: + returnType: navigation.Menu + signatures: [MENUENTRY.Children] --- Use the `Children` method when rendering a nested menu. diff --git a/content/en/methods/menu-entry/HasChildren.md b/content/en/methods/menu-entry/HasChildren.md index fac03b7ae..03e6cb672 100644 --- a/content/en/methods/menu-entry/HasChildren.md +++ b/content/en/methods/menu-entry/HasChildren.md @@ -3,11 +3,10 @@ title: HasChildren description: Reports whether the given menu entry has child menu entries. categories: [] keywords: [] -action: - related: - - methods/menu-entry/Children - returnType: bool - signatures: [MENUENTRY.HasChildren] +params: + functions_and_methods: + returnType: bool + signatures: [MENUENTRY.HasChildren] --- Use the `HasChildren` method when rendering a nested menu. diff --git a/content/en/methods/menu-entry/Identifier.md b/content/en/methods/menu-entry/Identifier.md index ba8b77ece..809624459 100644 --- a/content/en/methods/menu-entry/Identifier.md +++ b/content/en/methods/menu-entry/Identifier.md @@ -1,18 +1,16 @@ --- title: Identifier -description: Returns the `identifier` property of the given menu entry. +description: Returns the `identifier` property of the given menu entry. categories: [] keywords: [] -action: - related: [] - returnType: string - signatures: [MENUENTRY.Identifier] +params: + functions_and_methods: + returnType: string + signatures: [MENUENTRY.Identifier] --- The `Identifier` method returns the `identifier` property of the menu entry. If you define the menu entry [automatically], it returns the page's section. -[automatically]: /content-management/menus/#define-automatically - {{< code-toggle file=hugo >}} [[menus.main]] identifier = 'about' @@ -37,8 +35,7 @@ This example uses the `Identifier` method when querying the translation table on
``` -{{% note %}} -In the menu definition above, note that the `identifier` property is only required when two or more menu entries have the same name, or when localizing the name using translation tables. +> [!note] +> In the menu definition above, note that the `identifier` property is only required when two or more menu entries have the same name, or when localizing the name using translation tables. -[details]: /content-management/menus/#properties-front-matter -{{% /note %}} +[automatically]: /content-management/menus/#define-automatically diff --git a/content/en/methods/menu-entry/KeyName.md b/content/en/methods/menu-entry/KeyName.md index 409cb31d6..d614a5a87 100644 --- a/content/en/methods/menu-entry/KeyName.md +++ b/content/en/methods/menu-entry/KeyName.md @@ -1,12 +1,12 @@ --- title: KeyName -description: Returns the `identifier` property of the given menu entry, falling back to its `name` property. +description: Returns the `identifier` property of the given menu entry, falling back to its `name` property. categories: [] keywords: [] -action: - related: [] - returnType: string - signatures: [MENUENTRY.KeyName] +params: + functions_and_methods: + returnType: string + signatures: [MENUENTRY.KeyName] --- In this menu definition, the second entry does not contain an `identifier`, so the `Identifier` method returns its `name` property instead: diff --git a/content/en/methods/menu-entry/Menu.md b/content/en/methods/menu-entry/Menu.md index 79b400f1f..074911eeb 100644 --- a/content/en/methods/menu-entry/Menu.md +++ b/content/en/methods/menu-entry/Menu.md @@ -3,12 +3,10 @@ title: Menu description: Returns the identifier of the menu that contains the given menu entry. categories: [] keywords: [] -action: - related: - - methods/page/IsMenuCurrent - - methods/page/HasMenuCurrent - returnType: string - signatures: [MENUENTRY.Menu] +params: + functions_and_methods: + returnType: string + signatures: [MENUENTRY.Menu] --- ```go-html-template diff --git a/content/en/methods/menu-entry/Name.md b/content/en/methods/menu-entry/Name.md index fb5fc1b5b..706d0f8c8 100644 --- a/content/en/methods/menu-entry/Name.md +++ b/content/en/methods/menu-entry/Name.md @@ -3,15 +3,15 @@ title: Name description: Returns the `name` property of the given menu entry. categories: [] keywords: [] -action: - related: [] - returnType: string - signatures: [MENUENTRY.Name] +params: + functions_and_methods: + returnType: string + signatures: [MENUENTRY.Name] --- 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`]. +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/ diff --git a/content/en/methods/menu-entry/Page.md b/content/en/methods/menu-entry/Page.md index d177a1af0..489ee7acc 100644 --- a/content/en/methods/menu-entry/Page.md +++ b/content/en/methods/menu-entry/Page.md @@ -3,10 +3,10 @@ title: Page description: Returns the Page object associated with the given menu entry. categories: [] keywords: [] -action: - related: [] - returnType: page.Page - signatures: [MENUENTRY.Page] +params: + functions_and_methods: + returnType: page.Page + signatures: [MENUENTRY.Page] --- Regardless of how you [define menu entries], an entry associated with a page has access to its [methods]. diff --git a/content/en/methods/menu-entry/PageRef.md b/content/en/methods/menu-entry/PageRef.md index 368579796..979879b03 100644 --- a/content/en/methods/menu-entry/PageRef.md +++ b/content/en/methods/menu-entry/PageRef.md @@ -3,12 +3,10 @@ title: PageRef description: Returns the `pageRef` property of the given menu entry. categories: [] keywords: [] -action: - related: - - /methods/menu-entry/URL - returnType: string - signatures: [MENUENTRY.PageRef] -toc: true +params: + functions_and_methods: + returnType: string + signatures: [MENUENTRY.PageRef] --- The use case for this method is rare. @@ -31,28 +29,15 @@ If a matching page is not found: - The [`Page`] method returns nil - The [`HasMenuCurrent`] and [`IsMenuCurrent`] methods on a `Page` object return `false` -{{% note %}} -In almost also scenarios you should use the [`URL`] method instead. - -[`URL`]: /methods/menu-entry/url/ -{{% /note %}} - -[defining a menu entry]: /content-management/menus/#define-in-site-configuration -[`Page`]: /methods/menu-entry/page/ -[`URL`]: /methods/menu-entry/url/ -[`IsMenuCurrent`]: /methods/page/ismenucurrent/ -[`HasMenuCurrent`]: /methods/page/hasmenucurrent/ -[`RelPermalink`]: /methods/page/relpermalink/ +> [!note] +> In almost also scenarios you should use the [`URL`] method instead. ## Example This example is contrived. -{{% note %}} -In almost also scenarios you should use the [`URL`] method instead. - -[`URL`]: /methods/menu-entry/url/ -{{% /note %}} +> [!note] +> In almost also scenarios you should use the [`URL`] method instead. Consider this content structure: @@ -77,13 +62,13 @@ weight = 20 With this template code: -{{< code file=layouts/partials/menu.html >}} +```go-html-template {file="layouts/partials/menu.html"} -{{< /code >}} +``` Hugo render this HTML: @@ -98,13 +83,13 @@ In the above note that the `href` attribute of the second `anchor` element is bl With this template code: -{{< code file=layouts/partials/menu.html >}} +```go-html-template {file="layouts/partials/menu.html"} -{{< /code >}} +``` Hugo renders this HTML: @@ -116,3 +101,9 @@ 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. + +[`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 diff --git a/content/en/methods/menu-entry/Params.md b/content/en/methods/menu-entry/Params.md index 4d3e8bdaf..20c4f7fc7 100644 --- a/content/en/methods/menu-entry/Params.md +++ b/content/en/methods/menu-entry/Params.md @@ -3,10 +3,10 @@ title: Params description: Returns the `params` property of the given menu entry. categories: [] keywords: [] -action: - related: [] - returnType: maps.Params - signatures: [MENUENTRY.Params] +params: + functions_and_methods: + returnType: maps.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: diff --git a/content/en/methods/menu-entry/Parent.md b/content/en/methods/menu-entry/Parent.md index af1b4afe6..7c617527b 100644 --- a/content/en/methods/menu-entry/Parent.md +++ b/content/en/methods/menu-entry/Parent.md @@ -3,10 +3,10 @@ title: Parent description: Returns the `parent` property of the given menu entry. categories: [] keywords: [] -action: - related: [] - returnType: string - signatures: [MENUENTRY.Parent] +params: + functions_and_methods: + returnType: string + signatures: [MENUENTRY.Parent] --- With this menu definition: @@ -40,7 +40,7 @@ This template renders the nested menu, listing the `parent` property next each o {{ if .HasChildren }} {{ end }} diff --git a/content/en/methods/menu-entry/Post.md b/content/en/methods/menu-entry/Post.md index b2fa2da5b..2da8c38d8 100644 --- a/content/en/methods/menu-entry/Post.md +++ b/content/en/methods/menu-entry/Post.md @@ -1,13 +1,12 @@ --- title: Post -description: Returns the `post` property of the given menu entry. +description: Returns the `post` property of the given menu entry. categories: [] keywords: [] -action: - related: - - methods/menu-entry/Pre - returnType: template.HTML - signatures: [MENUENTRY.Post] +params: + functions_and_methods: + returnType: template.HTML + signatures: [MENUENTRY.Post] --- -{{% include "methods/menu-entry/_common/pre-post.md" %}} +{{% include "/_common/menu-entries/pre-and-post.md" %}} diff --git a/content/en/methods/menu-entry/Pre.md b/content/en/methods/menu-entry/Pre.md index df7c8f16e..19af243e7 100644 --- a/content/en/methods/menu-entry/Pre.md +++ b/content/en/methods/menu-entry/Pre.md @@ -1,13 +1,12 @@ --- title: Pre -description: Returns the `pre` property of the given menu entry. +description: Returns the `pre` property of the given menu entry. categories: [] keywords: [] -action: - related: - - methods/menu-entry/Post - returnType: template.HTML - signatures: [MENUENTRY.Pre] +params: + functions_and_methods: + returnType: template.HTML + signatures: [MENUENTRY.Pre] --- -{{% include "methods/menu-entry/_common/pre-post.md" %}} +{{% include "/_common/menu-entries/pre-and-post.md" %}} diff --git a/content/en/methods/menu-entry/Title.md b/content/en/methods/menu-entry/Title.md index 64bba2d44..526132d7c 100644 --- a/content/en/methods/menu-entry/Title.md +++ b/content/en/methods/menu-entry/Title.md @@ -1,15 +1,15 @@ --- title: Title -description: Returns the `title` property of the given menu entry. +description: Returns the `title` property of the given menu entry. categories: [] keywords: [] -action: - related: [] - returnType: string - signatures: [MENUENTRY.Title] +params: + functions_and_methods: + returnType: string + signatures: [MENUENTRY.Title] --- -The `Title` method returns the `title` property of the given menu entry. If the `title` is not defined, and the menu entry resolves to a page, the `Title` returns the page [`Title`]. +The `Title` method returns the `title` property of the given menu entry. If the `title` is not defined, and the menu entry resolves to a page, the `Title` returns the page [`Title`]. [`Title`]: /methods/page/title/ diff --git a/content/en/methods/menu-entry/URL.md b/content/en/methods/menu-entry/URL.md index 47db9153e..e29a6f058 100644 --- a/content/en/methods/menu-entry/URL.md +++ b/content/en/methods/menu-entry/URL.md @@ -3,10 +3,10 @@ title: URL description: Returns the relative permalink of the page associated with the given menu entry, else its `url` property. categories: [] keywords: [] -action: - related: [] - returnType: string - signatures: [MENUENTRY.URL] +params: + functions_and_methods: + returnType: string + signatures: [MENUENTRY.URL] --- For menu entries associated with a page, the `URL` method returns the page's [`RelPermalink`], otherwise it returns the entry's `url` property. diff --git a/content/en/methods/menu-entry/Weight.md b/content/en/methods/menu-entry/Weight.md index eab935736..b96e2cc87 100644 --- a/content/en/methods/menu-entry/Weight.md +++ b/content/en/methods/menu-entry/Weight.md @@ -1,17 +1,17 @@ --- title: Weight -description: Returns the `weight` property of the given menu entry. +description: Returns the `weight` property of the given menu entry. categories: [] keywords: [] -action: - related: [] - returnType: int - signatures: [MENUENTRY.Weight] +params: + functions_and_methods: + returnType: int + signatures: [MENUENTRY.Weight] --- -If you define the menu entry [automatically], the `Weight` method returns the page’s [`Weight`]. +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`. +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 diff --git a/content/en/methods/menu-entry/_common/_index.md b/content/en/methods/menu-entry/_common/_index.md deleted file mode 100644 index 4328d4d14..000000000 --- a/content/en/methods/menu-entry/_common/_index.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -cascade: - _build: - list: never - publishResources: false - render: never ---- - - diff --git a/content/en/methods/menu-entry/_index.md b/content/en/methods/menu-entry/_index.md index d89663593..129e9bcdc 100644 --- a/content/en/methods/menu-entry/_index.md +++ b/content/en/methods/menu-entry/_index.md @@ -4,9 +4,4 @@ linkTitle: Menu entry description: Use these methods in your menu templates. categories: [] keywords: [] -menu: - docs: - parent: methods --- - -Use these methods in your menu templates. diff --git a/content/en/methods/menu/ByName.md b/content/en/methods/menu/ByName.md index 2e28016b6..d98a4aced 100644 --- a/content/en/methods/menu/ByName.md +++ b/content/en/methods/menu/ByName.md @@ -3,10 +3,10 @@ title: ByName description: Returns the given menu with its entries sorted by name. categories: [] keywords: [] -action: - related: [] - returnType: navigation.Menu - signatures: [MENU.ByName] +params: + functions_and_methods: + returnType: navigation.Menu + signatures: [MENU.ByName] --- The `Sort` method returns the given menu with its entries sorted by `name`. diff --git a/content/en/methods/menu/ByWeight.md b/content/en/methods/menu/ByWeight.md index 7ba27031a..013d37e13 100644 --- a/content/en/methods/menu/ByWeight.md +++ b/content/en/methods/menu/ByWeight.md @@ -3,10 +3,10 @@ title: ByWeight description: Returns the given menu with its entries sorted by weight, then by name, then by identifier. categories: [] keywords: [] -action: - related: [] - returnType: navigation.Menu - signatures: [MENU.ByWeight] +params: + functions_and_methods: + returnType: navigation.Menu + signatures: [MENU.ByWeight] --- The `ByWeight` method returns the given menu with its entries sorted by [`weight`](g), then by `name`, then by `identifier`. This is the default sort order. @@ -53,11 +53,8 @@ Hugo renders this to: ``` -{{% note %}} -In the menu definition above, note that the `identifier` property is only required when two or more menu entries have the same name, or when localizing the name using translation tables. - -[details]: /content-management/menus/#properties-front-matter -{{% /note %}} +> [!note] +> In the menu definition above, note that the `identifier` property is only required when two or more menu entries have the same name, or when localizing the name using translation tables. You can also sort menu entries using the [`sort`] function. For example, to sort by `weight` in descending order: diff --git a/content/en/methods/menu/Limit.md b/content/en/methods/menu/Limit.md index 23a523dbd..005fef144 100644 --- a/content/en/methods/menu/Limit.md +++ b/content/en/methods/menu/Limit.md @@ -3,10 +3,10 @@ title: Limit description: Returns the given menu, limited to the first N entries. categories: [] keywords: [] -action: - related: [] - returnType: navigation.Menu - signatures: [MENU.Limit N] +params: + functions_and_methods: + returnType: navigation.Menu + signatures: [MENU.Limit N] --- The `Limit` method returns the given menu, limited to the first N entries. diff --git a/content/en/methods/menu/Reverse.md b/content/en/methods/menu/Reverse.md index a3fe09dce..1ee31aa51 100644 --- a/content/en/methods/menu/Reverse.md +++ b/content/en/methods/menu/Reverse.md @@ -3,10 +3,10 @@ title: Reverse description: Returns the given menu, reversing the sort order of its entries. categories: [] keywords: [] -action: - related: [] - returnType: navigation.Menu - signatures: [MENU.Reverse] +params: + functions_and_methods: + returnType: navigation.Menu + signatures: [MENU.Reverse] --- The `Reverse` method returns the given menu, reversing the sort order of its entries. diff --git a/content/en/methods/menu/_index.md b/content/en/methods/menu/_index.md index f5b925fd6..41084fdba 100644 --- a/content/en/methods/menu/_index.md +++ b/content/en/methods/menu/_index.md @@ -4,9 +4,4 @@ linkTitle: Menu description: Use these methods when ranging through menu entries. categories: [] keywords: [] -menu: - docs: - parent: methods --- - -Use these methods when ranging through menu entries. diff --git a/content/en/methods/page/Aliases.md b/content/en/methods/page/Aliases.md index 15e73384b..775404bd3 100644 --- a/content/en/methods/page/Aliases.md +++ b/content/en/methods/page/Aliases.md @@ -3,10 +3,10 @@ title: Aliases description: Returns the URL aliases as defined in front matter. categories: [] keywords: [] -action: - related: [] - returnType: '[]string' - signatures: [PAGE.Aliases] +params: + functions_and_methods: + returnType: '[]string' + signatures: [PAGE.Aliases] --- The `Aliases` method on a `Page` object returns the URL [aliases] as defined in front matter. diff --git a/content/en/methods/page/AllTranslations.md b/content/en/methods/page/AllTranslations.md index 51d82d4f9..62117b429 100644 --- a/content/en/methods/page/AllTranslations.md +++ b/content/en/methods/page/AllTranslations.md @@ -1,15 +1,12 @@ --- title: AllTranslations -description: Returns all translations of the given page, including the current language. +description: Returns all translations of the given page, including the current language. categories: [] keywords: [] -action: - related: - - methods/page/Translations - - methods/page/IsTranslated - - methods/page/TranslationKey - returnType: page.Pages - signatures: [PAGE.AllTranslations] +params: + functions_and_methods: + returnType: page.Pages + signatures: [PAGE.AllTranslations] --- With this site configuration: diff --git a/content/en/methods/page/AlternativeOutputFormats.md b/content/en/methods/page/AlternativeOutputFormats.md index 03e14e287..c4075d010 100644 --- a/content/en/methods/page/AlternativeOutputFormats.md +++ b/content/en/methods/page/AlternativeOutputFormats.md @@ -3,20 +3,19 @@ title: AlternativeOutputFormats description: Returns a slice of OutputFormat objects, excluding the current output format, each representing one of the output formats enabled for the given page. categories: [] keywords: [] -action: - related: - - methods/page/OutputFormats - returnType: page.OutputFormats - signatures: [PAGE.AlternativeOutputFormats] +params: + functions_and_methods: + returnType: page.OutputFormats + signatures: [PAGE.AlternativeOutputFormats] --- {{% glossary-term "output format" %}} -The `AlternativeOutputFormats` method on a `Page` object returns a slice of `OutputFormat` objects, excluding the current output format, each representing one of the output formats enabled for the given page.. See [details](/templates/output-formats/). +The `AlternativeOutputFormats` method on a `Page` object returns a slice of `OutputFormat` objects, excluding the current output format, each representing one of the output formats enabled for the given page. See [details](/configuration/output-formats/). ## Methods -{{% include "methods/page/_common/output-format-methods.md" %}} +{{% include "/_common/methods/page/output-format-methods.md" %}} ## Example @@ -29,7 +28,7 @@ Generate a `link` element in the `` of each page for each of the alternati {{ if .IsHome }} {{ $title = site.Title }} {{ end }} - {{ range .AlternativeOutputFormats -}} + {{ range .AlternativeOutputFormats }} {{ printf `` .Rel .MediaType.Type .Permalink $title | safeHTML }} {{ end }} ... diff --git a/content/en/methods/page/Ancestors.md b/content/en/methods/page/Ancestors.md index 4fb00fc06..d8275cf76 100644 --- a/content/en/methods/page/Ancestors.md +++ b/content/en/methods/page/Ancestors.md @@ -1,23 +1,14 @@ --- title: Ancestors -description: Returns a collection of Page objects, one for each ancestor section of the given page. +description: Returns a collection of Page objects, one for each ancestor section of the given page. categories: [] keywords: [] -action: - related: - - methods/page/CurrentSection - - methods/page/FirstSection - - methods/page/InSection - - methods/page/IsAncestor - - methods/page/IsDescendant - - methods/page/Parent - - methods/page/Sections - returnType: page.Pages - signatures: [PAGE.Ancestors] +params: + functions_and_methods: + returnType: page.Pages + signatures: [PAGE.Ancestors] --- -{{% glossary-term section %}} - With this content structure: ```text diff --git a/content/en/methods/page/BundleType.md b/content/en/methods/page/BundleType.md index b7d15ce4c..e919511da 100644 --- a/content/en/methods/page/BundleType.md +++ b/content/en/methods/page/BundleType.md @@ -3,10 +3,10 @@ title: BundleType description: Returns the bundle type of the given page, or an empty string if the page is not a page bundle. categories: [] keywords: [] -action: - related: [] - returnType: string - signatures: [PAGE.BundleType] +params: + functions_and_methods: + returnType: string + signatures: [PAGE.BundleType] --- A page bundle is a directory that encapsulates both content and associated [resources](g). There are two types of page bundles: [leaf bundles](g) and [branch bundles](g). See [details](/content-management/page-bundles/). diff --git a/content/en/methods/page/CodeOwners.md b/content/en/methods/page/CodeOwners.md index c0baf26ad..00afa7549 100644 --- a/content/en/methods/page/CodeOwners.md +++ b/content/en/methods/page/CodeOwners.md @@ -3,11 +3,10 @@ title: CodeOwners description: Returns of slice of code owners for the given page, derived from the CODEOWNERS file in the root of the project directory. categories: [] keywords: [] -action: - related: - - methods/page/GitInfo - returnType: '[]string' - signatures: [PAGE.CodeOwners] +params: + functions_and_methods: + returnType: '[]string' + signatures: [PAGE.CodeOwners] --- GitHub and GitLab support CODEOWNERS files. This file specifies the users responsible for developing and maintaining software and documentation. This definition can apply to the entire repository, specific directories, or to individual files. To learn more: diff --git a/content/en/methods/page/Content.md b/content/en/methods/page/Content.md index 373c6590a..21348ebe6 100644 --- a/content/en/methods/page/Content.md +++ b/content/en/methods/page/Content.md @@ -3,16 +3,10 @@ title: Content description: Returns the rendered content of the given page. categories: [] keywords: [] -action: - related: - - methods/page/Summary - - methods/page/ContentWithoutSummary - - methods/page/RawContent - - methods/page/Plain - - methods/page/PlainWords - - methods/page/RenderShortcodes - returnType: template.HTML - signatures: [PAGE.Content] +params: + functions_and_methods: + returnType: template.HTML + signatures: [PAGE.Content] --- The `Content` method on a `Page` object renders Markdown and shortcodes to HTML. diff --git a/content/en/methods/page/ContentWithoutSummary.md b/content/en/methods/page/ContentWithoutSummary.md index 527f5d962..4923b1197 100644 --- a/content/en/methods/page/ContentWithoutSummary.md +++ b/content/en/methods/page/ContentWithoutSummary.md @@ -3,16 +3,10 @@ title: ContentWithoutSummary description: Returns the rendered content of the given page, excluding the content summary. categories: [] keywords: [] -action: - related: - - methods/page/Content - - methods/page/Summary - - methods/page/RawContent - - methods/page/Plain - - methods/page/PlainWords - - methods/page/RenderShortcodes - returnType: template.HTML - signatures: [PAGE.ContentWithoutSummary] +params: + functions_and_methods: + returnType: template.HTML + signatures: [PAGE.ContentWithoutSummary] --- {{< new-in 0.134.0 />}} diff --git a/content/en/methods/page/CurrentSection.md b/content/en/methods/page/CurrentSection.md index 1684ee483..93457f13f 100644 --- a/content/en/methods/page/CurrentSection.md +++ b/content/en/methods/page/CurrentSection.md @@ -3,24 +3,16 @@ title: CurrentSection description: Returns the Page object of the section in which the given page resides. categories: [] keywords: [] -action: - related: - - methods/page/Ancestors - - methods/page/FirstSection - - methods/page/InSection - - methods/page/IsAncestor - - methods/page/IsDescendant - - methods/page/Parent - - methods/page/Sections - returnType: page.Page - signatures: [PAGE.CurrentSection] +params: + functions_and_methods: + returnType: page.Page + signatures: [PAGE.CurrentSection] --- {{% glossary-term section %}} -{{% note %}} -The current section of a [section page](g), [taxonomy page](g), [term page](g), or the home page, is itself. -{{% /note %}} +> [!note] +> The current section of a [section page](g), [taxonomy page](g), [term page](g), or the home page, is itself. Consider this content structure: diff --git a/content/en/methods/page/Data.md b/content/en/methods/page/Data.md index b3df243c5..ae0bdc57f 100644 --- a/content/en/methods/page/Data.md +++ b/content/en/methods/page/Data.md @@ -3,24 +3,18 @@ title: Data description: Returns a unique data object for each page kind. categories: [] keywords: [] -action: - related: [] - returnType: page.Data - signatures: [PAGE.Data] -toc: true +params: + functions_and_methods: + returnType: page.Data + signatures: [PAGE.Data] --- The `Data` method on a `Page` object returns a unique data object for each [page kind](g). -{{% note %}} -The `Data` method is only useful within [taxonomy](g) and [term](g) templates. - -Themes that are not actively maintained may still use `.Data.Pages` in list templates. Although that syntax remains functional, use one of these methods instead: [`Pages`], [`RegularPages`], or [`RegularPagesRecursive`] - -[`Pages`]: /methods/page/pages/ -[`RegularPages`]: /methods/page/regularpages/ -[`RegularPagesRecursive`]: /methods/page/regularpagesrecursive/ -{{% /note %}} +> [!note] +> The `Data` method is only useful within [taxonomy](g) and [term](g) templates. +> +> Themes that are not actively maintained may still use `.Data.Pages` in list 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: @@ -67,11 +61,8 @@ Terms {{ $taxonomyObject := .Data.Terms }} ``` -{{% note %}} -Once you have captured the `Taxonomy` object, use any of the [taxonomy methods] to sort, count, or capture a subset of its weighted pages. - -[taxonomy methods]: /methods/taxonomy/ -{{% /note %}} +> [!note] +> Once you have captured the `Taxonomy` object, use any of the [taxonomy methods] to sort, count, or capture a subset of its weighted pages. Learn more about [taxonomy templates]. @@ -102,5 +93,9 @@ Term Learn more about [term templates]. +[`Pages`]: /methods/page/pages/ +[`RegularPages`]: /methods/page/regularpages/ +[`RegularPagesRecursive`]: /methods/page/regularpagesrecursive/ +[taxonomy methods]: /methods/taxonomy/ [taxonomy templates]: /templates/types/#taxonomy [term templates]: /templates/types/#term diff --git a/content/en/methods/page/Date.md b/content/en/methods/page/Date.md index 113d6ca09..b6c2042c2 100644 --- a/content/en/methods/page/Date.md +++ b/content/en/methods/page/Date.md @@ -3,13 +3,10 @@ title: Date description: Returns the date of the given page. categories: [] keywords: [] -action: - related: - - methods/page/ExpiryDate - - methods/page/LastMod - - methods/page/PublishDate - returnType: time.Time - signatures: [PAGE.Date] +params: + functions_and_methods: + returnType: time.Time + signatures: [PAGE.Date] --- Set the date in front matter: @@ -19,11 +16,8 @@ title = 'Article 1' 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]. - -[details]: /getting-started/configuration/#configure-dates -{{% /note %}} +> [!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 is a [time.Time] value. Format and localize the value with the [`time.Format`] function, or use it with any of the [time methods]. @@ -34,6 +28,7 @@ The date is a [time.Time] value. Format and localize the value with the [`time.F In the example above we explicitly set the date in front matter. With Hugo's default configuration, the `Date` method returns the front matter value. This behavior is configurable, allowing you to set fallback values if the date is not defined in front matter. See [details]. [`time.Format`]: /functions/time/format/ -[details]: /getting-started/configuration/#configure-dates +[details]: /configuration/front-matter/#dates +[details]: /configuration/front-matter/#dates [time methods]: /methods/time/ [time.Time]: https://pkg.go.dev/time#Time diff --git a/content/en/methods/page/Description.md b/content/en/methods/page/Description.md index 67171fe01..5287aa699 100644 --- a/content/en/methods/page/Description.md +++ b/content/en/methods/page/Description.md @@ -3,11 +3,10 @@ title: Description description: Returns the description of the given page as defined in front matter. categories: [] keywords: [] -action: - related: - - methods/page/Summary - returnType: string - signatures: [PAGE.Description] +params: + functions_and_methods: + returnType: string + signatures: [PAGE.Description] --- Conceptually different from a [content summary], a page description is typically used in metadata about the page. @@ -17,12 +16,12 @@ title = 'How to make spicy tuna hand rolls' description = 'Instructions for making spicy tuna hand rolls.' {{< /code-toggle >}} -{{< code file=layouts/baseof.html >}} +```go-html-template {file="layouts/_default/baseof.html"} ... ... -{{< /code >}} +``` [content summary]: /content-management/summaries/ diff --git a/content/en/methods/page/Draft.md b/content/en/methods/page/Draft.md index fd55a9bc9..482a370bf 100644 --- a/content/en/methods/page/Draft.md +++ b/content/en/methods/page/Draft.md @@ -3,10 +3,10 @@ title: Draft description: Reports whether the given page is a draft as defined in front matter. categories: [] keywords: [] -action: - related: [] - returnType: bool - signatures: [PAGE.Draft] +params: + functions_and_methods: + returnType: bool + 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. diff --git a/content/en/methods/page/Eq.md b/content/en/methods/page/Eq.md index 99a9fc50f..4947a4bfa 100644 --- a/content/en/methods/page/Eq.md +++ b/content/en/methods/page/Eq.md @@ -3,17 +3,17 @@ title: Eq description: Reports whether two Page objects are equal. categories: [] keywords: [] -action: - related: [] - returnType: bool - signatures: [PAGE1.Eq PAGE2] +params: + functions_and_methods: + returnType: bool + signatures: [PAGE1.Eq PAGE2] --- In this contrived example from a single template, we list all pages in the current section except for the current page. ```go-html-template {{ $currentPage := . }} -{{ range .CurrentSection.Pages }} +{{ range .CurrentSection.Pages }} {{ if not (.Eq $currentPage) }} {{ .LinkTitle }} {{ end }} diff --git a/content/en/methods/page/ExpiryDate.md b/content/en/methods/page/ExpiryDate.md index 9b95ebc65..a72155c33 100644 --- a/content/en/methods/page/ExpiryDate.md +++ b/content/en/methods/page/ExpiryDate.md @@ -1,15 +1,12 @@ --- title: ExpiryDate -description: Returns the expiry date of the given page. +description: Returns the expiry date of the given page. categories: [] keywords: [] -action: - related: - - methods/page/Date - - methods/page/LastMod - - methods/page/PublishDate - returnType: time.Time - signatures: [PAGE.ExpiryDate] +params: + functions_and_methods: + returnType: time.Time + signatures: [PAGE.ExpiryDate] --- By default, Hugo excludes expired pages when building your site. To include expired pages, use the `--buildExpired` command line flag. @@ -30,6 +27,6 @@ The expiry date is a [time.Time] value. Format and localize the value with the [ In the example above we explicitly set the expiry date in front matter. With Hugo's default configuration, the `ExpiryDate` method returns the front matter value. This behavior is configurable, allowing you to set fallback values if the expiry date is not defined in front matter. See [details]. [`time.Format`]: /functions/time/format/ -[details]: /getting-started/configuration/#configure-dates +[details]: /configuration/front-matter/#dates [time methods]: /methods/time/ [time.Time]: https://pkg.go.dev/time#Time diff --git a/content/en/methods/page/File.md b/content/en/methods/page/File.md index 359c1ad2e..2af60a719 100644 --- a/content/en/methods/page/File.md +++ b/content/en/methods/page/File.md @@ -3,36 +3,33 @@ title: File description: For pages backed by a file, returns file information for the given page. categories: [] keywords: [] -action: - related: [] - returnType: hugolib.fileInfo - signatures: [PAGE.File] -toc: true +params: + functions_and_methods: + returnType: hugolib.fileInfo + signatures: [PAGE.File] --- -By default, not all pages are backed by a file, including top level [section pages](g), [taxonomy pages](g), and [term pages](g). By definition, you cannot retrieve file information when the file does not exist. +By default, not all pages are backed by a file, including top-level [section pages](g), [taxonomy pages](g), and [term pages](g). By definition, you cannot retrieve file information when the file does not exist. To back one of the pages above with a file, create an `_index.md` file in the corresponding directory. For example: ```text content/ └── books/ - ├── _index.md <-- the top level section page + ├── _index.md <-- the top-slevel section page ├── book-1.md └── book-2.md ``` -{{% note %}} -Code defensively by verifying file existence as shown in the examples below. -{{% /note %}} +> [!note] +> Code defensively by verifying file existence as shown in the examples below. ## Methods -{{% note %}} -The path separators (slash or backslash) in `Path`, `Dir`, and `Filename` depend on the operating system. -{{% /note %}} +> [!note] +> The path separators (slash or backslash) in `Path`, `Dir`, and `Filename` depend on the operating system. -###### BaseFileName +### BaseFileName (`string`) The file name, excluding the extension. @@ -42,7 +39,7 @@ The path separators (slash or backslash) in `Path`, `Dir`, and `Filename` depend {{ end }} ``` -###### ContentBaseName +### ContentBaseName (`string`) If the page is a branch or leaf bundle, the name of the containing directory, else the `TranslationBaseName`. @@ -52,7 +49,7 @@ The path separators (slash or backslash) in `Path`, `Dir`, and `Filename` depend {{ end }} ``` -###### Dir +### Dir (`string`) The file path, excluding the file name, relative to the `content` directory. @@ -62,7 +59,7 @@ The path separators (slash or backslash) in `Path`, `Dir`, and `Filename` depend {{ end }} ``` -###### Ext +### Ext (`string`) The file extension. @@ -72,7 +69,7 @@ The path separators (slash or backslash) in `Path`, `Dir`, and `Filename` depend {{ end }} ``` -###### Filename +### Filename (`string`) The absolute file path. @@ -82,21 +79,19 @@ The path separators (slash or backslash) in `Path`, `Dir`, and `Filename` depend {{ end }} ``` -###### IsContentAdapter +### IsContentAdapter {{< new-in 0.126.0 />}} (`bool`) Reports whether the file is a [content adapter]. -[content adapter]: /content-management/content-adapters/ - ```go-html-template {{ with .File }} {{ .IsContentAdapter }} {{ end }} ``` -###### LogicalName +### LogicalName (`string`) The file name. @@ -106,7 +101,7 @@ The path separators (slash or backslash) in `Path`, `Dir`, and `Filename` depend {{ end }} ``` -###### Path +### Path (`string`) The file path, relative to the `content` directory. @@ -116,9 +111,9 @@ The path separators (slash or backslash) in `Path`, `Dir`, and `Filename` depend {{ end }} ``` -###### Section +### Section -(`string`) The name of the top level section in which the file resides. +(`string`) The name of the top-level section in which the file resides. ```go-html-template {{ with .File }} @@ -126,7 +121,7 @@ The path separators (slash or backslash) in `Path`, `Dir`, and `Filename` depend {{ end }} ``` -###### TranslationBaseName +### TranslationBaseName (`string`) The file name, excluding the extension and language identifier. @@ -136,7 +131,7 @@ The path separators (slash or backslash) in `Path`, `Dir`, and `Filename` depend {{ end }} ``` -###### UniqueID +### UniqueID (`string`) The MD5 hash of `.File.Path`. @@ -184,7 +179,7 @@ UniqueID|15be14b...|186868f...|7d9159d... Some of the pages on a site may not be backed by a file. For example: -- Top level section pages +- Top-level section pages - Taxonomy pages - Term pages @@ -195,3 +190,5 @@ Without a backing file, Hugo will throw an error if you attempt to access a `.Fi {{ .ContentBaseName }} {{ end }} ``` + +[content adapter]: /content-management/content-adapters/ diff --git a/content/en/methods/page/FirstSection.md b/content/en/methods/page/FirstSection.md index 29fbdc841..73ddd2d7b 100644 --- a/content/en/methods/page/FirstSection.md +++ b/content/en/methods/page/FirstSection.md @@ -1,26 +1,18 @@ --- title: FirstSection -description: Returns the Page object of the top level section of which the given page is a descendant. +description: Returns the Page object of the top-level section of which the given page is a descendant. categories: [] keywords: [] -action: - related: - - methods/page/Ancestors - - methods/page/CurrentSection - - methods/page/InSection - - methods/page/IsAncestor - - methods/page/IsDescendant - - methods/page/Parent - - methods/page/Sections - returnType: page.Page - signatures: [PAGE.FirstSection] +params: + functions_and_methods: + returnType: page.Page + signatures: [PAGE.FirstSection] --- {{% glossary-term section %}} -{{% note %}} -When called on the home page, the `FirstSection` method returns the `Page` object of the home page itself. -{{% /note %}} +> [!note] +> When called on the home page, the `FirstSection` method returns the `Page` object of the home page itself. Consider this content structure: @@ -49,7 +41,7 @@ content/ └── _index.md <-- first section: home ``` -To link to the top level section of which the current page is a descendant: +To link to the top-level section of which the current page is a descendant: ```go-html-template {{ .FirstSection.LinkTitle }} diff --git a/content/en/methods/page/Fragments.md b/content/en/methods/page/Fragments.md index 581cbf7c3..2c0460def 100644 --- a/content/en/methods/page/Fragments.md +++ b/content/en/methods/page/Fragments.md @@ -3,12 +3,10 @@ title: Fragments description: Returns a data structure of the fragments in the given page. categories: [] keywords: [] -action: - related: - - methods/page/TableOfContents - returnType: tableofcontents.Fragments - signatures: [PAGE.Fragments] -toc: true +params: + functions_and_methods: + returnType: tableofcontents.Fragments + signatures: [PAGE.Fragments] --- In a URL, whether absolute or relative, the [fragment](g) links to an `id` attribute of an HTML element on the page. @@ -25,43 +23,53 @@ Use the `Fragments` method on a `Page` object to create a table of contents with ## Methods -Headings -: (`slice`) A slice of maps of all headings on the page, with first-level keys for each heading. Each map contains the following keys: `ID`, `Level`, `Title` and `Headings`. To inspect the data structure: +### Headings + +(`slice`) A slice of maps of all headings on the page, with first-level keys for each heading. Each map contains the following keys: `ID`, `Level`, `Title` and `Headings`. To inspect the data structure: ```go-html-template 
{{ debug.Dump .Fragments.Headings }}
``` -HeadingsMap -: (`map`) A nested map of all headings on the page. Each map contains the following keys: `ID`, `Level`, `Title` and `Headings`. To inspect the data structure: +### HeadingsMap + +(`map`) A nested map of all headings on the page. Each map contains the following keys: `ID`, `Level`, `Title` and `Headings`. To inspect the data structure: ```go-html-template 
{{ debug.Dump .Fragments.HeadingsMap }}
``` -Identifiers -: (`slice`) A slice containing the `id` of each heading on the page. To inspect the data structure: +### Identifiers + +(`slice`) A slice containing the `id` attribute of each heading on the page. If so configured, will also contain the `id` attribute of each description term (i.e., `dt` element) on the page. + +See [configure Markup](/configuration/markup/#parserautodefinitiontermid). + +To inspect the data structure: ```go-html-template 
{{ debug.Dump .Fragments.Identifiers }}
``` -Identifiers.Contains ID -: (`bool`) Reports whether one or more headings on the page has the given `id` attribute, useful for validating fragments within a link [render hook](g). +### Identifiers.Contains ID + +(`bool`) Reports whether one or more headings on the page has the given `id` attribute, useful for validating fragments within a link [render hook](g). ```go-html-template {{ .Fragments.Identifiers.Contains "section-2" }} → true ``` -Identifiers.Count ID -: (`int`) The number of headings on a page with the given `id` attribute, useful for detecting duplicates. +### Identifiers.Count ID + +(`int`) The number of headings on a page with the given `id` attribute, useful for detecting duplicates. ```go-html-template {{ .Fragments.Identifiers.Count "section-2" }} → 1 ``` -ToHTML -: (`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). +### ToHTML + +(`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. @@ -88,13 +96,14 @@ Hugo renders this to: ``` -{{% note %}} -It is safe to use the `Fragments` methods within a render hook, even for the current page. +> [!note] +> It is safe to use the `Fragments` methods within a render hook, even for the current page. +> +> When using the `Fragments` methods within a shortcode, call the shortcode using [standard notation]. If you use [Markdown notation] the rendered shortcode is included in the creation of the fragments map, resulting in a circular loop. -When using the `Fragments` methods within a shortcode, call the shortcode using the `{{}}` notation. If you use the `{{%/* */%}}` notation, the rendered shortcode is included in the creation of the fragments map, resulting in a circular loop. -{{% /note %}} - -[atx]: https://spec.commonmark.org/0.30/#atx-headings +[`TableOfContents`]: /methods/page/tableofcontents/ +[ATX]: https://spec.commonmark.org/0.30/#atx-headings +[Markdown notation]: /content-management/shortcodes/#notation [setext]: https://spec.commonmark.org/0.30/#setext-headings +[standard notation]: /content-management/shortcodes/#notation [table of contents]: /methods/page/tableofcontents/ -[`tableofcontents`]: /methods/page/tableofcontents/ diff --git a/content/en/methods/page/FuzzyWordCount.md b/content/en/methods/page/FuzzyWordCount.md index 8523edf8c..815a07402 100644 --- a/content/en/methods/page/FuzzyWordCount.md +++ b/content/en/methods/page/FuzzyWordCount.md @@ -1,14 +1,12 @@ --- title: FuzzyWordCount -description: Returns the number of words in the content of the given page, rounded up to the nearest multiple of 100. +description: Returns the number of words in the content of the given page, rounded up to the nearest multiple of 100. categories: [] keywords: [] -action: - related: - - methods/page/WordCount - - methods/page/ReadingTime - returnType: int - signatures: [PAGE.FuzzyWordCount] +params: + functions_and_methods: + returnType: int + signatures: [PAGE.FuzzyWordCount] --- ```go-html-template diff --git a/content/en/methods/page/GetPage.md b/content/en/methods/page/GetPage.md index 7c71c5afa..02f6888e0 100644 --- a/content/en/methods/page/GetPage.md +++ b/content/en/methods/page/GetPage.md @@ -1,13 +1,12 @@ --- title: GetPage -description: Returns a Page object from the given path. +description: Returns a Page object from the given path. categories: [] keywords: [] -action: - related: - - methods/site/GetPage - returnType: page.Page - signatures: [PAGE.GetPage PATH] +params: + functions_and_methods: + returnType: page.Page + signatures: [PAGE.GetPage PATH] aliases: [/functions/getpage] --- @@ -38,7 +37,7 @@ content/ The examples below depict the result of rendering works/paintings/the-mona-lisa.md: -{{< code file=layouts/works/single.html >}} +```go-html-template {file="layouts/works/single.html"} {{ with .GetPage "starry-night" }} {{ .Title }} → Starry Night {{ end }} @@ -62,4 +61,4 @@ The examples below depict the result of rendering works/paintings/the-mona-lisa. {{ with .GetPage "/works/sculptures/david" }} {{ .Title }} → David {{ end }} -{{< /code >}} +``` diff --git a/content/en/methods/page/GetTerms.md b/content/en/methods/page/GetTerms.md index 3020e4c2e..53b996fc5 100644 --- a/content/en/methods/page/GetTerms.md +++ b/content/en/methods/page/GetTerms.md @@ -3,10 +3,10 @@ title: GetTerms description: Returns a collection of term pages for terms defined on the given page in the given taxonomy, ordered according to the sequence in which they appear in front matter. categories: [] keywords: [] -action: - related: [] - returnType: page.Pages - signatures: [PAGE.GetTerms TAXONOMY] +params: + functions_and_methods: + returnType: page.Pages + signatures: [PAGE.GetTerms TAXONOMY] --- Given this front matter: diff --git a/content/en/methods/page/GitInfo.md b/content/en/methods/page/GitInfo.md index a05916d79..5fde05b07 100644 --- a/content/en/methods/page/GitInfo.md +++ b/content/en/methods/page/GitInfo.md @@ -3,19 +3,16 @@ title: GitInfo description: Returns Git information related to the last commit of the given page. categories: [] keywords: [] -action: - related: - - methods/page/CodeOwners - returnType: source.GitInfo - signatures: [PAGE.GitInfo] -toc: true +params: + functions_and_methods: + returnType: source.GitInfo + signatures: [PAGE.GitInfo] --- The `GitInfo` method on a `Page` object returns an object with additional methods. -{{% note %}} -Hugo's Git integration is performant, but may increase build times on large sites. -{{% /note %}} +> [!note] +> Hugo's Git integration is performant, but may increase build times on large sites. ## Prerequisites @@ -33,17 +30,14 @@ Alternatively, use the command line flag when building your site: hugo --enableGitInfo ``` -{{% note %}} -When you set `enableGitInfo` to `true`, or enable the feature with the command line flag, the last modification date for each content page will be the Author Date of the last commit for that file. - -This is configurable. See [details]. - -[details]: /getting-started/configuration/#configure-dates -{{% /note %}} +> [!note] +> When you set `enableGitInfo` to `true`, or enable the feature with the command line flag, the last modification date for each content page will be the Author Date of the last commit for that file. +> +> This is configurable. See [details]. ## Methods -###### AbbreviatedHash +### AbbreviatedHash (`string`) The abbreviated commit hash. @@ -53,7 +47,7 @@ This is configurable. See [details]. {{ end }} ``` -###### AuthorDate +### AuthorDate (`time.Time`) The author date. @@ -63,7 +57,7 @@ This is configurable. See [details]. {{ end }} ``` -###### AuthorEmail +### AuthorEmail (`string`) The author's email address, respecting [gitmailmap]. @@ -73,7 +67,7 @@ This is configurable. See [details]. {{ end }} ``` -###### AuthorName +### AuthorName (`string`) The author's name, respecting [gitmailmap]. @@ -83,7 +77,7 @@ This is configurable. See [details]. {{ end }} ``` -###### CommitDate +### CommitDate (`time.Time`) The commit date. @@ -93,7 +87,7 @@ This is configurable. See [details]. {{ end }} ``` -###### Hash +### Hash (`string`) The commit hash. @@ -103,7 +97,7 @@ This is configurable. See [details]. {{ end }} ``` -###### Subject +### Subject (`string`) The commit message subject. @@ -113,7 +107,7 @@ This is configurable. See [details]. {{ end }} ``` -###### Body +### Body (`string`) The commit message body. @@ -129,29 +123,29 @@ By default, when `enableGitInfo` is `true`, the `Lastmod` method on a `Page` obj You can change this behavior in your [site configuration]. -[git]: https://git-scm.com/book/en/v2/Getting-Started-Installing-Git -[gitmailmap]: https://git-scm.com/docs/gitmailmap -[site configuration]: /getting-started/configuration/#configure-front-matter - ## Hosting considerations -When hosting your site in a CI/CD environment, the step that clones your project repository must perform a deep clone. If the clone is shallow, the Git information for a given file may not be accurate---it may reflect the most recent repository commit, not the commit that last modified the file. +When hosting your site in a [CI/CD](g) environment, the step that clones your project repository must perform a deep clone. If the clone is shallow, the Git information for a given file may not be accurate---it may reflect the most recent repository commit, not the commit that last modified the file. -Some providers perform deep clones by default, others allow you to configure the clone depth, and some providers only perform shallow clones. +Some providers perform deep clones by default, others allow you to configure the clone depth, and some only perform shallow clones. Hosting service | Default clone depth | Configurable :-- | :-- | :-- AWS Amplify | Deep | N/A -Cloudflare Pages | Shallow | Yes [^CFP] +Cloudflare Pages | Shallow | Yes [^1] DigitalOcean App Platform | Deep | N/A -GitHub Pages | Shallow | Yes [^GHP] -GitLab Pages | Shallow | Yes [^GLP] +GitHub Pages | Shallow | Yes [^2] +GitLab Pages | Shallow | Yes [^3] Netlify | Deep | N/A Render | Shallow | No Vercel | Shallow | No -[^CFP]: To configure a Cloudflare Pages site for deep cloning, preface the site's normal Hugo build command with `git fetch --unshallow &&` (*e.g.*, `git fetch --unshallow && hugo`). +[^1]: To configure a Cloudflare Pages site for deep cloning, run `git fetch --unshallow` before building the site. -[^GHP]: You can configure the GitHub Action to do a deep clone by specifying `fetch-depth: 0` in the applicable "checkout" step of your workflow file, as shown in the Hugo documentation's [example workflow file](/hosting-and-deployment/hosting-on-github/#procedure). +[^2]: You can configure the GitHub Action to do a deep clone by specifying `fetch-depth: 0` in the applicable "checkout" step of your workflow file, as shown in the Hugo documentation's [example workflow file](/host-and-deploy/host-on-github-pages/#procedure). -[^GLP]: You can configure the GitLab Runner's clone depth [as explained in the GitLab documentation](https://docs.gitlab.com/ee/ci/large_repositories/#shallow-cloning); see also the Hugo documentation's [example workflow file](/hosting-and-deployment/hosting-on-gitlab/#configure-gitlab-cicd). +[^3]: You can configure the GitLab Runner's clone depth [as explained in the GitLab documentation](https://docs.gitlab.com/ee/ci/large_repositories/#shallow-cloning); see also the Hugo documentation's [example workflow file](/host-and-deploy/host-on-gitlab-pages/#configure-gitlab-cicd). + +[details]: /configuration/front-matter/#dates +[gitmailmap]: https://git-scm.com/docs/gitmailmap +[site configuration]: /configuration/front-matter/ diff --git a/content/en/methods/page/HasMenuCurrent.md b/content/en/methods/page/HasMenuCurrent.md index 24ce462c9..207882167 100644 --- a/content/en/methods/page/HasMenuCurrent.md +++ b/content/en/methods/page/HasMenuCurrent.md @@ -3,11 +3,10 @@ title: HasMenuCurrent description: Reports whether the given Page object matches the Page object associated with one of the child menu entries under the given menu entry in the given menu. categories: [] keywords: [] -action: - related: - - methods/page/IsMenuCurrent - returnType: bool - signatures: [PAGE.HasMenuCurrent MENU MENUENTRY] +params: + functions_and_methods: + returnType: bool + signatures: [PAGE.HasMenuCurrent MENU MENUENTRY] aliases: [/functions/hasmenucurrent] --- @@ -28,8 +27,7 @@ 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. -{{% /note %}} +> [!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. [menu templates]: /templates/menu/#example diff --git a/content/en/methods/page/HasShortcode.md b/content/en/methods/page/HasShortcode.md index 2846e9535..616b6de09 100644 --- a/content/en/methods/page/HasShortcode.md +++ b/content/en/methods/page/HasShortcode.md @@ -3,17 +3,17 @@ title: HasShortcode description: Reports whether the given shortcode is called by the given page. categories: [] keywords: [] -action: - related: [] - returnType: bool - signatures: [PAGE.HasShortcode NAME] +params: + functions_and_methods: + returnType: bool + signatures: [PAGE.HasShortcode NAME] --- By example, let's use [Plotly] to render a chart: [Plotly]: https://plotly.com/javascript/ -{{< code file=contents/example.md lang=markdown >}} +```text {file="content/example.md"} {{}} { "data": [ @@ -25,21 +25,21 @@ By example, let's use [Plotly] to render a chart: ], } {{}} -{{< /code >}} +``` The shortcode is simple: -{{< code file=layouts/shortcodes/plotly.html >}} +```go-html-template {file="layouts/shortcodes/plotly.html"} {{ $id := printf "plotly-%02d" .Ordinal }}
-{{< /code >}} +``` Now we can selectively load the required JavaScript on pages that call the "plotly" shortcode: -{{< code file=layouts/baseof.html >}} +```go-html-template {file="layouts/_default/baseof.html"} ... {{ if .HasShortcode "plotly" }} @@ -47,4 +47,4 @@ Now we can selectively load the required JavaScript on pages that call the "plot {{ end }} ... -{{< /code >}} +``` diff --git a/content/en/methods/page/HeadingsFiltered.md b/content/en/methods/page/HeadingsFiltered.md index d741b57ce..86c989d43 100644 --- a/content/en/methods/page/HeadingsFiltered.md +++ b/content/en/methods/page/HeadingsFiltered.md @@ -3,16 +3,14 @@ title: HeadingsFiltered description: Returns a slice of headings for each page related to the given page. categories: [] keywords: [] -action: - related: - - methods/pages/Related - - methods/page/Fragments - returnType: tableofcontents.Headings - signatures: [PAGE.HeadingsFiltered] +params: + functions_and_methods: + returnType: tableofcontents.Headings + signatures: [PAGE.HeadingsFiltered] --- Use in conjunction with the [`Related`] method on a [`Pages`] object. See [details]. [`Pages`]: /methods/pages/ [`Related`]: /methods/pages/related/ -[details]: /content-management/related/#index-content-headings-in-related-content +[details]: /content-management/related-content/#index-content-headings diff --git a/content/en/methods/page/InSection.md b/content/en/methods/page/InSection.md index 904f6ce75..adca82d86 100644 --- a/content/en/methods/page/InSection.md +++ b/content/en/methods/page/InSection.md @@ -3,24 +3,16 @@ title: InSection description: Reports whether the given page is in the given section. categories: [] keywords: [] -action: - related: - - methods/page/Ancestors - - methods/page/CurrentSection - - methods/page/FirstSection - - methods/page/IsAncestor - - methods/page/IsDescendant - - methods/page/Parent - - methods/page/Sections - returnType: bool - signatures: [PAGE.InSection SECTION] -toc: true +params: + functions_and_methods: + returnType: bool + signatures: [PAGE.InSection SECTION] --- -The `InSection` method on a `Page` object reports whether the given page is in the given section. Note that the method returns `true` when comparing a page to a sibling. - {{% glossary-term section %}} +The `InSection` method on a `Page` object reports whether the given page is in the given section. Note that the method returns `true` when comparing a page to a sibling. + With this content structure: ```text @@ -83,9 +75,8 @@ Inside of the `with` block, the [context](g) (the dot) is the section `Page` obj The result would be wrong when rendering the "auction-1" page because we are comparing the section page to itself. -{{% note %}} -Use the `$` to get the context passed into the template. -{{% /note %}} +> [!note] +> Use the `$` to get the context passed into the template. ```go-html-template {{ with .Site.GetPage "/auctions" }} @@ -93,9 +84,8 @@ Use the `$` to get the context passed into the template. {{ end }} ``` -{{% note %}} -Gaining a thorough understanding of context is critical for anyone writing template code. -{{% /note %}} +> [!note] +> Gaining a thorough understanding of context is critical for anyone writing template code. -[`with`]: /functions/go-template/with/ [`else`]: /functions/go-template/else/ +[`with`]: /functions/go-template/with/ diff --git a/content/en/methods/page/IsAncestor.md b/content/en/methods/page/IsAncestor.md index 2613a2875..fe1b78454 100644 --- a/content/en/methods/page/IsAncestor.md +++ b/content/en/methods/page/IsAncestor.md @@ -3,22 +3,12 @@ title: IsAncestor description: Reports whether PAGE1 is an ancestor of PAGE2. categories: [] keywords: [] -action: - related: - - methods/page/Ancestors - - methods/page/CurrentSection - - methods/page/FirstSection - - methods/page/InSection - - methods/page/IsDescendant - - methods/page/Parent - - methods/page/Sections - returnType: bool - signatures: [PAGE1.IsAncestor PAGE2] -toc: true +params: + functions_and_methods: + returnType: bool + signatures: [PAGE1.IsAncestor PAGE2] --- -{{% glossary-term section %}} - With this content structure: ```text @@ -81,9 +71,8 @@ Inside of the `with` block, the [context](g) (the dot) is the section `Page` obj The result would be wrong when rendering the "auction-1" page because we are comparing the section page to itself. -{{% note %}} -Use the `$` to get the context passed into the template. -{{% /note %}} +> [!note] +> Use the `$` to get the context passed into the template. ```go-html-template {{ with .Site.GetPage "/auctions" }} @@ -91,9 +80,8 @@ Use the `$` to get the context passed into the template. {{ end }} ``` -{{% note %}} -Gaining a thorough understanding of context is critical for anyone writing template code. -{{% /note %}} +> [!note] +> Gaining a thorough understanding of context is critical for anyone writing template code. -[`with`]: /functions/go-template/with/ [`else`]: /functions/go-template/else/ +[`with`]: /functions/go-template/with/ diff --git a/content/en/methods/page/IsDescendant.md b/content/en/methods/page/IsDescendant.md index 4ef7c6598..6ee8d3c4f 100644 --- a/content/en/methods/page/IsDescendant.md +++ b/content/en/methods/page/IsDescendant.md @@ -3,21 +3,12 @@ title: IsDescendant description: Reports whether PAGE1 is a descendant of PAGE2. categories: [] keywords: [] -action: - related: - - methods/page/Ancestors - - methods/page/CurrentSection - - methods/page/FirstSection - - methods/page/InSection - - methods/page/IsAncestor - - methods/page/Parent - - methods/page/Sections - returnType: bool - signatures: [PAGE1.IsDescendant PAGE2] +params: + functions_and_methods: + returnType: bool + signatures: [PAGE1.IsDescendant PAGE2] --- -{{% glossary-term section %}} - With this content structure: ```text @@ -80,9 +71,8 @@ Inside of the `with` block, the [context](g) (the dot) is the section `Page` obj The result would be wrong when rendering the "auction-1" page because we are comparing the section page to itself. -{{% note %}} -Use the `$` to get the context passed into the template. -{{% /note %}} +> [!note] +> Use the `$` to get the context passed into the template. ```go-html-template {{ with .Site.GetPage "/auctions" }} @@ -90,9 +80,8 @@ Use the `$` to get the context passed into the template. {{ end }} ``` -{{% note %}} -Gaining a thorough understanding of context is critical for anyone writing template code. -{{% /note %}} +> [!note] +> Gaining a thorough understanding of context is critical for anyone writing template code. -[`with`]: /functions/go-template/with/ [`else`]: /functions/go-template/else/ +[`with`]: /functions/go-template/with/ diff --git a/content/en/methods/page/IsHome.md b/content/en/methods/page/IsHome.md index 16b04034f..66d8180b0 100644 --- a/content/en/methods/page/IsHome.md +++ b/content/en/methods/page/IsHome.md @@ -3,13 +3,10 @@ title: IsHome description: Reports whether the given page is the home page. categories: [] keywords: [] -action: - related: - - methods/page/IsNode - - methods/page/IsPage - - methods/page/IsSection - returnType: bool - signatures: [PAGE.IsHome] +params: + functions_and_methods: + returnType: bool + signatures: [PAGE.IsHome] --- The `IsHome` method on a `Page` object returns `true` if the [page kind](g) is `home`. diff --git a/content/en/methods/page/IsMenuCurrent.md b/content/en/methods/page/IsMenuCurrent.md index a16be51ee..9bbacd018 100644 --- a/content/en/methods/page/IsMenuCurrent.md +++ b/content/en/methods/page/IsMenuCurrent.md @@ -3,11 +3,10 @@ title: IsMenuCurrent description: Reports whether the given Page object matches the Page object associated with the given menu entry in the given menu. categories: [] keywords: [] -action: - related: - - methods/page/HasMenuCurrent - returnType: bool - signatures: [PAGE.IsMenuCurrent MENU MENUENTRY] +params: + functions_and_methods: + returnType: bool + signatures: [PAGE.IsMenuCurrent MENU MENUENTRY] aliases: [/functions/ismenucurrent] --- @@ -26,8 +25,7 @@ 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. -{{% /note %}} +> [!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. [menu templates]: /templates/menu/#example diff --git a/content/en/methods/page/IsNode.md b/content/en/methods/page/IsNode.md index 5335ef376..194a2cac8 100644 --- a/content/en/methods/page/IsNode.md +++ b/content/en/methods/page/IsNode.md @@ -3,13 +3,10 @@ title: IsNode description: Reports whether the given page is a node. categories: [] keywords: [] -action: - related: - - methods/page/IsHome - - methods/page/IsPage - - methods/page/IsSection - returnType: bool - signatures: [PAGE.IsNode] +params: + functions_and_methods: + returnType: bool + signatures: [PAGE.IsNode] --- The `IsNode` method on a `Page` object returns `true` if the [page kind](g) is `home`, `section`, `taxonomy`, or `term`. diff --git a/content/en/methods/page/IsPage.md b/content/en/methods/page/IsPage.md index 92e6101d9..910a3a7e1 100644 --- a/content/en/methods/page/IsPage.md +++ b/content/en/methods/page/IsPage.md @@ -3,13 +3,10 @@ title: IsPage description: Reports whether the given page is a regular page. categories: [] keywords: [] -action: - related: - - methods/page/IsHome - - methods/page/IsNode - - methods/page/IsSection - returnType: bool - signatures: [PAGE.IsPage] +params: + functions_and_methods: + returnType: bool + signatures: [PAGE.IsPage] --- The `IsPage` method on a `Page` object returns `true` if the [page kind](g) is `page`. diff --git a/content/en/methods/page/IsSection.md b/content/en/methods/page/IsSection.md index 965e466cd..7a04fbd8f 100644 --- a/content/en/methods/page/IsSection.md +++ b/content/en/methods/page/IsSection.md @@ -3,13 +3,10 @@ title: IsSection description: Reports whether the given page is a section page. categories: [] keywords: [] -action: - related: - - methods/page/IsHome - - methods/page/IsNode - - methods/page/IsPage - returnType: bool - signatures: [PAGE.IsSection] +params: + functions_and_methods: + returnType: bool + signatures: [PAGE.IsSection] --- The `IsSection` method on a `Page` object returns `true` if the [page kind](g) is `section`. diff --git a/content/en/methods/page/IsTranslated.md b/content/en/methods/page/IsTranslated.md index 47019a52c..2cdf911ac 100644 --- a/content/en/methods/page/IsTranslated.md +++ b/content/en/methods/page/IsTranslated.md @@ -3,13 +3,10 @@ title: IsTranslated description: Reports whether the given page has one or more translations. categories: [] keywords: [] -action: - related: - - methods/page/Translations - - methods/page/AllTranslations - - methods/page/TranslationKey - returnType: bool - signatures: [PAGE.IsTranslated] +params: + functions_and_methods: + returnType: bool + signatures: [PAGE.IsTranslated] --- With this site configuration: diff --git a/content/en/methods/page/Keywords.md b/content/en/methods/page/Keywords.md index ef68c27f5..7c940984e 100644 --- a/content/en/methods/page/Keywords.md +++ b/content/en/methods/page/Keywords.md @@ -3,15 +3,15 @@ title: Keywords description: Returns a slice of keywords as defined in front matter. categories: [] keywords: [] -action: - related: [] - returnType: '[]string' - signatures: [PAGE.Keywords] +params: + functions_and_methods: + returnType: '[]string' + signatures: [PAGE.Keywords] --- By default, Hugo evaluates the keywords when creating collections of [related content]. -[related content]: /content-management/related/ +[related content]: /content-management/related-content/ {{< code-toggle file=content/recipes/sushi.md fm=true >}} title = 'How to make spicy tuna hand rolls' diff --git a/content/en/methods/page/Kind.md b/content/en/methods/page/Kind.md index c5b0c6b9d..a01877e8c 100644 --- a/content/en/methods/page/Kind.md +++ b/content/en/methods/page/Kind.md @@ -3,11 +3,10 @@ title: Kind description: Returns the kind of the given page. categories: [] keywords: [] -action: - related: - - methods/page/Type - returnType: string - signatures: [PAGE.Kind] +params: + functions_and_methods: + returnType: string + signatures: [PAGE.Kind] --- The [page kind](g) is one of `home`, `page`, `section`, `taxonomy`, or `term`. diff --git a/content/en/methods/page/Language.md b/content/en/methods/page/Language.md index e12fc2e62..9fd604df3 100644 --- a/content/en/methods/page/Language.md +++ b/content/en/methods/page/Language.md @@ -3,11 +3,10 @@ title: Language description: Returns the language object for the given page. categories: [] keywords: [] -action: - related: - - methods/site/Language - returnType: langs.Language - signatures: [PAGE.Language] +params: + functions_and_methods: + returnType: langs.Language + signatures: [PAGE.Language] --- The `Language` method on a `Page` object returns the language object for the given page. The language object points to the language definition in the site configuration. @@ -26,7 +25,7 @@ languageName = 'Deutsch' weight = 2 {{< /code-toggle >}} -###### Lang +### Lang (`string`) The language tag as defined by [RFC 5646]. @@ -34,7 +33,7 @@ weight = 2 {{ .Language.Lang }} → de ``` -###### LanguageCode +### LanguageCode (`string`) The language code from the site configuration. Falls back to `Lang` if not defined. @@ -42,7 +41,7 @@ weight = 2 {{ .Language.LanguageCode }} → de-DE ``` -###### LanguageDirection +### LanguageDirection (`string`) The language direction from the site configuration, either `ltr` or `rtl`. @@ -50,7 +49,7 @@ weight = 2 {{ .Language.LanguageDirection }} → ltr ``` -###### LanguageName +### LanguageName (`string`) The language name from the site configuration. @@ -58,7 +57,7 @@ weight = 2 {{ .Language.LanguageName }} → Deutsch ``` -###### Weight +### 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. diff --git a/content/en/methods/page/Lastmod.md b/content/en/methods/page/Lastmod.md index 78760d556..643eddc5e 100644 --- a/content/en/methods/page/Lastmod.md +++ b/content/en/methods/page/Lastmod.md @@ -1,16 +1,12 @@ --- title: Lastmod -description: Returns the last modification date of the given page. +description: Returns the last modification date of the given page. categories: [] keywords: [] -action: - related: - - methods/page/Date - - methods/page/ExpiryDate - - methods/page/PublishDate - - methods/page/GitInfo - returnType: time.Time - signatures: [PAGE.Lastmod] +params: + functions_and_methods: + returnType: time.Time + signatures: [PAGE.Lastmod] --- Set the last modification date in front matter: @@ -35,6 +31,6 @@ Learn more about [date configuration]. [`gitinfo`]: /methods/page/gitinfo/ [`time.format`]: /functions/time/format/ -[date configuration]: /getting-started/configuration/#configure-dates +[date configuration]: /configuration/front-matter/#dates [time methods]: /methods/time/ -[time.time]: https://pkg.go.dev/time#time +[time.time]: https://pkg.go.dev/time#Time diff --git a/content/en/methods/page/Layout.md b/content/en/methods/page/Layout.md index 3d0cdc437..f9aa5b6ab 100644 --- a/content/en/methods/page/Layout.md +++ b/content/en/methods/page/Layout.md @@ -3,18 +3,17 @@ title: Layout description: Returns the layout for the given page as defined in front matter. categories: [] keywords: [] -action: - related: - - methods/page/Type - returnType: string - signatures: [PAGE.Layout] +params: + functions_and_methods: + returnType: string + signatures: [PAGE.Layout] --- Specify the `layout` field in front matter to target a particular template. See [details]. [details]: /templates/lookup-order/#target-a-template -{{< code-toggle file=content/contact.md >}} +{{< code-toggle file=content/contact.md fm=true >}} title = 'Contact' layout = 'contact' {{< /code-toggle >}} diff --git a/content/en/methods/page/Len.md b/content/en/methods/page/Len.md index d4270bda3..010da88d1 100644 --- a/content/en/methods/page/Len.md +++ b/content/en/methods/page/Len.md @@ -3,11 +3,10 @@ title: Len description: Returns the length, in bytes, of the rendered content of the given page. categories: [] keywords: [] -action: - related: - - methods/page/Content - returnType: int - signatures: [PAGE.Len] +params: + functions_and_methods: + returnType: int + signatures: [PAGE.Len] --- ```go-html-template diff --git a/content/en/methods/page/LinkTitle.md b/content/en/methods/page/LinkTitle.md index 0ce32e641..fcfd5318d 100644 --- a/content/en/methods/page/LinkTitle.md +++ b/content/en/methods/page/LinkTitle.md @@ -3,11 +3,10 @@ title: LinkTitle description: Returns the link title of the given page. categories: [] keywords: [] -action: - related: - - methods/page/Title - returnType: string - signatures: [PAGE.LinkTitle] +params: + functions_and_methods: + returnType: string + signatures: [PAGE.LinkTitle] --- The `LinkTitle` method returns the `linkTitle` field as defined in front matter, falling back to the value returned by the [`Title`] method. diff --git a/content/en/methods/page/Next.md b/content/en/methods/page/Next.md index ff0525700..996603083 100644 --- a/content/en/methods/page/Next.md +++ b/content/en/methods/page/Next.md @@ -3,15 +3,10 @@ title: Next description: Returns the next page in a site's collection of regular pages, relative to the current page. categories: [] keywords: [] -action: - related: - - methods/page/Prev - - methods/page/NextInSection - - methods/page/PrevInSection - - methods/pages/Next - - methods/pages/Prev - returnType: page.Page - signatures: [PAGE.Next] +params: + functions_and_methods: + returnType: page.Page + signatures: [PAGE.Next] --- -{{% include "methods/page/_common/next-and-prev.md" %}} +{{% include "/_common/methods/page/next-and-prev.md" %}} diff --git a/content/en/methods/page/NextInSection.md b/content/en/methods/page/NextInSection.md index 640e9b44a..eb02c9492 100644 --- a/content/en/methods/page/NextInSection.md +++ b/content/en/methods/page/NextInSection.md @@ -1,15 +1,12 @@ --- title: NextInSection -description: Returns the next regular page in a section, relative to the given page. +description: Returns the next regular page in a section, relative to the given page. categories: [] keywords: [] -action: - related: - - methods/page/PrevInSection - - methods/pages/Next - - methods/pages/Prev - returnType: page.Page - signatures: [PAGE.NextInSection] +params: + functions_and_methods: + returnType: page.Page + signatures: [PAGE.NextInSection] --- -{{% include "methods/page/_common/nextinsection-and-previnsection.md" %}} +{{% include "/_common/methods/page/nextinsection-and-previnsection.md" %}} diff --git a/content/en/methods/page/OutputFormats.md b/content/en/methods/page/OutputFormats.md index a6d014a93..0e648efaa 100644 --- a/content/en/methods/page/OutputFormats.md +++ b/content/en/methods/page/OutputFormats.md @@ -3,28 +3,26 @@ title: OutputFormats description: Returns a slice of OutputFormat objects, each representing one of the output formats enabled for the given page. categories: [] keywords: [] -action: - related: - - methods/page/AlternativeOutputFormats - returnType: '[]OutputFormat' - signatures: [PAGE.OutputFormats] -toc: true +params: + functions_and_methods: + returnType: '[]OutputFormat' + signatures: [PAGE.OutputFormats] --- {{% glossary-term "output format" %}} -The `OutputFormats` method on a `Page` object returns a slice of `OutputFormat` objects, each representing one of the output formats enabled for the given page. See [details](/templates/output-formats/). +The `OutputFormats` method on a `Page` object returns a slice of `OutputFormat` objects, each representing one of the output formats enabled for the given page. See [details](/configuration/output-formats/). ## Methods -{{% include "methods/page/_common/output-format-methods.md" %}} +{{% include "/_common/methods/page/output-format-methods.md" %}} ## Example To link to the RSS feed for the current page: ```go-html-template -{{ with .OutputFormats.Get "rss" -}} +{{ with .OutputFormats.Get "rss" }} RSS Feed {{ end }} ``` @@ -37,4 +35,4 @@ On the site's home page, Hugo renders this to: Please see the [link to output formats] section to understand the importance of the construct above. -[link to output formats]: /templates/output-formats/#link-to-output-formats +[link to output formats]: /configuration/output-formats/#link-to-output-formats diff --git a/content/en/methods/page/Page.md b/content/en/methods/page/Page.md index 1d6867792..7c7728b2f 100644 --- a/content/en/methods/page/Page.md +++ b/content/en/methods/page/Page.md @@ -3,34 +3,33 @@ title: Page description: Returns the Page object of the given page. categories: [] keywords: [] -action: - related: [] - returnType: page.Page - signatures: [PAGE.Page] +params: + functions_and_methods: + returnType: page.Page + signatures: [PAGE.Page] --- This is a convenience method, useful within partial templates that are called from both [shortcodes](g) and page templates. -{{< code file=layouts/shortcodes/foo.html >}} +```go-html-template {file="layouts/shortcodes/foo.html"} {{ partial "my-partial.html" . }} -{{< /code >}} +``` When the shortcode calls the partial, it passes the current [context](g) (the dot). The context includes identifiers such as `Page`, `Params`, `Inner`, and `Name`. -{{< code file=layouts/_default/single.html >}} +```go-html-template {file="layouts/_default/single.html"} {{ partial "my-partial.html" . }} -{{< /code >}} +``` When the page template calls the partial, it also passes the current context (the dot). But in this case, the dot _is_ the `Page` object. -{{< code file=layouts/partials/my-partial.html >}} +```go-html-template {file="layouts/partials/my-partial.html"} The page title is: {{ .Page.Title }} -{{< /code >}} +``` To handle both scenarios, the partial template must be able to access the `Page` object with `Page.Page`. -{{% note %}} -And yes, that means you can do `.Page.Page.Page.Page.Title` too. - -But don't. -{{% /note %}} +> [!note] +> And yes, that means you can do `.Page.Page.Page.Page.Title` too. +> +> But don't. diff --git a/content/en/methods/page/Pages.md b/content/en/methods/page/Pages.md index 8efcde287..ba43c36a8 100644 --- a/content/en/methods/page/Pages.md +++ b/content/en/methods/page/Pages.md @@ -3,15 +3,13 @@ title: Pages description: Returns a collection of regular pages within the current section, and section pages of immediate descendant sections. categories: [] keywords: [] -action: - related: - - methods/page/RegularPages - - methods/page/RegularPagesRecursive - returnType: page.Pages - signatures: [PAGE.Pages] +params: + functions_and_methods: + returnType: page.Pages + signatures: [PAGE.Pages] --- -The `Pages` method on a `Page` object is available to these [page kinds](g): `home`, `section`, `taxonomy`, and `term`. The templates for these page kinds receive a page [collection](g) in [context](g). +The `Pages` method on a `Page` object is available to these [page kinds](g): `home`, `section`, `taxonomy`, and `term`. The templates for these page kinds receive a page [collection](g) in [context](g), in the [default sort order](g). Range through the page collection in your template: @@ -72,14 +70,13 @@ When rendering lesson-2, the `Pages` method returns: In the last example, the collection includes pages in the resources subdirectory. That directory is not a [section](g)---it does not contain an `_index.md` file. Its contents are part of the lesson-2 section. -{{% note %}} -When used with a `Site` object, the `Pages` method recursively returns all pages within the site. See [details]. - -[details]: /methods/site/pages/ -{{% /note %}} +> [!note] +> When used with a `Site` object, the `Pages` method recursively returns all pages within the site. See [details]. ```go-html-template {{ range .Site.Pages.ByTitle }}

{{ .Title }}

{{ end }} ``` + +[details]: /methods/site/pages/ diff --git a/content/en/methods/page/Paginate.md b/content/en/methods/page/Paginate.md index 9d98fbb2f..0b699d6b2 100644 --- a/content/en/methods/page/Paginate.md +++ b/content/en/methods/page/Paginate.md @@ -3,40 +3,31 @@ title: Paginate description: Paginates a collection of pages. categories: [] keywords: [] -action: - related: - - methods/page/Paginator - returnType: page.Pager - signatures: ['PAGE.Paginate COLLECTION [N]'] +params: + functions_and_methods: + returnType: page.Pager + signatures: ['PAGE.Paginate COLLECTION [N]'] --- 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. -[site configuration]: /getting-started/configuration/#pagination - -{{% note %}} -There is also a `Paginator` method on `Page` objects, but it can neither filter nor sort the page collection. - -The `Paginate` method is more flexible. -{{% /note %}} +> [!note] +> There is also a `Paginator` method on `Page` objects, but it can neither filter nor sort the page collection. +> +> The `Paginate` method is more flexible. You can invoke pagination on the [home template], [section templates], [taxonomy templates], and [term templates]. -[home template]: /templates/types/#home -[section templates]: /templates/types/#section -[taxonomy templates]: /templates/types/#taxonomy -[term templates]: /templates/types/#term - -{{< code file=layouts/_default/list.html >}} +```go-html-template {file="layouts/_default/list.html"} {{ $pages := where .Site.RegularPages "Section" "articles" }} {{ $pages = $pages.ByTitle }} {{ range (.Paginate $pages 7).Pages }}

{{ .Title }}

{{ end }} {{ template "_internal/pagination.html" . }} -{{< /code >}} +``` In the example above, we: @@ -46,6 +37,11 @@ In the example above, we: 1. Range over the paginated page collection, rendering a link to each page 1. Call the embedded pagination template to create navigation links between pagers -{{% note %}} -Please note that the results of pagination are cached. Once you have invoked either the `Paginator` or `Paginate` method, the paginated collection is immutable. Additional invocations of these methods will have no effect. -{{% /note %}} +> [!note] +> Please note that the results of pagination are cached. Once you have invoked either the `Paginator` or `Paginate` method, the paginated collection is immutable. Additional invocations of these methods will have no effect. + +[home template]: /templates/types/#home +[section templates]: /templates/types/#section +[site configuration]: /configuration/pagination/ +[taxonomy templates]: /templates/types/#taxonomy +[term templates]: /templates/types/#term diff --git a/content/en/methods/page/Paginator.md b/content/en/methods/page/Paginator.md index c3161da6c..bff7ea90c 100644 --- a/content/en/methods/page/Paginator.md +++ b/content/en/methods/page/Paginator.md @@ -1,45 +1,40 @@ --- title: Paginator -description: Paginates the collection of regular pages received in context. +description: Paginates the collection of regular pages received in context. categories: [] keywords: [] -action: - related: - - methods/page/Paginate - returnType: page.Pager - signatures: [PAGE.Paginator] +params: + functions_and_methods: + returnType: page.Pager + signatures: [PAGE.Paginator] --- 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`. -[site configuration]: /getting-started/configuration/#pagination - You can invoke pagination on the [home template], [section templates], [taxonomy templates], 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. -[home template]: /templates/types/#home -[section templates]: /templates/types/#section -[taxonomy templates]: /templates/types/#taxonomy -[term templates]: /templates/types/#term - -{{< code file=layouts/_default/list.html >}} +```go-html-template {file="layouts/_default/list.html"} {{ range .Paginator.Pages }}

{{ .LinkTitle }}

{{ end }} {{ template "_internal/pagination.html" . }} -{{< /code >}} +``` In the example above, the embedded pagination template creates navigation links between pagers. -{{% note %}} -Although simple to invoke, with the `Paginator` method you can neither filter nor sort the page collection. It acts upon the page collection received in context. +> [!note] +> Although simple to invoke, with the `Paginator` method you can neither filter nor sort the page collection. It acts upon the page collection received in context. +> +> The [`Paginate`] method is more flexible, and strongly recommended. -The [`Paginate`] method is more flexible, and strongly recommended. +> [!note] +> Please note that the results of pagination are cached. Once you have invoked either the `Paginator` or `Paginate` method, the paginated collection is immutable. Additional invocations of these methods will have no effect. -[`paginate`]: /methods/page/paginate/ -{{% /note %}} - -{{% note %}} -Please note that the results of pagination are cached. Once you have invoked either the `Paginator` or `Paginate` method, the paginated collection is immutable. Additional invocations of these methods will have no effect. -{{% /note %}} +[home template]: /templates/types/#home +[section templates]: /templates/types/#section +[site configuration]: /configuration/pagination/ +[taxonomy templates]: /templates/types/#taxonomy +[term templates]: /templates/types/#term +[`Paginate`]: /methods/page/paginate/ diff --git a/content/en/methods/page/Param.md b/content/en/methods/page/Param.md index daf09a5b4..b07c1cd92 100644 --- a/content/en/methods/page/Param.md +++ b/content/en/methods/page/Param.md @@ -3,10 +3,10 @@ title: Param description: Returns a page parameter with the given key, falling back to a site parameter if present. categories: [] keywords: [] -action: - related: [] - returnType: any - signatures: [PAGE.Param KEY] +params: + functions_and_methods: + returnType: any + signatures: [PAGE.Param KEY] aliases: [/functions/param] --- diff --git a/content/en/methods/page/Params.md b/content/en/methods/page/Params.md index faeda4504..eeb253437 100644 --- a/content/en/methods/page/Params.md +++ b/content/en/methods/page/Params.md @@ -3,40 +3,40 @@ title: Params description: Returns a map of custom parameters as defined in the front matter of the given page. categories: [] keywords: [] -action: - related: - - functions/collections/IndexFunction - - methods/site/Params - - methods/page/Param - returnType: maps.Params - signatures: [PAGE.Params] +params: + functions_and_methods: + returnType: maps.Params + signatures: [PAGE.Params] --- -With this front matter: +By way of example, consider this front matter: -{{< code-toggle file=content/news/annual-conference.md >}} +{{< code-toggle file=content/annual-conference.md fm=true >}} title = 'Annual conference' date = 2023-10-17T15:11:37-07:00 [params] display_related = true +key-with-hyphens = 'must use index function' [params.author] email = 'jsmith@example.org' name = 'John Smith' {{< /code-toggle >}} -The `title` and `date` fields are standard parameters---the other fields are user-defined. +The `title` and `date` fields are standard [front matter fields], while the other fields are user-defined. -Access the custom parameters by [chaining](g) the [identifiers](g): +Access the custom fields by [chaining](g) the [identifiers](g) when needed: ```go-html-template {{ .Params.display_related }} → true +{{ .Params.author.email }} → jsmith@example.org {{ .Params.author.name }} → John Smith ``` In the template example 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: ```go-html-template -{{ index .Params "key-with-hyphens" }} → 2023 +{{ index .Params "key-with-hyphens" }} → must use index function ``` [`index`]: /functions/collections/indexfunction/ +[front matter fields]: /content-management/front-matter/#fields diff --git a/content/en/methods/page/Parent.md b/content/en/methods/page/Parent.md index 4c182f8e1..0946a7993 100644 --- a/content/en/methods/page/Parent.md +++ b/content/en/methods/page/Parent.md @@ -3,26 +3,16 @@ title: Parent description: Returns the Page object of the parent section of the given page. categories: [] keywords: [] -action: - related: - - methods/page/Ancestors - - methods/page/CurrentSection - - methods/page/FirstSection - - methods/page/InSection - - methods/page/IsAncestor - - methods/page/IsDescendant - - methods/page/Sections - returnType: page.Page - signatures: [PAGE.Parent] +params: + functions_and_methods: + returnType: page.Page + signatures: [PAGE.Parent] --- {{% glossary-term section %}} -{{% note %}} -The parent section of a regular page is the [current section]. - -[current section]: /methods/page/currentsection/ -{{% /note %}} +> [!note] +> The parent section of a regular page is the [current section]. Consider this content structure: @@ -58,3 +48,5 @@ In the example above, note the parent section of the home page is nil. Code defe {{ .LinkTitle }} {{ end }} ``` + +[current section]: /methods/page/currentsection/ diff --git a/content/en/methods/page/Path.md b/content/en/methods/page/Path.md index 83ad01b94..db4e7d629 100644 --- a/content/en/methods/page/Path.md +++ b/content/en/methods/page/Path.md @@ -3,40 +3,26 @@ title: Path description: Returns the logical path of the given page. categories: [] keywords: [] -action: - related: - - methods/page/File - - methods/page/RelPermalink - returnType: string - signatures: [PAGE.Path] -toc: true +params: + functions_and_methods: + returnType: string + signatures: [PAGE.Path] --- {{< new-in 0.123.0 />}} -The `Path` method on a `Page` object returns the [logical path](g) of the given page, regardless of whether the page is backed by a file. +The `Path` method on a `Page` object returns the logical path of the given page, regardless of whether the page is backed by a file. + +{{% glossary-term "logical path" %}} ```go-html-template {{ .Path }} → /posts/post-1 ``` -This value is neither a file path nor a relative URL. It is a logical identifier for each page, independent of content format, language, and URL modifiers. - -{{% note %}} -Beginning with the release of [v0.92.0] in January 2022, Hugo emitted a warning whenever calling the `Path` method. The warning indicated that this method would change in a future release. - -The meaning of, and value returned by, the `Path` method on a `Page` object changed with the release of [v0.123.0] in February 2024. - -[v0.92.0]: https://github.com/gohugoio/hugo/releases/tag/v0.92.0 -[v0.123.0]: https://github.com/gohugoio/hugo/releases/tag/v0.123.0 -{{% /note %}} - -To determine the logical path for pages backed by a file, Hugo starts with the file path, relative to the `content` directory, and then: - -1. Strips the file extension -1. Strips the language identifier -1. Converts the result to lower case -1. Replaces spaces with hyphens +> [!note] +> Beginning with the release of [v0.92.0] in January 2022, Hugo emitted a warning whenever calling the `Path` method. The warning indicated that this method would change in a future release. +> +> The meaning of, and value returned by, the `Path` method on a `Page` object changed with the release of [v0.123.0] in February 2024. The value returned by the `Path` method on a `Page` object is independent of content format, language, and URL modifiers such as the `slug` and `url` front matter fields. @@ -101,25 +87,13 @@ Methods|Functions|Shortcodes :--|:--|:-- [`Site.GetPage`]|[`urls.Ref`]|[`ref`] [`Page.GetPage`]|[`urls.RelRef`]|[`relref`] -[`Page.Ref`]|| -[`Page.RelRef`]|| -[`Shortcode.Ref`]|| -[`Shortcode.RelRef`]|| +[`Page.Ref`]||| +[`Page.RelRef`]||| +[`Shortcode.Ref`]||| +[`Shortcode.RelRef`]||| -[`urls.Ref`]: /functions/urls/ref/ -[`urls.RelRef`]: /functions/urls/relref/ -[`Page.GetPage`]: /methods/page/getpage/ -[`Site.GetPage`]: /methods/site/getpage/ -[`ref`]: /shortcodes/ref/ -[`relref`]: /shortcodes/relref/ -[`Page.Ref`]: /methods/page/ref/ -[`Page.RelRef`]: /methods/page/relref/ -[`Shortcode.Ref`]: /methods/shortcode/ref -[`Shortcode.RelRef`]: /methods/shortcode/relref - -{{% note %}} -Specify the logical path when using any of these methods, functions, or shortcodes. If you include a file extension or language identifier, Hugo will strip these values before finding the page in the logical tree. -{{% /note %}} +> [!note] +> Specify the logical path when using any of these methods, functions, or shortcodes. If you include a file extension or language identifier, Hugo will strip these values before finding the page in the logical tree. ## Logical tree @@ -149,6 +123,18 @@ A key difference between these trees is the relative path from p1 to p2: - In the file tree, the relative path from p1 to p2 is `../p2.md` - In the logical tree, the relative path is `p2` -{{% note %}} -Remember to use the logical path when using any of the methods, functions, or shortcodes listed in the previous section. If you include a file extension or language identifier, Hugo will strip these values before finding the page in the logical tree. -{{% /note %}} +> [!note] +> Remember to use the logical path when using any of the methods, functions, or shortcodes listed in the previous section. If you include a file extension or language identifier, Hugo will strip these values before finding the page in the logical tree. + +[`Page.GetPage`]: /methods/page/getpage/ +[`Page.Ref`]: /methods/page/ref/ +[`Page.RelRef`]: /methods/page/relref/ +[`ref`]: /shortcodes/ref/ +[`relref`]: /shortcodes/relref/ +[`Shortcode.Ref`]: /methods/shortcode/ref +[`Shortcode.RelRef`]: /methods/shortcode/relref +[`Site.GetPage`]: /methods/site/getpage/ +[`urls.Ref`]: /functions/urls/ref/ +[`urls.RelRef`]: /functions/urls/relref/ +[v0.123.0]: https://github.com/gohugoio/hugo/releases/tag/v0.123.0 +[v0.92.0]: https://github.com/gohugoio/hugo/releases/tag/v0.92.0 diff --git a/content/en/methods/page/Permalink.md b/content/en/methods/page/Permalink.md index d8416df86..cc74f3342 100644 --- a/content/en/methods/page/Permalink.md +++ b/content/en/methods/page/Permalink.md @@ -3,11 +3,10 @@ title: Permalink description: Returns the permalink of the given page. categories: [] keywords: [] -action: - related: - - methods/page/RelPermalink - returnType: string - signatures: [PAGE.Permalink] +params: + functions_and_methods: + returnType: string + signatures: [PAGE.Permalink] --- Site configuration: diff --git a/content/en/methods/page/Plain.md b/content/en/methods/page/Plain.md index e26c33529..65d11166e 100644 --- a/content/en/methods/page/Plain.md +++ b/content/en/methods/page/Plain.md @@ -3,16 +3,10 @@ title: Plain description: Returns the rendered content of the given page, removing all HTML tags. categories: [] keywords: [] -action: - related: - - methods/page/Content - - methods/page/Summary - - methods/page/ContentWithoutSummary - - methods/page/RawContent - - methods/page/PlainWords - - methods/page/RenderShortcodes - returnType: string - signatures: [PAGE.Plain] +params: + functions_and_methods: + returnType: string + signatures: [PAGE.Plain] --- The `Plain` method on a `Page` object renders Markdown and [shortcodes](g) to HTML, then strips the HTML [tags]. It does not strip HTML [entities]. diff --git a/content/en/methods/page/PlainWords.md b/content/en/methods/page/PlainWords.md index 221fd741b..5749a21f9 100644 --- a/content/en/methods/page/PlainWords.md +++ b/content/en/methods/page/PlainWords.md @@ -3,25 +3,16 @@ title: PlainWords description: Calls the Plain method, splits the result into a slice of words, and returns the slice. categories: [] keywords: [] -action: - related: - - methods/page/Content - - methods/page/Summary - - methods/page/ContentWithoutSummary - - methods/page/RawContent - - methods/page/Plain - - methods/page/RenderShortcodes - returnType: '[]string' - signatures: [PAGE.PlainWords] +params: + functions_and_methods: + returnType: '[]string' + signatures: [PAGE.PlainWords] --- The `PlainWords` method on a `Page` object calls the [`Plain`] method, then uses Go's [`strings.Fields`] function to split the result into words. -{{% note %}} -_Fields splits the string s around each instance of one or more consecutive whitespace characters, as defined by [`unicode.IsSpace`], returning a slice of substrings of s or an empty slice if s contains only whitespace._ - -[`unicode.IsSpace`]: https://pkg.go.dev/unicode#IsSpace -{{% /note %}} +> [!note] +> `Fields` splits the string `s` around each instance of one or more consecutive whitespace characters, as defined by [`unicode.IsSpace`], returning a slice of substrings of `s` or an empty slice if `s` contains only whitespace. As a result, elements within the slice may contain leading or trailing punctuation. @@ -37,3 +28,4 @@ To determine the approximate number of unique words on a page: [`Plain`]: /methods/page/plain/ [`strings.Fields`]: https://pkg.go.dev/strings#Fields +[`unicode.IsSpace`]: https://pkg.go.dev/unicode#IsSpace diff --git a/content/en/methods/page/Prev.md b/content/en/methods/page/Prev.md index d28b50265..5a6e2162d 100644 --- a/content/en/methods/page/Prev.md +++ b/content/en/methods/page/Prev.md @@ -3,15 +3,10 @@ title: Prev description: Returns the previous page in a site's collection of regular pages, relative to the current page. categories: [] keywords: [] -action: - related: - - methods/page/Next - - methods/page/NextInSection - - methods/page/PrevInSection - - methods/pages/Next - - methods/pages/Prev - returnType: page.Page - signatures: [PAGE.Prev] +params: + functions_and_methods: + returnType: page.Page + signatures: [PAGE.Prev] --- -{{% include "methods/page/_common/next-and-prev.md" %}} +{{% include "/_common/methods/page/next-and-prev.md" %}} diff --git a/content/en/methods/page/PrevInSection.md b/content/en/methods/page/PrevInSection.md index aaafb367e..14d3ca082 100644 --- a/content/en/methods/page/PrevInSection.md +++ b/content/en/methods/page/PrevInSection.md @@ -1,15 +1,12 @@ --- title: PrevInSection -description: Returns the previous regular page in a section, relative to the given page. +description: Returns the previous regular page in a section, relative to the given page. categories: [] keywords: [] -action: - related: - - methods/page/NextInSection - - methods/pages/Next - - methods/pages/Prev - returnType: page.Page - signatures: [PAGE.PrevInSection] +params: + functions_and_methods: + returnType: page.Page + signatures: [PAGE.PrevInSection] --- -{{% include "methods/page/_common/nextinsection-and-previnsection.md" %}} +{{% include "/_common/methods/page/nextinsection-and-previnsection.md" %}} diff --git a/content/en/methods/page/PublishDate.md b/content/en/methods/page/PublishDate.md index d1f2eb2a1..7500a08aa 100644 --- a/content/en/methods/page/PublishDate.md +++ b/content/en/methods/page/PublishDate.md @@ -3,13 +3,10 @@ title: PublishDate description: Returns the publish date of the given page. categories: [] keywords: [] -action: - related: - - methods/page/Date - - methods/page/ExpiryDate - - methods/page/LastMod - returnType: time.Time - signatures: [PAGE.PublishDate] +params: + functions_and_methods: + returnType: time.Time + 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. @@ -30,6 +27,6 @@ The publish date is a [time.Time] value. Format and localize the value with the In the example above we explicitly set the publish date in front matter. With Hugo's default configuration, the `PublishDate` method returns the front matter value. This behavior is configurable, allowing you to set fallback values if the publish date is not defined in front matter. See [details]. [`time.Format`]: /functions/time/format/ -[details]: /getting-started/configuration/#configure-dates +[details]: /configuration/front-matter/#dates [time methods]: /methods/time/ [time.Time]: https://pkg.go.dev/time#Time diff --git a/content/en/methods/page/RawContent.md b/content/en/methods/page/RawContent.md index 9dab9693e..41215ef53 100644 --- a/content/en/methods/page/RawContent.md +++ b/content/en/methods/page/RawContent.md @@ -3,16 +3,10 @@ title: RawContent description: Returns the raw content of the given page. categories: [] keywords: [] -action: - related: - - methods/page/Content - - methods/page/Summary - - methods/page/ContentWithoutSummary - - methods/page/Plain - - methods/page/PlainWords - - methods/page/RenderShortcodes - returnType: string - signatures: [PAGE.RawContent] +params: + functions_and_methods: + returnType: string + signatures: [PAGE.RawContent] --- The `RawContent` method on a `Page` object returns the raw content. The raw content does not include front matter. @@ -21,12 +15,9 @@ The `RawContent` method on a `Page` object returns the raw content. The raw cont {{ .RawContent }} ``` -This is useful when rendering a page in a plain text [output format]. +This is useful when rendering a page in a plain text [output format](g). -{{% note %}} -[Shortcodes](g) within the content are not rendered. To get the raw content with shortcodes rendered, use the [`RenderShortcodes`] method on a `Page` object. +> [!note] +> [Shortcodes](g) within the content are not rendered. To get the raw content with shortcodes rendered, use the [`RenderShortcodes`] method on a `Page` object. [`RenderShortcodes`]: /methods/page/rendershortcodes/ -{{% /note %}} - -[output format]: /templates/output-formats/ diff --git a/content/en/methods/page/ReadingTime.md b/content/en/methods/page/ReadingTime.md index 531824b9b..1bd7dea31 100644 --- a/content/en/methods/page/ReadingTime.md +++ b/content/en/methods/page/ReadingTime.md @@ -3,12 +3,10 @@ title: ReadingTime description: Returns the estimated reading time, in minutes, for the given page. categories: [] keywords: [] -action: - related: - - methods/page/WordCount - - methods/page/FuzzyWordCount - returnType: int - signatures: [PAGE.ReadingTime] +params: + functions_and_methods: + returnType: int + signatures: [PAGE.ReadingTime] --- The estimated reading time is calculated by dividing the number of words in the content by the reading speed. diff --git a/content/en/methods/page/Ref.md b/content/en/methods/page/Ref.md index e0d42424d..35f9460ba 100644 --- a/content/en/methods/page/Ref.md +++ b/content/en/methods/page/Ref.md @@ -3,27 +3,23 @@ title: Ref description: Returns the absolute URL of the page with the given path, language, and output format. categories: [] keywords: [] -action: - related: - - methods/page/RelRef - - functions/urls/RelRef - - functions/urls/Ref - returnType: string - signatures: [PAGE.Ref OPTIONS] +params: + functions_and_methods: + returnType: string + signatures: [PAGE.Ref OPTIONS] --- -The map of option contains: +## Usage -path -: (`string`) The path to the page, relative to the `content` directory. Required. +The `Ref` method accepts a single argument: an options map. -lang -: (`string`) The language (site) to search for the page. Default is the current language. Optional. +## Options -outputFormat -: (`string`) The output format to search for the page. Default is the current output format. Optional. +{{% include "_common/ref-and-relref-options.md" %}} -The examples below show the rendered output when visiting a page on the English language version of the site: +## Examples + +The following examples show the rendered output for a page on the English version of the site: ```go-html-template {{ $opts := dict "path" "/books/book-1" }} @@ -36,9 +32,6 @@ The examples below show the rendered output when visiting a page on the English {{ .Ref $opts }} → https://example.org/de/books/book-1/index.json ``` -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. +## Error handling -{{< code-toggle file=hugo >}} -refLinksErrorLevel = 'warning' -refLinksNotFoundURL = '/some/other/url' -{{< /code-toggle >}} +{{% include "_common/ref-and-relref-error-handling.md" %}} diff --git a/content/en/methods/page/RegularPages.md b/content/en/methods/page/RegularPages.md index 08198fca4..761de3af5 100644 --- a/content/en/methods/page/RegularPages.md +++ b/content/en/methods/page/RegularPages.md @@ -3,15 +3,13 @@ title: RegularPages description: Returns a collection of regular pages within the current section. categories: [] keywords: [] -action: - related: - - methods/page/Pages - - methods/page/RegularPagesRecursive - returnType: page.Pages - signatures: [PAGE.RegularPages] +params: + functions_and_methods: + returnType: page.Pages + signatures: [PAGE.RegularPages] --- -The `RegularPages` method on a `Page` object is available to these [page kinds](g): `home`, `section`, `taxonomy`, and `term`. The templates for these page kinds receive a page [collection](g) in [context](g). +The `RegularPages` method on a `Page` object is available to these [page kinds](g): `home`, `section`, `taxonomy`, and `term`. The templates for these page kinds receive a page [collection](g) in [context](g), in the [default sort order](g). Range through the page collection in your template: @@ -69,14 +67,13 @@ When rendering lesson-2, the `RegularPages` method returns: In the last example, the collection includes pages in the resources subdirectory. That directory is not a [section](g)---it does not contain an `_index.md` file. Its contents are part of the lesson-2 section. -{{% note %}} -When used with the `Site` object, the `RegularPages` method recursively returns all regular pages within the site. See [details]. - -[details]: /methods/site/regularpages/ -{{% /note %}} +> [!note] +> When used with the `Site` object, the `RegularPages` method recursively returns all regular pages within the site. See [details]. ```go-html-template {{ range .Site.RegularPages.ByTitle }}

{{ .Title }}

{{ end }} ``` + +[details]: /methods/site/regularpages/ diff --git a/content/en/methods/page/RegularPagesRecursive.md b/content/en/methods/page/RegularPagesRecursive.md index 8e1c5f9a4..d85cd0b48 100644 --- a/content/en/methods/page/RegularPagesRecursive.md +++ b/content/en/methods/page/RegularPagesRecursive.md @@ -3,15 +3,13 @@ title: RegularPagesRecursive description: Returns a collection of regular pages within the current section, and regular pages within all descendant sections. categories: [] keywords: [] -action: - related: - - methods/page/Pages - - methods/page/RegularPages - returnType: page.Pages - signatures: [PAGE.RegularPagesRecursive] +params: + functions_and_methods: + returnType: page.Pages + signatures: [PAGE.RegularPagesRecursive] --- -The `RegularPagesRecursive` method on a `Page` object is available to these [page kinds](g): `home`, `section`, `taxonomy`, and `term`. The templates for these page kinds receive a page [collection](g) in [context](g). +The `RegularPagesRecursive` method on a `Page` object is available to these [page kinds](g): `home`, `section`, `taxonomy`, and `term`. The templates for these page kinds receive a page [collection](g) in [context](g), in the [default sort order](g). Range through the page collection in your template: @@ -81,6 +79,5 @@ When rendering lesson-2, the `RegularPagesRecursive` method returns: lessons/lesson-2/resources/task-list.md lessons/lesson-2/resources/worksheet.md -{{% note %}} -The `RegularPagesRecursive` method in not available on a `Site` object. -{{% /note %}} +> [!note] +> The `RegularPagesRecursive` method is not available on a `Site` object. diff --git a/content/en/methods/page/RelPermalink.md b/content/en/methods/page/RelPermalink.md index 817e3c862..a3c610d50 100644 --- a/content/en/methods/page/RelPermalink.md +++ b/content/en/methods/page/RelPermalink.md @@ -3,11 +3,10 @@ title: RelPermalink description: Returns the relative permalink of the given page. categories: [] keywords: [] -action: - related: - - methods/page/Permalink - returnType: string - signatures: [PAGE.RelPermalink] +params: + functions_and_methods: + returnType: string + signatures: [PAGE.RelPermalink] --- Site configuration: diff --git a/content/en/methods/page/RelRef.md b/content/en/methods/page/RelRef.md index 83ab08610..7edab5740 100644 --- a/content/en/methods/page/RelRef.md +++ b/content/en/methods/page/RelRef.md @@ -3,27 +3,23 @@ title: RelRef description: Returns the relative URL of the page with the given path, language, and output format. categories: [] keywords: [] -action: - related: - - methods/page/Ref - - functions/urls/Ref - - functions/urls/RelRef - returnType: string - signatures: [PAGE.RelRef OPTIONS] +params: + functions_and_methods: + returnType: string + signatures: [PAGE.RelRef OPTIONS] --- -The map of option contains: +## Usage -path -: (`string`) The path to the page, relative to the `content` directory. Required. +The `RelRef` method accepts a single argument: an options map. -lang -: (`string`) The language (site) to search for the page. Default is the current language. Optional. +## Options -outputFormat -: (`string`) The output format to search for the page. Default is the current output format. Optional. +{{% include "_common/ref-and-relref-options.md" %}} -The examples below show the rendered output when visiting a page on the English language version of the site: +## Examples + +The following examples show the rendered output for a page on the English version of the site: ```go-html-template {{ $opts := dict "path" "/books/book-1" }} @@ -36,9 +32,6 @@ The examples below show the rendered output when visiting a page on the English {{ .RelRef $opts }} → /de/books/book-1/index.json ``` -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. +## Error handling -{{< code-toggle file=hugo >}} -refLinksErrorLevel = 'warning' -refLinksNotFoundURL = '/some/other/url' -{{< /code-toggle >}} +{{% include "_common/ref-and-relref-error-handling.md" %}} diff --git a/content/en/methods/page/Render.md b/content/en/methods/page/Render.md index 1adc71c6d..10f7f9ca5 100644 --- a/content/en/methods/page/Render.md +++ b/content/en/methods/page/Render.md @@ -3,12 +3,10 @@ title: Render description: Renders the given template with the given page as context. categories: [] keywords: [] -action: - related: - - functions/partials/Include - - functions/partials/IncludeCached - returnType: template.HTML - signatures: [PAGE.Render NAME] +params: + functions_and_methods: + returnType: template.HTML + signatures: [PAGE.Render NAME] aliases: [/functions/render] --- diff --git a/content/en/methods/page/RenderShortcodes.md b/content/en/methods/page/RenderShortcodes.md index 3346f0ba1..d124606f0 100644 --- a/content/en/methods/page/RenderShortcodes.md +++ b/content/en/methods/page/RenderShortcodes.md @@ -3,18 +3,10 @@ title: RenderShortcodes description: Renders all shortcodes in the content of the given page, preserving the surrounding markup. categories: [] keywords: [] -action: - related: - - methods/page/Content - - methods/page/Summary - - methods/page/ContentWithoutSummary - - methods/page/RawContent - - methods/page/Plain - - methods/page/PlainWords - - methods/page/RenderString - returnType: template.HTML - signatures: [PAGE.RenderShortcodes] -toc: true +params: + functions_and_methods: + returnType: template.HTML + signatures: [PAGE.RenderShortcodes] --- {{< new-in 0.117.0 />}} @@ -23,7 +15,7 @@ Use this method in shortcode templates to compose a page from multiple content f For example: -{{< code file=layouts/shortcodes/include.html >}} +```go-html-template {file="layouts/shortcodes/include.html" copy=true} {{ with .Get 0 }} {{ with $.Page.GetPage . }} {{- .RenderShortcodes }} @@ -33,15 +25,15 @@ For example: {{ else }} {{ errorf "The %q shortcode requires a positional parameter indicating the logical path of the file to include. See %s" .Name .Position }} {{ end }} -{{< /code >}} +``` Then call the shortcode in your Markdown: -{{< code file=content/about.md lang=md >}} +```text {file="content/about.md"} {{%/* include "/snippets/services" */%}} {{%/* include "/snippets/values" */%}} {{%/* include "/snippets/leadership" */%}} -{{< /code >}} +``` Each of the included Markdown files can contain calls to other shortcodes. @@ -58,7 +50,7 @@ Use the latter for the "include" shortcode described above. To understand what is returned by the `RenderShortcodes` method, consider this content file -{{< code file=content/about.md lang=text >}} +```text {file="content/about.md"} +++ title = 'About' date = 2023-10-07T12:28:33-07:00 @@ -67,7 +59,7 @@ date = 2023-10-07T12:28:33-07:00 {{}} An *emphasized* word. -{{< /code >}} +``` With this template code: @@ -90,7 +82,7 @@ Note that the shortcode within the content file was rendered, but the surroundin The primary use case for `.RenderShortcodes` is inclusion of Markdown content. If you try to use `.RenderShortcodes` inside `HTML` blocks when inside Markdown, you will get a warning similar to this: -``` +```text WARN .RenderShortcodes detected inside HTML block in "/content/mypost.md"; this may not be what you intended ... ``` diff --git a/content/en/methods/page/RenderString.md b/content/en/methods/page/RenderString.md index 1a92c78c6..c7774774c 100644 --- a/content/en/methods/page/RenderString.md +++ b/content/en/methods/page/RenderString.md @@ -3,12 +3,10 @@ title: RenderString description: Renders markup to HTML. categories: [] keywords: [] -action: - related: - - methods/page/RenderShortcodes - - functions/transform/Markdownify - returnType: template.HTML - signatures: ['PAGE.RenderString [OPTIONS] MARKUP'] +params: + functions_and_methods: + returnType: template.HTML + signatures: ['PAGE.RenderString [OPTIONS] MARKUP'] aliases: [/functions/renderstring] --- diff --git a/content/en/methods/page/Resources.md b/content/en/methods/page/Resources.md index 6c79f58ee..dd472de88 100644 --- a/content/en/methods/page/Resources.md +++ b/content/en/methods/page/Resources.md @@ -3,16 +3,10 @@ title: Resources description: Returns a collection of page resources. categories: [] keywords: [] -action: - related: - - functions/resources/ByType - - functions/resources/Get - - functions/resources/GetMatch - - functions/resources/GetRemote - - functions/resources/Match - returnType: resource.Resources - signatures: [PAGE.Resources] -toc: true +params: + functions_and_methods: + returnType: resource.Resources + signatures: [PAGE.Resources] --- The `Resources` method on a `Page` object returns a collection of page resources. A page resource is a file within a [page bundle](g). @@ -21,7 +15,7 @@ To work with global or remote resources, see the [`resources`] functions. ## Methods -###### ByType +### ByType (`resource.Resources`) Returns a collection of page resources of the given [media type], or nil if none found. The media type is typically one of `image`, `text`, `audio`, `video`, or `application`. @@ -33,7 +27,7 @@ To work with global or remote resources, see the [`resources`] functions. When working with global resources instead of page resources, use the [`resources.ByType`] function. -###### Get +### Get (`resource.Resource`) Returns a page resource from the given path, or nil if none found. @@ -45,9 +39,9 @@ When working with global resources instead of page resources, use the [`resource When working with global resources instead of page resources, use the [`resources.Get`] function. -###### GetMatch +### GetMatch -(`resource.Resource`) Returns the first page resource from paths matching the given [glob pattern], or nil if none found. +(`resource.Resource`) Returns the first page resource from paths matching the given [glob](g) pattern, or nil if none found. ```go-html-template {{ with .Resources.GetMatch "images/*.jpg" }} @@ -57,9 +51,9 @@ When working with global resources instead of page resources, use the [`resource When working with global resources instead of page resources, use the [`resources.GetMatch`] function. -###### Match +### Match -(`resource.Resources`) Returns a collection of page resources from paths matching the given [glob pattern], or nil if none found. +(`resource.Resources`) Returns a collection of page resources from paths matching the given [glob](g) pattern, or nil if none found. ```go-html-template {{ range .Resources.Match "images/*.jpg" }} @@ -69,7 +63,7 @@ When working with global resources instead of page resources, use the [`resource When working with global resources instead of page resources, use the [`resources.Match`] function. -###### Mount +### Mount {{< new-in 0.140.0 />}} @@ -84,14 +78,13 @@ This method is currently only useful in [js.Batch](/functions/js/batch/#import-c ## Pattern matching -With the `GetMatch` and `Match` methods, Hugo determines a match using a case-insensitive [glob pattern]. +With the `GetMatch` and `Match` methods, Hugo determines a match using a case-insensitive [glob](g) pattern. -{{% include "functions/_common/glob-patterns.md" %}} +{{% include "/_common/glob-patterns.md" %}} [`resources.ByType`]: /functions/resources/ByType/ [`resources.GetMatch`]: /functions/resources/ByType/ [`resources.Get`]: /functions/resources/ByType/ [`resources.Match`]: /functions/resources/ByType/ [`resources`]: /functions/resources/ -[glob pattern]: https://github.com/gobwas/glob#example [media type]: https://en.wikipedia.org/wiki/Media_type diff --git a/content/en/methods/page/Scratch.md b/content/en/methods/page/Scratch.md index 436005a94..61c5dc19e 100644 --- a/content/en/methods/page/Scratch.md +++ b/content/en/methods/page/Scratch.md @@ -3,14 +3,14 @@ title: Scratch description: Returns a "scratch pad" to store and manipulate data, scoped to the current page. categories: [] keywords: [] -action: - related: [] - returnType: maps.Scratch - signatures: [PAGE.Scratch] +params: + functions_and_methods: + returnType: maps.Scratch + signatures: [PAGE.Scratch] expiryDate: 2026-11-18 # deprecated 2024-11-18 (soft) --- -{{% deprecated-in 0.138.0 %}} +{{< deprecated-in 0.138.0 >}} Use the [`PAGE.Store`] method instead. This is a soft deprecation. This method will be removed in a future release, but the removal date has not been established. Although Hugo will not emit a warning if you continue to use this method, you should begin using `PAGE.Store` as soon as possible. @@ -18,4 +18,4 @@ This is a soft deprecation. This method will be removed in a future release, but Beginning with v0.138.0 the `PAGE.Scratch` method is aliased to `PAGE.Store`. [`PAGE.Store`]: /methods/page/store/ -{{% /deprecated-in %}} +{{< /deprecated-in >}} diff --git a/content/en/methods/page/Section.md b/content/en/methods/page/Section.md index 31cfb1e6f..04c6a8a24 100644 --- a/content/en/methods/page/Section.md +++ b/content/en/methods/page/Section.md @@ -1,15 +1,16 @@ --- title: Section -description: Returns the name of the top level section in which the given page resides. +description: Returns the name of the top-level section in which the given page resides. categories: [] keywords: [] -action: - related: - - methods/page/Type - returnType: string - signatures: [PAGE.Section] +params: + functions_and_methods: + returnType: string + signatures: [PAGE.Section] --- +{{% glossary-term section %}} + With this content structure: ```text @@ -29,7 +30,7 @@ When rendering lesson-1.md: {{ .Section }} → lessons ``` -In the example above "lessons" is the top level section. +In the example above "lessons" is the top-level section. The `Section` method is often used with the [`where`] function to build a page collection. diff --git a/content/en/methods/page/Sections.md b/content/en/methods/page/Sections.md index 921e4eb4e..12f0a8c24 100644 --- a/content/en/methods/page/Sections.md +++ b/content/en/methods/page/Sections.md @@ -3,20 +3,13 @@ title: Sections description: Returns a collection of section pages, one for each immediate descendant section of the given page. categories: [] keywords: [] -action: - related: - - methods/page/Ancestors - - methods/page/CurrentSection - - methods/page/FirstSection - - methods/page/InSection - - methods/page/IsAncestor - - methods/page/IsDescendant - - methods/page/Parent - returnType: page.Pages - signatures: [PAGE.Sections] +params: + functions_and_methods: + returnType: page.Pages + signatures: [PAGE.Sections] --- -{{% glossary-term section %}} +The `Sections` method on a `Page` object is available to these [page kinds](g): `home`, `section`, and `taxonomy`. The templates for these page kinds receive a page [collection](g) in [context](g), in the [default sort order](g). With this content structure: diff --git a/content/en/methods/page/Site.md b/content/en/methods/page/Site.md index d83c45e0a..4649e5e00 100644 --- a/content/en/methods/page/Site.md +++ b/content/en/methods/page/Site.md @@ -3,11 +3,10 @@ title: Site description: Returns the Site object. categories: [] keywords: [] -action: - related: - - methods/page/Sites - returnType: page.siteWrapper - signatures: [PAGE.Site] +params: + functions_and_methods: + returnType: page.siteWrapper + signatures: [PAGE.Site] --- See [Site methods]. diff --git a/content/en/methods/page/Sitemap.md b/content/en/methods/page/Sitemap.md index 065c07c35..bb1360493 100644 --- a/content/en/methods/page/Sitemap.md +++ b/content/en/methods/page/Sitemap.md @@ -3,33 +3,37 @@ title: Sitemap description: Returns the sitemap settings for the given page as defined in front matter, falling back to the sitemap settings as defined in the site configuration. categories: [] keywords: [] -action: - related: [] - returnType: config.SitemapConfig - signatures: [PAGE.Sitemap] -toc: true +params: + functions_and_methods: + returnType: config.SitemapConfig + signatures: [PAGE.Sitemap] --- Access to the `Sitemap` method on a `Page` object is restricted to [sitemap templates]. ## Methods -changefreq -: (`string`) How frequently a page is likely to change. Valid values are `always`, `hourly`, `daily`, `weekly`, `monthly`, `yearly`, and `never`. With the default value of `""` Hugo will omit this field from the sitemap. See [details](https://www.sitemaps.org/protocol.html#changefreqdef). +### ChangeFreq + +(`string`) How frequently a page is likely to change. Valid values are `always`, `hourly`, `daily`, `weekly`, `monthly`, `yearly`, and `never`. With the default value of `""` Hugo will omit this field from the sitemap. See [details](https://www.sitemaps.org/protocol.html#changefreqdef). ```go-html-template {{ .Sitemap.ChangeFreq }} ``` -disable {{< new-in 0.125.0 />}} -: (`bool`) Whether to disable page inclusion. Default is `false`. Set to `true` in front matter to exclude the page. +### Disable + +{{< new-in 0.125.0 />}} + +(`bool`) Whether to disable page inclusion. Default is `false`. Set to `true` in front matter to exclude the page. ```go-html-template {{ .Sitemap.Disable }} ``` -priority -: (`float`) The priority of a page relative to any other page on the site. Valid values range from 0.0 to 1.0. With the default value of `-1` Hugo will omit this field from the sitemap. See [details](https://www.sitemaps.org/protocol.html#priority). +### Priority + +(`float`) The priority of a page relative to any other page on the site. Valid values range from 0.0 to 1.0. With the default value of `-1` Hugo will omit this field from the sitemap. See [details](https://www.sitemaps.org/protocol.html#prioritydef). ```go-html-template {{ .Sitemap.Priority }} @@ -54,7 +58,7 @@ changeFreq = 'hourly' And this simplistic sitemap template: -{{< code file=layouts/_default/sitemap.xml >}} +```xml {file="layouts/_default/sitemap.xml"} {{ printf "" | safeHTML }} @@ -70,7 +74,7 @@ And this simplistic sitemap template: {{ end }} -{{< /code >}} +``` The change frequency will be `hourly` for the news page, and `monthly` for other pages. diff --git a/content/en/methods/page/Sites.md b/content/en/methods/page/Sites.md index cd240655e..8677226d7 100644 --- a/content/en/methods/page/Sites.md +++ b/content/en/methods/page/Sites.md @@ -3,11 +3,10 @@ title: Sites description: Returns a collection of all Site objects, one for each language, ordered by language weight. categories: [] keywords: [] -action: - related: - - methods/page/Site - returnType: page.Sites - signatures: [PAGE.Sites] +params: + functions_and_methods: + returnType: page.Sites + signatures: [PAGE.Sites] --- This is a convenience method to access `.Site.Sites`. diff --git a/content/en/methods/page/Slug.md b/content/en/methods/page/Slug.md index 9fdb09b57..34000b660 100644 --- a/content/en/methods/page/Slug.md +++ b/content/en/methods/page/Slug.md @@ -3,10 +3,10 @@ title: Slug description: Returns the URL slug of the given page as defined in front matter. categories: [] keywords: [] -action: - related: [] - returnType: string - signatures: [PAGE.Slug] +params: + functions_and_methods: + returnType: string + signatures: [PAGE.Slug] --- {{< code-toggle file=content/recipes/spicy-tuna-hand-rolls.md fm=true >}} diff --git a/content/en/methods/page/Store.md b/content/en/methods/page/Store.md index 769a554f1..0b1049b0a 100644 --- a/content/en/methods/page/Store.md +++ b/content/en/methods/page/Store.md @@ -3,15 +3,10 @@ title: Store description: Returns a "scratch pad" to store and manipulate data, scoped to the current page. categories: [] keywords: [] -action: - related: - - methods/site/Store - - methods/shortcode/Store - - functions/hugo/Store - - functions/collections/NewScratch - returnType: maps.Scratch - signatures: [PAGE.Store] -toc: true +params: + functions_and_methods: + returnType: maps.Scratch + signatures: [PAGE.Store] aliases: [/functions/store/,/extras/scratch/,/doc/scratch/,/functions/scratch] --- diff --git a/content/en/methods/page/Summary.md b/content/en/methods/page/Summary.md index a875d62f0..9158e571d 100644 --- a/content/en/methods/page/Summary.md +++ b/content/en/methods/page/Summary.md @@ -3,14 +3,10 @@ title: Summary description: Returns the summary of the given page. categories: [] keywords: [] -action: - related: - - methods/page/Truncated - - methods/page/Content - - methods/page/ContentWithoutSummary - - methods/page/Description - returnType: template.HTML - signatures: [PAGE.Summary] +params: + functions_and_methods: + returnType: template.HTML + signatures: [PAGE.Summary] --- @@ -20,8 +16,6 @@ action: You can define a [summary] manually, in front matter, or automatically. A manual summary takes precedence over a front matter summary, and a front matter summary takes precedence over an automatic summary. -[summary]: /content-management/summaries/ - To list the pages in a section with a summary beneath each link: ```go-html-template @@ -33,8 +27,6 @@ To list the pages in a section with a summary beneath each link: Depending on content length and how you define the summary, the summary may be equivalent to the content itself. To determine whether the content length exceeds the summary length, use the [`Truncated`] method on a `Page` object. This is useful for conditionally rendering a “read more” link: -[`Truncated`]: /methods/page/truncated - ```go-html-template {{ range .Pages }}

{{ .LinkTitle }}

@@ -45,6 +37,8 @@ Depending on content length and how you define the summary, the summary may be e {{ end }} ``` -{{% note %}} -The `Truncated` method returns `false` if you define the summary in front matter. -{{% /note %}} +> [!note] +> The `Truncated` method returns `false` if you define the summary in front matter. + +[`Truncated`]: /methods/page/truncated +[summary]: /content-management/summaries/ diff --git a/content/en/methods/page/TableOfContents.md b/content/en/methods/page/TableOfContents.md index 38c3ff17b..7ec9fe614 100644 --- a/content/en/methods/page/TableOfContents.md +++ b/content/en/methods/page/TableOfContents.md @@ -3,11 +3,10 @@ title: TableOfContents description: Returns a table of contents for the given page. categories: [] keywords: [] -action: - related: - - methods/page/Fragments - returnType: template.HTML - signatures: [PAGE.TableOfContents] +params: + functions_and_methods: + returnType: template.HTML + signatures: [PAGE.TableOfContents] aliases: [/content-management/toc/] --- diff --git a/content/en/methods/page/Title.md b/content/en/methods/page/Title.md index 08fc9f9eb..dae4ba6dd 100644 --- a/content/en/methods/page/Title.md +++ b/content/en/methods/page/Title.md @@ -3,11 +3,10 @@ title: Title description: Returns the title of the given page. categories: [] keywords: [] -action: - related: - - methods/page/LinkTitle - returnType: string - signatures: [PAGE.Title] +params: + functions_and_methods: + returnType: string + signatures: [PAGE.Title] --- With pages backed by a file, the `Title` method returns the `title` field as defined in front matter: @@ -35,6 +34,6 @@ titleCaseStyle = "firstupper" See [details]. -[`capitalizeListTitles`]: /getting-started/configuration/#capitalizelisttitles -[`pluralizeListTitles`]: /getting-started/configuration/#pluralizelisttitles -[details]: /getting-started/configuration/#configure-title-case +[`capitalizeListTitles`]: /configuration/all/#capitalizelisttitles +[`pluralizeListTitles`]: /configuration/all/#pluralizelisttitles +[details]: /configuration/all/#title-case-style diff --git a/content/en/methods/page/TranslationKey.md b/content/en/methods/page/TranslationKey.md index a9e4b97e9..1e930687e 100644 --- a/content/en/methods/page/TranslationKey.md +++ b/content/en/methods/page/TranslationKey.md @@ -3,13 +3,10 @@ title: TranslationKey description: Returns the translation key of the given page. categories: [] keywords: [] -action: - related: - - methods/page/Translations - - methods/page/AllTranslations - - methods/page/IsTranslated - returnType: string - signatures: [PAGE.TranslationKey] +params: + functions_and_methods: + returnType: string + signatures: [PAGE.TranslationKey] --- 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. diff --git a/content/en/methods/page/Translations.md b/content/en/methods/page/Translations.md index 597a9aeb6..4bab9fe11 100644 --- a/content/en/methods/page/Translations.md +++ b/content/en/methods/page/Translations.md @@ -1,15 +1,12 @@ --- title: Translations -description: Returns all translations of the given page, excluding the current language. +description: Returns all translations of the given page, excluding the current language. categories: [] keywords: [] -action: - related: - - methods/page/AllTranslations - - methods/page/IsTranslated - - methods/page/TranslationKey - returnType: page.Pages - signatures: [PAGE.Translations] +params: + functions_and_methods: + returnType: page.Pages + signatures: [PAGE.Translations] --- With this site configuration: diff --git a/content/en/methods/page/Truncated.md b/content/en/methods/page/Truncated.md index b4ec7ce16..8c2573069 100644 --- a/content/en/methods/page/Truncated.md +++ b/content/en/methods/page/Truncated.md @@ -3,11 +3,10 @@ title: Truncated description: Reports whether the content length exceeds the summary length. categories: [] keywords: [] -action: - related: - - methods/page/Summary - returnType: bool - signatures: [PAGE.Truncated] +params: + functions_and_methods: + returnType: bool + signatures: [PAGE.Truncated] --- You can define a [summary] manually, in front matter, or automatically. A manual summary takes precedence over a front matter summary, and a front matter summary takes precedence over an automatic summary. @@ -26,6 +25,5 @@ The `Truncated` method returns `true` if the content length exceeds the summary {{ end }} ``` -{{% note %}} -The `Truncated` method returns `false` if you define the summary in front matter. -{{% /note %}} +> [!note] +> The `Truncated` method returns `false` if you define the summary in front matter. diff --git a/content/en/methods/page/Type.md b/content/en/methods/page/Type.md index 2a2a5c731..6f855fbe3 100644 --- a/content/en/methods/page/Type.md +++ b/content/en/methods/page/Type.md @@ -3,15 +3,13 @@ title: Type description: Returns the content type of the given page. categories: [] keywords: [] -action: - related: - - methods/page/Kind - - methods/page/Layout - returnType: string - signatures: [PAGE.Type] +params: + functions_and_methods: + returnType: string + signatures: [PAGE.Type] --- -The `Type` method on a `Page` object returns the [content type](g) of the given page. The content type is defined by the `type` field in front matter, or inferred from the top-level directory name if the `type` field in front matter is not defined. +The `Type` method on a `Page` object returns the [content type](g) of the given page. The content type is defined by the `type` field in front matter, or inferred from the top-level directory name if the `type` field in front matter is not defined. With this content structure: diff --git a/content/en/methods/page/Weight.md b/content/en/methods/page/Weight.md index 10f481baf..c14af0257 100644 --- a/content/en/methods/page/Weight.md +++ b/content/en/methods/page/Weight.md @@ -3,10 +3,10 @@ title: Weight description: Returns the weight of the given page as defined in front matter. categories: [] keywords: [] -action: - related: [] - returnType: int - signatures: [PAGE.Weight] +params: + functions_and_methods: + returnType: int + signatures: [PAGE.Weight] --- The `Weight` method on a `Page` object returns the [weight](g) of the given page as defined in front matter. diff --git a/content/en/methods/page/WordCount.md b/content/en/methods/page/WordCount.md index 70fe407ab..3950244ca 100644 --- a/content/en/methods/page/WordCount.md +++ b/content/en/methods/page/WordCount.md @@ -3,12 +3,10 @@ title: WordCount description: Returns the number of words in the content of the given page. categories: [] keywords: [] -action: - related: - - methods/page/FuzzyWordCount - - methods/page/ReadingTime - returnType: int - signatures: [PAGE.WordCount] +params: + functions_and_methods: + returnType: int + signatures: [PAGE.WordCount] --- ```go-html-template diff --git a/content/en/methods/page/_common/_index.md b/content/en/methods/page/_common/_index.md deleted file mode 100644 index 4328d4d14..000000000 --- a/content/en/methods/page/_common/_index.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -cascade: - _build: - list: never - publishResources: false - render: never ---- - - diff --git a/content/en/methods/page/_common/output-format-methods.md b/content/en/methods/page/_common/output-format-methods.md deleted file mode 100644 index 5390e7b46..000000000 --- a/content/en/methods/page/_common/output-format-methods.md +++ /dev/null @@ -1,27 +0,0 @@ ---- -_comment: Do not remove front matter. ---- - -Get IDENTIFIER -: (`any`) Returns the `OutputFormat` object with the given identifier. - -MediaType -: (`media.Type`) Returns the media type of the output format. - -MediaType.MainType -: (`string`) Returns the main type of the output format's media type. - -MediaType.SubType -: (`string`) Returns the subtype of the current format's media type. - -Name -: (`string`) Returns the output identifier of the output format. - -Permalink -: (`string`) Returns the permalink of the page generated by the current output format. - -Rel -: (`string`) Returns the `rel` value of the output format, either the default or as defined in the site configuration. - -RelPermalink -: (`string`) Returns the relative permalink of the page generated by the current output format. diff --git a/content/en/methods/page/_index.md b/content/en/methods/page/_index.md index 6dfaad9ae..c7ae7ad5d 100644 --- a/content/en/methods/page/_index.md +++ b/content/en/methods/page/_index.md @@ -4,10 +4,5 @@ linkTitle: Page description: Use these methods with a Page object. categories: [] keywords: [] -menu: - docs: - parent: methods aliases: [/variables/page/] --- - -Use these methods with a Page object. diff --git a/content/en/methods/pager/First.md b/content/en/methods/pager/First.md index 85e2e0dd3..9cd58989b 100644 --- a/content/en/methods/pager/First.md +++ b/content/en/methods/pager/First.md @@ -3,16 +3,10 @@ title: First description: Returns the first pager in the pager collection. categories: [] keywords: [] -action: - related: - - methods/pager/Last - - methods/pager/Prev - - methods/pager/Next - - methods/pager/HasPrev - - methods/pager/HasNext - - methods/page/Paginate - returnType: page.Pager - signatures: [PAGER.First] +params: + functions_and_methods: + returnType: page.Pager + signatures: [PAGER.First] --- Use the `First` method to build navigation between pagers. diff --git a/content/en/methods/pager/HasNext.md b/content/en/methods/pager/HasNext.md index e7550d788..cf3688efd 100644 --- a/content/en/methods/pager/HasNext.md +++ b/content/en/methods/pager/HasNext.md @@ -3,16 +3,10 @@ title: HasNext description: Reports whether there is a pager after the current pager. categories: [] keywords: [] -action: - related: - - methods/pager/HasPrev - - methods/pager/Prev - - methods/pager/Next - - methods/pager/First - - methods/pager/Last - - methods/page/Paginate - returnType: bool - signatures: [PAGER.HasNext] +params: + functions_and_methods: + returnType: bool + signatures: [PAGER.HasNext] --- Use the `HasNext` method to build navigation between pagers. diff --git a/content/en/methods/pager/HasPrev.md b/content/en/methods/pager/HasPrev.md index 00d5c1dea..4b486b7c5 100644 --- a/content/en/methods/pager/HasPrev.md +++ b/content/en/methods/pager/HasPrev.md @@ -3,16 +3,10 @@ title: HasPrev description: Reports whether there is a pager before the current pager. categories: [] keywords: [] -action: - related: - - methods/pager/HasNext - - methods/pager/Prev - - methods/pager/Next - - methods/pager/First - - methods/pager/Last - - methods/page/Paginate - returnType: bool - signatures: [PAGER.HasPrev] +params: + functions_and_methods: + returnType: bool + signatures: [PAGER.HasPrev] --- Use the `HasPrev` method to build navigation between pagers. diff --git a/content/en/methods/pager/Last.md b/content/en/methods/pager/Last.md index 074a46943..71dea183d 100644 --- a/content/en/methods/pager/Last.md +++ b/content/en/methods/pager/Last.md @@ -3,16 +3,10 @@ title: Last description: Returns the last pager in the pager collection. categories: [] keywords: [] -action: - related: - - methods/pager/First - - methods/pager/Prev - - methods/pager/Next - - methods/pager/HasPrev - - methods/pager/HasNext - - methods/page/Paginate - returnType: page.Pager - signatures: [PAGER.Last] +params: + functions_and_methods: + returnType: page.Pager + signatures: [PAGER.Last] --- Use the `Last` method to build navigation between pagers. diff --git a/content/en/methods/pager/Next.md b/content/en/methods/pager/Next.md index 099ac198e..d7ea9caa4 100644 --- a/content/en/methods/pager/Next.md +++ b/content/en/methods/pager/Next.md @@ -3,16 +3,10 @@ title: Next description: Returns the next pager in the pager collection. categories: [] keywords: [] -action: - related: - - methods/pager/Prev - - methods/pager/HasPrev - - methods/pager/HasNext - - methods/pager/First - - methods/pager/Last - - methods/page/Paginate - returnType: page.Pager - signatures: [PAGER.Next] +params: + functions_and_methods: + returnType: page.Pager + signatures: [PAGER.Next] --- Use the `Next` method to build navigation between pagers. diff --git a/content/en/methods/pager/NumberOfElements.md b/content/en/methods/pager/NumberOfElements.md index 3980cdfe2..9f88126fc 100644 --- a/content/en/methods/pager/NumberOfElements.md +++ b/content/en/methods/pager/NumberOfElements.md @@ -3,12 +3,10 @@ title: NumberOfElements description: Returns the number of pages in the current pager. categories: [] keywords: [] -action: - related: - - methods/pager/TotalNumberOfElements - - methods/page/Paginate - returnType: int - signatures: [PAGER.NumberOfElements] +params: + functions_and_methods: + returnType: int + signatures: [PAGER.NumberOfElements] --- ```go-html-template diff --git a/content/en/methods/pager/PageGroups.md b/content/en/methods/pager/PageGroups.md index 9dee18c0d..46f6d81cb 100644 --- a/content/en/methods/pager/PageGroups.md +++ b/content/en/methods/pager/PageGroups.md @@ -3,11 +3,10 @@ title: PageGroups description: Returns the page groups in the current pager. categories: [] keywords: [] -action: - related: - - methods/page/Paginate - returnType: page.PagesGroup - signatures: [PAGER.PageGroups] +params: + functions_and_methods: + returnType: page.PagesGroup + signatures: [PAGER.PageGroups] --- Use the `PageGroups` method with any of the [grouping methods]. diff --git a/content/en/methods/pager/PageNumber.md b/content/en/methods/pager/PageNumber.md index 0d99c5a15..6d0b8e35d 100644 --- a/content/en/methods/pager/PageNumber.md +++ b/content/en/methods/pager/PageNumber.md @@ -3,12 +3,10 @@ title: PageNumber description: Returns the current pager's number within the pager collection. categories: [] keywords: [] -action: - related: - - methods/pager/TotalPages - - methods/page/Paginate - returnType: int - signatures: [PAGER.PageNumber] +params: + functions_and_methods: + returnType: int + signatures: [PAGER.PageNumber] --- Use the `PageNumber` method to build navigation between pagers. diff --git a/content/en/methods/pager/PageSize.md b/content/en/methods/pager/PageSize.md index d69c31207..5aad88682 100644 --- a/content/en/methods/pager/PageSize.md +++ b/content/en/methods/pager/PageSize.md @@ -3,15 +3,15 @@ title: PageSize description: Returns the number of pages per pager. categories: [] keywords: [] -action: - related: [] - returnType: int - signatures: [PAGER.PageSize] +params: + functions_and_methods: + returnType: int + signatures: [PAGER.PageSize] expiryDate: 2026-06-09 # deprecated 2024-06-09 in v0.128.0 --- -{{% deprecated-in 0.128.0 %}} +{{< deprecated-in 0.128.0 >}} Use [`PAGER.PagerSize`] instead. [`PAGER.PagerSize`]: /methods/pager/pagersize/ -{{% /deprecated-in %}} +{{< /deprecated-in >}} diff --git a/content/en/methods/pager/PagerSize.md b/content/en/methods/pager/PagerSize.md index 5f5f7d3a8..b2397a3e8 100644 --- a/content/en/methods/pager/PagerSize.md +++ b/content/en/methods/pager/PagerSize.md @@ -3,11 +3,10 @@ title: PagerSize description: Returns the number of pages per pager. categories: [] keywords: [] -action: - related: - - methods/page/Paginate - returnType: int - signatures: [PAGER.PagerSize] +params: + functions_and_methods: + returnType: int + signatures: [PAGER.PagerSize] --- {{< new-in 0.128.0 />}} diff --git a/content/en/methods/pager/Pagers.md b/content/en/methods/pager/Pagers.md index 5f167c13e..e431069f4 100644 --- a/content/en/methods/pager/Pagers.md +++ b/content/en/methods/pager/Pagers.md @@ -3,11 +3,10 @@ title: Pagers description: Returns the pagers collection. categories: [] keywords: [] -action: - related: - - methods/page/Paginate - returnType: page.pagers - signatures: [PAGER.Pagers] +params: + functions_and_methods: + returnType: page.pagers + signatures: [PAGER.Pagers] --- Use the `Pagers` method to build navigation between pagers. diff --git a/content/en/methods/pager/Pages.md b/content/en/methods/pager/Pages.md index 1c049d53b..6e5772a48 100644 --- a/content/en/methods/pager/Pages.md +++ b/content/en/methods/pager/Pages.md @@ -3,11 +3,10 @@ title: Pages description: Returns the pages in the current pager. categories: [] keywords: [] -action: - related: - - methods/page/Paginate - returnType: page.Pages - signatures: [PAGER.Pages] +params: + functions_and_methods: + returnType: page.Pages + signatures: [PAGER.Pages] --- ```go-html-template diff --git a/content/en/methods/pager/Prev.md b/content/en/methods/pager/Prev.md index c129c6a5a..eb79f96e9 100644 --- a/content/en/methods/pager/Prev.md +++ b/content/en/methods/pager/Prev.md @@ -3,16 +3,10 @@ title: Prev description: Returns the previous pager in the pager collection. categories: [] keywords: [] -action: - related: - - methods/pager/Next - - methods/pager/HasPrev - - methods/pager/HasNext - - methods/pager/First - - methods/pager/Last - - methods/page/Paginate - returnType: page.Pager - signatures: [PAGER.Prev] +params: + functions_and_methods: + returnType: page.Pager + signatures: [PAGER.Prev] --- Use the `Prev` method to build navigation between pagers. diff --git a/content/en/methods/pager/TotalNumberOfElements.md b/content/en/methods/pager/TotalNumberOfElements.md index 3cd1c8dad..ad29a01f3 100644 --- a/content/en/methods/pager/TotalNumberOfElements.md +++ b/content/en/methods/pager/TotalNumberOfElements.md @@ -3,12 +3,10 @@ title: TotalNumberOfElements description: Returns the number of pages in the pager collection. categories: [] keywords: [] -action: - related: - - methods/pager/NumberOfElements - - methods/page/Paginate - returnType: int - signatures: [PAGER.TotalNumberOfElements] +params: + functions_and_methods: + returnType: int + signatures: [PAGER.TotalNumberOfElements] --- ```go-html-template diff --git a/content/en/methods/pager/TotalPages.md b/content/en/methods/pager/TotalPages.md index e305beeff..63da5d786 100644 --- a/content/en/methods/pager/TotalPages.md +++ b/content/en/methods/pager/TotalPages.md @@ -3,12 +3,10 @@ title: TotalPages description: Returns the number of pagers in the pager collection. categories: [] keywords: [] -action: - related: - - methods/pager/PageNumber - - methods/page/Paginate - returnType: int - signatures: [PAGER.TotalPages] +params: + functions_and_methods: + returnType: int + signatures: [PAGER.TotalPages] --- Use the `TotalPages` method to build navigation between pagers. diff --git a/content/en/methods/pager/URL.md b/content/en/methods/pager/URL.md index 3daddbbd5..a3558ba7c 100644 --- a/content/en/methods/pager/URL.md +++ b/content/en/methods/pager/URL.md @@ -3,11 +3,10 @@ title: URL description: Returns the URL of the current pager relative to the site root. categories: [] keywords: [] -action: - related: - - methods/page/Paginate - returnType: string - signatures: [PAGER.URL] +params: + functions_and_methods: + returnType: string + signatures: [PAGER.URL] --- Use the `URL` method to build navigation between pagers. diff --git a/content/en/methods/pager/_index.md b/content/en/methods/pager/_index.md index 58a1def7b..7a79bf42f 100644 --- a/content/en/methods/pager/_index.md +++ b/content/en/methods/pager/_index.md @@ -1,14 +1,6 @@ --- title: Pager methods linkTitle: Pager -description: Use these methods with Pager objects when paginating a list page. +description: Use these methods with Pager objects when building navigation for a paginated list page. keywords: [] -menu: - docs: - identifier: - parent: methods --- - -Use these methods with Pager objects when building navigation for a [paginated] list page. - -[paginated]: /templates/pagination/ diff --git a/content/en/methods/pages/ByDate.md b/content/en/methods/pages/ByDate.md index eb4e86535..18f1b985e 100644 --- a/content/en/methods/pages/ByDate.md +++ b/content/en/methods/pages/ByDate.md @@ -3,18 +3,15 @@ title: ByDate description: Returns the given page collection sorted by date in ascending order. categories: [] keywords: [] -action: - related: - - methods/pages/ByExpiryDate - - methods/pages/ByLastMod - - methods/pages/ByPublishDate - returnType: page.Pages - signatures: [PAGES.ByDate] +params: + functions_and_methods: + returnType: page.Pages + signatures: [PAGES.ByDate] --- When sorting by date, the value is determined by your [site configuration], defaulting to the `date` field in front matter. -[site configuration]: /getting-started/configuration/#configure-dates +[site 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 41753c340..703988c4e 100644 --- a/content/en/methods/pages/ByExpiryDate.md +++ b/content/en/methods/pages/ByExpiryDate.md @@ -3,18 +3,15 @@ title: ByExpiryDate description: Returns the given page collection sorted by expiration date in ascending order. categories: [] keywords: [] -action: - related: - - methods/pages/ByDate - - methods/pages/ByLastMod - - methods/pages/ByPublishDate - returnType: page.Pages - signatures: [PAGES.ByExpiryDate] +params: + functions_and_methods: + returnType: page.Pages + signatures: [PAGES.ByExpiryDate] --- When sorting by expiration date, the value is determined by your [site configuration], defaulting to the `expiryDate` field in front matter. -[site configuration]: /getting-started/configuration/#configure-dates +[site 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 30d87f954..36244eb4d 100644 --- a/content/en/methods/pages/ByLanguage.md +++ b/content/en/methods/pages/ByLanguage.md @@ -3,10 +3,10 @@ title: ByLanguage description: Returns the given page collection sorted by language in ascending order. categories: [] keywords: [] -action: - related: [] - returnType: page.Pages - signatures: [PAGES.ByLanguage] +params: + functions_and_methods: + returnType: page.Pages + signatures: [PAGES.ByLanguage] --- ```go-html-template diff --git a/content/en/methods/pages/ByLastmod.md b/content/en/methods/pages/ByLastmod.md index 385093134..3c03d2a6e 100644 --- a/content/en/methods/pages/ByLastmod.md +++ b/content/en/methods/pages/ByLastmod.md @@ -3,18 +3,15 @@ title: ByLastmod description: Returns the given page collection sorted by last modification date in ascending order. categories: [] keywords: [] -action: - related: - - methods/pages/ByDate - - methods/pages/ByExpiryDate - - methods/pages/ByPublishDate - returnType: page.Pages - signatures: [PAGES.ByLastmod] +params: + functions_and_methods: + returnType: page.Pages + 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. -[site configuration]: /getting-started/configuration/#configure-dates +[site configuration]: /configuration/front-matter/#dates ```go-html-template {{ range .Pages.ByLastmod }} diff --git a/content/en/methods/pages/ByLength.md b/content/en/methods/pages/ByLength.md index 602b548c2..c47bf98ba 100644 --- a/content/en/methods/pages/ByLength.md +++ b/content/en/methods/pages/ByLength.md @@ -3,10 +3,10 @@ title: ByLength description: Returns the given page collection sorted by content length in ascending order. categories: [] keywords: [] -action: - related: [] - returnType: page.Pages - signatures: [PAGES.ByLength] +params: + functions_and_methods: + returnType: page.Pages + signatures: [PAGES.ByLength] --- ```go-html-template diff --git a/content/en/methods/pages/ByLinkTitle.md b/content/en/methods/pages/ByLinkTitle.md index 073b1e1ba..4a024d25a 100644 --- a/content/en/methods/pages/ByLinkTitle.md +++ b/content/en/methods/pages/ByLinkTitle.md @@ -3,12 +3,10 @@ title: ByLinkTitle description: Returns the given page collection sorted by link title in ascending order, falling back to title if link title is not defined. categories: [] keywords: [] -action: - related: - - methods/pages/ByTitle - - methods/pages/ByParam - returnType: page.Pages - signatures: [PAGES.ByLinkTitle] +params: + functions_and_methods: + returnType: page.Pages + signatures: [PAGES.ByLinkTitle] --- ```go-html-template diff --git a/content/en/methods/pages/ByParam.md b/content/en/methods/pages/ByParam.md index 9a919cc88..9544122a6 100644 --- a/content/en/methods/pages/ByParam.md +++ b/content/en/methods/pages/ByParam.md @@ -3,12 +3,10 @@ title: ByParam description: Returns the given page collection sorted by the given parameter in ascending order. categories: [] keywords: [] -action: - related: - - methods/pages/ByTitle - - methods/pages/ByLinkTitle - returnType: page.Pages - signatures: [PAGES.ByParam PARAM] +params: + functions_and_methods: + returnType: page.Pages + 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. diff --git a/content/en/methods/pages/ByPublishDate.md b/content/en/methods/pages/ByPublishDate.md index e622636a2..3dde6fd95 100644 --- a/content/en/methods/pages/ByPublishDate.md +++ b/content/en/methods/pages/ByPublishDate.md @@ -3,18 +3,15 @@ title: ByPublishDate description: Returns the given page collection sorted by publish date in ascending order. categories: [] keywords: [] -action: - related: - - methods/pages/ByDate - - methods/pages/ByExpiryDate - - methods/pages/ByLastMod - returnType: page.Pages - signatures: [PAGES.ByPublishDate] +params: + functions_and_methods: + returnType: page.Pages + signatures: [PAGES.ByPublishDate] --- When sorting by publish date, the value is determined by your [site configuration], defaulting to the `publishDate` field in front matter. -[site configuration]: /getting-started/configuration/#configure-dates +[site configuration]: /configuration/front-matter/#dates ```go-html-template {{ range .Pages.ByPublishDate }} diff --git a/content/en/methods/pages/ByTitle.md b/content/en/methods/pages/ByTitle.md index ee54d5cda..e10c41714 100644 --- a/content/en/methods/pages/ByTitle.md +++ b/content/en/methods/pages/ByTitle.md @@ -3,12 +3,10 @@ title: ByTitle description: Returns the given page collection sorted by title in ascending order. categories: [] keywords: [] -action: - related: - - methods/pages/ByLinkTitle - - methods/pages/ByParam - returnType: page.Pages - signatures: [PAGES.ByTitle] +params: + functions_and_methods: + returnType: page.Pages + signatures: [PAGES.ByTitle] --- ```go-html-template diff --git a/content/en/methods/pages/ByWeight.md b/content/en/methods/pages/ByWeight.md index 76d12e196..ba255d3c3 100644 --- a/content/en/methods/pages/ByWeight.md +++ b/content/en/methods/pages/ByWeight.md @@ -3,10 +3,10 @@ title: ByWeight description: Returns the given page collection sorted by weight in ascending order. categories: [] keywords: [] -action: - related: [] - returnType: page.Pages - signatures: [PAGES.ByWeight] +params: + functions_and_methods: + returnType: page.Pages + signatures: [PAGES.ByWeight] --- Assign a [weight](g) to a page using the `weight` field in front matter. The weight must be a non-zero integer. Lighter items float to the top, while heavier items sink to the bottom. Unweighted or zero-weighted pages are placed at the end of the collection. diff --git a/content/en/methods/pages/GroupBy.md b/content/en/methods/pages/GroupBy.md index b46a39bdf..aff0800e9 100644 --- a/content/en/methods/pages/GroupBy.md +++ b/content/en/methods/pages/GroupBy.md @@ -3,13 +3,13 @@ title: GroupBy description: Returns the given page collection grouped by the given field in ascending order. categories: [] keywords: [] -action: - related: [] - returnType: page.PagesGroup - signatures: ['PAGES.GroupBy FIELD [SORT]'] +params: + functions_and_methods: + returnType: page.PagesGroup + signatures: ['PAGES.GroupBy FIELD [SORT]'] --- -{{% include "methods/pages/_common/group-sort-order.md" %}} +{{% include "/_common/methods/pages/group-sort-order.md" %}} ```go-html-template {{ range .Pages.GroupBy "Section" }} diff --git a/content/en/methods/pages/GroupByDate.md b/content/en/methods/pages/GroupByDate.md index b29b90843..7ef4843a4 100644 --- a/content/en/methods/pages/GroupByDate.md +++ b/content/en/methods/pages/GroupByDate.md @@ -3,14 +3,10 @@ title: GroupByDate description: Returns the given page collection grouped by date in descending order. categories: [] keywords: [] -action: - related: - - methods/pages/GroupByExpiryDate - - methods/pages/GroupByLastMod - - methods/pages/GroupByParamDate - - methods/pages/GroupByPublishDate - returnType: page.PagesGroup - signatures: ['PAGES.GroupByDate LAYOUT [SORT]'] +params: + functions_and_methods: + returnType: page.PagesGroup + 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. @@ -19,9 +15,9 @@ The [layout string] has the same format as the layout string for the [`time.Form [`time.Format`]: /functions/time/format/ [layout string]: #layout-string -[site configuration]: /getting-started/configuration/#configure-dates +[site configuration]: /configuration/front-matter/#dates -{{% include "methods/pages/_common/group-sort-order.md" %}} +{{% include "/_common/methods/pages/group-sort-order.md" %}} To group content by year and month: @@ -64,4 +60,4 @@ The pages within each group will also be sorted by date, either ascending or des ## Layout string -{{% include "functions/_common/time-layout-string.md" %}} +{{% include "/_common/time-layout-string.md" %}} diff --git a/content/en/methods/pages/GroupByExpiryDate.md b/content/en/methods/pages/GroupByExpiryDate.md index 261d15fb5..d209e6c2b 100644 --- a/content/en/methods/pages/GroupByExpiryDate.md +++ b/content/en/methods/pages/GroupByExpiryDate.md @@ -3,14 +3,10 @@ title: GroupByExpiryDate description: Returns the given page collection grouped by expiration date in descending order. categories: [] keywords: [] -action: - related: - - methods/pages/GroupByDate - - methods/pages/GroupByLastMod - - methods/pages/GroupByParamDate - - methods/pages/GroupByPublishDate - returnType: page.PagesGroup - signatures: ['PAGES.GroupByExpiryDate LAYOUT [SORT]'] +params: + functions_and_methods: + returnType: page.PagesGroup + 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. @@ -19,9 +15,9 @@ The [layout string] has the same format as the layout string for the [`time.Form [`time.Format`]: /functions/time/format/ [layout string]: #layout-string -[site configuration]: /getting-started/configuration/#configure-dates +[site configuration]: /configuration/front-matter/#dates -{{% include "methods/pages/_common/group-sort-order.md" %}} +{{% include "/_common/methods/pages/group-sort-order.md" %}} To group content by year and month: @@ -64,4 +60,4 @@ The pages within each group will also be sorted by expiration date, either ascen ## Layout string -{{% include "functions/_common/time-layout-string.md" %}} +{{% include "/_common/time-layout-string.md" %}} diff --git a/content/en/methods/pages/GroupByLastmod.md b/content/en/methods/pages/GroupByLastmod.md index 4f9afdded..8729cd3c9 100644 --- a/content/en/methods/pages/GroupByLastmod.md +++ b/content/en/methods/pages/GroupByLastmod.md @@ -3,14 +3,10 @@ title: GroupByLastmod description: Returns the given page collection grouped by last modification date in descending order. categories: [] keywords: [] -action: - related: - - methods/pages/GroupByDate - - methods/pages/GroupByExpiryDate - - methods/pages/GroupByParamDate - - methods/pages/GroupByPublishDate - returnType: page.PagesGroup - signatures: ['PAGES.GroupByLastmod LAYOUT [SORT]'] +params: + functions_and_methods: + returnType: page.PagesGroup + 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. @@ -19,9 +15,9 @@ The [layout string] has the same format as the layout string for the [`time.Form [`time.Format`]: /functions/time/format/ [layout string]: #layout-string -[site configuration]: /getting-started/configuration/#configure-dates +[site configuration]: /configuration/front-matter/#dates -{{% include "methods/pages/_common/group-sort-order.md" %}} +{{% include "/_common/methods/pages/group-sort-order.md" %}} To group content by year and month: @@ -64,4 +60,4 @@ The pages within each group will also be sorted by last modification date, eithe ## Layout string -{{% include "functions/_common/time-layout-string.md" %}} +{{% include "/_common/time-layout-string.md" %}} diff --git a/content/en/methods/pages/GroupByParam.md b/content/en/methods/pages/GroupByParam.md index 9c63ab902..6764144d6 100644 --- a/content/en/methods/pages/GroupByParam.md +++ b/content/en/methods/pages/GroupByParam.md @@ -3,13 +3,13 @@ title: GroupByParam description: Returns the given page collection grouped by the given parameter in ascending order. categories: [] keywords: [] -action: - related: [] - returnType: page.PagesGroup - signatures: ['PAGES.GroupByParam PARAM [SORT]'] +params: + functions_and_methods: + returnType: page.PagesGroup + signatures: ['PAGES.GroupByParam PARAM [SORT]'] --- -{{% include "methods/pages/_common/group-sort-order.md" %}} +{{% include "/_common/methods/pages/group-sort-order.md" %}} ```go-html-template {{ range .Pages.GroupByParam "color" }} diff --git a/content/en/methods/pages/GroupByParamDate.md b/content/en/methods/pages/GroupByParamDate.md index 826d3c83e..b05a096d2 100644 --- a/content/en/methods/pages/GroupByParamDate.md +++ b/content/en/methods/pages/GroupByParamDate.md @@ -3,14 +3,10 @@ title: GroupByParamDate description: Returns the given page collection grouped by the given date parameter in descending order. categories: [] keywords: [] -action: - related: - - methods/pages/GroupByDate - - methods/pages/GroupByExpiryDate - - methods/pages/GroupByLastMod - - methods/pages/GroupByPublishDate - returnType: page.PagesGroup - signatures: ['PAGES.GroupByParamDate PARAM LAYOUT [SORT]'] +params: + functions_and_methods: + returnType: page.PagesGroup + signatures: ['PAGES.GroupByParamDate PARAM LAYOUT [SORT]'] --- 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. @@ -18,7 +14,7 @@ The [layout string] has the same format as the layout string for the [`time.Form [`time.Format`]: /functions/time/format/ [layout string]: #layout-string -{{% include "methods/pages/_common/group-sort-order.md" %}} +{{% include "/_common/methods/pages/group-sort-order.md" %}} To group content by year and month: @@ -61,4 +57,4 @@ The pages within each group will also be sorted by the parameter date, either as ## Layout string -{{% include "functions/_common/time-layout-string.md" %}} +{{% include "/_common/time-layout-string.md" %}} diff --git a/content/en/methods/pages/GroupByPublishDate.md b/content/en/methods/pages/GroupByPublishDate.md index 40e43c3b8..50e12f085 100644 --- a/content/en/methods/pages/GroupByPublishDate.md +++ b/content/en/methods/pages/GroupByPublishDate.md @@ -3,14 +3,10 @@ title: GroupByPublishDate description: Returns the given page collection grouped by publish date in descending order. categories: [] keywords: [] -action: - related: - - methods/pages/GroupByDate - - methods/pages/GroupByExpiryDate - - methods/pages/GroupByLastMod - - methods/pages/GroupByParamDate - returnType: page.PagesGroup - signatures: ['PAGES.GroupByPublishDate LAYOUT [SORT]'] +params: + functions_and_methods: + returnType: page.PagesGroup + 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. @@ -19,9 +15,9 @@ The [layout string] has the same format as the layout string for the [`time.Form [`time.Format`]: /functions/time/format/ [layout string]: #layout-string -[site configuration]: /getting-started/configuration/#configure-dates +[site configuration]: /configuration/front-matter/#dates -{{% include "methods/pages/_common/group-sort-order.md" %}} +{{% include "/_common/methods/pages/group-sort-order.md" %}} To group content by year and month: @@ -64,4 +60,4 @@ The pages within each group will also be sorted by publish date, either ascendin ## Layout string -{{% include "functions/_common/time-layout-string.md" %}} +{{% include "/_common/time-layout-string.md" %}} diff --git a/content/en/methods/pages/Len.md b/content/en/methods/pages/Len.md index 0a5989a1a..85b3267cd 100644 --- a/content/en/methods/pages/Len.md +++ b/content/en/methods/pages/Len.md @@ -3,10 +3,10 @@ title: Len description: Returns the number of pages in the given page collection. categories: [] keywords: [] -action: - related: [] - returnType: int - signatures: [PAGES.Len] +params: + functions_and_methods: + returnType: int + signatures: [PAGES.Len] --- ```go-html-template diff --git a/content/en/methods/pages/Limit.md b/content/en/methods/pages/Limit.md index bf889fd7e..6ee3de24d 100644 --- a/content/en/methods/pages/Limit.md +++ b/content/en/methods/pages/Limit.md @@ -3,10 +3,10 @@ title: Limit description: Returns the first N pages from the given page collection. categories: [] keywords: [] -action: - related: [] - returnType: page.Pages - signatures: [PAGES.Limit NUMBER] +params: + functions_and_methods: + returnType: page.Pages + signatures: [PAGES.Limit NUMBER] --- ```go-html-template diff --git a/content/en/methods/pages/Next.md b/content/en/methods/pages/Next.md index dcf1231ac..ce091c1ab 100644 --- a/content/en/methods/pages/Next.md +++ b/content/en/methods/pages/Next.md @@ -3,15 +3,10 @@ title: Next description: Returns the next page in a page collection, relative to the given page. categories: [] keywords: [] -action: - related: - - methods/pages/Prev - - methods/page/Next - - methods/page/Prev - - methods/page/NextInSection - - methods/page/PrevInSection - returnType: page.Page - signatures: [PAGES.Next PAGE] +params: + functions_and_methods: + returnType: page.Page + signatures: [PAGES.Next PAGE] --- -{{% include "methods/pages/_common/next-and-prev.md" %}} +{{% include "/_common/methods/pages/next-and-prev.md" %}} diff --git a/content/en/methods/pages/Prev.md b/content/en/methods/pages/Prev.md index 2d8738521..004b9496d 100644 --- a/content/en/methods/pages/Prev.md +++ b/content/en/methods/pages/Prev.md @@ -3,15 +3,10 @@ title: Prev description: Returns the previous page in a page collection, relative to the given page. categories: [] keywords: [] -action: - related: - - methods/pages/Next - - methods/page/Next - - methods/page/Prev - - methods/page/NextInSection - - methods/page/PrevInSection - returnType: page.Pages - signatures: [PAGES.Prev PAGE] +params: + functions_and_methods: + returnType: page.Pages + signatures: [PAGES.Prev PAGE] --- -{{% include "methods/pages/_common/next-and-prev.md" %}} +{{% include "/_common/methods/pages/next-and-prev.md" %}} diff --git a/content/en/methods/pages/Related.md b/content/en/methods/pages/Related.md index a80722a0e..22eeb4dfa 100644 --- a/content/en/methods/pages/Related.md +++ b/content/en/methods/pages/Related.md @@ -3,21 +3,19 @@ title: Related description: Returns a collection of pages related to the given page. categories: [] keywords: [] -action: - related: - - methods/page/HeadingsFiltered - - functions/collections/KeyVals - returnType: page.Pages - signatures: - - PAGES.Related PAGE - - PAGES.Related OPTIONS +params: + functions_and_methods: + returnType: page.Pages + signatures: + - PAGES.Related PAGE + - PAGES.Related OPTIONS --- Based on front matter, Hugo uses several factors to identify content related to the given page. Use the default [related content configuration], or tune the results to the desired indices and parameters. See [details]. The argument passed to the `Related` method may be a `Page` or an options map. For example, to pass the current page: -{{< code file=layouts/_default/single.html >}} +```go-html-template {file="layouts/_default/single.html"} {{ with .Site.RegularPages.Related . | first 5 }}

Related pages:

    @@ -26,11 +24,11 @@ The argument passed to the `Related` method may be a `Page` or an options map. F {{ end }}
{{ end }} -{{< /code >}} +``` To pass an options map: -{{< code file=layouts/_default/single.html >}} +```go-html-template {file="layouts/_default/single.html"} {{ $opts := dict "document" . "indices" (slice "tags" "keywords") @@ -43,7 +41,7 @@ To pass an options map: {{ end }} {{ end }} -{{< /code >}} +``` ## Options @@ -73,5 +71,5 @@ A contrived example using all of the above: }} ``` -[details]: /content-management/related/ -[related content configuration]: /content-management/related/ +[details]: /content-management/related-content/ +[related content configuration]: /configuration/related-content/ diff --git a/content/en/methods/pages/Reverse.md b/content/en/methods/pages/Reverse.md index e03e0ea47..23c4b0324 100644 --- a/content/en/methods/pages/Reverse.md +++ b/content/en/methods/pages/Reverse.md @@ -3,10 +3,10 @@ title: Reverse description: Returns the given page collection in reverse order. categories: [] keywords: [] -action: - related: [] - returnType: page.Pages - signatures: [PAGES.Reverse] +params: + functions_and_methods: + returnType: page.Pages + signatures: [PAGES.Reverse] --- ```go-html-template diff --git a/content/en/methods/pages/_common/_index.md b/content/en/methods/pages/_common/_index.md deleted file mode 100644 index 4328d4d14..000000000 --- a/content/en/methods/pages/_common/_index.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -cascade: - _build: - list: never - publishResources: false - render: never ---- - - diff --git a/content/en/methods/pages/_index.md b/content/en/methods/pages/_index.md index d8a64f5d5..f2495ae49 100644 --- a/content/en/methods/pages/_index.md +++ b/content/en/methods/pages/_index.md @@ -4,10 +4,5 @@ linkTitle: Pages description: Use these methods with a collection of Page objects. categories: [] keywords: [] -menu: - docs: - parent: methods aliases: [/variables/pages] --- - -Use these methods with a collection of Page objects. diff --git a/content/en/methods/resource/Colors.md b/content/en/methods/resource/Colors.md index 08f63ae3f..14d0a40d8 100644 --- a/content/en/methods/resource/Colors.md +++ b/content/en/methods/resource/Colors.md @@ -3,42 +3,36 @@ title: Colors description: Applicable to images, returns a slice of the most dominant colors using a simple histogram method. categories: [] keywords: [] -action: - related: [] - returnType: '[]images.Color' - signatures: [RESOURCE.Colors] -toc: true -math: true +params: + functions_and_methods: + returnType: '[]images.Color' + signatures: [RESOURCE.Colors] --- -The `Resources.Colors` method returns a slice of the most dominant colors in an image, ordered from most dominant to least dominant. This method is fast, but if you also downsize your image you can improve performance by extracting the colors from the scaled image. +{{% include "/_common/methods/resource/global-page-remote-resources.md" %}} -{{% include "methods/resource/_common/global-page-remote-resources.md" %}} +The `Resources.Colors` method returns a slice of the most dominant colors in an image, ordered from most dominant to least dominant. This method is fast, but if you also downsize your image you can improve performance by extracting the colors from the scaled image. ## Methods Each color is an object with the following methods: -ColorHex +### ColorHex + {{< new-in 0.125.0 />}} -: (`string`) Returns the [hexadecimal color] value, prefixed with a hash sign. -Luminance +(`string`) Returns the [hexadecimal color] value, prefixed with a hash sign. + +### Luminance + {{< new-in 0.125.0 />}} -: (`float64`) Returns the [relative luminance] of the color in the sRGB colorspace in the range [0, 1]. A value of `0` represents the darkest black, while a value of `1` represents the lightest white. -{{% note %}} -Image filters such as [`images.Dither`], [`images.Padding`], and [`images.Text`] accept either hexadecimal color values or `images.Color` objects as arguments. +(`float64`) Returns the [relative luminance] of the color in the sRGB colorspace in the range [0, 1]. A value of `0` represents the darkest black, while a value of `1` represents the lightest white. -Hugo renders an `images.Color` object as a hexadecimal color value. - -[`images.Dither`]: /functions/images/dither/ -[`images.Padding`]: /functions/images/padding/ -[`images.Text`]: /functions/images/text/ -{{% /note %}} - -[hexadecimal color]: https://developer.mozilla.org/en-US/docs/Web/CSS/hex-color -[relative luminance]: https://www.w3.org/TR/WCAG21/#dfn-relative-luminance +> [!note] +> Image filters such as [`images.Dither`], [`images.Padding`], and [`images.Text`] accept either hexadecimal color values or `images.Color` objects as arguments. +> +> Hugo renders an `images.Color` object as a hexadecimal color value. ## Sorting @@ -169,7 +163,12 @@ Calculate the contrast ratio to determine WCAG conformance: {{ end }} ``` -[WCAG]: https://en.wikipedia.org/wiki/Web_Content_Accessibility_Guidelines +[`images.Dither`]: /functions/images/dither/ +[`images.Padding`]: /functions/images/padding/ +[`images.Text`]: /functions/images/text/ [contrast ratio]: https://www.w3.org/TR/WCAG21/#dfn-contrast-ratio [enhanced]: https://www.w3.org/WAI/WCAG22/quickref/?showtechniques=145#contrast-enhanced +[hexadecimal color]: https://developer.mozilla.org/en-US/docs/Web/CSS/hex-color [minimum]: https://www.w3.org/WAI/WCAG22/quickref/?showtechniques=145#contrast-minimum +[relative luminance]: https://www.w3.org/TR/WCAG21/#dfn-relative-luminance +[WCAG]: https://en.wikipedia.org/wiki/Web_Content_Accessibility_Guidelines diff --git a/content/en/methods/resource/Content.md b/content/en/methods/resource/Content.md index 4135113e9..2c2c12d3a 100644 --- a/content/en/methods/resource/Content.md +++ b/content/en/methods/resource/Content.md @@ -3,20 +3,21 @@ title: Content description: Returns the content of the given resource. categories: [] keywords: [] -action: - related: [] - returnType: any - signatures: [RESOURCE.Content] -toc: +params: + functions_and_methods: + returnType: any + signatures: [RESOURCE.Content] --- +{{% include "/_common/methods/resource/global-page-remote-resources.md" %}} + The `Content` method on a `Resource` object returns `template.HTML` when the resource type is `page`, otherwise it returns a `string`. [resource type]: /methods/resource/resourcetype/ -{{< code file=assets/quotations/kipling.txt >}} +```text {file="assets/quotations/kipling.txt"} He travels the fastest who travels alone. -{{< /code >}} +``` To get the content: @@ -57,5 +58,3 @@ To create inline JavaScript: {{ end }} ``` - -{{% include "methods/resource/_common/global-page-remote-resources.md" %}} diff --git a/content/en/methods/resource/Crop.md b/content/en/methods/resource/Crop.md index 711fc07b0..97b3b95d3 100644 --- a/content/en/methods/resource/Crop.md +++ b/content/en/methods/resource/Crop.md @@ -3,18 +3,14 @@ title: Crop description: Applicable to images, returns an image resource cropped to the given dimensions without resizing. categories: [] keywords: [] -action: - related: - - methods/resource/Fit - - methods/resource/Fill - - methods/resource/Resize - - methods/resource/Process - - functions/images/Process - returnType: images.ImageResource - signatures: [RESOURCE.Crop SPEC] -toc: true +params: + functions_and_methods: + returnType: images.ImageResource + signatures: [RESOURCE.Crop SPEC] --- +{{% include "/_common/methods/resource/global-page-remote-resources.md" %}} + Crop an image to match the given dimensions without resizing. You must provide both width and height. ```go-html-template @@ -25,9 +21,7 @@ Crop an image to match the given dimensions without resizing. You must provide b {{ end }} ``` -{{% include "methods/resource/_common/global-page-remote-resources.md" %}} - -{{% include "/methods/resource/_common/processing-spec.md" %}} +{{% include "/_common/methods/resource/processing-spec.md" %}} ## Example diff --git a/content/en/methods/resource/Data.md b/content/en/methods/resource/Data.md index b6744d1be..0709ca50a 100644 --- a/content/en/methods/resource/Data.md +++ b/content/en/methods/resource/Data.md @@ -3,18 +3,18 @@ title: Data description: Applicable to resources returned by the resources.GetRemote function, returns information from the HTTP response. categories: [] keywords: [] -action: - related: - - functions/resources/GetRemote - - methods/resource/Err - returnType: map - signatures: [RESOURCE.Data] +params: + functions_and_methods: + returnType: map + signatures: [RESOURCE.Data] --- The `Data` method on a resource returned by the [`resources.GetRemote`] function returns information from the HTTP response. [`resources.GetRemote`]: /functions/resources/getremote/ +## Example + ```go-html-template {{ $url := "https://example.org/images/a.jpg" }} {{ $opts := dict "responseHeaders" (slice "Server") }} @@ -36,30 +36,31 @@ The `Data` method on a resource returned by the [`resources.GetRemote`] function {{ end }} ``` -###### ContentLength +## Methods + +### ContentLength (`int`) The content length in bytes. -###### ContentType +### ContentType (`string`) The content type. -###### Headers +### Headers (`map[string][]string`) A map of response headers matching those requested in the [`responseHeaders`] option passed to the `resources.GetRemote` function. The header name matching is case-insensitive. In most cases there will be one value per header key. -[`responseHeaders`]: /functions/resources/getremote/#responseheaders - -###### Status +### Status (`string`) The HTTP status text. -###### StatusCode +### StatusCode (`int`) The HTTP status code. -###### TransferEncoding +### TransferEncoding (`string`) The transfer encoding. [`resources.GetRemote`]: /functions/resources/getremote/ +[`responseHeaders`]: /functions/resources/getremote/#responseheaders diff --git a/content/en/methods/resource/Err.md b/content/en/methods/resource/Err.md index 34ba6f9bc..591af8266 100644 --- a/content/en/methods/resource/Err.md +++ b/content/en/methods/resource/Err.md @@ -1,22 +1,20 @@ --- title: Err -description: Applicable to resources returned by the resources.GetRemote function, returns an error message if the HTTP request fails, else nil. +description: Applicable to resources returned by the resources.GetRemote function, returns an error message if the HTTP request fails, else nil. categories: [] keywords: [] -action: - related: - - functions/resources/GetRemote - - methods/resource/Data - returnType: resource.resourceError - signatures: [RESOURCE.Err] +params: + functions_and_methods: + returnType: resource.resourceError + signatures: [RESOURCE.Err] expiryDate: 2027-01-16 # deprecated 2025-01-16 in v0.141.0 --- -{{% deprecated-in 0.141.0 %}} +{{< deprecated-in 0.141.0 >}} Use the `try` statement instead. See [example]. [example]: /functions/go-template/try/#example -{{% /deprecated-in %}} +{{< /deprecated-in >}} The `Err` method on a resource returned by the [`resources.GetRemote`] function returns an error message if the HTTP request fails, else nil. If you do not handle the error yourself, Hugo will fail the build. @@ -58,6 +56,5 @@ To log an error as a warning instead of an error: {{ end }} ``` -{{% note %}} -An HTTP response with a 404 status code is not an HTTP request error. To handle 404 status codes, code defensively using the nested `with-else-end` construct as shown above. -{{% /note %}} +> [!note] +> An HTTP response with a 404 status code is not an HTTP request error. To handle 404 status codes, code defensively using the nested `with-else-end` construct as shown above. diff --git a/content/en/methods/resource/Exif.md b/content/en/methods/resource/Exif.md index a8e5a42aa..443a0ee1a 100644 --- a/content/en/methods/resource/Exif.md +++ b/content/en/methods/resource/Exif.md @@ -3,28 +3,35 @@ title: Exif description: Applicable to JPEG, PNG, TIFF, and WebP images, returns an EXIF object containing image metadata. categories: [] keywords: [] -action: - related: [] - returnType: exif.ExifInfo - signatures: [RESOURCE.Exif] -toc: true +params: + functions_and_methods: + returnType: exif.ExifInfo + signatures: [RESOURCE.Exif] --- +{{% include "/_common/methods/resource/global-page-remote-resources.md" %}} + Applicable to JPEG, PNG, TIFF, and WebP images, the `Exif` method on an image `Resource` object returns an [EXIF] object containing image metadata. ## Methods -Date -: (`time.Time`) Returns the image creation date/time. Format with the [`time.Format`] function. +### Date -Lat -: (`float64`) Returns the GPS latitude in degrees. +(`time.Time`) Returns the image creation date/time. Format with the [`time.Format`] function. -Long -: (`float64`) Returns the GPS longitude in degrees. +### Lat -Tags -: (`exif.Tags`) Returns a collection of the available EXIF tags for this image. You may include or exclude specific tags from this collection in the [site configuration]. +(`float64`) Returns the GPS latitude in degrees. + +### Long + +(`float64`) Returns the GPS longitude in degrees. + +### Tags + +(`exif.Tags`) Returns a collection of the available EXIF tags for this image. You may include or exclude specific tags from this collection. See [configure imaging]. + +[configure imaging]: /configuration/imaging/#exif-data ## Examples @@ -71,8 +78,5 @@ To list specific values: {{ end }} ``` -{{% include "methods/resource/_common/global-page-remote-resources.md" %}} - [exif]: https://en.wikipedia.org/wiki/Exif -[site configuration]: /content-management/image-processing/#exif-data [`time.Format`]: /functions/time/format/ diff --git a/content/en/methods/resource/Fill.md b/content/en/methods/resource/Fill.md index 8bbaf93ee..82c696c91 100644 --- a/content/en/methods/resource/Fill.md +++ b/content/en/methods/resource/Fill.md @@ -1,20 +1,16 @@ --- title: Fill -description: Applicable to images, returns an image resource cropped and resized to the given dimensions. +description: Applicable to images, returns an image resource cropped and resized to the given dimensions. categories: [] keywords: [] -action: - related: - - methods/resource/Crop - - methods/resource/Fit - - methods/resource/Resize - - methods/resource/Process - - functions/images/Process - returnType: images.ImageResource - signatures: [RESOURCE.Fill SPEC] -toc: true +params: + functions_and_methods: + returnType: images.ImageResource + signatures: [RESOURCE.Fill SPEC] --- +{{% include "/_common/methods/resource/global-page-remote-resources.md" %}} + Crop and resize an image to match the given dimensions. You must provide both width and height. ```go-html-template @@ -25,9 +21,7 @@ Crop and resize an image to match the given dimensions. You must provide both wi {{ end }} ``` -{{% include "methods/resource/_common/global-page-remote-resources.md" %}} - -{{% include "/methods/resource/_common/processing-spec.md" %}} +{{% include "/_common/methods/resource/processing-spec.md" %}} ## Example diff --git a/content/en/methods/resource/Filter.md b/content/en/methods/resource/Filter.md index 2b059c993..b83c3d8cb 100644 --- a/content/en/methods/resource/Filter.md +++ b/content/en/methods/resource/Filter.md @@ -3,14 +3,14 @@ title: Filter description: Applicable to images, applies one or more image filters to the given image resource. categories: [] keywords: [] -action: - related: - - functions/images/Filter - returnType: images.ImageResource - signatures: [RESOURCE.Filter FILTER...] -toc: true +params: + functions_and_methods: + returnType: images.ImageResource + signatures: [RESOURCE.Filter FILTER...] --- +{{% include "/_common/methods/resource/global-page-remote-resources.md" %}} + Apply one or more [image filters](#image-filters) to the given image. To apply a single filter: @@ -41,8 +41,6 @@ You can also apply image filters using the [`images.Filter`] function. [`images.Filter`]: /functions/images/filter/ -{{% include "methods/resource/_common/global-page-remote-resources.md" %}} - ## Example ```go-html-template @@ -65,4 +63,4 @@ You can also apply image filters using the [`images.Filter`] function. Use any of these filters with the `Filter` method. -{{< list-pages-in-section path=/functions/images filter=functions_images_no_filters filterType=exclude >}} +{{% list-pages-in-section path=/functions/images filter=functions_images_no_filters filterType=exclude %}} diff --git a/content/en/methods/resource/Fit.md b/content/en/methods/resource/Fit.md index 13354fe5a..7b416c4a1 100644 --- a/content/en/methods/resource/Fit.md +++ b/content/en/methods/resource/Fit.md @@ -1,20 +1,16 @@ --- title: Fit -description: Applicable to images, returns an image resource downscaled to fit the given dimensions while maintaining aspect ratio. +description: Applicable to images, returns an image resource downscaled to fit the given dimensions while maintaining aspect ratio. categories: [] keywords: [] -action: - related: - - methods/resource/Crop - - methods/resource/Fill - - methods/resource/Resize - - methods/resource/Process - - functions/images/Process - returnType: images.ImageResource - signatures: [RESOURCE.Fit SPEC] -toc: true +params: + functions_and_methods: + returnType: images.ImageResource + signatures: [RESOURCE.Fit SPEC] --- +{{% include "/_common/methods/resource/global-page-remote-resources.md" %}} + Downscale an image to fit the given dimensions while maintaining aspect ratio. You must provide both width and height. ```go-html-template @@ -25,9 +21,7 @@ Downscale an image to fit the given dimensions while maintaining aspect ratio. Y {{ end }} ``` -{{% include "methods/resource/_common/global-page-remote-resources.md" %}} - -{{% include "/methods/resource/_common/processing-spec.md" %}} +{{% include "/_common/methods/resource/processing-spec.md" %}} ## Example diff --git a/content/en/methods/resource/Height.md b/content/en/methods/resource/Height.md index dcaf6c514..cc131378a 100644 --- a/content/en/methods/resource/Height.md +++ b/content/en/methods/resource/Height.md @@ -3,13 +3,14 @@ title: Height description: Applicable to images, returns the height of the given resource. categories: [] keywords: [] -action: - related: - - methods/resource/Width - returnType: int - signatures: [RESOURCE.Height] +params: + functions_and_methods: + returnType: int + signatures: [RESOURCE.Height] --- +{{% include "/_common/methods/resource/global-page-remote-resources.md" %}} + ```go-html-template {{ with resources.Get "images/a.jpg" }} {{ .Height }} → 400 @@ -23,5 +24,3 @@ Use the `Width` and `Height` methods together when rendering an `img` element: {{ end }} ``` - -{{% include "methods/resource/_common/global-page-remote-resources.md" %}} diff --git a/content/en/methods/resource/Key.md b/content/en/methods/resource/Key.md deleted file mode 100644 index 2dbd371be..000000000 --- a/content/en/methods/resource/Key.md +++ /dev/null @@ -1,45 +0,0 @@ ---- -title: Key -description: Returns the unique key for the given resource, equivalent to its publishing path. -draft: true -categories: [] -keywords: [] -action: - related: - - methods/resource/Permalink - - methods/resource/RelPermalink - - methods/resource/Publish - returnType: string - signatures: [RESOURCE.Key] ---- - -By way of example, consider this site configuration: - -{{< code-toggle file=hugo >}} -baseURL = 'https://example.org/docs/' -{{< /code-toggle >}} - -And this template: - -```go-html-template - {{ with resources.Get "images/a.jpg" }} - {{ with resources.Copy "foo/bar/b.jpg" . }} - {{ .Key }} → foo/bar/b.jpg - - {{ .Name }} → images/a.jpg - {{ .Title }} → images/a.jpg - - {{ .RelPermalink }} → /docs/foo/bar/b.jpg - {{ end }} - {{ end }} -``` - -We used the [`resources.Copy`] function to change the publishing path. The `Key` method returns the updated path, but note that it is different than the value returned by [`RelPermalink`]. The `RelPermalink` value includes the subdirectory segment of the `baseURL` in the site configuration. - -The `Key` method is useful if you need to get the resource's publishing path without publishing the resource. Unlike the `Permalink`, `RelPermalink`, or `Publish` methods, calling `Key` will not publish the resource. - -{{% include "methods/resource/_common/global-page-remote-resources.md" %}} - -[`Permalink`]: /methods/resource/permalink/ -[`RelPermalink`]: /methods/resource/relpermalink/ -[`resources.Copy`]: /functions/resources/copy/ diff --git a/content/en/methods/resource/MediaType.md b/content/en/methods/resource/MediaType.md index 6dea8706c..7721f69ba 100644 --- a/content/en/methods/resource/MediaType.md +++ b/content/en/methods/resource/MediaType.md @@ -3,18 +3,21 @@ title: MediaType description: Returns a media type object for the given resource. categories: [] keywords: [] -action: - related: [] - returnType: media.Type - signatures: [RESOURCE.MediaType] +params: + functions_and_methods: + returnType: media.Type + signatures: [RESOURCE.MediaType] --- +{{% include "/_common/methods/resource/global-page-remote-resources.md" %}} + The `MediaType` method on a `Resource` object returns an object with additional methods. ## Methods -Type -: (`string`) The resource's media type. +### Type + +(`string`) The resource's media type. ```go-html-template {{ with resources.Get "images/a.jpg" }} @@ -22,8 +25,9 @@ Type {{ end }} ``` -MainType -: (`string`) The main type of the resource’s media type. +### MainType + +(`string`) The main type of the resource's media type. ```go-html-template {{ with resources.Get "images/a.jpg" }} @@ -31,8 +35,9 @@ MainType {{ end }} ``` -SubType -: (`string`) The subtype of the resource’s media type. This may or may not correspond to the file suffix. +### SubType + +(`string`) The subtype of the resource's media type. This may or may not correspond to the file suffix. ```go-html-template {{ with resources.Get "images/a.jpg" }} @@ -40,8 +45,9 @@ SubType {{ end }} ``` -Suffixes -: (`slice`) A slice of possible file suffixes for the resource’s media type. +### Suffixes + +(`slice`) A slice of possible file suffixes for the resource's media type. ```go-html-template {{ with resources.Get "images/a.jpg" }} @@ -49,4 +55,12 @@ Suffixes {{ end }} ``` -{{% include "methods/resource/_common/global-page-remote-resources.md" %}} +### FirstSuffix.Suffix + +(`string`) The first of the possible file suffixes for the resource's media type. + +```go-html-template +{{ with resources.Get "images/a.jpg" }} + {{ .MediaType.FirstSuffix.Suffix }} → jpg +{{ end }} +``` diff --git a/content/en/methods/resource/Name.md b/content/en/methods/resource/Name.md index 28ccf3abf..c678c96c9 100644 --- a/content/en/methods/resource/Name.md +++ b/content/en/methods/resource/Name.md @@ -3,12 +3,10 @@ title: Name description: Returns the name of the given resource as optionally defined in front matter, falling back to its file path. categories: [] keywords: [] -action: - related: - - methods/resource/Title - returnType: string - signatures: [RESOURCE.Name] -toc: true +params: + functions_and_methods: + returnType: string + signatures: [RESOURCE.Name] --- The value returned by the `Name` method on a `Resource` object depends on the resource type. diff --git a/content/en/methods/resource/Params.md b/content/en/methods/resource/Params.md index a171b3ddf..38f2ef6c2 100644 --- a/content/en/methods/resource/Params.md +++ b/content/en/methods/resource/Params.md @@ -3,10 +3,10 @@ title: Params description: Returns a map of resource parameters as defined in front matter. categories: [] keywords: [] -action: - related: [] - returnType: map - signatures: [RESOURCE.Params] +params: + functions_and_methods: + returnType: map + signatures: [RESOURCE.Params] --- Use the `Params` method with [page resources](g). It is not applicable to either [global resources](g) or [remote resources](g). diff --git a/content/en/methods/resource/Permalink.md b/content/en/methods/resource/Permalink.md index 4c87b4b46..a8ec2d323 100644 --- a/content/en/methods/resource/Permalink.md +++ b/content/en/methods/resource/Permalink.md @@ -1,16 +1,16 @@ --- title: Permalink -description: Publishes the given resource and returns its permalink. +description: Publishes the given resource and returns its permalink. categories: [] keywords: [] -action: - related: - - methods/resource/RelPermalink - - methods/resource/Publish - returnType: string - signatures: [RESOURCE.Permalink] +params: + functions_and_methods: + returnType: string + signatures: [RESOURCE.Permalink] --- +{{% include "/_common/methods/resource/global-page-remote-resources.md" %}} + The `Permalink` method on a `Resource` object writes the resource to the publish directory, typically `public`, and returns its [permalink](g). ```go-html-template @@ -18,5 +18,3 @@ The `Permalink` method on a `Resource` object writes the resource to the publish {{ .Permalink }} → https://example.org/images/a.jpg {{ end }} ``` - -{{% include "methods/resource/_common/global-page-remote-resources.md" %}} diff --git a/content/en/methods/resource/Process.md b/content/en/methods/resource/Process.md index 550b06401..fb27da54e 100644 --- a/content/en/methods/resource/Process.md +++ b/content/en/methods/resource/Process.md @@ -3,18 +3,14 @@ title: Process description: Applicable to images, returns an image resource processed with the given specification. categories: [] keywords: [] -action: - related: - - methods/resource/Crop - - methods/resource/Fit - - methods/resource/Fill - - methods/resource/Resize - - functions/images/Process - returnType: images.ImageResource - signatures: [RESOURCE.Process SPEC] -toc: true +params: + functions_and_methods: + returnType: images.ImageResource + signatures: [RESOURCE.Process SPEC] --- +{{% include "/_common/methods/resource/global-page-remote-resources.md" %}} + Process an image with the given specification. The specification can contain an optional action, one of `crop`, `fill`, `fit`, or `resize`. This means that you can use this method instead of [`Crop`], [`Fill`], [`Fit`], or [`Resize`]. ```go-html-template @@ -37,9 +33,7 @@ You can also use this method to apply simple transformations such as rotation an The `Process` method is also available as a filter, which is more effective if you need to apply multiple filters to an image. See [`images.Process`]. -{{% include "methods/resource/_common/global-page-remote-resources.md" %}} - -{{% include "/methods/resource/_common/processing-spec.md" %}} +{{% include "/_common/methods/resource/processing-spec.md" %}} ## Example diff --git a/content/en/methods/resource/Publish.md b/content/en/methods/resource/Publish.md index 05344c658..0ecdf7e74 100644 --- a/content/en/methods/resource/Publish.md +++ b/content/en/methods/resource/Publish.md @@ -3,14 +3,14 @@ title: Publish description: Publishes the given resource. categories: [] keywords: [] -action: - related: - - methods/resource/Permalink - - methods/resource/RelPermalink - returnType: nil - signatures: [RESOURCE.Publish] +params: + functions_and_methods: + returnType: nil + signatures: [RESOURCE.Publish] --- +{{% include "/_common/methods/resource/global-page-remote-resources.md" %}} + The `Publish` method on a `Resource` object writes the resource to the publish directory, typically `public`. ```go-html-template @@ -30,5 +30,3 @@ Instead of this: ```go-html-template {{ $noop := $resource.Permalink }} ``` - -{{% include "methods/resource/_common/global-page-remote-resources.md" %}} diff --git a/content/en/methods/resource/RelPermalink.md b/content/en/methods/resource/RelPermalink.md index a7226b057..d4c907bff 100644 --- a/content/en/methods/resource/RelPermalink.md +++ b/content/en/methods/resource/RelPermalink.md @@ -3,14 +3,14 @@ title: RelPermalink description: Publishes the given resource and returns its relative permalink. categories: [] keywords: [] -action: - related: - - methods/resource/Permalink - - methods/resource/Publish - returnType: string - signatures: [RESOURCE.RelPermalink] +params: + functions_and_methods: + returnType: string + signatures: [RESOURCE.RelPermalink] --- +{{% include "/_common/methods/resource/global-page-remote-resources.md" %}} + The `Permalink` method on a `Resource` object writes the resource to the publish directory, typically `public`, and returns its [relative permalink](g). ```go-html-template @@ -18,5 +18,3 @@ The `Permalink` method on a `Resource` object writes the resource to the publish {{ .RelPermalink }} → /images/a.jpg {{ end }} ``` - -{{% include "methods/resource/_common/global-page-remote-resources.md" %}} diff --git a/content/en/methods/resource/Resize.md b/content/en/methods/resource/Resize.md index 4ba054bb5..93c029ba6 100644 --- a/content/en/methods/resource/Resize.md +++ b/content/en/methods/resource/Resize.md @@ -3,17 +3,14 @@ title: Resize description: Applicable to images, returns an image resource resized to the given width and/or height. categories: [] keywords: [] -action: - related: - - methods/resource/Crop - - methods/resource/Fit - - methods/resource/Fill - - methods/resource/Process - - functions/images/Process - returnType: images.ImageResource - signatures: [RESOURCE.Resize SPEC] +params: + functions_and_methods: + returnType: images.ImageResource + signatures: [RESOURCE.Resize SPEC] --- +{{% include "/_common/methods/resource/global-page-remote-resources.md" %}} + Resize an image to the given width and/or height. If you specify both width and height, the resulting image will be disproportionally scaled unless the original image has the same aspect ratio. @@ -26,9 +23,7 @@ If you specify both width and height, the resulting image will be disproportiona {{ end }} ``` -{{% include "methods/resource/_common/global-page-remote-resources.md" %}} - -{{% include "/methods/resource/_common/processing-spec.md" %}} +{{% include "/_common/methods/resource/processing-spec.md" %}} ## Example diff --git a/content/en/methods/resource/ResourceType.md b/content/en/methods/resource/ResourceType.md index db52e7b10..0ea9c0cf9 100644 --- a/content/en/methods/resource/ResourceType.md +++ b/content/en/methods/resource/ResourceType.md @@ -3,12 +3,14 @@ title: ResourceType description: Returns the main type of the given resource's media type. categories: [] keywords: [] -action: - related: [] - returnType: string - signatures: [RESOURCE.ResourceType] +params: + functions_and_methods: + returnType: string + signatures: [RESOURCE.ResourceType] --- +{{% include "/_common/methods/resource/global-page-remote-resources.md" %}} + Common resource types include `audio`, `image`, `text`, and `video`. ```go-html-template @@ -34,10 +36,8 @@ content/ With the structure above, we can range through page resources of type `page` to build content: -{{< code file=layouts/lessons/single.html >}} +```go-html-template {file="layouts/lessons/single.html"} {{ range .Resources.ByType "page" }} {{ .Content }} {{ end }} -{{< /code >}} - -{{% include "methods/resource/_common/global-page-remote-resources.md" %}} +``` diff --git a/content/en/methods/resource/Title.md b/content/en/methods/resource/Title.md index 1a984f902..c02d29ff8 100644 --- a/content/en/methods/resource/Title.md +++ b/content/en/methods/resource/Title.md @@ -3,12 +3,10 @@ title: Title description: Returns the title of the given resource as optionally defined in front matter, falling back to a relative path or hashed file name depending on resource type. categories: [] keywords: [] -action: - related: - - methods/resource/Name - returnType: string - signatures: [RESOURCE.Title] -toc: true +params: + functions_and_methods: + returnType: string + signatures: [RESOURCE.Title] --- The value returned by the `Title` method on a `Resource` object depends on the resource type. diff --git a/content/en/methods/resource/Width.md b/content/en/methods/resource/Width.md index 8b96c95e8..e1b43f44c 100644 --- a/content/en/methods/resource/Width.md +++ b/content/en/methods/resource/Width.md @@ -3,13 +3,14 @@ title: Width description: Applicable to images, returns the width of the given resource. categories: [] keywords: [] -action: - related: - - methods/resource/Height - returnType: int - signatures: [RESOURCE.Width] +params: + functions_and_methods: + returnType: int + signatures: [RESOURCE.Width] --- +{{% include "/_common/methods/resource/global-page-remote-resources.md" %}} + ```go-html-template {{ with resources.Get "images/a.jpg" }} {{ .Width }} → 600 @@ -23,5 +24,3 @@ Use the `Width` and `Height` methods together when rendering an `img` element: {{ end }} ``` - -{{% include "methods/resource/_common/global-page-remote-resources.md" %}} diff --git a/content/en/methods/resource/_common/_index.md b/content/en/methods/resource/_common/_index.md deleted file mode 100644 index 4328d4d14..000000000 --- a/content/en/methods/resource/_common/_index.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -cascade: - _build: - list: never - publishResources: false - render: never ---- - - diff --git a/content/en/methods/resource/_common/global-page-remote-resources.md b/content/en/methods/resource/_common/global-page-remote-resources.md deleted file mode 100644 index e410df038..000000000 --- a/content/en/methods/resource/_common/global-page-remote-resources.md +++ /dev/null @@ -1,7 +0,0 @@ ---- -_comment: Do not remove front matter. ---- - -{{% note %}} -Use this method with [global resources](g), [page resources](g), or [remote resources](g). -{{% /note %}} diff --git a/content/en/methods/resource/_index.md b/content/en/methods/resource/_index.md index e9426e1a5..edfbc5b14 100644 --- a/content/en/methods/resource/_index.md +++ b/content/en/methods/resource/_index.md @@ -4,9 +4,4 @@ linkTitle: Resource description: Use these methods with global, page, and remote Resource objects. categories: [] keywords: [] -menu: - docs: - parent: methods --- - -Use these methods with global, page, and remote Resource objects. diff --git a/content/en/methods/shortcode/Get.md b/content/en/methods/shortcode/Get.md index 8874c7649..b9c01cfc4 100644 --- a/content/en/methods/shortcode/Get.md +++ b/content/en/methods/shortcode/Get.md @@ -3,49 +3,44 @@ title: Get description: Returns the value of the given argument. categories: [] keywords: [] -action: - related: - - methods/shortcode/IsNamedParams - - methods/shortcode/Params - returnType: any - signatures: [SHORTCODE.Get ARG] -toc: true +params: + functions_and_methods: + returnType: any + signatures: [SHORTCODE.Get ARG] --- Specify the argument by position or by name. When calling a shortcode within Markdown, use either positional or named argument, but not both. -{{% note %}} -Some shortcodes support positional arguments, some support named arguments, and others support both. Refer to the shortcode's documentation for usage details. -{{% /note %}} +> [!note] +> Some shortcodes support positional arguments, some support named arguments, and others support both. Refer to the shortcode's documentation for usage details. ## Positional arguments This shortcode call uses positional arguments: -{{< code file=content/about.md lang=md >}} +```text {file="content/about.md"} {{}} -{{< /code >}} +``` To retrieve arguments by position: -{{< code file=layouts/shortcodes/myshortcode.html >}} +```go-html-template {file="layouts/shortcodes/myshortcode.html"} {{ printf "%s %s." (.Get 0) (.Get 1) }} → Hello world. -{{< /code >}} +``` ## Named arguments This shortcode call uses named arguments: -{{< code file=content/about.md lang=md >}} +```text {file="content/about.md"} {{}} -{{< /code >}} +``` To retrieve arguments by name: -{{< code file=layouts/shortcodes/myshortcode.html >}} +```go-html-template {file="layouts/shortcodes/myshortcode.html"} {{ printf "%s %s." (.Get "greeting") (.Get "firstName") }} → Hello world. -{{< /code >}} +``` -{{% note %}} -Argument names are case-sensitive. -{{% /note %}} +> [!note] +> Argument names are case-sensitive. diff --git a/content/en/methods/shortcode/Inner.md b/content/en/methods/shortcode/Inner.md index ef8d05ecb..cdce4c1c3 100644 --- a/content/en/methods/shortcode/Inner.md +++ b/content/en/methods/shortcode/Inner.md @@ -3,28 +3,23 @@ title: Inner description: Returns the content between opening and closing shortcode tags, applicable when the shortcode call includes a closing tag. categories: [] keywords: [] -action: - related: - - functions/strings/Trim - - methods/page/RenderString - - functions/transform/Markdownify - - methods/shortcode/InnerDeindent - returnType: template.HTML - signatures: [SHORTCODE.Inner] -toc: true +params: + functions_and_methods: + returnType: template.HTML + signatures: [SHORTCODE.Inner] --- This content: -{{< code file=content/services.md lang=md >}} +```text {file="content/services.md"} {{}} We design the **best** widgets in the world. {{}} -{{< /code >}} +``` With this shortcode: -{{< code file=layouts/shortcodes/card.html >}} +```go-html-template {file="layouts/shortcodes/card.html"}
{{ with .Get "title" }}
{{ . }}
@@ -33,7 +28,7 @@ With this shortcode: {{ .Inner | strings.TrimSpace }}
-{{< /code >}} +``` Is rendered to: @@ -46,23 +41,17 @@ Is rendered to: ``` -{{% note %}} -Content between opening and closing shortcode tags may include leading and/or trailing newlines, depending on placement within the Markdown. Use the [`strings.TrimSpace`] function as shown above to remove both carriage returns and newlines. +> [!note] +> Content between opening and closing shortcode tags may include leading and/or trailing newlines, depending on placement within the Markdown. Use the [`strings.TrimSpace`] function as shown above to remove carriage returns and newlines. -[`strings.TrimSpace`]: /functions/strings/trimspace/ -{{% /note %}} - -{{% note %}} -In the example above, the value returned by `Inner` is Markdown, but it was rendered as plain text. Use either of the following approaches to render Markdown to HTML. -{{% /note %}} +> [!note] +> In the example above, the value returned by `Inner` is Markdown, but it was rendered as plain text. Use either of the following approaches to render Markdown to HTML. ## Use RenderString Let's modify the example above to pass the value returned by `Inner` through the [`RenderString`] method on the `Page` object: -[`RenderString`]: /methods/page/renderstring/ - -{{< code file=layouts/shortcodes/card.html >}} +```go-html-template {file="layouts/shortcodes/card.html"}
{{ with .Get "title" }}
{{ . }}
@@ -71,7 +60,7 @@ Let's modify the example above to pass the value returned by `Inner` through the {{ .Inner | strings.TrimSpace | .Page.RenderString }}
-{{< /code >}} +``` Hugo renders this to: @@ -86,18 +75,15 @@ Hugo renders this to: You can use the [`markdownify`] function instead of the `RenderString` method, but the latter is more flexible. See [details]. -[details]: /methods/page/renderstring/ -[`markdownify`]: /functions/transform/markdownify/ - ## Alternative notation Instead of calling the shortcode with the `{{}}` notation, use the `{{%/* */%}}` notation: -{{< code file=content/services.md lang=md >}} +```text {file="content/services.md"} {{%/* card title="Product Design" */%}} We design the **best** widgets in the world. {{%/* /card */%}} -{{< /code >}} +``` When you use the `{{%/* */%}}` notation, Hugo renders the entire shortcode as Markdown, requiring the following changes. @@ -112,7 +98,7 @@ This configuration is not unsafe if _you_ control the content. Read more about H Second, because we are rendering the entire shortcode as Markdown, we must adhere to the rules governing [indentation] and inclusion of [raw HTML blocks] as provided in the [CommonMark] specification. -{{< code file=layouts/shortcodes/card.html >}} +```go-html-template {file="layouts/shortcodes/card.html"}
{{ with .Get "title" }}
{{ . }}
@@ -122,7 +108,7 @@ Second, because we are rendering the entire shortcode as Markdown, we must adher {{ .Inner | strings.TrimSpace }}
-{{< /code >}} +``` The difference between this and the previous example is subtle but required. Note the change in indentation, the addition of a blank line, and removal of the `RenderString` method. @@ -143,11 +129,15 @@ The difference between this and the previous example is subtle but required. Not ``` -{{% note %}} -When using the `{{%/* */%}}` notation, do not pass the value returned by `Inner` through the `RenderString` method or the `markdownify` function. -{{% /note %}} +> [!note] +> Don't process the `Inner` value with `RenderString` or `markdownify` when using [Markdown notation] to call the shortcode. -[commonmark]: https://commonmark.org/ +[`markdownify`]: /functions/transform/markdownify/ +[`RenderString`]: /methods/page/renderstring/ +[`strings.TrimSpace`]: /functions/strings/trimspace/ +[CommonMark]: https://spec.commonmark.org/current/ +[details]: /methods/page/renderstring/ [indentation]: https://spec.commonmark.org/0.30/#indented-code-blocks -[raw html blocks]: https://spec.commonmark.org/0.30/#html-blocks +[Markdown notation]: /content-management/shortcodes/#notation +[raw HTML blocks]: https://spec.commonmark.org/0.31.2/#html-blocks [security model]: /about/security/ diff --git a/content/en/methods/shortcode/InnerDeindent.md b/content/en/methods/shortcode/InnerDeindent.md index ab4263709..0b8c8e2d8 100644 --- a/content/en/methods/shortcode/InnerDeindent.md +++ b/content/en/methods/shortcode/InnerDeindent.md @@ -1,13 +1,12 @@ --- title: InnerDeindent -description: Returns the content between opening and closing shortcode tags, with indentation removed, applicable when the shortcode call includes a closing tag. +description: Returns the content between opening and closing shortcode tags, with indentation removed, applicable when the shortcode call includes a closing tag. categories: [] keywords: [] -action: - related: - - methods/shortcode/Inner - returnType: template.HTML - signatures: [SHORTCODE.InnerDeindent] +params: + functions_and_methods: + returnType: template.HTML + signatures: [SHORTCODE.InnerDeindent] --- Similar to the [`Inner`] method, `InnerDeindent` returns the content between opening and closing shortcode tags. However, with `InnerDeindent`, indentation before the content is removed. @@ -16,7 +15,7 @@ This allows us to effectively bypass the rules governing [indentation] as provid Consider this Markdown, an unordered list with a small gallery of thumbnail images within each list item: -{{< code file=content/about.md lang=md >}} +```text {file="content/about.md"} - Gallery one {{}} @@ -30,17 +29,17 @@ Consider this Markdown, an unordered list with a small gallery of thumbnail imag ![kitten c](thumbnails/c.jpg) ![kitten d](thumbnails/d.jpg) {{}} -{{< /code >}} +``` In the example above, notice that the content between the opening and closing shortcode tags is indented by four spaces. Per the CommonMark specification, this is treated as an indented code block. With this shortcode, calling `Inner` instead of `InnerDeindent`: -{{< code file=layouts/shortcodes/gallery.html >}} +```go-html-template {file="layouts/shortcodes/gallery.html"}
{{ .Inner | strings.TrimSpace | .Page.RenderString }}
-{{< /code >}} +``` Hugo renders the Markdown to: @@ -67,11 +66,11 @@ Hugo renders the Markdown to: Although technically correct per the CommonMark specification, this is not what we want. If we remove the indentation using the `InnerDeindent` method: -{{< code file=layouts/shortcodes/gallery.html >}} +```go-html-template {file="layouts/shortcodes/gallery.html"}
{{ .InnerDeindent | strings.TrimSpace | .Page.RenderString }}
-{{< /code >}} +``` Hugo renders the Markdown to: diff --git a/content/en/methods/shortcode/IsNamedParams.md b/content/en/methods/shortcode/IsNamedParams.md index a1d93ddac..1e0a7f00e 100644 --- a/content/en/methods/shortcode/IsNamedParams.md +++ b/content/en/methods/shortcode/IsNamedParams.md @@ -3,28 +3,27 @@ title: IsNamedParams description: Reports whether the shortcode call uses named arguments. categories: [] keywords: [] -action: - related: - - methods/shortcode/Get - returnType: bool - signatures: [SHORTCODE.IsNamedParams] +params: + functions_and_methods: + returnType: bool + signatures: [SHORTCODE.IsNamedParams] --- To support both positional and named arguments when calling a shortcode, use the `IsNamedParams` method to determine how the shortcode was called. With this shortcode template: -{{< code file=layouts/shortcodes/myshortcode.html >}} +```go-html-template {file="layouts/shortcodes/myshortcode.html"} {{ if .IsNamedParams }} {{ printf "%s %s." (.Get "greeting") (.Get "firstName") }} {{ else }} {{ printf "%s %s." (.Get 0) (.Get 1) }} {{ end }} -{{< /code >}} +``` Both of these calls return the same value: -{{< code file=content/about.md lang=md >}} +```text {file="content/about.md"} {{}} {{}} -{{< /code >}} +``` diff --git a/content/en/methods/shortcode/Name.md b/content/en/methods/shortcode/Name.md index fcf92718f..b5f9b6c17 100644 --- a/content/en/methods/shortcode/Name.md +++ b/content/en/methods/shortcode/Name.md @@ -3,24 +3,22 @@ title: Name description: Returns the shortcode file name, excluding the file extension. categories: [] keywords: [] -action: - related: - - methods/shortcode/Position - - functions/fmt/Errorf - returnType: string - signatures: [SHORTCODE.Name] +params: + functions_and_methods: + returnType: string + signatures: [SHORTCODE.Name] --- The `Name` method is useful for error reporting. For example, if your shortcode requires a "greeting" argument: -{{< code file=layouts/shortcodes/myshortcode.html >}} +```go-html-template {file="layouts/shortcodes/myshortcode.html"} {{ $greeting := "" }} {{ with .Get "greeting" }} {{ $greeting = . }} {{ else }} {{ errorf "The %q shortcode requires a 'greeting' argument. See %s" .Name .Position }} {{ end }} -{{< /code >}} +``` In the absence of a "greeting" argument, Hugo will throw an error message and fail the build: diff --git a/content/en/methods/shortcode/Ordinal.md b/content/en/methods/shortcode/Ordinal.md index 41393fa22..def0c016f 100644 --- a/content/en/methods/shortcode/Ordinal.md +++ b/content/en/methods/shortcode/Ordinal.md @@ -3,29 +3,28 @@ title: Ordinal description: Returns the zero-based ordinal of the shortcode in relation to its parent. categories: [] keywords: [] -action: - related: [] - returnType: int - signatures: [SHORTCODE.Ordinal] +params: + functions_and_methods: + returnType: int + signatures: [SHORTCODE.Ordinal] --- The `Ordinal` method returns the zero-based ordinal of the shortcode in relation to its parent. If the parent is the page itself, the ordinal represents the position of this shortcode in the page content. -{{% note %}} -Hugo increments the ordinal with each shortcode call, regardless of the specific shortcode type. This means that the ordinal value is tracked sequentially across all shortcodes within a given page. -{{% /note %}} +> [!note] +> Hugo increments the ordinal with each shortcode call, regardless of the specific shortcode type. This means that the ordinal value is tracked sequentially across all shortcodes within a given page. This method is useful for, among other things, assigning unique element IDs when a shortcode is called two or more times from the same page. For example: -{{< code file=content/about.md lang=md >}} +```text {file="content/about.md"} {{}} {{}} -{{< /code >}} +``` This shortcode performs error checking, then renders an HTML `img` element with a unique `id` attribute: -{{< code file=layouts/shortcodes/img.html >}} +```go-html-template {file="layouts/shortcodes/img.html"} {{ $src := "" }} {{ with .Get "src" }} {{ $src = . }} @@ -38,7 +37,7 @@ This shortcode performs error checking, then renders an HTML `img` element with {{ else }} {{ errorf "The %q shortcode requires a 'src' argument. See %s" .Name .Position }} {{ end }} -{{< /code >}} +``` Hugo renders the page to: @@ -47,8 +46,7 @@ Hugo renders the page to: ``` -{{% note %}} -In the shortcode template above, the [`with`] statement is used to create conditional blocks. Remember that the `with` statement binds context (the dot) to its expression. Inside of a `with` block, preface shortcode method calls with a `$` to access the top level context passed into the template. +> [!note] +> In the shortcode template above, the [`with`] statement is used to create conditional blocks. Remember that the `with` statement binds context (the dot) to its expression. Inside of a `with` block, preface shortcode method calls with a `$` to access the top-level context passed into the template. [`with`]: /functions/go-template/with/ -{{% /note %}} diff --git a/content/en/methods/shortcode/Page.md b/content/en/methods/shortcode/Page.md index 8bb58fa18..774caf9fc 100644 --- a/content/en/methods/shortcode/Page.md +++ b/content/en/methods/shortcode/Page.md @@ -3,10 +3,10 @@ title: Page description: Returns the Page object from which the shortcode was called. categories: [] keywords: [] -action: - related: [] - returnType: hugolib.pageForShortcode - signatures: [SHORTCODE.Page] +params: + functions_and_methods: + returnType: hugolib.pageForShortcode + signatures: [SHORTCODE.Page] --- With this content: @@ -26,11 +26,11 @@ Calling this shortcode: We can access the front matter values using the `Page` method: -{{< code file=layouts/shortcodes/book-details.html >}} +```go-html-template {file="layouts/shortcodes/book-details.html"}
  • Title: {{ .Page.Title }}
  • Author: {{ .Page.Params.author }}
  • Published: {{ .Page.Params.publication_year }}
  • ISBN: {{ .Page.Params.isbn }}
-{{< /code >}} +``` diff --git a/content/en/methods/shortcode/Params.md b/content/en/methods/shortcode/Params.md index c0772e36a..f001e737f 100644 --- a/content/en/methods/shortcode/Params.md +++ b/content/en/methods/shortcode/Params.md @@ -3,31 +3,30 @@ title: Params description: Returns a collection of the shortcode arguments. categories: [] keywords: [] -action: - related: - - methods/shortcode/Get - returnType: any - signatures: [SHORTCODE.Params] +params: + functions_and_methods: + returnType: any + signatures: [SHORTCODE.Params] --- When you call a shortcode using positional arguments, the `Params` method returns a slice. -{{< code file=content/about.md lang=md >}} +```text {file="content/about.md"} {{}} -{{< /code >}} +``` -{{< code file=layouts/shortcodes/myshortcode.html >}} +```go-html-template {file="layouts/shortcodes/myshortcode.html"} {{ index .Params 0 }} → Hello {{ index .Params 1 }} → world -{{< /code >}} +``` When you call a shortcode using named arguments, the `Params` method returns a map. -{{< code file=content/about.md lang=md >}} +```text {file="content/about.md"} {{}} -{{< /code >}} +``` -{{< code file=layouts/shortcodes/myshortcode.html >}} +```go-html-template {file="layouts/shortcodes/myshortcode.html"} {{ .Params.greeting }} → Hello {{ .Params.name }} → world -{{< /code >}} +``` diff --git a/content/en/methods/shortcode/Parent.md b/content/en/methods/shortcode/Parent.md index 740b1ad7e..91c445d2a 100644 --- a/content/en/methods/shortcode/Parent.md +++ b/content/en/methods/shortcode/Parent.md @@ -1,31 +1,31 @@ --- title: Parent -description: Returns the parent shortcode context in nested shortcodes. +description: Returns the parent shortcode context in nested shortcodes. categories: [] keywords: [] -action: - related: [] - returnType: hugolib.ShortcodeWithPage - signatures: [SHORTCODE.Parent] +params: + functions_and_methods: + returnType: hugolib.ShortcodeWithPage + signatures: [SHORTCODE.Parent] --- This is useful for inheritance of common shortcode arguments from the root. In this contrived example, the "greeting" shortcode is the parent, and the "now" shortcode is child. -{{< code file=content/welcome.md lang=md >}} +```text {file="content/welcome.md"} {{}} Welcome. Today is {{}}. {{}} -{{< /code >}} +``` -{{< code file=layouts/shortcodes/greeting.html >}} +```go-html-template {file="layouts/shortcodes/greeting.html"}
{{ .Inner | strings.TrimSpace | .Page.RenderString }}
-{{< /code >}} +``` -{{< code file=layouts/shortcodes/now.html >}} +```go-html-template {file="layouts/shortcodes/now.html"} {{- $dateFormat := "January 2, 2006 15:04:05" }} {{- with .Params }} @@ -41,7 +41,7 @@ Welcome. Today is {{}}. {{- end }} {{- now | time.Format $dateFormat -}} -{{< /code >}} +``` The "now" shortcode formats the current time using: diff --git a/content/en/methods/shortcode/Position.md b/content/en/methods/shortcode/Position.md index 6f047c01b..24810e825 100644 --- a/content/en/methods/shortcode/Position.md +++ b/content/en/methods/shortcode/Position.md @@ -1,26 +1,24 @@ --- title: Position -description: Returns the filename and position from which the shortcode was called. +description: Returns the file name and position from which the shortcode was called. categories: [] keywords: [] -action: - related: - - methods/shortcode/Name - - functions/fmt/Errorf - returnType: text.Position - signatures: [SHORTCODE.Position] +params: + functions_and_methods: + returnType: text.Position + signatures: [SHORTCODE.Position] --- The `Position` method is useful for error reporting. For example, if your shortcode requires a "greeting" argument: -{{< code file=layouts/shortcodes/myshortcode.html >}} +```go-html-template {file="layouts/shortcodes/myshortcode.html"} {{ $greeting := "" }} {{ with .Get "greeting" }} {{ $greeting = . }} {{ else }} {{ errorf "The %q shortcode requires a 'greeting' argument. See %s" .Name .Position }} {{ end }} -{{< /code >}} +``` In the absence of a "greeting" argument, Hugo will throw an error message and fail the build: @@ -28,6 +26,5 @@ In the absence of a "greeting" argument, Hugo will throw an error message and fa ERROR The "myshortcode" shortcode requires a 'greeting' argument. See "/home/user/project/content/about.md:11:1" ``` -{{% note %}} -The position can be expensive to calculate. Limit its use to error reporting. -{{% /note %}} +> [!note] +> The position can be expensive to calculate. Limit its use to error reporting. diff --git a/content/en/methods/shortcode/Ref.md b/content/en/methods/shortcode/Ref.md index 305e1e7d8..3a877d568 100644 --- a/content/en/methods/shortcode/Ref.md +++ b/content/en/methods/shortcode/Ref.md @@ -3,27 +3,23 @@ title: Ref description: Returns the absolute URL of the page with the given path, language, and output format. categories: [] keywords: [] -action: - related: - - methods/shortcode/RelRef - - functions/urls/RelRef - - functions/urls/Ref - returnType: string - signatures: [SHORTCODE.Ref OPTIONS] +params: + functions_and_methods: + returnType: string + signatures: [SHORTCODE.Ref OPTIONS] --- -The map of option contains: +## Usage -path -: (`string`) The path to the page, relative to the `content` directory. Required. +The `Ref` method accepts a single argument: an options map. -lang -: (`string`) The language (site) to search for the page. Default is the current language. Optional. +## Options -outputFormat -: (`string`) The output format to search for the page. Default is the current output format. Optional. +{{% include "_common/ref-and-relref-options.md" %}} -The examples below show the rendered output when visiting a page on the English language version of the site: +## Examples + +The following examples show the rendered output for a page on the English version of the site: ```go-html-template {{ $opts := dict "path" "/books/book-1" }} @@ -36,9 +32,6 @@ The examples below show the rendered output when visiting a page on the English {{ .Ref $opts }} → https://example.org/de/books/book-1/index.json ``` -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. +## Error handling -{{< code-toggle file=hugo >}} -refLinksErrorLevel = 'warning' -refLinksNotFoundURL = '/some/other/url' -{{< /code-toggle >}} +{{% include "_common/ref-and-relref-error-handling.md" %}} diff --git a/content/en/methods/shortcode/RelRef.md b/content/en/methods/shortcode/RelRef.md index 4e367312b..273705a95 100644 --- a/content/en/methods/shortcode/RelRef.md +++ b/content/en/methods/shortcode/RelRef.md @@ -3,27 +3,23 @@ title: RelRef description: Returns the relative URL of the page with the given path, language, and output format. categories: [] keywords: [] -action: - related: - - methods/shortcode/Ref - - functions/urls/Ref - - functions/urls/RelRef - returnType: string - signatures: [SHORTCODE.RelRef OPTIONS] +params: + functions_and_methods: + returnType: string + signatures: [SHORTCODE.RelRef OPTIONS] --- -The map of option contains: +## Usage -path -: (`string`) The path to the page, relative to the `content` directory. Required. +The `RelRef` method accepts a single argument: an options map. -lang -: (`string`) The language (site) to search for the page. Default is the current language. Optional. +## Options -outputFormat -: (`string`) The output format to search for the page. Default is the current output format. Optional. +{{% include "_common/ref-and-relref-options.md" %}} -The examples below show the rendered output when visiting a page on the English language version of the site: +## Examples + +The following examples show the rendered output for a page on the English version of the site: ```go-html-template {{ $opts := dict "path" "/books/book-1" }} @@ -36,9 +32,6 @@ The examples below show the rendered output when visiting a page on the English {{ .RelRef $opts }} → /de/books/book-1/index.json ``` -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. +## Error handling -{{< code-toggle file=hugo >}} -refLinksErrorLevel = 'warning' -refLinksNotFoundURL = '/some/other/url' -{{< /code-toggle >}} +{{% include "_common/ref-and-relref-error-handling.md" %}} diff --git a/content/en/methods/shortcode/Scratch.md b/content/en/methods/shortcode/Scratch.md index 6dd882e24..6efec2097 100644 --- a/content/en/methods/shortcode/Scratch.md +++ b/content/en/methods/shortcode/Scratch.md @@ -3,14 +3,14 @@ title: Scratch description: Returns a "scratch pad" to store and manipulate data, scoped to the current shortcode. categories: [] keywords: [] -action: - related: [] - returnType: maps.Scratch - signatures: [SHORTCODE.Scratch] +params: + functions_and_methods: + returnType: maps.Scratch + signatures: [SHORTCODE.Scratch] expiryDate: 2026-11-18 # deprecated 2024-11-18 (soft) --- -{{% deprecated-in 0.139.0 %}} +{{< deprecated-in 0.139.0 >}} Use the [`SHORTCODE.Store`] method instead. This is a soft deprecation. This method will be removed in a future release, but the removal date has not been established. Although Hugo will not emit a warning if you continue to use this method, you should begin using `SHORTCODE.Store` as soon as possible. @@ -18,4 +18,4 @@ This is a soft deprecation. This method will be removed in a future release, but Beginning with v0.139.0 the `SHORTCODE.Scratch` method is aliased to `SHORTCODE.Store`. [`SHORTCODE.Store`]: /methods/shortcode/store/ -{{% /deprecated-in %}} +{{< /deprecated-in >}} diff --git a/content/en/methods/shortcode/Site.md b/content/en/methods/shortcode/Site.md index af2a755ee..4c5a9a9b5 100644 --- a/content/en/methods/shortcode/Site.md +++ b/content/en/methods/shortcode/Site.md @@ -3,11 +3,10 @@ title: Site description: Returns the Site object. categories: [] keywords: [] -action: - related: - - methods/page/Sites - returnType: page.siteWrapper - signatures: [SHORTCODE.Site] +params: + functions_and_methods: + returnType: page.siteWrapper + signatures: [SHORTCODE.Site] --- See [Site methods]. diff --git a/content/en/methods/shortcode/Store.md b/content/en/methods/shortcode/Store.md index 8d9a8596b..76cb9237d 100644 --- a/content/en/methods/shortcode/Store.md +++ b/content/en/methods/shortcode/Store.md @@ -3,28 +3,22 @@ title: Store description: Returns a "scratch pad" to store and manipulate data, scoped to the current shortcode. categories: [] keywords: [] -action: - related: - - methods/page/Store - - methods/site/Store - - functions/hugo/Store - - functions/collections/NewScratch - returnType: maps.Scratch - signatures: [SHORTCODE.Store] -toc: true +params: + functions_and_methods: + returnType: maps.Scratch + signatures: [SHORTCODE.Store] --- {{< new-in 0.139.0 />}} Use the `Store` method to create a [scratch pad](g) to store and manipulate data, scoped to the current shortcode. To create a scratch pad with a different [scope](g), refer to the [scope](#scope) section below. -{{% note %}} -With the introduction of the [`newScratch`] function, and the ability to [assign values to template variables] after initialization, the `Store` method within a shortcode is mostly obsolete. - -[assign values to template variables]: https://go.dev/doc/go1.11#text/template -[`newScratch`]: /functions/collections/newScratch/ -{{% /note %}} +> [!note] +> With the introduction of the [`newScratch`] function, and the ability to [assign values to template variables] after initialization, the `Store` method within a shortcode is mostly obsolete. {{% include "_common/store-methods.md" %}} {{% include "_common/scratch-pad-scope.md" %}} + +[`newScratch`]: /functions/collections/newScratch/ +[assign values to template variables]: https://go.dev/doc/go1.11#texttemplatepkgtexttemplate diff --git a/content/en/methods/shortcode/_index.md b/content/en/methods/shortcode/_index.md index 1c99adba7..0064f42aa 100644 --- a/content/en/methods/shortcode/_index.md +++ b/content/en/methods/shortcode/_index.md @@ -4,10 +4,5 @@ linkTitle: Shortcode description: Use these methods in your shortcode templates. categories: [] keywords: [] -menu: - docs: - parent: methods aliases: [/variables/shortcodes] --- - -Use these methods in your shortcode templates. diff --git a/content/en/methods/site/AllPages.md b/content/en/methods/site/AllPages.md index 7c6c21b57..90cceee8c 100644 --- a/content/en/methods/site/AllPages.md +++ b/content/en/methods/site/AllPages.md @@ -3,16 +3,13 @@ title: AllPages description: Returns a collection of all pages in all languages. categories: [] keywords: [] -action: - related: - - methods/site/Pages - - methods/site/RegularPages - - methods/site/Sections - returnType: page.Pages - signatures: [SITE.AllPages] +params: + functions_and_methods: + returnType: page.Pages + signatures: [SITE.AllPages] --- -This method returns all page [kinds](g) in all languages. That includes the home page, section pages, taxonomy pages, term pages, and regular pages. +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 ea965a568..3644443cb 100644 --- a/content/en/methods/site/BaseURL.md +++ b/content/en/methods/site/BaseURL.md @@ -3,14 +3,10 @@ title: BaseURL description: Returns the base URL as defined in the site configuration. categories: [] keywords: [] -action: - related: - - functions/urls/AbsURL - - functions/urls/AbsLangURL - - functions/urls/RelURL - - functions/urls/RelLangURL - returnType: string - signatures: [SITE.BaseURL] +params: + functions_and_methods: + returnType: string + signatures: [SITE.BaseURL] --- Site configuration: @@ -25,13 +21,12 @@ Template: {{ .Site.BaseURL }} → https://example.org/docs/ ``` -{{% note %}} -There is almost never a good reason to use this method in your templates. Its usage tends to be fragile due to misconfiguration. +> [!note] +> There is almost never a good reason to use this method in your templates. Its usage tends to be fragile due to misconfiguration. +> +> Use the [`absURL`], [`absLangURL`], [`relURL`], or [`relLangURL`] functions instead. -Use the [`absURL`], [`absLangURL`], [`relURL`], or [`relLangURL`] functions instead. - -[`absURL`]: /functions/urls/absURL/ [`absLangURL`]: /functions/urls/absLangURL/ -[`relURL`]: /functions/urls/relURL/ +[`absURL`]: /functions/urls/absURL/ [`relLangURL`]: /functions/urls/relLangURL/ -{{% /note %}} +[`relURL`]: /functions/urls/relURL/ diff --git a/content/en/methods/site/BuildDrafts.md b/content/en/methods/site/BuildDrafts.md index 0d85c78fd..4beceeb6b 100644 --- a/content/en/methods/site/BuildDrafts.md +++ b/content/en/methods/site/BuildDrafts.md @@ -3,10 +3,10 @@ title: BuildDrafts description: Reports whether the current build includes draft pages. categories: [] keywords: [] -action: - related: [] - returnType: bool - signatures: [SITE.BuildDrafts] +params: + functions_and_methods: + returnType: bool + signatures: [SITE.BuildDrafts] --- By default, draft pages are not published when building a site. You can change this behavior with a command line flag: diff --git a/content/en/methods/site/Config.md b/content/en/methods/site/Config.md index 0ff4cddec..d1b4d1f42 100644 --- a/content/en/methods/site/Config.md +++ b/content/en/methods/site/Config.md @@ -3,20 +3,17 @@ title: Config description: Returns a subset of the site configuration. categories: [] keywords: [] -action: - related: [] - returnType: page.SiteConfig - signatures: [SITE.Config] -toc: true +params: + functions_and_methods: + returnType: page.SiteConfig + 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. ## Services -These are the default service settings, typically used by Hugo's built-in templates and shortcodes. - -{{< code-toggle config=services />}} +See [configure services](/configuration/services). For example, to use Hugo's built-in Google Analytics template you must add a [Google tag ID]: @@ -37,9 +34,7 @@ You must capitalize each identifier as shown above. ## Privacy -These are the default privacy settings, typically used by Hugo's built-in templates and shortcodes: - -{{< code-toggle config=privacy />}} +See [configure privacy](/configuration/privacy). For example, to disable usage of the built-in YouTube shortcode: diff --git a/content/en/methods/site/Copyright.md b/content/en/methods/site/Copyright.md index e2ae7d2a5..dd8bdb4a3 100644 --- a/content/en/methods/site/Copyright.md +++ b/content/en/methods/site/Copyright.md @@ -1,12 +1,12 @@ --- title: Copyright -description: Returns the copyright notice as defined in the site configuration. +description: Returns the copyright notice as defined in the site configuration. categories: [] keywords: [] -action: - related: [] - returnType: string - signatures: [SITE.Copyright] +params: + functions_and_methods: + returnType: string + signatures: [SITE.Copyright] --- Site configuration: diff --git a/content/en/methods/site/Data.md b/content/en/methods/site/Data.md index 1021aad7d..296851874 100644 --- a/content/en/methods/site/Data.md +++ b/content/en/methods/site/Data.md @@ -3,25 +3,16 @@ title: Data description: Returns a data structure composed from the files in the data directory. categories: [] keywords: [] -action: - related: - - functions/collections/IndexFunction - - functions/transform/Unmarshal - - functions/collections/Where - - functions/collections/Sort - returnType: map - signatures: [SITE.Data] +params: + functions_and_methods: + returnType: map + signatures: [SITE.Data] --- 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. -[mounted]: /hugo-modules/configuration/#module-configuration-mounts - -{{% 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. - -[`transform.Unmarshal`]: /functions/transform/unmarshal/ -{{% /note %}} +> [!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: @@ -37,23 +28,23 @@ data/ And these data files: -{{< code file=data/books/fiction.yaml lang=yaml >}} +```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 -{{< /code >}} +``` -{{< code file=data/books/nonfiction.yaml lang=yaml >}} +```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 -{{< /code >}} +``` Access the data by [chaining](g) the [identifiers](g): @@ -108,3 +99,5 @@ In the template examples above, each of the keys is a valid identifier. For exam ``` [`index`]: /functions/collections/indexfunction/ +[`transform.Unmarshal`]: /functions/transform/unmarshal/ +[mounted]: /configuration/module/#mounts diff --git a/content/en/methods/site/DisqusShortname.md b/content/en/methods/site/DisqusShortname.md index f6fedf4e9..de679fd7e 100644 --- a/content/en/methods/site/DisqusShortname.md +++ b/content/en/methods/site/DisqusShortname.md @@ -3,15 +3,15 @@ title: DisqusShortname description: Returns the Disqus shortname as defined in the site configuration. categories: [] keywords: [] -action: - related: [] - returnType: string - signatures: [SITE.DisqusShortname] +params: + functions_and_methods: + returnType: string + signatures: [SITE.DisqusShortname] expiryDate: 2025-10-30 # deprecated 2023-10-30 in v0.120.0 --- -{{% deprecated-in 0.120.0 %}} +{{< deprecated-in 0.120.0 >}} Use [`Site.Config.Services.Disqus.Shortname`] instead. [`Site.Config.Services.Disqus.Shortname`]: /methods/site/config/ -{{% /deprecated-in %}} +{{< /deprecated-in >}} diff --git a/content/en/methods/site/GetPage.md b/content/en/methods/site/GetPage.md index a439a578b..2a3bd7d59 100644 --- a/content/en/methods/site/GetPage.md +++ b/content/en/methods/site/GetPage.md @@ -3,12 +3,10 @@ title: GetPage description: Returns a Page object from the given path. categories: [] keywords: [] -action: - related: - - methods/page/GetPage - returnType: page.Page - signatures: [SITE.GetPage PATH] -toc: true +params: + functions_and_methods: + returnType: page.Page + signatures: [SITE.GetPage PATH] --- The `GetPage` method is also available on `Page` objects, allowing you to specify a path relative to the current page. See [details]. diff --git a/content/en/methods/site/GoogleAnalytics.md b/content/en/methods/site/GoogleAnalytics.md index f87e1787e..e4d28bcce 100644 --- a/content/en/methods/site/GoogleAnalytics.md +++ b/content/en/methods/site/GoogleAnalytics.md @@ -3,15 +3,15 @@ title: GoogleAnalytics description: Returns the Google Analytics tracking ID as defined in the site configuration. categories: [] keywords: [] -action: - related: [] - returnType: string - signatures: [SITE.GoogleAnalytics] +params: + functions_and_methods: + returnType: string + signatures: [SITE.GoogleAnalytics] expiryDate: 2025-10-30 # deprecated 2023-10-30 in v0.120.0 --- -{{% deprecated-in 0.120.0 %}} +{{< deprecated-in 0.120.0 >}} Use [`Site.Config.Services.GoogleAnalytics.ID`] instead. [`Site.Config.Services.GoogleAnalytics.ID`]: /methods/site/config/ -{{% /deprecated-in %}} +{{< /deprecated-in >}} diff --git a/content/en/methods/site/Home.md b/content/en/methods/site/Home.md index a25491a8e..19ab61747 100644 --- a/content/en/methods/site/Home.md +++ b/content/en/methods/site/Home.md @@ -3,10 +3,10 @@ title: Home description: Returns the home Page object for the given site. categories: [] keywords: [] -action: - related: [] - returnType: page.Page - signatures: [SITE.Home] +params: + functions_and_methods: + returnType: page.Page + signatures: [SITE.Home] --- This method is useful for obtaining a link to the home page. diff --git a/content/en/methods/site/IsDevelopment.md b/content/en/methods/site/IsDevelopment.md index 51783efb9..cddd18818 100644 --- a/content/en/methods/site/IsDevelopment.md +++ b/content/en/methods/site/IsDevelopment.md @@ -3,15 +3,15 @@ title: IsDevelopment description: Reports whether the current running environment is “development”. categories: [] keywords: [] -action: - related: [] - returnType: bool - signatures: [SITE.IsDevelopment] +params: + functions_and_methods: + returnType: bool + signatures: [SITE.IsDevelopment] expiryDate: 2025-10-30 # deprecated 2023-10-30 in v0.120.0 --- -{{% deprecated-in 0.120.0 %}} +{{< deprecated-in 0.120.0 >}} Use [`hugo.IsDevelopment`] instead. [`hugo.IsDevelopment`]: /functions/hugo/isdevelopment/ -{{% /deprecated-in %}} +{{< /deprecated-in >}} diff --git a/content/en/methods/site/IsMultiLingual.md b/content/en/methods/site/IsMultiLingual.md index 10968f14d..3f9723f1c 100644 --- a/content/en/methods/site/IsMultiLingual.md +++ b/content/en/methods/site/IsMultiLingual.md @@ -3,15 +3,15 @@ title: IsMultiLingual description: Reports whether there are two or more configured languages. categories: [] keywords: [] -action: - related: [] - returnType: bool - signatures: [SITE.IsMultiLingual] +params: + functions_and_methods: + returnType: bool + signatures: [SITE.IsMultiLingual] expiryDate: 2026-03-16 # deprecated 2024-03-16 in 0.124.0 --- -{{% deprecated-in 0.124.0 %}} +{{< deprecated-in 0.124.0 >}} Use [`hugo.IsMultilingual`] instead. [`hugo.IsMultilingual`]: /functions/hugo/ismultilingual/ -{{% /deprecated-in %}} +{{< /deprecated-in >}} diff --git a/content/en/methods/site/IsServer.md b/content/en/methods/site/IsServer.md index 8fb5b7bf6..8b09c8492 100644 --- a/content/en/methods/site/IsServer.md +++ b/content/en/methods/site/IsServer.md @@ -3,15 +3,15 @@ title: IsServer description: Reports whether the built-in development server is running. categories: [] keywords: [] -action: - related: [] - returnType: bool - signatures: [SITE.IsServer] +params: + functions_and_methods: + returnType: bool + signatures: [SITE.IsServer] expiryDate: 2025-10-30 # deprecated 2023-10-30 in v0.120.0 --- -{{% deprecated-in 0.120.0 %}} +{{< deprecated-in 0.120.0 >}} Use [`hugo.IsServer`] instead. [`hugo.IsServer`]: /functions/hugo/isserver/ -{{% /deprecated-in %}} +{{< /deprecated-in >}} diff --git a/content/en/methods/site/Language.md b/content/en/methods/site/Language.md index 2400c225a..31f15b8cb 100644 --- a/content/en/methods/site/Language.md +++ b/content/en/methods/site/Language.md @@ -1,14 +1,12 @@ --- title: Language -description: Returns the language object for the given site. +description: Returns the language object for the given site. categories: [] keywords: [] -action: - related: - - methods/page/language - returnType: langs.Language - signatures: [SITE.Language] -toc: true +params: + functions_and_methods: + returnType: langs.Language + signatures: [SITE.Language] --- The `Language` method on a `Site` object returns the language object for the given site. The language object points to the language definition in the site configuration. @@ -27,7 +25,7 @@ languageName = 'Deutsch' weight = 1 {{< /code-toggle >}} -###### Lang +### Lang (`string`) The language tag as defined by [RFC 5646]. @@ -35,7 +33,7 @@ weight = 1 {{ .Site.Language.Lang }} → de ``` -###### LanguageCode +### LanguageCode (`string`) The language code from the site configuration. Falls back to `Lang` if not defined. @@ -43,7 +41,7 @@ weight = 1 {{ .Site.Language.LanguageCode }} → de-DE ``` -###### LanguageDirection +### LanguageDirection (`string`) The language direction from the site configuration, either `ltr` or `rtl`. @@ -51,7 +49,7 @@ weight = 1 {{ .Site.Language.LanguageDirection }} → ltr ``` -###### LanguageName +### LanguageName (`string`) The language name from the site configuration. @@ -59,7 +57,7 @@ weight = 1 {{ .Site.Language.LanguageName }} → Deutsch ``` -###### Weight +### 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. diff --git a/content/en/methods/site/LanguagePrefix.md b/content/en/methods/site/LanguagePrefix.md index 88808eda0..81a5e8607 100644 --- a/content/en/methods/site/LanguagePrefix.md +++ b/content/en/methods/site/LanguagePrefix.md @@ -3,12 +3,10 @@ title: LanguagePrefix description: Returns the URL language prefix, if any, for the given site. categories: [] keywords: [] -action: - related: - - functions/urls/AbsLangURL - - functions/urls/RelLangURL - returnType: string - signatures: [SITE.LanguagePrefix] +params: + functions_and_methods: + returnType: string + signatures: [SITE.LanguagePrefix] --- Consider this site configuration: diff --git a/content/en/methods/site/Languages.md b/content/en/methods/site/Languages.md index cfa1ade6b..056d6193a 100644 --- a/content/en/methods/site/Languages.md +++ b/content/en/methods/site/Languages.md @@ -3,11 +3,10 @@ title: Languages description: Returns a collection of language objects for all sites, ordered by language weight. categories: [] keywords: [] -action: - related: - - methods/site/Language - returnType: langs.Languages - signatures: [SITE.Languages] +params: + functions_and_methods: + returnType: langs.Languages + signatures: [SITE.Languages] --- 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. diff --git a/content/en/methods/site/LastChange.md b/content/en/methods/site/LastChange.md index f6017df04..e02937bf1 100644 --- a/content/en/methods/site/LastChange.md +++ b/content/en/methods/site/LastChange.md @@ -3,15 +3,15 @@ title: LastChange description: Returns the last modification date of site content. categories: [] keywords: [] -action: - related: [] - returnType: time.Time - signatures: [SITE.LastChange] +params: + functions_and_methods: + returnType: time.Time + signatures: [SITE.LastChange] expiryDate: 2026-02-19 # deprecated 2024-02-19 in v0.123.0 --- -{{% deprecated-in 0.123.0 %}} +{{< deprecated-in 0.123.0 >}} Use [`.Site.Lastmod`] instead. [`.Site.Lastmod`]: /methods/site/lastmod/ -{{% /deprecated-in %}} +{{< /deprecated-in >}} diff --git a/content/en/methods/site/Lastmod.md b/content/en/methods/site/Lastmod.md index f1663db49..38f6da2fa 100644 --- a/content/en/methods/site/Lastmod.md +++ b/content/en/methods/site/Lastmod.md @@ -3,10 +3,10 @@ title: Lastmod description: Returns the last modification date of site content. categories: [] keywords: [] -action: - related: [] - returnType: time.Time - signatures: [SITE.Lastmod] +params: + functions_and_methods: + returnType: time.Time + signatures: [SITE.Lastmod] --- {{< new-in 0.123.0 />}} diff --git a/content/en/methods/site/MainSections.md b/content/en/methods/site/MainSections.md index aa6e84bda..bee4f2d57 100644 --- a/content/en/methods/site/MainSections.md +++ b/content/en/methods/site/MainSections.md @@ -1,18 +1,17 @@ --- 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 the site configuration, falling back to the top-level section with the most pages. categories: [] keywords: [] -action: - related: [] - returnType: '[]string' - signatures: [SITE.MainSections] +params: + functions_and_methods: + returnType: '[]string' + signatures: [SITE.MainSections] --- Site configuration: {{< code-toggle file=hugo >}} -[params] mainSections = ['books','films'] {{< /code-toggle >}} @@ -22,7 +21,7 @@ Template: {{ .Site.MainSections }} → [books films] ``` -If `params.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 the site 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: @@ -44,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 `params.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 site authors to set `mainSections` in their site configuration. Then your home template can do something like this: diff --git a/content/en/methods/site/Menus.md b/content/en/methods/site/Menus.md index e51980c2e..398a9b022 100644 --- a/content/en/methods/site/Menus.md +++ b/content/en/methods/site/Menus.md @@ -3,21 +3,16 @@ title: Menus description: Returns a collection of menu objects for the given site. categories: [] keywords: [] -action: - related: - - methods/page/IsMenuCurrent - - methods/page/HasMenuCurrent - returnType: navigation.Menus - signatures: [SITE.Menus] +params: + functions_and_methods: + returnType: navigation.Menus + signatures: [SITE.Menus] --- The `Menus` method on a `Site` object returns a collection of menus, where each menu contains one or more entries, either flat or nested. Each entry points to a page within the site, or to an external resource. -{{% note %}} -Menus can be defined and localized in several ways. Please see the [menus] section for a complete explanation and examples. - -[menus]: /content-management/menus/ -{{% /note %}} +> [!note] +> Menus can be defined and localized in several ways. Please see the [menus] section for a complete explanation and examples. A site can have multiple menus. For example, a main menu and a footer menu: @@ -88,7 +83,7 @@ You will typically render a menu using a partial template. As the active menu en The example above is simplistic. Please see the [menu templates] section for more information. -[menu templates]: /templates/menu/ - [`partial`]: /functions/partials/include/ [`partialCached`]: /functions/partials/includecached/ +[menu templates]: /templates/menu/ +[menus]: /content-management/menus/ diff --git a/content/en/methods/site/Pages.md b/content/en/methods/site/Pages.md index bb684a96d..a6ba5e029 100644 --- a/content/en/methods/site/Pages.md +++ b/content/en/methods/site/Pages.md @@ -3,16 +3,13 @@ title: Pages description: Returns a collection of all pages. categories: [] keywords: [] -action: - related: - - methods/site/AllPages - - methods/site/RegularPages - - methods/site/Sections - returnType: page.Pages - signatures: [SITE.Pages] +params: + functions_and_methods: + returnType: page.Pages + signatures: [SITE.Pages] --- -This method returns all page [kinds](g) in the current language. That includes the home page, section pages, taxonomy pages, term pages, and regular pages. +This method returns all page [kinds](g) in the current language, 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/Param.md b/content/en/methods/site/Param.md index 0c2f621c8..929e30e98 100644 --- a/content/en/methods/site/Param.md +++ b/content/en/methods/site/Param.md @@ -3,10 +3,10 @@ title: Param description: Returns the site parameter with the given key. categories: [] keywords: [] -action: - related: [] - returnType: any - signatures: [SITE.Param KEY] +params: + functions_and_methods: + returnType: any + 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. diff --git a/content/en/methods/site/Params.md b/content/en/methods/site/Params.md index 418118ee3..8467be41d 100644 --- a/content/en/methods/site/Params.md +++ b/content/en/methods/site/Params.md @@ -3,13 +3,10 @@ title: Params description: Returns a map of custom parameters as defined in the site configuration. categories: [] keywords: [] -action: - related: - - functions/collections/indexFunction - - methods/page/Params - - methods/page/Param - returnType: maps.Params - signatures: [SITE.Params] +params: + functions_and_methods: + returnType: maps.Params + signatures: [SITE.Params] --- With this site configuration: diff --git a/content/en/methods/site/RegularPages.md b/content/en/methods/site/RegularPages.md index 65bafef6c..69a460529 100644 --- a/content/en/methods/site/RegularPages.md +++ b/content/en/methods/site/RegularPages.md @@ -3,16 +3,13 @@ title: RegularPages description: Returns a collection of all regular pages. categories: [] keywords: [] -action: - related: - - methods/site/AllPages - - methods/site/RegularPages - - methods/site/Sections - returnType: page.Pages - signatures: [SITE.RegularPages] +params: + functions_and_methods: + returnType: page.Pages + signatures: [SITE.RegularPages] --- -The `RegularPages` method on a `Site` object returns a collection of all [regular pages](g). +The `RegularPages` method on a `Site` object returns a collection of all [regular pages](g), in the [default sort order](g). ```go-html-template {{ range .Site.RegularPages }} @@ -20,14 +17,9 @@ The `RegularPages` method on a `Site` object returns a collection of all [regula {{ end }} ``` -By default, Hugo sorts page collections by: +{{% glossary-term "default sort order" %}} -1. The page `weight` as defined in front matter -1. The page `date` as defined in front matter -1. The page `linkTitle` as defined in front matter -1. The file path - -If the `linkTitle` is not defined, Hugo evaluates the `title` instead. +[default sort order](g) To change the sort order, use any of the `Pages` [sorting methods]. For example: diff --git a/content/en/methods/site/Sections.md b/content/en/methods/site/Sections.md index a397c5926..0ddaf0626 100644 --- a/content/en/methods/site/Sections.md +++ b/content/en/methods/site/Sections.md @@ -1,17 +1,16 @@ --- title: Sections -description: Returns a collection of first level section pages. +description: Returns a collection of top-level section pages. categories: [] keywords: [] -action: - related: - - methods/site/AllPages - - methods/site/Pages - - methods/site/RegularPages - returnType: page.Pages - signatures: [SITE.Sections] +params: + functions_and_methods: + returnType: page.Pages + signatures: [SITE.Sections] --- +The `Sections` method on a `Site` object returns a collection of top-level [section pages](g), in the [default sort order](g). + Given this content structure: ```text diff --git a/content/en/methods/site/Sites.md b/content/en/methods/site/Sites.md index ac287d3b4..cca71a40a 100644 --- a/content/en/methods/site/Sites.md +++ b/content/en/methods/site/Sites.md @@ -3,10 +3,10 @@ title: Sites description: Returns a collection of all Site objects, one for each language, ordered by default content language then by language weight. categories: [] keywords: [] -action: - related: [] - returnType: page.Sites - signatures: [SITE.Sites] +params: + functions_and_methods: + returnType: page.Sites + signatures: [SITE.Sites] --- With this site configuration: diff --git a/content/en/methods/site/Store.md b/content/en/methods/site/Store.md index dcc3a0bed..7dcf7d095 100644 --- a/content/en/methods/site/Store.md +++ b/content/en/methods/site/Store.md @@ -3,14 +3,10 @@ title: Store description: Returns a "scratch pad" to store and manipulate data, scoped to the current site. categories: [] keywords: [] -action: - related: - - methods/page/store - - functions/hugo/store - - functions/collections/NewScratch - returnType: maps.Scratch - signatures: [site.Store] -toc: true +params: + functions_and_methods: + returnType: maps.Scratch + signatures: [site.Store] --- {{< new-in 0.139.0 />}} @@ -19,7 +15,7 @@ Use the `Store` method on a `Site` object to create a [scratch pad](g) to store ## Methods -###### Set +### Set Sets the value of a given key. @@ -27,7 +23,7 @@ Sets the value of a given key. {{ site.Store.Set "greeting" "Hello" }} ``` -###### Get +### Get Gets the value of a given key. @@ -36,7 +32,7 @@ Gets the value of a given key. {{ site.Store.Get "greeting" }} → Hello ``` -###### Add +### Add Adds a given value to existing value(s) of the given key. @@ -58,9 +54,9 @@ For single values, `Add` accepts values that support Go's `+` operator. If the f {{ site.Store.Set "greetings" (slice "Hello") }} {{ site.Store.Add "greetings" (slice "Welcome" "Cheers") }} {{ site.Store.Get "greetings" }} → [Hello Welcome Cheers] -``` + ``` -###### SetInMap +### SetInMap Takes a `key`, `mapKey` and `value` and adds a map of `mapKey` and `value` to the given `key`. @@ -70,7 +66,7 @@ Takes a `key`, `mapKey` and `value` and adds a map of `mapKey` and `value` to th {{ site.Store.Get "greetings" }} → map[english:Hello french:Bonjour] ``` -###### DeleteInMap +### DeleteInMap Takes a `key` and `mapKey` and removes the map of `mapKey` from the given `key`. @@ -81,7 +77,7 @@ Takes a `key` and `mapKey` and removes the map of `mapKey` from the given `key`. {{ site.Store.Get "greetings" }} → map[french:Bonjour] ``` -###### GetSortedMapValues +### GetSortedMapValues Returns an array of values from `key` sorted by `mapKey`. @@ -91,7 +87,7 @@ Returns an array of values from `key` sorted by `mapKey`. {{ site.Store.GetSortedMapValues "greetings" }} → [Hello Bonjour] ``` -###### Delete +### Delete Removes the given key. diff --git a/content/en/methods/site/Taxonomies.md b/content/en/methods/site/Taxonomies.md index ee98d2ac5..92dc41a9b 100644 --- a/content/en/methods/site/Taxonomies.md +++ b/content/en/methods/site/Taxonomies.md @@ -3,15 +3,15 @@ title: Taxonomies description: Returns a data structure containing the site's Taxonomy objects, the terms within each Taxonomy object, and the pages to which the terms are assigned. categories: [] keywords: [] -action: - related: [] - returnType: page.TaxonomyList - signatures: [SITE.Taxonomies] +params: + functions_and_methods: + returnType: page.TaxonomyList + signatures: [SITE.Taxonomies] --- Conceptually, the `Taxonomies` method on a `Site` object returns a data structure such as: -{{< code-toggle >}} +{{< code-toggle file=hugo >}} taxonomy a: - term 1: - page 1 @@ -50,7 +50,7 @@ content/ Conceptually, the taxonomies data structure looks like: -{{< code-toggle >}} +{{< code-toggle file=hugo >}} genres: - suspense: - And Then There Were None @@ -89,13 +89,10 @@ Hugo renders this to: ``` -{{% note %}} -Hugo's taxonomy system is powerful, allowing you to classify content and create relationships between pages. - -Please see the [taxonomies] section for a complete explanation and examples. - -[taxonomies]: /content-management/taxonomies/ -{{% /note %}} +> [!note] +> Hugo's taxonomy system is powerful, allowing you to classify content and create relationships between pages. +> +> Please see the [taxonomies] section for a complete explanation and examples. ## Examples @@ -143,7 +140,7 @@ The following example displays all terms in a site's tags taxonomy: ``` This example will list all taxonomies and their terms, as well as all the content assigned to each of the terms. -{{< code file=layouts/partials/all-taxonomies.html >}} +```go-html-template {file="layouts/partials/all-taxonomies.html"} {{ with .Site.Taxonomies }} {{ $numberOfTerms := 0 }} {{ range $taxonomy, $terms := . }} @@ -174,4 +171,6 @@ This example will list all taxonomies and their terms, as well as all the conten {{ end }} {{ end }} -{{< /code >}} +``` + +[taxonomies]: /content-management/taxonomies/ diff --git a/content/en/methods/site/Title.md b/content/en/methods/site/Title.md index a357286c1..935edda0c 100644 --- a/content/en/methods/site/Title.md +++ b/content/en/methods/site/Title.md @@ -3,10 +3,10 @@ title: Title description: Returns the title as defined in the site configuration. categories: [] keywords: [] -action: - related: [] - returnType: string - signatures: [SITE.Title] +params: + functions_and_methods: + returnType: string + signatures: [SITE.Title] --- Site configuration: diff --git a/content/en/methods/site/_index.md b/content/en/methods/site/_index.md index bf322ee07..f395a3693 100644 --- a/content/en/methods/site/_index.md +++ b/content/en/methods/site/_index.md @@ -4,10 +4,5 @@ linkTitle: Site description: Use these methods with Site objects. categories: [] keywords: [] -menu: - docs: - parent: methods aliases: [/variables/site/] --- - -Use these methods with Site objects. A multilingual project will have two or more sites, one for each language. diff --git a/content/en/methods/taxonomy/Alphabetical.md b/content/en/methods/taxonomy/Alphabetical.md index 72cd1c355..af4af596c 100644 --- a/content/en/methods/taxonomy/Alphabetical.md +++ b/content/en/methods/taxonomy/Alphabetical.md @@ -3,23 +3,21 @@ title: Alphabetical description: Returns an ordered taxonomy, sorted alphabetically by term. categories: [] keywords: [] -action: - related: - - methods/taxonomy/ByCount - returnType: page.OrderedTaxonomy - signatures: [TAXONOMY.Alphabetical] -toc: true +params: + functions_and_methods: + returnType: page.OrderedTaxonomy + signatures: [TAXONOMY.Alphabetical] --- The `Alphabetical` method on a `Taxonomy` object returns an [ordered taxonomy](g), sorted alphabetically by [term](g). While a `Taxonomy` object is a [map](g), an ordered taxonomy is a [slice](g), where each element is an object that contains the term and a slice of its [weighted pages](g). -{{% include "methods/taxonomy/_common/get-a-taxonomy-object.md" %}} +{{% include "/_common/methods/taxonomy/get-a-taxonomy-object.md" %}} ## Get the ordered taxonomy -Now that we have captured the “genres” Taxonomy object, let’s get the ordered taxonomy sorted alphabetically by term: +Now that we have captured the “genres” Taxonomy object, let's get the ordered taxonomy sorted alphabetically by term: ```go-html-template {{ $taxonomyObject.Alphabetical }} @@ -37,7 +35,7 @@ To inspect the data structure: 
{{ debug.Dump $taxonomyObject.Alphabetical }}
``` -{{% include "methods/taxonomy/_common/ordered-taxonomy-element-methods.md" %}} +{{% include "/_common/methods/taxonomy/ordered-taxonomy-element-methods.md" %}} ## Example diff --git a/content/en/methods/taxonomy/ByCount.md b/content/en/methods/taxonomy/ByCount.md index 930f8953b..fbf9bb4a1 100644 --- a/content/en/methods/taxonomy/ByCount.md +++ b/content/en/methods/taxonomy/ByCount.md @@ -3,23 +3,21 @@ title: ByCount description: Returns an ordered taxonomy, sorted by the number of pages associated with each term. categories: [] keywords: [] -action: - related: - - methods/taxonomy/Alphabetical - returnType: page.OrderedTaxonomy - signatures: [TAXONOMY.ByCount] -toc: true +params: + functions_and_methods: + returnType: page.OrderedTaxonomy + signatures: [TAXONOMY.ByCount] --- The `ByCount` method on a `Taxonomy` object returns an [ordered taxonomy](g), sorted by the number of pages associated with each [term](g). While a `Taxonomy` object is a [map](g), an ordered taxonomy is a [slice](g), where each element is an object that contains the term and a slice of its [weighted pages](g). -{{% include "methods/taxonomy/_common/get-a-taxonomy-object.md" %}} +{{% include "/_common/methods/taxonomy/get-a-taxonomy-object.md" %}} ## Get the ordered taxonomy -Now that we have captured the “genres” Taxonomy object, let’s get the ordered taxonomy sorted by the number of pages associated with each term: +Now that we have captured the “genres” Taxonomy object, let's get the ordered taxonomy sorted by the number of pages associated with each term: ```go-html-template {{ $taxonomyObject.ByCount }} @@ -37,7 +35,7 @@ To inspect the data structure: 
{{ debug.Dump $taxonomyObject.ByCount }}
``` -{{% include "methods/taxonomy/_common/ordered-taxonomy-element-methods.md" %}} +{{% include "/_common/methods/taxonomy/ordered-taxonomy-element-methods.md" %}} ## Example diff --git a/content/en/methods/taxonomy/Count.md b/content/en/methods/taxonomy/Count.md index 4b756f254..76af8ee04 100644 --- a/content/en/methods/taxonomy/Count.md +++ b/content/en/methods/taxonomy/Count.md @@ -3,16 +3,15 @@ title: Count description: Returns the number of number of weighted pages to which the given term has been assigned. categories: [] keywords: [] -action: - related: [] - returnType: int - signatures: [TAXONOMY.Count TERM] -toc: true +params: + functions_and_methods: + returnType: int + signatures: [TAXONOMY.Count TERM] --- The `Count` method on a `Taxonomy` object returns the number of number of [weighted pages](g) to which the given [term](g) has been assigned. -{{% include "methods/taxonomy/_common/get-a-taxonomy-object.md" %}} +{{% include "/_common/methods/taxonomy/get-a-taxonomy-object.md" %}} ## Count the weighted pages diff --git a/content/en/methods/taxonomy/Get.md b/content/en/methods/taxonomy/Get.md index 107912493..03c184868 100644 --- a/content/en/methods/taxonomy/Get.md +++ b/content/en/methods/taxonomy/Get.md @@ -3,16 +3,15 @@ title: Get description: Returns a slice of weighted pages to which the given term has been assigned. categories: [] keywords: [] -action: - related: [] - returnType: page.WeightedPages - signatures: [TAXONOMY.Get TERM] -toc: true +params: + functions_and_methods: + returnType: page.WeightedPages + signatures: [TAXONOMY.Get TERM] --- The `Get` method on a `Taxonomy` object returns a slice of [weighted pages](g) to which the given [term](g) has been assigned. -{{% include "methods/taxonomy/_common/get-a-taxonomy-object.md" %}} +{{% include "/_common/methods/taxonomy/get-a-taxonomy-object.md" %}} ## Get the weighted pages diff --git a/content/en/methods/taxonomy/Page.md b/content/en/methods/taxonomy/Page.md index 039719b93..b0b5d3aff 100644 --- a/content/en/methods/taxonomy/Page.md +++ b/content/en/methods/taxonomy/Page.md @@ -3,10 +3,10 @@ title: Page description: Returns the taxonomy page or nil if the taxonomy has no terms. categories: [] keywords: [] -action: - related: [] - returnType: page.Page - signatures: [TAXONOMY.Page] +params: + functions_and_methods: + returnType: page.Page + signatures: [TAXONOMY.Page] --- {{< new-in 0.125.0 />}} diff --git a/content/en/methods/taxonomy/_common/_index.md b/content/en/methods/taxonomy/_common/_index.md deleted file mode 100644 index 4328d4d14..000000000 --- a/content/en/methods/taxonomy/_common/_index.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -cascade: - _build: - list: never - publishResources: false - render: never ---- - - diff --git a/content/en/methods/taxonomy/_index.md b/content/en/methods/taxonomy/_index.md index 18c7f12c9..13acdb10c 100644 --- a/content/en/methods/taxonomy/_index.md +++ b/content/en/methods/taxonomy/_index.md @@ -3,11 +3,5 @@ title: Taxonomy methods linkTitle: Taxonomy description: Use these methods with Taxonomy objects. keywords: [] -menu: - docs: - identifier: - parent: methods aliases: [/variables/taxonomy/] --- - -Use these methods with Taxonomy objects. diff --git a/content/en/methods/time/Add.md b/content/en/methods/time/Add.md index 8fd755244..e518a1633 100644 --- a/content/en/methods/time/Add.md +++ b/content/en/methods/time/Add.md @@ -3,13 +3,10 @@ title: Add description: Returns the given time plus the given duration. categories: [] keywords: [] -action: - related: - - functions/time/AsTime - - functions/time/Duration - - functions/time/ParseDuration - returnType: time.Time - signatures: [TIME.Add DURATION] +params: + functions_and_methods: + returnType: time.Time + signatures: [TIME.Add DURATION] --- ```go-html-template diff --git a/content/en/methods/time/AddDate.md b/content/en/methods/time/AddDate.md index 8537d6e25..ffc93c712 100644 --- a/content/en/methods/time/AddDate.md +++ b/content/en/methods/time/AddDate.md @@ -3,11 +3,10 @@ title: AddDate description: Returns the time corresponding to adding the given number of years, months, and days to the given time.Time value. categories: [] keywords: [] -action: - aliases: [] - related: [] - returnType: time.Time - signatures: [TIME.AddDate YEARS MONTHS DAYS] +params: + functions_and_methods: + returnType: time.Time + signatures: [TIME.AddDate YEARS MONTHS DAYS] aliases: [/functions/adddate] --- @@ -21,11 +20,10 @@ aliases: [/functions/adddate] {{ $d.AddDate -1 -1 -1 | time.Format "2006-01-02" }} → 2020-11-30 ``` -{{% note %}} -When adding months or years, Hugo normalizes the final `time.Time` value if the resulting day does not exist. For example, adding one month to 31 January produces 2 March or 3 March, depending on the year. - -See [this explanation](https://github.com/golang/go/issues/31145#issuecomment-479067967) from the Go team. -{{% /note %}} +> [!note] +> When adding months or years, Hugo normalizes the final `time.Time` value if the resulting day does not exist. For example, adding one month to 31 January produces 2 March or 3 March, depending on the year. +> +> See [this explanation](https://github.com/golang/go/issues/31145#issuecomment-479067967) from the Go team. ```go-html-template {{ $d := "2023-01-31" | time.AsTime }} diff --git a/content/en/methods/time/After.md b/content/en/methods/time/After.md index 64c6cfe67..1c8d41f64 100644 --- a/content/en/methods/time/After.md +++ b/content/en/methods/time/After.md @@ -3,13 +3,10 @@ title: After description: Reports whether TIME1 is after TIME2. categories: [] keywords: [] -action: - related: - - methods/time/Before - - methods/time/Equal - - functions/time/AsTime - returnType: bool - signatures: [TIME1.After TIME2] +params: + functions_and_methods: + returnType: bool + signatures: [TIME1.After TIME2] --- ```go-html-template diff --git a/content/en/methods/time/Before.md b/content/en/methods/time/Before.md index c3d582860..f6dc3a8e7 100644 --- a/content/en/methods/time/Before.md +++ b/content/en/methods/time/Before.md @@ -3,13 +3,10 @@ title: Before description: Reports whether TIME1 is before TIME2. categories: [] keywords: [] -action: - related: - - methods/time/After - - methods/time/Equal - - functions/time/AsTime - returnType: bool - signatures: [TIME1.Before TIME2] +params: + functions_and_methods: + returnType: bool + signatures: [TIME1.Before TIME2] --- ```go-html-template diff --git a/content/en/methods/time/Day.md b/content/en/methods/time/Day.md index 1173b8489..e9e67873c 100644 --- a/content/en/methods/time/Day.md +++ b/content/en/methods/time/Day.md @@ -3,16 +3,10 @@ title: Day description: Returns the day of the month of the given time.Time value. categories: [] keywords: [] -action: - related: - - methods/time/Year - - methods/time/Month - - methods/time/Hour - - methods/time/Minute - - methods/time/Second - - functions/time/AsTime - returnType: int - signatures: [TIME.Day] +params: + functions_and_methods: + returnType: int + signatures: [TIME.Day] --- ```go-html-template diff --git a/content/en/methods/time/Equal.md b/content/en/methods/time/Equal.md index 4d45a3ada..6db10423c 100644 --- a/content/en/methods/time/Equal.md +++ b/content/en/methods/time/Equal.md @@ -3,13 +3,10 @@ title: Equal description: Reports whether TIME1 is equal to TIME2. categories: [] keywords: [] -action: - related: - - methods/time/After - - methods/time/Before - - functions/time/AsTime - returnType: bool - signatures: [TIME1.Equal TIME2] +params: + functions_and_methods: + returnType: bool + signatures: [TIME1.Equal TIME2] --- ```go-html-template diff --git a/content/en/methods/time/Format.md b/content/en/methods/time/Format.md index 9a718b53b..8a484b74e 100644 --- a/content/en/methods/time/Format.md +++ b/content/en/methods/time/Format.md @@ -3,15 +3,10 @@ title: Format description: Returns a textual representation of the time.Time value formatted according to the layout string. categories: [] keywords: [] -action: - aliases: [] - related: - - functions/time/AsTime - - methods/time/UTC - - methods/time/Local - returnType: string - signatures: [TIME.Format LAYOUT] -toc: true +params: + functions_and_methods: + returnType: string + signatures: [TIME.Format LAYOUT] aliases: [/methods/time/format] --- @@ -23,11 +18,8 @@ aliases: [/methods/time/format] {{ $t.Format $format }} → 27 Jan 2023 ``` -{{% note %}} -To [localize](g) the return value, use the [`time.Format`] function instead. - -[`time.Format`]: /functions/time/format/ -{{% /note %}} +> [!note] +> To [localize](g) the return value, use the [`time.Format`] function instead. Use the `Format` method with any `time.Time` value, including the four predefined front matter dates: @@ -40,15 +32,12 @@ Use the `Format` method with any `time.Time` value, including the four predefine {{ .Lastmod.Format $format }} ``` -{{% note %}} -Use the [`time.Format`] function to format string representations of dates, and to format raw TOML dates that exclude time and time zone offset. - -[`time.Format`]: /functions/time/format/ -{{% /note %}} +> [!note] +> Use the [`time.Format`] function to format string representations of dates, and to format raw TOML dates that exclude time and time zone offset. ## Layout string -{{% include "functions/_common/time-layout-string.md" %}} +{{% include "/_common/time-layout-string.md" %}} ## Examples @@ -95,3 +84,5 @@ Use the [`humanize`](/functions/inflect/humanize) function to render the day of {{ humanize $t.Day }} of {{ $t.Format "January 2006" }} → 27th of January 2023 ``` + +[`time.Format`]: /functions/time/format/ diff --git a/content/en/methods/time/Hour.md b/content/en/methods/time/Hour.md index 58ed00260..28ecf62ac 100644 --- a/content/en/methods/time/Hour.md +++ b/content/en/methods/time/Hour.md @@ -3,16 +3,10 @@ title: Hour description: Returns the hour within the day of the given time.Time value, in the range [0, 23]. categories: [] keywords: [] -action: - related: - - methods/time/Year - - methods/time/Month - - methods/time/Day - - methods/time/Minute - - methods/time/Second - - functions/time/AsTime - returnType: int - signatures: [TIME.Hour] +params: + functions_and_methods: + returnType: int + signatures: [TIME.Hour] --- ```go-html-template diff --git a/content/en/methods/time/IsDST.md b/content/en/methods/time/IsDST.md index df2b84cae..28177b105 100644 --- a/content/en/methods/time/IsDST.md +++ b/content/en/methods/time/IsDST.md @@ -3,11 +3,10 @@ title: IsDST description: Reports whether the given time.Time value is in Daylight Savings Time. categories: [] keywords: [] -action: - related: - - functions/time/AsTime - returnType: bool - signatures: [TIME.IsDST] +params: + functions_and_methods: + returnType: bool + signatures: [TIME.IsDST] --- ```go-html-template diff --git a/content/en/methods/time/IsZero.md b/content/en/methods/time/IsZero.md index 2026f3b2e..400172794 100644 --- a/content/en/methods/time/IsZero.md +++ b/content/en/methods/time/IsZero.md @@ -3,11 +3,10 @@ title: IsZero description: Reports whether the given time.Time value represents the zero time instant, January 1, year 1, 00:00:00 UTC. categories: [] keywords: [] -action: - related: - - functions/time/AsTime - returnType: bool - signatures: [TIME.IsZero] +params: + functions_and_methods: + returnType: bool + signatures: [TIME.IsZero] --- ````go-html-template diff --git a/content/en/methods/time/Local.md b/content/en/methods/time/Local.md index bd40e3a44..74fe889e0 100644 --- a/content/en/methods/time/Local.md +++ b/content/en/methods/time/Local.md @@ -3,12 +3,10 @@ title: Local description: Returns the given time.Time value with the location set to local time. categories: [] keywords: [] -action: - related: - - methods/time/UTC - - functions/time/AsTime - returnType: time.Time - signatures: [TIME.Local] +params: + functions_and_methods: + returnType: time.Time + signatures: [TIME.Local] --- ```go-html-template diff --git a/content/en/methods/time/Minute.md b/content/en/methods/time/Minute.md index d482fab5d..b53db6d83 100644 --- a/content/en/methods/time/Minute.md +++ b/content/en/methods/time/Minute.md @@ -3,16 +3,10 @@ title: Minute description: Returns the minute offset within the hour of the given time.Time value, in the range [0, 59]. categories: [] keywords: [] -action: - related: - - methods/time/Year - - methods/time/Month - - methods/time/Day - - methods/time/Hour - - methods/time/Second - - functions/time/AsTime - returnType: int - signatures: [TIME.Minute] +params: + functions_and_methods: + returnType: int + signatures: [TIME.Minute] --- ```go-html-template diff --git a/content/en/methods/time/Month.md b/content/en/methods/time/Month.md index 0a01d1a70..b0ccea9c3 100644 --- a/content/en/methods/time/Month.md +++ b/content/en/methods/time/Month.md @@ -3,16 +3,10 @@ title: Month description: Returns the month of the year of the given time.Time value. categories: [] keywords: [] -action: - related: - - methods/time/Year - - methods/time/Day - - methods/time/Hour - - methods/time/Minute - - methods/time/Second - - functions/time/AsTime - returnType: time.Month - signatures: [TIME.Month] +params: + functions_and_methods: + returnType: time.Month + signatures: [TIME.Month] --- To convert the `time.Month` value to a string: diff --git a/content/en/methods/time/Nanosecond.md b/content/en/methods/time/Nanosecond.md index 606143139..d895f9622 100644 --- a/content/en/methods/time/Nanosecond.md +++ b/content/en/methods/time/Nanosecond.md @@ -3,11 +3,10 @@ title: Nanosecond description: Returns the nanosecond offset within the second of the given time.Time value, in the range [0, 999999999]. categories: [] keywords: [] -action: - related: - - functions/time/AsTime - returnType: int - signatures: [TIME.Nanosecond] +params: + functions_and_methods: + returnType: int + signatures: [TIME.Nanosecond] --- ```go-html-template diff --git a/content/en/methods/time/Round.md b/content/en/methods/time/Round.md index 16bd2009f..816d41b44 100644 --- a/content/en/methods/time/Round.md +++ b/content/en/methods/time/Round.md @@ -3,13 +3,10 @@ title: Round description: Returns the result of rounding TIME to the nearest multiple of DURATION since January 1, 0001, 00:00:00 UTC. categories: [] keywords: [] -action: - related: - - functions/time/AsTime - - functions/time/ParseDuration - - methods/time/Truncate - returnType: time.Time - signatures: [TIME.Round DURATION] +params: + functions_and_methods: + returnType: time.Time + signatures: [TIME.Round DURATION] --- The rounding behavior for halfway values is to round up. diff --git a/content/en/methods/time/Second.md b/content/en/methods/time/Second.md index e326c64bc..3af086fd3 100644 --- a/content/en/methods/time/Second.md +++ b/content/en/methods/time/Second.md @@ -3,16 +3,10 @@ title: Second description: Returns the second offset within the minute of the given time.Time value, in the range [0, 59]. categories: [] keywords: [] -action: - related: - - methods/time/Year - - methods/time/Month - - methods/time/Day - - methods/time/Hour - - methods/time/Minute - - functions/time/AsTime - returnType: int - signatures: [TIME.Second] +params: + functions_and_methods: + returnType: int + signatures: [TIME.Second] --- ```go-html-template diff --git a/content/en/methods/time/Sub.md b/content/en/methods/time/Sub.md index 9678365eb..d48bf3467 100644 --- a/content/en/methods/time/Sub.md +++ b/content/en/methods/time/Sub.md @@ -3,11 +3,10 @@ title: Sub description: Returns the duration computed by subtracting TIME2 from TIME1. categories: [] keywords: [] -action: - related: - - functions/time/AsTime - returnType: time.Duration - signatures: [TIME1.Sub TIME2] +params: + functions_and_methods: + returnType: time.Duration + signatures: [TIME1.Sub TIME2] --- ```go-html-template diff --git a/content/en/methods/time/Truncate.md b/content/en/methods/time/Truncate.md index 64751f2c1..b797afec0 100644 --- a/content/en/methods/time/Truncate.md +++ b/content/en/methods/time/Truncate.md @@ -3,13 +3,10 @@ title: Truncate description: Returns the result of rounding TIME down to a multiple of DURATION since January 1, 0001, 00:00:00 UTC. categories: [] keywords: [] -action: - related: - - functions/time/AsTime - - functions/time/ParseDuration - - methods/time/Round - returnType: time.Time - signatures: [TIME.Truncate DURATION] +params: + functions_and_methods: + returnType: time.Time + signatures: [TIME.Truncate DURATION] --- The `Truncate` method operates on TIME as an absolute duration since the [zero time](g); it does not operate on the presentation form of the time. If DURATION is a multiple of one hour, `Truncate` may return a time with a non-zero minute, depending on the time zone. diff --git a/content/en/methods/time/UTC.md b/content/en/methods/time/UTC.md index 6fd7b526d..e131a003e 100644 --- a/content/en/methods/time/UTC.md +++ b/content/en/methods/time/UTC.md @@ -3,12 +3,10 @@ title: UTC description: Returns the given time.Time value with the location set to UTC. categories: [] keywords: [] -action: - related: - - methods/time/Local - - functions/time/AsTime - returnType: time.Time - signatures: [TIME.UTC] +params: + functions_and_methods: + returnType: time.Time + signatures: [TIME.UTC] --- ```go-html-template diff --git a/content/en/methods/time/Unix.md b/content/en/methods/time/Unix.md index fcfc661fe..73deb524e 100644 --- a/content/en/methods/time/Unix.md +++ b/content/en/methods/time/Unix.md @@ -1,15 +1,11 @@ --- title: Unix -description: Returns the given time.Time value expressed as the number of seconds elapsed since January 1, 1970 UTC. +description: Returns the given time.Time value expressed as the number of seconds elapsed since January 1, 1970 UTC. categories: [] -action: - related: - - methods/time/UnixMilli - - methods/time/UnixMicro - - methods/time/UnixNano - - functions/time/AsTime - returnType: int64 - signatures: [TIME.Unix] +params: + functions_and_methods: + returnType: int64 + signatures: [TIME.Unix] aliases: [/functions/unix] --- diff --git a/content/en/methods/time/UnixMicro.md b/content/en/methods/time/UnixMicro.md index 150497cd3..fadb0916c 100644 --- a/content/en/methods/time/UnixMicro.md +++ b/content/en/methods/time/UnixMicro.md @@ -1,16 +1,12 @@ --- title: UnixMicro -description: Returns the given time.Time value expressed as the number of microseconds elapsed since January 1, 1970 UTC. +description: Returns the given time.Time value expressed as the number of microseconds elapsed since January 1, 1970 UTC. categories: [] keywords: [] -action: - related: - - methods/time/Unix - - methods/time/UnixMilli - - methods/time/UnixNano - - functions/time/AsTime - returnType: int64 - signatures: [TIME.UnixMicro] +params: + functions_and_methods: + returnType: int64 + signatures: [TIME.UnixMicro] --- See [Unix epoch](https://en.wikipedia.org/wiki/Unix_time). diff --git a/content/en/methods/time/UnixMilli.md b/content/en/methods/time/UnixMilli.md index e5e90ba25..9d2261d91 100644 --- a/content/en/methods/time/UnixMilli.md +++ b/content/en/methods/time/UnixMilli.md @@ -1,16 +1,12 @@ --- title: UnixMilli -description: Returns the given time.Time value expressed as the number of milliseconds elapsed since January 1, 1970 UTC. +description: Returns the given time.Time value expressed as the number of milliseconds elapsed since January 1, 1970 UTC. categories: [] keywords: [] -action: - related: - - methods/time/Unix - - methods/time/UnixMicro - - methods/time/UnixNano - - functions/time/AsTime - returnType: int64 - signatures: [TIME.UnixMilli] +params: + functions_and_methods: + returnType: int64 + signatures: [TIME.UnixMilli] --- See [Unix epoch](https://en.wikipedia.org/wiki/Unix_time). diff --git a/content/en/methods/time/UnixNano.md b/content/en/methods/time/UnixNano.md index 63db320a3..4159ddee2 100644 --- a/content/en/methods/time/UnixNano.md +++ b/content/en/methods/time/UnixNano.md @@ -1,16 +1,12 @@ --- title: UnixNano -description: Returns the given time.Time value expressed as the number of nanoseconds elapsed since January 1, 1970 UTC. +description: Returns the given time.Time value expressed as the number of nanoseconds elapsed since January 1, 1970 UTC. categories: [] keywords: [] -action: - related: - - methods/time/Unix - - methods/time/UnixMilli - - methods/time/UnixMicro - - functions/time/AsTime - returnType: int64 - signatures: [TIME.UnixNano] +params: + functions_and_methods: + returnType: int64 + signatures: [TIME.UnixNano] --- See [Unix epoch](https://en.wikipedia.org/wiki/Unix_time). diff --git a/content/en/methods/time/Weekday.md b/content/en/methods/time/Weekday.md index b2a95fe9c..da939ff87 100644 --- a/content/en/methods/time/Weekday.md +++ b/content/en/methods/time/Weekday.md @@ -1,13 +1,12 @@ --- title: Weekday -description: Returns the day of the week of the given time.Time value. +description: Returns the day of the week of the given time.Time value. categories: [] keywords: [] -action: - related: - - functions/time/AsTime - returnType: time.Weekday - signatures: [TIME.Weekday] +params: + functions_and_methods: + returnType: time.Weekday + signatures: [TIME.Weekday] --- To convert the `time.Weekday` value to a string: diff --git a/content/en/methods/time/Year.md b/content/en/methods/time/Year.md index b046896f4..3f647ea34 100644 --- a/content/en/methods/time/Year.md +++ b/content/en/methods/time/Year.md @@ -3,16 +3,10 @@ title: Year description: Returns the year of the given time.Time value. categories: [] keywords: [] -action: - related: - - methods/time/Month - - methods/time/Day - - methods/time/Hour - - methods/time/Minute - - methods/time/Second - - functions/time/AsTime - returnType: int - signatures: [TIME.Year] +params: + functions_and_methods: + returnType: int + signatures: [TIME.Year] --- ```go-html-template diff --git a/content/en/methods/time/YearDay.md b/content/en/methods/time/YearDay.md index f380cdffe..a93158b45 100644 --- a/content/en/methods/time/YearDay.md +++ b/content/en/methods/time/YearDay.md @@ -3,10 +3,10 @@ title: YearDay description: Returns the day of the year of the given time.Time value, in the range [1, 365] for non-leap years, and [1, 366] in leap years. categories: [] keywords: [] -action: - related: [] - returnType: int - signatures: [TIME.YearDay] +params: + functions_and_methods: + returnType: int + signatures: [TIME.YearDay] --- ```go-html-template diff --git a/content/en/methods/time/_index.md b/content/en/methods/time/_index.md index 81d4690e0..8114664d3 100644 --- a/content/en/methods/time/_index.md +++ b/content/en/methods/time/_index.md @@ -4,10 +4,4 @@ linkTitle: Time description: Use these methods with time.Time values. categories: [] keywords: [] -menu: - docs: - identifier: time-methods - parent: methods --- - -Use these methods with time.Time values. diff --git a/content/en/myshowcase/featured.png b/content/en/myshowcase/featured.png deleted file mode 100644 index 4f390132eb13d9640019d30f13aa1cb882e5c5eb..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 41270 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 diff --git a/content/en/news/_content.gotmpl b/content/en/news/_content.gotmpl new file mode 100644 index 000000000..f979c9adc --- /dev/null +++ b/content/en/news/_content.gotmpl @@ -0,0 +1,30 @@ +{{/* Get releases from GitHub. */}} +{{ $u := "https://api.github.com/repos/gohugoio/hugo/releases" }} +{{ $releases := partial "helpers/funcs/get-remote-data.html" $u }} +{{ $releases = where $releases "draft" false }} +{{ $releases = where $releases "prerelease" false }} + +{{/* Add pages. */}} +{{ range $releases | first 24 }} + {{ $publishDate := .published_at | time.AsTime }} + + {{/* Correct the v0.138.0 release date. See https://github.com/gohugoio/hugo/issues/13066. */}} + {{ if eq .name "v0.138.0" }} + {{ $publishDate = "2024-11-06T11:22:34Z" }} + {{ end }} + + {{ $content := dict "mediaType" "text/markdown" "value" "" }} + {{ $dates := dict "publishDate" (time.AsTime $publishDate) }} + {{ $params := dict "permalink" .html_url }} + {{ $build := dict "render" "never" "list" "local" }} + {{ $page := dict + "build" $build + "content" $content + "dates" $dates + "kind" "page" + "params" $params + "path" .name + "title" (printf "Release %s" .name) + }} + {{ $.AddPage $page }} +{{ end }} diff --git a/content/en/news/_index.md b/content/en/news/_index.md index c170a69a4..23c082cb7 100644 --- a/content/en/news/_index.md +++ b/content/en/news/_index.md @@ -4,6 +4,6 @@ description: Stay up-to-date with the latest news and announcements. outputs: - html - rss -aliases: [/release-notes/] weight: 10 +aliases: [/release-notes/] --- diff --git a/content/en/quick-reference/_index.md b/content/en/quick-reference/_index.md index f2673ba37..98f978f4f 100644 --- a/content/en/quick-reference/_index.md +++ b/content/en/quick-reference/_index.md @@ -1,16 +1,8 @@ --- title: Quick reference guides -linktitle: Quick reference +linkTitle: Quick reference description: Use these quick reference guides for quick access to key information. categories: [] keywords: [] -menu: - docs: - identifier: quick-reference-in-this-section - parent: quick-reference - weight: 10 weight: 10 -showSectionMenu: false --- - -{{% param description %}} diff --git a/content/en/quick-reference/emojis.md b/content/en/quick-reference/emojis.md index 946a49069..15c2e60e6 100644 --- a/content/en/quick-reference/emojis.md +++ b/content/en/quick-reference/emojis.md @@ -1,14 +1,8 @@ --- title: Emojis description: Include emoji shortcodes in your Markdown or templates. -categories: [quick reference] -keywords: [emoji] -menu: - docs: - parent: quick-reference - weight: 20 -weight: 20 -toc: true +categories: [] +keywords: [] --- ## Attribution diff --git a/content/en/quick-reference/functions.md b/content/en/quick-reference/functions.md index 42eafedd3..72235d0f3 100644 --- a/content/en/quick-reference/functions.md +++ b/content/en/quick-reference/functions.md @@ -1,14 +1,8 @@ --- title: Functions description: A quick reference guide to Hugo's functions, grouped by namespace. Aliases, if any, appear in parentheses to the right of the function name. -categories: [quick reference] +categories: [] keywords: [] -menu: - docs: - parent: quick-reference - weight: 30 -weight: 30 -toc: true --- {{% quick-reference section="functions" %}} diff --git a/content/en/quick-reference/glossary/_index.md b/content/en/quick-reference/glossary/_index.md index 1b5111e8e..42894c4da 100644 --- a/content/en/quick-reference/glossary/_index.md +++ b/content/en/quick-reference/glossary/_index.md @@ -1,16 +1,8 @@ --- title: Glossary description: Terms commonly used throughout the documentation. -categories: [quick-reference] -keywords: [glossary] -hide_in_this_section: true -menu: - docs: - parent: quick-reference - weight: 40 -aliases: [/getting-started/glossary/] -weight: 40 -layout: single +categories: [] +keywords: [] build: render: always list: always @@ -18,6 +10,10 @@ cascade: build: render: never list: local +layout: single +params: + hide_in_this_section: true +aliases: [/getting-started/glossary/] --- {{% glossary %}} diff --git a/content/en/quick-reference/glossary/cicd.md b/content/en/quick-reference/glossary/cicd.md new file mode 100644 index 000000000..355097b1b --- /dev/null +++ b/content/en/quick-reference/glossary/cicd.md @@ -0,0 +1,7 @@ +--- +title: CI/CD +params: + reference: https://en.wikipedia.org/wiki/CI/CD +--- + +The term _CI/CD_ is an abbreviation for Continuous Integration and Continuous Delivery or Continuous Deployment depending on context. diff --git a/content/en/quick-reference/glossary/cli.md b/content/en/quick-reference/glossary/cli.md index 61269dc8e..8f898e364 100644 --- a/content/en/quick-reference/glossary/cli.md +++ b/content/en/quick-reference/glossary/cli.md @@ -2,4 +2,4 @@ title: CLI --- -_CLI_ is an abbreviation of Command Line Interface. +_CLI_ stands for command-line interface, a text-based method for interacting with computer programs or operating systems. diff --git a/content/en/quick-reference/glossary/default-sort-order.md b/content/en/quick-reference/glossary/default-sort-order.md index 2b5588d56..9b981a7e9 100644 --- a/content/en/quick-reference/glossary/default-sort-order.md +++ b/content/en/quick-reference/glossary/default-sort-order.md @@ -2,4 +2,9 @@ title: default sort order --- -The _default sort order_ is the default order in which Hugo sorts page collections: by [_weight_](g), then by date (descending), then by link title, and then by file path. +The _default sort order_ for [_page collections_](g), used when no other criteria are set, follows this priority: + + 1. [`weight`](/content-management/front-matter/#weight) (ascending) + 1. [`date`](/content-management/front-matter/#date) (descending) + 1. [`linkTitle`](/content-management/front-matter/#linktitle) falling back to [`title`](/content-management/front-matter/#title) (ascending) + 1. [logical path](g) (ascending) diff --git a/content/en/quick-reference/glossary/environment.md b/content/en/quick-reference/glossary/environment.md index 6605c2263..ebba0ccdf 100644 --- a/content/en/quick-reference/glossary/environment.md +++ b/content/en/quick-reference/glossary/environment.md @@ -4,8 +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 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. -To determine the current environment within a template, use the [`hugo.Environment`] function. - -[`hugo.Environment`]: /functions/hugo/environment/ + 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.md b/content/en/quick-reference/glossary/glob.md index 5243d1ef9..bb9c5a4d8 100644 --- a/content/en/quick-reference/glossary/glob.md +++ b/content/en/quick-reference/glossary/glob.md @@ -3,4 +3,4 @@ title: glob reference: https://github.com/gobwas/glob?tab=readme-ov-file#example --- -A _glob_ is a pattern used to match filenames and paths. It's a shorthand for specifying a set of files, making it easier to work with multiple files at once. +A _glob_ is a pattern used to match file names and paths. It's a shorthand for specifying a set of files, making it easier to work with multiple files at once. diff --git a/content/en/quick-reference/glossary/interval.md b/content/en/quick-reference/glossary/interval.md index f1ce7bc93..a7ed8a6cd 100644 --- a/content/en/quick-reference/glossary/interval.md +++ b/content/en/quick-reference/glossary/interval.md @@ -4,8 +4,8 @@ title: interval An [_interval_](https://en.wikipedia.org/wiki/Interval_(mathematics)) is a range of numbers between two endpoints: closed, open, or half-open. -- A _closed interval_, denoted by brackets, includes its endpoints. For example, [0, 1] is the interval where `0 <= x <= 1`. + - A _closed interval_, denoted by brackets, includes its endpoints. For example, [0, 1] is the interval where `0 <= x <= 1`. -- An _open interval_, denoted by parentheses, excludes its endpoints. For example, (0, 1) is the interval where `0 < x < 1`. + - An _open interval_, denoted by parentheses, excludes its endpoints. For example, (0, 1) is the interval where `0 < x < 1`. -- A _half-open interval_ includes only one of its endpoints. For example, (0, 1] is the _left-open_ interval where `0 < x <= 1`, while [0, 1) is the _right-open_ interval where `0 <= x < 1`. + - A _half-open interval_ includes only one of its endpoints. For example, (0, 1] is the _left-open_ interval where `0 < x <= 1`, while [0, 1) is the _right-open_ interval where `0 <= x < 1`. diff --git a/content/en/quick-reference/glossary/logical-path.md b/content/en/quick-reference/glossary/logical-path.md index aa5ce9374..2eeee751f 100644 --- a/content/en/quick-reference/glossary/logical-path.md +++ b/content/en/quick-reference/glossary/logical-path.md @@ -3,6 +3,4 @@ title: logical path reference: /methods/page/path/#examples --- -{{< new-in 0.123.0 />}} - -A _logical path_ is a page or page resource identifier derived from the file path, excluding its extension and language identifier. This value is neither a file path nor a URL. Starting with a file path relative to the `content` directory, Hugo determines the logical path by stripping the file extension and language identifier, converting to lower case, then replacing spaces with hyphens. +A _logical path_ is a page or page resource identifier derived from the file path, excluding its extension and language identifier. This value is neither a file path nor a URL. Starting with a file path relative to the `content` directory, Hugo determines the logical path by stripping the file extension and language identifier, converting to lower case, then replacing spaces with hyphens. Path segments are separated with a slash (`/`). diff --git a/content/en/quick-reference/glossary/markdown-attribute.md b/content/en/quick-reference/glossary/markdown-attribute.md index ccbcefd66..f5c57c728 100644 --- a/content/en/quick-reference/glossary/markdown-attribute.md +++ b/content/en/quick-reference/glossary/markdown-attribute.md @@ -3,4 +3,4 @@ title: Markdown attribute reference: /content-management/markdown-attributes/ --- -A _Markdown attribute_ is a key-value pair attached to a Markdown element. These attributes are commonly used to add HTML attributes, like `class` and `id`, to the element when it's rendered into HTML. They provide a way to extend the basic Markdown syntax and add more semantic meaning or styling hooks to your content. +A _Markdown attribute_ is a key-value pair attached to a Markdown element. These attributes are commonly used to add HTML attributes, like `class` and `id`, to the element when it's rendered into HTML. They provide a way to extend the basic Markdown syntax and add more semantic meaning or styling hooks to your content. diff --git a/content/en/quick-reference/glossary/media-type.md b/content/en/quick-reference/glossary/media-type.md new file mode 100644 index 000000000..2994360ef --- /dev/null +++ b/content/en/quick-reference/glossary/media-type.md @@ -0,0 +1,6 @@ +--- +title: media type +reference: /configuration/media-types/ +--- + +A _media type_ (formerly known as a MIME type) is a two-part identifier for file formats and transmitted content. For example, the media type for JSON data is `application/json`. diff --git a/content/en/quick-reference/glossary/method.md b/content/en/quick-reference/glossary/method.md index b7618bbf9..634cd4b97 100644 --- a/content/en/quick-reference/glossary/method.md +++ b/content/en/quick-reference/glossary/method.md @@ -2,4 +2,4 @@ title: method --- -Used within a [_template action_](g) and associated with an [_object_](g), a _method_ takes zero or more [_arguments_](g) and either returns a value or performs an action. For example, `.IsHome` is a method on the `.Page` object which returns `true` if the current page is the home page. See also [_function_](g). +Used within a [_template action_](g) and associated with an [_object_](g), a _method_ takes zero or more [_arguments_](g) and either returns a value or performs an action. For example, `IsHome` is a method on a `Page` object which returns `true` if the current page is the home page. See also [_function_](g). diff --git a/content/en/quick-reference/glossary/ordered-taxonomy.md b/content/en/quick-reference/glossary/ordered-taxonomy.md index 7e0e2763d..9b6c1d92c 100644 --- a/content/en/quick-reference/glossary/ordered-taxonomy.md +++ b/content/en/quick-reference/glossary/ordered-taxonomy.md @@ -2,7 +2,4 @@ title: ordered taxonomy --- -Created by invoking the [`Alphabetical`] or [`ByCount`] method on a [`Taxonomy`](g) object, which is a [_map_](g), an _ordered taxonomy_ is a [_slice_](g), where each element is an object that contains the [_term_](g) and a slice of its [weighted pages](g). - -[`Alphabetical`]: /methods/taxonomy/alphabetical/ -[`ByCount`]: /methods/taxonomy/bycount/ +Created by invoking the [`Alphabetical`](/methods/taxonomy/alphabetical/) or [`ByCount`](/methods/taxonomy/bycount/) method on a [`Taxonomy`](g) object, which is a [_map_](g), an _ordered taxonomy_ is a [_slice_](g), where each element is an object that contains the [_term_](g) and a slice of its [_weighted pages_](g). diff --git a/content/en/quick-reference/glossary/output-format.md b/content/en/quick-reference/glossary/output-format.md index 9004dc223..df042d06b 100644 --- a/content/en/quick-reference/glossary/output-format.md +++ b/content/en/quick-reference/glossary/output-format.md @@ -1,6 +1,6 @@ --- title: output format -reference: /templates/output-formats/ +reference: /configuration/output-formats/ --- -An _output format_ is a collection of settings that defines how Hugo renders a file when building a site. For example, `html`, `rss`, and `json` are built-in output formats. You can create multiple output formats and control their generation based on [page kind](g), or by enabling one or more output formats for specific pages. +An _output format_ is a collection of settings that defines how Hugo renders a file when building a site. For example, `html`, `json`, and `rss` are built-in output formats. You can create multiple output formats and control their generation based on [page kind](g), or by enabling one or more output formats for specific pages. diff --git a/content/en/quick-reference/glossary/pipeline.md b/content/en/quick-reference/glossary/pipeline.md index 2bb3fa3b7..6dab52578 100644 --- a/content/en/quick-reference/glossary/pipeline.md +++ b/content/en/quick-reference/glossary/pipeline.md @@ -4,4 +4,4 @@ title: pipeline Within a [_template action_](g), a _pipeline_ is a possibly chained sequence of values, [_function_](g) calls, or [_method_](g) calls. Functions and methods in the pipeline may take multiple [_arguments_](g). -A pipeline may be *chained* by separating a sequence of commands with pipeline characters (`|`). In a chained pipeline, the result of each command is passed as the last argument to the following command. The output of the final command in the pipeline is the value of the pipeline. + A pipeline may be chained by separating a sequence of commands with pipeline characters (`|`). In a chained pipeline, the result of each command is passed as the last argument to the following command. The output of the final command in the pipeline is the value of the pipeline. diff --git a/content/en/quick-reference/glossary/primary-output-format.md b/content/en/quick-reference/glossary/primary-output-format.md new file mode 100644 index 000000000..c40c0176c --- /dev/null +++ b/content/en/quick-reference/glossary/primary-output-format.md @@ -0,0 +1,10 @@ +--- +title: primary output format +details: /configuration/outputs/ +--- + +A _primary output format_ defines the default URL returned by the [`Permalink`] and [`RelPermalink`] methods for a given [page kind](g). It is specified as the first entry within the [outputs configuration] for that page kind. + +[`Permalink`]: /methods/page/permalink/ +[`RelPermalink`]: /methods/page/relpermalink/ +[outputs configuration]: /configuration/outputs/ diff --git a/content/en/quick-reference/glossary/regular-expression.md b/content/en/quick-reference/glossary/regular-expression.md new file mode 100644 index 000000000..222f289d9 --- /dev/null +++ b/content/en/quick-reference/glossary/regular-expression.md @@ -0,0 +1,8 @@ +--- +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. + + [RE2 syntax]: https://github.com/google/re2/wiki/syntax diff --git a/content/en/quick-reference/glossary/resource-type.md b/content/en/quick-reference/glossary/resource-type.md index 64d9c27ab..9a2412fb9 100644 --- a/content/en/quick-reference/glossary/resource-type.md +++ b/content/en/quick-reference/glossary/resource-type.md @@ -2,7 +2,4 @@ title: resource type --- -A _resource type_ is the main type of a resource's [media type]. Content files such as Markdown, HTML, AsciiDoc, Pandoc, reStructuredText, and Emacs Org Mode have resource type `page`. Other resource types include `image`, `video`, etc. Retrieve the resource type using the [`ResourceType`] method on a `Resource` object. - -[media type]: /methods/resource/mediatype/ -[`ResourceType`]: /methods/resource/resourcetype/ +A _resource type_ is the main type of a resource's [media type](/methods/resource/mediatype/). Content files such as Markdown, HTML, AsciiDoc, Pandoc, reStructuredText, and Emacs Org Mode have resource type `page`. Other resource types include `image`, `text`, `video`, and others. Retrieve the resource type using the [`ResourceType`](/methods/resource/resourcetype/) method on a `Resource` object. diff --git a/content/en/quick-reference/glossary/resource.md b/content/en/quick-reference/glossary/resource.md index bd3a9d10d..0864bc43d 100644 --- a/content/en/quick-reference/glossary/resource.md +++ b/content/en/quick-reference/glossary/resource.md @@ -4,4 +4,4 @@ title: resource A _resource_ is any file consumed by the build process to augment or generate content, structure, behavior, or presentation. For example: images, videos, content snippets, CSS, Sass, JavaScript, and data. -Hugo supports three types of resources: [_global resources_](g), [_page resources_](g), and [_remote resources_](g). + Hugo supports three types of resources: [_global resources_](g), [_page resources_](g), and [_remote resources_](g). diff --git a/content/en/quick-reference/glossary/scratch-pad.md b/content/en/quick-reference/glossary/scratch-pad.md index f94d4fd5b..4792ce12e 100644 --- a/content/en/quick-reference/glossary/scratch-pad.md +++ b/content/en/quick-reference/glossary/scratch-pad.md @@ -2,7 +2,4 @@ title: scratch pad --- -Conceptually, a _scratch pad_ is a [_map_](g) with [_methods_](g) to set, get, update, and delete values. Attach the data structure to a `Page` or `Site` object using the [`Store`] method, or create a locally scoped scratch pad using the [`newScratch`] function. - -[`Store`]: /methods/page/store/ -[`newScratch`]: /functions/collections/newscratch/ +Conceptually, a _scratch pad_ is a [_map_](g) with [_methods_](g) to set, get, update, and delete values. Attach the data structure to a `Page` or `Site` object using the [`Store`](/methods/page/store/) method, or create a locally scoped scratch pad using the [`newScratch`](/functions/collections/newscratch/) function. diff --git a/content/en/quick-reference/glossary/shortcode.md b/content/en/quick-reference/glossary/shortcode.md index bfc2f6c51..a6503ea63 100644 --- a/content/en/quick-reference/glossary/shortcode.md +++ b/content/en/quick-reference/glossary/shortcode.md @@ -3,4 +3,4 @@ title: shortcode reference: /content-management/shortcodes --- -A _shortcode_ is a [_template_](g) invoked within markup, accepting any number of [_arguments_](g). They can be used with any [content format](g) to insert elements such as videos, images, and social media embeds into your content. +A _shortcode_ is a [_template_](g) invoked within markup, accepting any number of [_arguments_](g). They can be used with any [_content format_](g) to insert elements such as videos, images, and social media embeds into your content. diff --git a/content/en/quick-reference/glossary/template-action.md b/content/en/quick-reference/glossary/template-action.md index d9a6c635c..e40c228fe 100644 --- a/content/en/quick-reference/glossary/template-action.md +++ b/content/en/quick-reference/glossary/template-action.md @@ -3,4 +3,4 @@ title: template action reference: https://pkg.go.dev/text/template#hdr-Actions --- -A data evaluation or control structure within a [_template_](g), delimited by "{{" and "}}". +A data evaluation or control structure within a [_template_](g), delimited by `{{` and `}}`. diff --git a/content/en/quick-reference/methods.md b/content/en/quick-reference/methods.md index 5b4797f3a..524713c1f 100644 --- a/content/en/quick-reference/methods.md +++ b/content/en/quick-reference/methods.md @@ -1,14 +1,8 @@ --- title: Methods description: A quick reference guide to Hugo's methods, grouped by object. -categories: [quick reference] +categories: [] keywords: [] -menu: - docs: - parent: quick-reference - weight: 50 -weight: 50 -toc: true --- {{% quick-reference section="methods" %}} diff --git a/content/en/quick-reference/page-collections.md b/content/en/quick-reference/page-collections.md index 836af3ea2..4c2387bbe 100644 --- a/content/en/quick-reference/page-collections.md +++ b/content/en/quick-reference/page-collections.md @@ -1,56 +1,38 @@ --- title: Page collections description: A quick reference guide to Hugo's page collections. -categories: [quick reference] +categories: [] keywords: [] -menu: - docs: - parent: quick-reference - weight: 60 -weight: 60 -toc: true --- ## Page -assets/ Use these `Page` methods when rendering lists on [section pages](g), [taxonomy pages](g), [term pages](g), and the home page. -{{< list-pages-in-section path=/methods/page filter=methods_page_page_collections filterType=include omitElementIDs=true titlePrefix=PAGE. >}} +{{% list-pages-in-section path=/methods/page filter=methods_page_page_collections filterType=include titlePrefix=PAGE. %}} ## Site Use these `Site` methods when rendering lists on any page. -{{< list-pages-in-section path=/methods/site filter=methods_site_page_collections filterType=include omitElementIDs=true titlePrefix=SITE. >}} +{{% list-pages-in-section path=/methods/site filter=methods_site_page_collections filterType=include titlePrefix=SITE. %}} ## Filter Use the [`where`] function to filter page collections. -[`where`]: /functions/collections/where/ - ## Sort -By default, Hugo sorts page collections by: +{{% glossary-term "default sort order" %}} -1. [Weight] -1. [Date] in descending order -1. [LinkTitle] falling back to [Title] -1. [Filename] if the page is backed by a file +Use these methods to sort page collections by different criteria. -[Date]: /methods/page/date/ -[Weight]: /methods/page/weight/ -[LinkTitle]: /methods/page/linktitle/ -[Title]: /methods/page/title/ -[Filename]: /methods/page/file/#filename - -Use these methods to sort page collections. - -{{< list-pages-in-section path=/methods/pages filter=methods_pages_sort filterType=include titlePrefix=. omitElementIDs=true titlePrefix=PAGES. >}} +{{% list-pages-in-section path=/methods/pages filter=methods_pages_sort filterType=include titlePrefix=. titlePrefix=PAGES. %}} ## Group Use these methods to group page collections. -{{< list-pages-in-section path=/methods/pages filter=methods_pages_group filterType=include titlePrefix=. omitElementIDs=true titlePrefix=PAGES. >}} +{{% list-pages-in-section path=/methods/pages filter=methods_pages_group filterType=include titlePrefix=. titlePrefix=PAGES. %}} + +[`where`]: /functions/collections/where/ diff --git a/content/en/quick-reference/syntax-highlighting-styles.md b/content/en/quick-reference/syntax-highlighting-styles.md new file mode 100644 index 000000000..14b313cbc --- /dev/null +++ b/content/en/quick-reference/syntax-highlighting-styles.md @@ -0,0 +1,35 @@ +--- +title: Syntax highlighting styles +description: Highlight code examples using one of these styles. +categories: [] +keywords: [highlight] +--- + +## Overview + +Hugo provides several methods to add syntax highlighting to code examples: + +- Use the [`transform.Highlight`] function within your templates +- Use the [`highlight`] shortcode with any [content format](g) +- Use fenced code blocks with the Markdown content format + +Regardless of method, use any of the syntax highlighting styles below. + +Set the default syntax highlighting style in your site configuration: + +{{< code-toggle file=hugo >}} +[markup.highlight] +style = 'monokai' +{{< /code-toggle >}} + +See [configure Markup](/configuration/markup/#highlight). + +[`transform.Highlight`]: /functions/transform/highlight/ +[`highlight`]: /shortcodes/highlight/ +[fenced code blocks]: /content-management/syntax-highlighting/#fenced-code-blocks + +## Styles + +This gallery demonstrates the application of each syntax highlighting style with code examples written in different programming languages. + +{{% syntax-highlighting-styles %}} diff --git a/content/en/render-hooks/_common/_index.md b/content/en/render-hooks/_common/_index.md deleted file mode 100644 index 4328d4d14..000000000 --- a/content/en/render-hooks/_common/_index.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -cascade: - _build: - list: never - publishResources: false - render: never ---- - - diff --git a/content/en/render-hooks/_index.md b/content/en/render-hooks/_index.md index 668808f44..a5e6203ff 100644 --- a/content/en/render-hooks/_index.md +++ b/content/en/render-hooks/_index.md @@ -1,17 +1,8 @@ --- title: Render hooks - description: Create render hooks to override the rendering of Markdown to HTML. categories: [] keywords: [] -menu: - docs: - identifier: render-hooks-in-this-section - parent: render-hooks - weight: 10 weight: 10 -showSectionMenu: false aliases: [/templates/render-hooks/] --- - -Create render hooks to override the rendering of Markdown to HTML. diff --git a/content/en/render-hooks/blockquotes.md b/content/en/render-hooks/blockquotes.md index bdeb06af9..7ba282a0a 100755 --- a/content/en/render-hooks/blockquotes.md +++ b/content/en/render-hooks/blockquotes.md @@ -2,14 +2,8 @@ title: Blockquote render hooks linkTitle: Blockquotes description: Create a blockquote render hook to override the rendering of Markdown blockquotes to HTML. -categories: [render hooks] +categories: [] keywords: [] -menu: - docs: - parent: render-hooks - weight: 30 -weight: 30 -toc: true --- {{< new-in 0.132.0 />}} @@ -18,73 +12,56 @@ toc: true Blockquote render hook templates receive the following [context](g): -###### AlertType +AlertType +: (`string`) Applicable when [`Type`](#type) is `alert`, this is the alert type converted to lowercase. See the [alerts](#alerts) section below. -(`string`) Applicable when [`Type`](#type) is `alert`, this is the alert type converted to lowercase. See the [alerts](#alerts) section below. +AlertTitle +: {{< new-in 0.134.0 />}} +: (`template.HTML`) Applicable when [`Type`](#type) is `alert`, this is the alert title. See the [alerts](#alerts) section below. -###### AlertTitle +AlertSign +: {{< new-in 0.134.0 />}} +: (`string`) Applicable when [`Type`](#type) is `alert`, this is the alert sign. Typically used to indicate whether an alert is graphically foldable, this is one of `+`, `-`, or an empty string. See the [alerts](#alerts) section below. -{{< new-in 0.134.0 />}} +Attributes +: (`map`) The [Markdown attributes], available if you configure your site as follows: -(`template.HTML`) Applicable when [`Type`](#type) is `alert`, this is the alert title. See the [alerts](#alerts) section below. + {{< code-toggle file=hugo >}} + [markup.goldmark.parser.attribute] + block = true + {{< /code-toggle >}} -###### AlertSign +Ordinal +: (`int`) The zero-based ordinal of the blockquote on the page. -{{< new-in 0.134.0 />}} +Page +: (`page`) A reference to the current page. -(`string`) Applicable when [`Type`](#type) is `alert`, this is the alert sign. Typically used to indicate whether an alert is graphically foldable, this is one of `+`, `-`, or an empty string. See the [alerts](#alerts) section below. +PageInner +: (`page`) A reference to a page nested via the [`RenderShortcodes`] method. [See details](#pageinner-details). -###### Attributes +Position +: (`string`) The position of the blockquote within the page content. -(`map`) The [Markdown attributes], available if you configure your site as follows: +Text +: (`template.HTML`) The blockquote text, excluding the first line if [`Type`](#type) is `alert`. See the [alerts](#alerts) section below. -[Markdown attributes]: /content-management/markdown-attributes/ - -{{< code-toggle file=hugo >}} -[markup.goldmark.parser.attribute] -block = true -{{< /code-toggle >}} - -###### Ordinal - -(`int`) The zero-based ordinal of the blockquote on the page. - -###### Page - -(`page`) A reference to the current page. - -###### PageInner - -(`page`) A reference to a page nested via the [`RenderShortcodes`] method. [See details](#pageinner-details). - -[`RenderShortcodes`]: /methods/page/rendershortcodes - -###### Position - -(`string`) The position of the blockquote within the page content. - -###### Text -(`template.HTML`) The blockquote text, excluding the first line if [`Type`](#type) is `alert`. See the [alerts](#alerts) section below. - -###### Type - -(`bool`) The blockquote type. Returns `alert` if the blockquote has an alert designator, else `regular`. See the [alerts](#alerts) section below. +Type +: (`string`) The blockquote type. Returns `alert` if the blockquote has an alert designator, else `regular`. See the [alerts](#alerts) section below. ## Examples In its default configuration, Hugo renders Markdown blockquotes according to the [CommonMark specification]. To create a render hook that does the same thing: -[CommonMark specification]: https://spec.commonmark.org/current/ - -{{< code file=layouts/_default/_markup/render-blockquote.html copy=true >}} +```go-html-template {file="layouts/_default/_markup/render-blockquote.html" copy=true}
{{ .Text }}
-{{< /code >}} +``` To render a blockquote as an HTML `figure` element with an optional citation and caption: -{{< code file=layouts/_default/_markup/render-blockquote.html copy=true >}} +```go-html-template {file="layouts/_default/_markup/render-blockquote.html" copy=true}
{{ .Text }} @@ -95,7 +72,7 @@ To render a blockquote as an HTML `figure` element with an optional citation and {{ end }}
-{{< /code >}} +``` Then in your markdown: @@ -112,7 +89,7 @@ Also known as _callouts_ or _admonitions_, alerts are blockquotes used to emphas With the basic Markdown syntax, the first line of each alert is an alert designator consisting of an exclamation point followed by the alert type, wrapped within brackets. For example: -{{< code file=content/example.md lang=text >}} +```text {file="content/example.md"} > [!NOTE] > Useful information that users should know, even when skimming content. @@ -127,34 +104,29 @@ With the basic Markdown syntax, the first line of each alert is an alert designa > [!CAUTION] > Advises about risks or negative outcomes of certain actions. -{{< /code >}} +``` The basic syntax is compatible with [GitHub], [Obsidian], and [Typora]. -[GitHub]: https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#alerts -[Obsidian]: https://help.obsidian.md/Editing+and+formatting/Callouts -[Typora]: https://support.typora.io/Markdown-Reference/#callouts--github-style-alerts - ### Extended syntax With the extended Markdown syntax, you may optionally include an alert sign and/or an alert title. The alert sign is one of `+` or `-`, typically used to indicate whether an alert is graphically foldable. For example: -{{< code file=content/example.md lang=text >}} +```text {file="content/example.md"} > [!WARNING]+ Radiation hazard > Do not approach or handle without protective gear. -{{< /code >}} +``` The extended syntax is compatible with [Obsidian]. -{{% note %}} -The extended syntax is not compatible with GitHub or Typora. If you include an alert sign or an alert title, these applications render the Markdown as a blockquote. -{{% /note %}} +> [!note] +> The extended syntax is not compatible with GitHub or Typora. If you include an alert sign or an alert title, these applications render the Markdown as a blockquote. ### Example This blockquote render hook renders a multilingual alert if an alert designator is present, otherwise it renders a blockquote according to the CommonMark specification. -{{< code file=layouts/_default/_markup/render-blockquote.html copy=true >}} +```go-html-template {file="layouts/_default/_markup/render-blockquote.html" copy=true} {{ $emojis := dict "caution" ":exclamation:" "important" ":information_source:" @@ -180,7 +152,7 @@ This blockquote render hook renders a multilingual alert if an alert designator {{ .Text }} {{ end }} -{{< /code >}} +``` To override the label, create these entries in your i18n files: @@ -202,4 +174,11 @@ layouts/ └── render-blockquote-regular.html ``` -{{% include "/render-hooks/_common/pageinner.md" %}} +{{% include "/_common/render-hooks/pageinner.md" %}} + +[`RenderShortcodes`]: /methods/page/rendershortcodes +[CommonMark specification]: https://spec.commonmark.org/current/ +[GitHub]: https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#alerts +[Markdown attributes]: /content-management/markdown-attributes/ +[Obsidian]: https://help.obsidian.md/Editing+and+formatting/Callouts +[Typora]: https://support.typora.io/Markdown-Reference/#callouts--github-style-alerts diff --git a/content/en/render-hooks/code-blocks.md b/content/en/render-hooks/code-blocks.md index 7999dbeb8..d1a01e9b0 100755 --- a/content/en/render-hooks/code-blocks.md +++ b/content/en/render-hooks/code-blocks.md @@ -2,27 +2,21 @@ title: Code block render hooks linkTitle: Code blocks description: Create a code block render hook to override the rendering of Markdown code blocks to HTML. -categories: [render hooks] +categories: [] keywords: [] -menu: - docs: - parent: render-hooks - weight: 40 -weight: 40 -toc: true --- ## Markdown This Markdown example contains a fenced code block: -{{< code file=content/example.md lang=text >}} +````text {file="content/example.md"} ```bash {class="my-class" id="my-codeblock" lineNos=inline tabWidth=2} declare a=1 echo "$a" exit ``` -{{< /code >}} +```` A fenced code block consists of: @@ -31,9 +25,6 @@ A fenced code block consists of: - A code sample - A trailing code fence -[code fence]: https://spec.commonmark.org/0.31.2/#code-fence -[info string]: https://spec.commonmark.org/0.31.2/#info-string - In the previous example, the info string contains: - The language of the code sample (the first word) @@ -45,63 +36,46 @@ In the example above, the _generic attributes_ are `class` and `id`. In the abse In the example above, the _highlighting options_ are `lineNos` and `tabWidth`. Hugo uses the [Chroma] syntax highlighter to render the code sample. You can control the appearance of the rendered code by specifying one or more [highlighting options]. -[Chroma]: https://github.com/alecthomas/chroma/ -[highlighting options]: /functions/transform/highlight/#options - -{{% note %}} -Although `style` is a global HTML attribute, when used in an info string it is a highlighting option. -{{% /note %}} +> [!note] +> Although `style` is a global HTML attribute, when used in an info string it is a highlighting option. ## Context Code block render hook templates receive the following [context](g): -###### Attributes +Attributes +: (`map`) The generic attributes from the info string. -(`map`) The generic attributes from the info string. +Inner +: (`string`) The content between the leading and trailing code fences, excluding the info string. -###### Inner +Options +: (`map`) The highlighting options from the info string. -(`string`) The content between the leading and trailing code fences, excluding the info string. +Ordinal +: (`int`) The zero-based ordinal of the code block on the page. -###### Options +Page +: (`page`) A reference to the current page. -(`map`) The highlighting options from the info string. +PageInner +: {{< new-in 0.125.0 />}} +: (`page`) A reference to a page nested via the [`RenderShortcodes`] method. [See details](#pageinner-details). -###### Ordinal +Position +: (`text.Position`) The position of the code block within the page content. -(`int`) The zero-based ordinal of the code block on the page. - -###### Page - -(`page`) A reference to the current page. - -###### PageInner - -{{< new-in 0.125.0 />}} - -(`page`) A reference to a page nested via the [`RenderShortcodes`] method. [See details](#pageinner-details). - -[`RenderShortcodes`]: /methods/page/rendershortcodes - -###### Position - -(`text.Position`) The position of the code block within the page content. - -###### Type - -(`string`) The first word of the info string, typically the code language. +Type +: (`string`) The first word of the info string, typically the code language. ## Examples In its default configuration, Hugo renders fenced code blocks by passing the code sample through the Chroma syntax highlighter and wrapping the result. To create a render hook that does the same thing: -[CommonMark specification]: https://spec.commonmark.org/current/ - -{{< code file=layouts/_default/_markup/render-codeblock.html copy=true >}} +```go-html-template {file="layouts/_default/_markup/render-codeblock.html" copy=true} {{ $result := transform.HighlightCodeBlock . }} {{ $result.Wrapped }} -{{< /code >}} +``` Although you can use one template with conditional logic to control the behavior on a per-language basis, you can also create language-specific templates. @@ -116,35 +90,38 @@ layouts/ For example, to create a code block render hook to render [Mermaid] diagrams: -[Mermaid]: https://mermaid.js.org/ - -{{< code file=layouts/_default/_markup/render-codeblock-mermaid.html copy=true >}} +```go-html-template {file="layouts/_default/_markup/render-codeblock-mermaid.html" copy=true} 
-  {{- .Inner | htmlEscape | safeHTML }}
+  {{ .Inner | htmlEscape | safeHTML }}
{{ .Page.Store.Set "hasMermaid" true }} -{{< /code >}} +``` -Then include this snippet at the bottom of the your base template: +Then include this snippet at the _bottom_ of your base template, before the closing `body` tag: -{{< code file=layouts/_default/baseof.html copy=true >}} +```go-html-template {file="layouts/_default/baseof.html" copy=true} {{ if .Store.Get "hasMermaid" }} {{ end }} -{{< /code >}} +``` See the [diagrams] page for details. -[diagrams]: /content-management/diagrams/#mermaid-diagrams - ## Embedded Hugo includes an [embedded code block render hook] to render [GoAT diagrams]. +{{% include "/_common/render-hooks/pageinner.md" %}} + +[`RenderShortcodes`]: /methods/page/rendershortcodes +[Chroma]: https://github.com/alecthomas/chroma/ +[code fence]: https://spec.commonmark.org/0.31.2/#code-fence +[diagrams]: /content-management/diagrams/#mermaid-diagrams [embedded code block render hook]: {{% eturl render-codeblock-goat %}} [GoAT diagrams]: /content-management/diagrams/#goat-diagrams-ascii - -{{% include "/render-hooks/_common/pageinner.md" %}} +[highlighting options]: /functions/transform/highlight/#options +[info string]: https://spec.commonmark.org/0.31.2/#info-string +[Mermaid]: https://mermaid.js.org/ diff --git a/content/en/render-hooks/headings.md b/content/en/render-hooks/headings.md index 7c9d6b6fe..89868d478 100755 --- a/content/en/render-hooks/headings.md +++ b/content/en/render-hooks/headings.md @@ -2,78 +2,63 @@ title: Heading render hooks linkTitle: Headings description: Create a heading render hook to override the rendering of Markdown headings to HTML. -categories: [render hooks] +categories: [] keywords: [] -menu: - docs: - parent: render-hooks - weight: 50 -weight: 50 -toc: true --- ## Context Heading render hook templates receive the following [context](g): -###### Anchor +Anchor +: (`string`) The `id` attribute of the heading element. -(`string`) The `id` attribute of the heading element. +Attributes +: (`map`) The [Markdown attributes], available if you configure your site as follows: -###### Attributes + {{< code-toggle file=hugo >}} + [markup.goldmark.parser.attribute] + title = true + {{< /code-toggle >}} -(`map`) The [Markdown attributes], available if you configure your site as follows: +Level +: (`int`) The heading level, 1 through 6. + +Page +: (`page`) A reference to the current page. + +PageInner +: {{< new-in 0.125.0 />}} +: (`page`) A reference to a page nested via the [`RenderShortcodes`] method. [See details](#pageinner-details). + +PlainText +: (`string`) The heading text as plain text. + +Text +: (`template.HTML`) The heading text. [Markdown attributes]: /content-management/markdown-attributes/ - -{{< code-toggle file=hugo >}} -[markup.goldmark.parser.attribute] -title = true -{{< /code-toggle >}} - -###### Level - -(`int`) The heading level, 1 through 6. - -###### Page - -(`page`) A reference to the current page. - -###### PageInner - -{{< new-in 0.125.0 />}} - -(`page`) A reference to a page nested via the [`RenderShortcodes`] method. [See details](#pageinner-details). - [`RenderShortcodes`]: /methods/page/rendershortcodes -###### PlainText - -(`string`) The heading text as plain text. - -###### Text - -(`template.HTML`) The heading text. - ## Examples In its default configuration, Hugo renders Markdown headings according to the [CommonMark specification] with the addition of automatic `id` attributes. To create a render hook that does the same thing: [CommonMark specification]: https://spec.commonmark.org/current/ -{{< code file=layouts/_default/_markup/render-heading.html copy=true >}} +```go-html-template {file="layouts/_default/_markup/render-heading.html" copy=true} {{- .Text -}} -{{< /code >}} +``` To add an anchor link to the right of each heading: -{{< code file=layouts/_default/_markup/render-heading.html copy=true >}} +```go-html-template {file="layouts/_default/_markup/render-heading.html" copy=true} {{ .Text }} # -{{< /code >}} +``` -{{% include "/render-hooks/_common/pageinner.md" %}} +{{% include "/_common/render-hooks/pageinner.md" %}} diff --git a/content/en/render-hooks/images.md b/content/en/render-hooks/images.md index 63f294081..a4faac672 100755 --- a/content/en/render-hooks/images.md +++ b/content/en/render-hooks/images.md @@ -2,14 +2,8 @@ title: Image render hooks linkTitle: Images description: Create an image render to hook override the rendering of Markdown images to HTML. -categories: [render hooks] +categories: [] keywords: [] -menu: - docs: - parent: render-hooks - weight: 60 -weight: 60 -toc: true --- ## Markdown @@ -28,76 +22,59 @@ These components are passed into the render hook [context](g) as shown below. Image render hook templates receive the following context: -###### Attributes +Attributes +: (`map`) The [Markdown attributes], available if you configure your site as follows: -(`map`) The [Markdown attributes], available if you configure your site as follows: + {{< code-toggle file=hugo >}} + [markup.goldmark.parser] + wrapStandAloneImageWithinParagraph = false + [markup.goldmark.parser.attribute] + block = true + {{< /code-toggle >}} -[Markdown attributes]: /content-management/markdown-attributes/ +Destination +: (`string`) The image destination. -{{< code-toggle file=hugo >}} -[markup.goldmark.parser] -wrapStandAloneImageWithinParagraph = false -[markup.goldmark.parser.attribute] -block = true -{{< /code-toggle >}} +IsBlock +: (`bool`) Reports whether a standalone image is not wrapped within a paragraph element. -###### Destination +Ordinal +: (`int`) The zero-based ordinal of the image on the page. -(`string`) The image destination. +Page +: (`page`) A reference to the current page. -###### IsBlock +PageInner +: {{< new-in 0.125.0 />}} +: (`page`) A reference to a page nested via the [`RenderShortcodes`] method. [See details](#pageinner-details). -(`bool`) Returns true if a standalone image is not wrapped within a paragraph element. +PlainText +: (`string`) The image description as plain text. -###### Ordinal +Text +: (`template.HTML`) The image description. -(`int`) The zero-based ordinal of the image on the page. - -###### Page - -(`page`) A reference to the current page. - -###### PageInner - -{{< new-in 0.125.0 />}} - -(`page`) A reference to a page nested via the [`RenderShortcodes`] method. [See details](#pageinner-details). - -[`RenderShortcodes`]: /methods/page/rendershortcodes - -###### PlainText - -(`string`) The image description as plain text. - -###### Text - -(`template.HTML`) The image description. - -###### Title - -(`string`) The image title. +Title +: (`string`) The image title. ## Examples -{{% note %}} -With inline elements such as images and links, remove leading and trailing whitespace using the `{{‑ ‑}}` delimiter notation to prevent whitespace between adjacent inline elements and text. -{{% /note %}} +> [!note] +> With inline elements such as images and links, remove leading and trailing whitespace using the `{{‑ ‑}}` delimiter notation to prevent whitespace between adjacent inline elements and text. In its default configuration, Hugo renders Markdown images according to the [CommonMark specification]. To create a render hook that does the same thing: -[CommonMark specification]: https://spec.commonmark.org/current/ - -{{< code file=layouts/_default/_markup/render-image.html copy=true >}} +```go-html-template {file="layouts/_default/_markup/render-image.html" copy=true} {{ . }} {{- /* chomp trailing newline */ -}} -{{< /code >}} +``` To render standalone images within `figure` elements: -{{< code file=layouts/_default/_markup/render-image.html copy=true >}} +```go-html-template {file="layouts/_default/_markup/render-image.html" copy=true} {{- if .IsBlock -}}
{{- end -}} -{{< /code >}} +``` Note that the above requires the following site configuration: @@ -126,8 +103,6 @@ wrapStandAloneImageWithinParagraph = false Hugo includes an [embedded image render hook] to resolve Markdown image destinations. Disabled by default, you can enable it in your site configuration: -[embedded image render hook]: {{% eturl render-image %}} - {{< code-toggle file=hugo >}} [markup.goldmark.renderHooks.image] enableDefault = true @@ -135,11 +110,8 @@ enableDefault = true A custom render hook, even when provided by a theme or module, will override the embedded render hook regardless of the configuration setting above. -{{% note %}} -The embedded image render hook is automatically enabled for multilingual single-host sites if [duplication of shared page resources] is disabled. This is the default configuration for multilingual single-host sites. - -[duplication of shared page resources]: /getting-started/configuration-markup/#duplicateresourcefiles -{{% /note %}} +> [!note] +> The embedded image render hook is automatically enabled for multilingual single-host sites if [duplication of shared page resources] is disabled. This is the default configuration for multilingual single-host sites. 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. @@ -157,4 +129,10 @@ target = 'assets' Note that the embedded image render hook does not perform image processing. Its sole purpose is to resolve Markdown image destinations. -{{% include "/render-hooks/_common/pageinner.md" %}} +{{% include "/_common/render-hooks/pageinner.md" %}} + +[`RenderShortcodes`]: /methods/page/rendershortcodes +[CommonMark specification]: https://spec.commonmark.org/current/ +[duplication of shared page resources]: /configuration/markup/#duplicateresourcefiles +[embedded image render hook]: {{% eturl render-image %}} +[Markdown attributes]: /content-management/markdown-attributes/ diff --git a/content/en/render-hooks/introduction.md b/content/en/render-hooks/introduction.md index d086c91bb..045d25c3d 100755 --- a/content/en/render-hooks/introduction.md +++ b/content/en/render-hooks/introduction.md @@ -1,14 +1,9 @@ --- title: Introduction description: An introduction to Hugo's render hooks. -categories: [render hooks] +categories: [] keywords: [] -menu: - docs: - identifier: render-hooks-introduction - parent: render-hooks - weight: 20 -weight: 20 +weight: 10 --- When rendering Markdown to HTML, render hooks override the conversion. Each render hook is a template, with one template for each supported element type: @@ -21,13 +16,10 @@ When rendering Markdown to HTML, render hooks override the conversion. Each rend - [Passthrough elements](/render-hooks/passthrough) - [Tables](/render-hooks/tables) -{{% note %}} -Hugo supports multiple [content formats] including Markdown, HTML, AsciiDoc, Emacs Org Mode, Pandoc, and reStructuredText. - -The render hook capability is limited to Markdown. You cannot create render hooks for the other content formats. - -[content formats]: /content-management/formats/ -{{% /note %}} +> [!note] +> Hugo supports multiple [content formats] including Markdown, HTML, AsciiDoc, Emacs Org Mode, Pandoc, and reStructuredText. +> +> The render hook capability is limited to Markdown. You cannot create render hooks for the other content formats. For example, consider this Markdown: @@ -37,7 +29,7 @@ For example, consider this Markdown: ![kitten](kitten.jpg) ``` -Without link or image render hooks, this example above is rendered to: +Without link or image render hooks, the example above is rendered to: ```html

Hugo

@@ -85,3 +77,5 @@ layouts/ ``` The remaining pages in this section describe each type of render hook, including examples and the context received by each template. + +[content formats]: /content-management/formats/ diff --git a/content/en/render-hooks/links.md b/content/en/render-hooks/links.md index 89044c662..23f725eb7 100755 --- a/content/en/render-hooks/links.md +++ b/content/en/render-hooks/links.md @@ -2,14 +2,8 @@ title: Link render hooks linkTitle: Links description: Create a link render hook to override the rendering of Markdown links to HTML. -categories: [render hooks] +categories: [] keywords: [] -menu: - docs: - parent: render-hooks - weight: 70 -weight: 70 -toc: true --- ## Markdown @@ -28,56 +22,44 @@ These components are passed into the render hook [context](g) as shown below. Link render hook templates receive the following context: -###### Destination +Destination +: (`string`) The link destination. -(`string`) The link destination. +Page +: (`page`) A reference to the current page. -###### Page +PageInner +: {{< new-in 0.125.0 />}} +: (`page`) A reference to a page nested via the [`RenderShortcodes`] method. [See details](#pageinner-details). -(`page`) A reference to the current page. +PlainText +: (`string`) The link description as plain text. -###### PageInner +Text +: (`template.HTML`) The link description. -{{< new-in 0.125.0 />}} - -(`page`) A reference to a page nested via the [`RenderShortcodes`] method. [See details](#pageinner-details). - -[`RenderShortcodes`]: /methods/page/rendershortcodes - -###### PlainText - -(`string`) The link description as plain text. - -###### Text - -(`template.HTML`) The link description. - -###### Title - -(`string`) The link title. +Title +: (`string`) The link title. ## Examples -{{% note %}} -With inline elements such as images and links, remove leading and trailing whitespace using the `{{‑ ‑}}` delimiter notation to prevent whitespace between adjacent inline elements and text. -{{% /note %}} +> [!note] +> With inline elements such as images and links, remove leading and trailing whitespace using the `{{‑ ‑}}` delimiter notation to prevent whitespace between adjacent inline elements and text. In its default configuration, Hugo renders Markdown links according to the [CommonMark specification]. To create a render hook that does the same thing: -[CommonMark specification]: https://spec.commonmark.org/current/ - -{{< code file=layouts/_default/_markup/render-link.html copy=true >}} +```go-html-template {file="layouts/_default/_markup/render-link.html" copy=true} {{- with .Text }}{{ . }}{{ end -}} {{- /* chomp trailing newline */ -}} -{{< /code >}} +``` To include a `rel` attribute set to `external` for external links: -{{< code file=layouts/_default/_markup/render-link.html copy=true >}} +```go-html-template {file="layouts/_default/_markup/render-link.html" copy=true} {{- $u := urls.Parse .Destination -}} {{- /* chomp trailing newline */ -}} -{{< /code >}} +``` ## Default @@ -94,8 +76,6 @@ To include a `rel` attribute set to `external` for external links: Hugo includes an [embedded link render hook] to resolve Markdown link destinations. Disabled by default, you can enable it in your site configuration: -[embedded link render hook]: {{% eturl render-link %}} - {{< code-toggle file=hugo >}} [markup.goldmark.renderHooks.link] enableDefault = true @@ -103,11 +83,8 @@ enableDefault = true A custom render hook, even when provided by a theme or module, will override the embedded render hook regardless of the configuration setting above. -{{% note %}} -The embedded link render hook is automatically enabled for multilingual single-host sites if [duplication of shared page resources] is disabled. This is the default configuration for multilingual single-host sites. - -[duplication of shared page resources]: /getting-started/configuration-markup/#duplicateresourcefiles -{{% /note %}} +> [!note] +> The embedded link render hook is automatically enabled for multilingual single-host sites if [duplication of shared page resources] is disabled. This is the default configuration for multilingual single-host sites. 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. @@ -123,4 +100,9 @@ source = 'static' target = 'assets' {{< /code-toggle >}} -{{% include "/render-hooks/_common/pageinner.md" %}} +{{% include "/_common/render-hooks/pageinner.md" %}} + +[`RenderShortcodes`]: /methods/page/rendershortcodes +[CommonMark specification]: https://spec.commonmark.org/current/ +[duplication of shared page resources]: /configuration/markup/#duplicateresourcefiles +[embedded link render hook]: {{% eturl render-link %}} diff --git a/content/en/render-hooks/passthrough.md b/content/en/render-hooks/passthrough.md index 798225061..356a030af 100755 --- a/content/en/render-hooks/passthrough.md +++ b/content/en/render-hooks/passthrough.md @@ -1,29 +1,23 @@ --- title: Passthrough render hooks linkTitle: Passthrough -description: Create a passthrough render hook to override the rendering of text snippets captured by the Goldmark passthrough extension. -categories: [render hooks] +description: Create a passthrough render hook to override the rendering of text snippets captured by the Goldmark Passthrough extension. +categories: [] keywords: [] -menu: - docs: - parent: render-hooks - weight: 80 -weight: 80 -toc: true --- {{< new-in 0.132.0 />}} ## Overview -Hugo uses [Goldmark] to render Markdown to HTML. Goldmark supports custom extensions to extend its core functionality. The Goldmark [passthrough extension] captures and preserves raw Markdown within delimited snippets of text, including the delimiters themselves. These are known as _passthrough elements_. +Hugo uses [Goldmark] to render Markdown to HTML. Goldmark supports custom extensions to extend its core functionality. The [Passthrough] extension captures and preserves raw Markdown within delimited snippets of text, including the delimiters themselves. These are known as _passthrough elements_. [Goldmark]: https://github.com/yuin/goldmark -[passthrough extension]: /getting-started/configuration-markup/#passthrough +[Passthrough]: /configuration/markup/#passthrough Depending on your choice of delimiters, Hugo will classify a passthrough element as either _block_ or _inline_. Consider this contrived example: -{{< code file=content/sample.md >}} +```text {file="content/example.md"} This is a \[block\] @@ -31,9 +25,9 @@ This is a passthrough element with opening and closing block delimiters. This is an \(inline\) passthrough element with opening and closing inline delimiters. -{{< /code >}} +``` -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 site 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] @@ -45,7 +39,7 @@ inline = [['\(', '\)']] In the example above there are two sets of `block` delimiters. You may use either one in your Markdown. -The Goldmark passthrough extension is often used in conjunction with the MathJax or KaTeX display engine to render [mathematical expressions] written in the LaTeX markup language. +The Passthrough extension is often used in conjunction with the MathJax or KaTeX display engine to render [mathematical expressions] written in the LaTeX markup language. [mathematical expressions]: /content-management/mathematics/ @@ -55,72 +49,65 @@ To enable custom rendering of passthrough elements, create a passthrough render Passthrough render hook templates receive the following [context](g): -###### Attributes +Attributes +: (`map`) The [Markdown attributes], available if you configure your site as follows: -(`map`) The [Markdown attributes], available if you configure your site as follows: + {{< code-toggle file=hugo >}} + [markup.goldmark.parser.attribute] + block = true + {{< /code-toggle >}} + + Hugo populates the `Attributes` map for _block_ passthrough elements. Markdown attributes are not applicable to _inline_ elements. + +Inner +: (`string`) The inner content of the passthrough element, excluding the delimiters. + +Ordinal +: (`int`) The zero-based ordinal of the passthrough element on the page. + +Page +: (`page`) A reference to the current page. + +PageInner +: (`page`) A reference to a page nested via the [`RenderShortcodes`] method. [See details](#pageinner-details). + +Position +: (`string`) The position of the passthrough element within the page content. + +Type +: (`string`) The passthrough element type, either `block` or `inline`. [Markdown attributes]: /content-management/markdown-attributes/ - -{{< code-toggle file=hugo >}} -[markup.goldmark.parser.attribute] -block = true -{{< /code-toggle >}} - -Hugo populates the `Attributes` map for _block_ passthrough elements. Markdown attributes are not applicable to _inline_ elements. - -###### Inner -(`string`) The inner content of the passthrough element, excluding the delimiters. - -###### Ordinal - -(`int`) The zero-based ordinal of the passthrough element on the page. - -###### Page - -(`page`) A reference to the current page. - -###### PageInner - -(`page`) A reference to a page nested via the [`RenderShortcodes`] method. [See details](#pageinner-details). - [`RenderShortcodes`]: /methods/page/rendershortcodes -###### Position - -(`string`) The position of the passthrough element within the page content. - -###### Type - -(`string`) The passthrough element type, either `block` or `inline`. - ## Example Instead of client-side JavaScript rendering of mathematical markup using MathJax or KaTeX, create a passthrough render hook which calls the [`transform.ToMath`] function. [`transform.ToMath`]: /functions/transform/tomath/ -{{< code file=layouts/_default/_markup/render-passthrough.html copy=true >}} +```go-html-template {file="layouts/_default/_markup/render-passthrough.html" copy=true} {{- $opts := dict "output" "htmlAndMathml" "displayMode" (eq .Type "block") }} {{- with try (transform.ToMath .Inner $opts) }} {{- with .Err }} - {{ errorf "Unable to render mathematical markup to HTML using the transform.ToMath function. The KaTeX display engine threw the following error: %s: see %s." . $.Position }} + {{- errorf "Unable to render mathematical markup to HTML using the transform.ToMath function. The KaTeX display engine threw the following error: %s: see %s." . $.Position }} {{- else }} {{- .Value }} {{- $.Page.Store.Set "hasMath" true }} {{- end }} {{- end -}} -{{< /code >}} +``` Then, in your base template, conditionally include the KaTeX CSS within the head element: -{{< code file=layouts/_default/baseof.html copy=true >}} +```go-html-template {file="layouts/_default/baseof.html" copy=true} {{ $noop := .WordCount }} {{ if .Page.Store.Get "hasMath" }} {{ end }} -{{< /code >}} +``` In the above, note the use of a [noop](g) statement to force content rendering before we check the value of `hasMath` with the `Store.Get` method. @@ -134,4 +121,4 @@ layouts/ └── render-passthrough-inline.html ``` -{{% include "/render-hooks/_common/pageinner.md" %}} +{{% include "/_common/render-hooks/pageinner.md" %}} diff --git a/content/en/render-hooks/tables.md b/content/en/render-hooks/tables.md index d131664fc..c7671aff4 100755 --- a/content/en/render-hooks/tables.md +++ b/content/en/render-hooks/tables.md @@ -2,14 +2,8 @@ title: Table render hooks linkTitle: Tables description: Create a table render hook to override the rendering of Markdown tables to HTML. -categories: [render hooks] +categories: [] keywords: [] -menu: - docs: - parent: render-hooks - weight: 90 -weight: 90 -toc: true --- {{< new-in 0.134.0 />}} @@ -18,50 +12,44 @@ toc: true Table render hook templates receive the following [context](g): -###### Attributes +Attributes +: (`map`) The [Markdown attributes], available if you configure your site as follows: -(`map`) The [Markdown attributes], available if you configure your site as follows: + {{< code-toggle file=hugo >}} + [markup.goldmark.parser.attribute] + block = true + {{< /code-toggle >}} + +Ordinal +: (`int`) The zero-based ordinal of the table on the page. + +Page +: (`page`) A reference to the current page. + +PageInner +: (`page`) A reference to a page nested via the [`RenderShortcodes`] method. [See details](#pageinner-details). + +Position +: (`string`) The position of the table within the page content. + +THead +: (`slice`) A slice of table header rows, where each element is a slice of table cells. + +TBody +: (`slice`) A slice of table body rows, where each element is a slice of table cells. [Markdown attributes]: /content-management/markdown-attributes/ - -{{< code-toggle file=hugo >}} -[markup.goldmark.parser.attribute] -block = true -{{< /code-toggle >}} - -###### Ordinal - -(`int`) The zero-based ordinal of the table on the page. - -###### Page - -(`page`) A reference to the current page. - -###### PageInner - -(`page`) A reference to a page nested via the [`RenderShortcodes`] method. [See details](#pageinner-details). - [`RenderShortcodes`]: /methods/page/rendershortcodes -###### Position - -(`string`) The position of the table within the page content. - -###### THead -(`slice`) A slice of table header rows, where each element is a slice of table cells. - -###### TBody -(`slice`) A slice of table body rows, where each element is a slice of table cells. - ## Table cells Each table cell within the slice of slices returned by the `THead` and `TBody` methods has the following fields: -###### Alignment -(`string`) The alignment of the text within the table cell, one of `left`, `center`, or `right`. +Alignment +: (`string`) The alignment of the text within the table cell, one of `left`, `center`, or `right`. -###### Text -(`template.HTML`) The text within the table cell. +Text +: (`template.HTML`) The text within the table cell. ## Example @@ -69,7 +57,7 @@ In its default configuration, Hugo renders Markdown tables according to the [Git [GitHub Flavored Markdown specification]: https://github.github.com/gfm/#tables-extension- -{{< code file=layouts/_default/_markup/render-table.html copy=true >}} +```go-html-template {file="layouts/_default/_markup/render-table.html" copy=true}
-{{< /code >}} +``` -{{% include "/render-hooks/_common/pageinner.md" %}} +{{% include "/_common/render-hooks/pageinner.md" %}} diff --git a/content/en/shortcodes/_index.md b/content/en/shortcodes/_index.md index 2d9a8fdd6..826ee5796 100644 --- a/content/en/shortcodes/_index.md +++ b/content/en/shortcodes/_index.md @@ -1,16 +1,7 @@ --- title: Shortcodes - description: Insert elements such as videos, images, and social media embeds into your content using Hugo's embedded shortcodes. categories: [] keywords: [] -menu: - docs: - identifier: shortcodes-in-this-section - parent: shortcodes - weight: 10 weight: 10 -showSectionMenu: true --- - -Insert elements such as videos, images, and social media embeds into your content using Hugo's embedded shortcodes. diff --git a/content/en/shortcodes/comment.md b/content/en/shortcodes/comment.md deleted file mode 100755 index 1600c09d3..000000000 --- a/content/en/shortcodes/comment.md +++ /dev/null @@ -1,39 +0,0 @@ ---- -title: Comment -description: Include hidden comments in your content with the comment shortcode. -categories: [shortcodes] -keywords: [] -menu: - docs: - identifier: shortcodes-comment - parent: shortcodes - weight: -weight: -expiryDate: 2025-01-22 # deprecated 2025-02-01 in v0.143.0 and immediately removed from the documentation ---- - -{{% note %}} -To override Hugo's embedded `comment` shortcode, copy the [source code] to a file with the same name in the `layouts/shortcodes` directory. - -[source code]: {{% eturl comment %}} -{{% /note %}} - -{{< new-in 0.137.1 />}} - -Use the `comment` shortcode to include comments in your content. Hugo will ignore the text within these comments when rendering your site. - -Use it inline: - -```text -{{%/* comment */%}} rewrite the paragraph below {{%/* /comment */%}} -``` - -Or as a block comment: - -```text -{{%/* comment */%}} -rewrite the paragraph below -{{%/* /comment */%}} -``` - -Although you can call this shortcode using the `{{}}` notation, computationally it is more efficient to call it using the `{{%/* */%}}` notation as shown above. diff --git a/content/en/shortcodes/details.md b/content/en/shortcodes/details.md index f30f81d75..94502ac1c 100755 --- a/content/en/shortcodes/details.md +++ b/content/en/shortcodes/details.md @@ -1,23 +1,15 @@ --- -title: Details +title: Details shortcode +linkTitle: Details description: Insert an HTML details element into your content using the details shortcode. -categories: [shortcodes] +categories: [] keywords: [] -menu: - docs: - parent: shortcodes - weight: -weight: -toc: true --- {{< new-in 0.140.0 />}} -{{% note %}} -To override Hugo's embedded `details` shortcode, copy the [source code] to a file with the same name in the `layouts/shortcodes` directory. - -[source code]: {{% eturl details %}} -{{% /note %}} +> [!note] +> To override Hugo's embedded `details` shortcode, copy the [source code] to a file with the same name in the `layouts/shortcodes` directory. ## Example @@ -44,7 +36,7 @@ Which looks like this in your browser: This is a **bold** word. {{< /details >}} -## Parameters +## Arguments summary : (`string`) The content of the child `summary` element rendered from Markdown to HTML. Default is `Details`. @@ -78,3 +70,5 @@ details > summary > * { } /* target the content */ details > :not(summary) { } ``` + +[source code]: {{% eturl details %}} diff --git a/content/en/shortcodes/figure.md b/content/en/shortcodes/figure.md index eb98598b6..74af52fe7 100755 --- a/content/en/shortcodes/figure.md +++ b/content/en/shortcodes/figure.md @@ -1,21 +1,13 @@ --- -title: Figure +title: Figure shortcode +linkTitle: Figure description: Insert an HTML figure element into your content using the figure shortcode. -categories: [shortcodes] +categories: [] keywords: [] -menu: - docs: - parent: shortcodes - weight: -weight: -toc: true --- -{{% note %}} -To override Hugo's embedded `figure` shortcode, copy the [source code] to a file with the same name in the `layouts/shortcodes` directory. - -[source code]: {{% eturl figure %}} -{{% /note %}} +> [!note] +> To override Hugo's embedded `figure` shortcode, copy the [source code] to a file with the same name in the `layouts/shortcodes` directory. ## Example @@ -57,7 +49,7 @@ Which looks like this in your browser: class="ma0 w-75" >}} -## Parameters +## Arguments src : (`string`) The `src` attribute of the `img` element. Typically this is a [page resource](g) or a [global resource](g). @@ -113,3 +105,5 @@ target = 'assets' source = 'static' target = 'assets' {{< /code-toggle >}} + +[source code]: {{% eturl figure %}} diff --git a/content/en/shortcodes/gist.md b/content/en/shortcodes/gist.md index 1c740bccb..fd2b468ab 100755 --- a/content/en/shortcodes/gist.md +++ b/content/en/shortcodes/gist.md @@ -1,26 +1,20 @@ --- -title: Gist +title: Gist shortcode +linkTitle: Gist description: Embed a GitHub Gist in your content using the gist shortcode. -categories: [shortcodes] +categories: [] keywords: [] -menu: - docs: - parent: shortcodes - weight: -weight: expiryDate: 2027-02-01 # deprecated 2025-02-01 in v0.143.0 --- -{{% deprecated-in 0.143.0 %}} +{{< deprecated-in 0.143.0 >}} The `gist` shortcode was deprecated in version 0.143.0 and will be removed in a future release. To continue embedding GitHub Gists in your content, you'll need to create a custom shortcode: 1. Create a new file: Create a file named `gist.html` within the `layouts/shortcodes` directory. -2. Copy the source code: Paste the [original source code] of the gist shortcode into the newly created `gist.html` file. +1. Copy the source code: Paste the [original source code]({{% eturl gist %}}) of the gist shortcode into the newly created `gist.html` file. This will allow you to maintain the functionality of embedding GitHub Gists in your content after the deprecation of the original shortcode. - -[original source code]: {{% eturl gist %}} -{{% /deprecated-in %}} +{{< /deprecated-in >}} To display a GitHub gist with this URL: diff --git a/content/en/shortcodes/highlight.md b/content/en/shortcodes/highlight.md index 0a35aa4e6..371a3d46e 100755 --- a/content/en/shortcodes/highlight.md +++ b/content/en/shortcodes/highlight.md @@ -1,35 +1,20 @@ --- -title: Highlight +title: Highlight shortcode +linkTitle: Highlight description: Insert syntax-highlighted code into your content using the highlight shortcode. -categories: [shortcodes] -keywords: [] -menu: - docs: - parent: shortcodes - weight: -weight: -toc: true +categories: [] +keywords: [highlight] --- -{{% note %}} -To override Hugo's embedded `highlight` shortcode, copy the [source code] to a file with the same name in the `layouts/shortcodes` directory. +> [!note] +> To override Hugo's embedded `highlight` shortcode, copy the [source code] to a file with the same name in the `layouts/shortcodes` directory. -[source code]: {{% eturl highlight %}} -{{% /note %}} +> [!note] +> With the Markdown [content format], the `highlight` shortcode is rarely needed because, by default, Hugo automatically applies syntax highlighting to fenced code blocks. +> +> The primary use case for the `highlight` shortcode in Markdown is to apply syntax highlighting to inline code snippets. -{{% note %}} -With the Markdown [content format], the `highlight` shortcode is rarely needed because, by default, Hugo automatically applies syntax highlighting to fenced code blocks. - -The primary use case for the `highlight` shortcode in Markdown is to apply syntax highlighting to inline code snippets. - -[content format]: /content-management/formats/ -{{% /note %}} - -The `highlight` shortcode calls the [`transform.Highlight`] function which uses the [Chroma] syntax highlighter, supporting over 200 languages with more than 40 [available styles]. - -[chroma]: https://github.com/alecthomas/chroma -[available styles]: https://xyproto.github.io/splash/docs/ -[`transform.Highlight`]: /functions/transform/highlight/ +The `highlight` shortcode calls the [`transform.Highlight`] function which uses the [Chroma] syntax highlighter, supporting over 200 languages with more than 40 [highlighting styles]. ## Arguments @@ -50,13 +35,10 @@ LANG 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. -[site configuration]: /getting-started/configuration-markup#highlight -[supported languages]: /content-management/syntax-highlighting/#list-of-chroma-highlighting-languages - ## Example ```text -{{}} +{{}} package main import "fmt" @@ -95,12 +77,12 @@ This is some {{< highlight go "hl_inline=true, noClasses=true" >}}fmt.Println("i Given the verbosity of the example above, if you need to frequently highlight inline code snippets, create your own shortcode using a shorter name with preset options. -{{< code file=layouts/shortcodes/hl.html >}} +```go-html-template {file="layouts/shortcodes/hl.html"} {{ $code := .Inner | strings.TrimSpace }} -{{ $lang := or (.Get 0) "go" }} +{{ $lang := or (.Get 0) "go" }} {{ $opts := dict "hl_inline" true "noClasses" true }} {{ transform.Highlight $code $lang $opts }} -{{< /code >}} +``` ```text This is some {{}}fmt.Println("inline"){{}} code. @@ -114,4 +96,12 @@ This is some {{< hl >}}fmt.Println("inline"){{< /hl >}} code. Pass the options when calling the shortcode. You can set their default values in your [site configuration]. -{{% include "functions/_common/highlighting-options" %}} +{{% include "_common/syntax-highlighting-options.md" %}} + +[`transform.Highlight`]: /functions/transform/highlight/ +[Chroma]: https://github.com/alecthomas/chroma +[content format]: /content-management/formats/ +[highlighting styles]: /quick-reference/syntax-highlighting-styles/ +[site 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 eb2bb7671..3256790c6 100755 --- a/content/en/shortcodes/instagram.md +++ b/content/en/shortcodes/instagram.md @@ -1,21 +1,13 @@ --- -title: Instagram +title: Instagram shortcode +linkTitle: Instagram description: Embed an Instagram post in your content using the instagram shortcode. -categories: [shortcodes] +categories: [] keywords: [] -menu: - docs: - parent: shortcodes - weight: -weight: -toc: true --- -{{% note %}} -To override Hugo's embedded `instagram` shortcode, copy the [source code] to a file with the same name in the `layouts/shortcodes` directory. - -[source code]: {{% eturl instagram %}} -{{% /note %}} +> [!note] +> To override Hugo's embedded `instagram` shortcode, copy the [source code] to a file with the same name in the `layouts/shortcodes` directory. ## Example @@ -46,3 +38,5 @@ disable simple : (`bool`) Whether to enable simple mode for image card generation. If `true`, Hugo creates a static card without JavaScript. This mode only supports image cards, and the image is fetched directly from Instagram's servers. Default is `false`. + +[source code]: {{% eturl instagram %}} diff --git a/content/en/shortcodes/param.md b/content/en/shortcodes/param.md index bff659ec1..133b2322a 100755 --- a/content/en/shortcodes/param.md +++ b/content/en/shortcodes/param.md @@ -1,24 +1,17 @@ --- -title: Param +title: Param shortcode +linkTitle: Param description: Insert a parameter from front matter or site configuration into your content using the param shortcode. -categories: [shortcodes] +categories: [] keywords: [] -menu: - docs: - parent: shortcodes - weight: -weight: --- -{{% note %}} -To override Hugo's embedded `param` shortcode, copy the [source code] to a file with the same name in the `layouts/shortcodes` directory. - -[source code]: {{% eturl param %}} -{{% /note %}} +> [!note] +> To override Hugo's embedded `param` shortcode, copy the [source code] to a file with the same name in the `layouts/shortcodes` directory. The `param` shortcode renders a parameter from front matter, falling back to a site parameter of the same name. The shortcode throws an error if the parameter does not exist. -{{< code file=example.md lang=text >}} +```text {file="content/example.md"} --- title: Example date: 2025-01-15T23:29:46-08:00 @@ -28,7 +21,7 @@ params: --- We found a {{%/* param "color" */%}} shirt. -{{< /code >}} +``` Hugo renders this to: @@ -41,3 +34,5 @@ Access nested values by [chaining](g) the [identifiers](g): ```text {{%/* param my.nested.param */%}} ``` + +[source code]: {{% eturl param %}} diff --git a/content/en/shortcodes/qr.md b/content/en/shortcodes/qr.md index a7a6d92cb..98d6cee4c 100755 --- a/content/en/shortcodes/qr.md +++ b/content/en/shortcodes/qr.md @@ -1,31 +1,20 @@ --- -title: QR +title: QR shortcode +linkTitle: QR description: Insert a QR code into your content using the qr shortcode. -categories: [shortcodes] +categories: [] keywords: [] -menu: - docs: - parent: shortcodes - weight: -weight: -toc: true --- {{< new-in 0.141.0 />}} -{{% note %}} -To override Hugo's embedded `qr` shortcode, copy the [source code] to a file with the same name in the `layouts/shortcodes` directory. - -[source code]: {{% eturl qr %}} -{{% /note %}} +> [!note] +> To override Hugo's embedded `qr` shortcode, copy the [source code] to a file with the same name in the `layouts/shortcodes` directory. The `qr` shortcode encodes the given text into a [QR code] using the specified options and renders the resulting image. Internally this shortcode calls the `images.QR` function. Please read the [related documentation] for implementation details and guidance. -[QR code]: https://en.wikipedia.org/wiki/QR_code -[related documentation]: /functions/images/qr/ - ## Examples Use the self-closing syntax to pass the text as an argument: @@ -56,8 +45,6 @@ To create a QR code for a phone number: To create a QR code containing contact information in the [vCard] format: -[vCard]: https://en.wikipedia.org/wiki/VCard - ```text {{}} BEGIN:VCARD @@ -84,7 +71,7 @@ EMAIL;TYPE=WORK:jsmith@example.org END:VCARD {{< /qr >}} -## Parameters +## Arguments text : (`string`) The text to encode, falling back to the text between the opening and closing shortcode tags. @@ -98,8 +85,6 @@ scale targetDir : (`string`) The subdirectory within the [`publishDir`] where Hugo will place the generated image. -[`publishDir`]: /getting-started/configuration/#publishdir - alt : (`string`) The `alt` attribute of the `img` element. @@ -109,5 +94,14 @@ class id : (`string`) The `id` attribute of the `img` element. +loading +: (`string`) The `loading` attribute of the `img` element, either `eager` or `lazy`. + title : (`string`) The `title` attribute of the `img` element. + +[`publishDir`]: /configuration/all/#publishdir +[QR code]: https://en.wikipedia.org/wiki/QR_code +[related documentation]: /functions/images/qr/ +[source code]: {{% eturl qr %}} +[vCard]: https://en.wikipedia.org/wiki/VCard diff --git a/content/en/shortcodes/ref.md b/content/en/shortcodes/ref.md index af133447e..2f821254c 100755 --- a/content/en/shortcodes/ref.md +++ b/content/en/shortcodes/ref.md @@ -1,48 +1,61 @@ --- -title: Ref +title: Ref shortcode +linkTitle: Ref description: Insert a permalink to the given page reference using the ref shortcode. -categories: [shortcodes] +categories: [] keywords: [] -menu: - docs: - parent: shortcodes - weight: -weight: --- -{{% note %}} -To override Hugo's embedded `ref` shortcode, copy the [source code] to a file with the same name in the `layouts/shortcodes` directory. +> [!note] +> To override Hugo's embedded `ref` shortcode, copy the [source code] to a file with the same name in the `layouts/shortcodes` directory. -[source code]: {{% eturl ref %}} -{{% /note %}} +> [!note] +> When working with the Markdown [content format], this shortcode has become largely redundant. Its functionality is now primarily handled by [link render hooks], specifically the embedded one provided by Hugo. This hook effectively addresses all the use cases previously covered by this shortcode. -{{% note %}} -When working with the Markdown [content format], this shortcode has become largely redundant. Its functionality is now primarily handled by [link render hooks], specifically the embedded one provided by Hugo. This hook effectively addresses all the use cases previously covered by this shortcode. +## Usage -[content format]: /content-management/formats/ -[link render hooks]: /render-hooks/images/#default -{{% /note %}} +The `ref` shortcode accepts either a single positional argument (the path) or one or more named arguments, as listed below. -The `ref` shortcode returns the permalink of the given page reference. +## Arguments -Example usage: +{{% include "_common/ref-and-relref-options.md" %}} -```text -[Post 1]({{%/* ref "/posts/post-1" */%}}) -[Post 1]({{%/* ref "/posts/post-1.md" */%}}) -[Post 1]({{%/* ref "/posts/post-1#foo" */%}}) -[Post 1]({{%/* ref "/posts/post-1.md#foo" */%}}) +## Examples + +The `ref` shortcode typically provides the destination for a Markdown link. + +> [!note] +> Always use [Markdown notation] notation when calling this shortcode. + +The following examples show the rendered output for a page on the English version of the site: + +```md +[Link A]({{%/* ref "/books/book-1" */%}}) + +[Link B]({{%/* ref path="/books/book-1" */%}}) + +[Link C]({{%/* ref path="/books/book-1" lang="de" */%}}) + +[Link D]({{%/* ref path="/books/book-1" lang="de" outputFormat="json" */%}}) ``` Rendered: ```html -Post 1 -Post 1 -Post 1 -Post 1 +Link A + +Link B + +Link C + +Link D ``` -{{% note %}} -Always use the `{{%/* */%}}` notation when calling this shortcode. -{{% /note %}} +## Error handling + +{{% include "_common/ref-and-relref-error-handling.md" %}} + +[content format]: /content-management/formats/ +[link render hooks]: /render-hooks/images/#default +[Markdown notation]: /content-management/shortcodes/#notation +[source code]: {{% eturl ref %}} diff --git a/content/en/shortcodes/relref.md b/content/en/shortcodes/relref.md index e98e82919..5b413b87e 100755 --- a/content/en/shortcodes/relref.md +++ b/content/en/shortcodes/relref.md @@ -1,48 +1,61 @@ --- -title: Relref +title: Relref shortcode +linkTitle: Relref description: Insert a relative permalink to the given page reference using the relref shortcode. -categories: [shortcodes] +categories: [] keywords: [] -menu: - docs: - parent: shortcodes - weight: -weight: --- -{{% note %}} -To override Hugo's embedded `relref` shortcode, copy the [source code] to a file with the same name in the `layouts/shortcodes` directory. +> [!note] +> To override Hugo's embedded `relref` shortcode, copy the [source code] to a file with the same name in the `layouts/shortcodes` directory. -[source code]: {{% eturl relref %}} -{{% /note %}} +> [!note] +> When working with the Markdown [content format], this shortcode has become largely redundant. Its functionality is now primarily handled by [link render hooks], specifically the embedded one provided by Hugo. This hook effectively addresses all the use cases previously covered by this shortcode. -{{% note %}} -When working with the Markdown [content format], this shortcode has become largely redundant. Its functionality is now primarily handled by [link render hooks], specifically the embedded one provided by Hugo. This hook effectively addresses all the use cases previously covered by this shortcode. +## Usage -[content format]: /content-management/formats/ -[link render hooks]: /render-hooks/links/ -{{% /note %}} +The `relref` shortcode accepts either a single positional argument (the path) or one or more named arguments, as listed below. -The `relref` shortcode returns the relative permalink of the given page reference. +## Arguments -Example usage: +{{% include "_common/ref-and-relref-options.md" %}} -```text -[Post 1]({{%/* relref "/posts/post-1" */%}}) -[Post 1]({{%/* relref "/posts/post-1.md" */%}}) -[Post 1]({{%/* relref "/posts/post-1#foo" */%}}) -[Post 1]({{%/* relref "/posts/post-1.md#foo" */%}}) +## Examples + +The `relref` shortcode typically provides the destination for a Markdown link. + +> [!note] +> Always use [Markdown notation] notation when calling this shortcode. + +The following examples show the rendered output for a page on the English version of the site: + +```md +[Link A]({{%/* ref "/books/book-1" */%}}) + +[Link B]({{%/* ref path="/books/book-1" */%}}) + +[Link C]({{%/* ref path="/books/book-1" lang="de" */%}}) + +[Link D]({{%/* ref path="/books/book-1" lang="de" outputFormat="json" */%}}) ``` Rendered: ```html -Post 1 -Post 1 -Post 1 -Post 1 +Link A + +Link B + +Link C + +Link D ``` -{{% note %}} -Always use the `{{%/* */%}}` notation when calling this shortcode. -{{% /note %}} +## Error handling + +{{% include "_common/ref-and-relref-error-handling.md" %}} + +[content format]: /content-management/formats/ +[link render hooks]: /render-hooks/links/ +[Markdown notation]: /content-management/shortcodes/#notation +[source code]: {{% eturl relref %}} diff --git a/content/en/shortcodes/vimeo.md b/content/en/shortcodes/vimeo.md index 5ecdf5d02..c354eefe0 100755 --- a/content/en/shortcodes/vimeo.md +++ b/content/en/shortcodes/vimeo.md @@ -1,21 +1,13 @@ --- -title: Vimeo +title: Vimeo shortcode +linkTitle: Vimeo description: Embed a Vimeo video in your content using the vimeo shortcode. -categories: [shortcodes] +categories: [] keywords: [] -menu: - docs: - parent: shortcodes - weight: -weight: -toc: true --- -{{% note %}} -To override Hugo's embedded `vimeo` shortcode, copy the [source code] to a file with the same name in the `layouts/shortcodes` directory. - -[source code]: {{% eturl vimeo %}} -{{% /note %}} +> [!note] +> To override Hugo's embedded `vimeo` shortcode, copy the [source code] to a file with the same name in the `layouts/shortcodes` directory. ## Example @@ -35,7 +27,7 @@ Hugo renders this to: {{< vimeo 55073825 >}} -## Parameters +## Arguments class : (`string`) The `class` attribute of the wrapping `div` element. Adding one or more CSS classes disables inline styling. @@ -70,3 +62,4 @@ simple The source code for the simple version of the shortcode is available [here]. [here]: {{% eturl vimeo_simple %}} +[source code]: {{% eturl vimeo %}} diff --git a/content/en/shortcodes/x.md b/content/en/shortcodes/x.md index e27bc996a..f1eebdaf2 100755 --- a/content/en/shortcodes/x.md +++ b/content/en/shortcodes/x.md @@ -1,23 +1,15 @@ --- -title: X +title: X shortcode +linkTitle: X description: Embed an X post in your content using the x shortcode. -categories: [shortcodes] +categories: [] keywords: [] -menu: - docs: - parent: shortcodes - weight: -weight: -toc: true --- {{< new-in 0.141.0 />}} -{{% note %}} -To override Hugo's embedded `x` shortcode, copy the [source code] to a file with the same name in the `layouts/shortcodes` directory. - -[source code]: {{% eturl x %}} -{{% /note %}} +> [!note] +> To override Hugo's embedded `x` shortcode, copy the [source code] to a file with the same name in the `layouts/shortcodes` directory. ## Example @@ -54,8 +46,9 @@ simple The source code for the simple version of the shortcode is available [here]. -[here]: {{% eturl x_simple %}} - 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`. {{< code-toggle config=services.x />}} + +[here]: {{% eturl x_simple %}} +[source code]: {{% eturl x %}} diff --git a/content/en/shortcodes/youtube.md b/content/en/shortcodes/youtube.md index 546529500..18c5ae6c2 100755 --- a/content/en/shortcodes/youtube.md +++ b/content/en/shortcodes/youtube.md @@ -1,21 +1,13 @@ --- -title: YouTube +title: YouTube shortcode +linkTitle: YouTube description: Embed a YouTube video in your content using the youtube shortcode. -categories: [shortcodes] +categories: [] keywords: [] -menu: - docs: - parent: shortcodes - weight: -weight: -toc: true --- -{{% note %}} -To override Hugo's embedded `youtube` shortcode, copy the [source code] to a file with the same name in the `layouts/shortcodes` directory. - -[source code]: {{% eturl youtube %}} -{{% /note %}} +> [!note] +> To override Hugo's embedded `youtube` shortcode, copy the [source code] to a file with the same name in the `layouts/shortcodes` directory. ## Example @@ -27,7 +19,7 @@ https://www.youtube.com/watch?v=0RKpf3rK57I Include this in your Markdown: -```text +```texts {{}} ``` @@ -35,44 +27,44 @@ Hugo renders this to: {{< youtube 0RKpf3rK57I >}} -## Parameters +## Arguments id : (`string`) The video `id`. Optional if the `id` is provided as a positional argument as shown in the example above. allowFullScreen -{{< new-in 0.125.0 />}} +: {{< new-in 0.125.0 />}} : (`bool`) Whether the `iframe` element can activate full screen mode. Default is `true`. autoplay - {{< new-in 0.125.0 />}} +: {{< new-in 0.125.0 />}} : (`bool`) Whether to automatically play the video. Forces `mute` to `true`. Default is `false`. class : (`string`) The `class` attribute of the wrapping `div` element. When specified, removes the `style` attributes from the `iframe` element and its wrapping `div` element. controls -{{< new-in 0.125.0 />}} +: {{< new-in 0.125.0 />}} : (`bool`) Whether to display the video controls. Default is `true`. end -{{< new-in 0.125.0 />}} +: {{< new-in 0.125.0 />}} : (`int`) The time, measured in seconds from the start of the video, when the player should stop playing the video. loading -{{< new-in 0.125.0 />}} +: {{< new-in 0.125.0 />}} : (`string`) The loading attribute of the `iframe` element, either `eager` or `lazy`. Default is `eager`. loop -{{< new-in 0.125.0 />}} -: (`bool`) Whether to indefinitely repeat the video. Ignores the `start` and `end` arguments after the first play. Default is `false`. +: {{< new-in 0.125.0 />}} +: (`bool`) Whether to indefinitely repeat the video. Ignores the `start` and `end` arguments after the first play. Default is `false`. mute -{{< new-in 0.125.0 />}} +: {{< new-in 0.125.0 />}} : (`bool`) Whether to mute the video. Always `true` when `autoplay` is `true`. Default is `false`. start -{{< new-in 0.125.0 />}} +: {{< new-in 0.125.0 />}} : (`int`) The time, measured in seconds from the start of the video, when the player should start playing the video. title @@ -95,3 +87,5 @@ disable privacyEnhanced : (`bool`) Whether to block YouTube from storing information about visitors on your website unless the user plays the embedded video. Default is `false`. + +[source code]: {{% eturl youtube %}} diff --git a/content/en/showcase/1password-support/bio.md b/content/en/showcase/1password-support/bio.md index 3e15adc9f..32d299bd4 100644 --- a/content/en/showcase/1password-support/bio.md +++ b/content/en/showcase/1password-support/bio.md @@ -1,4 +1,3 @@ - **1Password** is a password manager that keeps you safe online. It protects your secure information behind the one password only you know. The [1Password Support](https://support.1password.com/) website was built from scratch with **Hugo** and enhanced with **React** and **Elasticsearch** to give us the best of both worlds: The simplicity and performance of a static site, with the richness of a hosted web app. diff --git a/content/en/showcase/1password-support/index.md b/content/en/showcase/1password-support/index.md index c0a66ce45..54a30f849 100644 --- a/content/en/showcase/1password-support/index.md +++ b/content/en/showcase/1password-support/index.md @@ -1,12 +1,10 @@ --- - title: 1Password Support date: 2018-02-22 -description: "Showcase: \"Compiles 400 pages in five languages in the blink of an eye.\"" +description: 'Showcase: "Compiles 400 pages in five languages in the blink of an eye."' siteURL: https://support.1password.com/ byline: "[Mitch Cohen](https://github.com/mitchchn), Documentation Team Lead" aliases: [/showcase/1password/] - --- At 1Password, we used to go through a different documentation platform every month: blog engines, ebooks, wikis, site generators written in Ruby and JavaScript. Each was inadequate in its own special way. Then we found **Hugo**. We made one last switch, and we're glad we did. @@ -31,9 +29,9 @@ Finding a tool that will make your customers, writers, designers, _and_ DevOps t ### Tech specs -* [1Password Support](https://support.1password.com) uses Hugo with a custom theme. It shares styles and some template code with [1Password.com](https://1password.com), which we also moved to Hugo in 2016. -* Code and articles live in a private GitHub repository, which is deployed to a static content server using Git hooks. -* Writers build and preview the site on their computers and contribute content using pull requests. -* We use Hugo's [multilingual support](/content-management/multilingual/) to build the site in English, Spanish, French, Italian, German, and Russian. With the help of Hugo, 1Password Support became our very first site in multiple languages. -* Our [contact form](https://support.1password.com/contact) is a single-page React app. We were able to integrate it with Hugo seamlessly thanks to its support for static files. -* The one part of the support site which is not static is our search engine, which we developed with Elasticsearch and host on AWS. +- [1Password Support](https://support.1password.com) uses Hugo with a custom theme. It shares styles and some template code with [1Password.com](https://1password.com), which we also moved to Hugo in 2016. +- Code and articles live in a private GitHub repository, which is deployed to a static content server using Git hooks. +- Writers build and preview the site on their computers and contribute content using pull requests. +- We use Hugo's [multilingual support](/content-management/multilingual/) to build the site in English, Spanish, French, Italian, German, and Russian. With the help of Hugo, 1Password Support became our very first site in multiple languages. +- Our [contact form](https://support.1password.com/contact) is a single-page React app. We were able to integrate it with Hugo seamlessly thanks to its support for static files. +- The one part of the support site which is not static is our search engine, which we developed with Elasticsearch and host on AWS. diff --git a/content/en/showcase/_index.md b/content/en/showcase/_index.md index cec1936ea..e618e8104 100644 --- a/content/en/showcase/_index.md +++ b/content/en/showcase/_index.md @@ -1,4 +1,7 @@ --- title: Showcases -draft: true +cascade: + build: + render: never + list: never --- diff --git a/content/en/myshowcase/bio.md b/content/en/showcase/_template/bio.md similarity index 51% rename from content/en/myshowcase/bio.md rename to content/en/showcase/_template/bio.md index 6b8f7e1a9..5ea389617 100644 --- a/content/en/myshowcase/bio.md +++ b/content/en/showcase/_template/bio.md @@ -1,7 +1,6 @@ - Add some **general info** about Myshowcase here. The site is built by: -* [Person 1](https://example.org) -* [Person 1](https://example.org) +- [Person 1](https://example.org) +- [Person 1](https://example.org) diff --git a/archetypes/showcase/featured.png b/content/en/showcase/_template/featured.png similarity index 100% rename from archetypes/showcase/featured.png rename to content/en/showcase/_template/featured.png diff --git a/content/en/myshowcase/index.md b/content/en/showcase/_template/index.md similarity index 90% rename from content/en/myshowcase/index.md rename to content/en/showcase/_template/index.md index abb4ad6b2..3103903e1 100644 --- a/content/en/myshowcase/index.md +++ b/content/en/showcase/_template/index.md @@ -1,21 +1,15 @@ --- - title: Myshowcase -date: 2021-01-14 +date: draft: true - -description: "A short description of this page." - +description: A short description of this page. # The URL to the site on the internet. siteURL: https://gohugo.io/ - # Link to the site's Hugo source code if public and you can/want to share. # Remove or leave blank if not needed/wanted. siteSource: https://github.com/gohugoio/hugoDocs - # Add credit to the article author. Leave blank or remove if not needed/wanted. -byline: "[bep](https://github.com/bep), Hugo Lead" - +byline: '[bep](https://github.com/bep), Hugo Lead' --- To complete this showcase: diff --git a/content/en/showcase/alora-labs/index.md b/content/en/showcase/alora-labs/index.md index 559169319..5e676bad3 100644 --- a/content/en/showcase/alora-labs/index.md +++ b/content/en/showcase/alora-labs/index.md @@ -1,7 +1,7 @@ --- title: Alora Labs date: 2021-05-27 -description: "Showcase: \"Making performant websites accessible for everyone.\"" +description: 'Showcase: "Making performant websites accessible for everyone."' siteURL: https://aloralabs.com/ siteSource: https://github.com/aloralabs/homepage aliases: [/showcase/aloralabs/] diff --git a/content/en/showcase/ampio-help/bio.md b/content/en/showcase/ampio-help/bio.md index c7dd9894a..a08b26be7 100644 --- a/content/en/showcase/ampio-help/bio.md +++ b/content/en/showcase/ampio-help/bio.md @@ -1,11 +1,10 @@ - __We are Ampio.__ We design and manufacture a building automation system that provides control, comfort, safety and reliability. Visit [our page](http://ampio.com/) to learn more about our solution! __Ampio Knowledge Base__ is a service built and maintained with Hugo. It is a self-service support platform for our customers and certified installers. It also contains a complete portfolio of our modules---building blocks of the Ampio building automation system. The site is built by: -* [@mgetka](https://github.com/mgetka), developer -* [@SteynAnna](https://github.com/SteynAnna), maintainer +- [@mgetka](https://github.com/mgetka), developer +- [@SteynAnna](https://github.com/SteynAnna), maintainer and other members of the Ampio team responsible for content creation. diff --git a/content/en/showcase/ampio-help/index.md b/content/en/showcase/ampio-help/index.md index 2daafbbe1..462452cb1 100644 --- a/content/en/showcase/ampio-help/index.md +++ b/content/en/showcase/ampio-help/index.md @@ -1,7 +1,6 @@ --- title: Ampio Knowledge Base date: 2022-10-30 - description: "Knowledge base for the Ampio building automation system." siteURL: https://help.ampio.com/ --- @@ -39,7 +38,7 @@ Hugo was our first choice of SSG. The multilingualism support was the primary fe The rich functionalities of WordPress WYSIWYG editors soon turned out to be a curse. It became burdensome to maintain formatting consistency across documents prepared by multiple contributors. When we considered Markdown, we knew that it would give us a lot less flexibility. In our case, it proved to be a blessing in disguise---the constraints imposed by the notation ensured that each document was prepared in the same way. And in the cases where Markdown was not enough, Hugo shortcodes gave us all that we needed to get the results we anticipated. -In terms of PDF generation, we utilized [custom output formats](/templates/output-formats/) to produce intermediary document representations, which are consumed by our custom tool transforming them to TeX documents, which are finally used to produce PDF files. +In terms of PDF generation, we utilized [custom output formats](/configuration/output-formats/) to produce intermediary document representations, which are consumed by our custom tool transforming them to TeX documents, which are finally used to produce PDF files. Custom output formats were also used to create search indexes. The search functionality is built on the brilliant [TNTSearch](https://github.com/teamtnt/tntsearch) library. The search queries and results are handled by PHP snippets embedded into static documents handled by Hugo. @@ -66,9 +65,9 @@ Total in 1096 ms Very quickly it became apparent that our initial concerns about the adaptation of the workflow among contributors were grossly exaggerated. Markdown is fairly straightforward and did not cause any trouble for the contributors. -We recommended that our colleagues use Visual Studio Code as a tool for content creation. The project’s repository tracks project-scoped configuration of the editor, which includes a set of _tasks_ allowing to run a live server from the GUI level. This is very useful for those who are easily frightened when faced with the mighty terminal. +We recommended that our colleagues use Visual Studio Code as a tool for content creation. The project's repository tracks project-scoped configuration of the editor, which includes a set of _tasks_ allowing to run a live server from the GUI level. This is very useful for those who are easily frightened when faced with the mighty terminal. -The basic skills of the Git workflow were also easily acquired. At the end of the day, builds and deployments are fully managed by CI/CD processes, so the administration of the service drills down to reviewing and accepting merge requests in the Git frontend. As a side effect, we receive a full and clear history of contributions, which is well appreciated by our quality assurance auditors. +The basic skills of the Git workflow were also easily acquired. At the end of the day, builds and deployments are fully managed by [CI/CD](g) processes, so the administration of the service drills down to reviewing and accepting merge requests in the Git frontend. As a side effect, we receive a full and clear history of contributions, which is well appreciated by our quality assurance auditors. We could even say that our experiment spread the love for Git among non-programmers in our organization! diff --git a/content/en/showcase/bypasscensorship/bio.md b/content/en/showcase/bypasscensorship/bio.md index 0a847df1e..a6c98f9ba 100644 --- a/content/en/showcase/bypasscensorship/bio.md +++ b/content/en/showcase/bypasscensorship/bio.md @@ -2,5 +2,5 @@ Bypass Censorship find and promote tools that provide Internet access to everyon The site is built by: -* [Leyla Avsar](https://www.leylaavsar.com/) (designer) -* [Fredrik Jonsson](https://xdeb.net/) (dev) +- [Leyla Avsar](https://www.leylaavsar.com/) (designer) +- [Fredrik Jonsson](https://xdeb.net/) (dev) diff --git a/content/en/showcase/bypasscensorship/index.md b/content/en/showcase/bypasscensorship/index.md index 8cbda9aa6..bd1a072c0 100644 --- a/content/en/showcase/bypasscensorship/index.md +++ b/content/en/showcase/bypasscensorship/index.md @@ -1,10 +1,9 @@ --- title: Bypass Censorship date: 2019-06-16 -description: "Showcase: Bypass Censorship find and promote tools that provide Internet access to everyone." +description: 'Showcase: "Bypass Censorship find and promote tools that provide Internet access to everyone."' siteURL: https://www.bypasscensorship.org/ byline: "[Fredrik Jonsson](https://xdeb.net/), Web developer & Linux sysadmin" - --- The British Broadcasting Corporation (BBC) (UK), Deutsche Welle (DW) (Germany), France Médias Monde (FMM) (France), the U.S. Agency for Global Media (USAGM) (US) and the Open Technology Fund (OTF) (US) co-sponsor the Bypass Censorship website. diff --git a/content/en/showcase/digitalgov/bio.md b/content/en/showcase/digitalgov/bio.md index db3ffafaf..70bb990b9 100644 --- a/content/en/showcase/digitalgov/bio.md +++ b/content/en/showcase/digitalgov/bio.md @@ -1,2 +1 @@ - **Digital.gov** helps people in the U.S. government deliver better, more accessible digital services through publishing essential guidance, resources, tools, and online events that make it easier for people to design, build, and deliver essential services for the public. diff --git a/content/en/showcase/digitalgov/index.md b/content/en/showcase/digitalgov/index.md index 3db2c608f..7f0584712 100644 --- a/content/en/showcase/digitalgov/index.md +++ b/content/en/showcase/digitalgov/index.md @@ -1,7 +1,7 @@ --- title: Digital.gov date: 2020-05-01 -description: "Showcase: \"Guidance on building better digital services in government.\"" +description: 'Showcase: "Guidance on building better digital services in government."' siteURL: https://digital.gov/ siteSource: https://github.com/gsa/digitalgov.gov --- @@ -14,15 +14,15 @@ Digital.gov is built using the [U.S. Web Design System](https://designsystem.dig - **Start with real user needs** — We used human-centered design methods to inform our product decisions (like qualitative user research), and gathered feedback from real users. We also continually test our assumptions with small experiments. - **Earn trust** —We recognize that trust has to be earned every time. We are including all [required links and content](https://digital.gov/resources/required-web-content-and-links/) on our site, clearly identifying as a government site, building with modern best practices, and using HTTPS. -- **Embrace accessibility** — [Accessibility](https://digital.gov/resources/intro-accessibility/) affects everybody, and we built it into every decision. We’re continually working to conform to Section 508 requirements, use user experience best practices, and support a wide range of devices. -- **Promote continuity** — We started from shared solutions like USWDS and [Federalist](https://federalist.18f.gov/). We designed our site to clearly identify as a government site by including USWDS’s .gov banner, common colors and patterns, and built with modern best practices. +- **Embrace accessibility** — [Accessibility](https://digital.gov/resources/intro-accessibility/) affects everybody, and we built it into every decision. We're continually working to conform to Section 508 requirements, use user experience best practices, and support a wide range of devices. +- **Promote continuity** — We started from shared solutions like USWDS and [Federalist](https://federalist.18f.gov/). We designed our site to clearly identify as a government site by including USWDS's .gov banner, common colors and patterns, and built with modern best practices. - **Listen** — We actively collect user feedback and web metrics. We use the [Digital Analytics Program](https://digital.gov/services/dap/) (DAP) and analyze the data to discover actionable insights. We make small, incremental changes to continuously improve our website by listening to readers and learning from what we hear. _More on the [USWDS maturity model »](https://designsystem.digital.gov/maturity-model/)_ ## Open tools -We didn’t start from scratch. We built and designed the Digital.gov using many of the open-source tools and services that we develop for government here in the [Technology Transformation Services](https://www.gsa.gov/tts/) (TTS). +We didn't start from scratch. We built and designed the Digital.gov using many of the open-source tools and services that we develop for government here in the [Technology Transformation Services](https://www.gsa.gov/tts/) (TTS). Using services that make it possible to design, build, and iterate quickly are essential to modern web design and development, which is why [Federalist](https://federalist.18f.gov/) and the [U.S. Web Design System](https://designsystem.digital.gov/) are such a great combination. diff --git a/content/en/showcase/fireship/bio.md b/content/en/showcase/fireship/bio.md index faf739bfa..2a5639aa7 100644 --- a/content/en/showcase/fireship/bio.md +++ b/content/en/showcase/fireship/bio.md @@ -1,6 +1,5 @@ - **Fireship.io** is an ecosystem of detailed and practical resources for developers who want to build and ship high-quality apps. The site is built by: -* [Jeff Delaney](https://fireship.io/contributors/jeff-delaney/) +- [Jeff Delaney](https://fireship.io/contributors/jeff-delaney/) diff --git a/content/en/showcase/fireship/index.md b/content/en/showcase/fireship/index.md index a229e4f6a..454ee87d7 100644 --- a/content/en/showcase/fireship/index.md +++ b/content/en/showcase/fireship/index.md @@ -1,7 +1,7 @@ --- title: fireship.io date: 2019-02-02 -description: "Showcase: \"Hugo helps us create complex technical content that integrates engaging web components\"" +description: 'Showcase: "Hugo helps us create complex technical content that integrates engaging web components."' siteURL: https://fireship.io siteSource: https://github.com/fireship-io/fireship.io byline: "[Jeff Delaney](https://github.com/codediodeio), Fireship.io Creator" diff --git a/content/en/showcase/forestry/bio.md b/content/en/showcase/forestry/bio.md index 0b8f28743..23951a1c6 100644 --- a/content/en/showcase/forestry/bio.md +++ b/content/en/showcase/forestry/bio.md @@ -1,4 +1,3 @@ - Forestry.io is a Git-backed CMS (content management system) for websites and web products built using static site generators such as Hugo. Forestry bridges the gap between developers and their teams, by making development fun and easy, while providing powerful content management for their teams. diff --git a/content/en/showcase/forestry/index.md b/content/en/showcase/forestry/index.md index fabcb7cd3..5b8872316 100644 --- a/content/en/showcase/forestry/index.md +++ b/content/en/showcase/forestry/index.md @@ -1,7 +1,7 @@ --- title: Forestry.io date: 2018-03-16 -description: "Showcase: \"Seeing Hugo in action is a whole different world of awesome.\"" +description: 'Showcase: "Seeing Hugo in action is a whole different world of awesome."' siteURL: https://forestry.io/ siteSource: https://github.com/forestryio/forestry.io --- @@ -10,7 +10,7 @@ It was clear from the get-go that we had to go with a static site generator. Sta ### Why Hugo? -In our early research we looked at Ionic’s [site](https://github.com/ionic-team/ionic) to get some inspiration. They used Jekyll to build their website. While Jekyll is a great generator, the build times for larger sites can be painfully slow. With more than 150 pages plus many custom configurations and add-ons, our website doesn’t fall into the low-volume category anymore. Our developers want a smooth experience when working on the website and our content editors need the ability to preview content quickly. In short, we need our builds to be lightning fast. +In our early research we looked at Ionic's [site](https://github.com/ionic-team/ionic) to get some inspiration. They used Jekyll to build their website. While Jekyll is a great generator, the build times for larger sites can be painfully slow. With more than 150 pages plus many custom configurations and add-ons, our website doesn't fall into the low-volume category anymore. Our developers want a smooth experience when working on the website and our content editors need the ability to preview content quickly. In short, we need our builds to be lightning fast. We knew Hugo was fast but we did [some additional benchmarking](https://forestry.io/blog/hugo-vs-jekyll-benchmark/) before making our decision. Seeing Hugo in action is a whole different world of awesome. Hugo takes less than one second to build our 150-page site! Take a look: @@ -35,14 +35,14 @@ Lastly, we want to take the opportunity to give some love to other amazing tools ### What tools did we use? -* Our Norwegian designer Nichlas is in love with [**Sketch**](https://www.sketchapp.com/). From what we hear it’s a designer’s dream come true. -* Some say our main graphic is [mesmerizing](https://x.com/hmncllctv/status/968907474664284160). Nichlas created it using [**3DS Max**](https://www.autodesk.com/products/3ds-max/overview). -* [**Hugo**](https://gohugo.io/) -- of course. -* Chris can’t think of modern web development without [**Gulp**](https://gulpjs.com/) & [**Webpack**](https://webpack.js.org/). We used them to add additional build steps such as Browsersync, CSS, JS and SVG optimization. -* Speaking about adding steps to our build, our lives would be much harder without [**CircleCI**](https://circleci.com/) for continuous deployment and automated testing purposes. -* We can’t stop raving about [**Algolia**](https://www.algolia.com/). Chris loves it and even wrote a tutorial on [how to implement Algolia](https://forestry.io/blog/search-with-algolia-in-hugo/) into static sites using Hugo’s [Custom Outputs](/templates/output-formats/). -* [**Cloudinary**](https://cloudinary.com/) is probably one of the easiest ways to get responsive images into your website. -* We might be a little biased on this one - We think [**Forestry.io**](https://forestry.io/) is a great way to add a content management system with a clean UI on top of your site without interrupting your experience as a developer. -* For hosting purposes we use the almighty [**AWS**](https://aws.amazon.com/). -* [**Formspree.io**](https://formspree.io/) is managing our support and enterprise requests. -* We also use browser cookies and JS to customize our user’s experience and give it a more dynamic feel. +- Our Norwegian designer Nichlas is in love with [**Sketch**](https://www.sketchapp.com/). From what we hear it's a designer's dream come true. +- Some say our main graphic is [mesmerizing](https://x.com/hmncllctv/status/968907474664284160). Nichlas created it using [**3DS Max**](https://www.autodesk.com/products/3ds-max/overview). +- [**Hugo**](https://gohugo.io/) -- of course. +- Chris can't think of modern web development without [**Gulp**](https://gulpjs.com/) & [**Webpack**](https://webpack.js.org/). We used them to add additional build steps such as Browsersync, CSS, JS and SVG optimization. +- Speaking about adding steps to our build, our lives would be much harder without [**CircleCI**](https://circleci.com/) for continuous deployment and automated testing purposes. +- We can't stop raving about [**Algolia**](https://www.algolia.com/). Chris loves it and even wrote a tutorial on [how to implement Algolia](https://forestry.io/blog/search-with-algolia-in-hugo/) into static sites using Hugo's [custom output formats](/configuration/output-formats/). +- [**Cloudinary**](https://cloudinary.com/) is probably one of the easiest ways to get responsive images into your website. +- We might be a little biased on this one - We think [**Forestry.io**](https://forestry.io/) is a great way to add a content management system with a clean UI on top of your site without interrupting your experience as a developer. +- For hosting purposes we use the almighty [**AWS**](https://aws.amazon.com/). +- [**Formspree.io**](https://formspree.io/) is managing our support and enterprise requests. +- We also use browser cookies and JS to customize our user's experience and give it a more dynamic feel. diff --git a/content/en/showcase/godot-tutorials/index.md b/content/en/showcase/godot-tutorials/index.md index 3b71fd8bc..fe4f9337e 100644 --- a/content/en/showcase/godot-tutorials/index.md +++ b/content/en/showcase/godot-tutorials/index.md @@ -1,16 +1,9 @@ --- - title: Godot Tutorials date: 2021-01-07 - description: "Teaching game development skills with love." - -# The URL to the site on the internet. siteURL: https://godottutorials.com - -# Add credit to the article author. Leave blank or remove if not needed/wanted. byline: "[Godot Tutorials](https://godottutorials.com), Web Developer & Game Programmer" - --- [Godot Tutorials](https://godottutorials.com) started as a way to teach beginners game programming and game development. diff --git a/content/en/showcase/hapticmedia/index.md b/content/en/showcase/hapticmedia/index.md index 7ca2b6cef..52c3337bf 100644 --- a/content/en/showcase/hapticmedia/index.md +++ b/content/en/showcase/hapticmedia/index.md @@ -1,7 +1,7 @@ --- title: Hapticmedia Blog date: 2019-10-01 -description: "Showcase: \"A simple, but powerful, multilingual blog.\"" +description: 'Showcase: "A simple, but powerful, multilingual blog."' siteURL: https://hapticmedia.fr/blog/en/ byline: "[Cyril Bonnet](https://github.com/monsieurnebo), Web Developer" --- diff --git a/content/en/showcase/hartwell-insurance/bio.md b/content/en/showcase/hartwell-insurance/bio.md index 7fab74292..4cded7beb 100644 --- a/content/en/showcase/hartwell-insurance/bio.md +++ b/content/en/showcase/hartwell-insurance/bio.md @@ -1,4 +1,3 @@ - Hartwell Insurance is an insurance company set up solely to service the Broker community. By combining **Hugo**, **Service Worker** and **Netlify**, we were able to achieve incredible global site performance. diff --git a/content/en/showcase/hartwell-insurance/index.md b/content/en/showcase/hartwell-insurance/index.md index 24b4e3a9f..07ee6182c 100644 --- a/content/en/showcase/hartwell-insurance/index.md +++ b/content/en/showcase/hartwell-insurance/index.md @@ -1,26 +1,20 @@ --- - title: Hartwell Insurance - date: 2018-02-09 - -description: "Showcase: \"Hugo + Netlify + PWA makes for a rapid website.\"" - +description: 'Showcase: "Hugo + Netlify + PWA makes for a rapid website."' siteURL: https://www.hartwell-insurance.com/ - byline: "[Trys Mudford](http://www.trysmudford.com), Lead Developer, Tomango" - --- -We’ve just launched a shiny new website for [Hartwell Insurance](https://www.hartwell-insurance.com/) – I’m really proud of it. It was tackled in a different way to most previous Tomango site builds, using some fancy new tools and some vintage web standards. +We've just launched a shiny new website for [Hartwell Insurance](https://www.hartwell-insurance.com/). I'm really proud of it. It was tackled in a different way to most previous Tomango site builds, using some fancy new tools and some vintage web standards. -It’s a multi-page, single-page (!) website written in Hugo, a static site generator built with performance as a first-class feature. _I’ve outlined a load of benefits to Hugo & static sites [here](https://why-static.netlify.com/), in case you’re interested._ +It's a multi-page, single-page (!) website written in Hugo, a static site generator built with performance as a first-class feature. _I've outlined a load of benefits to Hugo & static sites [here](https://why-static.netlify.com/), in case you're interested._ -> **In essence, a static site generator pre-renders the whole site into HTML files and serves them like it’s 1995.** +> **In essence, a static site generator pre-renders the whole site into HTML files and serves them like it's 1995.** -There’s no Apache or Node backend that does compilation at runtime, it’s all done at the build step. This means the server; Netlify in this case, only has to do one thing – serve files. Unsurprisingly, serving simple files is VERY quick. +There's no Apache or Node backend that does compilation at runtime, it's all done at the build step. This means the server; Netlify in this case, only has to do one thing: serve files. Unsurprisingly, serving simple files is VERY quick. -The starter point was the [Victor Hugo](https://github.com/netlify/victor-hugo) repository that Netlify have created. It let me dive in with Hugo, PostCSS, Browsersync and ES6 without setting up any tooling myself – always a win! +The starter point was the [Victor Hugo](https://github.com/netlify/victor-hugo) repository that Netlify have created. It let me dive in with Hugo, PostCSS, Browsersync and ES6 without setting up any tooling myself---always a win! I then took all the content from the design file and moved it into Markdown, putting shortcodes in where necessary. This site did need a number of custom shortcodes for the presentational elements like the expanding circles and full width backgrounds. But mostly it was just clean, semantic HTML with some CSS and JS enhancement thrown in. @@ -32,17 +26,17 @@ For the ripple effects on the section headings, I used JS to prepend a ` On the Hartwell Profitmaker section, I toyed with the idea of using Vue.js for the calculator, but after giving it some thought, I decided to code in Vanilla. The result, all of the site JS comes in at 3.2KB! -The plan was to host with Netlify and therefore get access to Netlify Forms. It meant spending 0 minutes on getting a backend set up – I could focus fully on the frontend. +The plan was to host with Netlify and therefore get access to Netlify Forms. It meant spending 0 minutes on getting a backend set up so I could focus fully on the frontend. -Cache invalidation isn’t normally something I spend all that much time thinking about when building a site. But as this site was going to be a Progressive Web App, invalidating files would be important to ensure the site didn’t appear broken when we made changes. As I was using Victor-Hugo, I wasn’t really sure how to best tackle this and sadly spent far too many hours wrangling with Webpack and Gulp files to try and get hashed file names working nicely. +Cache invalidation isn't normally something I spend all that much time thinking about when building a site. But as this site was going to be a Progressive Web App, invalidating files would be important to ensure the site didn't appear broken when we made changes. As I was using Victor-Hugo, I wasn't really sure how to best tackle this and sadly spent far too many hours wrangling with Webpack and Gulp files to try and get hashed file names working nicely. Then; while I was waiting for a haircut, I read a [Netlify blog post](https://www.netlify.com/blog/2017/02/23/better-living-through-caching/) on how they do cache invalidation with HTTP2 and it promptly blew my mind. -When you request an asset, they send an ETag in the headers which is a hash of the file. There’s also a header to tell the browser not to trust it’s own cache (which sounds a little bit bonkers). +When you request an asset, they send an ETag in the headers which is a hash of the file. There's also a header to tell the browser not to trust it's own cache (which sounds a little bit bonkers). So when you request the page, it opens a persistent HTTP2 connection up (so no new connections for file requests). When it gets to requesting that asset, the browser sends the ETag back to Netlify and they either return nothing if the ETag matches, or the new file with the new ETag. No `app.klfjlkdsfjdslkfjdslkfdsj.js` or `app.js?v=20180112`. Just a clean `app.js` with instant cache invalidation. Amazing. -Finally, the [Service Worker](https://www.hartwell-insurance.com/sw.js) could be added. This turned out to be straightforward as the Netlify cache invalidation system solved most of the pain points. I went for a network-first, cache-fallback setup for both assets and HTML. This does mean flaky speeds are reliant on the page connection time, but given we’re on HTTP2, I’m hoping the persistent connection and tiny ETag size will keep it quick. For online connections, every request is up to date and instantly live after any update. Offline connections fall back to every assets’ last cached state. It seems to work really nicely, and there’s no need for an update prompt if assets have changed. +Finally, the [Service Worker](https://www.hartwell-insurance.com/sw.js) could be added. This turned out to be straightforward as the Netlify cache invalidation system solved most of the pain points. I went for a network-first, cache-fallback setup for both assets and HTML. This does mean flaky speeds are reliant on the page connection time, but given we're on HTTP2, I'm hoping the persistent connection and tiny ETag size will keep it quick. For online connections, every request is up to date and instantly live after any update. Offline connections fall back to every assets' last cached state. It seems to work really nicely, and there's no need for an update prompt if assets have changed. --- @@ -52,17 +46,17 @@ The WebPageTest results are looking good. The speed index is 456, 10x smaller th ![WebPageTest results](hartwell-webpagetest.png) -[TestMySite.io](https://testmysite.io/5a7e1bb2df99531a23c9ad2f/hartwell-insurance.com) is return ~2ms time to first byte from the CDN edge nodes. Lighthouse audits are also very promising. There’s still some improvement to be gained lazy-loading the images and inlining the CSS. I’m less excited about the [second suggestion](http://www.trysmudford.com/css-in-2017/), but I’ll certainly look at some lazy-loading, especially as I’m already using `IntersectionObserver` for some animations. +[TestMySite.io](https://testmysite.io/5a7e1bb2df99531a23c9ad2f/hartwell-insurance.com) is return ~2ms time to first byte from the CDN edge nodes. Lighthouse audits are also very promising. There's still some improvement to be gained lazy-loading the images and inlining the CSS. I'm less excited about the [second suggestion](http://www.trysmudford.com/css-in-2017/), but I'll certainly look at some lazy-loading, especially as I'm already using `IntersectionObserver` for some animations. ![Lighthouse results](hartwell-lighthouse.png) -The most encouraging result is how quick the site is around the world. Most Tomango clients (and their customers) are pretty local and almost exclusively UK-based. We have a dedicated server in Surrey that serves our market pretty well. It did take me by surprise just how much slower a connection from the USA, Australia and Japan to our server was. They’re waiting ~500ms just for the first byte, let alone downloading each asset. +The most encouraging result is how quick the site is around the world. Most Tomango clients (and their customers) are pretty local and almost exclusively UK-based. We have a dedicated server in Surrey that serves our market pretty well. It did take me by surprise just how much slower a connection from the USA, Australia and Japan to our server was. They're waiting ~500ms just for the first byte, let alone downloading each asset. -[Hartwell Insurance](https://www.hartwell-insurance.com/) are a US company so by putting them on our server, we’d be instantly hampering their local response times by literally seconds. This was one of the main reasons for going with Netlify. They provide global CDN hosting that’s quick from anywhere in the world. +[Hartwell Insurance](https://www.hartwell-insurance.com/) are a US company so by putting them on our server, we'd be instantly hampering their local response times by literally seconds. This was one of the main reasons for going with Netlify. They provide global CDN hosting that's quick from anywhere in the world. --- -This project was such a blast to develop, it’s a real pleasure to put new technologies to good use in production, and to see real performance and usability benefits from them. Even using classic web methods of serving directories with files is fun when you’ve been using dynamic systems for a while – there’s something really pure about it. +This project was such a blast to develop, it's a real pleasure to put new technologies to good use in production, and to see real performance and usability benefits from them. Even using classic web methods of serving directories with files is fun when you've been using dynamic systems for a while---there's something really pure about it. --- diff --git a/content/en/showcase/keycdn/index.md b/content/en/showcase/keycdn/index.md index 6308b34c4..c6972325f 100644 --- a/content/en/showcase/keycdn/index.md +++ b/content/en/showcase/keycdn/index.md @@ -1,10 +1,8 @@ --- - title: KeyCDN date: 2020-04-10 -description: "Showcase: \"Hugo has become an integral part of our stack.\"" +description: 'Showcase: "Hugo has become an integral part of our stack."' siteURL: https://www.keycdn.com - --- At KeyCDN one of our primary focuses is on performance. With speed being ingrained in our DNA we knew from the start that we must use a fast static website generator that could meet our requirements. When evaluating the right solution, Hugo met our requirements and we looked no further as it was the fastest and most flexible. @@ -13,18 +11,18 @@ At KeyCDN one of our primary focuses is on performance. With speed being ingrain Before our migration to Hugo our website was powered by a PHP-based website that had about 50 pages and a WordPress website that had over 500 posts between our blog and knowledge base. This became harder to maintain as time continued. We felt like we were losing the speed and flexibility that we require. To overcome this we knew we needed to convert our website to be static. This would allow our website to be faster and more secure as it could be delivered by all of our edge locations. -It wasn’t an easy task at the beginning, however, after evaluating Hugo and benchmarking it we knew we had found the ideal solution. Hugo was by far the fastest setup and offered an intuitive way to build our entire website exactly as needed. The Go-based templates, shortcodes, and configuration options made it easy to build a complex website. +It wasn't an easy task at the beginning, however, after evaluating Hugo and benchmarking it we knew we had found the ideal solution. Hugo was by far the fastest setup and offered an intuitive way to build our entire website exactly as needed. The Go-based templates, shortcodes, and configuration options made it easy to build a complex website. -In the fall of 2018 we started the migration and within a couple short months we had built a custom static website with Hugo and migrated all content from our old systems. The simplicity and vast amount of functionality that Hugo offers made this process fast and left our entire team, including all of our writers and developers, happy with the migration. Since migrating to Hugo we haven’t looked back. Hugo has become an integral part of our stack. We’re grateful to all those who have contributed to make Hugo what it is today. +In the fall of 2018 we started the migration and within a couple short months we had built a custom static website with Hugo and migrated all content from our old systems. The simplicity and vast amount of functionality that Hugo offers made this process fast and left our entire team, including all of our writers and developers, happy with the migration. Since migrating to Hugo we haven't looked back. Hugo has become an integral part of our stack. We're grateful to all those who have contributed to make Hugo what it is today. ## Technical overview Below is an overview of what we used with Hugo to build our website: -* [KeyCDN](https://www.keycdn.com) uses a custom theme and is our primary hub for all style sheets and JavaScript. Our other websites, like [KeyCDN Tools](https://tools.keycdn.com), only import the required style sheets and JavaScript. -* We use [Gulp](https://gulpjs.com) in our build process for many tasks, such as combining, versioning, and compressing our style sheets as well as our JavaScript. -* Our search is powered by a custom solution that we’ve built. It allows our pages, blog, and knowledge base to be searched. It uses [Axios](https://github.com/axios/axios) to send a `POST` request containing the search query. An index file in JSON generated by Hugo is searched and the results are then returned. -* Our commenting system is also powered by a custom solution that we’ve built. It uses Axios to send a `GET` request containing the slug to pull the comment thread and a `POST` request containing the name, email address, and comment when submitting a comment. -* Our contact form is a simple HTML form, which uses Axios as well. -* Our writers use shortcodes to enhance the capability of Markdown. -* Our entire website is delivered through KeyCDN using a Pull Zone, which means all of our edge locations are delivering our website. +- [KeyCDN](https://www.keycdn.com) uses a custom theme and is our primary hub for all style sheets and JavaScript. Our other websites, like [KeyCDN Tools](https://tools.keycdn.com), only import the required style sheets and JavaScript. +- We use [Gulp](https://gulpjs.com) in our build process for many tasks, such as combining, versioning, and compressing our style sheets as well as our JavaScript. +- Our search is powered by a custom solution that we've built. It allows our pages, blog, and knowledge base to be searched. It uses [Axios](https://github.com/axios/axios) to send a `POST` request containing the search query. An index file in JSON generated by Hugo is searched and the results are then returned. +- Our commenting system is also powered by a custom solution that we've built. It uses Axios to send a `GET` request containing the slug to pull the comment thread and a `POST` request containing the name, email address, and comment when submitting a comment. +- Our contact form is a simple HTML form, which uses Axios as well. +- Our writers use shortcodes to enhance the capability of Markdown. +- Our entire website is delivered through KeyCDN using a Pull Zone, which means all of our edge locations are delivering our website. diff --git a/content/en/showcase/letsencrypt/bio.md b/content/en/showcase/letsencrypt/bio.md index 92551dc47..62c547980 100644 --- a/content/en/showcase/letsencrypt/bio.md +++ b/content/en/showcase/letsencrypt/bio.md @@ -1,3 +1 @@ - - Let's Encrypt is a free, automated, and open certificate authority (CA), run for the public's benefit. It is a service provided by the [Internet Security Research Group (ISRG)](https://www.abetterinternet.org/). diff --git a/content/en/showcase/letsencrypt/index.md b/content/en/showcase/letsencrypt/index.md index e2f8e168f..8696cb7ad 100644 --- a/content/en/showcase/letsencrypt/index.md +++ b/content/en/showcase/letsencrypt/index.md @@ -1,13 +1,13 @@ --- -title: Let’s Encrypt +title: Let's Encrypt date: 2018-03-13 -description: "Showcase: Lessons learned from taking letsencrypt.org to Hugo." +description: 'Showcase: "Lessons learned from taking letsencrypt.org to Hugo."' siteURL: https://letsencrypt.org/ siteSource: https://github.com/letsencrypt/website byline: "[bep](https://github.com/bep), Hugo Lead" --- -The **Let’s Encrypt website** has a common set of elements: A landing page and some other static info-pages, a document section, a blog, and a documentation section. Having it moved to Hugo was mostly motivated by a _simpler administration and Hugo's [multilingual support](/content-management/multilingual/)_. They already serve HTTPS to more than 60 million domains, and having the documentation available in more languages will increase that reach.[^1] +The **Let's Encrypt website** has a common set of elements: A landing page and some other static info-pages, a document section, a blog, and a documentation section. Having it moved to Hugo was mostly motivated by a _simpler administration and Hugo's [multilingual support](/content-management/multilingual/)_. They already serve HTTPS to more than 60 million domains, and having the documentation available in more languages will increase that reach.[^1] {{< x user="letsencrypt" id="971755920639307777" >}} @@ -15,6 +15,4 @@ I helped them port the site from Jekyll to Hugo. There are usually very few surp That site is bookmarked in many browsers, so preserving the URLs was a must. Hugo's URL handling is very flexible, but there was one challenge. The website has a mix of standard and what we in Hugo call _ugly URLs_ (`https://letsencrypt.org/2017/12/07/looking-forward-to-2018.html`). In Hugo this is handled automatically, and you can turn it on globally or per language. But before Hugo `0.33` you could not configure it for parts of your site. You could set it manually for the relevant pages in front matter -- which is how it was done in Jekyll -- but that would be hard to manage, especially when you start to introduce translations. So, in Hugo 0.33 I added support for _ugly URLs_ per section and also `url` set in front matter for list pages (`https://letsencrypt.org/blog/`). -The lessons learned from this also lead to [disableLanguages](/content-management/multilingual/#disable-a-language) in Hugo `0.34` (a way to turn off languages during translation). And I also registered [this issue](https://github.com/gohugoio/hugo/issues/4463). Once fixed it will make it easier to handle partially translated sites. - [^1]: The work on getting the content translated is in progress. diff --git a/content/en/showcase/linode/bio.md b/content/en/showcase/linode/bio.md index 42fa92229..52c7204c1 100644 --- a/content/en/showcase/linode/bio.md +++ b/content/en/showcase/linode/bio.md @@ -1,4 +1,3 @@ - **Linode** is a cloud hosting provider that offers high performance SSD Linux servers for your infrastructure needs. **Hugo** offers the documentation team incredible performance as we scale and continue providing quality Linux tutorials. diff --git a/content/en/showcase/linode/index.md b/content/en/showcase/linode/index.md index 5a341be8a..f91c99d50 100644 --- a/content/en/showcase/linode/index.md +++ b/content/en/showcase/linode/index.md @@ -1,7 +1,7 @@ --- title: Linode Docs date: 2018-02-12 -description: "Showcase: \"Hugo allows us to build thousands of pages in seconds.\"" +description: 'Showcase: "Hugo allows us to build thousands of pages in seconds."' siteURL: https://linode.com/docs/ siteSource: https://github.com/linode/docs --- @@ -12,4 +12,4 @@ As our library grew into thousands of guides, we needed a fast static site gener Hugo solved a lot of our growing pains with features like shortcodes, customizable URLs, LiveReload, and more. We have already brought our site build time down from minutes to just a few seconds, and we are excited to see what future developments in Hugo will bring. -Thank you to all the [Hugo contributors](https://github.com/gohugoio/hugo/graphs/contributors) and especially [@bep](https://github.com/bep) for helping us with the adoption of Hugo. +Thank you to all the [Hugo contributors](https://github.com/gohugoio/hugo/graphs/contributors) and especially [@bep](https://github.com/bep) for helping us with the adoption of Hugo. diff --git a/content/en/showcase/overmindstudios/bio.md b/content/en/showcase/overmindstudios/bio.md index b2f92f08c..080de69a0 100644 --- a/content/en/showcase/overmindstudios/bio.md +++ b/content/en/showcase/overmindstudios/bio.md @@ -1,6 +1,5 @@ - **Overmind Studios** is a visual effects studio headquartered in Southern Germany. The site is built by: -* [Tobias Kummer](https://www.overmind-studios.de/about/) +- [Tobias Kummer](https://www.overmind-studios.de/about/) diff --git a/content/en/showcase/overmindstudios/index.md b/content/en/showcase/overmindstudios/index.md index 3208b2b72..00b09c5be 100644 --- a/content/en/showcase/overmindstudios/index.md +++ b/content/en/showcase/overmindstudios/index.md @@ -4,6 +4,7 @@ description: "A fresh start to make things easier in the future." siteURL: https://www.overmind-studios.de/ byline: "[tobkum](https://github.com/tobkum), Co-Founder Overmind Studios" --- + After many years of running our site on WordPress, we decided to switch to Hugo. WordPress is a great CMS for many people, but it has some downsides, especially for those who need a fast, secure, and customizable site. Plugins can become outdated, customization can be difficult, and bloat can slow down page loading times. diff --git a/content/en/showcase/pharmaseal/index.md b/content/en/showcase/pharmaseal/index.md index d324833c9..3a8da2377 100644 --- a/content/en/showcase/pharmaseal/index.md +++ b/content/en/showcase/pharmaseal/index.md @@ -1,19 +1,9 @@ --- - title: PHARMASEAL date: 2019-04-29 - description: "Pharmaseal website developed using Hugo, Forestry, hosted and deployed by Netlify." - -# The URL to the site on the internet. siteURL: https://pharmaseal.co/ - -# Link to the site's Hugo source code if public and you can/want to share. -# Remove or leave blank if not needed/wanted. - -# Add credit to the article author. Leave blank or remove if not needed/wanted. byline: "[Roboto Studio](https://roboto.studio), Jonathan Alford" - --- We wanted to shake the status quo with PHARMASEAL, opting for a fast and scalable website built with Hugo instead of slower monolithic systems the competitors were using. diff --git a/content/en/showcase/quiply-employee-communications-app/index.md b/content/en/showcase/quiply-employee-communications-app/index.md index e1e426ed2..2c8854a8d 100644 --- a/content/en/showcase/quiply-employee-communications-app/index.md +++ b/content/en/showcase/quiply-employee-communications-app/index.md @@ -1,23 +1,9 @@ --- - -# A suitable title for this article. title: Quiply Employee Communications App - -# Set this to the current date. date: 2018-02-13 - -description: "\"It became immediately clear that we'd use Hugo going forward as it compiles super-fast, is intuitive to use and offers all the features we need.\"" - -# The URL to the site on the internet. +description: '"It became immediately clear that we would use Hugo going forward as it compiles super-fast, is intuitive to use, and offers all the features we need."' siteURL: https://www.quiply.com - -# Link to the site's Hugo source code if public and you can/want to share. -# Remove or leave blank if not needed/wanted. -# siteSource: https://github.com/gohugoio/hugoDocs - -# Add credit to the article author. Leave blank or remove if not needed/wanted. byline: "[Sebastian Schirmer](mailto:sebastian.schirmer@quiply.com), Quiply Co-Founder" - --- With the launch of our Employee Communications app Quiply we created a very simple and static one-page website to showcase our product. diff --git a/content/en/showcase/template/bio.md b/content/en/showcase/template/bio.md deleted file mode 100644 index de9287898..000000000 --- a/content/en/showcase/template/bio.md +++ /dev/null @@ -1,7 +0,0 @@ - -Add some **general info** about the site here. - -The site is built by: - -* [Person 1](https://example.org) -* [Person 1](https://example.org) diff --git a/content/en/showcase/template/featured-template.png b/content/en/showcase/template/featured-template.png deleted file mode 100644 index 4f390132eb13d9640019d30f13aa1cb882e5c5eb..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 41270 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 diff --git a/content/en/showcase/template/index.md b/content/en/showcase/template/index.md deleted file mode 100644 index abfb0803c..000000000 --- a/content/en/showcase/template/index.md +++ /dev/null @@ -1,18 +0,0 @@ ---- -title: Hugo Showcase Template -date: 2018-02-07 -description: "A short description of this page." -siteURL: https://gohugo.io/ -siteSource: https://github.com/gohugoio/hugoDocs -byline: "[bep](https://github.com/bep), Hugo Lead" ---- -Have a **notable Hugo site[^1]**? We would love to feature it in this **Showcase Section** - -Please: - -1. Fork https://github.com/gohugoio/hugoDocs. -1. Run `hugo new content showcase/your-site`. This will use the archetype bundle in the [docs repo](https://github.com/gohugoio/hugoDocs/tree/master/archetypes). -1. Follow the instructions in the newly created page bundle. -1. Create a new pull request in https://github.com/gohugoio/hugoDocs/pulls. - -[^1]: We want this to show Hugo in its best light, so this is not for the average Hugo blog. In most cases the answer to "Is my site [notable](https://www.dictionary.com/browse/notable)?" will be obvious, but if in doubt, create an [issue](https://github.com/gohugoio/hugoDocs/issues) with a link and some words, and we can discuss it. But if you have a site with an interesting Hugo story or a company site where the company itself is notable, you are most welcome. diff --git a/content/en/showcase/tomango/bio.md b/content/en/showcase/tomango/bio.md index 052bd93cd..c90e48163 100644 --- a/content/en/showcase/tomango/bio.md +++ b/content/en/showcase/tomango/bio.md @@ -1,4 +1,3 @@ - We help ambitious businesses grow by getting more of the customers they want. Our new site runs quickly, anywhere in the world, regardless of internet connectivity. diff --git a/content/en/showcase/tomango/index.md b/content/en/showcase/tomango/index.md index 6dc1a5c1f..d07abf92a 100644 --- a/content/en/showcase/tomango/index.md +++ b/content/en/showcase/tomango/index.md @@ -1,17 +1,10 @@ --- - title: Tomango - date: 2018-05-04 - -description: "Showcase: \"Tomango site relaunch: Building our JAMstack site\"" - +description: 'Showcase: "Tomango site relaunch: Building our JAMstack site"' siteURL: https://www.tomango.co.uk - siteSource: https://github.com/trys/tomango-2018 - byline: "[Trys Mudford](https://www.trysmudford.com), Lead Developer, Tomango" - --- Hugo is our static site generator (SSG) of choice. It's **really quick**. After using it on a number of [client projects](/showcase/hartwell-insurance/), it became clear that our new site _had_ to be built with Hugo. diff --git a/content/en/templates/404.md b/content/en/templates/404.md index ae18428fb..1a1a3c146 100644 --- a/content/en/templates/404.md +++ b/content/en/templates/404.md @@ -2,18 +2,14 @@ title: Custom 404 page linkTitle: 404 templates description: Create a template to render a 404 error page. -categories: [templates] +categories: [] keywords: [] -menu: - docs: - parent: templates - weight: 160 -weight: 160 +weight: 190 --- To render a 404 error page in the root of your site, create a 404 template in the root of the `layouts` directory. For example: -{{< code file=layouts/404.html >}} +```go-html-template {file="layouts/404.html"} {{ define "main" }}

404 Not Found

The page you requested cannot be found.

@@ -23,7 +19,7 @@ To render a 404 error page in the root of your site, create a 404 template in th

{{ end }} -{{< /code >}} +``` For multilingual sites, add the language key to the file name: diff --git a/content/en/templates/_common/_index.md b/content/en/templates/_common/_index.md deleted file mode 100644 index 4328d4d14..000000000 --- a/content/en/templates/_common/_index.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -cascade: - _build: - list: never - publishResources: false - render: never ---- - - diff --git a/content/en/templates/_common/filter-sort-group.md b/content/en/templates/_common/filter-sort-group.md deleted file mode 100644 index 24bbee96e..000000000 --- a/content/en/templates/_common/filter-sort-group.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -_comment: Do not remove front matter. ---- - -{{% note %}} -The [page collections quick reference guide] describes methods and functions to filter, sort, and group page collections. - -[page collections quick reference guide]: /quick-reference/page-collections/ -{{% /note %}} diff --git a/content/en/templates/_index.md b/content/en/templates/_index.md index d205c9218..ea293e8e1 100644 --- a/content/en/templates/_index.md +++ b/content/en/templates/_index.md @@ -1,16 +1,8 @@ --- title: Templates - description: Create templates to render your content, resources, and data. categories: [] keywords: [] -menu: - docs: - identifier: templates-in-this-section - parent: templates - weight: 10 weight: 10 aliases: [/templates/overview/,/templates/content] --- - -A template is an HTML file with [template actions](g), located within the `layouts` directory of a project, theme, or module. Visit the topics below, in the order presented, to understand template selection and creation. diff --git a/content/en/templates/base.md b/content/en/templates/base.md index 45320e3cf..bb6a25b1e 100644 --- a/content/en/templates/base.md +++ b/content/en/templates/base.md @@ -1,14 +1,9 @@ --- title: Base templates description: The base and block construct allows you to define the outer shell of your master templates (i.e., the chrome of the page). -categories: [templates,fundamentals] +categories: [] keywords: [] -menu: - docs: - parent: templates - weight: 50 -weight: 50 -toc: true +weight: 40 aliases: [/templates/blocks/,/templates/base-templates-and-blocks/] --- @@ -26,7 +21,7 @@ See [Template Lookup Order](/templates/lookup-order/) for details and examples. The following defines a simple base template at `_default/baseof.html`. As a default template, it is the shell from which all your pages will be rendered unless you specify another `*baseof.html` closer to the beginning of the lookup order. -{{< code file=layouts/_default/baseof.html >}} +```go-html-template {file="layouts/_default/baseof.html"} @@ -46,13 +41,13 @@ The following defines a simple base template at `_default/baseof.html`. As a def {{ end }} -{{< /code >}} +``` ## Override the base template The default list template will inherit all of the code defined above and can then implement its own `"main"` block from: -{{< code file=layouts/_default/list.html >}} +```go-html-template {file="layouts/_default/list.html"} {{ define "main" }}

Posts

{{ range .Pages }} @@ -62,25 +57,25 @@ The default list template will inherit all of the code defined above and can the {{ end }} {{ end }} -{{< /code >}} - -This replaces the contents of our (basically empty) "main" block with something useful for the list template. In this case, we didn't define a `"title"` block, so the contents from our base template remain unchanged in lists. - -{{% note %}} -Code that you put outside the block definitions *can* break your layout. This even includes HTML comments. For example: - -```go-html-template - -{{ define "main" }} -...your code here -{{ end }} ``` -[See this thread from the Hugo discussion forums.](https://discourse.gohugo.io/t/baseof-html-block-templates-and-list-types-results-in-empty-pages/5612/6) -{{% /note %}} -The following shows how you can override both the `"main"` and `"title"` block areas from the base template with code unique to your default [single template]: +This replaces the contents of our (basically empty) `main` block with something useful for the list template. In this case, we didn't define a `title` block, so the contents from our base template remain unchanged in lists. -{{< code file=layouts/_default/single.html >}} +> [!warning] +> Only [template comments] are allowed outside a block's `define` and `end` statements. Avoid placing any other text, including HTML comments, outside these boundaries. Doing so will cause rendering issues, potentially resulting in a blank page. See the example below. + +```go-html-template {file="layouts/_default/do-not-do-this.html"} +
This div element broke your template.
+{{ define "main" }} +

{{ .Title }}

+ {{ .Content }} +{{ end }} + +``` + +The following shows how you can override both the `main` and `title` block areas from the base template with code unique to your default [single template]: + +```go-html-template {file="layouts/_default/single.html"} {{ define "title" }} {{ .Title }} – {{ .Site.Title }} @@ -89,6 +84,7 @@ The following shows how you can override both the `"main"` and `"title"` block a

{{ .Title }}

{{ .Content }} {{ end }} -{{< /code >}} +``` [single template]: /templates/types/#single +[template comments]: /templates/introduction/#comments diff --git a/content/en/templates/content-view.md b/content/en/templates/content-view.md index 7b995ece5..f001e400e 100644 --- a/content/en/templates/content-view.md +++ b/content/en/templates/content-view.md @@ -1,21 +1,16 @@ --- title: Content view templates description: Hugo can render alternative views of your content, useful in list and summary views. -categories: [templates] +categories: [] keywords: [] -menu: - docs: - parent: templates - weight: 120 -weight: 120 -toc: true +weight: 110 aliases: [/templates/views/] --- The following are common use cases for content views: -* You want content of every type to be shown on the home page but only with limited [summary views][summaries]. -* You only want a bulleted list of your content in a [taxonomy template]. Views make this very straightforward by delegating the rendering of each different type of content to the content itself. +- You want content of every type to be shown on the home page but only with limited [summary views][summaries]. +- You only want a bulleted list of your content in a [taxonomy template]. Views make this very straightforward by delegating the rendering of each different type of content to the content itself. ## Create a content view @@ -46,11 +41,11 @@ The following is the lookup order for content views ordered by specificity. ## Example: content view inside a list -### `list.html` +### list.html In this example, `.Render` is passed into the template to call the [render function][render]. `.Render` is a special function that instructs content to render itself with the view template provided as the first argument. In this case, the template is going to render the `summary.html` view that follows: -{{< code file=layouts/_default/list.html >}} +```go-html-template {file="layouts/_default/list.html"}

{{ .Title }}

@@ -59,13 +54,13 @@ In this example, `.Render` is passed into the template to call the [render funct {{ end }}
-{{< /code >}} +``` -### `summary.html` +### summary.html Hugo passes the `Page` object to the following `summary.html` view template. -{{< code file=layouts/_default/summary.html >}} +```go-html-template {file="layouts/_default/summary.html"} -{{< /code >}} +``` -### `li.html` +### li.html Continuing on the previous example, we can change our render function to use a smaller `li.html` view by changing the argument in the call to the `.Render` function (i.e., `{{ .Render "li" }}`). -{{< code file=layouts/_default/li.html >}} +```go-html-template {file="layouts/_default/li.html"}
  • {{ .LinkTitle }}
    {{ .Date.Format "Mon, Jan 2, 2006" }}
    • -{{< /code >}} +``` [render]: /methods/page/render/ [single template]: /templates/types/#single diff --git a/content/en/templates/embedded.md b/content/en/templates/embedded.md index 2e571256e..198136393 100644 --- a/content/en/templates/embedded.md +++ b/content/en/templates/embedded.md @@ -1,33 +1,21 @@ --- title: Embedded templates description: Hugo provides embedded templates for common use cases. -categories: [templates] +categories: [] keywords: [] -menu: - docs: - parent: templates - weight: 200 -weight: 200 -toc: true +weight: 170 aliases: [/templates/internal] --- ## Disqus -{{% note %}} -To override Hugo's embedded Disqus template, copy the [source code] to a file with the same name in the `layouts/partials` directory, then call it from your templates using the [`partial`] function: - -`{{ partial "disqus.html" . }}` - -[`partial`]: /functions/partials/include/ -[source code]: {{% eturl disqus %}} -{{% /note %}} +> [!note] +> To override Hugo's embedded Disqus template, copy the [source code]({{% eturl disqus %}}) to a file with the same name in the `layouts/partials` directory, then call it from your templates using the [`partial`] function: +> +> `{{ partial "disqus.html" . }}` Hugo includes an embedded template for [Disqus], a popular commenting system for both static and dynamic websites. To effectively use Disqus, secure a Disqus "shortname" by [signing up] for the free service. -[Disqus]: https://disqus.com -[signing up]: https://disqus.com/profile/signup/ - To include the embedded template: ```go-html-template @@ -38,7 +26,7 @@ To include the embedded template: To use Hugo's Disqus template, first set up a single configuration value: -{{< code-toggle file="hugo" >}} +{{< code-toggle file=hugo >}} [services.disqus] shortname = 'your-disqus-shortname' {{}} @@ -66,19 +54,13 @@ disable ## Google Analytics -{{% note %}} -To override Hugo's embedded Google Analytics template, copy the [source code] to a file with the same name in the `layouts/partials` directory, then call it from your templates using the [`partial`] function: - -`{{ partial "google_analytics.html" . }}` - -[`partial`]: /functions/partials/include/ -[source code]: {{% eturl google_analytics %}} -{{% /note %}} +> [!note] +> To override Hugo's embedded Google Analytics template, copy the [source code]({{% eturl google_analytics %}}) to a file with the same name in the `layouts/partials` directory, then call it from your templates using the [`partial`] function: +> +> `{{ partial "google_analytics.html" . }}` Hugo includes an embedded template supporting [Google Analytics 4]. -[Google Analytics 4]: https://support.google.com/analytics/answer/10089681 - To include the embedded template: ```go-html-template @@ -110,14 +92,10 @@ respectDoNotTrack ## Open Graph -{{% note %}} -To override Hugo's embedded Open Graph template, copy the [source code] to a file with the same name in the `layouts/partials` directory, then call it from your templates using the [`partial`] function: - -`{{ partial "opengraph.html" . }}` - -[`partial`]: /functions/partials/include/ -[source code]: {{% eturl opengraph %}} -{{% /note %}} +> [!note] +> To override Hugo's embedded Open Graph template, copy the [source code]({{% eturl opengraph %}}) to a file with the same name in the `layouts/partials` directory, then call it from your templates using the [`partial`] function: +> +> `{{ partial "opengraph.html" . }}` Hugo includes an embedded template for the [Open Graph protocol](https://ogp.me/), metadata that enables a page to become a rich object in a social graph. This format is used for Facebook and some other sites. @@ -169,19 +147,13 @@ If using YouTube this will produce a og:video tag like ` [!note] +> To override Hugo's embedded Schema template, copy the [source code]({{% eturl schema %}}) to a file with the same name in the `layouts/partials` directory, then call it from your templates using the [`partial`] function: +> +> `{{ partial "schema.html" . }}` Hugo includes an embedded template to render [microdata] `meta` elements within the `head` element of your templates. -[microdata]: https://html.spec.whatwg.org/multipage/microdata.html#microdata - To include the embedded template: ```go-html-template @@ -190,14 +162,10 @@ To include the embedded template: ## X (Twitter) Cards -{{% note %}} -To override Hugo's embedded Twitter Cards template, copy the [source code] to a file with the same name in the `layouts/partials` directory, then call it from your templates using the [`partial`] function: - -`{{ partial "twitter_cards.html" . }}` - -[`partial`]: /functions/partials/include/ -[source code]: {{% eturl twitter_cards %}} -{{% /note %}} +> [!note] +> To override Hugo's embedded Twitter Cards template, copy the [source code]({{% eturl twitter_cards %}}) to a file with the same name in the `layouts/partials` directory, then call it from your templates using the [`partial`] function: +> +> `{{ 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. @@ -218,21 +186,21 @@ Hugo's X (Twitter) Card template is configured using a mix of configuration sett description = "Text about my cool site" {{}} -{{< code-toggle file=content/blog/my-post.md >}} +{{< code-toggle file=content/blog/my-post.md fm=true >}} title = "Post title" 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](/getting-started/configuration/) are used instead. +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`. 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: -{{< code-toggle file="hugo" copy=false >}} +{{< code-toggle file=hugo >}} [params.social] twitter = "GoHugoIO" {{}} @@ -242,3 +210,9 @@ NOTE: The `@` will be added for you ```html ``` + +[`partial`]: /functions/partials/include/ +[Disqus]: https://disqus.com +[Google Analytics 4]: https://support.google.com/analytics/answer/10089681 +[microdata]: https://html.spec.whatwg.org/multipage/microdata.html#microdata +[signing up]: https://disqus.com/profile/signup/ diff --git a/content/en/templates/home.md b/content/en/templates/home.md index 18114eb0f..937a4a5a8 100644 --- a/content/en/templates/home.md +++ b/content/en/templates/home.md @@ -1,41 +1,33 @@ --- title: Home page templates description: The home page of a website is often formatted differently than the other pages. For this reason, Hugo makes it easy for you to define your new site's home page as a unique template. -categories: [templates] +categories: [] keywords: [] -menu: - docs: - parent: templates - weight: 60 -weight: 60 -toc: true +weight: 50 aliases: [/layout/homepage/,/templates/homepage-template/,/templates/homepage/] --- ## Introduction -A home page template is used to render your site's home page, and is the only template required for a single-page website. For example, the home page template below inherits the site's shell from the base template and renders the home page content, such as a list of other pages. +A home page template is used to render your site's home page, and is the only template required for a single-page website. For example, the home page template below inherits the site's shell from the base template and renders the home page content, such as a list of other pages. -{{< code file=layouts/_default/home.html >}} +```go-html-template {file="layouts/_default/home.html"} {{ define "main" }} {{ .Content }} {{ range site.RegularPages }}

    {{ .LinkTitle }}

    {{ end }} {{ end }} -{{< /code >}} +``` -{{% include "templates/_common/filter-sort-group.md" %}} +{{% include "/_common/filter-sort-group.md" %}} ## Lookup order Hugo's [template lookup order] determines the template path, allowing you to create unique templates for any page. -[template lookup order]: /templates/lookup-order/#home-templates - -{{% note %}} -You must have thorough understanding of the template lookup order when creating templates. Template selection is based on template type, page kind, content type, section, language, and output format. -{{% /note %}} +> [!note] +> You must have thorough understanding of the template lookup order when creating templates. Template selection is based on template type, page kind, content type, section, language, and output format. ## Content and front matter @@ -53,7 +45,7 @@ params: The home page template below inherits the site's shell from the base template, renders the subtitle and content as defined in the `_index.md` file, then renders of list of the site's [regular pages](g). -{{< code file=layouts/_default/home.html >}} +```go-html-template {file="layouts/_default/home.html"} {{ define "main" }}

    {{ .Params.Subtitle }}

    {{ .Content }} @@ -61,4 +53,6 @@ The home page template below inherits the site's shell from the base template, r

    {{ .LinkTitle }}

    {{ end }} {{ end }} -{{< /code >}} +``` + +[template lookup order]: /templates/lookup-order/#home-templates diff --git a/content/en/templates/introduction.md b/content/en/templates/introduction.md index b68ecf925..8898ee456 100644 --- a/content/en/templates/introduction.md +++ b/content/en/templates/introduction.md @@ -1,34 +1,22 @@ --- title: Introduction to templating linkTitle: Introduction -description: Create templates to render your content, resources, and data. -categories: [templates,fundamentals] +description: An introduction to Hugo's templating syntax. +categories: [] keywords: [] -menu: - docs: - identifier: templates-introduction - parent: templates - weight: 20 -weight: 20 -toc: true +weight: 10 --- -A template is a file in the `layouts` directory of a project, theme, or module. Templates use [variables] , [functions], and [methods] to transform your content, resources, and data into a published page. +{{% glossary-term template %}} -[functions]: /functions/ -[methods]: /methods/ -[variables]: #variables +Templates use [variables], [functions], and [methods] to transform your content, resources, and data into a published page. -{{% note %}} -Hugo uses Go's [text/template] and [html/template] packages. - -The text/template package implements data-driven templates for generating textual output, while the html/template package implements data-driven templates for generating HTML output safe against code injection. - -By default, Hugo uses the html/template package when rendering HTML files. - -[text/template]: https://pkg.go.dev/text/template -[html/template]: https://pkg.go.dev/html/template -{{% /note %}} +> [!note] +> Hugo uses Go's [text/template] and [html/template] packages. +> +> The text/template package implements data-driven templates for generating textual output, while the html/template package implements data-driven templates for generating HTML output safe against code injection. +> +> By default, Hugo uses the html/template package when rendering HTML files. For example, this HTML template initializes the `$v1` and `$v2` variables, then displays them and their product within an HTML paragraph. @@ -38,9 +26,7 @@ For example, this HTML template initializes the `$v1` and `$v2` variables, then

    The product of {{ $v1 }} and {{ $v2 }} is {{ mul $v1 $v2 }}.

    ``` -While HTML templates are the most common, you can create templates for any [output format] including CSV, JSON, RSS, and plain text. - -[output format]: /templates/output-formats/ +While HTML templates are the most common, you can create templates for any [output format](g) including CSV, JSON, RSS, and plain text. ## Context @@ -52,21 +38,15 @@ For example, a template for a single page receives a `Page` object, and the `Pag Within a template, the dot (`.`) represents the current context. -{{< code file=layouts/_default/single.html >}} +```go-html-template {file="layouts/_default/single.html"}

    {{ .Title }}

    -{{< /code >}} +``` In the example above the dot represents the `Page` object, and we call its [`Title`] method to return the title as defined in [front matter]. -[front matter]: /content-management/front-matter/ -[`Title`]: /methods/page/title - The current context may change within a template. For example, at the top of a template the context might be a `Page` object, but we rebind the context to another value or object within [`range`] or [`with`] blocks. -[`range`]: /functions/go-template/range/ -[`with`]: /functions/go-template/with/ - -{{< code file=layouts/_default/single.html >}} +```go-html-template {file="layouts/_default/single.html"}

    {{ .Title }}

    {{ range slice "foo" "bar" }} @@ -76,7 +56,7 @@ The current context may change within a template. For example, at the top of a t {{ with "baz" }}

    {{ . }}

    {{ end }} -{{< /code >}} +``` In the example above, the context changes as we `range` through the [slice](g) of values. In the first iteration the context is "foo", and in the second iteration the context is "bar". Inside of the `with` block the context is "baz". Hugo renders the above to: @@ -91,11 +71,11 @@ In the example above, the context changes as we `range` through the [slice](g) o Within a `range` or `with` block you can access the context passed into the template by prepending a dollar sign (`$`) to the dot: -{{< code file=layouts/_default/single.html >}} +```go-html-template {file="layouts/_default/single.html"} {{ with "foo" }}

    {{ $.Title }} - {{ . }}

    {{ end }} -{{< /code >}} +``` Hugo renders this to: @@ -103,9 +83,8 @@ Hugo renders this to:

    My Page Title - foo

    ``` -{{% note %}} -Make sure that you thoroughly understand the concept of _context_ before you continue reading. The most common templating errors made by new users relate to context. -{{% /note %}} +> [!note] +> Make sure that you thoroughly understand the concept of _context_ before you continue reading. The most common templating errors made by new users relate to context. ## Actions @@ -113,12 +92,12 @@ In the examples above the paired opening and closing braces represent the beginn A template action may contain literal values ([boolean](g), [string](g), [integer](g), and [float](g)), variables, functions, and methods. -{{< code file=layouts/_default/single.html >}} +```go-html-template {file="layouts/_default/single.html"} {{ $convertToLower := true }} {{ if $convertToLower }}

    {{ strings.ToLower .Title }}

    {{ end }} -{{< /code >}} +``` In the example above: @@ -140,12 +119,12 @@ Hugo renders the above to: Notice the blank lines and indentation in the previous example? Although irrelevant in production when you typically minify the output, you can remove the adjacent whitespace by using template action delimiters with hyphens: -{{< code file=layouts/_default/single.html >}} +```go-html-template {file="layouts/_default/single.html"} {{- $convertToLower := true -}} {{- if $convertToLower -}}

    {{ strings.ToLower .Title }}

    {{- end -}} -{{< /code >}} +``` Hugo renders this to: @@ -178,9 +157,8 @@ These are also equivalent: {{ 5 | add 2 | mul 6 }} → 42 ``` -{{% note %}} -Remember that the piped value becomes the final argument to the function or method to which you are piping. -{{% /note %}} +> [!note] +> Remember that the piped value becomes the final argument to the function or method to which you are piping. ### Line splitting @@ -225,8 +203,6 @@ Variables initialized inside of an `if`, `range`, or `with` block are scoped to With variables that represent a slice or map, use the [`index`] function to return the desired value. -[`index`]: /functions/collections/indexfunction/ - ```go-html-template {{ $slice := slice "foo" "bar" "baz" }} {{ index $slice 2 }} → baz @@ -235,9 +211,8 @@ With variables that represent a slice or map, use the [`index`] function to retu {{ index $map "c" }} → baz ``` -{{% note %}} -Slices and arrays are zero-based; element 0 is the first element. -{{% /note %}} +> [!note] +> Slices and arrays are zero-based; element 0 is the first element. With variables that represent a map or object, [chain](g) identifiers to return the desired value or to access the desired method. @@ -249,9 +224,8 @@ With variables that represent a map or object, [chain](g) identifiers to return {{ $homePage.Title }} → My Homepage ``` -{{% note %}} -As seen above, object and method names are capitalized. Although not required, to avoid confusion we recommend beginning variable and map key names with a lowercase letter or underscore. -{{% /note %}} +> [!note] +> As seen above, object and method names are capitalized. Although not required, to avoid confusion we recommend beginning variable and map key names with a lowercase letter or underscore. ## Functions @@ -259,12 +233,8 @@ Used within a template action, a function takes one or more arguments and return Go's text/template and html/template packages provide a small set of functions, operators, and statements for general use. See the [go-templates] section of the function documentation for details. -[go-templates]: /functions/go-template/ - Hugo provides hundreds of custom [functions] categorized by namespace. For example, the `strings` namespace includes these and other functions: -[functions]: /functions - Function|Alias :--|:-- [`strings.ToLower`](/functions/strings/tolower)|`lower` @@ -285,10 +255,6 @@ Used within a template action and associated with an object, a method takes zero The most commonly accessed objects are the [`Page`] and [`Site`] objects. This is a small sampling of the [methods] available to each object. -[`Site`]: /methods/site/ -[`Page`]: /methods/page/ -[methods]: /methods/ - Object|Method|Description :--|:--|:-- `Page`|[`Date`](methods/page/date/)|Returns the date of the given page. @@ -300,34 +266,31 @@ Object|Method|Description Chain the method to its object with a dot (`.`) as shown below, remembering that the leading dot represents the [current context]. -[current context]: #current-context - -{{< code file=layouts/_default/single.html >}} +```go-html-template {file="layouts/_default/single.html"} {{ .Site.Title }} → My Site Title {{ .Page.Title }} → My Page Title -{{< /code >}} +``` The context passed into most templates is a `Page` object, so this is equivalent to the previous example: -{{< code file=layouts/_default/single.html >}} +```go-html-template {file="layouts/_default/single.html"} {{ .Site.Title }} → My Site Title {{ .Title }} → My Page Title -{{< /code >}} +``` Some methods take an argument. Separate the argument from the method with a space. For example: -{{< code file=layouts/_default/single.html >}} +```go-html-template {file="layouts/_default/single.html"} {{ $page := .Page.GetPage "/books/les-miserables" }} {{ $page.Title }} → Les Misérables -{{< /code >}} +``` ## Comments -{{% note %}} -Do not attempt to use HTML comment delimiters to comment out template code. - -Hugo strips HTML comments when rendering a page, but first evaluates any template code within the HTML comment delimiters. Depending on the template code within the HTML comment delimiters, this could cause unexpected results or fail the build. -{{% /note %}} +> [!note] +> Do not attempt to use HTML comment delimiters to comment out template code. +> +> Hugo strips HTML comments when rendering a page, but first evaluates any template code within the HTML comment delimiters. Depending on the template code within the HTML comment delimiters, this could cause unexpected results or fail the build. Template comments are similar to template actions. Paired opening and closing braces represent the beginning and end of a comment. For example: @@ -353,8 +316,6 @@ You may not nest one comment inside of another. To render an HTML comment, pass a string through the [`safeHTML`] template function. For example: -[`safeHTML`]: /functions/safe/html - ```go-html-template {{ "" | safeHTML }} {{ printf "" .Site.Title | safeHTML }} @@ -364,8 +325,6 @@ To render an HTML comment, pass a string through the [`safeHTML`] template funct Use the [`template`] function to include one or more of Hugo's [embedded templates]: -[embedded templates]: /templates/embedded/ - ```go-html-template {{ template "_internal/google_analytics.html" . }} {{ template "_internal/opengraph" . }} @@ -374,14 +333,8 @@ Use the [`template`] function to include one or more of Hugo's [embedded templat {{ template "_internal/twitter_cards.html" . }} ``` -[`partial`]: /functions/partials/include/ -[`partialCached`]: /functions/partials/includecached/ -[`template`]: /functions/go-template/template/ - Use the [`partial`] or [`partialCached`] function to include one or more [partial templates]: -[partial templates]: /templates/partial - ```go-html-template {{ partial "breadcrumbs.html" . }} {{ partialCached "css.html" . }} @@ -389,24 +342,17 @@ Use the [`partial`] or [`partialCached`] function to include one or more [partia Create your partial templates in the layouts/partials directory. -{{% note %}} -In the examples above, note that we are passing the current context (the dot) to each of the templates. -{{% /note %}} +> [!note] +> In the examples above, note that we are passing the current context (the dot) to each of the templates. ## Examples This limited set of contrived examples demonstrates some of concepts described above. Please see the [functions], [methods], and [templates] documentation for specific examples. -[templates]: /templates/ - ### Conditional blocks See documentation for [`if`], [`else`], and [`end`]. -[`if`]: /functions/go-template/if/ -[`else`]: /functions/go-template/else/ -[`end`]: /functions/go-template/end/ - ```go-html-template {{ $var := 42 }} {{ if eq $var 6 }} @@ -424,9 +370,6 @@ See documentation for [`if`], [`else`], and [`end`]. See documentation for [`and`] and [`or`]. -[`and`]: /functions/go-template/and -[`or`]: /functions/go-template/or - ```go-html-template {{ $v1 := true }} {{ $v2 := false }} @@ -448,8 +391,6 @@ See documentation for [`and`] and [`or`]. See documentation for [`range`], [`else`], and [`end`]. -[`range`]: /functions/go-template/range/ - ```go-html-template {{ $s := slice "foo" "bar" "baz" }} {{ range $s }} @@ -461,8 +402,6 @@ See documentation for [`range`], [`else`], and [`end`]. Use the [`seq`] function to loop a specified number of times: -[`seq`]: /functions/collections/seq - ```go-html-template {{ $total := 0 }} {{ range seq 4 }} @@ -475,8 +414,6 @@ Use the [`seq`] function to loop a specified number of times: See documentation for [`with`], [`else`], and [`end`]. -[`with`]: /functions/go-template/with/ - ```go-html-template {{ $var := "foo" }} {{ with $var }} @@ -534,21 +471,65 @@ Access the custom site parameters by chaining the identifiers: See documentation for the [`Params`](/methods/page/params/) method on a `Page` object. -With this front matter: +By way of example, consider this front matter: -{{< code-toggle file=content/news/annual-conference.md >}} +{{< code-toggle file=content/annual-conference.md fm=true >}} title = 'Annual conference' date = 2023-10-17T15:11:37-07:00 [params] display_related = true +key-with-hyphens = 'must use index function' [params.author] email = 'jsmith@example.org' name = 'John Smith' {{< /code-toggle >}} -Access the custom page parameters by chaining the identifiers: +The `title` and `date` fields are standard [front matter fields], while the other fields are user-defined. + +Access the custom fields by [chaining](g) the [identifiers](g) when needed: ```go-html-template {{ .Params.display_related }} → true +{{ .Params.author.email }} → jsmith@example.org {{ .Params.author.name }} → John Smith ``` + +In the template example 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: + +```go-html-template +{{ index .Params "key-with-hyphens" }} → must use index function +``` + +[`and`]: /functions/go-template/and +[`else`]: /functions/go-template/else/ +[`end`]: /functions/go-template/end/ +[`if`]: /functions/go-template/if/ +[`index`]: /functions/collections/indexfunction/ +[`index`]: /functions/collections/indexfunction/ +[`or`]: /functions/go-template/or +[`Page`]: /methods/page/ +[`partial`]: /functions/partials/include/ +[`partialCached`]: /functions/partials/includecached/ +[`range`]: /functions/go-template/range/ +[`range`]: /functions/go-template/range/ +[`safeHTML`]: /functions/safe/html +[`seq`]: /functions/collections/seq +[`Site`]: /methods/site/ +[`template`]: /functions/go-template/template/ +[`Title`]: /methods/page/title +[`with`]: /functions/go-template/with/ +[`with`]: /functions/go-template/with/ +[current context]: #current-context +[embedded templates]: /templates/embedded/ +[front matter]: /content-management/front-matter/ +[front matter fields]: /content-management/front-matter/#fields +[functions]: /functions/ +[functions]: /functions +[go-templates]: /functions/go-template/ +[html/template]: https://pkg.go.dev/html/template +[methods]: /methods/ +[methods]: /methods/ +[partial templates]: /templates/partial +[templates]: /templates/ +[text/template]: https://pkg.go.dev/text/template +[variables]: #variables diff --git a/content/en/templates/lookup-order.md b/content/en/templates/lookup-order.md index c1a7b2676..518900797 100644 --- a/content/en/templates/lookup-order.md +++ b/content/en/templates/lookup-order.md @@ -2,14 +2,9 @@ title: Template lookup order linkTitle: Lookup order description: Hugo uses the rules below to select a template for a given page, starting from the most specific. -categories: [templates,fundamentals] +categories: [] keywords: [] -menu: - docs: - parent: templates - weight: 40 -weight: 40 -toc: true +weight: 20 --- ## Lookup rules @@ -23,7 +18,7 @@ Layout : Can be set in front matter. Output Format -: See [Custom Output Formats](/templates/output-formats). An output format has both a `name` (e.g. `rss`, `amp`, `html`) and a `suffix` (e.g. `xml`, `html`). We prefer matches with both (e.g. `index.amp.html`), but look for less specific templates. +: See [configure output formats](/configuration/output-formats/). An output format has both a `name` (e.g. `rss`, `amp`, `html`) and a `suffix` (e.g. `xml`, `html`). We prefer matches with both (e.g. `index.amp.html`), but look for less specific templates. Note that if the output format's Media Type has more than one suffix defined, only the first is considered. @@ -36,9 +31,8 @@ Type Section : Is relevant for `section`, `taxonomy` and `term` types. -{{% note %}} -Templates can live in either the project's or the themes' `layout` directories, and the most specific templates will be chosen. Hugo will interleave the lookups listed below, finding the most specific one either in the project or themes. -{{% /note %}} +> [!note] +> Templates can live in either the project's or the themes' `layout` directories, and the most specific templates will be chosen. Hugo will interleave the lookups listed below, finding the most specific one either in the project or themes. ## Target a template @@ -62,7 +56,7 @@ layouts/ But the contact page probably has a form and requires a different template. In the front matter specify `layout`: -{{< code-toggle file=content/contact.md >}} +{{< code-toggle file=content/contact.md fm=true >}} title = 'Contact' layout = 'contact' {{< /code-toggle >}} @@ -78,12 +72,12 @@ layouts/ As a content type, the word `page` is vague. Perhaps `miscellaneous` would be better. Add `type` to the front matter of each page: -{{< code-toggle file=content/about.md >}} +{{< code-toggle file=content/about.md fm=true >}} title = 'About' type = 'miscellaneous' {{< /code-toggle >}} -{{< code-toggle file=content/contact.md >}} +{{< code-toggle file=content/contact.md fm=true >}} title = 'Contact' type = 'miscellaneous' layout = 'contact' diff --git a/content/en/templates/menu.md b/content/en/templates/menu.md index bd0bc5569..4ff423255 100644 --- a/content/en/templates/menu.md +++ b/content/en/templates/menu.md @@ -1,15 +1,9 @@ --- -title: Menus +title: Menu templates description: Create templates to render one or more menus. -categories: [templates] +categories: [] keywords: [] -menu: - docs: - identifier: templates-menu - parent: templates - weight: 180 -weight: 180 -toc: true +weight: 150 aliases: [/templates/menus/,/templates/menu-templates/] --- @@ -29,7 +23,7 @@ The example below handles every combination. This partial template recursively "walks" a menu structure, rendering a localized, accessible nested list. -{{< code file=layouts/partials/menu.html copy=true >}} +```go-html-template {file="layouts/partials/menu.html" copy=true} {{- $page := .page }} {{- $menuID := .menuID }} @@ -72,14 +66,14 @@ This partial template recursively "walks" a menu structure, rendering a localize {{- end }} {{- end }} -{{< /code >}} +``` Call the partial above, passing a menu ID and the current page in context. -{{< code file=layouts/_default/single.html >}} +```go-html-template {file="layouts/_default/single.html"} {{ partial "menu.html" (dict "menuID" "main" "page" .) }} {{ partial "menu.html" (dict "menuID" "footer" "page" .) }} -{{< /code >}} +``` ## Page references @@ -87,7 +81,7 @@ Regardless of how you [define menu entries], an entry associated with a page has This simplistic example renders a page parameter named `version` next to each entry's `name`. Code defensively using `with` or `if` to handle entries where (a) the entry points to an external resource, or (b) the `version` parameter is not defined. -{{< code file=layouts/_default/single.html >}} +```go-html-template {file="layouts/_default/single.html"} {{- range site.Menus.main }} {{ .Name }} @@ -98,7 +92,7 @@ This simplistic example renders a page parameter named `version` next to each en {{- end }} {{- end }} -{{< /code >}} +``` ## Menu entry parameters @@ -109,13 +103,13 @@ When you define menu entries [in site configuration] or [in front matter], you c 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. -{{< code file=layouts/partials/menu.html >}} +```go-html-template {file="layouts/partials/menu.html"} {{- range site.Menus.main }} {{ .Name }} {{- end }} -{{< /code >}} +``` ## Localize @@ -127,7 +121,7 @@ Hugo provides two methods to localize your menu entries. See [multilingual]. [in front matter]: /content-management/menus/#define-in-front-matter [in site configuration]: /content-management/menus/#define-in-site-configuration [localize the menu entries]: /content-management/multilingual/#menus -[menu entry defined in front matter]: /content-management/menus/#example-front-matter -[menu entry defined in site configuration]: /content-management/menus/#example-site-configuration +[menu entry defined in front matter]: /content-management/menus/#example +[menu entry defined in site configuration]: /configuration/menus [menu methods]: /methods/menu/ [multilingual]: /content-management/multilingual/#menus diff --git a/content/en/templates/output-formats.md b/content/en/templates/output-formats.md deleted file mode 100644 index c81a81264..000000000 --- a/content/en/templates/output-formats.md +++ /dev/null @@ -1,241 +0,0 @@ ---- -title: Custom output formats -description: Hugo can output content in multiple formats, including calendar events, e-book formats, Google AMP, and JSON search indexes, or any custom text format. -categories: [templates,fundamentals] -keywords: [] -menu: - docs: - parent: templates - weight: 210 -weight: 210 -toc: true -aliases: [/templates/outputs/,/extras/output-formats/,/content-management/custom-outputs/] ---- - -This page describes how to properly configure your site with the media types and output formats, as well as where to create your templates for your custom outputs. - -## Media types - -A [media type] (formerly known as a MIME type) is a two-part identifier for file formats and format contents transmitted on the internet. - -This is the full set of built-in media types in Hugo: - -{{< datatable "config" "mediaTypes" "_key" "suffixes" >}} - -Notes: - -- It is possible to add custom media types or change the defaults; e.g., if you want to change the suffix for `text/html` to `asp`. -- `Suffixes` are the values that will be used for URLs and file names for that media type in Hugo. -- The `Type` is the identifier that must be used when defining new/custom `Output Formats` (see below). -- The full set of media types will be registered in Hugo's built-in development server to make sure they are recognized by the browser. - -To add or modify a media type, define it in a `mediaTypes` section in your [site configuration], either for all sites or for a given language. - -{{< code-toggle file=hugo >}} -[mediaTypes] - [mediaTypes."text/enriched"] - suffixes = ["enr"] - [mediaTypes."text/html"] - suffixes = ["asp"] -{{}} - -The above example adds one new media type, `text/enriched`, and changes the suffix for the built-in `text/html` media type. - -These media types are configured for your output formats. If you want to redefine one of Hugo's default output formats, you also need to redefine the media type. So, if you want to change the suffix of the `HTML` output format from `html` (default) to `htm`: - -{{< code-toggle file=hugo >}} -[mediaTypes] - [mediaTypes."text/html"] - suffixes = ["htm"] - -[outputFormats] - [outputFormats.html] - mediaType = "text/html" -{{}} - -{{% note %}} -For the above to work, you also need to add an `outputs` definition in your site configuration. -{{% /note %}} - -## Output format definitions - -Given a media type and some additional configuration, you get an **Output Format**. - -This is the full set of Hugo's built-in output formats: - -{{< datatable "config" "outputFormats" "_key" "baseName" "isHTML" "isPlainText" "mediaType" "noUgly" "path" "permalinkable" "protocol" "rel" >}} - -- A page can be output in as many output formats as you want, and you can have an infinite amount of output formats defined as long as they resolve to a unique path on the file system. In the above table, the best example of this is `amp` vs. `html`. `amp` has the value `amp` for `path` so it doesn't overwrite the `html` version; e.g. we can now have both `/index.html` and `/amp/index.html`. - -- The `mediaType` must match a defined media type. -- You can define new output formats or redefine built-in output formats; e.g., if you want to put `amp` pages in a different path. - -To add or modify an output format, define it in an `outputFormats` section in your site's [configuration file](/getting-started/configuration/), either for all sites or for a given language. - -{{< code-toggle file=hugo >}} -[outputFormats.MyEnrichedFormat] -mediaType = "text/enriched" -baseName = "myindex" -isPlainText = true -protocol = "bep://" -{{}} - -The above example is fictional, but if used for the home page on a site with `baseURL` `https://example.org`, it will produce a plain text home page with the URL `bep://example.org/myindex.enr`. - -### Configure output formats - -Use these parameters when configuring an output format: - -baseName -: (`string`) The base name of the published file. Default is `index`. - -isHTML -: (`bool`) Whether to classify the output format as HTML. Hugo uses this value to determine when to create alias redirects, when to inject the LiveReload script, etc. Default is `false`. - -isPlainText -: (`bool`) Whether to parse templates for this output format with Go's [text/template] package instead of the [html/template] package. Default is `false`. - -[html/template]: https://pkg.go.dev/html/template -[text/template]: https://pkg.go.dev/text/template - -mediaType -: (`string`) The [media type] of the published file. This must match a defined media type, either [built-in](#media-types) or custom. - -[media type]: https://en.wikipedia.org/wiki/Media_type - -notAlternative -: (`bool`) Whether to exclude this output format from the values returned by the [`AlternativeOutputFormats`] method on a `Page` object. Default is `false`. - -[`AlternativeOutputFormats`]: /methods/page/alternativeoutputformats/ - -noUgly -: (`bool`) Whether to disable ugly URLs for this output format when `uglyURLs` is `true` in your site configuration. Default is `false`. - -path -: (`string`) The path to the directory containing the published files, relative to the root of the publish directory. - -permalinkable -: (`bool`) If `true`, the [`Permalink`] and [`RelPermalink`] methods on a `Page` object return the rendering output format rather than main output format ([see below](#link-to-output-formats)). Enabled by default for the `html` and `amp` output formats. Default is `false`. - -[`Permalink`]: /methods/page/permalink/ -[`RelPermalink`]: /methods/page/relpermalink/ - -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://`. - -rel -: (`string`) If provided, you can assign this value to `rel` attributes in `link` elements when iterating over output formats in your templates. Default is `alternate`. - -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`. - -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. - -## Output formats for pages - -A `Page` in Hugo can be rendered to multiple _output formats_ on the file -system. - -### Default output formats - -Every `Page` has a [`Kind`] attribute, and the default Output -Formats are set based on that. - -{{< code-toggle config=outputs />}} - -### Customizing output formats - -This can be changed by defining an `outputs` list of output formats in either -the `Page` front matter or in the site configuration (either for all sites or -per language). - -Example from site configuration file: - -{{< code-toggle file=hugo >}} -[outputs] - home = ["html", "amp", "rss"] - page = ["html"] -{{}} - -Note that in the examples above, the output formats for `section`, -`taxonomy` and `term` will stay at their default value `['html','rss']`. - -- The `outputs` definition is per page [`Kind`]. -- The names (e.g. `html`, `amp`) must match the `name` of a defined output format, and can be overridden per page in front matter. - -The following is an example of front matter in a content file that defines output formats for the rendered `Page`: - -{{< code-toggle file=content/example.md fm=true >}} -title: Example -outputs: -- html -- amp -- json -{{< /code-toggle >}} - -## List output formats - -Each `Page` object has both an [`OutputFormats`] method (all formats, including the current) and an [`AlternativeOutputFormats`] method, the latter of which is useful for creating a `link rel` list in your site's ``: - -[`OutputFormats`]: /methods/page/outputformats -[`AlternativeOutputFormats`]: /methods/page/alternativeoutputformats - -```go-html-template -{{ range .AlternativeOutputFormats -}} - -{{ end }} -``` - -## Link to output formats - -The [`Permalink`] and [`RelPermalink`] methods on a `Page` object return the first output format defined for that page (usually `HTML` if nothing else is defined). This is regardless of the template from which they are called. - -[`Permalink`]: /methods/page/permalink -[`RelPermalink`]: /methods/page/relpermalink - -From `single.json.json`: - -```go-html-template -{{ .RelPermalink }} → /that-page/ -{{ with .OutputFormats.Get "json" }} - {{ .RelPermalink }} → /that-page/index.json -{{ end }} -``` - -In order for them to return the output format of the current template file instead, the given output format should have its `permalinkable` setting set to true. - -This is the same template file as above with the `json` output format's `permalinkable` parameter set to `true`: - -```go-html-template -{{ .RelPermalink }} → /that-page/index.json -{{ with .OutputFormats.Get "html" }} - {{ .RelPermalink }} → /that-page/ -{{ end }} -``` - -## Template lookup order - -Each output format requires a template conforming to the [template lookup order]. - -For the highest specificity in the template lookup order, include the page kind, output format, and suffix in the file name: - -[template lookup order]: /templates/lookup-order/ - -```text -[page kind].[output format].[suffix] -``` - -For example, for section pages: - -Output format|Template path -:--|:-- -`html`|`layouts/_default/section.html.html` -`json`|`layouts/_default/section.json.json` -`rss`|`layouts/_default/section.rss.xml` - -[site configuration]: /getting-started/configuration/ -[`kind`]: /methods/page/kind/ diff --git a/content/en/templates/pagination.md b/content/en/templates/pagination.md index 674c6a565..018ec9271 100644 --- a/content/en/templates/pagination.md +++ b/content/en/templates/pagination.md @@ -1,14 +1,9 @@ --- title: Pagination description: Split a list page into two or more subsets. -categories: [templates] +categories: [] keywords: [] -menu: - docs: - parent: templates - weight: 190 -weight: 190 -toc: true +weight: 160 aliases: [/extras/pagination,/doc/pagination/] --- @@ -20,9 +15,8 @@ Displaying a large page collection on a list page is not user-friendly: Improve usability by paginating `home`, `section`, `taxonomy`, and `term` pages. -{{% note %}} -The most common templating mistake related to pagination is invoking pagination more than once for a given list page. See the [caching](#caching) section below. -{{% /note %}} +> [!note] +> The most common templating mistake related to pagination is invoking pagination more than once for a given list page. See the [caching](#caching) section below. ## Terminology @@ -40,43 +34,7 @@ paginator ## Configuration -Control pagination behavior in your site configuration. These are the default settings: - -{{< code-toggle file=hugo config=pagination />}} - -disableAliases -: (`bool`) Whether to disable alias generation for the first pager. Default is `false`. - -pagerSize -: (`int`) The number of pages per pager. Default is `10`. - -path -: (`string`) The segment of each pager URL indicating that the target page is a pager. Default is `page`. - -With multilingual sites you can define the pagination behavior for each language: - -{{< code-toggle file=hugo >}} -[languages.en] -contentDir = 'content/en' -languageCode = 'en-US' -languageDirection = 'ltr' -languageName = 'English' -weight = 1 -[languages.en.pagination] -disableAliases = true -pagerSize = 10 -path = 'page' -[languages.de] -contentDir = 'content/de' -languageCode = 'de-DE' -languageDirection = 'ltr' -languageName = 'Deutsch' -weight = 2 -[languages.de.pagination] -disableAliases = true -pagerSize = 20 -path = 'blatt' -{{< /code-toggle >}} +See [configure pagination](/configuration/pagination). ## Methods @@ -93,9 +51,6 @@ The `Paginate` method is more flexible, allowing you to: By comparison, the `Paginator` method paginates the page collection passed into the template, and you cannot override the number of pages per pager. -[`Paginate`]: /methods/page/paginate/ -[`Paginator`]: /methods/page/paginator/ - ## Examples To paginate a list page using the `Paginate` method: @@ -137,22 +92,17 @@ In the example above, we: ## Caching -{{% note %}} -The most common templating mistake related to pagination is invoking pagination more than once for a given list page. -{{% /note %}} +> [!note] +> The most common templating mistake related to pagination is invoking pagination more than once for a given list page. Regardless of pagination method, the initial invocation is cached and cannot be changed. If you invoke pagination more than once for a given list page, subsequent invocations use the cached result. This means that subsequent invocations will not behave as written. When paginating conditionally, do not use the `compare.Conditional` function due to its eager evaluation of arguments. Use an `if-else` construct instead. -[`compare.Conditional`]: /functions/compare/conditional/ - ## Grouping Use pagination with any of the [grouping methods]. For example: -[grouping methods]: /quick-reference/page-collections/#group - ```go-html-template {{ $pages := where site.RegularPages "Type" "posts" }} {{ $paginator := .Paginate ($pages.GroupByDate "Jan 2006") }} @@ -167,8 +117,6 @@ Use pagination with any of the [grouping methods]. For example: {{ template "_internal/pagination.html" . }} ``` -[grouping methods]: /quick-reference/page-collections/#group - ## Navigation As shown in the examples above, the easiest way to add navigation between pagers is with Hugo's embedded pagination template: @@ -189,18 +137,14 @@ The `terse` format has fewer controls and page slots, consuming less space when {{ template "_internal/pagination.html" (dict "page" . "format" "terse") }} ``` -{{% note %}} -To override Hugo's embedded pagination template, copy the [source code] to a file with the same name in the `layouts/partials` directory, then call it from your templates using the [`partial`] function: - -`{{ partial "pagination.html" . }}` - -[`partial`]: /functions/partials/include/ -[source code]: {{% eturl pagination %}} -{{% /note %}} +> [!note] +> To override Hugo's embedded pagination template, copy the [source code] to a file with the same name in the `layouts/partials` directory, then call it from your templates using the [`partial`] function: +> +> `{{ partial "pagination.html" . }}` Create custom navigation components using any of the `Pager` methods: -{{< list-pages-in-section path=/methods/pager >}} +{{% list-pages-in-section path=/methods/pager %}} ## Structure @@ -288,3 +232,10 @@ public/ │ └── index.html └── index.html ``` + +[`Paginate`]: /methods/page/paginate/ +[`Paginator`]: /methods/page/paginator/ +[`partial`]: /functions/partials/include/ +[grouping methods]: /quick-reference/page-collections/#group +[grouping methods]: /quick-reference/page-collections/#group +[source code]: {{% eturl pagination %}} diff --git a/content/en/templates/partial.md b/content/en/templates/partial.md index 996914b05..8493a4674 100644 --- a/content/en/templates/partial.md +++ b/content/en/templates/partial.md @@ -1,14 +1,9 @@ --- title: Partial templates description: Partials are smaller, context-aware components in your list and page templates that can be used economically to keep your templating DRY. -categories: [templates] +categories: [] keywords: [] -menu: - docs: - parent: templates - weight: 110 -weight: 110 -toc: true +weight: 100 aliases: [/templates/partials/,/layout/chrome/] --- @@ -39,13 +34,11 @@ All partials are called within your templates using the following pattern: {{ partial "/.html" . }} ``` -{{% note %}} -One of the most common mistakes with new Hugo users is failing to pass a context to the partial call. In the pattern above, note how "the dot" (`.`) is required as the second argument to give the partial context. You can read more about "the dot" in the [Hugo templating introduction](/templates/introduction/#context). -{{% /note %}} +> [!note] +> One of the most common mistakes with new Hugo users is failing to pass a context to the partial call. In the pattern above, note how "the dot" (`.`) is required as the second argument to give the partial context. You can read more about "the dot" in the [Hugo templating introduction](/templates/introduction/#context). -{{% note %}} -`` including `baseof` is reserved. ([#5373](https://github.com/gohugoio/hugo/issues/5373)) -{{% /note %}} +> [!note] +> Do not include the word "baseof" when naming partial templates. The word "baseof" is reserved for base templates. As shown in the above example directory structure, you can nest your directories within `partials` for better source organization. You only need to call the nested partial's path relative to the `partials` directory: @@ -99,9 +92,8 @@ In addition to outputting markup, partials can be used to return a value of any {{ end }} ``` -{{% note %}} -Only one `return` statement is allowed per partial file. -{{% /note %}} +> [!note] +> Only one `return` statement is allowed per partial file. ## Inline partials @@ -126,7 +118,7 @@ The `partialCached` template function provides significant performance gains for The following `header.html` partial template is used for [spf13.com](https://spf13.com/): -{{< code file=layouts/partials/header.html >}} +```go-html-template {file="layouts/partials/header.html"} @@ -141,17 +133,16 @@ The following `header.html` partial template is used for [spf13.com](https://spf {{ partial "head_includes.html" . }} -{{< /code >}} +``` -{{% note %}} -The `header.html` example partial was built before the introduction of block templates to Hugo. Read more on [base templates and blocks](/templates/base/) for defining the outer chrome or shell of your master templates (i.e., your site's head, header, and footer). You can even combine blocks and partials for added flexibility. -{{% /note %}} +> [!note] +> The `header.html` example partial was built before the introduction of block templates to Hugo. Read more on [base templates and blocks](/templates/base/) for defining the outer chrome or shell of your master templates (i.e., your site's head, header, and footer). You can even combine blocks and partials for added flexibility. ### `footer.html` The following `footer.html` partial template is used for [spf13.com](https://spf13.com/): -{{< code file=layouts/partials/footer.html >}} +```go-html-template {file="layouts/partials/footer.html"}

    @@ -161,10 +152,7 @@ The following `footer.html` partial template is used for [spf13.com](https://spf

    -{{< /code >}} +``` [context]: /templates/introduction/ -[customize]: /hugo-modules/theme-components/ -[lookup order]: /templates/lookup-order/ [partialcached]: /functions/partials/includecached/ -[themes]: /themes/ diff --git a/content/en/templates/robots.md b/content/en/templates/robots.md index 0e453c549..2d412d775 100644 --- a/content/en/templates/robots.md +++ b/content/en/templates/robots.md @@ -2,13 +2,9 @@ title: robots.txt template linkTitle: robots.txt templates description: Hugo can generate a customized robots.txt in the same way as any other template. -categories: [templates] +categories: [] keywords: [] -menu: - docs: - parent: templates - weight: 170 -weight: 170 +weight: 180 aliases: [/extras/robots-txt/] --- @@ -20,8 +16,6 @@ enableRobotsTXT = true By default, Hugo generates robots.txt using an [embedded template]. -[embedded template]: {{% eturl robots %}} - ```text User-agent: * ``` @@ -37,24 +31,23 @@ You may overwrite the internal template with a custom template. Hugo selects the ## robots.txt template example -{{< code file=layouts/robots.txt >}} +```text {file="layouts/robots.txt"} User-agent: * {{ range .Pages }} Disallow: {{ .RelPermalink }} {{ end }} -{{< /code >}} +``` This template creates a robots.txt file with a `Disallow` directive for each page on the site. Search engines that honor the Robots Exclusion Protocol will not crawl any page on the site. -{{% note %}} -To create a robots.txt file without using a template: - -1. Set `enableRobotsTXT` to `false` in the site configuration. -1. Create a robots.txt file in the `static` directory. - -Remember that Hugo copies everything in the [`static` directory][static] to the root of `publishDir` (typically `public`) when you build your site. +> [!note] +> To create a robots.txt file without using a template: +> +> 1. Set `enableRobotsTXT` to `false` in the site configuration. +> 1. Create a robots.txt file in the `static` directory. +> +> Remember that Hugo copies everything in the [`static` directory][static] to the root of `publishDir` (typically `public`) when you build your site. +[embedded template]: {{% eturl robots %}} +[site configuration]: /configuration/ [static]: /getting-started/directory-structure/ -{{% /note %}} - -[site configuration]: /getting-started/configuration/ diff --git a/content/en/templates/rss.md b/content/en/templates/rss.md index da7244a94..f387a71e3 100644 --- a/content/en/templates/rss.md +++ b/content/en/templates/rss.md @@ -1,14 +1,9 @@ --- title: RSS templates description: Use the embedded RSS template, or create your own. -categories: [templates] +categories: [] keywords: [] -menu: - docs: - parent: templates - weight: 150 -weight: 150 -toc: true +weight: 140 --- ## Configuration @@ -52,7 +47,7 @@ email = 'jdoe@example.org' To include a feed reference in the `head` element of your rendered pages, place this within the `head` element of your templates: ```go-html-template -{{ with .OutputFormats.Get "rss" -}} +{{ with .OutputFormats.Get "rss" }} {{ printf `` .Rel .MediaType.Type .Permalink site.Title | safeHTML }} {{ end }} ``` @@ -67,9 +62,6 @@ Hugo will render this to: Override Hugo's [embedded RSS template] by creating one or more of your own, following the naming conventions as shown in the [template lookup order]. -[embedded RSS template]: {{% eturl rss %}} -[template lookup order]: /templates/lookup-order/#rss-templates - For example, to use different templates for home, section, taxonomy, and term pages: ```text @@ -82,3 +74,6 @@ layouts/ ``` RSS templates receive the `.Page` and `.Site` objects in context. + +[embedded RSS template]: {{% eturl rss %}} +[template lookup order]: /templates/lookup-order/#rss-templates diff --git a/content/en/templates/section.md b/content/en/templates/section.md index 339fe6389..8bc0f9dab 100644 --- a/content/en/templates/section.md +++ b/content/en/templates/section.md @@ -1,14 +1,9 @@ --- title: Section templates description: Create a section template to list its members. -categories: [templates] +categories: [] keywords: [] -menu: - docs: - parent: templates - weight: 80 -weight: 80 -toc: true +weight: 70 aliases: [/templates/sections/,/templates/section-templates/] --- @@ -22,7 +17,7 @@ See [Template Lookup](/templates/lookup-order/). ## Example: creating a default section template -{{< code file=layouts/_default/section.html >}} +```go-html-template {file="layouts/_default/section.html"} {{ define "main" }}
    {{ .Content }} @@ -37,7 +32,7 @@ See [Template Lookup](/templates/lookup-order/). {{ template "_internal/pagination.html" . }}
    {{ end }} -{{< /code >}} +``` ### Example: using `.Site.GetPage` diff --git a/content/en/templates/shortcode.md b/content/en/templates/shortcode.md index c73874673..711d342cb 100644 --- a/content/en/templates/shortcode.md +++ b/content/en/templates/shortcode.md @@ -1,23 +1,14 @@ --- title: Shortcode templates -description: Create custom shortcodes to simplify and standardize content creation. -categories: [templates] +description: Create custom shortcodes to simplify and standardize content creation. +categories: [] keywords: [] -menu: - docs: - parent: templates - weight: 130 -weight: 130 +weight: 120 aliases: [/templates/shortcode-templates/] -toc: true --- -{{% note %}} -Before creating custom shortcodes, please review the [shortcodes] page in the [content management] section. Understanding the usage details will help you design and create better templates. - -[shortcodes]: /content-management/shortcodes/ -[content management]: /content-management/shortcodes/ -{{% /note %}} +> [!note] +> Before creating custom shortcodes, please review the [shortcodes] page in the [content management] section. Understanding the usage details will help you design and create better templates. ## Introduction @@ -31,8 +22,6 @@ Hugo provides [embedded shortcodes] for many common tasks, but you'll likely nee - Tables - And many other custom elements -[embedded shortcodes]: /shortcodes/ - ## Directory structure Create shortcode templates within the `layouts/shortcodes` directory, either at its root or organized into subdirectories. @@ -81,7 +70,7 @@ foo|json|en|`layouts/shortcodes/foo.json.en.json` Use these methods in your shortcode templates. Refer to each methods's documentation for details and examples. -{{< list-pages-in-section path=/methods/shortcode >}} +{{% list-pages-in-section path=/methods/shortcode %}} ## Examples @@ -91,20 +80,18 @@ These examples range in complexity from simple to moderately advanced, with some Create a shortcode to insert the current year: -{{< code file=layouts/shortcodes/year.html >}} +```go-html-template {file="layouts/shortcodes/year.html"} {{- now.Format "2006" -}} -{{< /code >}} +``` Then call the shortcode from within your markup: -{{< code file=content/example.md >}} +```text {file="content/example.md"} This is {{}}, and look at how far we've come. -{{< /code >}} +``` This shortcode can be used inline or as a block on its own line. If a shortcode might be used inline, remove the surrounding [whitespace] by using [template action](g) delimiters with hyphens. -[whitespace]: /templates/introduction/#whitespace - ### Insert image This example assumes the following content structure, where `content/example/index.md` is a [page bundle](g) containing one or more [page resources](g). @@ -119,19 +106,19 @@ content/ Create a shortcode to capture an image as a page resource, resize it to the given width, convert it to the WebP format, and add an `alt` attribute: -{{< code file=layouts/shortcodes/image.html >}} +```go-html-template {file="layouts/shortcodes/image.html"} {{- with .Page.Resources.Get (.Get "path") }} - {{- with .Process (printf "resize %dx wepb" ($.Get "width")) }} + {{- with .Process (printf "resize %dx wepb" ($.Get "width")) -}} {{ $.Get {{- end }} {{- end -}} -{{< /code >}} +``` Then call the shortcode from within your markup: -{{< code file=content/example/index.md >}} +```text {file="content/example/index.md"} {{}} -{{< /code >}} +``` The example above uses: @@ -139,47 +126,38 @@ The example above uses: - The [`Get`] method to retrieve arguments by name - The `$` to access the template context -[`get`]: /methods/shortcode/get/ -[`with`]: /functions/go-template/with/ - -{{% note %}} -Make sure that you thoroughly understand the concept of context. The most common templating errors made by new users relate to context. - -Read more about context in the [introduction to templating]. - -[introduction to templating]: /templates/introduction/ -{{% /note %}} +> [!note] +> Make sure that you thoroughly understand the concept of context. The most common templating errors made by new users relate to context. +> +> Read more about context in the [introduction to templating]. ### Insert image with error handling The previous example, while functional, silently fails if the image is missing, and does not gracefully exit if a required argument is missing. We'll add error handling to address these issues: -{{< code file=layouts/shortcodes/image.html >}} -{{ with .Get "path" }} +```go-html-template {file="layouts/shortcodes/image.html"} +{{- with .Get "path" }} {{- with $r := $.Page.Resources.Get ($.Get "path") }} {{- with $.Get "width" }} {{- with $r.Process (printf "resize %dx wepb" ($.Get "width" )) }} - {{- $alt := or ($.Get "alt") "" }} + {{- $alt := or ($.Get "alt") "" -}} {{ $alt }} {{- end }} {{- else }} {{- errorf "The %q shortcode requires a 'width' argument: see %s" $.Name $.Position }} {{- end }} {{- else }} - {{ warnf "The %q shortcode was unable to find %s: see %s" $.Name ($.Get "path") $.Position }} + {{- warnf "The %q shortcode was unable to find %s: see %s" $.Name ($.Get "path") $.Position }} {{- end }} {{- else }} - {{ errorf "The %q shortcode requires a 'path' argument: see %s" .Name .Position }} + {{- errorf "The %q shortcode requires a 'path' argument: see %s" .Name .Position }} {{- end -}} -{{< /code >}} +``` This template throws an error and gracefully fails the build if the author neglected to provide a `path` or `width` argument, and it emits a warning if it cannot find the image at the specified path. If the author does not provide an `alt` argument, the `alt` attribute is set to an empty string. The [`Name`] and [`Position`] methods provide helpful context for errors and warnings. For example, a missing `width` argument causes the shortcode to throw this error: -[`name`]: /methods/shortcode/name/ -[`position`]: /methods/shortcode/position/ - ```text ERROR The "image" shortcode requires a 'width' argument: see "/home/user/project/content/example/index.md:7:1" ``` @@ -188,167 +166,146 @@ ERROR The "image" shortcode requires a 'width' argument: see "/home/user/project Shortcode arguments can be [named or positional]. We used named arguments previously; let's explore positional arguments. Here's the named argument version of our example: -[named or positional]: /content-management/shortcodes/#arguments - -{{< code file=content/example/index.md >}} +```text {file="content/example/index.md"} {{}} -{{< /code >}} +``` Here's how to call it with positional arguments: -{{< code file=content/example/index.md >}} +```text {file="content/example/index.md"} {{}} -{{< /code >}} +``` Using the `Get` method with zero-indexed keys, we'll initialize variables with descriptive names in our template: -{{< code file=layouts/shortcodes/image.html >}} -{{- $path := .Get 0 }} -{{- $width := .Get 1 }} -{{- $alt := .Get 2 }} -{{< /code >}} +```go-html-template {file="layouts/shortcodes/image.html"} +{{ $path := .Get 0 }} +{{ $width := .Get 1 }} +{{ $alt := .Get 2 }} +``` -{{% note %}} -Positional arguments work well for frequently used shortcodes with one or two arguments. Since you'll use them often, the argument order will be easy to remember. For less frequently used shortcodes, or those with more than two arguments, named arguments improve readability and reduce the chance of errors. -{{% /note %}} +> [!note] +> Positional arguments work well for frequently used shortcodes with one or two arguments. Since you'll use them often, the argument order will be easy to remember. For less frequently used shortcodes, or those with more than two arguments, named arguments improve readability and reduce the chance of errors. ### Named and positional arguments You can create a shortcode that will accept both named and positional arguments, but not at the same time. Use the [`IsNamedParams`] method to determine whether the shortcode call used named or positional arguments: -{{< code file=layouts/shortcodes/image.html >}} -{{- $path := cond (.IsNamedParams) (.Get "path") (.Get 0) }} -{{- $width := cond (.IsNamedParams) (.Get "width") (.Get 1) }} -{{- $alt := cond (.IsNamedParams) (.Get "alt") (.Get 2) }} -{{< /code >}} +```go-html-template {file="layouts/shortcodes/image.html"} +{{ $path := cond (.IsNamedParams) (.Get "path") (.Get 0) }} +{{ $width := cond (.IsNamedParams) (.Get "width") (.Get 1) }} +{{ $alt := cond (.IsNamedParams) (.Get "alt") (.Get 2) }} +``` This example uses the `cond` alias for the [`compare.Conditional`] function to get the argument by name if `IsNamedParams` returns `true`, otherwise get the argument by position. -[`compare.Conditional`]: /functions/compare/conditional/ -[`IsNamedParams`]: /methods/shortcode/isnamedparams/ - ### Argument collection Use the [`Params`] method to access the arguments as a collection. -[`Params`]: /methods/shortcode/params/ - When using named arguments, the `Params` method returns a map: -{{< code file=content/example/index.md >}} +```text {file="content/example/index.md"} {{}} -{{< /code >}} +``` -{{< code file=layouts/shortcodes/image.html >}} -{{- .Params.path }} → a.jpg -{{- .Params.width }} → 300 -{{- .Params.alt }} → A white kitten -{{< /code >}} +```go-html-template {file="layouts/shortcodes/image.html"} +{{ .Params.path }} → a.jpg +{{ .Params.width }} → 300 +{{ .Params.alt }} → A white kitten +``` When using positional arguments, the `Params` method returns a slice: -{{< code file=content/example/index.md >}} +```text {file="content/example/index.md"} {{}} -{{< /code >}} +``` -{{< code file=layouts/shortcodes/image.html >}} -{{- index .Params 0 }} → a.jpg -{{- index .Params 1 }} → 300 -{{- index .Params 1 }} → A white kitten -{{< /code >}} +```go-html-template {file="layouts/shortcodes/image.html"} +{{ index .Params 0 }} → a.jpg +{{ index .Params 1 }} → 300 +{{ index .Params 1 }} → A white kitten +``` Combine the `Params` method with the [`collections.IsSet`] function to determine if a parameter is set, even if its value is falsy. -[`collections.IsSet`]: /functions/collections/isset/ - ### Inner content -Extract the content enclosed within shortcode tags using the [`Inner`] method. This example demonstrates how to pass both content and a title to a shortcode. The shortcode then generates a `div` element containing an `h2` element (displaying the title) and the provided content. +Extract the content enclosed within shortcode tags using the [`Inner`] method. This example demonstrates how to pass both content and a title to a shortcode. The shortcode then generates a `div` element containing an `h2` element (displaying the title) and the provided content. -[`Inner`]: /methods/shortcode/inner/ - -{{< code file=content/example.md >}} +```text {file="content/example.md"} {{}} This is a **bold** word, and this is an _emphasized_ word. {{}} -{{< /code >}} +``` -{{< code file=layouts/shortcodes/contrived.html >}} +```go-html-template {file="layouts/shortcodes/contrived.html"}

    {{ .Get "title" }}

    {{ .Inner | .Page.RenderString }}
    -{{< /code >}} +``` The preceding example called the shortcode using [standard notation], requiring us to process the inner content with the [`RenderString`] method to convert the Markdown to HTML. This conversion is unnecessary when calling a shortcode using [Markdown notation]. -[`RenderString`]: /methods/page/renderstring/ -[markdown notation]: /content-management/shortcodes/#markdown-notation -[standard notation]: /content-management/shortcodes/#standard-notation - ### Nesting The [`Parent`] method provides access to the parent shortcode context when the shortcode in question is called within the context of a parent shortcode. This provides an inheritance model. -[`Parent`]: /methods/shortcode/parent/ - The following example is contrived but demonstrates the concept. Assume you have a `gallery` shortcode that expects one named `class` argument: -{{< code file=layouts/shortcodes/gallery.html >}} +```go-html-template {file="layouts/shortcodes/gallery.html"}
    {{ .Inner }}
    -{{< /code >}} +``` You also have an `img` shortcode with a single named `src` argument that you want to call inside of `gallery` and other shortcodes, so that the parent defines the context of each `img`: -{{< code file=layouts/shortcodes/img.html >}} +```go-html-template {file="layouts/shortcodes/img.html"} {{ $src := .Get "src" }} {{ with .Parent }} {{ else }} {{ end }} -{{< /code >}} +``` You can then call your shortcode in your content as follows: -{{< code file=content/example.md >}} +```text {file="content/example.md"} {{}} {{}} {{}} {{}} {{}} -{{< /code >}} - +``` This will output the following HTML. Note how the first two `img` shortcodes inherit the `class` value of `content-gallery` set with the call to the parent `gallery`, whereas the third `img` only uses `src`: ```html
    - - + +
    ``` ### Other examples -For guidance, consider examining Hugo's embedded shortcodes. The source code, available on [GitHub], can provide a useful model. - -[GitHub]: https://github.com/gohugoio/hugo/tree/master/tpl/tplimpl/embedded/templates/shortcodes +For guidance, consider examining Hugo's embedded shortcodes. The source code, available on [GitHub], can provide a useful model. ## Detection The [`HasShortcode`] method allows you to check if a specific shortcode has been called on a page. For example, consider a custom audio shortcode: -{{< code file=content/example.md >}} +```text {file="content/example.md"} {{}} -{{< /code >}} +``` You can use the `HasShortcode` method in your base template to conditionally load CSS if the audio shortcode was used on the page: -{{< code file=layouts/_default/baseof.html >}} +```go-html-template {file="layouts/_default/baseof.html"} ... {{ if .HasShortcode "audio" }} @@ -356,6 +313,26 @@ You can use the `HasShortcode` method in your base template to conditionally loa {{ end }} ... -{{< /code >}} +``` +[`collections.IsSet`]: /functions/collections/isset/ +[`compare.Conditional`]: /functions/compare/conditional/ +[`Get`]: /methods/shortcode/get/ [`HasShortcode`]: /methods/page/hasshortcode/ +[`Inner`]: /methods/shortcode/inner/ +[`IsNamedParams`]: /methods/shortcode/isnamedparams/ +[`Name`]: /methods/shortcode/name/ +[`Params`]: /methods/shortcode/params/ +[`Parent`]: /methods/shortcode/parent/ +[`Position`]: /methods/shortcode/position/ +[`RenderString`]: /methods/page/renderstring/ +[`with`]: /functions/go-template/with/ +[content management]: /content-management/shortcodes/ +[embedded shortcodes]: /shortcodes/ +[GitHub]: https://github.com/gohugoio/hugo/tree/master/tpl/tplimpl/embedded/templates/shortcodes +[introduction to templating]: /templates/introduction/ +[Markdown notation]: /content-management/shortcodes/#markdown-notation +[named or positional]: /content-management/shortcodes/#arguments +[shortcodes]: /content-management/shortcodes/ +[standard notation]: /content-management/shortcodes/#standard-notation +[whitespace]: /templates/introduction/#whitespace diff --git a/content/en/templates/single.md b/content/en/templates/single.md index f6292ca03..6f244ef10 100644 --- a/content/en/templates/single.md +++ b/content/en/templates/single.md @@ -1,14 +1,9 @@ --- title: Single templates description: Create a single template to render a single page. -categories: [templates] +categories: [] keywords: [] -menu: - docs: - parent: templates - weight: 70 -weight: 70 -toc: true +weight: 60 aliases: [/layout/content/,/templates/single-page-templates/] --- @@ -16,12 +11,12 @@ The single template below inherits the site's shell from the [base template]. [base template]: /templates/types/ -{{< code file=layouts/_default/single.html >}} +```go-html-template {file="layouts/_default/single.html"} {{ define "main" }}

    {{ .Title }}

    {{ .Content }} {{ end }} -{{< /code >}} +``` Review the [template lookup order] to select a template path that provides the desired level of specificity. @@ -29,7 +24,7 @@ Review the [template lookup order] to select a template path that provides the d The single template below inherits the site's shell from the base template, and renders the page title, creation date, content, and a list of associated terms in the "tags" taxonomy. -{{< code file=layouts/_default/single.html >}} +```go-html-template {file="layouts/_default/single.html"} {{ define "main" }}

    {{ .Title }}

    @@ -53,4 +48,4 @@ The single template below inherits the site's shell from the base template, and
    {{ end }} -{{< /code >}} +``` diff --git a/content/en/templates/sitemap.md b/content/en/templates/sitemap.md index b21372040..bf0850eef 100644 --- a/content/en/templates/sitemap.md +++ b/content/en/templates/sitemap.md @@ -1,14 +1,9 @@ --- title: Sitemap templates description: Hugo provides built-in sitemap templates. -categories: [templates] +categories: [] keywords: [] -menu: - docs: - parent: templates - weight: 140 -weight: 140 -toc: true +weight: 130 aliases: [/layout/sitemap/,/templates/sitemap-template/] --- @@ -23,26 +18,9 @@ With a multilingual project, Hugo generates: - A sitemap.xml file in the root of each site (language) using the [embedded sitemap template] - A sitemap.xml file in the root of the [`publishDir`] using the [embedded sitemapindex template] -[embedded sitemap template]: {{% eturl sitemap %}} -[embedded sitemapindex template]: {{% eturl sitemapindex %}} - ## Configuration -These are the default sitemap configuration values. They apply to all pages unless overridden in front matter. - -{{< code-toggle config=sitemap />}} - -changefreq -: (`string`) How frequently a page is likely to change. Valid values are `always`, `hourly`, `daily`, `weekly`, `monthly`, `yearly`, and `never`. With the default value of `""` Hugo will omit this field from the sitemap. See [details](https://www.sitemaps.org/protocol.html#changefreqdef). - -disable {{< new-in 0.125.0 />}} -: (`bool`) Whether to disable page inclusion. Default is `false`. Set to `true` in front matter to exclude the page. - -filename -: (`string`) The name of the generated file. Default is `sitemap.xml`. - -priority -: (`float`) The priority of a page relative to any other page on the site. Valid values range from 0.0 to 1.0. With the default value of `-1` Hugo will omit this field from the sitemap. See [details](https://www.sitemaps.org/protocol.html#priority). +See [configure sitemap](/configuration/sitemap). ## Override default values @@ -78,5 +56,7 @@ You may disable sitemap generation in your site configuration: disableKinds = ['sitemap'] {{}} -[`publishDir`]: /getting-started/configuration#publishdir +[`publishDir`]: /configuration/all/#publishdir +[embedded sitemap template]: {{% eturl sitemap %}} +[embedded sitemapindex template]: {{% eturl sitemapindex %}} [sitemap protocol]: https://www.sitemaps.org/protocol.html diff --git a/content/en/templates/taxonomy.md b/content/en/templates/taxonomy.md index f9f28ee57..96c93ec95 100644 --- a/content/en/templates/taxonomy.md +++ b/content/en/templates/taxonomy.md @@ -1,14 +1,9 @@ --- title: Taxonomy templates description: Create a taxonomy template to render a list of terms. -categories: [templates] +categories: [] keywords: [] -menu: - docs: - parent: templates - weight: 90 -weight: 90 -toc: true +weight: 80 aliases: [/taxonomies/displaying/,/templates/terms/,/indexes/displaying/,/taxonomies/templates/,/indexes/ordering/, /templates/taxonomies/, /templates/taxonomy-templates/] --- @@ -16,7 +11,7 @@ The [taxonomy](g) template below inherits the site's shell from the [base templa [base template]: /templates/types/ -{{< code file=layouts/_default/taxonomy.html >}} +```go-html-template {file="layouts/_default/taxonomy.html"} {{ define "main" }}

    {{ .Title }}

    {{ .Content }} @@ -24,7 +19,7 @@ The [taxonomy](g) template below inherits the site's shell from the [base templa

    {{ .LinkTitle }}

    {{ end }} {{ end }} -{{< /code >}} +``` Review the [template lookup order] to select a template path that provides the desired level of specificity. @@ -69,7 +64,7 @@ Once we have the `Taxonomy` object, we can call any of its [methods], allowing u The taxonomy template below inherits the site's shell from the base template, and renders a list of terms in the current taxonomy. Hugo sorts the list alphabetically by term, and displays the number of pages associated with each term. -{{< code file=layouts/_default/taxonomy.html >}} +```go-html-template {file="layouts/_default/taxonomy.html"} {{ define "main" }}

    {{ .Title }}

    {{ .Content }} @@ -77,13 +72,13 @@ The taxonomy template below inherits the site's shell from the base template, an

    {{ .Page.LinkTitle }} ({{ .Count }})

    {{ end }} {{ end }} -{{< /code >}} +``` ## Sort by term count The taxonomy template below inherits the site's shell from the base template, and renders a list of terms in the current taxonomy. Hugo sorts the list by the number of pages associated with each term, and displays the number of pages associated with each term. -{{< code file=layouts/_default/taxonomy.html >}} +```go-html-template {file="layouts/_default/taxonomy.html"} {{ define "main" }}

    {{ .Title }}

    {{ .Content }} @@ -91,7 +86,7 @@ The taxonomy template below inherits the site's shell from the base template, an

    {{ .Page.LinkTitle }} ({{ .Count }})

    {{ end }} {{ end }} -{{< /code >}} +``` ## Include content links @@ -102,7 +97,7 @@ The [`Alphabetical`] and [`ByCount`] methods used in the previous examples retur The taxonomy template below inherits the site's shell from the base template, and renders a list of terms in the current taxonomy. Hugo sorts the list by the number of pages associated with each term, displays the number of pages associated with each term, then lists the content to which each term is assigned. -{{< code file=layouts/_default/taxonomy.html >}} +```go-html-template {file="layouts/_default/taxonomy.html"} {{ define "main" }}

    {{ .Title }}

    {{ .Content }} @@ -115,7 +110,7 @@ The taxonomy template below inherits the site's shell from the base template, an {{ end }} {{ end }} -{{< /code >}} +``` ## Display metadata @@ -150,7 +145,7 @@ affiliation = "University of Chicago" Then create a taxonomy template specific to the "authors" taxonomy: -{{< code file=layouts/authors/taxonomy.html >}} +```go-html-template {file="layouts/authors/taxonomy.html"} {{ define "main" }}

    {{ .Title }}

    {{ .Content }} @@ -164,6 +159,6 @@ Then create a taxonomy template specific to the "authors" taxonomy: {{ end }} {{ end }} {{ end }} -{{< /code >}} +``` In the example above we list each author including their affiliation and portrait. diff --git a/content/en/templates/term.md b/content/en/templates/term.md index 07b8ef29a..cf1097e86 100644 --- a/content/en/templates/term.md +++ b/content/en/templates/term.md @@ -1,21 +1,16 @@ --- title: Term templates description: Create a term template to render a list of pages associated with the current term. -categories: [templates] +categories: [] keywords: [] -menu: - docs: - parent: templates - weight: 100 -weight: 100 -toc: true +weight: 90 --- The [term](g) template below inherits the site's shell from the [base template], and renders a list of pages associated with the current term. [base template]: /templates/types/ -{{< code file=layouts/_default/term.html >}} +```go-html-template {file="layouts/_default/term.html"} {{ define "main" }}

    {{ .Title }}

    {{ .Content }} @@ -23,7 +18,7 @@ The [term](g) template below inherits the site's shell from the [base template],

    {{ .LinkTitle }}

    {{ end }} {{ end }} -{{< /code >}} +``` Review the [template lookup order] to select a template path that provides the desired level of specificity. @@ -93,7 +88,7 @@ affiliation = "University of Chicago" Then create a term template specific to the "authors" taxonomy: -{{< code file=layouts/authors/term.html >}} +```go-html-template {file="layouts/authors/term.html"} {{ define "main" }}

    {{ .Title }}

    Affiliation: {{ .Params.affiliation }}

    @@ -107,6 +102,6 @@ Then create a term template specific to the "authors" taxonomy:

    {{ .LinkTitle }}

    {{ end }} {{ end }} -{{< /code >}} +``` In the example above we display the author with their affiliation and portrait, then a list of associated content. diff --git a/content/en/templates/types/index.md b/content/en/templates/types.md similarity index 77% rename from content/en/templates/types/index.md rename to content/en/templates/types.md index 8369917bf..b44d3eb47 100644 --- a/content/en/templates/types/index.md +++ b/content/en/templates/types.md @@ -1,20 +1,12 @@ --- title: Template types -linkTitle: Template types description: Create templates of different types to render your content, resources, and data. -categories: [templates] +categories: [] keywords: [] -menu: - docs: - parent: templates - weight: 30 weight: 30 -toc: true aliases: ['/templates/lists/'] --- -[![structural diagram of a website](site-hierarchy.svg)](site-hierarchy.svg) - ## Structure Create templates in the `layouts` directory in the root of your project. @@ -45,11 +37,8 @@ layouts/ Hugo's [template lookup order] determines the template path, allowing you to create unique templates for any page. -[template lookup order]: /templates/lookup-order/ - -{{% note %}} -You must have thorough understanding of the template lookup order when creating templates. Template selection is based on template type, page kind, content type, section, language, and output format. -{{% /note %}} +> [!note] +> You must have thorough understanding of the template lookup order when creating templates. Template selection is based on template type, page kind, content type, section, language, and output format. The purpose of each template type is described below. @@ -59,10 +48,7 @@ Base templates reduce duplicate code by wrapping other templates within a shell. For example, the base template below calls the [partial] function to include partial templates for the `head`, `header`, and `footer` elements of each page, and it uses the [block] function to include `home`, `single`, `section`, `taxonomy`, and `term` templates within the `main` element of each page. -[block]: /functions/go-template/block/ -[partial]: /functions/partials/include/ - -{{< code file=layouts/_default/baseof.html >}} +```go-html-template {file="layouts/_default/baseof.html"} @@ -80,24 +66,24 @@ For example, the base template below calls the [partial] function to include par -{{< /code >}} +``` Learn more about [base templates](/templates/base/). ## Home -A home page template is used to render your site's home page, and is the only template required for a single-page website. For example, the home page template below inherits the site's shell from the base template and renders the home page content, such as a list of other pages. +A home page template is used to render your site's home page, and is the only template required for a single-page website. For example, the home page template below inherits the site's shell from the base template and renders the home page content, such as a list of other pages. -{{< code file=layouts/_default/home.html >}} +```go-html-template {file="layouts/_default/home.html"} {{ define "main" }} {{ .Content }} {{ range site.RegularPages }}

    {{ .LinkTitle }}

    {{ end }} {{ end }} -{{< /code >}} +``` -{{% include "templates/_common/filter-sort-group.md" %}} +{{% include "/_common/filter-sort-group.md" %}} Learn more about [home page templates](/templates/home/). @@ -107,12 +93,12 @@ A single template renders a single page. For example, the single template below inherits the site's shell from the base template, and renders the title and content of each page. -{{< code file=layouts/_default/single.html >}} +```go-html-template {file="layouts/_default/single.html"} {{ define "main" }}

    {{ .Title }}

    {{ .Content }} {{ end }} -{{< /code >}} +``` Learn more about [single templates](/templates/single/). @@ -122,7 +108,7 @@ A section template typically renders a list of pages within a section. For example, the section template below inherits the site's shell from the base template, and renders a list of pages in the current section. -{{< code file=layouts/_default/section.html >}} +```go-html-template {file="layouts/_default/section.html"} {{ define "main" }}

    {{ .Title }}

    {{ .Content }} @@ -130,9 +116,9 @@ For example, the section template below inherits the site's shell from the base

    {{ .LinkTitle }}

    {{ end }} {{ end }} -{{< /code >}} +``` -{{% include "templates/_common/filter-sort-group.md" %}} +{{% include "/_common/filter-sort-group.md" %}} Learn more about [section templates](/templates/section/). @@ -142,7 +128,7 @@ A taxonomy template renders a list of terms in a [taxonomy](g). For example, the taxonomy template below inherits the site's shell from the base template, and renders a list of terms in the current taxonomy. -{{< code file=layouts/_default/taxonomy.html >}} +```go-html-template {file="layouts/_default/taxonomy.html"} {{ define "main" }}

    {{ .Title }}

    {{ .Content }} @@ -150,9 +136,9 @@ For example, the taxonomy template below inherits the site's shell from the base

    {{ .LinkTitle }}

    {{ end }} {{ end }} -{{< /code >}} +``` -{{% include "templates/_common/filter-sort-group.md" %}} +{{% include "/_common/filter-sort-group.md" %}} Learn more about [taxonomy templates](/templates/taxonomy/). @@ -162,7 +148,7 @@ A term template renders a list of pages associated with a [term](g). For example, the term template below inherits the site's shell from the base template, and renders a list of pages associated with the current term. -{{< code file=layouts/_default/term.html >}} +```go-html-template {file="layouts/_default/term.html"} {{ define "main" }}

    {{ .Title }}

    {{ .Content }} @@ -170,9 +156,9 @@ For example, the term template below inherits the site's shell from the base tem

    {{ .LinkTitle }}

    {{ end }} {{ end }} -{{< /code >}} +``` -{{% include "templates/_common/filter-sort-group.md" %}} +{{% include "/_common/filter-sort-group.md" %}} Learn more about [term templates](/templates/term/). @@ -180,17 +166,14 @@ Learn more about [term templates](/templates/term/). A partial template is typically used to render a component of your site, though you may also create partial templates that return values. -{{% note %}} -Unlike other template types, you cannot create partial templates to target a particular page kind, content type, section, language, or output format. Partial templates do not follow Hugo's [template lookup order]. - -[template lookup order]: /templates/lookup-order/ -{{% /note %}} +> [!note] +> Unlike other template types, you cannot create partial templates to target a particular page kind, content type, section, language, or output format. Partial templates do not follow Hugo's [template lookup order]. For example, the partial template below renders copyright information. -{{< code file=layouts/partials/footer.html >}} +```go-html-template {file="layouts/partials/footer.html"}

    Copyright {{ now.Year }}. All rights reserved.

    -{{< /code >}} +``` Learn more about [partial templates](/templates/partial/). @@ -201,11 +184,9 @@ A content view template is similar to a partial template, invoked by calling the - Automatically inherit the context of the current page - Follow a lookup order allowing you to target a given content type or section -[`Render`]: /methods/page/render/ - For example, the home template below inherits the site's shell from the base template, and renders a card component for each page within the "articles" section of your site. -{{< code file=layouts/_default/home.html >}} +```go-html-template {file="layouts/_default/home.html"} {{ define "main" }} {{ .Content }}
      @@ -214,14 +195,14 @@ For example, the home template below inherits the site's shell from the base tem {{ end }}
    {{ end }} -{{< /code >}} +``` -{{< code file=layouts/articles/card.html >}} +```go-html-template {file="layouts/articles/card.html"}

    {{ .LinkTitle }}

    {{ .Summary }}
    -{{< /code >}} +``` Learn more about [content view templates](/templates/content-view/). @@ -231,7 +212,7 @@ A render hook template overrides the conversion of Markdown to HTML. For example, the render hook template below adds a `rel` attribute to external links. -{{< code file=layouts/_default/_markup/render-link.html >}} +```go-html-template {file="layouts/_default/_markup/render-link.html"} {{- $u := urls.Parse .Destination -}} {{- /* chomp trailing newline */ -}} -{{< /code >}} +``` Learn more about [render hook templates](/render-hooks/). @@ -250,17 +231,17 @@ A shortcode template is used to render a component of your site. Unlike partial For example, the shortcode template below renders an audio element from a [global resource](g). -{{< code file=layouts/shortcodes/audio.html >}} +```go-html-template {file="layouts/shortcodes/audio.html"} {{ with resources.Get (.Get "src") }} {{ end }} -{{< /code >}} +``` Then call the shortcode from within markup: -{{< code file=content/example.md >}} +```text {file="content/example.md"} {{}} -{{< /code >}} +``` Learn more about [shortcode templates](/templates/shortcode/). @@ -272,3 +253,9 @@ Use other specialized templates to create: - [RSS feeds](/templates/rss/) - [404 error pages](/templates/404/) - [robots.txt files](/templates/robots/) + +[`Render`]: /methods/page/render/ +[block]: /functions/go-template/block/ +[partial]: /functions/partials/include/ +[template lookup order]: /templates/lookup-order/ +[template lookup order]: /templates/lookup-order/ diff --git a/content/en/templates/types/site-hierarchy.svg b/content/en/templates/types/site-hierarchy.svg deleted file mode 100644 index 3c744871b..000000000 --- a/content/en/templates/types/site-hierarchy.svg +++ /dev/null @@ -1 +0,0 @@ - \ No newline at end of file diff --git a/content/en/tools/_index.md b/content/en/tools/_index.md index a4df23800..3acc287ae 100644 --- a/content/en/tools/_index.md +++ b/content/en/tools/_index.md @@ -1,20 +1,7 @@ --- title: Developer tools - description: Third-party tools to help you create and manage sites. categories: [] keywords: [] -menu: - docs: - identifier: developer-tools-in-this-section - parent: developer-tools - weight: 10 weight: 10 --- - -One of Hugo's greatest strengths is its passionate---and always evolving---developer community. With the exception of the `highlight` shortcode mentioned in [Syntax Highlighting][syntax], the tools and other projects featured in this section are offerings from both commercial services and open-source projects, many of which are developed by Hugo developers just like you. - -[See the popularity of Hugo compared with other static site generators.][staticgen] - -[staticgen]: https://staticgen.com -[syntax]: /content-management/syntax-highlighting/ diff --git a/content/en/tools/editors.md b/content/en/tools/editors.md index b2e2cc47b..c375fcba8 100644 --- a/content/en/tools/editors.md +++ b/content/en/tools/editors.md @@ -1,15 +1,9 @@ --- title: Editor plugins -linkTitle: Editor plugins description: The Hugo community uses a wide range of tools and has developed plugins for some of the most popular text editors to help automate parts of your workflow. -categories: [developer tools] -keywords: [editor,plugin] -menu: - docs: - parent: developer-tools - weight: 20 -weight: 20 -toc: true +categories: [] +keywords: [] +weight: 10 --- ## Visual Studio Code diff --git a/content/en/tools/front-ends.md b/content/en/tools/front-ends.md index 217f96e2c..0c52a4687 100644 --- a/content/en/tools/front-ends.md +++ b/content/en/tools/front-ends.md @@ -2,14 +2,9 @@ title: Front-end interfaces linkTitle: Front-ends description: Do you prefer a graphical user interface over a text editor? Give these front-ends a try. -categories: [developer tools] -keywords: [frontend, gui] -menu: - docs: - parent: developer-tools - weight: 30 -weight: 30 -toc: true +categories: [] +keywords: [] +weight: 20 aliases: [/tools/frontends/] --- diff --git a/content/en/tools/migrations.md b/content/en/tools/migrations.md index 0fc78153f..103e28b9e 100644 --- a/content/en/tools/migrations.md +++ b/content/en/tools/migrations.md @@ -2,14 +2,9 @@ title: Migrate to Hugo linkTitle: Migrations description: A list of community-developed tools for migrating from your existing static site generator or content management system to Hugo. -categories: [developer tools] -keywords: [migrations,jekyll,wordpress,drupal,ghost,contentful] -menu: - docs: - parent: developer-tools - weight: 50 -weight: 50 -toc: true +categories: [] +keywords: [] +weight: 40 aliases: [/developer-tools/migrations/, /developer-tools/migrated/] --- @@ -49,7 +44,7 @@ Alternatively, you can use the [Jekyll import command](/commands/hugo_import_jek : A small utility written in Java that exports the entire WordPress site from the database and resource (e.g., images) files stored locally or remotely. Therefore, migration from the backup files is possible. Supports merging multiple WordPress sites into a single Hugo site. [wp2hugo](https://github.com/ashishb/wp2hugo) -: A Go-based CLI tool to migrate WordPress website to Hugo while preserving original URLs, GUIDs (for feeds), image URLs, code highlights, table of contents, YouTube embeds, Google Maps embeds, and original WordPress navigation categories. +: A Go-based CLI tool to migrate WordPress website to Hugo while preserving original URLs, GUIDs (for feeds), image URLs, code highlights, table of contents, YouTube embeds, Google Maps embeds, and original WordPress navigation categories. ## Medium @@ -68,7 +63,7 @@ Alternatively, you can use the [Jekyll import command](/commands/hugo_import_jek : Export all your Tumblr content to Hugo Markdown files with preserved original formatting. [Tumblr to Hugo](https://github.com/jipiboily/tumblr-to-hugo) -: A migration tool that converts each of your Tumblr posts to a content file with a proper title and path. It also generates a CSV file to help you set up URL redirects. +: A migration tool that converts each of your Tumblr posts to a content file with a proper title and path. It also generates a CSV file to help you set up URL redirects. ## Drupal diff --git a/content/en/tools/other.md b/content/en/tools/other.md index 8edfc4258..489d78506 100644 --- a/content/en/tools/other.md +++ b/content/en/tools/other.md @@ -2,13 +2,9 @@ title: Other community projects linkTitle: Other projects description: Some interesting projects developed by the Hugo community that don't quite fit into our other developer tool categories. -categories: [developer tools] -keywords: [frontend,gui] -menu: - docs: - parent: developer-tools - weight: 60 -weight: 60 +categories: [] +keywords: [] +weight: 50 --- And for all the other community projects around Hugo: diff --git a/content/en/tools/search.md b/content/en/tools/search.md index 152774304..2c392c75a 100644 --- a/content/en/tools/search.md +++ b/content/en/tools/search.md @@ -2,14 +2,9 @@ title: Search tools linkTitle: Search description: See some of the open-source and commercial search options for your newly created Hugo website. -categories: [developer tools] -keywords: [search] -menu: - docs: - parent: developer-tools - weight: 40 -weight: 40 -toc: true +categories: [] +keywords: [] +weight: 30 --- A static website with a dynamic search function? Yes, Hugo provides an alternative to embeddable scripts from Google or other search engines for static websites. Hugo allows you to provide your visitors with a custom search function by indexing your content files directly. @@ -48,8 +43,8 @@ A static website with a dynamic search function? Yes, Hugo provides an alternati ## Commercial -[Algolia](https://www.algolia.com/) -: Algolia's Search API makes it easy to deliver a great search experience in your apps and websites. Algolia Search provides hosted full-text, numerical, faceted, and geolocalized search. +[Algolia DocSearch](https://docsearch.algolia.com/) +: Algolia DocSearch is free for public technical documentation sites and easy to set up. For other use cases, [Algolia's Search API](https://www.algolia.com) makes it easy to deliver a great search experience in your apps and websites. Algolia Search provides hosted full-text, numerical, faceted, and geolocalized search. [Bonsai](https://www.bonsai.io) : Bonsai is a fully-managed hosted Elasticsearch service that is fast, reliable, and simple to set up. Easily ingest your docs from Hugo into Elasticsearch following [this guide from the docs](https://bonsai.io/docs/hugo). diff --git a/content/en/troubleshooting/_index.md b/content/en/troubleshooting/_index.md index a113fa9cf..fd51b4fc8 100644 --- a/content/en/troubleshooting/_index.md +++ b/content/en/troubleshooting/_index.md @@ -1,16 +1,8 @@ --- title: Troubleshooting - description: Use these techniques when troubleshooting your site. categories: [] keywords: [] -menu: - docs: - identifier: troubleshooting-in-this-section - parent: troubleshooting - weight: 10 weight: 10 aliases: [/templates/template-debugging/] --- - -Use these techniques when troubleshooting your site. diff --git a/content/en/troubleshooting/audit/index.md b/content/en/troubleshooting/audit/index.md index e0de0d5df..2efad55e3 100644 --- a/content/en/troubleshooting/audit/index.md +++ b/content/en/troubleshooting/audit/index.md @@ -2,20 +2,15 @@ title: Site audit linkTitle: Audit description: Run this audit before deploying your production site. -categories: [troubleshooting] +categories: [] keywords: [] -menu: - docs: - parent: troubleshooting - weight: 20 -weight: 20 --- There are several conditions that can produce errors in your published site which are not detected during the build. Run this audit before your final build. -{{< code copy=true >}} +```text {copy=true} HUGO_MINIFY_TDEWOLFF_HTML_KEEPCOMMENTS=true HUGO_ENABLEMISSINGTRANSLATIONPLACEHOLDERS=true hugo && grep -inorE "<\!-- raw HTML omitted -->|ZgotmplZ|\[i18n\]|\(\)|(<nil>)|hahahugo" public/ -{{< /code >}} +``` _Tested with GNU Bash 5.1 and GNU grep 3.7._ diff --git a/content/en/troubleshooting/deprecation.md b/content/en/troubleshooting/deprecation.md index 5dd9f3fa6..f2e5259a6 100644 --- a/content/en/troubleshooting/deprecation.md +++ b/content/en/troubleshooting/deprecation.md @@ -1,13 +1,8 @@ --- title: Deprecation description: The Hugo project follows a formal and consistent process to deprecate functions, methods, and configuration settings. -categories: [troubleshooting] +categories: [] keywords: [] -menu: - docs: - parent: troubleshooting - weight: 50 -weight: 50 --- When a project _deprecates_ something, they are telling its users: diff --git a/content/en/troubleshooting/faq.md b/content/en/troubleshooting/faq.md index 2edb309be..6992af5d3 100644 --- a/content/en/troubleshooting/faq.md +++ b/content/en/troubleshooting/faq.md @@ -2,133 +2,112 @@ title: Frequently asked questions linkTitle: FAQs description: These questions are frequently asked by new users. -categories: [troubleshooting] -keywords: [faq] -menu: - docs: - parent: troubleshooting - weight: 70 -weight: 70 +categories: [] +keywords: [] --- -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. These are just a few of the questions most frequently asked by new users. -###### An error message indicates that a feature is not available. Why? {#feature-not-available} +An error message indicates that a feature is not available. Why? +: + {{% include "/_common/installation/01-editions.md" %}} -{{% include "installation/_common/01-editions.md" %}} + When you attempt to use a feature that is not available in the edition that you installed, Hugo throws this error: -When you attempt to use a feature that is not available in the edition that you installed, Hugo throws this error: + ```go-html-template + this feature is not available in this edition of Hugo + ``` -```go-html-template -this feature is not available in this edition of Hugo -``` + To resolve, install a different edition based on the feature table above. See the [installation] section for details. -To resolve, install a different edition based on the feature table above. See the [installation] section for details. - -###### Why do I see "Page Not Found" when visiting the home page? - -In the `content/_index.md` file: +Why do I see "Page Not Found" when visiting the home page? +: In the `content/_index.md` file: - Is `draft` set to `true`? - Is the `date` in the future? - Is the `publishDate` in the future? - Is the `expiryDate` in the past? -If the answer to any of these questions is yes, either change the field values, or use one of these command line flags: `--buildDrafts`, `--buildFuture`, or `--buildExpired`. + If the answer to any of these questions is yes, either change the field values, or use one of these command line flags: `--buildDrafts`, `--buildFuture`, or `--buildExpired`. -###### Why is a given page not published? +Why is a given page not published? +: In the `content/section/page.md` file, or in the `content/section/page/index.md` file: -In the `content/section/page.md` file, or in the `content/section/page/index.md` file: + - Is `draft` set to `true`? + - Is the `date` in the future? + - Is the `publishDate` in the future? + - Is the `expiryDate` in the past? -- Is `draft` set to `true`? -- Is the `date` in the future? -- Is the `publishDate` in the future? -- Is the `expiryDate` in the past? + If the answer to any of these questions is yes, either change the field values, or use one of these command line flags: `--buildDrafts`, `--buildFuture`, or `--buildExpired`. -If the answer to any of these questions is yes, either change the field values, or use one of these command line flags: `--buildDrafts`, `--buildFuture`, or `--buildExpired`. +Why can't I see any of a page's descendants? +: You may have an `index.md` file instead of an `_index.md` file. See [details](/content-management/page-bundles/). -###### Why can't I see any of a page's descendants? +What is the difference between an `index.md` file and an `_index.md` file? +: A directory with an `index.md file` is a [leaf bundle](g). A directory with an `_index.md` file is a [branch bundle](g). See [details](/content-management/page-bundles/). -You may have an `index.md` file instead of an `_index.md` file. See [details](/content-management/page-bundles/). +Why is my partial template not rendered as expected? +: You may have neglected to pass the required [context](g) when calling the partial. For example: -###### What is the difference between an `index.md` file and an `_index.md` file? + ```go-html-template + {{/* incorrect */}} + {{ partial "_internal/pagination.html" }} -A directory with an `index.md file` is a [leaf bundle](g). A directory with an `_index.md` file is a [branch bundle](g). See [details](/content-management/page-bundles/). + {{/* correct */}} + {{ partial "_internal/pagination.html" . }} + ``` -###### Why is my partial template not rendered as expected? +In a template, what's the difference between `:=` and `=` when assigning values to variables? +: Use `:=` to initialize a variable, and use `=` to assign a value to a variable that has been previously initialized. See [details](https://pkg.go.dev/text/template#hdr-Variables). -You may have neglected to pass the required [context](g) when calling the partial. For example: +When I paginate a list page, why is the page collection not filtered as specified? +: You are probably invoking the [`Paginate`] or [`Paginator`] method more than once on the same page. See [details](/templates/pagination/). -```go-html-template -{{/* incorrect */}} -{{ partial "_internal/pagination.html" }} +Why are there two ways to call a shortcode? +: Use the `{{%/* shortcode */%}}` notation if the shortcode template, or the content between the opening and closing shortcode tags, contains Markdown. Otherwise use the\ +`{{}}` notation. See [details](/content-management/shortcodes/#notation). -{{/* correct */}} -{{ partial "_internal/pagination.html" . }} -``` +Can I use environment variables to control configuration? +: Yes. See [details](/configuration/introduction/#environment-variables). -###### In a template, what's the difference between `:=` and `=` when assigning values to variables? +Why am I seeing inconsistent output from one build to the next? +: The most common causes are page collisions (publishing two pages to the same path) and the effects of concurrency. Use the `--printPathWarnings` command line flag to check for page collisions, and create a topic on the [forum] if you suspect concurrency problems. -Use `:=` to initialize a variable, and use `=` to assign a value to a variable that has been previously initialized. See [details](https://pkg.go.dev/text/template#hdr-Variables). +Why isn't Hugo's development server detecting file changes? +: In its default configuration, Hugo's file watcher may not be able detect file changes when: -###### When I paginate a list page, why is the page collection not filtered as specified? + - Running Hugo within Windows Subsystem for Linux (WSL/WSL2) with project files on a Windows partition + - Running Hugo locally with project files on a removable drive + - Running Hugo locally with project files on a storage server accessed via the NFS, SMB, or CIFS protocols -You are probably invoking the [`Paginate`] or [`Paginator`] method more than once on the same page. See [details](/templates/pagination/). + In these cases, instead of monitoring native file system events, use the `--poll` command line flag. For example, to poll the project files every 700 milliseconds, use `--poll 700ms`. -###### Why are there two ways to call a shortcode? +Why is my page Scratch or Store missing a value? +: The [`Scratch`] and [`Store`] methods on a `Page` object allow you to create a [scratch pad](g) on the given page to store and manipulate data. Values are often set within a shortcode, a partial template called by a shortcode, or by a Markdown render hook. In all three cases, the scratch pad values are not determinate until Hugo renders the page content. -Use the `{{%/* shortcode */%}}` notation if the shortcode template, or the content between the opening and closing shortcode tags, contains Markdown. Otherwise use the\ -`{{}}` notation. See [details](/content-management/shortcodes/). + If you need to access a scratch pad value from a parent template, and the parent template has not yet rendered the page content, you can trigger content rendering by assigning the returned value to a [noop](g) variable: -###### Can I use environment variables to control configuration? + ```go-html-template + {{ $noop := .Content }} + {{ .Store.Get "mykey" }} + ``` -Yes. See [details](/getting-started/configuration/#configure-with-environment-variables). + You can trigger content rendering with other methods as well. See next FAQ. -###### Why am I seeing inconsistent output from one build to the next? +Which page methods trigger content rendering? +: The following methods on a `Page` object trigger content rendering: `Content`, `ContentWithoutSummary`, `FuzzyWordCount`, `Len`, `Plain`, `PlainWords`, `ReadingTime`, `Summary`, `Truncated`, and `WordCount`. -The most common causes are page collisions (publishing two pages to the same path) and the effects of concurrency. Use the `--printPathWarnings` command line flag to check for page collisions, and create a topic on the [forum] if you suspect concurrency problems. - -###### Why isn't Hugo's development server detecting file changes? - -In its default configuration, Hugo's file watcher may not be able detect file changes when: - -- Running Hugo within Windows Subsystem for Linux (WSL/WSL2) with project files on a Windows partition -- Running Hugo locally with project files on a removable drive -- Running Hugo locally with project files on a storage server accessed via the NFS, SMB, or CIFS protocols - -In these cases, instead of monitoring native file system events, use the `--poll` command line flag. For example, to poll the project files every 700 milliseconds, use `--poll 700ms`. - -###### Why is my page Scratch or Store missing a value? - -The [`Scratch`] and [`Store`] methods on a `Page` object allow you to create a [scratch pad](g) on the given page to store and manipulate data. Values are often set within a shortcode, a partial template called by a shortcode, or by a Markdown render hook. In all three cases, the scratch pad values are not determinate until Hugo renders the page content. - -If you need to access a scratch pad value from a parent template, and the parent template has not yet rendered the page content, you can trigger content rendering by assigning the returned value to a [noop](g) variable: - -```go-html-template -{{ $noop := .Content }} -{{ .Store.Get "mykey" }} -``` - -You can trigger content rendering with other methods as well. See next FAQ. - -[`Scratch`]: /methods/page/scratch -[`Store`]: /methods/page/store - -###### Which page methods trigger content rendering? - -The following methods on a `Page` object trigger content rendering: `Content`, `ContentWithoutSummary`, `FuzzyWordCount`, `Len`, `Plain`, `PlainWords`, `ReadingTime`, `Summary`, `Truncated`, and `WordCount`. - -{{% note %}} -For other questions please visit the [forum]. 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. - -[forum]: https://discourse.gohugo.io -[requesting help]: https://discourse.gohugo.io/t/requesting-help/9132 -{{% /note %}} +> [!note] +> For other questions please visit the [forum]. 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. [`Paginate`]: /methods/page/paginate/ [`Paginator`]: /methods/page/paginator/ +[`Scratch`]: /methods/page/scratch +[`Store`]: /methods/page/store +[forum]: https://discourse.gohugo.io [forum]: https://discourse.gohugo.io [installation]: /installation/ [requesting help]: https://discourse.gohugo.io/t/requesting-help/9132 +[requesting help]: https://discourse.gohugo.io/t/requesting-help/9132 diff --git a/content/en/troubleshooting/inspection.md b/content/en/troubleshooting/inspection.md index e9fc8ed0f..dc662243a 100644 --- a/content/en/troubleshooting/inspection.md +++ b/content/en/troubleshooting/inspection.md @@ -2,13 +2,8 @@ title: Data inspection linkTitle: Inspection description: Use template functions to inspect values and data structures. -categories: [troubleshooting] +categories: [] keywords: [] -menu: - docs: - parent: troubleshooting - weight: 40 -weight: 40 --- Use the [`debug.Dump`] function to inspect a data structure: diff --git a/content/en/troubleshooting/logging.md b/content/en/troubleshooting/logging.md index fc6838069..0cd25d1ae 100644 --- a/content/en/troubleshooting/logging.md +++ b/content/en/troubleshooting/logging.md @@ -1,14 +1,8 @@ --- title: Logging description: Enable logging to inspect events while building your site. -categories: [troubleshooting] +categories: [] keywords: [] -menu: - docs: - parent: troubleshooting - weight: 30 -weight: 30 -toc: true --- ## Command line @@ -20,40 +14,39 @@ Hugo has four logging levels: error : Display error messages only. -```sh -hugo --logLevel error -``` + ```sh + hugo --logLevel error + ``` warn : Display warning and error messages. -```sh -hugo --logLevel warn -``` + ```sh + hugo --logLevel warn + ``` info : Display information, warning, and error messages. -```sh -hugo --logLevel info -``` + ```sh + hugo --logLevel info + ``` debug : Display debug, information, warning, and error messages. -```sh -hugo --logLevel debug -``` + ```sh + hugo --logLevel debug + ``` -{{% note %}} -If you do not specify a logging level with the `--logLevel` flag, warnings and errors are always displayed. -{{% /note %}} +> [!note] +> If you do not specify a logging level with the `--logLevel` flag, warnings and errors are always displayed. ## Template functions You can also use template functions to print warnings or errors to the console. These functions are typically used to report data validation errors, missing files, etc. -{{< list-pages-in-section path=/functions/fmt filter=functions_fmt_logging filterType=include >}} +{{% list-pages-in-section path=/functions/fmt filter=functions_fmt_logging filterType=include %}} ## LiveReload diff --git a/content/en/troubleshooting/performance.md b/content/en/troubleshooting/performance.md index 2cf64477a..e366eba81 100644 --- a/content/en/troubleshooting/performance.md +++ b/content/en/troubleshooting/performance.md @@ -1,14 +1,8 @@ --- title: Performance description: Tools and suggestions for evaluating and improving performance. -categories: [troubleshooting] +categories: [] keywords: [] -menu: - docs: - parent: troubleshooting - weight: 60 -weight: 60 -toc: true aliases: [/troubleshooting/build-performance/] --- @@ -24,9 +18,8 @@ For example, with Microsoft Defender Antivirus: Then type `hugo.exe` add press the **Add** button. -{{% note %}} -Virus scanning exclusions are common, but use caution when changing these settings. See the [Microsoft Defender Antivirus documentation](https://support.microsoft.com/en-us/topic/how-to-add-a-file-type-or-process-exclusion-to-windows-security-e524cbc2-3975-63c2-f9d1-7c2eb5331e53) for details. -{{% /note %}} +> [!note] +> Virus scanning exclusions are common, but use caution when changing these settings. See the [Microsoft Defender Antivirus documentation] for details. Other virus scanners have similar exclusion mechanisms. See their respective documentation. @@ -92,21 +85,20 @@ total count template : The path to the template, relative to the `layouts` directory. -[`partial`]: /functions/partials/include/ -[`partialCached`]: /functions/partials/includecached/ - -{{% note %}} -Hugo builds pages in parallel where multiple pages are generated simultaneously. Because of this parallelism, the sum of "cumulative duration" values is usually greater than the actual time it takes to build a site. -{{% /note %}} +> [!note] +> Hugo builds pages in parallel where multiple pages are generated simultaneously. Because of this parallelism, the sum of "cumulative duration" values is usually greater than the actual time it takes to build a site. ## Caching Some partial templates such as sidebars or menus are executed many times during a site build. Depending on the content within the partial template and the desired output, the template may benefit from caching to reduce the number of executions. The [`partialCached`] template function provides caching capabilities for partial templates. -{{% note %}} -Note that you can create cached variants of each partial by passing additional arguments to `partialCached` beyond the initial context. See the `partialCached` documentation for more details. -{{% /note %}} +> [!note] +> Note that you can create cached variants of each partial by passing additional arguments to `partialCached` beyond the initial context. See the `partialCached` documentation for more details. ## Timers Use the `debug.Timer` function to determine execution time for a block of code, useful for finding performance bottlenecks in templates. See [details](/functions/debug/timer/). + +[`partial`]: /functions/partials/include/ +[`partialCached`]: /functions/partials/includecached/ +[Microsoft Defender Antivirus documentation]: https://support.microsoft.com/en-us/topic/how-to-add-a-file-type-or-process-exclusion-to-windows-security-e524cbc2-3975-63c2-f9d1-7c2eb5331e53 diff --git a/data/docs.yaml b/data/docs.yaml index dc61df0e8..0db4c7fe9 100644 --- a/data/docs.yaml +++ b/data/docs.yaml @@ -958,6 +958,73 @@ chroma: - Aliases: - zig Name: Zig + styles: + - abap + - algol + - algol_nu + - arduino + - autumn + - average + - base16-snazzy + - borland + - bw + - catppuccin-frappe + - catppuccin-latte + - catppuccin-macchiato + - catppuccin-mocha + - colorful + - doom-one + - doom-one2 + - dracula + - emacs + - evergarden + - friendly + - fruity + - github + - github-dark + - gruvbox + - gruvbox-light + - hr_high_contrast + - hrdark + - igor + - lovelace + - manni + - modus-operandi + - modus-vivendi + - monokai + - monokailight + - murphy + - native + - nord + - nordic + - onedark + - onesenterprise + - paraiso-dark + - paraiso-light + - pastie + - perldoc + - pygments + - rainbow_dash + - rose-pine + - rose-pine-dawn + - rose-pine-moon + - rrt + - solarized-dark + - solarized-dark256 + - solarized-light + - swapoff + - tango + - tokyonight-day + - tokyonight-moon + - tokyonight-night + - tokyonight-storm + - trac + - vim + - vs + - vulcan + - witchhazel + - xcode + - xcode-dark config: HTTPCache: cache: @@ -1019,6 +1086,13 @@ config: cascade: [] cleanDestinationDir: false contentDir: content + contentTypes: + text/asciidoc: {} + text/html: {} + text/markdown: {} + text/org: {} + text/pandoc: {} + text/rst: {} copyright: "" dataDir: data defaultContentLanguage: en @@ -1154,8 +1228,9 @@ config: attribute: block: false title: true + autoDefinitionTermID: false autoHeadingID: true - autoHeadingIDType: github + autoIDType: github wrapStandAloneImageWithinParagraph: true renderHooks: image: @@ -1400,6 +1475,7 @@ config: xml: keepWhitespace: false module: + auth: "" hugoVersion: extended: false max: "" @@ -1737,7 +1813,9 @@ config: headers: null redirects: - force: false - from: '**' + from: /** + fromHeaders: null + fromRe: "" status: 404 to: /404.html services: @@ -1795,6 +1873,8 @@ config_helpers: _merge: none cascade: _merge: none + contenttypes: + _merge: none deployment: _merge: none frontmatter: diff --git a/data/keywords.yaml b/data/keywords.yaml new file mode 100644 index 000000000..106929884 --- /dev/null +++ b/data/keywords.yaml @@ -0,0 +1,12 @@ +# We use the front matter keywords field to determine related content. To +# ensure consistency, during site build we validate each keyword against the +# entries in data/keywords.yaml. + +# As of March 5, 2025, this feature is experimental, pending usability +# assessment. We anticipate that the number of additions to data/keywords.yaml +# will decrease over time, though the initial implementation will require some +# effort. + +- menu +- resource +- highlight diff --git a/data/page_filters.yaml b/data/page_filters.yaml index a4969e9b7..82de6168e 100644 --- a/data/page_filters.yaml +++ b/data/page_filters.yaml @@ -6,7 +6,7 @@ # # For example: # -# {{< list-pages-in-section path=/functions/images filter=functions_images_no_filters filterType=exclude >}} +# {{% list-pages-in-section path=/functions/images filter=functions_images_no_filters filterType=exclude %}} functions_fmt_logging: - /functions/fmt/errorf diff --git a/hugo.toml b/hugo.toml index c0094725f..e8373a87c 100644 --- a/hugo.toml +++ b/hugo.toml @@ -1,8 +1,6 @@ baseURL = "https://gohugo.io/" defaultContentLanguage = "en" enableEmoji = true -ignoreLogs = ["error-missing-instagram-accesstoken"] -languageCode = "en-us" pluralizeListTitles = false timeZone = "Europe/Oslo" title = "Hugo" @@ -10,105 +8,6 @@ title = "Hugo" # We do redirects via Netlify's _redirects file, generated by Hugo (see "outputs" below). disableAliases = true -[pagination] - pagerSize = 100 - -[services.googleAnalytics] - ID = 'G-MBZGKNMDWC' - -[outputs] - home = ["html", "rss", "redir", "headers"] - section = ["html"] - page = ["html"] - taxonomy = ["html"] - term = ["html"] - -[params] - description = "The world’s fastest framework for building websites" - ghrepo = "https://github.com/gohugoio/hugoDocs/" - - [params.render_hooks.link] - errorLevel = 'warning' # ignore (default), warning, or error (fails the build) - -[languages] - [languages.en] - languageName = "English" - weight = 1 - -[security] - enableInlineShortcodes = false - [security.funcs] - getenv = ['^HUGO_', '^REPOSITORY_URL$', '^BRANCH$'] - [security.http] - methods = ['(?i)GET|POST'] - urls = ['.*'] - -[outputFormats] - [outputFormats.redir] - mediatype = "text/netlify" - baseName = "_redirects" - isPlainText = true - [outputFormats.headers] - mediatype = "text/netlify" - baseName = "_headers" - isPlainText = true - notAlternative = true - -[markup] - [markup.highlight] - style = 'solarized-dark' - lineNumbersInTable = true - noClasses = false - wrapperClass = 'highlight not-prose' - - [markup.goldmark.renderer] - hardWraps = false - unsafe = false - xhtml = false - - [markup.goldmark.extensions] - definitionList = true - footnote = true - linkify = true - strikethrough = true - table = true - taskList = true - typographer = true - - [markup.goldmark.extensions.passthrough] - enable = true - - [markup.goldmark.extensions.passthrough.delimiters] - block = [['\[', '\]'], ['$$', '$$']] - inline = [['\(', '\)']] - - [markup.goldmark.parser] - autoHeadingID = true - autoHeadingIDType = "github" - - [markup.goldmark.parser.attribute] - block = true - title = true - -[mediaTypes] - [mediaTypes."text/netlify"] - delimiter = "" - -[module] - [module.hugoVersion] - min = "0.141.0" - [[module.mounts]] - source = "assets" - target = "assets" - [[module.mounts]] - lang = 'en' - source = 'content/en' - target = 'content' - [[module.mounts]] - source = "hugo_stats.json" - target = "assets/notwatching/hugo_stats.json" - disableWatch = true - [build] [build.buildStats] disableIDs = true @@ -120,55 +19,153 @@ disableAliases = true source = "(postcss|tailwind)\\.config\\.js" target = "css" +[caches] + [caches.images] + dir = ":cacheDir/images" + maxAge = "1440h" + [caches.getresource] + dir = ':cacheDir/:project' + maxAge = "1h" + +[cascade] + [cascade.params] + hide_in_this_section = true + show_publish_date = true + [cascade.target] + kind = 'page' + path = '{/news/**}' + +[frontmatter] + date = ['date'] # do not add publishdate; it will affect page sorting + expiryDate = ['expirydate'] + lastmod = [':git', 'lastmod', 'publishdate', 'date'] + publishDate = ['publishdate', 'date'] + +[languages] + [languages.en] + languageCode = "en-US" + languageName = "English" + weight = 1 + +[markup] + [markup.goldmark] + [markup.goldmark.extensions] + [markup.goldmark.extensions.typographer] + disable = false + [markup.goldmark.extensions.passthrough] + enable = true + [markup.goldmark.extensions.passthrough.delimiters] + block = [['\[', '\]'], ['$$', '$$']] + inline = [['\(', '\)']] + [markup.goldmark.parser] + autoDefinitionTermID = true + [markup.goldmark.parser.attribute] + block = true + [markup.highlight] + lineNumbersInTable = false + noClasses = false + style = 'solarized-dark' + wrapperClass = 'highlight not-prose' + +[mediaTypes] + [mediaTypes."text/netlify"] + delimiter = "" + +[module] + [module.hugoVersion] + min = "0.144.0" + [[module.mounts]] + source = "assets" + target = "assets" + [[module.mounts]] + lang = 'en' + source = 'content/en' + target = 'content' + [[module.mounts]] + disableWatch = true + source = "hugo_stats.json" + target = "assets/notwatching/hugo_stats.json" + +[outputFormats] + [outputFormats.redir] + baseName = "_redirects" + isPlainText = true + mediatype = "text/netlify" + [outputFormats.headers] + baseName = "_headers" + isPlainText = true + mediatype = "text/netlify" + notAlternative = true + +[outputs] + home = ["html", "rss", "redir", "headers"] + page = ["html"] + section = ["html"] + taxonomy = ["html"] + term = ["html"] + +[params] + description = "The world’s fastest framework for building websites" + ghrepo = "https://github.com/gohugoio/hugoDocs/" + [params.render_hooks.link] + errorLevel = 'warning' # ignore (default), warning, or error (fails the build) + +[related] + includeNewer = true + threshold = 80 + toLower = true + [[related.indices]] + name = 'keywords' + weight = 1 + +[security] + [security.funcs] + getenv = ['^HUGO_', '^REPOSITORY_URL$', '^BRANCH$'] + [server] [[server.headers]] for = "/*" - [server.headers.values] X-Frame-Options = "DENY" X-XSS-Protection = "1; mode=block" X-Content-Type-Options = "nosniff" Referrer-Policy = "no-referrer" - [[server.headers]] for = "/**.{css,js}" -[minify] - [minify.tdewolff] - [minify.tdewolff.html] - keepSpecialComments = true - keepWhitespace = false +[services] + [services.googleAnalytics] + ID = 'G-MBZGKNMDWC' + +[taxonomies] +category = 'categories' ######## GLOBAL ITEMS TO BE SHARED WITH THE HUGO SITES ######## [menus] [[menus.global]] - name = 'News' - weight = 1 identifier = 'news' + name = 'News' pageRef = '/news/' - + weight = 1 [[menus.global]] - name = 'Docs' - weight = 5 identifier = 'docs' + name = 'Docs' url = '/documentation/' - + weight = 5 [[menus.global]] - name = 'Themes' - weight = 10 identifier = 'themes' + name = 'Themes' url = 'https://themes.gohugo.io/' - + weight = 10 [[menus.global]] - name = 'Community' - weight = 150 identifier = 'community' + name = 'Community' post = 'external' url = 'https://discourse.gohugo.io/' - + weight = 150 [[menus.global]] - name = 'GitHub' - weight = 200 identifier = 'github' + name = 'GitHub' post = 'external' url = 'https://github.com/gohugoio/hugo' + weight = 200 diff --git a/layouts/404.html b/layouts/404.html index bb92ea160..6d962ffc0 100644 --- a/layouts/404.html +++ b/layouts/404.html @@ -7,7 +7,7 @@ gopher + class="w-32 ml-12 float-right">
    diff --git a/layouts/_default/_markup/render-blockquote.html b/layouts/_default/_markup/render-blockquote.html new file mode 100644 index 000000000..98019e12d --- /dev/null +++ b/layouts/_default/_markup/render-blockquote.html @@ -0,0 +1,33 @@ +{{- if eq .Type "alert" }} + {{- $alerts := dict + "caution" (dict "color" "red" "icon" "exclamation-triangle") + "important" (dict "color" "blue" "icon" "exclamation-circle") + "note" (dict "color" "blue" "icon" "information-circle") + "tip" (dict "color" "green" "icon" "light-bulb") + "warning" (dict "color" "orange" "icon" "exclamation-triangle") + }} + + {{- $alertTypes := slice }} + {{- range $k, $_ := $alerts }} + {{- $alertTypes = $alertTypes | append $k }} + {{- end }} + {{- $alertTypes = $alertTypes | sort }} + + {{- $alertType := strings.ToLower .AlertType }} + {{- if in $alertTypes $alertType }} + {{- partial "layouts/blocks/alert.html" (dict + "color" (or ((index $alerts $alertType).color) "blue") + "icon" (or ((index $alerts $alertType).icon) "information-circle") + "text" .Text + "title" .AlertTitle + "class" .Attributes.class + ) + }} + {{- else }} + {{- errorf `Invalid blockquote alert type. Received %s. Expected one of %s (case-insensitive). See %s.` .AlertType (delimit $alertTypes ", " ", or ") .Page.String }} + {{- end }} +{{- else }} +
    + {{ .Text }} +
    +{{- end }} diff --git a/layouts/_default/_markup/render-codeblock.html b/layouts/_default/_markup/render-codeblock.html new file mode 100644 index 000000000..13725ffcd --- /dev/null +++ b/layouts/_default/_markup/render-codeblock.html @@ -0,0 +1,98 @@ +{{/* prettier-ignore-start */}} +{{/* +Renders a highlighted code block using the given options and attributes. + +In addition to the options available to the transform.Highlight function, you +may also specify the following parameters: + +@param {bool} [copy=false] Whether to display a copy-to-clipboard button. +@param {string} [file] The file name to display above the rendered code. +@param {bool} [details=false] Whether to wrap the highlighted code block within a details element. +@param {bool} [open=false] Whether to initially display the content of the details element. +@param {string} [summary=Details] The content of the details summary element rendered from Markdown to HTML. + +@returns {template.HTML} + +@examples + + ```go + fmt.Println("Hello world!") + ``` + + ```go {linenos=true file="layouts/index.html" copy=true} + fmt.Println("Hello world!") + ``` +*/}} +{{/* prettier-ignore-end */}} + +{{- $copy := false }} +{{- $file := or .Attributes.file "" }} +{{- $details := false }} +{{- $open := "" }} +{{- $summary := or .Attributes.summary "Details" | .Page.RenderString }} +{{- $ext := strings.TrimPrefix "." (path.Ext $file) }} +{{- $lang := or .Type $ext "text" }} +{{- if in (slice "html" "gotmpl") $lang }} + {{- $lang = "go-html-template" }} +{{- end }} +{{- if eq $lang "md" }} + {{- $lang = "text" }} +{{- end }} + +{{- with .Attributes.copy }} + {{- if in (slice true "true" 1) . }} + {{- $copy = true }} + {{- else if in (slice false "false" 0) . }} + {{- $copy = false }} + {{- end }} +{{- end }} + +{{- with .Attributes.details }} + {{- if in (slice true "true" 1) . }} + {{- $details = true }} + {{- else if in (slice false "false" 0) . }} + {{- $details = false }} + {{- end }} +{{- end }} + +{{- with .Attributes.open }} + {{- if in (slice true "true" 1) . }} + {{- $open = "open" }} + {{- else if in (slice false "false" 0) . }} + {{- $open = "" }} + {{- end }} +{{- end }} + +{{- if $details }} +
    + {{ $summary }} +{{- end }} + +
    + {{- $fileSelectClass := "select-none" }} + {{- if $copy }} + {{- $fileSelectClass = "select-text" }} + + + + {{- end }} + {{- with $file }} +
    + {{ . }} +
    + {{- end }} + +
    + {{- transform.Highlight (strings.TrimSpace .Inner) $lang .Options }} +
    +
    + +{{- if $details }} +
    +{{- end }} diff --git a/layouts/_default/_markup/render-heading.html b/layouts/_default/_markup/render-heading.html deleted file mode 100644 index c0e6c63ec..000000000 --- a/layouts/_default/_markup/render-heading.html +++ /dev/null @@ -1,10 +0,0 @@ -{{ .Text | safeHTML }} - {{- if in (slice 2 3 4 6) .Level }}{{" " -}} -     - - - - - -{{- end -}} - diff --git a/layouts/_default/_markup/render-link.html b/layouts/_default/_markup/render-link.html index 726610258..88e3cbee5 100644 --- a/layouts/_default/_markup/render-link.html +++ b/layouts/_default/_markup/render-link.html @@ -1,3 +1,4 @@ +{{/* prettier-ignore-start */ -}} {{- /* Last modified: 2025-01-19T14:44:56-08:00 */}} {{- /* @@ -75,8 +76,8 @@ either of these shortcodes in conjunction with this render hook. @context {string} Title The link title. @returns {template.html} -*/}} - +*/ -}} +{{/* prettier-ignore-end */ -}} {{- /* Initialize. */}} {{- $renderHookName := "link" }} @@ -185,24 +186,25 @@ either of these shortcodes in conjunction with this render hook. {{- end }} {{- /* Render anchor element. */ -}} -{{ .Text }} + >{{ .Text }} {{- define "partials/inline/h-rh-l/validate-fragment.html" }} {{- /* - Validates the fragment portion of a link destination. + Validates the fragment portion of a link destination. - @context {string} contentPath The page containing the link. - @context {string} errorLevel The error level when unable to resolve destination; ignore (default), warning, or error. - @context {page} page The page corresponding to the link destination - @context {struct} parsedURL The link destination parsed by urls.Parse. - @context {string} renderHookName The name of the render hook. + @context {string} contentPath The page containing the link. + @context {string} errorLevel The error level when unable to resolve destination; ignore (default), warning, or error. + @context {page} page The page corresponding to the link destination + @context {struct} parsedURL The link destination parsed by urls.Parse. + @context {string} renderHookName The name of the render hook. */}} {{- /* Initialize. */}} @@ -248,20 +250,20 @@ either of these shortcodes in conjunction with this render hook. {{- define "partials/inline/h-rh-l/get-glossary-link-attributes.html" }} {{- /* - Returns the anchor element attributes for a link to the given glossary term. + Returns the anchor element attributes for a link to the given glossary term. - It first checks for the existence of a glossary page for the given term. If - no page is found, it then checks for a glossary page for the singular form of - the term. If neither page exists it throws a warning or error dependent on - the errorLevel setting + It first checks for the existence of a glossary page for the given term. If + no page is found, it then checks for a glossary page for the singular form of + the term. If neither page exists it throws a warning or error dependent on + the errorLevel setting - The returned href attribute does not point to the glossary term page. - Instead, via its fragment, it points to an entry on the glossary page. + The returned href attribute does not point to the glossary term page. + Instead, via its fragment, it points to an entry on the glossary page. - @context {string} contentPath The page containing the link. - @context {string} errorLevel The error level when unable to resolve destination; ignore (default), warning, or error. - @context {string} renderHookName The name of the render hook. - @context {string} text The link text. + @context {string} contentPath The page containing the link. + @context {string} errorLevel The error level when unable to resolve destination; ignore (default), warning, or error. + @context {string} renderHookName The name of the render hook. + @context {string} text The link text. */}} {{- /* Get context.. */}} @@ -289,6 +291,7 @@ either of these shortcodes in conjunction with this render hook. "localized" "localization" "paginating" "paginate" "walking" "walk" + "ci/cd" "cicd" }} {{- /* Verify that a glossary term page exists for the given term. */}} @@ -308,7 +311,7 @@ either of these shortcodes in conjunction with this render hook. {{- end }} {{- /* Create the href attribute. */}} - {{- $href := ""}} + {{- $href := "" }} {{- if $termActual }} {{- $href = fmt.Printf "%s#%s" $glossaryPage.RelPermalink (anchorize $termActual) }} {{- end }} diff --git a/layouts/_default/_markup/render-passthrough.html b/layouts/_default/_markup/render-passthrough.html new file mode 100644 index 000000000..0ed001133 --- /dev/null +++ b/layouts/_default/_markup/render-passthrough.html @@ -0,0 +1,9 @@ +{{- $opts := dict "output" "htmlAndMathml" "displayMode" (eq .Type "block") }} +{{- with try (transform.ToMath .Inner $opts) }} + {{- with .Err }} + {{ errorf "Unable to render mathematical markup to HTML using the transform.ToMath function. The KaTeX display engine threw the following error: %s: see %s." . $.Position }} + {{- else }} + {{- .Value }} + {{- $.Page.Store.Set "hasMath" true }} + {{- end }} +{{- end -}} diff --git a/layouts/_default/_markup/render-table.html b/layouts/_default/_markup/render-table.html new file mode 100644 index 000000000..7f3a88601 --- /dev/null +++ b/layouts/_default/_markup/render-table.html @@ -0,0 +1,31 @@ +
    + + + {{- range .THead }} + + {{- range . }} + + {{- end }} + + {{- end }} + + + {{- range .TBody }} + + {{- range . }} + + {{- end }} + + {{- end }} + +
    + {{- .Text -}} +
    + {{- .Text -}} +
    +
    diff --git a/layouts/_default/baseof.html b/layouts/_default/baseof.html index f6e281455..1f4952146 100644 --- a/layouts/_default/baseof.html +++ b/layouts/_default/baseof.html @@ -1,14 +1,9 @@ + lang="{{ or site.Language.LanguageCode `en-US` }}"> - + {{ .Title }} @@ -19,7 +14,7 @@ + content="{{ .Description | default site.Params.description }}"> {{ partial "layouts/head/head-js.html" . }} {{ with (templates.Defer (dict "key" "global")) }} {{ $t := debug.Timer "tailwindcss" }} @@ -34,9 +29,16 @@ {{ end }} {{ $t.Stop }} {{ end }} + {{ $noop := .WordCount }} + {{ if .Page.Store.Get "hasMath" }} + + {{ end }} {{ partial "layouts/head/head.html" . }} - + {{ partial "layouts/hooks/body-start.html" . }} {{/* Layout. */}} {{ block "header" . }} @@ -46,7 +48,8 @@ {{ end }}
    + class="flex-1 mx-auto lg:mx-0 w-full max-w-3x lg:max-w-3x pt-8 lg:pt-14 pb-20 px-main print:pt-0"> + {{ partial "layouts/hooks/body-main-start.html" . }} {{ block "main" . }}{{ end }}
    {{ block "rightsidebar" . }} @@ -58,6 +61,8 @@
    {{/* Common icons. */}} {{ partial "layouts/icons.html" . }} + {{/* Common templates. */}} + {{ partial "layouts/templates.html" . }} {{/* Footer. */}} {{ block "footer" . }} {{ partial "layouts/footer.html" . }} diff --git a/layouts/_default/list.html b/layouts/_default/list.html index 76513788f..b049b6da9 100644 --- a/layouts/_default/list.html +++ b/layouts/_default/list.html @@ -1,15 +1,12 @@ {{ define "main" }} {{ $pages := "" }} - {{ $showDate := false }} {{ if .IsPage }} {{/* We currently have a slightly odd content structure with no top level /docs section. */}} {{ $pages = .CurrentSection.Pages }} {{ else }} + {{ $pages = .Pages }} {{ if eq .Section "news" }} - {{ $pages = partial "news/get-news-items.html" . }} - {{ $showDate = true }} - {{ else }} - {{ $pages = .Pages }} + {{ $pages = $pages.ByPublishDate.Reverse }} {{ end }} {{ end }} @@ -23,23 +20,25 @@ {{ end }} - {{ if $showDate }} -

    - {{ .Date.Format "January 2, 2006" }} -

    + href="{{ or .Params.permalink .RelPermalink }}"> + {{ if .Params.show_publish_date }} + {{ with .PublishDate }} +

    + {{ partial "layouts/date.html" . }} +

    + {{ end }} {{ end }}

    {{ .LinkTitle }}

    - {{ with .Params.action.signatures }} + {{ with .Params.functions_and_methods.signatures }} {{/* Set in functions and methods pages. */}} {{ with $signature := index . 0 }} - {{ if $.Params.action.returnType }} - {{ $signature = printf "%s ⟼ %s" $signature $.context.Params.action.returnType }} + {{ if $.Params.functions_and_methods.returnType }} + {{ $signature = printf "%s ⟼ %s" $signature $.context.Params.functions_and_methods.returnType }} {{ end }}
    @@ -56,6 +55,9 @@ {{ (or .Params.description .Summary) | plainify | safeHTML }} {{ end }}

    + {{ if and hugo.IsDevelopment site.Params.debug.display_page_metadata }} + {{ partial "helpers/debug/list-item-metadata.html" . }} + {{ end }}     {{ end }}
    diff --git a/layouts/_default/list.rss.xml b/layouts/_default/list.rss.xml new file mode 100644 index 000000000..90fa22148 --- /dev/null +++ b/layouts/_default/list.rss.xml @@ -0,0 +1,33 @@ +{{- printf "" | safeHTML }} + + + Hugo News + Recent news about Hugo, a static site generator written in Go, optimized for speed and designed for flexibility. + {{ .Permalink }} + Hugo {{ hugo.Version }} + {{ or site.Language.LanguageCode site.Language.Lang }} + {{- with site.Copyright }} + {{ . }} + {{- end }} + {{- with .OutputFormats.Get "rss" }} + {{ printf "" .Permalink .MediaType | safeHTML }} + {{- end }} + {{- $limit := cond (gt site.Config.Services.RSS.Limit 0) site.Config.Services.RSS.Limit 999 }} + {{- $pages := "" }} + {{- with site.GetPage "/news" }} + {{- $pages = .Pages.ByPublishDate.Reverse | first $limit }} + {{- else }} + {{- errorf "The list.rss.xml layout was unable to find the 'news' page." }} + {{- end }} + {{ (index $pages 0).PublishDate.Format "Mon, 02 Jan 2006 15:04:05 -0700" | safeHTML }} + {{- range $pages }} + + {{ .Title }} + {{ or .Params.permalink .Permalink }} + {{ .PublishDate.Format "Mon, 02 Jan 2006 15:04:05 -0700" | safeHTML }} + {{ or .Params.permalink .Permalink }} + {{ .Summary | transform.XMLEscape | safeHTML }} + + {{- end }} + + diff --git a/layouts/_default/single.html b/layouts/_default/single.html index b6587633b..2e9e4f379 100644 --- a/layouts/_default/single.html +++ b/layouts/_default/single.html @@ -1,14 +1,21 @@ {{ define "main" }} {{ $ttop := debug.Timer "single" }} -
    +
    {{ partial "layouts/docsheader.html" . }} -
    +
    {{ with .Params.description }}
    {{ . | markdownify }}
    {{ end }} - + {{ if .Params.show_publish_date }} + {{ with .PublishDate }} +

    + {{ partial "layouts/date.html" . }} +

    + {{ end }} + {{ end }} {{ $t := debug.Timer "single.categories" }} {{ $categories := .GetTerms "categories" }} {{ with $categories }} @@ -41,7 +48,7 @@ {{ end }} {{ $t.Stop }} - {{ if .Params.action.signatures }} + {{ if .Params.functions_and_methods.signatures }}
    {{- partial "docs/functions-signatures.html" . -}} {{- partial "docs/functions-return-type.html" . -}} @@ -67,5 +74,7 @@ {{ partial "layouts/in-this-section.html" . }} {{ end }} {{ $related }} - {{ $toc }} + {{ if $.Store.Get "hasToc" }} + {{ $toc }} + {{ end }} {{ end }} diff --git a/layouts/index.html b/layouts/index.html index 50dc2fbf3..392f66cd8 100644 --- a/layouts/index.html +++ b/layouts/index.html @@ -1,9 +1,9 @@ {{ define "main" }}
    {{ partial "layouts/home/opensource.html" . }} -
    +
    {{ partial "layouts/home/sponsors.html" (dict "ctx" . "gtag" "home" ) }} -
    +
    {{ partial "layouts/home/features.html" . }}
    {{ end }} @@ -15,7 +15,7 @@ Hugo Logo + class="w-64 aspect-3/1 mx-auto mb-8">

    The world’s fastest framework for building websites diff --git a/layouts/index.redir b/layouts/index.redir index 2dfd2bc0f..bb72f96e5 100644 --- a/layouts/index.redir +++ b/layouts/index.redir @@ -1,6 +1,6 @@ # Netlify redirects. See https://www.netlify.com/docs/redirects/ -{{ range $p := .Site.Pages -}} +{{ range $p := .Site.Pages -}} {{ range .Aliases }} -{{ . | printf "%-35s" }} {{ $p.RelPermalink -}} +{{ . | printf "%-35s" }} {{ $p.RelPermalink -}} {{ end -}} {{- end -}} diff --git a/layouts/index.rss.xml b/layouts/index.rss.xml deleted file mode 100644 index 460c4d30e..000000000 --- a/layouts/index.rss.xml +++ /dev/null @@ -1,68 +0,0 @@ -{{- printf "" | safeHTML }} - - - Hugo News - Recent news about Hugo, a static site generator written in Go, optimized for speed and designed for flexibility. - {{ .Permalink }} - Hugo {{ hugo.Version }} - {{ or site.Language.LanguageCode site.Language.Lang }} - {{- with site.Copyright }} - {{ . }} - {{- end }} - {{- with .OutputFormats.Get "rss" }} - {{ printf "" .Permalink .MediaType | safeHTML }} - {{- end }} - - {{- $news_items := slice }} - - {{- /* Get releases from GitHub. */}} - {{- $u := "https://api.github.com/repos/gohugoio/hugo/releases" }} - {{- $releases := partial "helpers/funcs/get-remote-data.html" $u }} - {{- $releases = where $releases "draft" false }} - {{- $releases = where $releases "prerelease" false }} - {{- range $releases | first 20 }} - {{- $summary := printf - "Hugo %s was released on %s. See [release notes](%s) for details." - .tag_name - (.published_at | time.AsTime | time.Format "2 Jan 2006") - .html_url - }} - {{- $ctx := dict - "PublishDate" (.published_at | time.AsTime) - "Title" (printf "Release %s" .name) - "Permalink" .html_url - "Section" "news" - "Summary" ($summary | $.Page.RenderString) - }} - {{- $news_items = $news_items | append $ctx }} - {{- end }} - - {{- /* Get content pages from news section. */}} - {{- range where site.RegularPages "Section" "news" }} - {{- $ctx := dict - "PublishDate" .PublishDate - "Title" .Title - "RelPermalink" .RelPermalink - "Section" "news" - "Summary" .Summary - "Params" (dict "description" .Description) - }} - {{- $news_items = $news_items | append $ctx }} - {{- end }} - {{- /* Sort, limit, and render lastBuildDate. */}} - {{- $limit := cond (gt site.Config.Services.RSS.Limit 1) site.Config.Services.RSS.Limit 999 }} - {{- $news_items = sort $news_items "PublishDate" "desc" | first $limit }} - {{ (index $news_items 0).PublishDate.Format "Mon, 02 Jan 2006 15:04:05 -0700" | safeHTML }} - - {{- /* Render items. */}} - {{- range $news_items }} - - {{ .Title }} - {{ .Permalink }} - {{ .PublishDate.Format "Mon, 02 Jan 2006 15:04:05 -0700" | safeHTML }} - {{ .Permalink }} - {{ .Summary | transform.XMLEscape | safeHTML }} - - {{- end }} - - diff --git a/layouts/partials/docs/functions-aliases.html b/layouts/partials/docs/functions-aliases.html index dc562307a..b3a5a7607 100644 --- a/layouts/partials/docs/functions-aliases.html +++ b/layouts/partials/docs/functions-aliases.html @@ -1,4 +1,4 @@ -{{- with .Params.action.aliases }} +{{- with .Params.functions_and_methods.aliases }} {{- $label := "Alias" }} {{- if gt (len .) 1 }} {{- $label = "Aliases" }} diff --git a/layouts/partials/docs/functions-return-type.html b/layouts/partials/docs/functions-return-type.html index 13c8c96f4..75c97f8d9 100644 --- a/layouts/partials/docs/functions-return-type.html +++ b/layouts/partials/docs/functions-return-type.html @@ -1,4 +1,4 @@ -{{- with .Params.action.returnType }} +{{- with .Params.functions_and_methods.returnType }}

    Returns

    {{- . -}} diff --git a/layouts/partials/docs/functions-signatures.html b/layouts/partials/docs/functions-signatures.html index 35d950265..6fb61df8e 100644 --- a/layouts/partials/docs/functions-signatures.html +++ b/layouts/partials/docs/functions-signatures.html @@ -1,4 +1,4 @@ -{{- with .Params.action.signatures }} +{{- with .Params.functions_and_methods.signatures }}

    Syntax

    {{- range . }} {{- $signature := . }} diff --git a/layouts/partials/helpers/debug/list-item-metadata.html b/layouts/partials/helpers/debug/list-item-metadata.html new file mode 100644 index 000000000..d027484b5 --- /dev/null +++ b/layouts/partials/helpers/debug/list-item-metadata.html @@ -0,0 +1,23 @@ + + + + + + + + + + + + + + + + +
    weight: + {{ .Weight }} +
    keywords: + {{ delimit (or .Keywords "") ", " }} +
    categories: + {{ delimit (or .Params.categories "") ", " }} +
    diff --git a/layouts/partials/helpers/funcs/get-remote-data.html b/layouts/partials/helpers/funcs/get-remote-data.html index 78b2ba06e..ed7043421 100644 --- a/layouts/partials/helpers/funcs/get-remote-data.html +++ b/layouts/partials/helpers/funcs/get-remote-data.html @@ -1,3 +1,4 @@ +{{/* prettier-ignore-start */ -}} {{/* Parses the serialized data from the given URL and returns a map or an array. @@ -8,7 +9,7 @@ Supports CSV, JSON, TOML, YAML, and XML. @example {{ partial "get-remote-data.html" "https://example.org/foo.json" }} */}} - +{{/* prettier-ignore-end */ -}} {{ $url := . }} {{ $data := dict }} {{ with try (resources.GetRemote $url) }} diff --git a/layouts/partials/helpers/linkcss.html b/layouts/partials/helpers/linkcss.html index c12406757..814d2b52f 100644 --- a/layouts/partials/helpers/linkcss.html +++ b/layouts/partials/helpers/linkcss.html @@ -5,7 +5,7 @@ + {{ template `render-attributes` $attr }}> {{ else }} {{ with $r | minify | fingerprint }} + {{ template `render-attributes` $attr }}> {{ end }} {{ end }} diff --git a/layouts/partials/helpers/picture.html b/layouts/partials/helpers/picture.html index 7f30f1437..454dd705e 100644 --- a/layouts/partials/helpers/picture.html +++ b/layouts/partials/helpers/picture.html @@ -9,17 +9,17 @@ + media="(min-width: 1200px)"> - - + media="(min-width: 1200px)"> + + + height="{{ $image1x.Height }}"> diff --git a/layouts/partials/helpers/validation/validate-keywords.html b/layouts/partials/helpers/validation/validate-keywords.html new file mode 100644 index 000000000..3447ec4ef --- /dev/null +++ b/layouts/partials/helpers/validation/validate-keywords.html @@ -0,0 +1,22 @@ +{{/* prettier-ignore-start */ -}} +{{- /* +We use the front matter keywords field to determine related content. To ensure +consistency, during site build we validate each keyword against the entries in +data/keywords.yaml. + +As of March 5, 2025, this feature is experimental, pending usability +assessment. We anticipate that the number of additions to data/keywords.yaml +will decrease over time, though the initial implementation will require some +effort. +*/}} +{{/* prettier-ignore-end */ -}} +{{- $t := debug.Timer "validateKeywords" }} +{{- $allowedKeywords := collections.Apply site.Data.keywords "strings.ToLower" "." }} +{{- range $p := site.Pages }} + {{- range .Params.keywords }} + {{- if not (in $allowedKeywords (lower .)) }} + {{- warnf "The word or phrase %q is not in the keywords data file. See %s." . $p.Page.String }} + {{- end }} + {{- end }} +{{- end }} +{{- $t.Stop }} diff --git a/layouts/partials/layouts/blocks/alert.html b/layouts/partials/layouts/blocks/alert.html index 705ce0e7e..45f0044d9 100644 --- a/layouts/partials/layouts/blocks/alert.html +++ b/layouts/partials/layouts/blocks/alert.html @@ -1,8 +1,8 @@ -{{ $title := .title | default "" }} -{{ $color := .color | default "yellow" }} -{{ $icon := .icon | default "exclamation" }} -{{ $text := .text | default "" }} -{{ $class := .class | default "mt-6 mb-8" }} +{{- $title := .title | default "" }} +{{- $color := .color | default "yellow" }} +{{- $icon := .icon | default "exclamation-triangle" }} +{{- $text := .text | default "" }} +{{- $class := .class | default "mt-6 mb-8" }}
    @@ -12,15 +12,13 @@
    - {{ with $title }} + {{- with $title }}

    {{ . }}

    - {{ end }} + {{- end }}
    -

    - {{ $text }} -

    + {{ $text }}
    diff --git a/layouts/partials/layouts/breadcrumbs.html b/layouts/partials/layouts/breadcrumbs.html index d0628c7ee..69bcf7bd5 100644 --- a/layouts/partials/layouts/breadcrumbs.html +++ b/layouts/partials/layouts/breadcrumbs.html @@ -15,7 +15,7 @@ {{ $isLast := eq $i (sub (len $ancestors) 1) }} {{ $p.LinkTitle }} + {{ $humanDate }} + diff --git a/layouts/partials/layouts/footer.html b/layouts/partials/layouts/footer.html index 99a856f7e..1b17e44e4 100644 --- a/layouts/partials/layouts/footer.html +++ b/layouts/partials/layouts/footer.html @@ -1,4 +1,5 @@ -
    -
    +
      + class="divide-y divide-gray-200 dark:divide-gray-900 h-[calc(100%-6rem)] overflow-y-auto">
    + {{/* End listing */ -}}

    +
    + {{ partial "layouts/search/algolialogo.html" }} +
    diff --git a/layouts/partials/layouts/templates.html b/layouts/partials/layouts/templates.html new file mode 100644 index 000000000..72b71a3d9 --- /dev/null +++ b/layouts/partials/layouts/templates.html @@ -0,0 +1,7 @@ + diff --git a/layouts/partials/layouts/toc.html b/layouts/partials/layouts/toc.html index 06946d885..774bc15c7 100644 --- a/layouts/partials/layouts/toc.html +++ b/layouts/partials/layouts/toc.html @@ -1,33 +1,37 @@ -{{ with .Fragments.Headings }} - {{ $.Store.Set "hasToc" true }} -
    -

    - On this page -

    - -
    +{{ with .Fragments }} + {{ with .Headings }} +
    +

    + On this page +

    + +
    + {{ end }} {{ end }} {{ define "render-toc-level" }} - {{ range . }} - {{ if and .ID (or (ge .Level 2) (lt .Level 4)) }} + {{ range .h }} + {{ if and .ID (and (ge .Level 2) (le .Level 4)) }} + {{ $indentation := "ml-0" }} + {{ if eq .Level 3 }} + {{ $indentation = "ml-2 lg:ml-3" }} + {{ else if eq .Level 4 }} + {{ $indentation = "ml-4 lg:ml-6" }} + {{ end }} + {{ $.p.Store.Set "hasToc" true }}
  • {{ .Title | safeHTML }} @@ -35,7 +39,7 @@ {{ end }} {{ with .Headings }}
      - {{ template "render-toc-level" . }} + {{ template "render-toc-level" (dict "h" . "p" $.p) }}
    {{ end }} {{ end }} diff --git a/layouts/partials/news/get-news-items.html b/layouts/partials/news/get-news-items.html deleted file mode 100644 index cb1a930d3..000000000 --- a/layouts/partials/news/get-news-items.html +++ /dev/null @@ -1,45 +0,0 @@ -{{ $news_items := slice }} - -{{/* Get releases from GitHub. */}} -{{ $u := "https://api.github.com/repos/gohugoio/hugo/releases" }} -{{ $releases := partial "helpers/funcs/get-remote-data.html" $u }} -{{ $releases = where $releases "draft" false }} -{{ $releases = where $releases "prerelease" false }} -{{ range $releases | first 20 }} - {{ $publishDate := .published_at | time.AsTime }} - - {{/* Correct the v0.138.0 release date. See https://github.com/gohugoio/hugo/issues/13066. */}} - {{ if eq .name "v0.138.0" }} - {{ $publishDate = "2024-11-06T11:22:34Z" | time.AsTime }} - {{ end }} - - {{ $ctx := dict - "Date" $publishDate - "Title" (printf "Release %s" .name) - "LinkTitle" (printf "Release %s" .name) - "Permalink" .html_url - "RelPermalink" .html_url - "Section" "news" - "Summary" "" - }} - {{ $news_items = $news_items | append $ctx }} -{{ end }} - -{{/* Get content pages from news section. */}} -{{ range .Pages }} - {{ $ctx := dict - "Date" .Date - "Title" .Title - "LinkTitle" .Title - "RelPermalink" .RelPermalink - "Section" "news" - "Summary" .Summary - "Params" (dict "description" .Description) - }} - {{ $news_items = $news_items | append $ctx }} -{{ end }} - -{{/* Sort by date (descending) and render. */}} -{{ $news_items = sort $news_items "Date" "desc" }} - -{{ return $news_items }} diff --git a/layouts/partials/opengraph/opengraph.html b/layouts/partials/opengraph/opengraph.html index 1c89b0814..e32e07298 100644 --- a/layouts/partials/opengraph/opengraph.html +++ b/layouts/partials/opengraph/opengraph.html @@ -1,4 +1,4 @@ - + + {{ end }}"> - + {{ end }}"> + {{- with $.Params.images -}} {{- range first 6 . }} - + {{ end -}} {{- else -}} {{- $featured := partial "opengraph/get-featured-image.html" . }} {{- with $featured -}} - + {{- else -}} {{- with $.Site.Params.images }} - + {{ end -}} {{- end -}} {{- end -}} {{- if .IsPage }} {{- $iso8601 := "2006-01-02T15:04:05-07:00" -}} - + {{ with .PublishDate }} + {{ .Format $iso8601 | printf "content=%q" | safeHTMLAttr }}> {{ end }} {{ with .Lastmod }} + {{ .Format $iso8601 | printf "content=%q" | safeHTMLAttr }}> {{ end }} {{- end -}} -{{- with .Params.audio }}{{ end }} +{{- with .Params.audio }}{{ end }} {{- with .Params.locale }} - + {{ end }} {{- with .Site.Params.title }} - + {{ end }} {{- with .Params.videos }} {{- range . }} - + {{ end }} {{ end }} @@ -71,7 +71,7 @@ {{- $series := index $siteSeries ($name | urlize) }} {{- range $page := first 6 $series.Pages }} {{- if ne $page.Permalink $permalink }} - + {{ end }} {{- end }} {{ end }} @@ -80,5 +80,5 @@ {{- /* Facebook Page Admin ID for Domain Insights */}} {{- with site.Params.social.facebook_admin }} - + {{ end }} diff --git a/layouts/shortcodes/chroma-lexers.html b/layouts/shortcodes/chroma-lexers.html index 38241be33..fd7130501 100644 --- a/layouts/shortcodes/chroma-lexers.html +++ b/layouts/shortcodes/chroma-lexers.html @@ -1,7 +1,28 @@ -
    - {{ range .Site.Data.docs.chroma.lexers }} -
    {{ .Name }}
    -
    {{ with .Aliases }}{{ delimit . ", " }}{{ end }}
    - {{ end }} -
    - \ No newline at end of file +{{/* prettier-ignore-start */ -}} +{{- /* +Renders an HTML template of Chroma lexers and their aliases. + +@example {{< chroma-lexers >}} +*/ -}} +{{/* prettier-ignore-end */ -}} +
    + + + + + + + {{- range site.Data.docs.chroma.lexers }} + + + + + {{- end }} + +
    LanguageIdentifiers
    {{ .Name }} + {{- range $k, $_ := .Aliases }} + {{- if $k }},{{ end }} + {{ . }} + {{- end }} +
    +
    diff --git a/layouts/shortcodes/code-toggle.html b/layouts/shortcodes/code-toggle.html index 4e64fded0..a22c378be 100644 --- a/layouts/shortcodes/code-toggle.html +++ b/layouts/shortcodes/code-toggle.html @@ -1,19 +1,26 @@ +{{/* prettier-ignore-start */ -}} {{- /* - Renders syntax-highlighted configuration data in JSON, TOML, and YAML formats. +Renders syntax-highlighted configuration data in JSON, TOML, and YAML formats. - @param {string} [config] The section of site.Data.docs.config to render. - @param {bool} [copy=false] If true, display a copy to clipboard button. - @param {string} [file] The file name to display above the rendered code. - @param {bool} [fm=false] If true, render the code as front matter. - @param {bool} [skipHeader=false] If false, omit top level key(s) when rendering a section of site.Data.docs.config. +@param {string} [config] The section of site.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} [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. - @returns {template.HTML} -*/}} +@example {{< code-toggle file=hugo config=build />}} +@example {{< code-toggle file=content/example.md fm="true" }} + title='Example' + draft='false + {{< /code-toggle }} +*/ -}} +{{/* prettier-ignore-end */ -}} {{- /* Initialize. */}} {{- $config := "" }} -{{- $dataKey := "" }} {{- $copy := false }} +{{- $dataKey := "" }} {{- $file := "" }} {{- $fm := false }} {{- $skipHeader := false }} @@ -60,22 +67,26 @@ {{- else }} {{- $code = $.Inner }} {{- end }} -
    - - - + + +
    + {{- if $copy }} + + + + {{- end }} - {{ if $code }} - {{ range $i, $lang := $langs }} + {{- if $code }} + {{- range $i, $lang := $langs }}
    - {{ end }} - {{ end }} + {{- end }} + {{- end }}
    diff --git a/layouts/shortcodes/code.html b/layouts/shortcodes/code.html deleted file mode 100644 index 1ccb44b7d..000000000 --- a/layouts/shortcodes/code.html +++ /dev/null @@ -1,38 +0,0 @@ -{{- $codeLang := or (.Get "lang") "" }} -
    - {{ if (.Get "copy") }} - - - - {{ end }} - {{- with .Get "file" -}} - {{- if not $codeLang }} - {{- $ext := strings.TrimPrefix "." (path.Ext .) }} - {{- $codeLang = cond (eq $ext "html") "go-html-template" $ext }} - {{- end }} -
    - {{ . }} -
    - {{- end -}} - - -
    - {{ $inner := trim .Inner "\n" | safeHTML }} - {{ if .Get "nocode" }} - {{ $inner }} - {{ else }} - {{ with $codeLang }} - {{ highlight $inner . "" }} - {{ else }} - 
    {{ $inner }}
-
    - {{ end }} - {{ end }} -
    -
    diff --git a/layouts/shortcodes/datatable-filtered.html b/layouts/shortcodes/datatable-filtered.html index ff3f299bd..de8b0cf55 100644 --- a/layouts/shortcodes/datatable-filtered.html +++ b/layouts/shortcodes/datatable-filtered.html @@ -9,31 +9,39 @@ {{ $fields := after 3 .Params }} {{ $list := where $list $filter1 $filter2 $filter3 }} - - - {{ range $fields }} - - {{ end }} - - {{ range $list }} - - {{ range $k, $v := . }} - {{ $.Scratch.Set $k $v }} - {{ end }} - {{ range $k, $v := $fields }} - - {{ end }} - - {{ end }} -
    {{ . }}
    - {{ $tdContent := $.Scratch.Get . }} - {{ if eq $k 3 }} - {{ printf "%v" $tdContent | - strings.ReplaceRE `\[` "
    1. " | - strings.ReplaceRE `\s` "
    2. " | - strings.ReplaceRE `\]` "
    " | - safeHTML }} - {{ else }} - {{ $tdContent }} - {{ end}} -
    + +
    + + + + {{ range $fields }} + + {{ end }} + + + + {{ range $list }} + + {{ range $k, $v := . }} + {{ $.Scratch.Set $k $v }} + {{ end }} + {{ range $k, $v := $fields }} + + {{ end }} + + {{ end }} + +
    {{ . }}
    + {{ $tdContent := $.Scratch.Get . }} + {{ if eq $k 3 }} + {{ printf "%v" $tdContent | + strings.ReplaceRE `\[` "
    1. " | + strings.ReplaceRE `\s` "
    2. " | + strings.ReplaceRE `\]` "
    " | + safeHTML + }} + {{ else }} + {{ $tdContent }} + {{ end }} +
    +
    diff --git a/layouts/shortcodes/datatable.html b/layouts/shortcodes/datatable.html index 12054f89d..f135d841c 100644 --- a/layouts/shortcodes/datatable.html +++ b/layouts/shortcodes/datatable.html @@ -4,30 +4,36 @@ {{ $fields := after 2 .Params }} - - - {{ range $fields }} - {{ $s := . }} - {{ if eq $s "_key" }} - {{ $s = "Type" }} - {{ end }} - - {{ end }} - - {{ range $k1, $v1 := $list }} - - {{ range $k2, $v2 := . }} - {{ $.Scratch.Set $k2 $v2 }} - {{ end }} - {{ range $fields }} - {{ $s := "" }} - {{ if eq . "_key" }} - {{ $s = $k1 }} - {{ else }} - {{ $s = $.Scratch.Get . }} +
    +
    {{ $s }}
    + + + {{ range $fields }} + {{ $s := . }} + {{ if eq $s "_key" }} + {{ $s = "type" }} + {{ end }} + {{ end }} - + + + + {{ range $k1, $v1 := $list }} + + {{ range $k2, $v2 := . }} + {{ $.Scratch.Set $k2 $v2 }} + {{ end }} + {{ range $fields }} + {{ $s := "" }} + {{ if eq . "_key" }} + {{ $s = $k1 }} + {{ else }} + {{ $s = $.Scratch.Get . }} + {{ end }} + + {{ end }} + {{ end }} - - {{ end }} -
    {{ $s }}{{ $s }}
    {{ $s }}
    + + +
    diff --git a/layouts/shortcodes/deprecated-in.html b/layouts/shortcodes/deprecated-in.html index 0272ea4a6..ce2ba389e 100644 --- a/layouts/shortcodes/deprecated-in.html +++ b/layouts/shortcodes/deprecated-in.html @@ -1,17 +1,29 @@ -{{ $_hugo_config := `{ "version": 1 }` }} +{{/* prettier-ignore-start */ -}} +{{- /* +Renders a callout indicating the version in which a feature was deprecated. -{{ with .Get 0 }} - {{ $version := printf "v%v" (strings.TrimLeft "vV" .) }} - {{ $href := printf "https://github.com/gohugoio/hugo/releases/tag/%s" $version }} - {{ $text := (printf `Deprecated in %s. -%s` $href $version $.Inner) | safeHTML }} +Include descriptive text between the opening and closing tags, or omit the +descriptive text and call the shortcode with a self-closing tag. - {{ partial "layouts/blocks/alert.html" (dict - "text" $text - "color" "orange" - "icon" "exclamation" - ) -}} -{{ else }} - {{ errorf "The %q shortcode requires a single positional parameter indicating version. See %s" .Name .Position }} -{{ end }} +@param {string} 0 The semantic version string, with or without a leading v. + +@example {{< deprecated-in 0.144.0 />}} + +@example {{< deprecated-in 0.144.0 >}} + Some descriptive text here. + {{< /deprecated-in >}} +*/ -}} +{{/* prettier-ignore-end */ -}} +{{- with $version := .Get 0 | strings.TrimLeft "vV" }} + {{- $href := printf "https://github.com/gohugoio/hugo/releases/tag/v%s" $version }} + {{- $inner := strings.TrimSpace $.Inner }} + {{- $text := printf "Deprecated in [v%s](%s)\n\n%s" $version $href $inner | $.Page.RenderString (dict "display" "block") }} + {{- partial "layouts/blocks/alert.html" (dict + "color" "orange" + "icon" "exclamation" + "text" $text + ) + }} +{{- else }} + {{- errorf "The %q shortcode requires a single positional parameter indicating version. See %s" .Name .Position }} +{{- end }} diff --git a/layouts/shortcodes/eturl.html b/layouts/shortcodes/eturl.html index c0cf30aec..a0237dbe0 100644 --- a/layouts/shortcodes/eturl.html +++ b/layouts/shortcodes/eturl.html @@ -1,3 +1,4 @@ +{{/* prettier-ignore-start */ -}} {{- /* Renders an absolute URL to the source code for an embedded template. @@ -6,31 +7,20 @@ embedded_templates.toml file in the data directory. @param {string} filename The embedded template's file name, excluding extension. -@returns template.HTML - @example {{% et robots.txt %}} @example {{% et filename=robots.txt %}} -*/}} - -{{- /* Get parameters. */}} -{{- $filename := "" -}} -{{- if .IsNamedParams -}} - {{- $filename = .Get "filename" -}} -{{- else -}} - {{- $filename = .Get 0 -}} -{{- end -}} - -{{- /* Render. */}} -{{- with $filename -}} - {{- with site.Data.embedded_template_urls -}} - {{- with index . $filename -}} - {{- urls.JoinPath site.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 -}} - {{- else -}} - {{- errorf "The %q shortcode was unable to find the embedded_template_urls data file in the site's data directory. See %s" $.Name $.Position -}} - {{- end -}} -{{- else -}} - {{- errorf "The %q shortcodes requires a named or positional parameter, the file name of the embedded template, excluding its extension. See %s" .Name .Position -}} +*/ -}} +{{/* prettier-ignore-end */ -}} +{{- with $filename := or (.Get "filename") (.Get 0) }} + {{- with site.Data.embedded_template_urls }} + {{- with index . $filename }} + {{- urls.JoinPath site.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 }} + {{- else }} + {{- errorf "The %q shortcode was unable to find the embedded_template_urls data file in the site's data directory. See %s" $.Name $.Position }} + {{- end }} +{{- else }} + {{- errorf "The %q shortcodes requires a named or positional parameter, the file name of the embedded template, excluding its extension. See %s" .Name .Position }} {{- end -}} diff --git a/layouts/shortcodes/glossary-term.html b/layouts/shortcodes/glossary-term.html index 7aace730e..2a45dc8cb 100644 --- a/layouts/shortcodes/glossary-term.html +++ b/layouts/shortcodes/glossary-term.html @@ -2,16 +2,14 @@ Renders the definition of the given glossary term. @param {string} (.Get 0) The glossary term. -@returns {template.HTML} @example {{% glossary-term float %}} @example {{% glossary-term "floating point" %}} -*/}} - +*/ -}} {{- with .Get 0 }} {{- $path := printf "/quick-reference/glossary/%s" (urlize .) }} {{- with site.GetPage $path }} -{{ .RenderShortcodes }} {{/* Do not indent. Do not remove non-breaking space. */}} +{{ .RenderShortcodes }}{{/* Do not indent. */}} {{- else }} {{- errorf "The glossary term (%s) shortcode was unable to find %s: see %s" $.Name $path $.Position }} {{- end }} diff --git a/layouts/shortcodes/glossary.html b/layouts/shortcodes/glossary.html index e91be32ce..7331d5c9f 100644 --- a/layouts/shortcodes/glossary.html +++ b/layouts/shortcodes/glossary.html @@ -2,54 +2,52 @@ Renders the glossary of terms. When you call this shortcode using the {{% %}} notation, the glossary terms are -Markdown headings (level 6) which means they are members of .Page.Fragments. -This allows the link render hook to verify links to glossary terms. +Markdown headings (level 6) which means they are members of .Fragments. This +allows the link render hook to verify links to glossary terms. Yes, the terms themselves are pages, but we don't want to link to the pages, at -least not right now. Instead, we want to link to the fragments rendered by this +least not right now. Instead, we want to link to the ids rendered by this shortcode. -@returns {template.HTML} - @example {{% glossary %}} -*/}} +*/ -}} {{- $path := "/quick-reference/glossary" }} {{- with site.GetPage $path }} - {{- /* Build and render alphabetical index. */}} - {{- $m := dict }} - {{- range $p := .Pages.ByTitle }} - {{- $k := substr .Title 0 1 | strings.ToUpper }} - {{- if index $m $k }} - {{- continue }} - {{- end }} - {{- $anchor := path.BaseName .Path | anchorize }} - {{- $m = merge $m (dict $k $anchor) }} + {{- /* Build and render alphabetical index. */}} + {{- $m := dict }} + {{- range $p := .Pages.ByTitle }} + {{- $k := substr .Title 0 1 | strings.ToUpper }} + {{- if index $m $k }} + {{- continue }} {{- end }} - {{- range $k, $v := $m }} + {{- $anchor := path.BaseName .Path | anchorize }} + {{- $m = merge $m (dict $k $anchor) }} + {{- end }} + {{- range $k, $v := $m }} [{{ $k }}](#{{ $v }}) {{/* Do not indent. */}} - {{- end }} + {{- end }} - {{- /* Render glossary terms. */}} - {{- range $p := .Pages.ByTitle }} -###### {{ .Title }}{{/* Do not indent. */}} -{{ .RenderShortcodes }}{{/* Do not indent. */}} - {{- with .Params.reference }} - {{- $destination := "" }} - {{- with $u := urls.Parse . }} - {{- if $u.IsAbs }} - {{- $destination = $u.String }} + {{/* Render glossary terms. */}} + {{- range $p := .Pages.ByTitle }} +{{ .Title }}{{/* Do not indent. */}} +: {{ .RawContent | strings.TrimSpace | safeHTML }}{{/* Do not indent. */}} + {{ with .Params.reference }} + {{- $destination := "" }} + {{- with $u := urls.Parse . }} + {{- if $u.IsAbs }} + {{- $destination = $u.String }} + {{- else }} + {{- with site.GetPage $u.Path }} + {{- $destination = .RelPermalink }} {{- else }} - {{- with site.GetPage $u.Path -}} - {{- $destination = .RelPermalink }} - {{- else }} - {{- errorf "The %q shortcode was unable to find the reference link %s: see %s" $.Name . $p.String }} - {{- end }} + {{- errorf "The %q shortcode was unable to find the reference link %s: see %s" $.Name . $p.String }} {{- end }} - {{- end -}} - See [details]({{ $destination }}).{{/* Do not indent. */}} + {{- end }} {{- end }} +: See [details]({{ $destination }}).{{/* Do not indent. */}} {{- end }} + {{ end }} {{- else }} {{- errorf "The %q shortcode was unable to get %s: see %s" .Name $path .Position}} diff --git a/layouts/shortcodes/gomodules-info.html b/layouts/shortcodes/gomodules-info.html deleted file mode 100644 index 126d846c0..000000000 --- a/layouts/shortcodes/gomodules-info.html +++ /dev/null @@ -1,12 +0,0 @@ -{{ $text := ` - Most of the commands for **Hugo Modules** require a newer version (>= 1.18) of Go installed (see https://golang.org/dl/) and the relevant VCS client (e.g. Git, see https://git-scm.com/downloads/ ). - If you have an "older" site running on Netlify, you may have to set GO_VERSION to 1.19 or newer in your Environment settings. - - For more information about Go Modules, see: - - * https://go.dev/wiki/Modules - * https://blog.golang.org/using-go-modules - ` -}} - -{{ partial "layouts/blocks/alert.html" (dict "title" "Go Modules" "text" ($text | markdownify) "color" "orange" "icon" "exclamation") }} diff --git a/layouts/shortcodes/hl.html b/layouts/shortcodes/hl.html index 1a5b4e1ec..3fafcb5e8 100644 --- a/layouts/shortcodes/hl.html +++ b/layouts/shortcodes/hl.html @@ -1,11 +1,14 @@ +{{/* prettier-ignore-start */ -}} {{- /* Returns syntax-highlighted code from the given text. This is useful as a terse way to highlight inline code snippets. Calling the highlight shortcode for inline snippets is verbose. -*/}} +@example This is {{< hl python >}}inline{{< /hl >}} code. +*/ -}} +{{/* prettier-ignore-end */ -}} {{- $code := .Inner | strings.TrimSpace }} -{{- $lang := or (.Get 0) "go" }} +{{- $lang := or (.Get 0) "go" }} {{- $opts := dict "hl_inline" true "noClasses" true }} {{- transform.Highlight $code $lang $opts }} diff --git a/layouts/shortcodes/img.html b/layouts/shortcodes/img.html index 7c2d805d2..60187802e 100644 --- a/layouts/shortcodes/img.html +++ b/layouts/shortcodes/img.html @@ -1,90 +1,85 @@ +{{/* prettier-ignore-start */ -}} {{- /* Renders the given image using the given filter, if any. +When using the text filter, provide the arguments in this order: + +0. The text +1. The horizontal offset, in pixels, relative to the left of the image (default 20) +2. The vertical offset, in pixels, relative to the top of the image (default 20) +3. The font size in pixels (default 64) +4. The line height (default 1.2) +5. The font color (default #ffffff) + +When using the padding filter, provide all arguments in this order: + +0. Padding top +1. Padding right +2. Padding bottom +3. Padding right +4. Canvas color + @param {string} src The path to the image which must be a remote, page, or global resource. @param {string} [filter] The filter to apply to the image (case-insensitive). @param {string} [filterArgs] A comma-delimited list of arguments to pass to the filter. @param {bool} [example=false] If true, renders a before/after example. @param {int} [exampleWidth=384] Image width, in pixels, when rendering a before/after example. -@returns {template.HTML} +@example {{< img src="zion-national-park.jpg" >}} +@example {{< img src="zion-national-park.jpg" alt="Zion National Park" >}} -@examples +@example {{< img + src="zion-national-park.jpg" + alt="Zion National Park" + filter="grayscale" + >}} - {{< img src="zion-national-park.jpg" >}} +@example {{< img + src="zion-national-park.jpg" + alt="Zion National Park" + filter="process" + filterArgs="resize 400x webp" + >}} - {{< img src="zion-national-park.jpg" alt="Zion National Park" >}} +@example {{< img + src="zion-national-park.jpg" + alt="Zion National Park" + filter="colorize" + filterArgs="180,50,20" + >}} - {{< img - src="zion-national-park.jpg" - alt="Zion National Park" - filter="grayscale" - >}} +@example {{< img + src="zion-national-park.jpg" + alt="Zion National Park" + filter="grayscale" + example=true + >}} - {{< img - src="zion-national-park.jpg" - alt="Zion National Park" - filter="process" - filterArgs="resize 400x webp" - >}} +@example {{< img + src="zion-national-park.jpg" + alt="Zion National Park" + filter="grayscale" + example=true + exampleWidth=400 + >}} - {{< img - src="zion-national-park.jpg" - alt="Zion National Park" - filter="colorize" - filterArgs="180,50,20" - >}} - - {{< img - src="zion-national-park.jpg" - alt="Zion National Park" - filter="grayscale" - example=true - >}} - - {{< img - src="zion-national-park.jpg" - alt="Zion National Park" - filter="grayscale" - example=true - exampleWidth=400 - >}} - - When using the text filter, provide the arguments in this order: - - 0. The text - 1. The horizontal offset, in pixels, relative to the left of the image (default 20) - 2. The vertical offset, in pixels, relative to the top of the image (default 20) - 3. The font size in pixels (default 64) - 4. The line height (default 1.2) - 5. The font color (default #ffffff) - - {{< img - src="images/examples/zion-national-park.jpg" - alt="Zion National Park" - filter="Text" - filterArgs="Zion National Park,25,250,56" - example=true - >}} - - When using the padding filter, provide all arguments in this order: - - 0. Padding top - 1. Padding right - 2. Padding bottom - 3. Padding right - 4. Canvas color - - {{< img - src="images/examples/zion-national-park.jpg" - alt="Zion National Park" - filter="Padding" - filterArgs="20,50,20,50,#0705" - example=true - >}} - -*/}} +@example {{< img + src="images/examples/zion-national-park.jpg" + alt="Zion National Park" + filter="Text" + filterArgs="Zion National Park,25,250,56" + example=true + >}} +@example {{< img + src="images/examples/zion-national-park.jpg" + alt="Zion National Park" + filter="Padding" + filterArgs="20,50,20,50,#0705" + example=true + >}} +*/ -}} +{{/* prettier-ignore-end */ -}} {{- /* Initialize. */}} {{- $alt := "" }} {{- $src := "" }} @@ -100,12 +95,12 @@ Renders the given image using the given filter, if any. "fontSize" 64 "lineHeight" 1.2 "fontColor" "#ffffff" - "fontPath" "https://github.com/google/fonts/raw/main/ofl/lato/Lato-Regular.ttf" + "fontPath" "https://github.com/google/fonts/raw/refs/heads/main/ofl/lato/Lato-Regular.ttf" }} {{- /* Get and validate parameters. */}} {{- with .Get "alt" }} - {{- $alt = .}} + {{- $alt = . }} {{- end }} {{- with .Get "src" }} @@ -138,7 +133,7 @@ Renders the given image using the given filter, if any. {{- if in (slice "false" false 0) (.Get "example") }} {{- $example = false }} -{{- else if in (slice "true" true 1) (.Get "example")}} +{{- else if in (slice "true" true 1) (.Get "example") }} {{- $example = true }} {{- end }} @@ -328,17 +323,22 @@ Renders the given image using the given filter, if any. {{- end }} {{- /* Render. */}} -{{- $class := "di va b--black-20" }} -{{- if eq $filter "mask" }} - {{- $class = "di va" }} -{{- end }} +{{- $class := "border-1 border-gray-300 dark:border-gray-500" }} {{- if $example }}

    Original

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

    Processed

    - {{ $alt }} + {{ $alt }} {{- else -}} - {{ $alt }} + {{ $alt }} {{- end }} {{- define "validate-arg-count" }} @@ -387,5 +387,5 @@ Renders the given image using the given filter, if any. {{- end }} {{- end }} {{- end }} - {{- return $r}} + {{- return $r }} {{- end -}} diff --git a/layouts/shortcodes/imgproc.html b/layouts/shortcodes/imgproc.html index c09133ba8..fee48525a 100644 --- a/layouts/shortcodes/imgproc.html +++ b/layouts/shortcodes/imgproc.html @@ -1,37 +1,39 @@ +{{/* prettier-ignore-start */ -}} {{- /* Renders the given image using the given process specification. -@param {string} (positional parameter 0) The path to the image, relative to the current page. The image must be a page resource. -@param {string}} (positional parameter 1) The image processing specification. +@param {string} path The path to the image, either a page resource or a global resource. +@param {string} spec The image processing specification. +@param {string} alt The alt attribute of the img element. -@returns template.HTML - -@example {{< imgproc "sunset.jpg" "resize 300x" />}} -*/}} - -{{- with $.Get 0 }} - {{- with $i := $.Page.Resources.Get . }} - {{- with $spec := $.Get 1 }} +@example {{< imgproc path="sunset.jpg" spec="resize 300x" alt="A sunset" >}} +*/ -}} +{{/* prettier-ignore-end */ -}} +{{- with $.Get "path" }} + {{- with $i := or ($.Page.Resources.Get .) (resources.Get .) }} + {{- with $spec := $.Get "spec" }} {{- with $i.Process . }} -
    - -
    - - {{- with $.Inner }} - {{ . }} - {{- else }} - {{ $spec }} - {{- end }} - +
    + {{ $.Get `alt` }} +
    + {{- with $.Inner }} + {{ . }} + {{- else }} + {{ $spec }} + {{- end }}
    {{- end }} {{- else }} - {{- errorf "The %q shortcode requires a positional parameter (1) containing the image processing specification. See %s" $.Name $.Position }} + {{- errorf "The %q shortcode requires a 'spec' argument containing the image processing specification. See %s" $.Name $.Position }} {{- end }} {{- else }} {{- errorf "The %q shortcode was unable to find %q. See %s" $.Name . $.Position }} {{- end }} {{- else }} - {{- errorf "The %q shortcode requires a positional parameter (0) indicating the image path, relative to the current page. See %s" $.Name $.Position }} + {{- errorf "The %q shortcode requires a 'path' argument indicating the image path. The image must be a page resource or a global resource. See %s" $.Name $.Position }} {{- end }} diff --git a/layouts/shortcodes/include.html b/layouts/shortcodes/include.html index b4a20cd72..81b0c1d8f 100644 --- a/layouts/shortcodes/include.html +++ b/layouts/shortcodes/include.html @@ -1,20 +1,19 @@ +{{/* prettier-ignore-start */ -}} {{- /* Renders the page using the RenderShortcode method on the Page object. You must call this shortcode using the {{% %}} notation. @param {string} (positional parameter 0) The path to the page, relative to the content directory. -@returns template.HTML @example {{% include "functions/_common/glob-patterns" %}} -*/}} - +*/ -}} +{{/* prettier-ignore-end */ -}} {{- with .Get 0 }} {{- with or ($.Page.GetPage .) (site.GetPage .) }} {{- .RenderShortcodes }} {{- else }} - {{/* TODO1 make error */}} - {{- warnf "The %q shortcode was unable to find %q. See %s" $.Name . $.Position }} + {{- errorf "The %q shortcode was unable to find %q. See %s" $.Name . $.Position }} {{- end }} {{- else }} {{- errorf "The %q shortcode requires a positional parameter indicating the path of the file to include. See %s" .Name .Position }} diff --git a/layouts/shortcodes/list-pages-in-section.html b/layouts/shortcodes/list-pages-in-section.html index 73e7f85a9..f6dfe7275 100644 --- a/layouts/shortcodes/list-pages-in-section.html +++ b/layouts/shortcodes/list-pages-in-section.html @@ -9,88 +9,61 @@ filter is an array of paths to a file, relative to the root of the content directory. Hugo will throw an error if the specified filter does not exist, or if any of the pages in the filter do not exist. -The definition term elements (dt) have an id attribute derived from the title -of the page. This is probably unique, because pages of the same title in the -same section is unlikely. - -If you render a complete list on a page, then call the shortcode again to -render a subset, you will generate duplicate element ids. In this case, set -omitElementIDs to true for the subset. - @param {string} path The path to the section. @param {string} [filter=""] The name of filter list. @param {string} [filterType=""] The type of filter, either include or exclude. -@param {string} [omitElementIDs=false] Whether to omit dt element ids. @param {string} [titlePrefix=""] The string to prepend to the link title. -@returns template.HTML - @example {{< list-pages-in-section path=/methods/resources >}} @example {{< list-pages-in-section path=/functions/images filter=some_filter filterType=exclude >}} @example {{< list-pages-in-section path=/functions/images filter=some_filter filterType=exclude titlePrefix=foo >}} -@example {{< list-pages-in-section path=/functions/images filter=some_filter filterType=exclude titlePrefix=foo omitElementIDs=true >}} */}} -{{- /* Initialize. */}} -{{- $filter := or "" (.Get "filter" | lower)}} -{{- $filterType := or (.Get "filterType") "none" | lower }} -{{- $filteredPages := slice }} -{{- $titlePrefix := or (.Get "titlePrefix") "" }} -{{- $omitElementIDs := false }} +{{/* Initialize. */}} +{{ $filter := or "" (.Get "filter" | lower) }} +{{ $filterType := or (.Get "filterType") "none" | lower }} +{{ $filteredPages := slice }} +{{ $titlePrefix := or (.Get "titlePrefix") "" }} -{{- /* Get boolean parameters. */}} -{{- if in (slice "false" false 0) (.Get "omitElementIDs") }} - {{- $omitElementIDs = false }} -{{- else if in (slice "true" true 1) (.Get "omitElementIDs")}} - {{- $omitElementIDs = true }} -{{- end }} +{{/* Build slice of filtered pages. */}} +{{ with $filter }} + {{ with index site.Data.page_filters . }} + {{ range . }} + {{ with site.GetPage . }} + {{ $filteredPages = $filteredPages | append . }} + {{ else }} + {{ errorf "The %q shortcode was unable to find %q as specified in the page_filters data file. See %s" $.Name . $.Position }} + {{ end }} + {{ end }} + {{ else }} + {{ errorf "The %q shortcode was unable to find the %q filter in the page_filters data file. See %s" $.Name . $.Position }} + {{ end }} +{{ end }} -{{- /* Build slice of filtered pages. */}} -{{- with $filter }} - {{- with index site.Data.page_filters . }} - {{- range . }} - {{- with site.GetPage . }} - {{- $filteredPages = $filteredPages | append . }} - {{- else }} - {{- errorf "The %q shortcode was unable to find %q as specified in the page_filters data file. See %s" $.Name . $.Position }} - {{- end }} - {{- end }} - {{- else }} - {{- errorf "The %q shortcode was unable to find the %q filter in the page_filters data file. See %s" $.Name . $.Position }} - {{- end }} -{{- end }} - -{{- /* Render */}} -{{- with $sectionPath := .Get "path" }} - {{- with site.GetPage . }} - {{- with .RegularPages }} -
    - {{- range $page := .ByTitle }} - {{- if or +{{/* Render. */}} +{{ with $sectionPath := .Get "path" }} + {{ with site.GetPage . }} + {{ with .RegularPages }} + {{ range $page := .ByTitle }} + {{ if or (and (eq $filterType "include") (in $filteredPages $page)) (and (eq $filterType "exclude") (not (in $filteredPages $page))) (eq $filterType "none") }} - {{- $linkTitle := .LinkTitle }} - {{- with $titlePrefix }} - {{- $linkTitle = printf "%s%s" . $linkTitle }} - {{- end }} - {{- $idAttribute := "" }} - {{- if not $omitElementIDs }} - {{- $id := path.Join .File.Dir .File.ContentBaseName | replaceRE `[\|/]` ":" | lower }} - {{- $idAttribute = printf " id=%q" $id }} - {{- end }} -
    {{ $linkTitle }}
    -
    {{- $page.Description | $page.RenderString }}
    - {{- end }} - {{- end }} -
    - {{- else }} - {{- warnf "The %q shortcode found no pages in the %q section. See %s" $.Name $sectionPath $.Position }} - {{- end }} - {{- else }} - {{- errorf "The %q shortcode was unable to find %q. See %s" $.Name $sectionPath $.Position }} - {{- end }} -{{- else }} - {{- errorf "The %q shortcode requires a 'path' parameter indicating the path to the section. See %s" $.Name $.Position }} -{{- end }} + {{ $linkTitle := .LinkTitle }} + {{ with $titlePrefix }} + {{ $linkTitle = printf "%s%s" . $linkTitle }} + {{ end }} +[{{ $linkTitle }}]({{ $page.RelPermalink }}){{/* Do not indent. */}} +: {{ $page.Description }}{{/* Do not indent. */}} + {{ end }} + {{ end }} + {{ else }} + {{ warnf "The %q shortcode found no pages in the %q section. See %s" $.Name $sectionPath $.Position }} + {{ end }} + {{ else }} + {{ errorf "The %q shortcode was unable to find %q. See %s" $.Name $sectionPath $.Position }} + {{ end }} +{{ else }} + {{ errorf "The %q shortcode requires a 'path' parameter indicating the path to the section. See %s" $.Name $.Position }} +{{ end }} diff --git a/layouts/shortcodes/module-mounts-note.html b/layouts/shortcodes/module-mounts-note.html index c1c67991e..ba89abcbf 100644 --- a/layouts/shortcodes/module-mounts-note.html +++ b/layouts/shortcodes/module-mounts-note.html @@ -1 +1,2 @@ -Also see [Module Mounts Config](/hugo-modules/configuration/#module-configuration-mounts) for an alternative way to configure this directory. +For a more flexible approach to configuring this directory, consult the section +on [module mounts](/configuration/module/#mounts). diff --git a/layouts/shortcodes/new-in.html b/layouts/shortcodes/new-in.html index e99cc7bcf..955d0a710 100644 --- a/layouts/shortcodes/new-in.html +++ b/layouts/shortcodes/new-in.html @@ -1,31 +1,31 @@ +{{/* prettier-ignore-start */ -}} {{- /* - Renders a "new in" button indicating the version in which a feature was added. +Renders a callout or badge indicating the version in which a feature was added. - When comparing the current version to the specified version, the "new in" - button will be hidden if any of the following conditions is true: +To render a callout, include descriptive text between the opening and closing +tags. To render a badge,omit the descriptive text and call the shortcode with a +self-closing tag. - - The major version difference exceeds the majorVersionDiffThreshold - - The minor version difference exceeds the minorVersionDiffThreshold +When comparing the current version to the specified version, the "new in" +button will be hidden if any of the following conditions is true: - @param {string} version The semantic version string, with or without a leading v. - @returns {template.HTML} +- The major version difference exceeds the majorVersionDiffThreshold +- The minor version difference exceeds the minorVersionDiffThreshold - @examples {{< new-in 0.100.0 / ->}} +@param {string} 0 The semantic version string, with or without a leading v. -{{< new-in 0.100.0 >}} -Some descriptive text here. -{{< /new-in >}} -*/}} -{{ $_hugo_config := `{ "version": 1 }` }} +@example {{< new-in 0.100.0 />}} -{{- /* Set defaults. */}} +@example {{{< new-in 0.100.0 >}} + Some descriptive text here. + {{< /new-in >}} +*/ -}} +{{/* prettier-ignore-end */ -}} {{- $majorVersionDiffThreshold := 0 }} {{- $minorVersionDiffThreshold := 30 }} {{- $displayExpirationWarning := true }} -{{- /* Render. */}} -{{- with $version := .Get 0 | strings.TrimPrefix "v" }} +{{- with $version := .Get 0 | strings.TrimLeft "vV" }} {{- $majorVersionDiff := sub (index (split hugo.Version ".") 0 | int) (index (split $version ".") 0 | int) }} {{- $minorVersionDiff := sub (index (split hugo.Version ".") 1 | int) (index (split $version ".") 1 | int) }} {{- if or (gt $majorVersionDiff $majorVersionDiffThreshold) (gt $minorVersionDiff $minorVersionDiffThreshold) }} @@ -35,14 +35,12 @@ Some descriptive text here. {{- else }} {{- $href := printf "https://github.com/gohugoio/hugo/releases/tag/v%s" $version }} {{- with $.Inner }} - {{ $text := printf `

    New in v%s.

    %s` - $href $version (. | $.Page.RenderString (dict "display" "block")) - }} - + {{- $inner := strings.TrimSpace . }} + {{- $text := printf "New in [v%s](%s)\n\n%s" $version $href $inner | $.Page.RenderString (dict "display" "block") }} {{ partial "layouts/blocks/alert.html" (dict - "text" ($text | safeHTML) "color" "green" "icon" "exclamation" + "text" $text ) }} {{- else }} @@ -62,5 +60,5 @@ Some descriptive text here. {{- end }} {{- end }} {{- else }} - {{- errorf "The %q shortcode requires a positional parameter (version). See %s" .Name .Position }} -{{- end -}} + {{- errorf "The %q shortcode requires a single positional parameter indicating version. See %s" .Name .Position }} +{{- end }} diff --git a/layouts/shortcodes/note.html b/layouts/shortcodes/note.html deleted file mode 100644 index b18d53bc7..000000000 --- a/layouts/shortcodes/note.html +++ /dev/null @@ -1,7 +0,0 @@ -{{ $_hugo_config := `{ "version": 1 }` }} -{{ partial "layouts/blocks/alert.html" (dict - "text" .Inner - "color" "blue" - "icon" "exclamation" - ) -}} diff --git a/layouts/shortcodes/per-lang-config-keys.html b/layouts/shortcodes/per-lang-config-keys.html new file mode 100644 index 000000000..f6090d555 --- /dev/null +++ b/layouts/shortcodes/per-lang-config-keys.html @@ -0,0 +1,71 @@ +{{/* prettier-ignore-start */ -}} +{{- /* +Renders a responsive grid of the configuration keys that can be defined +separately for each language. +*/ -}} +{{/* prettier-ignore-end */ -}} +{{- $siteConfigKeys := slice + (dict "baseURL" "/configuration/all/#baseurl") + (dict "buildDrafts" "/configuration/all/#builddrafts") + (dict "buildExpired" "/configuration/all/#buildexpired") + (dict "buildFuture" "/configuration/all/#buildfuture") + (dict "canonifyURLs" "/configuration/all/#canonifyurls") + (dict "capitalizeListTitles" "/configuration/all/#capitalizelisttitles") + (dict "contentDir" "/configuration/all/#contentdir") + (dict "copyright" "/configuration/all/#copyright") + (dict "disableAliases" "/configuration/all/#disablealiases") + (dict "disableHugoGeneratorInject" "/configuration/all/#disableHugogeneratorinject") + (dict "disableKinds" "/configuration/all/#disableKinds") + (dict "disableLiveReload" "/configuration/all/#disablelivereload") + (dict "disablePathToLower" "/configuration/all/#disablepathtolower") + (dict "enableEmoji " "/configuration/all/#enableemoji") + (dict "frontmatter" "/configuration/front-matter/") + (dict "hasCJKLanguage" "/configuration/all/#hascjklanguage") + (dict "languageCode" "/configuration/all/#languagecode") + (dict "mainSections" "/configuration/all/#mainsections") + (dict "markup" "/configuration/markup/") + (dict "mediaTypes" "/configuration/media-types/") + (dict "menus" "/configuration/menus/") + (dict "outputFormats" "/configuration/output-formats") + (dict "outputs" "/configuration/outputs/") + (dict "page" "/configuration/page/") + (dict "pagination" "/configuration/pagination/") + (dict "params" "/configuration/params/") + (dict "permalinks" "/configuration/permalinks/") + (dict "pluralizeListTitles" "/configuration/all/#pluralizelisttitles") + (dict "privacy" "/configuration/privacy/") + (dict "refLinksErrorLevel" "/configuration/all/#reflinkserrorlevel") + (dict "refLinksNotFoundURL" "/configuration/all/#reflinksnotfoundurl") + (dict "related" "/configuration/related-content/") + (dict "relativeURLs" "/configuration/all/#relativeurls") + (dict "removePathAccents" "/configuration/all/#removepathaccents") + (dict "renderSegments" "/configuration/all/#rendersegments") + (dict "sectionPagesMenu" "/configuration/all/#sectionpagesmenu") + (dict "security" "/configuration/security/") + (dict "services" "/configuration/services/") + (dict "sitemap" "/configuration/sitemap/") + (dict "staticDir" "/configuration/all/#staticdir") + (dict "summaryLength" "/configuration/all/#summarylength") + (dict "taxonomies" "/configuration/taxonomies/") + (dict "timeZone" "/configuration/all/#timezone") + (dict "title" "/configuration/all/#title") + (dict "titleCaseStyle" "/configuration/all/#titlecasestyle") +}} + +{{- $a := len $siteConfigKeys }} +{{- $b := math.Ceil (div $a 2.) }} +{{- $c := math.Ceil (div $a 3.) }} + + +
    + {{- range $siteConfigKeys }} + {{ range $k, $v := . }} + {{ $u := urls.Parse $v }} + {{ if not (site.GetPage $u.Path) }} + {{ errorf "The %q shorcode was unable to find %s. See %s." $.Name $u.Path $.Position }} + {{ end }} + {{ $k }} + {{ end }} + {{- end }} +
    diff --git a/layouts/shortcodes/quick-reference.html b/layouts/shortcodes/quick-reference.html index fc53c93bd..0ac544036 100644 --- a/layouts/shortcodes/quick-reference.html +++ b/layouts/shortcodes/quick-reference.html @@ -1,37 +1,28 @@ -{{/* -Renders the child sections of the given top-level section, listing each child's immediate descendants. +{{- /* +Renders the child sections of the given top-level section, listing each child's +immediate descendants. @param {string} section The top-level section to render. -@returns template.HTML - -@example {{% quick-reference section="functions" %}} -*/}} +@example {{% quick-reference section="/functions" %}} +*/ -}} {{ $section := "" }} {{ with .Get "section" }} {{ $section = . }} {{ else }} - {{ errorf "The %q shortcodes requires a 'section' parameter. See %s" .Name .Position }} + {{ errorf "The %q shortcode requires a 'section' parameter. See %s" .Name .Position }} {{ end }} -{{/* Do not change the markdown indentation, and do not remove blank lines. */}} {{ with site.GetPage $section }} {{ range .Sections }} - -## {{ .LinkTitle }} -{{ .RawContent }} - - {{ range .Pages }} - {{ $aliases := "" }} - {{ if eq .Section "functions" }} - {{ with .Params.action.aliases }} - {{ $aliases = delimit . " or " }} - {{ end }} +## {{ .LinkTitle }}{{/* Do not indent. */}} +{{ .Description }}{{/* Do not indent. */}} + {{ .Content }} + {{ with .Pages }} + {{ range . }} +[{{ .LinkTitle }}]({{ .RelPermalink }}){{/* Do not indent. */}} +: {{ .Description }}{{/* Do not indent. */}} {{ end }} - -[{{ .LinkTitle }}]({{ .RelPermalink }}) {{ with $aliases }}({{ . }}){{ end }} -: {{ .Description }} - {{ end }} {{ end }} {{ else }} diff --git a/layouts/shortcodes/readfile.html b/layouts/shortcodes/readfile.html deleted file mode 100644 index 1a7d6a320..000000000 --- a/layouts/shortcodes/readfile.html +++ /dev/null @@ -1 +0,0 @@ -TODO readfile.html diff --git a/layouts/shortcodes/root-configuration-keys.html b/layouts/shortcodes/root-configuration-keys.html new file mode 100644 index 000000000..46a6e074f --- /dev/null +++ b/layouts/shortcodes/root-configuration-keys.html @@ -0,0 +1,45 @@ +{{/* prettier-ignore-start */ -}} +{{/* +Renders a comma-separated list of links to the root key configuration pages. + +@example {{< root-configuration-keys >}} +*/ -}} +{{/* prettier-ignore-end */ -}} +{{- /* Create scratch map of key:filename. */}} +{{- $s := newScratch }} +{{- range $k, $v := site.Data.docs.config }} + {{- if or (reflect.IsMap .) (reflect.IsSlice .) }} + {{- $s.Set $k ($k | humanize | anchorize) }} + {{- end }} +{{- end }} + +{{/* Deprecated. */}} +{{- $s.Delete "author" }} + +{{/* Use mounts instead. */}} +{{- $s.Delete "staticDir" }} +{{- $s.Delete "ignoreFiles" }} + +{{/* This key is "HTTPCache" not "httpCache". */}} +{{- $s.Set "HTTPCache" "http-cache" }} + +{{/* This key is "frontmatter" not "frontMatter" */}} +{{- $s.Set "frontmatter" "front-matter" }} + +{{/* The page title is "Related content" not "related". */}} +{{- $s.Set "related" "related-content" }} + +{{/* It can be configured as bool or map; we want to show map. */}} +{{- $s.Set "uglyURLs" "ugly-urls" }} + +{{- $links := slice }} +{{- range $k, $v := $s.Values }} + {{- $path := printf "/configuration/%s" $v }} + {{- with site.GetPage $path }} + {{- $links = $links | append (printf "%s" .RelPermalink $k) }} + {{- else }} + {{- errorf "The %q shortcode was unable to find the page %s. See %s." $.Name $path $.Position }} + {{- end }} +{{- end }} + +{{- delimit $links ", " ", and " | safeHTML -}} diff --git a/layouts/shortcodes/syntax-highlighting-styles.html b/layouts/shortcodes/syntax-highlighting-styles.html new file mode 100644 index 000000000..297849cef --- /dev/null +++ b/layouts/shortcodes/syntax-highlighting-styles.html @@ -0,0 +1,70 @@ +{{- /* +Renders a gallery a Chroma syntax highlighting styles. + +@example {{% syntax-highlighting-styles %}} +*/ -}} +{{- $examples := slice }} + +{{- /* Example: css */}} +{{- $example := dict "lang" "css" "code" ` +body { + font-size: 16px; /* comment */ +} +`}} +{{- $examples = $examples | append $example }} + +{{- /* Example: html */}} +{{- $example = dict "lang" "html" "code" ` +Example +`}} +{{- $examples = $examples | append $example }} + +{{- /* Example: go-html-template */}} +{{- $example = dict "lang" "go-html-template" "code" ` +{{ with $.Page.Params.content }} + {{ . | $.Page.RenderString }} {{/* comment */}} +{{ end }} +`}} +{{- $examples = $examples | append $example }} + +{{- /* Example: javascript */}} +{{- $example = dict "lang" "javascript" "code" ` +if ([1,"one",2,"two"].includes(value)){ + console.log("Number is either 1 or 2."); // comment +} +`}} +{{- $examples := $examples | append $example }} + +{{- /* Example: markdown */}} +{{- $example = dict "lang" "markdown" "code" ` +{{< figure src="kitten.jpg" >}} +[example](https://example.org "An example") +`}} +{{- $examples := $examples | append $example }} + +{{- /* Example: toml */}} +{{- $example = dict "lang" "toml" "code" ` +[params] +bool = true # comment +string = 'foo' +`}} +{{- $examples := $examples | append $example }} + +{{- /* Render */}} +{{- with site.Data.docs.chroma.styles }} + {{- range $style := . }} + +### {{ $style }} {class="!mt-7 !mb-6"}{{/* Do not indent. */}} + + {{- range $examples }} + +{{ .lang }}{{/* Do not indent. */}} +{class="text-sm !-mt-3 !-mb-5"}{{/* Do not indent. */}} + +```{{ .lang }} {noClasses=true style="{{ $style }}"}{{/* Do not indent. */}} +{{- .code | safeHTML -}}{{/* Do not indent. */}} +```{{/* Do not indent. */}} + + {{- end }} + {{- end }} +{{- end }} diff --git a/netlify.toml b/netlify.toml index 0cd557e7c..67c146cad 100644 --- a/netlify.toml +++ b/netlify.toml @@ -3,7 +3,7 @@ command = "hugo --gc --minify" [build.environment] - HUGO_VERSION = "0.143.1" + HUGO_VERSION = "0.145.0" [context.production.environment] HUGO_ENV = "production" diff --git a/package.json b/package.json index 92339ba25..24ffc7ff5 100644 --- a/package.json +++ b/package.json @@ -9,14 +9,17 @@ "author": "", "license": "", "devDependencies": { - "@tailwindcss/cli": "^4.0.0", - "@tailwindcss/typography": "^0.5.15", - "tailwindcss": "^4.0.0" + "@awmottaz/prettier-plugin-void-html": "~1.8.0", + "@tailwindcss/cli": "~4.1.0", + "@tailwindcss/typography": "~0.5.16", + "prettier": "~3.5.3", + "prettier-plugin-go-template": "~0.0.15", + "tailwindcss": "~4.1.0" }, "dependencies": { - "@alpinejs/focus": "^3.14.8", - "@alpinejs/persist": "^3.14.8", - "@hotwired/turbo": "^8.0.12", - "alpinejs": "^3.14.8" + "@alpinejs/focus": "~3.14.9", + "@alpinejs/persist": "~3.14.9", + "@hotwired/turbo": "~8.0.13", + "alpinejs": "~3.14.9" } } diff --git a/static/browserconfig.xml b/static/browserconfig.xml deleted file mode 100644 index 62400c5f2..000000000 --- a/static/browserconfig.xml +++ /dev/null @@ -1,10 +0,0 @@ - - - - - - - #2d89ef - - -