aboutsummaryrefslogtreecommitdiffhomepage
diff options
context:
space:
mode:
authorBjørn Erik Pedersen <[email protected]>2024-06-21 09:35:57 +0200
committerBjørn Erik Pedersen <[email protected]>2024-06-21 09:35:57 +0200
commit8b9803425e63e1b1801f8d5d676e96368d706722 (patch)
treea89b0807aeeb767b27535e7917def6965dab130b
parent2658a71e1b6fe24a8b754a62ce0398a09d270d86 (diff)
downloadhugo-8b9803425e63e1b1801f8d5d676e96368d706722.tar.gz
hugo-8b9803425e63e1b1801f8d5d676e96368d706722.zip
Squashed 'docs/' changes from 8c46b304a..9b06f951e
9b06f951e Update theme aa24b5319 Improve quick start example 08e4e626d Update index.md f4c1a8ce1 Update Disqus comments implementation notes (#2631) aac3c0279 Update data sources 6ac3d7617 Fix typo 017da70a0 Ensure consistent use of method instead of variable 820881dcf Fix typo dc6fa5ac6 Document LiveReload debugging 18b8c79f3 Improve url function examples 89e6997f1 Improve url function examples 53134e05c Remove static files page 27645a90f Improve data file/source documentation f86b95bd4 Correct manual summary divider example f0e95c8d1 Add examples to comparison operators c5c6aa798 Document Pager methods 015049af9 Fix typos ea6a9fa3f Remove new-in label 0359c4a1e Fix links 3ab8bb4e3 Update performance.md b5393c65d Update configuration.md ca9697630 Update Sections.md 927c90562 Document HTTP cache config 6da219643 netlify: Hugo 0.127.0 de236b58b Deprecate .Sites.First in favor of .Sites.Default 076067b47 netlify: Hugo 0.126.3 c37dd680e Change GetPage examples to single argument 24282c554 Clarify cardinalityThreshold a4ce1a2d2 Revert "Update summaries.md" 466bc7e0f Update summaries.md 168800d5a Fix typo 65f6ca106 content adapters: Use --printPathWarnings to detect page collisions 9c7a700ea Update CLI docs 993aa40d3 netlify: Hugo 0.126.2 0242ec396 Replace file tree image with text 7670da499 rel and relref: Add note about which language version is picked 5dbd7ee26 Add cautionary note to virus scanner exclusion instructions 3c52fab72 Fix typo 868620bcd Improve content summary page 6bca7bc77 Rework safe functions e30d17947 Rework index function b76e81697 Miscellaneous edits 35849e55a Update formats.md 8f939ed5d Update menus.md ea2fd0384 Update docs.yaml (#2592) 2f5d1712b Add security.http.mediaTypes to security page d218b9c44 Change twitter.com to x.com cb2255821 content adapters: Note to exclude file extension when specifying page path 2d5a1690f Indicate that .Page.Sites.First returns the site corresponding to the default content language 60071d923 Indicate that .Site.Sites.First returns the site corresponding to the default content language 0a115cfda Add content adapters section to features summary 011742c24 timer: Adjust output example 977101061 Describe possibility of page collisions with content adapters d57b8a8cf Document virus scanning performance impact and remedy dd5c3af04 netlify: Hugo 0.126.1 0b16c842d Update description of Markdown content format e42ff7609 Fix typo a120ccd0d Update Scratch and Store descriptions cbb2294e3 Update content-adapters.md c39aa4e25 netlify: Upgrade to Hugo 0.126.0 58b9554b7 Update version references 6140802d8 Update docs.yaml 5ee96971a Document content adapters 653069a0d Document the Goldmark extras extension b8ca2833d Update sample data efad994ee Describe .Language.LanguageCode fallback value 3336532fe Update Colors.md 40b49a1f4 Update embedded.md f31741b47 Remove references to symlinks 1d5f40c90 Update sample data fb76580f8 Update function signatures 463adcf26 Use key-value consistently throughout documentation d03ed1887 Update sample data fc59e1f6f Remove examples of LanguageCode fallback b608f3165 Clarify purpose of multilingual site `title` b677f9424 use-modules: clarify the example of initializing a new module 774d64a4d Update theme 417e869f0 Update site configuration docs 1dbe9ee20 Update sample data file fa494af4b Move sample data file 300b4a319 Add sample data file b4fc35c3e Change transform.Unmarshal remote data examples (#2557) 4b79599b9 netlify: Hugo 0.125.6 e8cb250f3 Improve external learning resources 9b0c02e46 Rework content formats 886f952e0 Clarify descriptions of permalink tokens 2f0d8c98c Fix a misused word 3b3b0693d Update Dart Sass version refs c5d0fbcb0 netlify: Hugo 0.125.5 bf7d4f4fd Add Discourse to the comment system list 86a29bd43 Clarify language key format 6126c901a Update multilingual.md 6ec03c2c7 Update WorkingDir: Add new-in d48f40ded Document multilingual 404 redirects b161cc0c5 Update version references 02732fe91 Remove layouts directory 5befe5f28 Vendor theme 21247df4e Update link render hook 7d2fd8647 Update link render hook af9e6bbe7 Update Colors.md 0442f8264 Document images.Color.Luminance and images.Color.ColorHex d58b0b2f5 Update views.md 48ef3ad18 netlify: Hugo 0.125.4 b5721dff2 Update cross-references.md 27905febb Fix typo d16acd658 netlify: Hugo 0.125.3 o 28a1b9dce Update Parse.md 842b20d2c Update YouTube shortcode argument description a133a4828 Clarify that generated syntax highlighter css overrides markup.highlight.style 6e739fcbf Fix alias in /about/security.md a9859e4e2 netlify: Hugo 0.125.2 326fcb518 Update CLI docs 1d3afb6b0 Fix netlify.toml examples in hosting-on-netlify f4628189a Document front matter params expected by embedded templates 8a12d3c48 Fix typo 4b411d3fb Fix typo a7fa25d7f Update CLI docs 7c9a1b864 Add related funcs/methods to time.Round and time.Truncate 79f22ead4 Update strings.Diff description 8085d85e3 Document time.Truncate and time.Round 76a1263e7 netlify: Hugo 0.125.1 6ea4cb709 Update introduction.md e59a8805b Fix typo eace2624a Fix PageInner reference links ba66d6b90 Fix typo 3dcf32e25 Update debug.Dump 38d6731e2 netlify: Hugo 0.125.0 34362b62f Merge branch 'tempv0.125.0' 2221162fa Update privacy defaults and description 3873cf209 Remove "same path" restriction when using resources.Copy 66237fe12 Update youtube shortcode args 961639dfa Document additional changes in v0.125.0 3aa75ee74 Document taxonomies Page method 7f26f69e8 docs: Regen docshelper 05494b7d2 Fix conflicting text for global site function 264fe788e Add missing example to TOC page de8d008e4 Update formats.md 8559c70c3 Update comments.md 987f9424e Update comments.md b77011c93 Improve function descriptions ae663793b all: Fix duplicate words in comments 585095cf8 Fix home page feed 37c6954ac Improve RSS feeds 6cd1b77af Update front-matter.md 3d95ad715 Fix RSS last build date 2c6153461 Improve RSS feed for news section (#2521) 898d7c261 Fix typo 0241936e1 Add installation instructions for Exherbo 62df9bd73 Add missing links to warnidf function c9551d433 Fix a typo in templates docs 09ff1f27c Update YearDay.md 4b278d920 Fix literal usage of manual summary divider 8dec28c50 Fix literal usage of manual summary divider 16102faa8 Add introduction video b276bb17f Fix default data type 61319af7a Fix file extension typo in page-bundles.md ea74d798a Update shortcodes.md 9d18e239f tpl/tplimpl: Optionally exclude content from sitemap 4fe2efc76 Update page-bundles.md 34f099e1e Revise page bundle descriptions 021eea7b1 Update link to Modules page of Go Wiki 6972a9a83 Fix reference link 5ebfdea40 Fix configuration file tree example 12bebaaea Fixing typos b179f3b7f Update segments example ad3e26cec Update segments example 6970a9eeb Fix typo 194139ce7 Update configuration-markup.md 8fb8af286 tpl/tplimpl: Update Google Analytics template and config 4f8fd82ad Add wp2hugo migration tool 39261556a Update directory-structure.md 1e2c0b880 netlify: Hugo 0.124.1 55d5a2787 Update partial function example e26b4634f Fix typo bdada4361 Fix typo and capitalization 4a1fcfc29 Miscellaneous edits 6d6092058 Rework the about section 77ec9d696 Fix typo 6efbf5a39 Update configuration.md dc1fe4405 Update configuration.md 3d1cd3383 Miscellaneous updates 8049e7701 Update IsMultihost method 939281f3a Update version references 5e9567046 Add segments documentation 8e267d780 Update MultiLingual and MultiHost methods/functions c6aeeb747 netlify: Hugo 0.124.0 9fcd40fb5 Merge branch 'tempv0.124.0' 2f7a4ed68 docs: Regen CLI docs 5162805d7 docs: Regen docshelper e1fa18bf8 Update versions in GitHub hosting example 70653e4b2 Add PubCrank to list of front ends 5f81464d5 Update opengraph configuration example cc8a99633 Update hosting-on-gitlab.md 3af715f77 Clarify .Page.File behavior when page is not backed by a file cab417dee Update cspell rules 29f4dde19 Rename section menu entries from "Overview" to "In this section" e04291a99 Miscellaneous edits towards the goal of consistent language f9fc2d5d6 Update page collection quick reference a4893d9ba Update multilingual.md ed81ac6b0 Fix typo 1f522e32e Fix typo c4611eab5 Rework introduction to templating 64154fb8f Fix typo ad71bdfbf Miscellaneous multilingual edits 016adc81b Sync CLI docs 346a5fb02 netlify: Hugo 0.123.8 ff0bedd97 Document hugo.IsMultihost 0e234715c docs: Fix hyphens and grammar in synopsis of command 'hugo server' c8ef1da97 Add the Hugo dedicated Quiqr CMS 59dfe253b Fix grammatical error 1c6ca8022 Standardize usage of the term open-source e6fd6e68c Update Translations.md f6728e79b Update AllTranslations.md 18812d030 Fix typo 3b2d738c9 Correct isCJKLanguage description a1188fe28 Bump version references b51bd5548 Sync and vendor theme da3ba4902 Replace the github logo png with svg f75112195 Add diego to developer tools a4b001470 netlify: Hugo 0.123.7 c37107fda Fix typo 37c1d9c92 Fix typo 48a5ac213 Correct description of MENUENTRY.Title f434e25e8 Correct RESOURCE.Title example de03cd28c netlify: Hugo 0.123.5 3c103d0f9 Revise and improve RESOURCE.Name and RESOURCE.Title examples 4aafbb2f4 netlify: Hugo 0.123.4 f2bf6c365 Clarify archetype context 98ddc91a2 List page kinds to which a taxonomy term may be applied 6094e59bb Remove refs to RESOURCE.Key 208d44a04 Update Key.md 46dd28266 Document the capitalizeListTitles site config option 2ed3b7732 netlify: Hugo 0.123.3 73d35c02f Merge branch 'tempv0.123.3' 93eb216ca js: Support JSX and JSXImportSourceOptions c0cd22cc8 netlify: Hugo 0.123.2 94256ecd0 Add "comma" to list of comments solutions 6a4f38fc3 Update RESOURCE.Name examples 8cf5046f5 netlify: Hugo 0.123.1 c11c8e0da Fix link to embedded code block render hook for GoAT diagrams 08c4af7af Fix typos 1c20eb91a Update all transform.Unmarshal examples d41da7450 Clarify functionality of sectionPagesMenu 5bb3752f7 Update list of methods that use logical path fcab32c62 Update version strings 5770d37c0 Add new-in badge to images.Dither 9f9a9315f Remove variables section 313b1d85e Define and describe the concept of a logical path 97a8d2963 Document HUGO_MEMORYLIMIT c60cd20a8 Capitalize the word Markdown throughout the documentation f9b5938dd Create links to referenced embedded templates df31318d1 Improve quick start guide a76fa0de4 Rework Netlify hosting instructions and examples a3184764d Provide examples of content rendering before accessing Scratch or Store 0206b9699 Include examples of building from source ab268c395 Create FAQ reqarding file watcher c89cf2baa More updates for v0.123.00 b8d5383f7 Replace links to variable pages with links to method pages ad4a124c0 Updates for v0.123.0 24eda1cb0 netlify: Hugo 0.123.0 f7436b6a3 Merge commit '2658a71e1b6fe24a8b754a62ce0398a09d270d86' da2d6ba11 docs: Regen docshelper 411374a58 Add images.Dither filter 36937d58d docs: Regen CLI docs 7c4b77317 docs: Regenerate docshelper a9f56bf9b Merge commit '6efb279bfacbd7304cef994be8181c6f804e7dd4' b3346da53 docs: Make null booleans falsy in the docs helper 88286d1ea docs: Regen docs helper a8ad989c6 Merge commit '9b0050e9aabe4be65c78ccf292a348f309d50ccd' as 'docs' fc7de7136 docs: Prepare for new sub tree 1083bf7c0 releaser: Prepare repository for 0.123.0-DEV b9a03bd59 releaser: Bump versions for release of 0.122.0 e0021f496 build(deps): bump golang.org/x/tools from 0.16.0 to 0.17.0 d25902c0d build(deps): bump github.com/rogpeppe/go-internal from 1.11.0 to 1.12.0 50042ee1f docs: Regen docshelper 3758456b3 Merge commit '7125ad401ad043e46262afc7eca8dceb6d54bb9e' 7125ad401 Squashed 'docs/' changes from 4dd2d6415..3b1a8579d d0d2c6795 markup/goldmark: Support passthrough extension 2dd608378 build(deps): bump github.com/pelletier/go-toml/v2 from 2.1.0 to 2.1.1 45f52be7f build(deps): bump github.com/evanw/esbuild from 0.19.8 to 0.19.12 87bf2b968 tpl/tplimpl: Fix incorrect lastBuildDate f281ef8a4 tpl: fix incorrect lastBuildDate 46f618756 parser/metadecoders: Accumulate org keywords into arrays 891534307 deps: Update github.com/tdewolff/minify/v2 v2.20.9 => v2.20.13 a541e3b4d Upgrade to Go 1.21.6 912c6576b parser/metadecoders: Add CSV lazyQuotes option to transform.Unmarshal 911bc60a7 README: Update minimum Go version to 1.20 5ff632332 releaser: Prepare repository for 0.122.0-DEV 6d5b44305 releaser: Bump versions for release of 0.121.2 1ccd3147a build(deps): bump golang.org/x/crypto from 0.16.0 to 0.17.0 e40b9fbbc tpl/math: Add math.Rand template function 9cd8fbb33 Adjust site benchmark abcc61002 Simplify baseline benchmark 648d00c7d resources/images: Create AutoOrient image filter 8adba648c all: Remove unused code 6f13430d4 releaser: Prepare repository for 0.122.0-DEV 00b46fed8 releaser: Bump versions for release of 0.121.1 eb9f1eb65 Upgrade to Go 1.21.5 5186e762a releaser: Prepare repository for 0.122.0-DEV e321c3502 releaser: Bump versions for release of 0.121.0 255e0a971 docs: Regen docshelper 558f3258a build(deps): bump github.com/alecthomas/chroma/v2 from 2.11.1 to 2.12.0 6580cd30a docs: Adjust last merge from docs repository 7617de86c docs: Regen docs helper d19ed4d4e Merge commit '35dec7c96f7ee3eb17dd444f7067f0c776fb56ae' 35dec7c96 Squashed 'docs/' changes from 4d936aee6..4dd2d6415 9f978d387 Pull in the latest code from Go's template packages (#11771) 14d85ec13 tpl: Allow using page resources on the images page parameter for `opengraph`, `schema` and `twitter_cards` templates 171836cdf hugolib: Apply titleCaseStyle to automatic section pages 9ea7103db tpl/urls: Retain query and fragment with absURL and absLangURL 3fc42da3d markup: Add Level to Heading struct d24da1712 tpl/fmt: Print suppression help with erroridf 4583b4130 tpl/transform: Display Chroma highlighting errors 507f4e356 build(deps): bump github.com/tdewolff/minify/v2 from 2.20.8 to 2.20.9 a7e721e02 build(deps): bump github.com/spf13/cast from 1.5.1 to 1.6.0 2627b91d3 build(deps): bump github.com/getkin/kin-openapi from 0.121.0 to 0.122.0 6d4b01241 github: Fix CI build on Windows e536d461a build(deps): bump golang.org/x/image from 0.13.0 to 0.14.0 bfc325f56 deps: Update github.com/tdewolff/minify/v2 v2.20.7 => v2.20.8 36a60f65d build(deps): bump github.com/spf13/afero from 1.10.0 to 1.11.0 de2fcc5e1 build(deps): bump github.com/evanw/esbuild from 0.19.7 to 0.19.8 26a8ec207 Fix handling of dropped error in test 9ca889ba4 build(deps): bump google.golang.org/api from 0.151.0 to 0.152.0 e2a624dd6 common/para: Skip flaky test on CI 4fb40ee87 deps: Upgrade to libwebp 1.3.2 bc93a3613 build(deps): bump github.com/aws/aws-sdk-go from 1.48.4 to 1.48.6 3e5bc6f3b build(deps): bump golang.org/x/tools from 0.15.0 to 0.16.0 7c47036f1 build(deps): bump github.com/getkin/kin-openapi from 0.120.0 to 0.121.0 4d07e1fe8 build(deps): bump github.com/bep/logg from 0.3.0 to 0.4.0 1c41232e6 deps: Upgrade to github.com/bep/simplecobra v0.4.0 f11ca0fad build(deps): bump github.com/aws/aws-sdk-go from 1.48.2 to 1.48.4 30a18e882 watcher: Skip flaky test for now d7a2f3f98 build(deps): bump golang.org/x/tools from 0.14.0 to 0.15.0 b4c5df42f tpl/transform: Add transform.XMLEscape template function ef12d169c build(deps): bump github.com/gorilla/websocket from 1.5.0 to 1.5.1 a62bbfa9e build(deps): bump github.com/fatih/color from 1.15.0 to 1.16.0 8d32ca223 tpl/tplimpl: Remove superfluous type attr on script elements 5887230b7 build(deps): bump golang.org/x/net from 0.17.0 to 0.18.0 a4a66b821 build(deps): bump github.com/evanw/esbuild from 0.19.5 to 0.19.7 813390b5a build(deps): bump github.com/alecthomas/chroma/v2 from 2.10.0 to 2.11.1 d528bbd6d build(deps): bump github.com/tdewolff/minify/v2 from 2.20.5 to 2.20.7 af7f6c8b3 build(deps): bump google.golang.org/api from 0.138.0 to 0.151.0 e70849ea7 build(deps): bump github.com/aws/aws-sdk-go from 1.45.14 to 1.48.2 (#11724) dd6cd6268 resources/resource: Fix GroupByParamDate with raw TOML dates 27620daa2 common/para: Skip flaky tests on Windows 80d2fdbaa navigation: Unexport menu entry methods 805cc1773 markup/goldmark: Sync image render hook code with Goldmark 0bde6931a helpers: Fix TrimShortHTML used by markdownify and RenderString ac7cffa7e releaser: Prepare repository for 0.121.0-DEV f11bca5fe releaser: Bump versions for release of 0.120.4 9315a2d2c Upgrade to go 1.21.4 cee3a56a9 Add a new test helper da2a8e640 releaser: Prepare repository for 0.121.0-DEV a4892a07b releaser: Bump versions for release of 0.120.3 cb98e9061 tpl/tplimpl: Fix deprecation logic in embedded templates 5fa97ee96 Remove some old and unused deprecation code 4d38f4725 Add a field prefix to the deprecated log statements 80f793c38 Avoid double printing INFO deprecation messages a9079d7a6 build(deps): bump github.com/tdewolff/parse/v2 from 2.7.1 to 2.7.3 4914b7f18 build(deps): bump github.com/tdewolff/minify/v2 from 2.20.1 to 2.20.5 9e06fd339 releaser: Prepare repository for 0.121.0-DEV 9c2b2414d releaser: Bump versions for release of 0.120.2 ab2143368 Fix deprecation printing on info level 23fcfb7f7 tpl/tplimpl: Fix deprecation logic in RSS template 47bf2fcbe releaser: Prepare repository for 0.121.0-DEV 16fb2cae8 releaser: Bump versions for release of 0.120.1 2bedcf3d1 deps: Update github.com/tdewolff/minify/v2 v2.20.0 => v2.20.1 935999e2f releaser: Prepare repository for 0.121.0-DEV 20c3bae2c releaser: Bump versions for release of 0.120.0 29b6e133a docs: Regen docshelper 7f8ab7468 Add Solaris build 59bcc098c build(deps): bump github.com/fsnotify/fsnotify from 1.6.0 to 1.7.0 e26ba752d build(deps): bump github.com/google/go-cmp from 0.5.9 to 0.6.0 bcf07fa63 build(deps): bump github.com/alecthomas/chroma/v2 from 2.9.1 to 2.10.0 b6a756813 Make site.BaseURL and $pager.URL a string acf01bfb7 create/skeletons: Fix menu template 27b22cd87 commands/new: Remove format flag from new content cmd a2488b1c9 hugolib: Display correct markup identifier in error message 8f60c0c1e livereloadinject: Save some allocations 9dc608084 livereloadinject: Use more robust injection method a349aafb7 tpl/urls: Return strings from URL functions b8fbd4a57 transform/livereloadinject: Add benchmark e2b2092ce build(deps): bump golang.org/x/tools from 0.13.0 to 0.14.0 f4df7b88b build(deps): bump github.com/tdewolff/minify/v2 from 2.12.9 to 2.20.0 3d9bd404e build(deps): bump github.com/mattn/go-isatty from 0.0.19 to 0.0.20 5f5e55aa8 build(deps): bump golang.org/x/image from 0.12.0 to 0.13.0 aaaf1c8df Squashed 'docs/' changes from 417593493..4d936aee6 0baa4f983 Merge commit 'aaaf1c8df5d6aa061609d20510f7fa6c42e5cc1a' d3d4ab41a docs: Regenerate docshelper 28d844642 Revert "modules: Throttle the "downloading modules …" log entries" eb5fd3127 Revert "modules: Adjust the log throttle logic a little" 3ed28e4bf resources/images: Create padding image filter db14238ba markup/goldmark: Update the CJK extension to allow specifying line break styles 3f64b5a3d modules: Adjust the log throttle logic a little 66904097e modules: Throttle the "downloading modules …" log entries e54139c85 tpl/collections: Make delimit return a string 3710a5ec7 Squashed 'docs/' changes from cb18a5183..417593493 705e3cd5f Merge commit '3710a5ec7efe6baca6e452f43632c05d22bab3c4' 8c61fd254 build(deps): bump golang.org/x/net from 0.15.0 to 0.17.0 d3145e4e5 build(deps): bump github.com/evanw/esbuild from 0.19.3 to 0.19.5 743a1da3e build(deps): bump github.com/spf13/afero from 1.9.5 to 1.10.0 123901b74 build(deps): bump github.com/bep/logg from 0.2.0 to 0.3.0 71fd79a3f Revise the deprecation logging c4a530f10 Remove rest of the now unused emoji code 272484f8b markdown: Pass emoji codes to yuin/goldmark-emoji de4e46603 Fix so hugo get -u updates transitively c23a0c4a0 watcher/filenotify: Remove redundant duplicated comments a95670b98 docs: Remove outdated note from CONTRIBUTING.md 46bdc0388 tpl/debug: Add average and median to timer output 5160c7efa tpl/debug: Add debug.Timer e2dd4cd05 Merge commit 'e509cac533600cf4fa8382c9cdab78ddd82db688' e509cac53 Squashed 'docs/' changes from 7ef2dbce4..cb18a5183 fd3817181 Add some convenient integration test helpers 2eca1b3cc hugolib: Deprecate .Site.DisqusShortname 625162674 tpl/tplimpl: Fix dropped error a692278bc hugolib: Deprecate .Site.GoogleAnalytics d4016dd5c tpl/tplimpl: Deprecate .Site.Author usage in RSS template 4910312ee tpl/tplimpl: Deprecate .Site.Social usage with internal templates 1b5f78b6b markup/tableofcontents: Return template.HTML from .Fragments.ToHTML d5d0f420d deps: Update github.com/tdewolff/minify/v2 v2.12.7 => v2.12.9 5993afa4c commands: Update message displayed when running CLI from GUI d1b445853 common/hugo: Add hugo.IsServer and hugo.IsDevelopment 274852bcf all: Format files with gofmt 37a2d5eb4 magefile: Update isGoLatest to check for Go 1.21 4c95389c2 resources/integrity: Return string instead of template.HTMLAttr 3af8bded2 Update README.md 46da0b7aa tpl/lang: Formally deprecate lang.NumFmt 75f56b4ce tpl/collections: Fix and deprecate echoParams d234a963e releaser: Prepare repository for 0.120.0-DEV b84644c00 releaser: Bump versions for release of 0.119.0 a9d19dbdd docs: Even more about images.Process 12d713176 docs: More about images.Process 6b65b2fae common: Remove unused constants 1768684d8 docs: Regen docshelper 9aec42c54 Squashed 'docs/' changes from 686c7b6eb..7ef2dbce4 eb0ed33df Merge commit '9aec42c5452b3eb224888c50ba1c3f3b68a447e9' 6a246d115 Add images.Process filter ef0e7149d Add $image.Process c32094ace google_analytics_async.html: Add deprecation warning a262fd4dd build(deps): bump golang.org/x/tools from 0.12.0 to 0.13.0 f0d32455d build(deps): bump github.com/alecthomas/chroma/v2 from 2.8.0 to 2.9.1 e8bc8e6d0 build(deps): bump github.com/evanw/esbuild from 0.19.2 to 0.19.3 f9b3c0f48 Add images.Opacity filter 11fcda971 build(deps): bump github.com/aws/aws-sdk-go from 1.44.314 to 1.45.14 f31375d4c build(deps): bump github.com/getkin/kin-openapi from 0.118.0 to 0.120.0 6415b599b build(deps): bump golang.org/x/image from 0.11.0 to 0.12.0 1e9b87f76 Upgrade to Go 1.21.1 275c0acbf commands: Update CLI docs with the important -u flag in hugo mod get f9163155d create/skeletons: Improve viewport meta tag 79a17d9e5 Fix tests for Go 1.21.1 75c0f8828 commands/gen: Remove default highlight style 18ce85462 Fix recently broken benchmark 69f5bad40 Adjust baseline benchmarks 525bed991 commands: Print language code after web server address info 2ae4786ca releaser: Prepare repository for 0.119.0-DEV da7983ac4 releaser: Bump versions for release of 0.118.2 df5d76fed release: Revert to building with Go 1.20 7362ba220 releaser: Prepare repository for 0.119.0-DEV 0eb480aa1 releaser: Bump versions for release of 0.118.1 7e9092eee Revert to bullseye as the release build image 0200eaf58 releaser: Prepare repository for 0.119.0-DEV 28b640a22 releaser: Bump versions for release of 0.118.0 db45dbbee Merge commit '77b976dd92b4f66657d83d875aef0c617df492d9' 77b976dd9 Squashed 'docs/' changes from a7e1e9be8..686c7b6eb e847a98db docs: Regen docs helper 45c9bbc6c Don't use the OS environment when creating config for docs 94fbab2a8 Delay the creation of cache directories until they're used c3f273b2d deploy: Create AWS session for CloudFront invalidation via Go CDK d7dcc76d2 markup/goldmark: Add CJK extension 9bf76fd7e build(deps): bump google.golang.org/api from 0.134.0 to 0.138.0 15d3e48ce Fix RegularPagesRecursive for the home page b2a02c3c5 build(deps): bump golang.org/x/tools from 0.11.1 to 0.12.0 6821d6f15 build(deps): bump gocloud.dev from 0.33.0 to 0.34.0 93c7ad12e build(deps): bump github.com/pelletier/go-toml/v2 from 2.0.9 to 2.1.0 d2ae9e136 testscripts: Move hugo new tests to where they belong 3a8aad6b1 Fix .RawContent for empty content pages (#11407) a7b93e656 hugolib: Handle dropped error 65871d5cf common/loggers: Fix typo in option name 2e4bf89ec misc: Change dart-sass labels in workflows and snapcraft ebaa733d4 Make sure resources directory isn't created in hugo new theme 24b1be45c Go 1.21 Upgrade 111f02db2 testscripts: Make mod vendor test stable 8a08f91d5 dockerfile: Update Docker images dcf425c84 Fix it so disable a module does not disable transitive dependency required by others 9a8c84d60 create/skeletons: Move theme's site config to top level a19d03b0e build(deps): bump github.com/yuin/goldmark from 1.5.5 to 1.5.6 cdf0b3b7a modules: Make new cache directories read/write d979831db deploy: Update InvalidateCloudFront to use Go CDK helper bcf7421ea Avoid escaping HTML chars inside hugo_stats.json b6538532f commands/new: Embed site and theme skeletons 90944aa26 docshelper: Improve template lookup order descriptions db7bc4969 build(deps): bump github.com/evanw/esbuild from 0.18.17 to 0.19.2 a2f6400d6 cache: Hide IsResourceDir from the exported config 7d74cd0cc commands: Handle floats without decimals in hugo config d139f3023 docs: Replace docs.json with docs.yaml b1b691241 config: Add a type value for the tags related config entry 0de81c643 build(deps): bump golang.org/x/net from 0.13.0 to 0.14.0 851bf3515 Add all config to docshelper.json d4a6c16c1 build(deps): bump golang.org/x/image from 0.10.0 to 0.11.0 5d5fb22ea Merge commit '7c62d6ef1654c0383eae474d3bd9ddf7754c1f30' 7c62d6ef1 Squashed 'docs/' changes from c43daf45f..a7e1e9be8 641390f8f Try to make test more stable 2e6191b2e deps: Sync go-i18n with upstream 22861cb4d Return original error on resources.GetRemote retry timeouts 16da1ade7 testing: Write test caches to /tmp a3d42a277 Add retry in resources.GetRemote for temporary HTTP errors 2c20fd557 build(deps): bump gocloud.dev from 0.24.0 to 0.33.0 243736e75 build(deps): bump golang.org/x/net from 0.11.0 to 0.13.0 bf891c225 build(deps): bump github.com/marekm4/color-extractor from 1.2.0 to 1.2.1 da0df0ada build(deps): bump github.com/frankban/quicktest from 1.14.5 to 1.14.6 0885f8ec2 build(deps): bump golang.org/x/image from 0.9.0 to 0.10.0 61be050a9 build(deps): bump github.com/clbanning/mxj/v2 from 2.5.7 to 2.7.0 65af75fb0 build(deps): bump golang.org/x/tools from 0.9.3 to 0.11.1 2d75f74b8 build(deps): bump go.uber.org/automaxprocs from 1.5.2 to 1.5.3 2ac3d6160 build(deps): bump github.com/hairyhenderson/go-codeowners ade7ec818 Add Page.RenderShortcodes 8fa8ce3e4 Update GitHub issue template 9dce45c25 build(deps): bump github.com/pelletier/go-toml/v2 from 2.0.8 to 2.0.9 239f2e2c9 releaser: Prepare repository for 0.117.0-DEV 3e1ea030a releaser: Bump versions for release of 0.116.1 30885a6c5 Fix module config watch regression 58da8554c deps: Fix Chroma dependency version 92c159437 releaser: Prepare repository for 0.117.0-DEV 5a7e0da84 releaser: Bump versions for release of 0.116.0 d7db096a9 build(deps): bump github.com/evanw/esbuild from 0.18.11 to 0.18.17 c1df5b1b0 config: Do not fail on unknown config keys be8e2de59 resources: Fix spelling in method name d297c8e1b docs: Regenerate CLI docs fbb8eb39e Fix so temporary images do not get published 87d9bffe7 readme: Fix link d9fdcbe93 commands: Update cacheDir description 295d73388 Update where.md d5247788e docs: Update where 036e260d8 docs: Update where function operators a50356b9a docs: Rework the cacheDir documentation 8859be1c0 Merge commit '87de22d7464e239c775fbd48ebce1665d5b1e80d' 87de22d74 Squashed 'docs/' changes from 85befbb4d..c43daf45f bec9b80d9 Deprecate taxonomyTerm 1c97095ac Warn about unknown kinds in disableKinds b3cb6788b Move all Kind constants to its own package 5542f02fb build(deps): bump github.com/rogpeppe/go-internal 0bc7ed9a1 build(deps): bump golang.org/x/image from 0.8.0 to 0.9.0 36b512605 Remove unused autogenerated method 2589b1295 commands: Replace deprecated ioutil with os ef6e813ca tpl/collections: Add BenchmarkWhereOps f4598a098 tpl/collections: Add like operator to where function dc2a544fa tpl/collections: Fix description of apply function 916397320 snap: Set cache location to $HOME/.cache/hugo_cache b3f10556f Use os.UserCacheDir as first fallback if cacheDir is not set 4d7af757c Add a common regexp cache 7f058b8ba Fix multiple languages in HUGO_DISABLELANGUAGES 575d7f806 snap: Allow access to SSH keys and $HOME/.config/hugo 739d10e8b deps: Upgrade github.com/yuin/goldmark v1.5.4 => v1.5.5 0dbe0f1a0 releaser: Prepare repository for 0.116.0-DEV dc9524521 releaser: Bump versions for release of 0.115.4 d70b6c7d0 Fix broken handling of legacy taxonomyTerm in disableKinds d947db371 commands: Move testscript into its correct place d8c94c354 publisher: Improve class collector for dynamic classes 6bbec9001 Fix cache busting setup 5bd22ba85 commands: Delay server builds after the watcher is set up 7ae62f4aa Create hugo_stats.json if it's mounted but does not exists f1a061e9e Re-instate disableLiveReload as a config option (and not just a flag) 2f11e673c common/htime: Fix localization of abbreviated month names 387c5f60f Improve error messages for PostCSS etc. c406fd3a0 Fix setting config from env with complex (e.g. YAML) strings 286821e36 Fix for data mounts in sub folders 79f15be5b releaser: Prepare repository for 0.116.0-DEV 5c2e014a5 releaser: Bump versions for release of 0.115.3 cc44583cc Improve behavior of defaultContentLanguageInSubdir when only the default language is enabled 4da672af8 Return error when .Render is invoked without arg f1886f8c3 js: Pass tsconfig.json to esBuild 5bec50838 tpl/collections: Fix WordCount (etc.) regression in Where, Sort, Delimit f650e4d75 config/allconfig: Update timeout description c934a4506 docs: Refresh docs.json 91b02091a releaser: Prepare repository for 0.116.0-DEV 8966424e0 releaser: Bump versions for release of 0.115.2 72510969a snap: Allow access to AWS, Azure, and GCS config/credentials 70c5e485b snap: Update metadata and security.exec.osEnv a78b17d7f Make imageConfig work with modules a48194253 Restore language.disabled config 0f921ace6 Fix hugo mod vendor for modules with hugo.toml 601995376 Fix static content files multilingual root regression 92e86702e Fix defaultContentLanguageInSubdir with only 1 language 6c9ea022a config: Expand default security.exec.osEnv policy 12d3469dd Add titleCaseStyle none and firstupper bf7ee8a91 Bump github.com/bep/clock v0.3.0 to renamed github.com/bep/clocks v0.5.0 d912491f2 releaser: Prepare repository for 0.116.0-DEV 857374e69 releaser: Bump versions for release of 0.115.1 c27639b9a docs: Regen docs helper ceb486f98 Fix buildStats when tags and classes are disabled 5afc89f2b Rework the build.writeStats struct c1eac616d snap: Explicitly set security.exec.osenv during build 3c8256a13 snap: Restore security.exec.osenv whitelist 19d76ae96 github: Build for Dragonfly in CI build 11ecea610 Make build.writeStats a struct da98724bc build(deps): bump github.com/evanw/esbuild from 0.18.10 to 0.18.11 4d470bb73 build(deps): bump github.com/alecthomas/chroma/v2 from 2.7.0 to 2.8.0 0ff8e13c1 commands: Fix index out of range in hugo mod get ffd37d4f7 Only print the path warnings once b4b65245b Update README.md 87886f40d releaser: Prepare repository for 0.116.0-DEV 67caf5069 releaser: Bump versions for release of 0.115.0 7917961d5 Misc permalinks adjustments 80ecb9589 commands: Handle hugo mod get --help 58e09cc6c Update README.md 635cc346c commands: Fix panic when running hugo new theme without theme name 12646750a Print help message when triggered with no flags 79639c981 Fix output formats and media type per language config regression 9b313cec1 build(deps): bump github.com/evanw/esbuild from 0.18.5 to 0.18.10 b74b8d647 common/collections: Fix append regression to allow appending nil 793e38f5c commands: Fix help message for hugo new theme 7f698c893 Don't panic on invalid security whitelist regexp fa0e16f4c Fix false path warnings with resources.PostProcess 12e4c4d5d docs: Update permalinks documentation bac03f407 Merge branch 'master' of github.com:gohugoio/hugo cc14c6a52 resources/page: Allow section and taxonomy pages to have a permalink configuration e3308a0bb tpl/tplimpl: Fix typo in global variable name 019299b0b commands: Enable format flag with hugo new site 23ed087c4 Update README.md a018259bc Merge branch 'release-0.114.1' ad5e04daa releaser: Prepare repository for 0.115.0-DEV e9b716ad9 releaser: Bump versions for release of 0.114.1 ae31dbdd1 Revert "build(deps): bump gocloud.dev from 0.24.0 to 0.30.0" 5b4bfc2db Fix broken nodeploy setup 92f55f112 build(deps): bump github.com/niklasfasching/go-org from 1.6.6 to 1.7.0 078226dd6 Fix broken nodeploy setup 06d228aad snap: Switch from Embedded Dart Sass to Dart Sass (#11146) b1016d2e2 commands: Make hugo env respect --logLevel 49336bfc5 commands: Update Jekyll post-import output 941818295 build(deps): bump gocloud.dev from 0.24.0 to 0.30.0 5491e5547 build(deps): bump github.com/evanw/esbuild from 0.18.4 to 0.18.5 bf7af9043 deps: Update github.com/tdewolff/minify/v2 v2.12.5 => v2.12.7 5e12bf7dc releaser: Prepare repository for 0.115.0-DEV 9df2ec798 releaser: Bump versions for release of 0.114.0 59300faae Revert "build(deps): bump gocloud.dev from 0.24.0 to 0.29.0" 9f98b3e71 docs: Regen docshelper 3ab84651c Add empty Environ when loading test config 7241b5fd5 docs: Regen CLI docs 6dfbd2479 common/loggers: Drop the bold INFO etc. prefixes f59c3c021 loggers: Avoid using Logf for the LevelLoggerToWriter 3ca29b156 tocss/dartsas: Avoid using Logf for the internal Dart Sass logging fdb0b7fb1 helpers: Remove superflous formatting flag in deprecation warnings 49dd53a40 Revert "deps: Update github.com/tdewolff/minify/v2 v2.12.5 => v2.12.6" 68d9d3ebd all: Fix some typos 9009c8cdc all: Fix typos in function names and comments 12dc9a6e4 deploy: Fix deploy defaults for non-zero flag values (e.g. maxDeletes, invalidateCDN) 1b85303ac common/loggers: Re-add trailing newline in logger.Printf 8a04d47ab build(deps): bump github.com/evanw/esbuild from 0.18.3 to 0.18.4 7c9fada77 Replace the old log setup, with structured logging etc. 0e7944658 Revert "snap: Transition base snap from core20 to core22 (#11101)" (#11125) aaf2e9693 build(deps): bump github.com/evanw/esbuild from 0.18.2 to 0.18.3 ee359df17 Fix upstream Go templates bug with reversed key/value assignment 0f989d5e2 build(deps): bump golang.org/x/sync from 0.2.0 to 0.3.0 f73c56753 common/collections: Always make a copy of the input slice in Append d178fe94f tpl/collections: Fix append when appending a slice to a slice of slices 732dcb848 build(deps): bump google.golang.org/api from 0.123.0 to 0.127.0 944859f1a build(deps): bump golang.org/x/tools from 0.9.1 to 0.9.3 90b2674dd Re-add site.RSSLink (and deprecate it) bb9377b5e build(deps): bump github.com/kyokomi/emoji/v2 from 2.2.11 to 2.2.12 e88f1b80b build(deps): bump github.com/getkin/kin-openapi from 0.117.0 to 0.118.0 516f0cb6c build(deps): bump golang.org/x/net from 0.10.0 to 0.11.0 21d17566a Fix .Width and .Height for animated gifs 35e9b3ed1 snap: Transition base snap from core20 to core22 (#11101) 3c1deaf20 Squashed 'docs/' changes from 1d5548d73..85befbb4d a0009e070 Merge commit '3c1deaf201a35de08d23cc58f8f03682cace3349' 7bed16c30 build(deps): bump gocloud.dev from 0.24.0 to 0.29.0 2ba2271e4 tpl/math: Allow variadic math functions to take slice args, add math.Product, math.Sum 60a2cdf72 Fix config merge regression with root slices (e.g. disableKinds) e08cfc8ca build(deps): bump golang.org/x/image from 0.7.0 to 0.8.0 ef147f4e8 commands: Remove flags log, verboseLog, add flag logLevel, deprecate flags verbose and debug 489519566 build(deps): bump github.com/magefile/mage from 1.14.0 to 1.15.0 91c0b0f76 build(deps): bump github.com/pelletier/go-toml/v2 from 2.0.6 to 2.0.8 baef235d5 build(deps): bump github.com/evanw/esbuild from 0.17.19 to 0.18.2 0541a1b57 Fix handling of aliases (e.g. hugo serve) 258884f44 cache: Set default cache path based on $USER 254c2b323 build(deps): bump go.uber.org/atomic from 1.10.0 to 1.11.0 84f71ba8f build(deps): bump github.com/hairyhenderson/go-codeowners 69f0e88a4 resources: Remove failing and superflous test assertion 82adc972e build(deps): bump github.com/frankban/quicktest from 1.14.4 to 1.14.5 60533fdc0 build(deps): bump github.com/mattn/go-isatty from 0.0.17 to 0.0.19 261143bbb build(deps): bump github.com/spf13/afero from 1.9.3 to 1.9.5 b8526f32f commands,config: Fix typo in log and error messages ed7e25006 helpers: Avoid url.Parse in RelURL and AbsURL if we can 6a09e7f28 Adjust benchmarks 29e5cbb69 Adjust benchmark ded686600 Add BenchmarkAbsURL e1d43021c helpers: Improve schema detection when creating relative URLs 5db215d4d helpers: Add a basic benchmark for RelURL b7dc93ca1 config: Remove unexpected _merge keys introduced in author and social maps f210188da Upgrade to v2 of the Dart Sass Embedded Protocol c782ebd89 Fix indented SASS imports for Dart Sass 73779707a releaser: Prepare repository for 0.114.0-DEV 085c1b3d6 releaser: Bump versions for release of 0.113.0 6c955cc3d docs: Regenerate CLI docs 5446900de commands: Update CLI docs vs server and production cf38c73f5 commands: Add TLS/HTTPS support to hugo server 536bf71ab releaser: Prepare repository for 0.113.0-DEV ea3c95a7b releaser: Bump versions for release of 0.112.7 5e5ce00d4 Fix menuItem.URL when pageRef is not set a191b38ac Don't inject livereload script on hugo -w 382c726e6 markup: Fix typo in function and struct names 4c46f9400 all: Replace deprecated ioutil with io and os 8c7a4e995 releaser: Prepare repository for 0.113.0-DEV 2ca0fcc44 releaser: Bump versions for release of 0.112.6 a6d774e80 docs: Regenerate CLI docs dfb1895e4 Squashed 'docs/' changes from 1798dc0d5..1d5548d73 9e4072ac2 Merge commit 'dfb1895e4b82b2249d9baaed37ac7ae5e855a126' 0ef295284 commands: Add --lang to hugo config e3ae8f025 Make sure any default mounts show up in "hugo config" 06faee5be github: Fix Windows build 409c6c3fc deps: Update github.com/tdewolff/minify/v2 v2.12.5 => v2.12.6 ff77a927f tpl/tplimpl: Use .Language.LanguageCode in built-in templates 9cdca1f95 Fail on invalid defaultContentLanguage 6462eecfb Avoid panic in invalid language config a7d6b1413 Don't panic on empty yaml config params 3f497d496 Prevent double escaping of image alt-text in Goldmar typographer 32585696b Fix potential deadlock in ByParam d47225ce9 releaser: Bump versions for release of 0.112.5 e3dfc76fa Fix it so languageCode on top level config still works cd59216de releaser: Prepare repository for 0.113.0-DEV e285153d7 releaser: Bump versions for release of 0.112.4 20ea2e0c6 docs: Regenerate CLI docs 51d0a0ab0 commands: Add the common build flags to the config commands fd099331e Fix Processed images count regression for multiple languages 43f1282e7 commands: Reinstate some of the removed build flags (e.g. --theme) to new and mod e96cdfe96 Don't create the public folder unless needed ffdbce578 docs: Regen CLI docs a838a27e4 Merge commit 'd3927310d5b2404c3238f9b899db3329ea516490' d3927310d Squashed 'docs/' changes from 39af43ef1..1798dc0d5 273d9f69a commands: Fail the build when no config file or config dir a6257d8a4 langs: Remove the Language.Params deprecation message for now 6c2db0dfb Add language.LanguageCode 8f293a185 Fix --renderStaticToDisk regression 901cd970d commands: Re-introduce the -f shorthand for hugo new site f86b5f70a commands: Move the --format flag to only the commands that support it 3297b395d releaser: Prepare repository for 0.113.0-DEV ba6f74e40 releaser: Bump versions for release of 0.112.3 231374a1f Fix regression when loading config -e is empty or HUGO_ENV or HUGO_ENVIRONMENT is set 5adc83790 releaser: Prepare repository for 0.113.0-DEV f89108f2b releaser: Bump versions for release of 0.112.2 dd6792201 minifiers: Make sure JS.Version always has a value 9a235d0af Fix regression with site.IsServer when not running a server 99407c39b releaser: Prepare repository for 0.113.0-DEV 7c90c19d2 releaser: Bump versions for release of 0.112.1 ed906a86e Fix regression when config for OutputFormat.BaseName is an empty string d666edad7 releaser: Prepare repository for 0.113.0-DEV 0a95d6704 releaser: Bump versions for release of 0.112.0 70b2aaf87 circleci: Add github.com to known hosts f01492115 Revert "build(deps): bump gocloud.dev from 0.24.0 to 0.29.0" bd38e35f9 Revert "postcss: Improve validation of option 'config'" 85b13c105 Add --format to hugo config b6e6438f7 docs: Regen docshelper 943ff7f7c commands: Add missing gen docshelper command 288be1976 Fix "unknown command" message when no suggestion 9a0370e8e postcss: Improve validation of option 'config' 10d0fcc01 docs: Regen CLI docs b95e15694 Merge commit 'f96384a3b596f9bc0a3a035970b09b2c601f0ccb' f96384a3b Squashed 'docs/' changes from 6e32d0591..39af43ef1 4cac5f5e3 Avoid writing to hugo_stats.json when there are no changes 2c3d4dfb7 Add cache busting config to support Tailwind 3 1292d5a26 build(deps): bump github.com/tdewolff/parse/v2 from 2.6.5 to 2.6.6 baa556904 build(deps): bump gocloud.dev from 0.24.0 to 0.29.0 a5413c1f8 build(deps): bump github.com/gobuffalo/flect from 0.3.0 to 1.0.2 9cea58a8a build(deps): bump golang.org/x/image from 0.5.0 to 0.7.0 1a5dce4cc build(deps): bump github.com/tdewolff/minify/v2 from 2.12.4 to 2.12.5 6ca8a40f2 commands: Make all list commands list what 'all' did before 2db7ec622 tpl/tplimpl: Add img loading attribute to figure shortcode (#10927) e6dc8053b commands: Fix build logic when listing expired/future draft content 2637b4ef4 Allow whitelisting mediaTypes used in resources.GetRemote 7c7baa618 Add hugo.WorkingDir 4f085e80d Make language merging of markup etc. config without values in the root 150d190ff tpl/urls: Return empty string when JoinPath has zero args 065ae003a build(deps): bump github.com/dustin/go-humanize from 1.0.0 to 1.0.1 1a7d57c0b build(deps): bump google.golang.org/api from 0.76.0 to 0.123.0 bba54e694 build(deps): bump golang.org/x/tools from 0.4.0 to 0.9.1 737054311 build(deps): bump github.com/cli/safeexec from 1.0.0 to 1.0.1 f6269ee92 build(deps): bump github.com/getkin/kin-openapi from 0.110.0 to 0.117.0 715d48404 deps: Update github.com/evanw/esbuild v0.17.0 => v0.17.19 0a51dfac9 commands: Fix data race c371171ab deps: Update github.com/alecthomas/chroma/v2 v2.7.0 d6197a41f Re-add --printUnusedTemplates and --printPathWarnings e4e0313c8 tpl/urls: Fix build broken by a merge 5b3e165ba tpl/urls: Add JoinPath template function 03cb38e6c Allow legacy taxonomyTerm in disableKinds ad4bc969d Fix warn message about custom params on the language top level 4003c7903 Fix some spelling mistakes 610cedaa6 all: Fix comments for exported functions and packages 24e7d0c17 deps: Update github.com/bep/golibsass v1.1.0 => v1.1.1 008170c8a Make GOMAXPROCS to be CPU limit aware 7c647bcae Allow empty params.mainSections 95818e27d modules: Fix format flag in error 3f00f4753 commands: Load config before creating the filesystem 834b3d7e4 Fix some recently introduced error handling issues 1155bbca9 tpl/lang: document delimiter option for FormatNumberCustom 86b2a2743 Re-add site.LanguagePrefix 35955f50e github: Trim the test flow a little 8a69ccbb0 commands: Improve the common build flag handling 7ce033a89 Support, but warn, about top level language custom params 05542130b Handle transient errors in config loading etc. 5251f015b Re-establish all the server flags 5d857165f Deprecate site.Language.Params and some other fixes 0106cf1a6 Revert "Make GOMAXPROCS CPU limit aware" 59050f97f Make GOMAXPROCS CPU limit aware faa6998f2 Add Sections to Site interface 3d90871e9 helpers: simplify path tests with T.TempDir bda082c98 tpl: Add math.Abs 241b21b0f Create a struct with all of Hugo's config options 6aededf6b Improve date parsing performance for the common case 0988b76a7 Add a counter helper e0e19a934 Expand the baseline benchmark a little bcd7ac770 Revert "Update syntax-highlighting.md (#10929)" (#10930) a4fb8dc6b Update syntax-highlighting.md (#10929) 4f341fa1a Update README.md 5c7b79cf7 tpl/strings: Clarify findRESubmatch description 0cb6ca590 langs/i18n: Fallback to defaultContentLanguage instead of English f1062519a tpl/debug: Add VisualizeSpaces 46a3cf618 Update README.md 9906c1ae5 Prevent the global error collector to panic when sending on closed channel 5596dc24a markup/goldmark: Add config options for the typographer extension d01731d53 readme: Fix build command f1e8f010f Update README.md 5748133d5 Add test for ToC vs include 05c095a0e resources.functions: improve validation 891b2918d resources: Fix typos in error message and variables b0b1b76dc markup/goldmark: Fail on invalid Markdown attributes 0fbab7cbc commands: Fix data race in test f5eddf89b tpl/math: Return error if less than 2 input numbers 0e8ab20a8 releaser: Prepare repository for 0.112.0-DEV 5d4eb5154 releaser: Bump versions for release of 0.111.3 1c841ec91 deps: Update go-org to v1.6.6 e7148f335 Fix "unknown shortcode token" when calling shortcode within fenced code block d55af2abf Run gofmt -s on source files b6f44aaf1 docs: Improve examples of variadic math functions 84201e8d5 tpl/math: Allow multi numbers in add, sub, mul, div, min and max 04b981164 readme: Update dependency list 9818724b5 Improve error message for unclosed shortcode with inner content 34a86e13f Don't fail when calling Paginate with an empty pages.PagesGroup 0f01bd463 server: Replace golang.org/x/net/context with context d171d1543 tpl: Add hasSuffix alias 02ab77da3 watcher: use time.NewTicker to prevent leaks 873be9f90 ensure we default to 10 correctly bebb2b8d0 switch transfers to workers e6f029bde customize parallel transfer count bdbfacb86 metadecoders: Add support for native org dates in frontmatter PR #7433 added support for Org timestamps for the DATE header. This PR widens the support with additional front matter headers LASTMOD, PUBLISHDATE and EXPIRYDATE. 32ea40aa8 releaser: Prepare repository for 0.112.0-DEV 4164f8fef releaser: Bump versions for release of 0.111.2 b83050cb4 Fix .Fragments when called cross sites on uninitialized output format df5608f8a Allow page.TableOfContents on self in shortcode f56ce01ae tpl/partial: Consolidate GoDoc 3bbeb5688 Fix "context canceled" with partial 184a67ac4 cache: Fix --gc failure on Windows 6c798eba6 Page context handling in i18n ec1c97e7e Work around --gc failure on Windows <= 10 f10009e7f Update to Go 1.20.1 a950950f1 snap: Fix dart-sass-embedded installation 36ce3a4a9 Correct typos in Go comments 17e60b77e releaser: Prepare repository for 0.112.0-DEV 39a4a3cf6 releaser: Bump versions for release of 0.111.1 52f339dad Merge branch 'release-0.111.0' eef23a7f2 Fix "page" not defined 18cf75805 releaser: Prepare repository for 0.112.0-DEV 3fa8bb831 releaser: Bump versions for release of 0.111.0 db9f74d24 Revert "build(deps): bump gocloud.dev from 0.24.0 to 0.28.0 (#10610)" 60e6fa798 build: Bump build images 7e51ba03c build: Update Linux ARM build image 66f94b494 tpl/tplimpl: Remove the Google News internal template c0d15a289 strings: fix Truncate behavior for formatted html 2a61910e8 tpl/strings: Adjust benchmark 079d1b654 tpl/strings: Add BenchmarkTruncate a56b9071d cods: Regen docs helper 5c317c55e Move the Related doc counter to prevent a race a669467d9 Misc ioutil deprecation adjustments d453c1274 Replace deprecated ioutil with io and os 336622d5e Squashed 'docs/' changes from 36dd5483f..6e32d0591 97b010f52 Merge commit '336622d5e7afd9334cd2de7150d4f16bdf7c24f9' 4d36b99a4 build(deps): bump github.com/tdewolff/parse/v2 from 2.6.4 to 2.6.5 807237bc0 build(deps): bump github.com/mattn/go-isatty from 0.0.16 to 0.0.17 79b03b3f7 build(deps): bump golang.org/x/image e31441031 Remove unused temp directory 39cc3a2a7 exif: Return the proper exposure time value in some special cases ce524d0b5 Add a page template func 2662faf61 dartsass: Import CSS without extension at compile time 271318ad7 Split parse and render for Goldmark e442a63bb related: Add config option cardinalityThreshold d5601e839 docs: Another fix related docs example cedd04db3 docs: Fix related docs example 4bf91b975 build(deps): bump golang.org/x/net from 0.4.0 to 0.7.0 ae48507d6 Fix shortcode error when closing without .Inner 7d78a498e Throw an error when shortcode is expected to be closed 0dbeac80c Add some shortcode testcases b99d073ca sass: Remove some unused leftover code e965cb679 resources/sass: Remove debug statements cf591b7c0 Squashed 'docs/' changes from 1214f6ffb..36dd5483f 7e539cb39 Merge commit 'cf591b7c0c598d34896709db6d28598da37e3ff6' 586fea0de page: Move the cache double check right after the lock fa2d7adf1 page: Add some concurrency to the building of the related page index 4346987fa related: Adjust benchmark 2dad13c0e create: Fix typo in error message ecf3cd514 tocss: Simplify the hugo:vars type handling a1a9c08b5 resource_transformers/tocss: Fixed hugo:vars casting 6abd15e78 Adjust tests for GO 1.20 094135ff9 tpl/internal: Sync Go template src to Go 1.20 4801e2e8e build: Update to Go 1.20 90da7664b Add page fragments support to Related 0afec0a9f related: Adjust benchmark 28540ed13 related: Add benchmark 9af78d110 tpl/collections: Improve error message in Index d33a7ebcc Make the HTML collector parsing more robust 2a364cca6 Revert "build(deps): bump github.com/getkin/kin-openapi from 0.110.0 to 0.114.0" 3fb2417cb deps: Upgrade github.com/yuin/goldmark v1.5.3 => v1.5.4 fce089048 tpl/strings: Add strings.ContainsNonSpace 87c78bd3e build(deps): bump github.com/getkin/kin-openapi from 0.110.0 to 0.114.0 69c369e11 deps: Upgrade github.com/alecthomas/chroma v2.4.0 => v2.5.0 73ece30d8 markup: Fix linenos codeblock hl option case regression f9fc0e045 Fix slow HTML elements collector for the pre case 4f4a1c00b publisher: Add benchmark 76c6140c5 snap: Install dart-sass-embedded for 32-bit ARM (armhf) too d4482e8bf snap: Add read access for ~/.gitconfig.local and ~/.config/git/* too 1477d0ba9 commands: Fix server url rewrites (http status 200) dd37163f5 build(deps): bump github.com/kyokomi/emoji/v2 from 2.2.10 to 2.2.11 c3a59a7d5 build(deps): bump gocloud.dev from 0.24.0 to 0.28.0 (#10610) 4ccc8cfb4 Fix description of collections.Uniq e2cfc3d5a Update CONTRIBUTING.md 168858331 Fix shortcode detection in RenderString 4ef9baf5b Only invoke a given cached partial once 93ed6e447 Update README.md 0d1161b26 releaser: Prepare repository for 0.111.0-DEV e32a493b7 releaser: Bump versions for release of 0.110.0 19e960562 dos: Regen CLI docs 80e8bd3b7 docs: Regen docshelper b661132e0 Merge commit 'ef6f101e75256c3bb88a6f1f3b5c1273bf8d7382' ef6f101e7 Squashed 'docs/' changes from 2c0125b52..1214f6ffb d59541903 related: Handly []any 671f64b2e Fix permalinks issue with repeated sections 2fb40ece5 tpl/strings: Add findRESubmatch c6b388769 config/security: Add O\w+ (e.g. GOROOT) to the default allowed list 21af5b359 Preserve front matter slice value types (e.g. int) f38a2fbd2 Make hugo.toml the new config.toml 6a579ebac Add fill HTTP Response info into .Data in resources.GetRemote f13531e60 Fix HEAD method in resources.GetRemote b5d485060 Fix order when reading custom headers in resources.GetRemote 6e9fa9e0f deps: Upgrade github.com/evanw/esbuild v0.15.18 => v0.17.0 c4f3a46ce Update README.md fbc3e08c6 resource: Fix Go Doc vs .Data.Integrity e402d91ee Misc doc, code refactoring to improve documentation 3c51625c7 Make readFile return nil when file not found (note) dd6d0a6de Remove reference to Goreleaser in code comment f95fd57aa tpl/compare: Sort special float values as string e754d5cb3 tpl/diagrams: Move Goat to its own file 002cd5280 Update CONTRIBUTING.md a76c405d4 Update CONTRIBUTING.md c0a03a2a3 Update README.md e127d3e5c releaser: Prepare repository for 0.110.0-DEV 47b12b83e releaser: Bump versions for release of 0.109.0 180dfeba0 Adjust "you need the extended version" error message 10bb29d7f docs: Regen docs helper JSON eb0c8f9d0 resource/page: Slight adjustment of Page.Ancestors 3a216186b resource/page: Add Page.Ancestors 7874b9681 build(deps): bump golang.org/x/tools from 0.3.0 to 0.4.0 71832328f Annotate test assertions 37ab1cf12 hugolib: Exclude non-linkable pages from translations map 59af05cab Add HUGO_PUBLISHDIR to the Node environment 4989da653 Revert "tpl/tplimpl: Use https in sitemap templates" cd1ed563a tpl: Improve template funcs GoDoc aa2c72419 tpl/resources: Fix data race in ToCSS effa6a422 tocss: Add some more test cases 5d5f0a237 tocss: Fix unquote case with double quotes d20d2651e Allow "fast render mode" even if --disableLiveReload is set 41a080b26 tocss: Add vars option 41bc6f702 Squashed 'docs/' changes from 2201ac0e5..2c0125b52 9a215d695 Merge commit '41bc6f702aa54200530efbf4267e5c823df3028d' eda1e720c modules: Improve "module workspace" not found error 330fa8941 modules: Adjust watch logic vs workspace use definitions 6db527483 Add any configured Go Workspace file to the config watcher 0d4b17d4c modules: Make the module.workspace=off as default (note) 3afaca758 release: Add a note section in release notes 2d217cba5 helpers: Allow at signs in UnicodeSanitize (note) 17055d1fa parser/metadecoders: Remove superflous cast in test 2a81a4949 parser/metadecoders: Simplify nil check in Unmarshal e30d711c2 parser/metadecoders: Add empty /data JSON file as empty map ad2059878 Also consider wrapped errors when checking for file IsNotExist errors 87e898a17 tpl/openapi3: Wrap *kopenapi3.T b54de1bd9 resources/js: Fix some import discrepancies between Hugo and ESBuild c9354d546 github: Update to Dart Sass 1.56.2 d89426985 github: Use ruby/setup-ruby 3fd0b7849 tpl/tplimpl: Use https in sitemap templates e0e63f35e parser/metadecoders: Fix spelling cc574ef12 releaser: Prepare repository for 0.109.0-DEV a0d64a46e releaser: Bump versions for release of 0.108.0 f97544a83 Make the hugo env non verbose output slightly more verbose d8efe085c Add dart-sass-embedded version info to hugo env -v f5b5b71c6 deps: Upgrade github.com/bep/godartsass v0.15.0 => v0.16.0 b82b547ac tpl/embedded: Make Open Graph's series optional da670c38e Squashed 'docs/' changes from 4c1309cdf..2201ac0e5 c9f2fa266 Merge commit 'da670c38ee63a7fef25e2b9f42519232055b60dc' 5067775a6 common/hugio: Fix multiWriteCloser.Close 50549c867 build(deps): bump github.com/getkin/kin-openapi from 0.109.0 to 0.110.0 de9c5542c docs: Add basic doc for wrapStandAloneImageWithinParagraph etc. e93138dfd dartsass: Add sourceMapIncludeSources option 7d16c3c0c github: Update Dart Sass Embedded to 1.56.1 63126c635 markup/goldmark: Add removeSurroundingParagraph for Markdown images 535ea8cc9 build(deps): bump github.com/evanw/esbuild from 0.15.16 to 0.15.18 8bbec426c build(deps): bump golang.org/x/text from 0.4.0 to 0.5.0 0bfa293dc build(deps): bump github.com/evanw/esbuild from 0.15.15 to 0.15.16 0b976d2b4 tpl/tplimpl: Allow alternate comment syntax a49e51fd0 resources: Increase timeout for http.Client d373774cb tpl/collections: Fix some index cases where the indices given is a slice and be more lenient with nil inputs 7d5e3ab8a tpl: Misco GoDoc improvements dc44bca96 config/security: Add CI env var to whitelist da1652789 Squashed 'docs/' changes from 32cb8785e..4c1309cdf ef518485c Merge commit 'da16527896d3087585c5e758083ea498dcabc2c3' 83080df61 deps: Upgrade github.com/bep/godartsass v0.14.0 => v0.15.0 b8d5c378b tpl: Use consistent delimiter spacing in examples 75f782a5a docs: Regen docs helper 2221b5b30 releaser: Bump versions for release of 0.107.0 6a004b8d9 build(deps): bump github.com/getkin/kin-openapi from 0.108.0 to 0.109.0 092362242 build(deps): bump github.com/evanw/esbuild from 0.15.14 to 0.15.15 7855b47f0 Add a cache for lexers.Get 34d1150d9 markup/goldmark: Improve benchmark 85e2ac1a4 commands: Create assets directory with new site 74776726d build(deps): bump github.com/frankban/quicktest from 1.14.3 to 1.14.4 63f7f0ff5 build(deps): bump golang.org/x/tools from 0.2.0 to 0.3.0 bcb62d891 deps: Upgrade github.com/alecthomas/chroma/v2 v2.4.0 00fe7e040 hugo/parser: Fix shortcode boolean param parsing df85cb9ae releaser: Prepare repository for 0.107.0-DEV e08ce30fe releaser: Bump versions for release of 0.106.0 a99fed485 resources/tpl: Add a test for resources.Get db945a6ed tlp/resources: resources.Get returns nil when given empty string bafb389b3 build(deps): bump github.com/pelletier/go-toml/v2 from 2.0.4 to 2.0.6 0a019a1a5 docs: Regen CLI docs 9f7fb0a73 docs: Regenerate docs helper f04cc581e Merge commit '00c4484c7092181729f6f470805bc7d72e8ad17b' 00c4484c7 Squashed 'docs/' changes from 392668f4f..32cb8785e cdd83bf3c build(deps): bump github.com/evanw/esbuild from 0.15.13 to 0.15.14 e00220a06 deps: Update the libweb version string a662ddae1 deps: Upgrade github.com/bep/gowebp v0.1.0 => v0.2.0 13adf3e02 readme: Update ToC fe08d35f2 build(deps): bump github.com/yuin/goldmark from 1.5.2 to 1.5.3 4b675ddd4 build(deps): bump github.com/spf13/afero from 1.9.2 to 1.9.3 24eaa290c build(deps): bump github.com/getkin/kin-openapi from 0.107.0 to 0.108.0 f6ab9553f tpl/internal: Sync go_templates 58a98c775 build(deps): bump github.com/clbanning/mxj/v2 from 2.5.6 to 2.5.7 900904fd1 build(deps): bump golang.org/x/net from 0.1.0 to 0.2.0 24eca0cbe build(deps): bump github.com/evanw/esbuild from 0.15.12 to 0.15.13 60e0e2c1d Add Go 1.16+ install method to README 52ea07d2e Fix taxonomy weight sort regression 77fc74a5b releaser: Prepare repository for 0.106.0-DEV 0e3b42b4a releaser: Bump versions for release of 0.105.0 f50585442 build(deps): bump golang.org/x/tools from 0.1.12 to 0.2.0 2aedccc9a build(deps): bump github.com/getkin/kin-openapi from 0.106.0 to 0.107.0 c10931404 build(deps): bump golang.org/x/text from 0.3.7 to 0.4.0 4732c47d1 build(deps): bump github.com/spf13/cobra from 1.5.0 to 1.6.1 62780ec8d build(deps): bump github.com/getkin/kin-openapi from 0.103.0 to 0.106.0 351d6b062 build(deps): bump github.com/tdewolff/minify/v2 from 2.12.1 to 2.12.4 631d768be Revise the fix for shortcode vs output format nilpointer e5d2a8f6a Avoid nilpointer when shortcode page content output nil 00ff161b6 livereload: Use text/javascript here, too 588710a7a media: Rename application/javascript, application/typescript to text/javascript etc. ed930db2f build(deps): bump github.com/yuin/goldmark from 1.4.15 to 1.5.2 05df96481 build(deps): bump github.com/fsnotify/fsnotify from 1.5.4 to 1.6.0 20ef6dcf9 Skip flakey server tests on GitHub Action on Windows 9860e0e18 build(deps): bump github.com/magefile/mage from 1.13.0 to 1.14.0 d1cd1db0e github: Avoid duplicate test runs 09e10110a tpl/encoding: Add noHTMLEscape option to jsonify 2ef60dbd2 build(deps): bump github.com/evanw/esbuild from 0.15.9 to 0.15.12 6275aad9e Update Go and Alpine version in Dockerfile 01ebb6e30 Don't use self-closing generator tag a066e9885 build: Update to Go 1.19.2 1fd3320dc github: Use SHA versions 0fb2b3d14 Resolve dependency-path not found error in workflow db05232d5 Use setup-go action to cache dependencies 2734f956c releaser: Prepare repository for 0.105.0-DEV 58b824581 releaser: Bump versions for release of 0.104.3 ec57cf2c3 resources: Update golden image dithering exception list 3a9cb7b0f resources/images: Fix 2 animated GIF resize issues 0addb302a server: Fix flaky TestServerPathEncodingIssues tests b002d4795 commands: Remove extraneous newline from result of convert toTOML e3f31352d config/security: Fix filename ec02c537e releaser: Prepare repository for 0.105.0-DEV 84cbe7249 releaser: Bump versions for release of 0.104.2 4611b6920 Fix htimes /: operation not permitted error on config changes 2171e3c9a Revert "Adjust a test" cac773aef Adjust a test 51010a69b releaser: Prepare repository for 0.105.0-DEV 8958b8741 releaser: Bump versions for release of 0.104.1 29ccb3606 Fix /static performance regression from Hugo 0.103.0 d8aba18e0 releaser: Prepare repository for 0.105.0-DEV c744dbd6e releaser: Bump versions for release of 0.104.0 5c4165336 Consolidate the glob case logic 281554ee9 hugofs: Fix glob case-sensitivity bug f3560aa0e server: Fix 404 redirects on Windows edf9038a9 build(deps): bump github.com/evanw/esbuild from 0.15.8 to 0.15.9 78f49b4c0 build(deps): bump github.com/yuin/goldmark from 1.4.14 to 1.4.15 fa4b77e7e build(deps): bump github.com/getkin/kin-openapi from 0.100.0 to 0.103.0 8377c3cea docs: Regen docs helper 4d909d476 build(deps): bump github.com/alecthomas/chroma/v2 from 2.2.0 to 2.3.0 4eb6d9740 build(deps): bump github.com/evanw/esbuild from 0.15.7 to 0.15.8 4f9cb4f34 docs: Regenerate CLI docs 0171fb201 Run go mod tidy a4028112e resources/images: Add $image.Colors 08f0984f9 commands: Skip flaky test on CI 86653fa38 config/security: Allow proxy variables in subcommands c46d10498 releaser: Prepare repository for 0.104.0-DEV b665f1e8f releaser: Bump versions for release of 0.103.1 6be6752c8 server: Fix redirects when file path contains bytes > 0x80 8e9dce109 Merge branch 'release-0.103.0' 00b71668b releaser: Prepare repository for 0.104.0-DEV beebf2afb releaser: Bump versions for release of 0.103.0 3f0b40f67 Use standard GOOS/GOARCH values in release archives 0bd79d30c Use standard GOOS/GOARCH values in release archives 8e77bcc93 Filter out any duplicate files to post process 74daca6b3 Support PostProcess for all file types 1fd4c562a build(deps): bump github.com/gobuffalo/flect from 0.2.5 to 0.3.0 a5cda5ca4 server: Add 404 support 5e2b28d6e build(deps): bump github.com/getkin/kin-openapi from 0.98.0 to 0.100.0 f2019f0a2 build(deps): bump github.com/evanw/esbuild from 0.15.5 to 0.15.7 475638fe0 build(deps): bump github.com/yuin/goldmark from 1.4.13 to 1.4.14 203cc5457 Feat/sponsors in readme (#10273) 90ad80450 Squashed 'docs/' changes from e5aa641a6..392668f4f af23cdca9 Merge commit '90ad8045056167004d27857a95542936657b8a16' ab5ce5989 Fix usage description 7d40da876 Add `--force` to `hugo new` 02c89a446 scss: Handle single-file sourcemaps correctly 06c3ac674 release: Bump Hugoreleaser version 5e03de0dd Update stale.yml bef31b58a releaser: Prepare repository for 0.103.0-DEV b76146b12 releaser: Bump versions for release of 0.102.3 8e5044d7f Fix shortcode parser regression with quoted param values 5046a6c7c deps: Update github.com/tdewolff/minify/v2 v2.12.0 => v2.12.1 160a067c8 snap: Use "snapcraftctl set-grade" e0ba1a805 snap: Use "snapcraftctl set-version" 7b49c56a6 snap: Make external dependencies actually work dffca5788 release: Add the releaser commits to the ignore list 79932e722 release: Fix the Deb archives 9eb9b70a2 releaser: Prepare repository for 0.103.0-DEV 0ff4a9326 releaser: Bump versions for release of 0.102.0 45e1084ff Add linux/arm64 extended to release setup c98348416 license: Add copyright info 2de393c79 build(deps): bump go.uber.org/atomic from 1.9.0 to 1.10.0 7efb35680 build(deps): bump github.com/kyokomi/emoji/v2 from 2.2.9 to 2.2.10 ddbcc6712 build(deps): bump github.com/getkin/kin-openapi from 0.97.0 to 0.98.0 fd75f129b deps: Update github.com/pelletier/go-toml/v2 v2.0.2 => v2.0.4 14878ca0a build(deps): bump github.com/spf13/afero from 1.8.2 to 1.9.2 e88873b80 build(deps): bump github.com/tdewolff/parse/v2 from 2.6.1 to 2.6.2 4219993b0 build(deps): bump github.com/mattn/go-isatty from 0.0.14 to 0.0.16 988e1417a build(deps): bump github.com/rogpeppe/go-internal from 1.8.1 to 1.9.0 42529882c build(deps): bump github.com/yuin/goldmark from 1.4.12 to 1.4.13 45f1b1cfc build(deps): bump github.com/spf13/cobra from 1.4.0 to 1.5.0 369bdf22f build(deps): bump github.com/tdewolff/minify/v2 from 2.11.10 to 2.12.0 d1b03a093 build(deps): bump github.com/evanw/esbuild from 0.14.43 to 0.15.5 941c28ab0 readme: Add Golang URL to Go links ffbdcc75a Update README.md 95d976451 Update README.md b66f9f266 Update README.md f7e00c039 github: Use GitHub's Choco-Install function to retry installs f5ba6fd45 common/hugio: One more fix for non-OS fs c4bbc1eee common/hugio: Fix CopyDir when fs is not OS 0e0fb1b64 snap: Delete obsolete custom x-nodejs plugins b017f7cb0 livereload: Inject script without head or body tag 7fb28085a releaser: Fat MacOS binaries 0cd1929b9 Update to Go 1.19 cbdaff213 markup/goldmark/codeblock: Fix attributes when no language identifier in CodeBlock 3fefea06b commands: Fix embed in livereload.go 5c48ba934 Update README.md 21562e3aa Externalise and embed livereload.js string 9c24b86e4 Cache when not found in LookupLayout 223bf2800 parser/pageparser: Don't store the byte slices 72b0ccdb0 Make the baseline benchmark's test files stable bdf935d66 Squashed 'docs/' changes from 30f32a624..e5aa641a6 65e52a7f5 Merge commit 'bdf935d66c1f02dfc942a30e9fc00519bba3aacb' 8ebcaa539 Accept vendor-specified build date if .git/ is unavailable 241481931 snap: Replace mage with "go build" and set VendorInfo=snap 5caed8a71 snap: Use interface names etc-gitconfig and gitconfig, Take 2 d1278f696 Extract the baseline benchmark to a test 92f31ae63 Add a baseline benchmark fd3953c18 snap: Use interface names etc-gitconfig and gitconfig 15463f835 releaser: Prepare repository for 0.102.0-DEV 466fa43c1 releaser: Bump versions for release of 0.101.0 6072ce0bc releaser: Add release notes for 0.101.0 [ci skip] 2c5943ddc build: Update to Go 1.18.3 0cb459a20 docs: Regen docshelper 475f87f68 Squashed 'docs/' changes from 96fdc246c..30f32a624 604cfffc5 Merge commit '475f87f685439de0f907a9ffc29bfd1361eb1c59' d863dde6c markup/highlight: Add hl_inline option 580b214a4 deps: Update github.com/alecthomas/chroma/v2 v2.1.0 => v2.2.0 ddb954708 build(deps): bump github.com/clbanning/mxj/v2 from 2.5.5 to 2.5.6 288b0fb15 build(deps): bump github.com/pelletier/go-toml/v2 from 2.0.1 to 2.0.2 3e1344632 build(deps): bump golang.org/x/tools from 0.1.10 to 0.1.11 7a9ce0eca build(deps): bump github.com/tdewolff/minify/v2 from 2.11.5 to 2.11.10 f2ba0cc8c build(deps): bump github.com/evanw/esbuild from 0.14.42 to 0.14.43 62ceaabdc build(deps): bump github.com/getkin/kin-openapi from 0.94.0 to 0.97.0 35fa19283 deps: Udpate to github.com/alecthomas/chroma/v2 09ac73338 common: Add hugo.GoVersion 66da1b7b2 resources: Panic on Copy of Resource with .Err 5a9ecb82a resources/page: Add :slugorfilename attribute cbc35c48d Respect NO_COLOR 44f3c0796 readme: Update dependency list a5a4422aa Fix relURL with leading slash when baseURL includes a subdirectory 617e09448 js: Resolve index.esm.js cf12fa616 Add animated GIF support 2e1c81770 resources: Add a Gif source file to golden tests 4276075c7 releaser: Prepare repository for 0.101.0-DEV d25cb2943 releaser: Bump versions for release of 0.100.2 8b9bdc403 releaser: Add release notes for 0.100.2 [ci skip] 4e94d1db7 Update CONTRIBUTING.md 0566bbf7c Fix raw TOML dates in where/eq 534e7155b deps: Update to github.com/pelletier/go-toml/v2 v2.0.1 953f215f3 tpl/path: Add path.BaseName function 8e2fd5592 livereload: Use `X-Forwarded-Host` for Codespace 311b8008b helpers: Fix panic with invalid defaultMarkdownHandler c7d5f9f06 resources: Register MediaTypes before build bfebd8c02 releaser: Prepare repository for 0.101.0-DEV 0afb4866e releaser: Bump versions for release of 0.100.1 b1ec0c226 releaser: Add release notes for 0.100.1 [ci skip] 212d9e301 Fix panic with markdownify/RenderString with shortcode on Page with no content file 4daac654d releaser: Prepare repository for 0.101.0-DEV 27b077544 releaser: Bump versions for release of 0.100.0 0f8343a2c releaser: Add release notes for 0.100.0 [ci skip] 3fcbee261 docs: Regen CLI docs db9d27427 docs: Regen docs helper 95baafeac Merge commit 'e4bfe59c4e043c92d3992587d8c64d264b262a22' e4bfe59c4 Squashed 'docs/' changes from 2d9da3a56..96fdc246c 6f7bf3f2d Fix indentation in highlight shortcode 9e904d756 Make .RenderString render shortcodes d2cfaede5 Improve shortcode indentation handling 322d19a81 Add Markdown as an output format 7cb484e12 build(deps): bump github.com/evanw/esbuild from 0.14.39 to 0.14.42 0b395f0b4 Run go mod tidy c1a83076b Add a shortcode benchmark 0f8dc4703 Remove Blackfriday markdown engine 3b478f50b Fix HasMenuCurrent and IsDescendant/IsAncestor when comparing to itself f343b8eb7 build(deps): bump github.com/sanity-io/litter from 1.5.4 to 1.5.5 60ede146b deps: Update to github.com/tdewolff/minify/v2 v2.11.5 dd9eaf19f Don't use the baseURL /path as part of the resource cache key 46a2ea6d0 postcss: Make the resource cache key more stable 653ab2cc1 commands: Fix case where languages cannot be configured 52edea0fe github: Set HUGO_BUILD_TAGS: extended when running tests 6a5acd753 metrics: Fix divide by zero error 805b21555 Fix error message when PostCSS config file is not found 8ca705252 server: Skip watching dirs in ignoreFiles bb232a351 resources: Improve error message on .Resize etc. on SVGs 3854a6fa6 Fix Plainify edge cases cd0112a05 Add resources.Copy 6f7fbe03b basefs: add `noBuildLock` flag 2fc2e9c87 import: Fix importing jekyll site e164834f0 releaser: Prepare repository for 0.100.0-DEV d52406738 releaser: Bump versions for release of 0.99.1 31ce89f7f releaser: Add release notes for 0.99.1 [ci skip] ee55fde5e releaser: Fix version replacement 2f9eac480 server: Fix multihost crash 3a8189ee9 Update stale.yml 7bc3401eb common/hugo: Fix version logic 1de333e7a releaser: Bump versions for release of 0.99.0 35cb6eefb releaser: Add release notes for 0.99.0 [ci skip] 657d1a2d9 server: Refresh the error template 87a22eb6d server: Fix SIGINT handling after loading bad configuration fc9f315d8 Improve SASS errors 4b189d8fd postcss: Fix import error handling c2fa0a332 build(deps): bump github.com/fsnotify/fsnotify from 1.5.3 to 1.5.4 48ea24f89 common/herrors: Remove unused struct 9f563856c build(deps): bump github.com/evanw/esbuild from 0.14.38 to 0.14.39 5c96bda70 errors: Misc improvements 4a96df96d server: Always rebuild the files involved in an error e8537e6dd postcss: Fix line numbers in error messages 2fbdee726 Update CONTRIBUTING.md 91fe1b6c6 js: Bump test dependency 7de629121 deps: Update github.com/spf13/cast v1.4.1 => v1.5.0 9d7f16624 hugolib: Check for nil in shouldRender 51f08b0b6 Revise the use of htime.Since/htime.Now 860c51c31 tpl/collections: Make sort stable 855e5869c docs: Regen CLI docs 327aaed6d Squashed 'docs/' changes from 7030fe3a2..2d9da3a56 1c7759028 Merge commit '327aaed6d8ca57d8e5e3acb99ff53402ff1c556d' 35c88a7f9 Use configured timeZone for the clock e77ca3c10 Add `clock` cli flag f2946da9e Improve error messages, esp. when the server is running 6eea32bd6 tpl: Improve godoc a6d545854 github: Add permissions to test action e5f217316 tpl/crypto: Add example for FNV32a 89c1655ec releaser: Prepare repository for 0.99.0-DEV 165d299cd releaser: Bump versions for release of 0.98.0 e94dc6710 releaser: Add release notes for 0.98.0 [ci skip] a4fff5753 docs: Regen docs helper 3902f9a47 Squashed 'docs/' changes from 4c5edacfe..7030fe3a2 4852a3765 Merge commit '3902f9a4767fe6e62ac5146728d8311b8cd227e0' fa80fe3c8 Some godoc adjustments and image struct renames 11047534e tpl/crypto: Add FNV32a d7b54a4c3 markup/goldmark: Fix attribute nilpointer 13ceef759 deps: Update to gocloud.dev v0.24.0 942d0dd2c build(deps): bump github.com/mitchellh/mapstructure from 1.4.3 to 1.5.0 a022ca271 deps: Update github.com/yuin/goldmark v1.4.11 => v1.4.12 d56b33955 build(deps): bump github.com/evanw/esbuild from 0.14.36 to 0.14.38 55e28c239 deps: Update github.com/tdewolff/minify/v2 v2.11.1 => v2.11.2 9a888c243 Some godoc adjustments 05b45c35c tpl/lang: Handle nil values in lang.Merge 625be77e0 resources/page: Mark some more interface methods as internal 097fd588c Deprecate page.Author and page.Authors 41cc4e4ba releaser: Prepare repository for 0.98.0-DEV 078053a43 releaser: Bump versions for release of 0.97.3 7d9f88808 releaser: Add release notes for 0.97.3 [ci skip] 9b352f04a Fix syncing of /static regression e66e2e9ce Revert "Revert "Fix PostProcess regression for hugo server"" 5de6f8a02 releaser: Prepare repository for 0.98.0-DEV 5099abe60 releaser: Bump versions for release of 0.97.2 99ec88d42 releaser: Add release notes for 0.97.2 [ci skip] 6c35a1a9e Revert "Fix PostProcess regression for hugo server" 363bc907c releaser: Prepare repository for 0.98.0-DEV 04efcb2a6 releaser: Bump versions for release of 0.97.1 456072552 releaser: Add release notes for 0.97.1 [ci skip] 4deb5c606 Fix PostProcess regression for hugo server 397fce560 Fix MediaType when reading images from cache 0093eaa68 deps: Upgrade github.com/bep/overlayfs v0.4.0 => v0.5.0 d0f731c03 releaser: Prepare repository for 0.98.0-DEV c07f3626e releaser: Bump versions for release of 0.97.0 42b5d1653 releaser: Add release notes for 0.97.0 [ci skip] d80d5a104 releaser: Reduce parallelism 842262f65 Revert "build(deps): bump gocloud.dev from 0.20.0 to 0.25.0" 2dbdf38a5 resources: Add `key` to reources.GetRemote options map f8c4e1690 build(deps): bump github.com/evanw/esbuild from 0.14.34 to 0.14.36 627eed1d6 Make string sorting (e.g. ByTitle, ByLinkTitle and ByParam) language aware 82ba634ed Fix gosum checksum errors d417a6cf7 build(deps): bump github.com/tdewolff/minify/v2 from 2.11.0 to 2.11.1 13dac7f3c compare: Add a string sort benchmark 30c2e54c2 Replace all usage of CopyOnWriteFs with OverlayFs 3117e5859 deps: Update github.com/tdewolff/minify/v2 v2.10.0 => v2.11.0 ec920363c Squashed 'docs/' changes from 63386081c..4c5edacfe 5b5dcb8d5 Merge commit 'ec920363cdeb687c8bcac9c242767d366fb058cb' ffe3eb919 docs: Regen CLI docs d070bdf10 Rework the Destination filesystem to make --renderStaticToDisk work b08193971 Revert "Revert "Some minor adjustments to the new static filesystem logic"" 0a56f2af4 Revert "Revert "Allow rendering static files to disk and dynamic to memory in server mode"" 9e360d384 build(deps): bump github.com/evanw/esbuild from 0.14.31 to 0.14.34 a8c221d33 modules/client: Vendor config directory if present e58a54089 resources: Create a common ResourceFinder interface 20162518c build(deps): bump gocloud.dev from 0.20.0 to 0.25.0 6b469cc8f build(deps): bump golang.org/x/tools from 0.1.9 to 0.1.10 080dcac6b build(deps): bump github.com/magefile/mage from 1.12.1 to 1.13.0 072fc8cc3 build(deps): bump github.com/gobuffalo/flect from 0.2.4 to 0.2.5 658e11eba Localize all the GroupBy*Date methods e0a882fd3 build(deps): bump github.com/getkin/kin-openapi from 0.93.0 to 0.94.0 d0657a436 deploy: Set an MD5 attribute and use that if eTag not available a6e2e38bb build(deps): bump github.com/sanity-io/litter from 1.5.2 to 1.5.4 510e17900 build(deps): bump github.com/evanw/esbuild from 0.14.25 to 0.14.31 21484f9e1 build(deps): bump github.com/frankban/quicktest from 1.14.2 to 1.14.3 da00e7714 Add environment as a new filter to _cascade.target ed9aa374d Merge branch 'release-0.96.0' 2a231b0b5 Snap: Add {system,user}-gitconfig plugs to read gitconfig (#9619) 69c590080 releaser: Prepare repository for 0.97.0-DEV 2fd4a7d3d releaser: Bump versions for release of 0.96.0 5a4ac2dac releaser: Add release notes for 0.96.0 [ci skip] db1562e13 docs: Regen docshelper 5b18e1084 docs: Regen CLI docs d276e901b Squashed 'docs/' changes from a393f4cf4..63386081c d7497b28c Merge commit 'd276e901b36d2576ef8350ed96b17f66254eac1b' 94459680b Deprecate .File.Extension 9202117ba resources: Add more details to .Err a6fa290f6 commands: Change link protocol to https 0bbc2fb52 build(deps): bump github.com/getkin/kin-openapi from 0.91.0 to 0.93.0 94e8a9076 tpl/crypto: Add optional encoding arg to hmac function a461e9d01 Fix typo 48c98a8d2 Fix some typos bbd455fe7 Update CONTRIBUTING.md to use "go install" to install mage 8309a2b1c Dockerfile: Make it build with Go 1.18 2b7231097 snap: Make it build with Go 1.18 13ff4ded7 build(deps): bump github.com/yuin/goldmark from 1.4.10 to 1.4.11 c3289eb5b build(deps): bump github.com/spf13/cobra from 1.3.0 to 1.4.0 9539069f5 commands: Improve server startup to make tests less flaky 0e305d695 all: Use strings.Cut 5adb81ce3 Support '-u=patch' in hugo mod get 1c0e7c1ae Make sure file mounts higher up wins cad2d8cc7 resources/images: Require width and height for Crop, Fill, and Fit b80853de9 all: gofmt -w -r 'interface{} -> any' . 423594e03 dartsass: Enable deprecation, @warn and @debug logging 64afb7ca5 Use revision etc. from debug.BuildInfo 004bec2e9 releaser: Prepare repository for 0.96.0-DEV 9f2e76af6 releaser: Bump versions for release of 0.95.0 f1d157682 releaser: Add release notes for 0.95.0 [ci skip] 5930173cd readme: Add note about Go 1.18 3476b5334 tpl: Pull in Go 1.18 patch that fixes the "no space in {{ continue }} and {{ break }}" bug e792d2701 readme: Add a contribution note 9d6495d77 github: Make it build with Go 1.18 42cc5f88b tpl: Adjustments and an integration test for Go 1.18 a6488e7ba Remove Go 1.17 support 65a78cae1 tpl: Sync go_templates for Go 1.18 4d6d1d08d build: Bump to Go 1.18 b60e1bbdf dartsass: Improve error message when no read access 61cf3c9f6 Fix and refactor typos 31fbc081c Improve server startup/shutdown cebd886ac commands: Improve server tests 38f778cfc releaser: Prepare repository for 0.95.0-DEV 48fb9e4de releaser: Bump versions for release of 0.94.2 0958167b3 releaser: Add release notes for 0.94.2 [ci skip] b37183e48 deps: Update github.com/yuin/goldmark v1.4.9 => v1.4.10 04ccde3e9 releaser: Prepare repository for 0.95.0-DEV 0fcd9a5d8 releaser: Bump versions for release of 0.94.1 414608436 releaser: Add release notes for 0.94.1 [ci skip] 3bc742bea docs: Regenerate CLI docs 1a796d723 deps: Fix Goldmark regression with HTML comments 64b7b7a89 Revert "Allow rendering static files to disk and dynamic to memory in server mode" 5ef8a9f32 Revert "Some minor adjustments to the new static filesystem logic" 3bc34666c releaser: Prepare repository for 0.95.0-DEV 63b236603 releaser: Bump versions for release of 0.94.0 b107b4b29 releaser: Add release notes for 0.94.0 [ci skip] a4ac188c1 docs: Regenerate docshelper b82d95575 Revert "markup/highlight: Add hl_inline option" 4e14cf760 Fail with error when double-rendering text in markdownify/RenderString 5697348e1 markup/goldmark: Default to https for linkify f98e570b1 Add lang attribute to internal alias template cdb8b0842 docs: Regenerate docshelper a360cab75 markup/highlight: Add hl_inline option c97fed08f minifiers: Make keepWhitespace = false default for HTML (note) 53a6210d8 markup/goldmark/codeblocks: Fix slice bounds out of range 7182809d9 docs: Regenerate CLI docs 1f8cd2614 docs: Regenerate docshelper 9d76b8fa3 Merge commit 'd706529720b3b2ccb99719ccd578062ca25a0cc2' d70652972 Squashed 'docs/' changes from 3f95a2ace..a393f4cf4 4576c82ed Cache reflect.MethodByName ff02d4172 releaser: Remove the GitHub link syntax around release contributors 63bb2a5b1 Some minor adjustments to the new static filesystem logic 7d8011ed6 Allow rendering static files to disk and dynamic to memory in server mode b9a1be2f9 build(deps): bump github.com/kyokomi/emoji/v2 from 2.2.8 to 2.2.9 097824503 build(deps): bump github.com/evanw/esbuild from 0.14.23 to 0.14.25 ff37df830 build(deps): bump github.com/niklasfasching/go-org from 1.6.0 to 1.6.2 5857d5524 build(deps): bump github.com/getkin/kin-openapi from 0.90.0 to 0.91.0 d86eca5bb releaser: Prepare repository for 0.94.0-DEV 44e3c002a releaser: Bump versions for release of 0.93.3 9177849f9 releaser: Add release notes for 0.93.3 [ci skip] 0e0d672bc Remove the decorator from the fs used in ReadDir 19f816f77 Update stale.yml 970f385c4 build(deps): bump github.com/yuin/goldmark from 1.4.7 to 1.4.8 76c1248f7 Remove the examples/ folder 9e76507da releaser: Prepare repository for 0.94.0-DEV 643b5ae9c releaser: Bump versions for release of 0.93.2 2f7feca9a releaser: Add release notes for 0.93.2 [ci skip] 673cde1eb tpl/os: Revert readDir in theme behaviour e46e9ceb2 markup/goldmark: Escape image alt attribute 883e71c96 releaser: Prepare repository for 0.94.0-DEV e9669fed1 releaser: Bump versions for release of 0.93.1 fefb1caac releaser: Add release notes for 0.93.1 [ci skip] 0327da050 tpl/transform: Fix it when template.HTML is passes as option to Hightlight 9b8b6d34e tpl/partials: Fix partialCached deadlock regression 376704d38 tpl/collections: Fix apply when function have Context as first arg c1398b91a Squashed 'docs/' changes from 93f7baf80..3f95a2ace 41b5bc963 Merge commit 'c1398b91a9f4c67876b31feb67516b252e654d3c' 5a1b394f2 releaser: Prepare repository for 0.94.0-DEV 074690824 releaser: Bump versions for release of 0.93.0 75084bfc7 releaser: Add release notes for 0.93.0 [ci skip] 12d00d288 docs: Regenerate docs helper 260ff1374 markup/highlight: Ignore HL_lines_parsed in the gen docs 14915a0c3 cod: Regen CLI docs fd0c1a5e9 tpl/diagrams: Rename the SVG accessor to Wrapped 3ad39001d markup/highlight: Rework the return value from HighlightCodeblock 39261b689 tpl/transform: Add CanHighlight cff14144a Rename Codeowners() to CodeOwners() 5f6715155 tpl/diagrams: Rename Body to Inner f7109771a CodeblockContext method renames e1f696911 build(deps): bump github.com/tdewolff/minify/v2 from 2.9.29 to 2.10.0 5f65c17a1 markup/goldmark: Adjust test for Windows 579ff9b65 markup/goldmark: Improve attributes vs options 928a89696 markup/goldmark: Add Position to CodeblockContext 2e54c0093 markup/goldmark: Unify some code block tests 10928a4f7 Remove the trailing new line in .Code afd63bf7d markup/goldmark: Rename extension struct 228126b7f build(deps): bump github.com/gobuffalo/flect from 0.2.3 to 0.2.4 0f80be341 markup/goldmark: Use Ordinal to create default lineanchors 78afdb88a build(deps): bump github.com/gorilla/websocket from 1.4.2 to 1.5.0 3ed83227b build(deps): bump github.com/sanity-io/litter from 1.5.1 to 1.5.2 1a257bb2b Move the Goat template to the correct place 97514f17d build(deps): bump google.golang.org/api from 0.63.0 to 0.70.0 0df096b86 Update error message about failed menus in config.toml 308ad611b build(deps): bump github.com/getkin/kin-openapi from 0.85.0 to 0.90.0 6bffcdbd2 Add test for line anchor attributes with code fences 7248f4318 build(deps): bump github.com/evanw/esbuild from 0.14.22 to 0.14.23 08fdca9d9 Add Markdown diagrams and render hooks for code blocks 2c20f5bc0 build(deps): bump github.com/aws/aws-sdk-go from 1.41.14 to 1.43.5 723b2c485 build(deps): bump github.com/google/go-cmp from 0.5.6 to 0.5.7 06bac57ab Add support for CODEOWNERS ec8b767fa Remove Viper as a dependency 6407b2cd0 helpers: Allow hyphens in UnicodeSanitize 6ff39fd90 Change `disqus_config` to `window.disqus_config` 96c0bdf3a deps: Update github.com/spf13/cobra v1.2.1 => v1.3.0 e97d3c640 Add page.Store 7732da9f9 Allow images to be cropped without being resized aebde49b8 commands: Fix server panic regression 4ada09415 markup/goldmark: Add BenchmarkCodeblocks bddcfd911 deps: Update github.com/gohugoio/localescompressed v0.14.0 => v0.15.0 d485f9543 deps: Update github.com/yuin/goldmark v1.4.4 => v1.4.7 a87be597a modules: Add modules.Workspace config for Go 1.18 b0eea0075 Update stale.yml ef8b781b1 Update stale.yml 3136ff67d github: Configure stale to be run manually 929808190 tpl/partials: Fix recently introduced deadlock in partials cache 667f3a4ba tpl/partials: Add some more partials to BenchmarkIncludeCached c061b253a deps: Update github.com/evanw/esbuild v0.14.11 => v0.14.22 0927cf739 tpl/partials: Make sure a cached partial is invoked only once 26a5e89fa build(deps): bump github.com/rogpeppe/go-internal from 1.8.0 to 1.8.1 e9fa7e81b build(deps): bump github.com/magefile/mage from 1.11.0 to 1.12.1 ff545f427 markup/goldmark: Exclude event attributes from markdown render hook b2a827c52 markup/goldmark: Fix mangling of headers/links in render hooks 77c7059ff markup/goldmark: Add a render hook benchmark f4c90bd6b Fix BenchmarkCascadeTarget d16228334 metrics: Add cached count tracking ea6bcd694 tpl: Remove TODO comment f2e7b49ac Add --printUnusedTemplates 923419d7f deps: Update github.com/tdewolff/minify/v2 v2.9.22 => v2.9.29 837fdfdf4 commands: Rename --i18n-warnings to printI18nWarnings 6819feab6 commands: Rename --path-warnings, --print-men to --printPathWarnings, --printMemoryUsage ea54a99ca deps: Update github.com/alecthomas/chroma v0.9.4 => v0.10.0 9563c7d13 Finally remove deprecated Page methods 230a49594 Squashed 'docs/' changes from b8b20e9a2..93f7baf80 c707b71cd Merge commit '230a495941b191af0bdaa7e2fc8c61607cb38207' b0a9cf0a7 tpl: Use go:embed to load internal templates 9433cc256 releaser: Prepare repository for 0.93.0-DEV cdf6a0d62 releaser: Bump versions for release of 0.92.2 bf1fa7137 releaser: Add release notes for 0.92.2 [ci skip] 4f4cec73b Add HUGO_ENV to the os/exec environment da4866c2b Simplify some integration tests d1109f590 Fix validation of Page Kind in cascade target map a7d182cea Add another cascade benchmark a2a660ed1 commands: Fix server deadlock on config error f7bc4cc50 Exclude event attributes when rendering markdown 54f8d8a70 Remove the "check" command 3036d0ac9 Update the application/javascript media type 6a238a727 tpl/templates: Fix templates.Exist issue with base templates f60714b5a Add a migration test helper 215a715dd babel: Port integration tests to their own package d128d260b js: Port integration tests to its own package c4aaf1d51 postcss: Move integration test to its own package 94f10cf4f minifier: Port integration tests to its package b06c2103b templates: Port integration test to its package d22f7795c tocss: Port integration tests to their package 39f69ca7f openapi3: Port integration test into correct package 64f75adcf Add a new integration test framework 926271909 Validate comparison operator argument count 333676293 Remove hugo gen autocomplete 5ca40c8f7 deps: Update github.com/pelletier/go-toml/v2 to v2.0.0-beta.6 ef7d14a24 Fix erroneous warning with .Page.RenderString on a page without a backing file c05c99f0c Fix typo in panicOnWarning message ff7689ce0 releaser: Prepare repository for 0.93.0-DEV 85e2e8626 releaser: Bump versions for release of 0.92.1 515f8a6d8 releaser: Add release notes for 0.92.1 [ci skip] f22c4aba0 Make the RenderString content provider fix more general 85d31f7bf Fix .RenderString issue in .Translations 22055176d general: Fix issue causing log threads to hang indefinitely when print() panics 7a080b624 Fix duplicate mount sources 265573994 tpl/collections: Fix apply with namespaced template funcs 348d300a7 common: Remove unused code 6f07bdb15 common/paths: Remove unused code 55a9bc1e7 helpers: Remove unused code 20a7ce7c1 Do not render hl_style as an HTML attribute 8cd449240 build(deps): bump github.com/spf13/viper from 1.8.1 to 1.10.1 9d8f318aa Fixing typos (#9387) fcbbbef22 Fix typo in warning message 6041adc16 github: Clean up the issue templates a little 408da4365 github: Add lock-threads step ed04ed574 releaser: Prepare repository for 0.93.0-DEV b35494036 releaser: Bump versions for release of 0.92.0 bd89aef8b releaser: Add release notes for 0.92.0 [ci skip] f2bc13dd9 docs: Regenerate docshelper 098254f17 Merge commit 'a8e9fc699a6ff7d578f97a7c553ce844efad8fdb' a8e9fc699 Squashed 'docs/' changes from 4eb10c1a9..b8b20e9a2 cdcd15b6c Only create LazyContentProvider for the non-rendering Site 25d645f47 Fix missing page data for alternative formats fbb3c181c docs: Add dependency table to maintainance page 9af4ca386 deps: Upgrade github.com/evanw/esbuild v0.14.8 => v0.14.11 7396aa945 Add hugo.Deps d82cef5c5 hugolib: Fix livereload problem with files including NFC characters in MacOs 74f0777c5 docs. Regen CLI docs e334a4066 commands: Fix CLI help text for hugo new 5bd3c8df4 Update to Go 1.17.6 0aca99fe0 create: Correctly pass newContentEditor flags c8b5ab75b Add --panicOnWarning flag 85c5b8959 github: Increase stale days 965760835 docs: Regenerate CLI docs 4a0b55330 docs: Regenerate docshelper 1651beb2c Remove mmark 2b6063c3e Misc depreation updates 56ab83a59 Make the deprecated Page/File methods (from Hugo 0.55) ERROR dad0dc8d8 github: Add add stale GitHub action d3c4fdb8f Fix surprise OutputFormat.Rel overwriting d632dd7d7 hugolib: Make an RST test optional 0671ef559 deps: Upgrade github.com/niklasfasching/go-org v1.5.0 => v1.6.0 672481f1f Update stale.yml 1dbfc0f93 releaser: Prepare repository for 0.92.0-DEV 1798bd3fd releaser: Bump versions for release of 0.91.2 f0b55a68e releaser: Add release notes for 0.91.2 [ci skip] 623dda717 Revert "config/security: Add HOME to default exec env var whitelist" aee9e11a4 Make sure we always create the /public folder bd63c1aa5 Fix "stuck on build" in error situations in content processing 9eb05807c deps: Run "go mod tidy" 654f513a4 deps: Upgrade github.com/evanw/esbuild v0.14.7 => v0.14.8 759cdf3fc releaser: Prepare repository for 0.92.0-DEV f42350574 releaser: Bump versions for release of 0.91.1 af165d5b6 releaser: Add release notes for 0.91.1 [ci skip] 6779117f7 media: Also consider extension in FromContent ce0401109 media: Add missing BMP and GIF to the default MediaTypes list cdc73526a media: Add PDF MIME type 425c7d90f deps: Update github.com/evanw/esbuild v0.14.5 => v0.14.7 fca266ebb config/security: Add HOME to default exec env var whitelist 0016e21cd modules: Set GOCACHE env var 728feaecf releaser: Prepare repository for 0.92.0-DEV d1dc0e9a5 releaser: Bump versions for release of 0.91.0 072bca69d releaser: Add release notes for 0.91.0 [ci skip] e26e13fbb releaser: Drop running tests as part of the release 6df2f080c docs: Regen docs helper b84745d49 tpl/resources: Add empty method mapping for GetRemote 44954497b Always use content to resolve content type in resources.GetRemote 22ef5da20 Add resources.GetRemote 5758c370e Allow for return partials with falsy arguments (#9298) 8ee6de6d9 deps: Upgrade github.com/evanw/esbuild v0.14.2 => v0.14.5 a4b9f1a92 don't use path.Join, because it cleans the final path f4389e48c Add some basic security policies with sensible defaults 803f572e6 Simplify Babel test assertions 6183184b9 Merge commit '45e6fdb315d113ba13e20a633ed0c67e3f25170d' 45e6fdb31 Squashed 'docs/' changes from 316cec249..4eb10c1a9 a037be774 Improve handling of remote image/jpeg resources (#9278) 8a005538d Fix Dockerfile 657d0272e Remove debug statement 159120cdd Fix deprecation notice 3f0d49e50 releaser: Prepare repository for 0.91.0-DEV 489078897 releaser: Bump versions for release of 0.90.1 3075eaa3b releaser: Add release notes for 0.90.1 [ci skip] 3bc683041 Remove the retries on error in remote resources.Get e4d6ec94b Allow user to handle/ignore errors in resources.Get 6260455ba Make resource.Get return nil on 404 not found c397975af Update to Go 1.17.5 965a6cbff Update to Go 1.17.4 and remove timeout in resources.Get 34a96290f releaser: Prepare repository for 0.91.0-DEV dd0d3fdbb releaser: Bump versions for release of 0.90.0 b92175233 releaser: Add release notes for 0.90.0 [ci skip] 0fa40ce58 releaser: Simplify the release process bf537f1c6 releaser: Remove unused code e86b33113 docs: Regenerate docs helper 6c841a691 Merge commit '8d9511a08f14260cbfb73119e4afae50e5a9966d' 8d9511a08 Squashed 'docs/' changes from 39a7fac34..316cec249 e71d715b9 Add custom font support to images.Text e61cdf335 images: Fix cache busting of image text filter 6c3bc5eba build(deps): bump github.com/getkin/kin-openapi from 0.80.0 to 0.85.0 283394a4f images: Text filter that draws text with the given options (#9239) 5538507e9 tpl/transform: Optional options for highlight func b4f27ef8e deps: Upgrade github.com/evanw/esbuild v0.13.12 => v0.14.2 (note) 3473e31eb releaser: Add "note" to Note regexp fa0da004a build(deps): bump github.com/mitchellh/mapstructure from 1.4.2 to 1.4.3 24a893cf8 releaser: Rework and simplify to use GitHub only for release notes bf1564bd2 build(deps): bump google.golang.org/api from 0.51.0 to 0.61.0 cd44d409b media: Add rss suffix for application/rss+xml 9a326d563 parser: Add a test case in format resolution b10381fbe lazy: Reset error in Reset 0eaaa8fee Implement XML data support 58adbeef8 Validate private use language tags 93572e531 resources: Add timeout to the HTTP request in Get 94f149b21 Add a remote retry for resources.Get 66753416b Make resources.Get use a file cache for remote resources 133e4bfbe Remove empty href element from pagination template f122771fb Check for empty deployment targets and matchers 08a863e1e resources: Adjust the remote Get cache so it does not get evicted on restarts 8aa7257f6 Add remote support to resources.Get 75a823a36 Add deprecation warning to google_news template 5e0947c5b helpers: Make UniqueStringsReuse allocation free 0b70b46aa releaser: Prepare repository for 0.90.0-DEV ab01ba6e7 releaser: Add release notes to /docs for release of 0.89.4 cc08c0959 releaser: Bump versions for release of 0.89.4 f97da9eca releaser: Add release notes for 0.89.4 [ci skip] 2e70f61fb Fix content dir resolution when main project is a Hugo Module 1ed8069a3 releaser: Prepare repository for 0.90.0-DEV c88cdb561 releaser: Add release notes to /docs for release of 0.89.3 e1064d219 releaser: Bump versions for release of 0.89.3 bf489b96d releaser: Add release notes for 0.89.3 [ci skip] b8155452a Improve error when we cannot determine content directory in "hugo new" 08552a7a4 deps: Upgrade github.com/yuin/goldmark v1.4.3 => v1.4.4 fdad91fd9 commands: Make sure pollInterval is always set 5f3f60898 create: Improve archetype directory discovery and tests 057d02de2 create: Add a log statement when archetype is a directory 43ac59da8 create: Always print "Content ... created" ab5c6990a commands: Fix missing file locking in server partial render 9369d13e5 modules: Improve error message 805c24c32 releaser: Prepare repository for 0.90.0-DEV 63e3a5ebb releaser: Add release notes to /docs for release of 0.89.2 eaa6c96a7 releaser: Bump versions for release of 0.89.2 cf3eb580b releaser: Add release notes for 0.89.2 [ci skip] 2b01c85d1 Fix path resolution in hugo new c09f5c5fd deps: Upgrade github.com/yuin/goldmark v1.4.2 => v1.4.3 9232e2844 releaser: Prepare repository for 0.90.0-DEV b6a4ae4ad releaser: Add release notes to /docs for release of 0.89.1 84de0c325 releaser: Bump versions for release of 0.89.1 a07410226 releaser: Add release notes for 0.89.1 [ci skip] da4406ea5 Revert "releaser: Fat MacOS binaries" 166862a09 create: Make sure the build lock is released before we open editor 82c33c710 readme: Update dependency list 41e9e9fe1 releaser: Prepare repository for 0.90.0-DEV ade966b84 releaser: Add release notes to /docs for release of 0.89.0 a93d4ba64 releaser: Bump versions for release of 0.89.0 110512a65 releaser: Add release notes for 0.89.0 f503b6395 docs: Regen CLI docs 30aba7fb0 source: Make ContentBaseName() return the directory for branch bundles 04a3b45db Fix description of lang.FormatNumberCustom 0cc39af68 Update Twitter shortcode oEmbed endpoint ed6fd26ce common/htime: Fix time.Format with Go layouts 7fa66425a build(deps): bump github.com/evanw/esbuild from 0.13.10 to 0.13.12 69210cfdf build(deps): bump github.com/yuin/goldmark from 1.4.1 to 1.4.2 4b36498a8 Merge commit 'aa5ac36a3eb68b86c803caec703869efefc8447e' aa5ac36a3 Squashed 'docs/' changes from 327003421..39a7fac34 3a977485e releaser: Fat MacOS binaries 0f248606d releaser: Only build amd64 binary for freebsd, netbsd, openbsd, dragonfly e82cbd746 tpl/time: Use configured location when date passed to Format is string 3339c2bb6 build(deps): bump github.com/aws/aws-sdk-go from 1.40.8 to 1.41.14 03bbdba8b build(deps): bump github.com/getkin/kin-openapi from 0.79.0 to 0.80.0 a772b8fc3 build(deps): bump github.com/evanw/esbuild from 0.13.8 to 0.13.10 dce49d133 resources: Rename excepted filenames for image golden testdata 61c5b7a2e build(deps): bump github.com/frankban/quicktest from 1.13.1 to 1.14.0 1d60bd1ef Fix typo in error message 75c9b893d create: Validate the target path in hugo new 64e1613fb Fix panic when specifying multiple excludeFiles directives b959ecbc8 htime: Set zone of datetime from from `go-toml` 70e454812 Added nodesource apt repository to snap package 355ff83e7 config: Set HUGO_ENABLEGITINFO=false override in Set_in_string 471ed91c6 hugofs: Add includeFiles and excludeFiles to mount configuration 94a5bac5b build(deps): bump github.com/mitchellh/mapstructure from 1.4.1 to 1.4.2 9830ca9e3 resources: Always preserve the original transform error b64fd0577 readme: Add hyperlink to the banner 2706437a7 build(deps): bump github.com/getkin/kin-openapi from 0.78.0 to 0.79.0 ec7c993cf deps: github.com/evanw/esbuild v0.13.5 => v0.13.8 32c6f656d create: Return error on no content dirs e02e0727e Fix file permissions in new archetype implementation 096f5e192 Fix the "page picker" logic in --navigateToChanged ba35e6985 Add a cross process build lock and use it in the archetype content builder c7957c90e readme: Fix a typo on OpenBSD bb0537703 deps: github.com/alecthomas/chroma v0.9.2 => v0.9.4 9185e11ef Reimplement archetypes 168a3aab4 build(deps): bump github.com/tdewolff/minify/v2 from 2.9.21 to 2.9.22 8bcfa3bdf deps: Update github.com/evanw/esbuild v0.13.5 d7331aaa7 releaser: Fix regexp cd4e67af1 build(deps): bump github.com/mattn/go-isatty from 0.0.13 to 0.0.14 e6ad1f0e7 build(deps): bump github.com/getkin/kin-openapi from 0.75.0 to 0.78.0 625d2c257 releaser: Update to Go go1.17.2 e6e44b7c4 Fix value of useResourceCacheWhen in TestResourceChainPostCSS 64abc83fc Allow multiple plugins in the PostCSS options map f8d132d73 docs: Create path.Clean documentation 26f1919ae Skip a test assertion on CI e55466ce7 tpl/path: Add path.Clean ecf025f00 readme: Remove tracking image fab1e43de Revert "Remove credit from release notes" e03f82eef Pass minification errors to the user a864ffe9a Clarify "precision" in currency format functions b49da3328 build(deps): bump github.com/evanw/esbuild from 0.12.24 to 0.12.29 7c21eca74 resources: Use default math/rand.Source for concurrency safety 13ad8408f commands: Make the error handling for the mod commands more lenient 1cabf61dd modules: Add some help text to the 'unknown revision' error 268e3069f deps: Update github.com/yuin/goldmark v1.4.0 => v1.4.1 3efc2e2af releaser: Prepare repository for 0.89.0-DEV 5bc547389 releaser: Add release notes to /docs for release of 0.88.1 bb3254385 releaser: Bump versions for release of 0.88.1 9b1d6d7e3 releaser: Add release notes for 0.88.1 [ci skip] e1ead4dbc Bump down again to Go 1.16.7 for the release builds 5b59b9c17 releaser: Prepare repository for 0.89.0-DEV acc5eb5b5 releaser: Add release notes to /docs for release of 0.88.0 6cacfa329 releaser: Bump versions for release of 0.88.0 4d03cd780 Release 0.88.0 8b14fdbf8 Update 0.88.0-relnotes.md fc21b63b4 releaser: Add release notes for 0.88.0 6631c9c7e Run go mod tidy cf73cc2ec js: Fix import order for ./foo when both ./foo.js and ./foo/index.js exists 7d1f806ec commands: Don't fail on template errors on go mod graph etc. 04b595996 build(deps): bump github.com/getkin/kin-openapi from 0.74.0 to 0.75.0 c278b6e45 build(deps): bump github.com/frankban/quicktest from 1.13.0 to 1.13.1 107c86feb build(deps): bump github.com/evanw/esbuild from 0.12.22 to 0.12.24 a0489c2df Avoid failing with "module not found" for hugo mod init and similar 0fc2ce9e4 Update to Go 1.17 32569285c Remove Pygments from snapcraft.yml 5a46eefbc Revert "build(deps): bump github.com/fsnotify/fsnotify from 1.4.9 to 1.5.0" 7a15edafe highlight: Add tabindex when code is not highlighted 2f0945baf build(deps): bump github.com/evanw/esbuild from 0.12.17 to 0.12.22 f4ffeea71 Fix it so disableKinds etc. does not get merged in from theme 7ba3f3d20 build(deps): bump golang.org/x/text from 0.3.6 to 0.3.7 f70165242 build(deps): bump github.com/fsnotify/fsnotify from 1.4.9 to 1.5.0 bc0743ed8 Prevent minifier from removing quoutes around post-processed attributes ffa2fe611 Revert "commands: Avoid too many watch file handles causing the server to fail to start" d966f5d08 highlight: Remove some pygments references 3f38c785b commands: Avoid too many watch file handles causing the server to fail to start 24589c081 build(deps): bump github.com/getkin/kin-openapi from 0.68.0 to 0.74.0 efebd756e deps: Update github.com/spf13/cast v1.4.0 => v1.4.1 58b6742cf Import time/tzdata on Windows 32ead4b1e releaser: Bump to Go 1.16.7 abd969a67 Revert "tpl/time: Handle nil values in time.AsTime" 3e1107289 tpl/time: Handle nil values in time.AsTime 9bba9a3a9 parser: Indent TOML tables d6c8cd771 Fix `lang.FormatPercent` description dfe54d321 releaser: Prepare repository for 0.88.0-DEV b0c541e49 releaser: Add release notes to /docs for release of 0.87.0 2ed7be295 releaser: Bump versions for release of 0.87.0 d9d1ef8b0 Release 0.87 ec1c1c345 Merge branch 'b087' into release-0.87.0 c7fd13462 Update 0.87.0-relnotes.md a5d2632eb Update 0.87.0-relnotes.md 494f284be docs: Adjust config docs bf738d2f4 docs: Regen CLI docs 8d19850e2 docs: Regen docs helper 093498352 Merge commit 'bd77f6e1c99e04a476f0b1bb4e44569134e02399' into release-0.87.0 bd77f6e1c Squashed 'docs/' changes from 60a58d123..327003421 1c5b025dd docs: Adjust time zone docs c13d33dd5 releaser: Add release notes for 0.87.0 d70c48570 Make sure module config loading errors have file positioning info 9ff17c332 tpl/time: Adjust tests to handle matching local time zones 7aaaf7e33 mod: Remove superflous replace statement 3a9665559 Reduce binary size vs locale, update to CLDR v36.1 9a7383caf deps: Update github.com/tdewolff/minify/v2 v2.9.20 => v2.9.21 6c70e1f22 Fix error handling for the time func alias 4d221ce46 Fail on invalid time zone e3dc5240f Improve handling of <nil> Params 268065cb2 Merge branch 'release-0.86.1' e0304c06e releaser: Add release notes for 0.86.1 [ci skip] 7aa8b1cd7 releaser: Prepare repository for 0.87.0-DEV f6821b88a releaser: Add release notes to /docs for release of 0.86.1 580d320a6 releaser: Bump versions for release of 0.86.1 b75d4526e releaser: Add release notes for 0.86.1 [ci skip] 94b616bdf config: Fix a potential deadlock in config reading e90b3591a build(deps): bump github.com/evanw/esbuild from 0.12.16 to 0.12.17 4b7da6a9d build(deps): bump github.com/getkin/kin-openapi from 0.67.0 to 0.68.0 7907d24ba tpl/lang: Add new localized versions of lang.FormatNumber etc. 726fe9c3c Go back to WARNING for Page deprecations b5de37ee7 Handle toml.LocalDate and toml.LocalDateTime in front matter bf301daf1 deps: Upgrade github.com/pelletier/go-toml/v2 v2.0.0-beta.3 => v2.0.0-beta.3.0.20210727221244-fa0796069526 a3701e093 Switch to go-toml v2 40b6016cf build(deps): bump github.com/tdewolff/minify/v2 from 2.9.19 to 2.9.20 7e1305710 Add a TOML front matter benchmark efa5760db Add timezone support for front matter dates without one a57dda854 Localize time.Format f9afba933 build(deps): bump github.com/getkin/kin-openapi from 0.61.0 to 0.67.0 a5d2ba429 build(deps): bump github.com/spf13/cast from 1.3.1 to 1.4.0 31972f364 build(deps): bump google.golang.org/api from 0.45.0 to 0.51.0 2e58782f9 build(deps): bump github.com/sanity-io/litter from 1.5.0 to 1.5.1 7b68f6524 build(deps): bump github.com/mattn/go-isatty from 0.0.12 to 0.0.13 81265af2c build(deps): bump github.com/spf13/cobra from 1.1.3 to 1.2.1 c102c9719 build(deps): bump github.com/mitchellh/mapstructure from 1.3.3 to 1.4.1 7c0f904f2 build(deps): bump github.com/google/go-cmp from 0.5.5 to 0.5.6 b2fbd4d13 build(deps): bump github.com/mitchellh/hashstructure from 1.0.0 to 1.1.0 90041d1b6 build(deps): bump github.com/gobuffalo/flect from 0.2.2 to 0.2.3 05047096f build(deps): bump github.com/pelletier/go-toml from 1.9.0 to 1.9.3 a469156ea build(deps): bump github.com/aws/aws-sdk-go from 1.38.23 to 1.40.8 18fdd85bc build(deps): bump github.com/tdewolff/minify/v2 from 2.9.18 to 2.9.19 aeb1935d4 deps: Update github.com/evanw/esbuild v0.11.16 => v0.12.16 c7252224c Deprecate Blackfriday and fix a potential deadlock in config e09d7882c deps: Update github.com/yuin/goldmark v1.3.9 => v1.4.0 15c0eed04 build(deps): bump github.com/frankban/quicktest from 1.12.0 to 1.13.0 91cbb9630 Bump all long-living deprecations to ERRORs a352d19d8 Fix theme count in release notes 11bb67dcf releaser: Prepare repository for 0.87.0-DEV 41c6c52ea releaser: Add release notes to /docs for release of 0.86.0 d270eaf4f releaser: Bump versions for release of 0.86.0 b2e67505f Release 0.86.0 32508045d navigation: Check Page first in URL() e521c9a36 Update 0.86.0-relnotes.md dfb1cc431 releaser: Add release notes for 0.86.0 0294a4a4f Merge commit '53a352795a69a9d4a373f50ec62138595948c6ea' 53a352795 Squashed 'docs/' changes from 6ebb5dad9..60a58d123 351ed0f56 commands: Fix panic on invalid config in "hugo mod get" and similar d831d2fce Simplify "active menu" logic for section menus 634481ba8 Fix Params case handling for menu items defined in site config c19f65f95 minifiers: Make keepWhitespace = true default for HTML 022c47955 hugofs: Make FileMeta a struct f27e54244 markup: Add tabindex="0" to default <pre> wrapper ae6cf93c8 Fix default values when loading from config dir a70da2b74 Fix the deprecation error/warn log levels 805664818 markup/goldmark: Rename/reorder the hook methods ee3d2bb1d markup/goldmark: Support auto links in render hook eb2a50036 Adjust a test helper 5cb52c231 Add config.cascade 30eea3915 resources: Regenerate image golden testdata 8f40f34cd Fix transparency problem when converting 32-bit images to WebP 8ddbc9546 releaser: Prepare repository for 0.86.0-DEV 724d5db58 releaser: Add release notes to /docs for release of 0.85.0 875fe4050 releaser: Bump versions for release of 0.85.0 56362e4bc Update 0.85.0-relnotes.md f5cfb9e25 releaser: Add release notes for 0.85.0 04dc469fb commands: Move time notification to after any build errors 07919d1cc exif: Log warning for metadata decode error f75f90079 Fix tab selection of disabled items in internal pagination template e31b1d194 commands: Make the --poll flag a duration 43a23239b docs: Regen CLI docs 4479f09c9 Merge commit '7eb0e10a80708c638554b8221a3120dc1168566c' 7eb0e10a8 Squashed 'docs/' changes from 710856e5a..6ebb5dad9 24ce98b6d Add polling as a fallback to native filesystem events in server watch 0019d60f6 deps: Bump github.com/yuin/goldmark v1.3.9 e451b984c Fix panic when theme has permalinks config b4d60b3db releaser: Prepare repository for 0.85.0-DEV 020e4acee releaser: Add release notes to /docs for release of 0.84.4 4c34faf42 releaser: Bump versions for release of 0.84.4 a339f6266 releaser: Add release notes for 0.84.4 [ci skip] 4c8552b11 Fix Cloudflare vs Netlify cache dir issue 34e4742f0 Fix date format in schema and opengraph templates bffa2a2a9 releaser: Prepare repository for 0.85.0-DEV a1b0353cc releaser: Add release notes to /docs for release of 0.84.3 bc6f84c58 releaser: Bump versions for release of 0.84.3 80410257e releaser: Add release notes for 0.84.3 [ci skip] 6c8c0c8b6 config: Fix Netlify default cache dir logic 49fedbc51 config: Fix handling of invalid OS env config overrides 829072010 releaser: Prepare repository for 0.85.0-DEV e0c67958f releaser: Add release notes to /docs for release of 0.84.2 f6b9ce6eb releaser: Bump versions for release of 0.84.2 4b03399b7 releaser: Add release notes for 0.84.2 [ci skip] 40dfdd095 modules: Add module.import.noMounts config 3a6dc6d3f modules: Use value type for module.Time 6cd2110ab commands: Add version time to "hugo config mounts" 6a365c271 commands: Add some more info to "hugo config mounts" 19aa95fc7 Fix config handling with empty config entries after merge 923dd9d1c Fix config loading for "hugo mod init" d9bdd37d3 deps: Update to Minify v2.9.18 b2eaf4c8c Remove credit from release notes efb6ee6c1 releaser: Prepare repository for 0.85.0-DEV 4bd65e224 releaser: Add release notes to /docs for release of 0.84.1 ff2266300 releaser: Bump versions for release of 0.84.1 8677cfb04 releaser: Add release notes for 0.84.1 [ci skip] 093dacab2 Fix language menu config regression 4a9d408fe config: Fix merge of config with map[string]string values. 931205988 releaser: Bump to Goreleaser v0.171.0 a7e3da242 markup: Rename Header(s) to Heading(s) in ToC struct b70a12ec4 Merge commit '4dd90050f154c91373329a5d7e348289c40be12f' 4dd90050f Squashed 'docs/' changes from 3a923e155..710856e5a 3d544c9ae releaser: Prepare repository for 0.85.0-DEV 2c4689f7b releaser: Add release notes to /docs for release of 0.84.0 9c0860f74 releaser: Bump versions for release of 0.84.0 a1694b06a releaser: Increase timeout 219ec3800 releaser: Add release notes for 0.84.0 be6b901cf docs: Regenerate docs helper 643b67193 output: Make WebAppManifestFormat NotAlternative=true ab4e1dfa4 media: Adjust test assertion 02f31897b media: support application/manifest+json 402da3f8f docs: Regenerate docshelper 92405e5b0 Squashed 'docs/' changes from 4c81c6c2a..3a923e155 a074f758b Merge commit '92405e5b0adc5d8c3dfde88d6a8b67eb09169190' bb2aa0870 Implement configuration in a directory for modules 9096842b0 tpl: Rename err-missing-instagram-accesstoken => error-missing-instagram-accesstoken 3aa7f0b27 deps: Update github.com/alecthomas/chroma v0.9.1 => v0.9.2 9b870aa78 deps: Run go mod tidy 93aad3c54 Split out the puthe path/filepath functions into common/paths 5af045eba resources/image: Fix fill with smartcrop sometimes returning 0 bytes images 8eafe0845 deps: Update to Goldmark v1.3.8 31fb29fb3 Do not read config from os.Environ when running tests d392893cd Misc config loading fixes a886dd53b github: Set a dummy Instagram token a91cd7652 docs: Regenerate docs helper 162f41d0e Merge commit '32ba623541d74ee0b7ae4efb1b8326dc49af28b8' 32ba62354 Squashed 'docs/' changes from bcc4f9324..4c81c6c2a 552cef5c5 Update to Go 1.16.5, Goreleaser 0.169.0 73483d0f9 tpl: Add a terse pagination template variant to improve performance 9b5debe4b Upgrade Instagram shortcode 12530519d Fix nested OS env config override when parent does not exist f55d2f437 tpl/fmt: Add erroridf template func 282f1aa3d tpl/data: Print response body on HTTP errors fcd63de3a tpl/data: Misc header improvements, tests, allow multiple headers of same key 150d75738 tpl/data: Allows user-defined HTTP headers with getJSON and getCSV 06d295427 hugofs: Set modTime at creation time 26ae12c0c Fix invalid timestamp of the "public" folder ee733085b config: Fix env split to allow = character in values 01758f99b Add math.Max and math.Min 845a7ba4f Catch incomplete shortcode error 10f60de89 Use SPDX license identifier 785a31b5b navigation: Cache and copy Menu for sorting bc1e05286 deps: Update to LibSASS 3.6.5 f518b4f71 publisher: Make the HTML element collector more robust dc6b7a75f Revert "publisher: Make the HTML element collector more robust" 3f515f0e3 Revert "publisher: Get the collector in line with the io.Writer interface" a9bcd3818 publisher: Get the collector in line with the io.Writer interface ef0f1a726 publisher: Make the HTML element collector more robust abbc99d4c common/maps: Add Scratch.DeleteInMap 76c95f55a Display version when building site (#8533) 2c7f5b62f docs: Update querify function description and examples c46fc838a tpl: Allow 'Querify' to take lone slice/interface argument 504c78da4 modules/npm: Change SetEscapeHTML to false b660ea8d5 Add a benchmark 64f88f301 readme: Update dependency list 7a2c10ae6 tpl: Fix countwords to handle special chars e1c328df2 releaser: Prepare repository for 0.84.0-DEV 5afe0a57d releaser: Add release notes to /docs for release of 0.83.1 8900e3391 releaser: Bump versions for release of 0.83.1 9753e1b9c releaser: Add release notes for 0.83.1 [ci skip] ececd1b12 langs/i18n: Fix warning regression in i18n b0ca723eb releaser: Prepare repository for 0.84.0-DEV 4c65ceccc releaser: Add release notes to /docs for release of 0.83.0 57a471a0d releaser: Bump versions for release of 0.83.0 9b63af55b Update 0.83.0-relnotes.md 23fc65832 docs: Fix shortcode e7b5e36e0 releaser: Add release notes for 0.83.0 a9b52b417 docs: Regenerate docs helper b073a1c97 docs: Regenerate CLI docs 4227cc1bd commands: Remove all dates from gendoc c239c643f Squashed 'docs/' changes from fb551cc75..bcc4f9324 d7b22aee4 Merge commit 'c239c643fee10bfa217cb108755b798f8f5f3b10' 3cc4fdd6f deps: Update getkin/kin-openapi v0.60.0 => v0.61. 7eb80a9e6 langs/i18n: Fix multiple unknown language codes 78c1a6a7c deps: Update github.com/evanw/esbuild v0.11.14 => v0.11.16 f6745ad35 Remove .Site.Authors from embedded templates f523e9f0f deploy: Don't treat a NotFound response for Delete as a fatal error. 63cd05ce5 snap: Switch to deb packages of nodejs and python3-pygments 902535ef1 snapcraft.yaml: Install bin/node from node/14/stable 70aebba04 build(deps): bump github.com/getkin/kin-openapi from 0.55.0 to 0.60.0 3e3b7d447 build(deps): bump github.com/evanw/esbuild from 0.11.13 to 0.11.14 c13d36874 resources/page: Fix permalinks pattern detection for some of the sections variants 048418ba7 deps: Update to Chroma v0.9.1 eebde0c2a langs/i18n: Improve plural handling of floats e4dc9a82b tpl/collections: Fix where on type mismatches 0d86a32d8 Make the shortcode template lookup for output formats stable 65c502cc8 build(deps): bump github.com/evanw/esbuild from 0.11.12 to 0.11.13 537c905ec langs/i18n: Revise the plural implementation 243951ebe snapcraft.yaml: Update to "base: core20" fe2ee0280 build(deps): bump github.com/frankban/quicktest from 1.11.3 to 1.12.0 316d65cd7 build(deps): bump google.golang.org/api from 0.44.0 to 0.45.0 b95229ab4 build(deps): bump github.com/aws/aws-sdk-go from 1.37.11 to 1.38.23 0551df090 Correct function name in comment bca40cf0c Fix Params case handling in where with slices of structs (e.g. Pages) 057e5a22a deps: Upgraded github.com/evanw/esbuild v0.11.0 => v0.11.12 fd96f65a3 docs: Regen docs helper 8f7891e70 Merge commit '07b8d9466dfb59c429c1b470a0443337bc0aeefe' 07b8d9466 Squashed 'docs/' changes from 9cece6640..fb551cc75 d3a64708f build(deps): bump github.com/tdewolff/minify/v2 from 2.9.15 to 2.9.16 3b56244f4 build(deps): bump golang.org/x/text from 0.3.5 to 0.3.6 f5d3d635e publisher: Remove some unreachable code 0d3c42da5 build(deps): bump github.com/getkin/kin-openapi from 0.39.0 to 0.55.0 ef34dd8f0 publisher: Some performance tweaks for the HTML elements collector bc80022e0 publisher: Exclude comment and doctype elements from writeStats 2bb9496ce Merge branch 'release-0.82.1' fda3c4d1e releaser: Prepare repository for 0.83.0-DEV 60618210b releaser: Add release notes to /docs for release of 0.82.1 f8b064f3c releaser: Bump versions for release of 0.82.1 4713e509b releaser: Add release notes for 0.82.1 [ci skip] 6e9d2bf0c Regression in media type suffix lookup e73f7a770 Regression in media type suffix lookup 3ddffd064 build(deps): bump github.com/yuin/goldmark from 1.3.2 to 1.3.5 6fc52d185 Remove duplicate references from release notes 73c3ae818 build(deps): bump github.com/spf13/afero from 1.5.1 to 1.6.0 7ca118fdf build(deps): bump github.com/pelletier/go-toml from 1.8.1 to 1.9.0 33d5f8059 Add webp image encoding support 509d39fa6 build(deps): bump google.golang.org/api from 0.40.0 to 0.44.0 7725c41d4 build(deps): bump github.com/nicksnyder/go-i18n/v2 from 2.1.1 to 2.1.2 5d36d8015 build(deps): bump github.com/rogpeppe/go-internal from 1.6.2 to 1.8.0 9b34d42bb Remove extraneous space from figure shortcode c2d8f87cf build(deps): bump github.com/magefile/mage from 1.10.0 to 1.11.0 cbc246616 build(deps): bump github.com/google/go-cmp from 0.5.4 to 0.5.5 fa432b17b org: Disable broken pretty relative links feature 0cd55c66d deps: Update go-org to v1.5.0 0d5cf256e build(deps): bump github.com/jdkato/prose from 1.2.0 to 1.2.1 36527576b build(deps): bump github.com/spf13/cobra from 1.1.1 to 1.1.3 9b83f45b6 Add complete dependency list in "hugo env -v" 7fdd2b95e Add hugo.IsExtended 3d5dbdcb1 publisher: Also test minified HTML in the element collector 8a308944e publisher: Skip script, pre and textarea content when looking for HTML elements 7b4ade56d output: Only output mediaType once in docshelper JSON 7c7974b71 Fix typo in docshelper.go 5656a908d tpl: Remove the FuzzMarkdownify func for now 2dc222cec Add slice syntax to sections permalinks config 4d22ad580 deps: Upgrade github.com/evanw/esbuild v0.9.6 => v0.11.0 5e2f12891 Try to fix the fuzz build 97934779e releaser: Prepare repository for 0.83.0-DEV 9d9607843 releaser: Add release notes to /docs for release of 0.82.0 1efd93c09 releaser: Bump versions for release of 0.82.0 584a9b3e2 releaser: Add release notes for 0.82.0 86b4fd35e docs: Regenerate docs helper 195d108da docs: Regen CLI docs 81689af79 Squashed 'docs/' changes from bb15e9804..9cece6640 c94aa5cf4 Merge commit '81689af79901f0cdaff765cda6322dd4a9a7ccb3' df8bb8812 Simplify some config loading code 57d8d208e deps: Update github.com/evanw/esbuild v0.9.0 => v0.9.6 fc06e8508 Apply OS env overrides twice b725253f9 Attributes for code fences should be placed after the lang indicator only 35dedf15c deps: Bump github.com/tdewolff/minify/v2 v2.9.15 7ed56c694 Fix OS env override for nested config param only available in theme 24c716cac Fix `new theme` command description 137d2dab3 github: More explicit support link to discourse ba1d0051b media: Make Type comparable 1b1dcf586 deps: Update to esbuild v0.9.0 f6612d8bd exif: Fix handling of utf8 runes in nullString() 0a2ab3f8f exif: Allow more spacing characters in strings 4d24e2a32 media: Add a basic benchmark 18074d0c2 Fix output format handling for render hooks 35bfb6622 Rename a test 6d21559fb Add a debug helper ba16a14c6 Add support for Google Analytics v4 782c79ae6 Bump go.mod to Go 1.16 5afcae7e0 #8210 Upgrade golang version for Dockerfile 60469f429 Update CONTRIBUTING.md aed7df62a markup: Handle attribute lists in code fences cd0c5d7ef Allow markdown attribute lists to be used in title render hooks e7e194435 Merge commit '9d31f650da964a52f05fc27b7fb99cf3e09778cf' 9d31f650d Squashed 'docs/' changes from d343ebf71..bb15e9804 88a85dcea build(deps): bump github.com/kyokomi/emoji/v2 from 2.2.7 to 2.2.8 7f8530039 tpl: Add method mappings for strings.Contains, strings.ContainsAny 01dd7c16a Fixes #7698. c8f45d1d8 commands: Fix autocomplete docs b3504a0ee releaser: Prepare repository for 0.82.0-DEV 59d15c97d releaser: Add release notes to /docs for release of 0.81.0 9e2d086ca releaser: Bump versions for release of 0.81.0 b65518ac6 releaser: Increase build timeout 0e9cd8128 releaser: Add release notes for 0.81.0 fe77f7434 tpl: Make the build green again 9e99950c6 docs: Regen CLI docs 1b364b003 docs: Regen docs helper acb9109df Squashed 'docs/' changes from ef9c4913c..d343ebf71 7d0a26198 Merge commit 'acb9109df778fa4a51c0d8b29b3212b12988908f' c60806550 tpl: Regenerate internal templates ffd9dac42 tpl: Update date logic of opengraph and schema internal templates 88b93a09d Run go mod tidy 29fb456c9 build: Add arm64 to Darwinextended build and add vendorInfo 718fba7d6 Update Travis, GitHub, CircleCI and Snap to Go 1.16 (only) 9650e5684 tpl: Add temporary patch to fix template data race e77b2e3aa Pull in latest Go 1.16 template source b5485aeae Add breaking tests for "map read and map write in templates" ccb822eb5 Pull in latest Go template source 21e9eb18a Expand template newline testcase to commands ae57ba6a9 Add a test case for Go 1.16 template action newlines cf3e077da tpl/internal: Synch Go templates fork with Go 1.16dev 66beac99c deps: Update github.com/tdewolff/minify/v2 v2.6.2 => v2.9.13 968dd7a71 build(deps): bump github.com/frankban/quicktest from 1.11.2 to 1.11.3 38f29e817 build(deps): bump github.com/getkin/kin-openapi from 0.32.0 to 0.39.0 cd87813aa build(deps): bump github.com/aws/aws-sdk-go from 1.36.33 to 1.37.11 4e815b063 build(deps): bump github.com/sanity-io/litter from 1.3.0 to 1.5.0 652a59d38 build(deps): bump github.com/olekukonko/tablewriter from 0.0.4 to 0.0.5 84f0ec7f8 deps: Update to esbuild v0.8.46 bdfbcf6f4 modules: Add config option modules.vendorClosest b60e9279a js: Fix potential path issue on Windows a9b0fea6a build(deps): bump google.golang.org/api from 0.26.0 to 0.40.0 e8df09774 Change version string format and add VendorInfo to help with issue triaging 3a5ee0d2d modules: Allow absolute paths for any modules resolved via project replacement 4ffaeaf15 modules: Throw an error running hugo mod vendor on mountless module bf55afd71 Fix some humanize issues 5f621df25 commands: Add PowerShell completion support 7118f89cf Refer to mage instead of make in comment regarding commitHash e6dd31281 markup/goldmark: Fix handling of legacy attribute config 2681633db markup/goldmark: Add attributes support for blocks (tables etc.) 1b2472825 deps: Update to Goldmark v1.3.2 441b11bee Update to Dart Sass Protocol beta6 4867cd1de tpl/embedded: Exclude pages without Permalink from sitemap 92c6c4041 langs/i18n: Support translation files with suffix *.yml d36fd5b3e Refactor: Write to stdout by default a7c515e1b Refactor: Remove powershell support 216b00f35 Feat: Add zsh, fish and powershell completion support 144943798 github: Enable NPM tests on Windows 440fdb0eb deps: Update to esbuild v0.8.39 b2a48dce5 Trim whitespace in elements written to hugo_stats.json 35def0ae4 tpl/data: Add default user-agent header for getJSON requests 2f9dadae4 build(deps): bump github.com/aws/aws-sdk-go from 1.35.0 to 1.36.33 ed3071b75 docs: Remove mention of a file size limit for readFile ee9c13676 tpl/os: remove 1mb limit for readFile. 32b86076e js: Add Inject config option 241b7483e tpl: Fix race condition in text template baseof e19a046c4 js: Add Shims option a1fe552fc Fix nilpointer in js.Build error handling a1a9f088b Merge commit 'e48ffb763572814a3788780bb9653dfa2daeae22' e48ffb763 Squashed 'docs/' changes from 1de7a358c..ef9c4913c 07ad283f6 build(deps): bump github.com/spf13/afero from 1.4.1 to 1.5.1 2c8b5d916 pipes: Add external source map support to js.Build and Babel 0004a733c tpl: Fix metrics hint tracking 8a26ab0bc tpl: Do not return errors in substr for out-of-bounds cases 788e50ad3 tpl: Add missing test scenario for strings.Substr 4d2b6fc4c Run go mod tidy 212e5e554 deps: Update go-org to v1.4.0 4fdec67b1 rst: Adjust log level 9b681ecfb releaser: Prepare repository for 0.81.0-DEV 792ef0f41 releaser: Add release notes to /docs for release of 0.80.0 5b3fc1c67 releaser: Bump versions for release of 0.80.0 63a33afee Update 0.80.0-relnotes.md 69aa3d459 releaser: Add release notes for 0.80.0 ffbf5e45f Allow Dart Sass transformations to be cached on disk 48994ea76 dartsass: Dart Sass only supports `expanded` and `compressed` 428b0b329 dartsass: Add missing OutputStyle option 1f7e9f733 Update emoji import paths and version cea157402 Add Dart Sass support f9f779786 GroupByParamDate now supports datetimes a9718f44c para: Skip para test when not on CI f802bb236 Update SECURITY.md 6c2941827 releaser: Add release notes to /docs for release of 0.79.1 10ae7c321 Improve LookPath ae2d1bd52 docs: create a SECURITY.md 81975f847 Fix Resource.ResourceType so it always returns MIME's main type 8103188b9 para: Show more detail on failed time test 3ba147e70 images: Add images.Overlay filter a2d146ec3 tpl: Regenerate templates d2d493ab5 tpl: Fix series detection in opengraph ce96895de hugolib/paths: Fix typo 04b89857e all: Fix minor typos 21fa1e86f Fix BenchmarkMergeByLanguage c84ad8db8 deps: Bump github.com/spf13/cobra from 0.15.0 to 0.20.0 4e0acb89b chore: configure proper link to discourse.gohugo.io (#8020) 718e09ed4 tpl/internal/go_templates: Revert formatting d90e37e0c all: Format code with gofumpt 32471b57b build(deps): bump github.com/evanw/esbuild from 0.8.15 to 0.8.17 4fc918e02 tpl: Add title parameter to YouTube shortcode 0ad378b09 Use --baseURL path for live-reload URL aebfe156f Fix RelURL and AbsURL when path starts with language 907d9e926 build(deps): bump github.com/getkin/kin-openapi from 0.31.0 to 0.32.0 5862fd2a6 tpl: Fix substr when length parameter is zero 64789fb5d tpl: Refactor and fix substr logic 32d4bf68d releaser: Prepare repository for 0.80.0-DEV 1415efdcd releaser: Add release notes to /docs for release of 0.79.0 4e6bf7907 releaser: Bump versions for release of 0.79.0 50be4370b Update 0.79.0-relnotes.md 3d2e6a30d releaser: Add release notes for 0.79.0 4f1e4bb3f Merge commit '9f1265fde4b9ef186148337c99f08601633b6056' 9f1265fde Squashed 'docs/' changes from 57c1d1a67..1de7a358c d162bbd79 publisher: Fix memory usage in writeStats 17e0bbe82 build(deps): bump gopkg.in/yaml.v2 from 2.3.0 to 2.4.0 e442cf30a Fix server rebuild issue with partials referenced from render hooks 7e223b3ba Allow setting the delimiter used for setting config via OS env, e.g. HUGO_ 8a6e70605 deps: Update to github.com/evanw/esbuild 0.8.11 to 0.8.14 34061706e output: Add more layout lookup tests 6f7633df7 build(deps): bump github.com/google/go-cmp from 0.5.2 to 0.5.3 a546059a9 examples: Remove unneeded meta tag from blog example b5d906e31 build(deps): bump github.com/getkin/kin-openapi from 0.30.0 to 0.31.0 fd70bdafe docs: Regen docshelper 8f5c9a747 Add menu params e4fcb672e resources: Preserve url set in frontmatter without sanitizing 18c13adcd watcher: Add file deleted by accident 20a35374a Revert "docs: Regenerate docshelper" caf16c208 docs: Regenerate docshelper b298c06e0 deps: Update to Chroma v0.8.2 55e290af4 build(deps): bump github.com/evanw/esbuild from 0.8.8 to 0.8.11 506a190a8 build(deps): bump github.com/getkin/kin-openapi from 0.26.0 to 0.30.0 fc81de643 build(deps): bump github.com/evanw/esbuild from 0.8.6 to 0.8.8 fcaa324e3 releaser: Prepare repository for 0.79.0-DEV 959724f0e releaser: Add release notes to /docs for release of 0.78.2 a3012d85d releaser: Bump versions for release of 0.78.2 fc7f73927 releaser: Add release notes for 0.78.2 [ci skip] 78f227b66 js: Let ESBuild handle all imports from node_modules 5e03f644a build(deps): bump github.com/evanw/esbuild from 0.8.5 to 0.8.6 a92ef20ff build(deps): bump github.com/evanw/esbuild from 0.8.4 to 0.8.5 0d54a8440 build(deps): bump github.com/getkin/kin-openapi from 0.22.1 to 0.26.0 943f3c932 Update GH docs to say "main" as default branch 4f20bf29e Updated year in header 4c613d5d5 Added first fuzzer 82a182e52 build(deps): bump github.com/frankban/quicktest from 1.11.1 to 1.11.2 dfc662b20 build(deps): bump golang.org/x/text from 0.3.3 to 0.3.4 2f0917cc0 build(deps): bump github.com/evanw/esbuild from 0.8.3 to 0.8.4 7565cda1f releaser: Prepare repository for 0.79.0-DEV 347f2de67 releaser: Add release notes to /docs for release of 0.78.1 210f6d38a releaser: Bump versions for release of 0.78.1 03f87f8f0 releaser: Add release notes for 0.78.1 [ci skip] 3437174c3 Disable NPM test on Travis on Windows f66302ca0 travis: Install nodejs on Windows 944150baf js: Remove external source map option bf2837a31 js: Misc fixes cf6131dc1 releaser: Prepare repository for 0.79.0-DEV fd62817bb releaser: Add release notes to /docs for release of 0.78.0 3ebe83aea releaser: Bump versions for release of 0.78.0 0c16debc7 Update 0.78.0-relnotes.md 794e1f9e7 releaser: Add release notes for 0.78.0 c64e9504d Merge commit 'b74591123eac47a20d1f26ff3e2d291cd9c5cfc0' b74591123 Squashed 'docs/' changes from d1157b687..57c1d1a67 3b2fe3cd3 js: Add avoidTDZ option 85e4dd737 Make js.Build fully support modules 3089fc0ba js.Build: Generate tsconfig files e10e36cf7 releaser: Prepare repository for 0.78.0-DEV ef290125c releaser: Add release notes to /docs for release of 0.77.0 5d2fceeca releaser: Bump versions for release of 0.77.0 0696df668 Release 0.77.0 5ba49c877 Update 0.77.0-relnotes.md c3ccda8fa releaser: Add release notes for 0.77.0 beabc8d99 modules: Allow absolute paths for project imports 332b65e4c docs: Regen docs helper 3553fc533 Merge commit '9cabb46f68bae01aeb1859727dcb21e8a10f5ec7' 9cabb46f6 Squashed 'docs/' changes from 9abd3043a..d1157b687 173187e26 Add module.replacements 8a1c637c4 Fix setting HUGO_MODULE_PROXY etc. via env vars 6d95dc9d7 tpl: Fix reflection bug in merge 56a343507 deploy: Do not call CDN service invalidation when executing a dry run deployment d48a98c47 create: Pass editor arguments from newContentEditor correctly 3261678f6 deps: Bump github.com/spf13/cobra from 0.0.7 to 1.1.1 f465c5c30 build: Allow optional "nodeploy" tag to exclude deploy command from bin 3400aff25 Allow cascade _target to work with non toml fm fdfa4a5fe Allow getJSON errors to be ignored 8cbe2bbfa build(deps): bump github.com/evanw/esbuild from 0.7.15 to 0.7.18 807db97af tpl: Refactor time.AsTime location implementation 26eeb2914 tpl: Update Hugo time to support optional [LOCATION] parameter b886fa46b Revert "Add benchmark for building docs site" 14bce18a6 highlight: Avoid making unnecessary allocation 837e084bb Add benchmark for building docs site 08e4f9ff9 embedded: Always show page number when 5 pages or less acfa15386 output: Improve layout path construction f033d9f01 build(deps): bump github.com/frankban/quicktest from 1.11.0 to 1.11.1 59fe27942 build(deps): bump github.com/evanw/esbuild from 0.7.14 to 0.7.15 62119022d Merge branch 'release-0.76.5' 2f3f41f73 releaser: Prepare repository for 0.77.0-DEV 60f0725b3 releaser: Add release notes to /docs for release of 0.76.5 dcf70ea5a releaser: Bump versions for release of 0.76.5 7487c0abf releaser: Add release notes for 0.76.5 [ci skip] 79a022a15 Render aliases even if render=link ead5799f7 Render aliases even if render=link d57be1132 build(deps): bump github.com/spf13/afero from 1.4.0 to 1.4.1 d07059669 build(deps): bump github.com/evanw/esbuild from 0.7.9 to 0.7.14 f5ea359dd docker: Update to Go 1.15 and Alpine 3.12 78b26d538 output: Test all lookup permutations in TestLayout 28179bd55 output: Reformat TestLayout table fef057b48 releaser: Prepare repository for 0.77.0-DEV 50dfe40b9 releaser: Add release notes to /docs for release of 0.76.4 1ef4211fe releaser: Bump versions for release of 0.76.4 b148063ec releaser: Add release notes for 0.76.4 [ci skip] e9a7ebaf6 snap: Install postcss v8 explicitly as it is now a peer dependency 506820435 lang/i18n: Fix for language code case issue with pt-br etc. 49972d079 Merge branch 'release-0.76.3' c98132e30 Add merge helper af19253f4 releaser: Prepare repository for 0.77.0-DEV e96234590 releaser: Add release notes to /docs for release of 0.76.3 d62bc7477 releaser: Bump versions for release of 0.76.3 1b1d62fdc releaser: Add release notes for 0.76.3 [ci skip] 33e9d79b7 langs/i18n: Add workaround for known language, but missing plural rule error fc6abc39c langs/i18n: Fix for bare TOML keys 18ed22be5 releaser: Prepare repository for 0.77.0-DEV 207913f34 releaser: Add release notes to /docs for release of 0.76.2 830b1a94d releaser: Bump versions for release of 0.76.2 605cff407 releaser: Add release notes for 0.76.2 [ci skip] 6dd60fca7 Revert "deps: Update to github.com/tdewolff/minify v2.9.4" 138a02591 releaser: Prepare repository for 0.77.0-DEV 58ac83a98 releaser: Add release notes to /docs for release of 0.76.1 2b8e8e6d9 releaser: Bump versions for release of 0.76.1 aef836986 releaser: Add release notes for 0.76.1 [ci skip] f9e798e8c langs/i18n: Fix i18n .Count regression ee56efffc Fix typo in 0.76.0 release note 2c4e76e96 releaser: Prepare repository for 0.77.0-DEV 9c7d6e475 releaser: Add release notes to /docs for release of 0.76.0 4482958f9 releaser: Bump versions for release of 0.76.0 e1ec3bc2b Release 0.76.0 1cfa63b9e releaser: Add release notes for 0.76.0 b9318e431 docs: Regen docshelper 5e39eb20a Merge commit 'e5568488051a571df48401e03f1304b95dbc9028' e55684880 Squashed 'docs/' changes from 4895c29c5..9abd3043a 634938908 pagemeta: Make BuildConfig.Render an enum c63db7f1f Allow cascade to be a slice with a _target discriminator 5e2a547cb Add force flag to server redirects config ee090c094 build(deps): bump github.com/evanw/esbuild from 0.7.8 to 0.7.9 edc5c4741 tpl: Add Do Not Track (dnt) option to Vimeo shortcode 05e358fd3 build(deps): bump github.com/tdewolff/minify/v2 from 2.9.5 to 2.9.7 a2e85d9a7 build(deps): bump github.com/aws/aws-sdk-go from 1.34.34 to 1.35.0 4fba78dd0 build(deps): bump github.com/getkin/kin-openapi from 0.22.0 to 0.22.1 c011b4667 build(deps): bump github.com/aws/aws-sdk-go from 1.34.33 to 1.34.34 35348b4b3 build(deps): bump github.com/evanw/esbuild from 0.7.7 to 0.7.8 34915777c build(deps): bump github.com/aws/aws-sdk-go from 1.34.27 to 1.34.33 0f4a837ed build(deps): bump github.com/evanw/esbuild from 0.7.4 to 0.7.7 b395d686e build(deps): bump github.com/tdewolff/minify/v2 from 2.9.4 to 2.9.5 97987e5c0 langs/i18n: Upgrade to go-i18n v2 111344113 publisher: Fix writeStats with quote inside quotes 4855c186d build(deps): bump github.com/evanw/esbuild from 0.7.2 to 0.7.4 0c3d2b67e Fix CLI example for PostCSS 8 6f07ec7e9 build(deps): bump github.com/aws/aws-sdk-go from 1.34.26 to 1.34.27 4318dc72f build(deps): bump github.com/alecthomas/chroma from 0.8.0 to 0.8.1 acdc27a32 build(deps): bump github.com/evanw/esbuild from 0.7.1 to 0.7.2 3acde9ae0 Make sure CSS is rebuilt when postcss.config.js or tailwind.config.js changes 473b6610d Fix typo in redirect error message 0bce97703 build(deps): bump github.com/aws/aws-sdk-go from 1.34.22 to 1.34.26 b254532b5 deps: Update to github.com/tdewolff/minify v2.9.4 05a228929 snap: Bump bundled Node.js from v12.18.3 to v12.18.4 8e553dcde markup/asciidocext: Add preserveTOC option d4fc70a3b build(deps): bump github.com/frankban/quicktest from 1.10.2 to 1.11.0 d905abc00 build(deps): bump github.com/evanw/esbuild from 0.6.32 to 0.7.1 8f3946746 build(deps): bump github.com/rogpeppe/go-internal from 1.5.1 to 1.6.2 b01b2564e build(deps): bump github.com/jdkato/prose from 1.1.1 to 1.2.0 9fa5ebe2c build(deps): bump github.com/spf13/afero from 1.2.2 to 1.4.0 efaed306b releaser: Prepare repository for 0.76.0-DEV a4a7bab73 releaser: Add release notes to /docs for release of 0.75.1 2a9dce423 releaser: Bump versions for release of 0.75.1 30159b58e releaser: Add release notes for 0.75.1 [ci skip] cd00f7f96 resources/image: Fix nilpointer for images with no Exif 214afe4c1 modules/npm: Preserve the original package.json if it exists cd830bb02 tpl: Fix grammar in the new 'requires non-zero' error message a8458bfb2 releaser: Prepare repository for 0.76.0-DEV fef924baf releaser: Add release notes to /docs for release of 0.75.0 07b5e602f releaser: Bump versions for release of 0.75.0 70f16e84e Release 0.75.0 abadf2954 releaser: Add release notes for 0.75.0 377ad87a5 Set PWD in environment when running the Node apps 292b0e26e typo: already -> already 534ae9c57 Squashed 'docs/' changes from d3eb97a33..4895c29c5 df56682a1 Merge commit '534ae9c57a902aea9ed6e62390dec11fa74b7122' be2404c8b docs: Regen docs helper c8da8eb1f docs: Regenerate CLI docs 787da6bd5 releaser: Drop 32-bit for MacOS 85ba9bfff Add "hugo mod npm pack" 9df60b62f Print layout name if it was specified when showing missing layout file error 4fad43c8b build(deps): bump github.com/aws/aws-sdk-go from 1.34.21 to 1.34.22 fb0f2cc71 markup/highlight: Add support to linkable line anchors on Chroma 748fd4cb0 snap: Bump bundled Node.js from v8.12.0 to v12.18.3 b82f440c5 Revert "snap: Change confinement from strict to classic" c8143efa5 build(deps): bump github.com/getkin/kin-openapi from 0.14.0 to 0.22.0 c80132bbe build(deps): bump github.com/aws/aws-sdk-go from 1.34.20 to 1.34.21 75fa4c5c9 build(deps): bump github.com/spf13/viper from 1.6.1 to 1.7.1 fd7969e0b deps: Run "go mod tidy" b7fa3c4bb deps: Update to Goldmark v1.2.1 6a848cbc3 markup/asciidocext: Fix AsciiDoc TOC with code 746ba803a build(deps): bump github.com/aws/aws-sdk-go from 1.27.1 to 1.34.20 612b7d376 build(deps): bump github.com/mitchellh/mapstructure from 1.1.2 to 1.3.3 6f4ff1a46 snap: Change confinement from strict to classic ddeca4593 build(deps): bump github.com/spf13/cobra from 0.0.5 to 0.0.7 31f2091f5 build(deps): bump github.com/sanity-io/litter from 1.2.0 to 1.3.0 d4611c432 modules: Add noVendor to module config 20af9a078 modules: Add ignoreImports to module imports config 9a1e6d15a modules: Make ignoreVendor a glob pattern 84adecf97 build(deps): bump github.com/gorilla/websocket from 1.4.1 to 1.4.2 573558a07 build(deps): bump github.com/fsnotify/fsnotify from 1.4.7 to 1.4.9 8b10c22f8 build(deps): bump github.com/kyokomi/emoji 195bd1243 build(deps): bump github.com/markbates/inflect from 1.0.0 to 1.0.4 6a544ece2 build(deps): bump github.com/frankban/quicktest from 1.7.2 to 1.10.2 4b430d456 Encode & in livereload injected code b9f10c75c build(deps): bump github.com/niklasfasching/go-org from 1.3.1 to 1.3.2 537c598e9 build(deps): bump github.com/bep/golibsass from 0.6.0 to 0.7.0 67348676f build(deps): bump golang.org/x/text from 0.3.2 to 0.3.3 f9cc0ec76 build(deps): bump github.com/evanw/esbuild from 0.6.5 to 0.6.32 b5483eed6 build(deps): bump github.com/nicksnyder/go-i18n from 1.10.0 to 1.10.1 90285f475 Revert "Update dependabot.yml" 4949bdc2e markup/asciidocext: Fix broken test f7c1b5fe1 docs: Update replaceRE func 183e86260 docs: Update replace func f50ee6bbe docs: Update merge function c0655ba6c Update dependabot.yml a2dda22c3 Create dependabot.yml 910d81a69 Remove Pygments from requirements.txt 8c490a73b docs: Regen CLI docs e6cd9da42 docs: Regen docs helper dcf25c0b4 markup/asciidocext: Revert trace=true 7d7771b67 Squashed 'docs/' changes from 7297c1172..d3eb97a33 b9e4f5898 Merge commit '7d7771b673e5949f554515a2c236b23192c765c8' e820b366b Update to Go 1.15.1 and 1.14.8 4055c1218 Fix some change detection issues on server reloads 3ba7c9253 markup/asciidoc: Add support for .TableOfContents 19ef27b98 markup/goldmark: Add a test case c6b661de8 js.Build: Add SourceMap flag with inline option cdfd1c99b tpl: Add limit support to replaceRE 047af7cfe tpl: Extend merge to accept multiple parameters f9ebaaed1 tpl: Add limit option to replace template function d39636a5f commands: Remove logic that hides 'Building Sites' message after build completes ad01aea3f Fixed misspelled words ec3742046 Improve stderr logging for PostCSS and simlilar ae63c2b5c Fail on partials with return when given none or a zero argument e627449c0 Update to Go 1.15 c2235c6a6 Revert "Update stale.yml" 4f69ade71 Update stale.yml f8b8b091f Merge commit 'cb39847dee488c373dd5bc2a3706385342a59355' cb39847de Squashed 'docs/' changes from a26d0e610..7297c1172 5f4259014 Remove trailing whitespace and tabs from RSS templates f3cb0be35 Fix a typo in CONTRIBUTING.md bffc4e12f Revert "Fix ellipsis display logic in pagination template" 12f6a1cdc Respect mediatypes for deploy 2fa851e65 Fix ellipsis display logic in pagination template 21dbfa1f1 mage: Add uninstall target e5591e89d deps: Update Chroma to 0.8.0 88929bc23 deps: Update go-org to v1.3.1 850c18bfe releaser: Prepare repository for 0.75.0-DEV da0437b48 releaser: Add release notes to /docs for release of 0.74.3 90fe00df0 releaser: Bump versions for release of 0.74.3 02efadc24 releaser: Add release notes for 0.74.3 [ci skip] 00e00da23 publisher: Collect transition attributes as classes 45c665d39 Fix Asciidoctor args a06c06a5c Fix date format in internal schema template 0256959a3 resources/js: Add option for setting bundle format eded9ac2a resources/js: Simplify options handling 8d7251282 make sure documentation intro text only appears once e81aef0a9 resources/js: Add es5 build target 673e622fa Merge commit '28bd06265e88454b061810578919d891909a83ad' 28bd06265 Squashed 'docs/' changes from c3b4f8410..a26d0e610 9f9191471 deps: esbuild v0.6.5 3727a9d11 releaser: Prepare repository for 0.75.0-DEV 48565de62 releaser: Add release notes to /docs for release of 0.74.2 808e12621 releaser: Bump versions for release of 0.74.2 aa85a46dc releaser: Add release notes for 0.74.2 [ci skip] 35011bcb2 Add .Defines to js.Build options 084624baa releaser: Prepare repository for 0.75.0-DEV 15163266c releaser: Add release notes to /docs for release of 0.74.1 a74f7d3cc releaser: Bump versions for release of 0.74.1 cb84d9816 releaser: Add release notes for 0.74.1 [ci skip] c91dbe4ce Fix baseof block regression 6e0452e18 releaser: Prepare repository for 0.75.0-DEV d2b116268 releaser: Add release notes to /docs for release of 0.74.0 626518430 releaser: Bump versions for release of 0.74.0 797127010 Release 0.74.0 1672a332d releaser: Add release notes for 0.74.0 823ce055e Squashed 'docs/' changes from cfd74b57d..c3b4f8410 5f7a65a08 Merge commit '823ce055ed3356da37e9ec4ac70446bdbbaa8de8' 25e3da334 docs: Regenerate docs helper 9df98ec49 Add proper Media Type handling in js.Build 2fc338070 Add js.Build asset bundling f1916f114 Merge commit '6aa5c9117fd34644459ea9bcfb1b3f5010658d5d' 6aa5c9117 Squashed 'docs/' changes from ac2c4a487..cfd74b57d 12a65e76d Add openapi3.Unmarshal 58c0f5e61 Remove trailing hyphen from auto heading ID a1c3e3c1f deploy: Ensure that non-trivial default flag values are passed through. 42e150fbf Fix server reload when non-HTML shortcode changes 028b35678 tpl/strings: Add strings.Count e9f87c4e3 Update formats.md doc for new allowed extensions. defd7106b tpl: Add debug.Dump beb6c03bc Update config.go to add two Asciidoctor extensions 4a3efea7e Add support for inline partials c66dc6c74 Add support for native Org dates in frontmatter 127d5feb3 deps: Update go-org to v1.3.0 2d42ba912 deps: Update go-org to v1.2.0 5b7b5dea1 Update bug_report.md ccfaeb678 hugolib: Add missing zero check on file 057b1377c cache: Remove some unused code 48dbb593f commands: Add an option to print memory usage at intervals f0266e2ef Rework external asciidoctor integration 77aa385b8 Enable the embedded template test when race detector is off 545a1c1ce Merge branch 'release-0.73.0' 47aaa52e3 releaser: Prepare repository for 0.74.0-DEV 428907cc3 releaser: Add release notes to /docs for release of 0.73.0 a78b3e341 releaser: Bump versions for release of 0.73.0 cfcb01451 Release 0.73.0 0b579db80 Updated installation instruction about Sass/SCSS support ee5d027cd releaser: Add release notes for 0.73.0 4a340ba25 Remove some old release notes 3466884e3 Create robots.txt in the domain root directory 6ff435aa3 Make GroupByParamDate work with string params 82abca32f Add GroupByLastmod fc045e12a Rename taxonomy kinds from taxonomy to term, taxonomyTerm to taxonomy 9679023f2 Fix aliases with path in baseURL 0a9172672 Merge commit 'efa74c5c6e6ff1daddeb5834ea7c69bed2acf171' efa74c5c6 Squashed 'docs/' changes from 9be494de3..ac2c4a487 6408c1cbc Fix server data race/nil pointer in withMaps 522ba1cd9 Fix order of GetTerms 889dc47ce Add genDocsHelper mage target f720fe56d Fix aliases with uglyURLs d6ed17c60 Fix crash for closing shortcode with no .Inner set 145b3fcce Fix aliases with relativeURLs 01e249e97 Regenerate templates 4b560cc11 Beautify HTML generated by pagination template e3e627e6b Add a nested data dir test 83d03a520 hugofs: Use os.PathError in RootMappingFs.doLstat fc0f13b68 commands: Fix URL rewrites vs fast render server mode 7eeebe1e5 tpl/crypto: Add hmac 740fa4a91 Remove credit (#7347) f8c67f93e Allow hook template per section/type 3d9235e8f tpl: Fix bad rounding in NumFmt f7d909f39 releaser: Prepare repository for 0.73.0-DEV 8a7ef3cf4 releaser: Add release notes to /docs for release of 0.72.0 2dfe242ea releaser: Bump versions for release of 0.72.0 7a1464e54 Release 0.72.0 41d50b4dd releaser: Add release notes for 0.72.0 4d53ae697 releaser: Adjust the "thanks" section 626b16e02 Merge commit '9e1dcefc5f559944b70d2fa520f6acd5c56a69f2' 9e1dcefc5 Squashed 'docs/' changes from 6c2195936..9be494de3 2919a6a50 common/maps: Add Scratch.Values 432885c49 deps: Update Goldmark to improve Typographer 6a3e89743 Add redirect support to the server 9613e3e8a Fix typo in install instructions c950c86b4 publisher: Fix tag collector for nested table elements 915202494 snap: Fix build error: my previous commits did not fix it b3e4f911f releaser: Prepare repository for 0.72.0-DEV a301f6b2a releaser: Add release notes to /docs for release of 0.71.1 646bc8508 releaser: Bump versions for release of 0.71.1 5c0d10045 releaser: Add release notes for 0.71.1 [ci skip] 81f563324 Add some more date test cases 9698b0dab Fix RenderString vs render hooks 32344fe3d Prevent WARNINGs in RenderString 4d7fa9f11 Fix IsAncestor/IsDescendant for taxonomies a985efcec Fix GetPage on section/bundle name overlaps 6c3c6686f Fix Go template script escaping c34bf4856 Add a test helper 833d16d46 releaser: Prepare repository for 0.72.0-DEV 06150c87b releaser: Add release notes to /docs for release of 0.71.0 330e52ebe releaser: Bump versions for release of 0.71.0 9e7823537 Release 0.71 7cd66c53b releaser: Add release notes for 0.71.0 723ec555e Fix Babel on Windows 518d14964 commands: Use WARN log level also for the early initialization e0e81b280 Merge commit 'c9403cbceaaeff53ff4833561f4eefe1dc1a405e' c9403cbce Squashed 'docs/' changes from ec0abe052..6c2195936 3cc41523b Update to Go 1.14.3 and Go 1.13.11 2fd0a5a67 Improve error message when no Babel installed 6e051c053 Add test for headings render hook 423b8f2fb Add render template hooks for headings 991934497 Add math.Pow 558c09305 deploy: Do not suppress .well-known/ directory b69a36140 snap: Quote "@babel/cli" to solve build error a0103864a snap: Remove custom x-nodejs plugin b342e8fbd Upgrade chroma to 0.7.3 to fix invalid css 6205d56b8 Use .Lastmod for og:updated_time a5039ddda releaser: Prepare repository for 0.71.0-DEV 7f47b99ea releaser: Add release notes to /docs for release of 0.70.0 b98e2f66b releaser: Bump versions for release of 0.70.0 57ebab7c2 Release 0.70.0 0e314925f releaser: Add release notes for 0.70.0 e4621446c Merge commit '89044b8f8795f17c36396c67823183a20fc88139' 89044b8f8 Squashed 'docs/' changes from 19f44e150..ec0abe052 01befcce3 deps: Update minify to v2.6.2 04b1a6d99 Add support for sort by boolean dd31e8000 deps: Update to Libsass 3.6.4 6add6d77b Rename transpileJS to babel 2a171ff1c resources: Add JavaScript transpiling solution 67f920419 Disable a test locally c03ea2b66 Fix some missing JS class collector cases fe60b7d9e Add diagnostic hints to init timeout message c2d9fd1eb releaser: Prepare repository for 0.70.0-DEV ec9dcf304 releaser: Add release notes to /docs for release of 0.69.2 03802ff3c releaser: Bump versions for release of 0.69.2 5e31198c9 releaser: Add release notes for 0.69.2 [ci skip] 8d5766d41 Fix IsAncestor and IsDescendant when the same page is passed 5c41f41ad deps: Update goldmark-highlighting 27a4c4410 Fix IsAncestor and IsDescendant under subsection ade27699e releaser: Prepare repository for 0.70.0-DEV 17661debb releaser: Add release notes to /docs for release of 0.69.1 8549189e8 releaser: Bump versions for release of 0.69.1 c2c7a4ce5 releaser: Add release notes for 0.69.1 [ci skip] 49e6c8cb4 hugolib/filesystems: Fix typo in test suite f37e77f2d Fix class collector when running with --minify 27af5a339 related: Fix toLower b3c825756 Fix broken test 5146dc614 tpl/tmplimpl/template: Change defer RLock to RUnlock 736f84b2d hugolib: Add Unlock before panic cd4d82020 docs: Fix typo in Hugo's Security Model 2b28e5a9c deps: Update go-org to v1.1.0 102ec2da7 commands: Modify gen chromastyles to output all CSS classes feaa582cb deps: Update to goldmark v1.1.28 ee67dbeff Fix query parameter handling in server fast render mode 4a3f2427e releaser: Prepare repository for 0.70.0-DEV 4205844bc releaser: Add release notes to /docs for release of 0.69.0 9b55d1358 releaser: Bump versions for release of 0.69.0 6f56a636f Update 0.69.0-relnotes.md 5ec7fa343 releaser: Add release notes for 0.69.0 b7ff4dc23 docs: Regen docs helper da3c3e5fb Squashed 'docs/' changes from 20d77860b..19f44e150 30748decf Merge commit 'da3c3e5fbd0de65f956618cd2e35401460a3cd02' 095bf64c9 Collect HTML elements during the build to use in PurgeCSS etc. 7791a804e deps: Update to latest emoji package c774b230e Update hosting-on-aws-amplify.md 2f721f8ec Add basic "post resource publish support" 8568928aa tpl: Extend Jsonify to support options map 1bc93021e tpl: Extend Jsonify to support optional indent parameter 7eba37ae9 Typo correction efc61d6f3 commands: Use semver for min_version per recommendations d8d6a25b5 modules: Fix hugo mod vendor for regular file mounts 9f12be54e Revert "Revert "common/herrors: Fix typos in comments"" 4437e918c Revert "common/herrors: Fix typos in comments" 4de3ecdc2 deps: Updateto gitmap v1.1.2 1123711b0 common/herrors: Fix typos in comments 3d84ef972 Merge commit 'c494c37a4523fbf2db6274dc87e0877fd5bec24b' c494c37a4 Squashed 'docs/' changes from 2a0ea423d..20d77860b 9c9987535 helpers: Fix TrimShortHTML 4a39564ef Fix IsDescendant/IsAncestor for overlapping section names b6e097cfe fix typo in getting started 19a8accc9 releaser: Prepare repository for 0.69.0-DEV 157669a0e releaser: Add release notes to /docs for release of 0.68.3 8f49df946 releaser: Bump versions for release of 0.68.3 1a68ad4e3 releaser: Add release notes for 0.68.3 [ci skip] 523d51948 Fix _build.list.local logic 971b28904 releaser: Prepare repository for 0.69.0-DEV 63bbb40df releaser: Add release notes to /docs for release of 0.68.2 73ae6d581 releaser: Bump versions for release of 0.68.2 e18a2ad3f releaser: Add release notes for 0.68.2 [ci skip] cfa73050a Fix cache reset for a page's collections on server live reload 244e49c0e releaser: Prepare repository for 0.69.0-DEV 98dc46e1a releaser: Add release notes to /docs for release of 0.68.1 87dd5725d releaser: Bump versions for release of 0.68.1 8c6a03a92 releaser: Add release notes for 0.68.1 [ci skip] 1ce3e7d52 releaser: Include "Revert" commits in change log c9dc316ad Revert "resources: Add data context to the key in ExecuteAsTemplate" 1664a0e89 releaser: Prepare repository for 0.69.0-DEV 1e67854b1 releaser: Add release notes to /docs for release of 0.68.0 e1b609af9 releaser: Bump versions for release of 0.68.0 8e5566af6 Release 0.68.0 1005f754e Update 0.68.0-relnotes.md efde7078e releaser: Add release notes for 0.68.0 2ebb9f548 Fix Go build version 7204b354a Some minify configuration adjustments 574c2959b Add minify config 99958f90f Allow headless bundles to list pages via $page.Pages and $page.RegularPages 1d91d8e14 Update to Go 1.14.1 and 1.13.9 95f492114 Fix GetTerms nil pointer c947351d7 Merge commit 'aa54803a84208816e9c678359bd3f86760484ce0' aa54803a8 Squashed 'docs/' changes from 988f7d5c2..2a0ea423d cc2a5d52a Pass directory name to filters in LstatIfPossible in the same way as Readdir 52c159c45 Update to goldmark 1.1.25. c7b6d74e8 resources: Fix scss vs css import regexp 1a8af7d4f Add workaround for regular CSS imports in SCSS 03b93bb98 Add .RegularPagesRecursive 94fb4dc3d releaser: Prepare repository for 0.68.0-DEV 4f44227bd releaser: Add release notes to /docs for release of 0.67.1 99d36237c releaser: Bump versions for release of 0.67.1 e371162c3 releaser: Add release notes for 0.67.1 [ci skip] 5eadc4c0a metrics: Fix --templateMetricsHints 18cb21ff2 resources: Add data context to the key in ExecuteAsTemplate df298558a Improve Tailwind/PostCSS error messages b1106f871 deps: Update Blackfriday c0177fe2b resources: Try to fix a Go 1.15 go vet error 5914f91b6 Add languageDirection to language configuration 5b4659fa0 releaser: Prepare repository for 0.68.0-DEV 7f1da3efc releaser: Add release notes to /docs for release of 0.67.0 f7d4b01c6 releaser: Bump versions for release of 0.67.0 b809b9680 Update 0.67.0-relnotes.md a9c91361c releaser: Add release notes for 0.67.0 63393230c docs: Doument the server config 6b61f2a5b Merge commit '14e369b961943a0b977776899e24e8bea63834df' 14e369b96 Squashed 'docs/' changes from 341ecabb2..988f7d5c2 6cceef65c Fix ambigous error on site.GetPage ffcb4aeb8 Fix handling of HTML files without front matter 8279d2e22 Support unComparable args of uniq/complement/in c4fa2f079 tpl: Fix error with unicode in file paths 108314444 Add HTTP header support for the dev server 51e178a6a deploy: Add include and exclude support for remote cb12f41a9 releaser: Prepare repository for 0.67.0-DEV 78c3c78fc releaser: Add release notes to /docs for release of 0.66.0 713132cd4 releaser: Bump versions for release of 0.66.0 bbaefd7e3 Update 0.66.0-relnotes.md cc1a71886 releaser: Add release notes for 0.66.0 6a34f88dc Skip some tests on CircleCI ae383f04c {{ in }} should work with html.Template type ee31e61fb docs: Regen CLI docs 760a87a45 commands: Add --all flag to hugo mod clean 3d3fa5c3f Add build.UseResourceCacheWhen ee3d02134 Update dependency list in README.md 8947c3fa0 Fix ref/relref short lookup for pages in sub-folder d7798906d tpl: Change error message on missing resource 305ce1c9e resources: Add full filename to image when processing fails 3e9db2ad9 hugolib: Fix error handling in page collector 449deb7f9 Update dependency list in README 1746e8a9b Fix ref/relRef regression for relative refs from bundles 6f48146e7 identity: Fix potential infinite recursion in server change detection b0d850321 Fix rebuild logic when editing template using a base template b66d38c41 resources: Add basic @import support to resources.PostCSS 05a74eaec deploy: Implement include/exclude filters for deploy 33ae62108 Update to Go 1.14 and 1.13.8 1352bc880 Add hugo.IsProduction function d184e5059 tpl: Add math.Sqrt 322c285ba releaser: Prepare repository for 0.66.0-DEV 211ba42a9 releaser: Add release notes to /docs for release of 0.65.3 0ac528d74 releaser: Bump versions for release of 0.65.3 d8bde266c releaser: Add release notes for 0.65.3 [ci skip] 0bd6356c6 Fix panic when home page is drafted ca68abf0b Fix goldmark toc rendering a524124be Fix crashes for 404 in IsAncestor etc. c1eb62512 releaser: Add release notes to /docs for release of 0.65.2 1510f0778 releaser: Bump versions for release of 0.65.2 aa2ef4542 releaser: Add release notes for 0.65.2 [ci skip] 76b2afe64 Apply missing go fmt f46053034 Fix panic on no output formats 4c2a0de41 Fix panic in 404.Parent 6be6684cc releaser: Add release notes to /docs for release of 0.65.1 dbaa15d40 releaser: Bump versions for release of 0.65.1 a449e87da releaser: Add release notes for 0.65.1 [ci skip] 7ef5a4c83 hugolib: Fix 2 Paginator.Pages taxonomy regressions a70bbd069 hugolib: Fix deletion of orphaned sections 24afe2b82 releaser: Add release notes to /docs for release of 0.65.0 9fd7d3957 releaser: Bump versions for release of 0.65.0 c45025cb9 releaser: Add release notes for 0.65.0 a5ebdf7d1 docs: Regenerate CLI docs 9bdedb251 Fix lazy publishing with publishResources=false dce210ab5 modules: Improve "hugo mod clean" 0b96aba02 commands: Add "hugo mod verify" fa520a2d9 Add Page.GetTerms 4b670bc8c Squashed 'docs/' changes from 16753a78d..341ecabb2 82029c1ec Merge commit '4b670bc8cc38103c2c60e5090c2f56bf30832b8d' 7489a8645 Add a list terms benchmark da54787cf Handle disabled RSS even if it's defined in outputs c7975b48b Fix goMinorVersion on non-final Go releases b2dcd53e3 Use the tree for taxonomy.Pages() 36983e618 Add some cagegories to the site collections benchmarks d73e37387 tpl: Adjust the RSS taxonomy logic aa3e18305 tpl: Fix RSS template for the terms listing 1b7acfe76 Fix taxonomy 19e12caf8 Fix RenderString for pages without content 20f2211fc modules: Do not try to get local themes in "hugo mod get" a21a9373e deps: Update goldmark-highlighting 775c7c247 commands: Support "hugo mod get -u ./..." eada236f8 Introduce a tree map for all content e5329f13c Another benchmark rename 5b145ddc4 Rename the Edit benchmarks 3c568ad01 markup/highlight: Fix chroma highlight 54bdcaaca Refactor a benchmark to make it runnable as test 1622510a5 Add benchmark for content edits 56d0b6588 Add "go mod verify" to build scripts 75c3787fc Add git to Dockerfile 9babb1f0c deps: Update go.sum 8a5124d6b commands: Rename doWithCommandeer to cfgInit/cfgSetAndInit 898a0a96a deps: Update golibsass 3b721110d Shuffle test files before insertion 40ba7e6d6 Update to LibSass v3.6.3 4f43c9022 releaser: Prepare repository for 0.65.0-DEV c327e75d0 releaser: Add release notes to /docs for release of 0.64.1 8bd8d4fe9 releaser: Bump versions for release of 0.64.1 ad7c38cd6 releaser: Add release notes for 0.64.1 [ci skip] b78576fd3 hugofs: Fix mount with hole regression 18888e09b Fix bundle resource ordering regression 1e5eb8679 Merge commit '3c0036805d64fdd8290f1c4a31371780ff3ea365' 3c0036805 Squashed 'docs/' changes from bd0e15bb6..16753a78d 7f0ebd4a3 CONTRIBUTING: Fix note about CGO 23ea43180 Update Go version requirement 6a74cbe91 releaser: Prepare repository for 0.65.0-DEV 241db8f78 releaser: Add release notes to /docs for release of 0.64.0 7624ab028 releaser: Bump versions for release of 0.64.0 8490a0aa9 Update 0.64.0-relnotes.md bd731d27b releaser: Add release notes for 0.64.0 80dd6ddde Fix module mount in sub folder 299731012 Mention a "no CGO rule" 2bbc865f7 commands: Fix config environment handling 0792cfa9f Update to Go 1.13.7 and Go 1.12.16 b3f0674b8 transform/livereloadinject: Add defer to livereload script tag ef78a0d18 transform/livereloadinject: Don't use document.write to inject livereload 585958645 hubolig: Add a render hook whitespace test 2d159e9cc Do not render alias paginator pages for non-HTML outputs f45cb3172 Fix base template handling with preceding comments 49ef64720 modules: Fix "hugo mod get -u" with no arguments 8f08cdd0a transform/livereloadinject: Inject livereload script right after head if possible 281abb18e deps: Update goldmark to v1.1.22 d8e685154 releaser: Prepare repository for 0.64.0-DEV 934ee21fa releaser: Add release notes to /docs for release of 0.63.2 c7427a50e releaser: Bump versions for release of 0.63.2 49e2931eb releaser: Add release notes for 0.63.2 [ci skip] e8831a056 hubolib: Revert to .Type = "page" when empty 74b6c4e5f And now finally fix the 404 templates 8df5d76e7 Fix 404 with base template regression 8ae2c9c3d releaser: Prepare repository for 0.64.0-DEV ce9aceb74 releaser: Add release notes to /docs for release of 0.63.1 fd32849bf releaser: Bump versions for release of 0.63.1 417f9ddf5 releaser: Add release notes for 0.63.1 [ci skip] 0df7bd62d deps: Make the build flags shared between sites f441f6751 Fix baseof with regular define regression 7ed22e9fb Revert to minify v2.6.1 fb974ae87 releaser: Prepare repository for 0.64.0-DEV 745ddcbba releaser: Add release notes to /docs for release of 0.63.0 3b3f5a259 releaser: Bump versions for release of 0.63.0 d10ed683c Release 0.63.0 19e387d18 releaser: Add release notes for 0.63.0 cafb1d53c docs, output: Add base template lookup variant to docs.json 4f466db66 docs: Regen docs helper 17af79a03 Fix 0.62.1 server rebuild slowdown regression 2fefc0160 tpl/compare: Fix eq when > 2 args 0c251be66 Allow multiple arguments in ne/ge/gt/le/lt functions Treat op arg1 arg2 arg3 ... as (arg1 op arg2) && (arg1 op arg3) and so on for ne/ge/gt/le/lt. 836c24261 hugolib: Disable a test assertion on ARM c6d650c8c tpl/tplimpl: Rework template management to get rid of concurrency issues 8585b388d deps: Update go-org d61bee5e0 examples: Fix blog not building 21ca2e9ce Add support for newline characters in raw string shortcode 3efa1d812 deps: Update github.com/alecthomas/chroma 65ec8fe82 deps: Update minify to v2.7.2 d3e8ab2e3 deps: Update Goldmark to v1.1.21 da8145565 Allow raw string literals in shortcode params 0c0bb3728 deps: Update github.com/gohugoio/testmodBuilder ddd75f212 hugolib: Some more benchmark adjustments 4ed6ebef4 hugolib: Adjust site benchmarks 94cfdf6be deps: Update direct dependencies 451380177 minifiers: Update to new CSS config 56354a63b deps: Update to Minify v2.7.0 b9b73a2f6 Revert "Add support for freebsd/arm64" aead8108b Add support for freebsd/arm64 1cf235412 tpl: Put Go's internal template funcs in Hugo's map df6e9efd8 Update releasenotes_writer.go ea05c0e84 hugolib: Add a benchmark with lots of templates 273047b5b releaser: Prepare repository for 0.63.0-DEV 83e501849 releaser: Add release notes to /docs for release of 0.62.2 12230b689 releaser: Bump versions for release of 0.62.2 afdb180e2 releaser: Add release notes for 0.62.2 [ci skip] 196a9df58 hugolib: Fix relative .Page.GetPage from bundle 9b6e61464 markup/goldmark: Adjust auto ID space handling d62ede8e9 docs: Document the new autoHeadingIDType setting 81b7e48a5 docs: Regenerate docshelper 16e7c1120 markup/goldmark: Add an optional Blackfriday auto ID strategy 8f071fc15 markup/goldmark: Make the autoID type config a string 469351d5b Merge commit '26f1458a2df6b55eee3a5de46f5fec23a43a7c7d' 26f1458a2 Squashed 'docs/' changes from 54f0e8776..bd0e15bb6 5ee1f0876 markup/goldmark: Simplify code a82d2700f markup/goldmark: Make auto IDs GitHub compatible ae816452b releaser: Prepare repository for 0.63.0-DEV a1518704a releaser: Add release notes to /docs for release of 0.62.1 3a21a1708 releaser: Bump versions for release of 0.62.1 451746ddd releaser: Add release notes for 0.62.1 [ci skip] ff6253bc7 Support files in content mounts aa4ccb8a1 Update alpine base image in Dockerfile to 3.11 5509954c7 hugolib: Fix inline shortcode regression 6b59b64f0 releaser: Prepare repository for 0.63.0-DEV 6608f1557 releaser: Add release notes to /docs for release of 0.62.0 b361d9a46 releaser: Bump versions for release of 0.62.0 592a7d104 Release 0.62.0 93216fda7 releaser: Add release notes for 0.62.0 8a4005cf2 Squashed 'docs/' changes from af4b7ac5b..54f0e8776 740b72558 Merge commit '8a4005cf2b0ef34265ff8051a6b76226685fc226' 1fb17be9a deps: Update Goldmark to v1.1.18 51d89dab1 deps: Update go-org c8bfe47c6 docs: More on hooks 50cc7fe54 tpl: Do not return any value in errorf 1773d71d5 tpl: Add a warnf template func 8a58ebb31 hugolib: Improve error and reload handling of hook templates in server mode 045368381 deps: Update to Goldmark v1.1.17 55c29d4de docs: Regen docshelper ccb1bf1ab tpl/collections: Some more params merge adjustments a67d95fe1 Preserve HTML Text for image render hooks ad6504e6b Fix abs path handling in module mounts 158e7ec20 Fix incorrect MIME type from image/jpg to image/jpeg eef934ae7 deps: Update Goldmark 00954c5d1 Preserve HTML Text for link render hooks 1b785a7a6 tpl/collections: Fix merge vs Params d20ca3700 tpl: Get rid of the custom template truth logic 3e316155c docs: Footnote e625088ef Add render template hooks for links and images 67f3aa72c Merge commit '2e711a28c71e8667258e5ab824f9b9a71c261b0a' 2e711a28c Squashed 'docs/' changes from 51c4f3184..af4b7ac5b 0947cf958 Enhance accessibility to issues 3c24ae030 hugolib: Fix test 03d6960a1 deps: Re-introduce the correct version of Goldmark 92c7f7ab8 tpl: Add some comments a03c631c4 Rework template handling for function and map lookups 167c01530 Create lightweight forks of text/template and html/template 4c804319f markup/tableofcontents: Add config option for ordered list 186a5ebfc releaser: Prepare repository for 0.62.0-DEV 9b445b9da releaser: Add release notes to /docs for release of 0.61.0 3af783966 releaser: Bump versions for release of 0.61.0 31f322a61 Release 0.61.0 38c60f2be releaser: Add release notes for 0.61.0 3cc217a65 deps: Update Goldmark 5f8c2818f Deprecate Ace and Amber c5f2f5837 markup: Add typographic chars from goldmark to toc 0efb00c2a tpl/partials: Allow any key type in partialCached 40a092b06 markup: Reimplement pygmentsCodefencesGuessSyntax d534ce942 deps: Update Goldmark a6b6b135a releaser: Prepare repository for 0.61.0-DEV 960667561 releaser: Add release notes to /docs for release of 0.60.1 6c0556308 releaser: Bump versions for release of 0.60.1 f5250ec09 releaser: Add release notes for 0.60.1 [ci skip] 86a5b59f6 deps: Update minify bb80fff69 Fix headless regression 347cfb0c1 deps: Update Goldmark b60ae35b9 hugolib: Fix timeout number parsing for YAML/JSON config 003ba5b10 releaser: Prepare repository for 0.61.0-DEV f2dea9b03 releaser: Add release notes to /docs for release of 0.60.0 763b0dcb9 releaser: Bump versions for release of 0.60.0 b2969b7a7 Release 0.60.0 60fea562c releaser: Add release notes for 0.60.0 14a1de14f modules: Add some more output if modules download takes time dcde8af8c Add some internal template image tests c91970c08 tpl/tplimpl: Featured and Site.Params image support for Schema dd1e5fc0b hugolib: Disable test assertion on Windows b0c7749fa deps: Update Goldmark 25a6b3369 tpl/tplimpl: Add support for featured and global image to OpenGraph template 017664392 hugolib: Fix cascade in server mode da5352359 hugolib: Fix .Sections vs siblings 96f09659c Fix language handling in ExecuteAsTemplate 03b369e67 hugolib: Adjust .Site.Permalinks deprecation level 69fd1c60d hugolib: Remove .Site.Ref/RelRef 33d733300 Deprecate mmark e3451371b hugolib: Fix recently broken timeout config 5c5231e09 commands: Use HUGO_ENV if set d6f7a9e28 resources/images: Make the image cache more robust 031f948f8 Update to Go 1.13.4 and Go 1.12.13 71597bd1a mage: Restore -v behaviour a8e9f8389 hugolib: Increase default timeout value to 30s 03e2d7462 hubolig: Fix potential data race ea96e1dc5 Revert "deps: Update Goldmark" 822191286 deps: Update Goldmark 8beaa4c25 mage: Fix mage check on darwin and add debugging output 8a89b8582 commands: Fix jekyll metadata import on individual posts e1175ae83 Improve grammar in README.md a2d77f4a8 markup/highlight: Replace the temp for with a dependency b546417a2 deps: Update Chroma 4175b0468 deps: Update Goldmark 55f951cbb markup/tableofcontents: GoDoc etc. 20f351ee4 Minor cleanups bfb9613a1 Add Goldmark as the new default markdown handler a3fe5e5e3 Fix Params case handling in the index, sort and where func cd07e6d57 Fix GetPage Params case issue 628efd6e2 common/para: Add parallel task executor helper 2dcc1318d Add some more output if loading modules takes time 14a985f8a Update homepage.md 0cf85c071 hugolib: Add a benchmark 20ec9fa2b modules: Do not check for remote modules if main project is vendored 812688fc2 hugolib: Fix emoji handling inside shortcodes a2670bf46 tpl/collections: Allow dict to create nested structures 1a36ce9b0 commands: Add hint when dir not empty 90d0cdf23 tpl/collections: Add collections.Reverse 95ef93be6 tpl/collections: Make index work with slice as the last arg 79355043e Merge commit 'efc0b1bb6c6564f54d596467dbc6a18cb206954e' efc0b1bb6 Squashed 'docs/' changes from 723da4a37..51c4f3184 d1d1f240a hubolib: Headless bundles should not be listed in .Pages 70a1aa345 Support Go time format strings in permalinks cafecca44 travis: Increase timeout to 30000 for mage -v check 5f6b6ec68 Prepare for Goldmark 366ee4d8d deps: Update quicktest c26d00db6 hugolib: Fix ref/relref anhcor handling 8483b53ae deps: Update to Chroma v0.6.9 for Java lexer fix 9f46a72c7 tpl/collections: Add some index map test cases 9abd39678 helpers: Use pointer receiver for ContentSpec ad4c56b55 travis: Allow arm64 to fail 3717db1f9 minifiers: Add a JSON roundtrip test ae4fde086 Update .travis.yml for arm64 support, etc. c6d69d0c9 mage: Skip Test386 on non-AMD64 architectures c3d433af5 Update past go-cmp's checkptr fix 07a203406 releaser: Prepare repository for 0.60.0-DEV d5dab232c releaser: Add release notes to /docs for release of 0.59.1 e04a22c5e releaser: Bump versions for release of 0.59.1 d14265da8 releaser: Add release notes for 0.59.1 [ci skip] 33c474b9b hugofs: Fix crash in multilingual content fs ed2682325 Dockerfile: Switch to mage builds, various optimizations 66fe68ffc resources/images: Add exception for new test image c5e1e8241 Adjust benchmark templates baa975082 deps: Update to Chroma v0.6.8 to fix a crash 3e8b5a5c0 deps: Update quicktest e6aa6edb4 Do not attempt to build if there is no config file 6bcc5ad8b releaser: Prepare repository for 0.60.0-DEV 1dd0c69c7 releaser: Add release notes to /docs for release of 0.59.0 b084af4bf releaser: Bump versions for release of 0.59.0 0237d4595 Release 0.59.0 109ac877c releaser: Add release notes for 0.59.0 5ac0f751a Squashed 'docs/' changes from 0584815c8..723da4a37 de8ca7e4d Merge commit '5ac0f751aa47e52625662215f66efa99a6abfc2e' 5070ba6c9 Squashed 'docs/' changes from fdea5430f..0584815c8 ec5962278 Merge commit '5070ba6c9e6c492deade3c30cfe769b9dbf7151d' b9bd35d72 Squashed 'docs/' content from commit fdea5430f 27aef3f1f Merge commit 'b9bd35d72e14932fb6588ff62b90cddef0a060fc' as 'docs' git-subtree-dir: docs git-subtree-split: 9b06f951e61081c503927bb772b75f93504aeba8
-rw-r--r--.cspell.json82
-rw-r--r--_vendor/github.com/gohugoio/gohugoioTheme/data/sponsors.toml14
-rw-r--r--_vendor/github.com/gohugoio/gohugoioTheme/layouts/_default/_markup/render-link.html14
-rw-r--r--_vendor/github.com/gohugoio/gohugoioTheme/layouts/index.rss.xml98
-rw-r--r--_vendor/github.com/gohugoio/gohugoioTheme/layouts/news/list.html15
-rw-r--r--_vendor/github.com/gohugoio/gohugoioTheme/layouts/news/list.xml68
-rw-r--r--_vendor/github.com/gohugoio/gohugoioTheme/layouts/partials/home-page-sections/open-source-involvement.html2
-rw-r--r--_vendor/github.com/gohugoio/gohugoioTheme/layouts/partials/home-page-sections/sponsors.html40
-rw-r--r--_vendor/github.com/gohugoio/gohugoioTheme/layouts/partials/utilities/get-remote-data.html23
-rw-r--r--_vendor/github.com/gohugoio/gohugoioTheme/layouts/shortcodes/eturl.html36
-rw-r--r--_vendor/github.com/gohugoio/gohugoioTheme/layouts/shortcodes/img.html8
-rw-r--r--_vendor/github.com/gohugoio/gohugoioTheme/layouts/shortcodes/new-in.html4
-rw-r--r--_vendor/github.com/gohugoio/gohugoioTheme/static/images/GitHub-Mark-64px.pngbin924 -> 0 bytes
-rw-r--r--_vendor/github.com/gohugoio/gohugoioTheme/static/images/Github.svg1
-rw-r--r--_vendor/modules.txt2
-rw-r--r--assets/images/examples/zion-national-park-grayscale.jpgbin42537 -> 0 bytes
-rw-r--r--config/_default/menus/menus.en.toml44
-rw-r--r--content/en/_index.md2
-rw-r--r--content/en/about/_index.md8
-rw-r--r--content/en/about/benefits.md36
-rw-r--r--content/en/about/features.md190
-rw-r--r--content/en/about/introduction.md39
-rw-r--r--content/en/about/license.md6
-rw-r--r--content/en/about/privacy.md (renamed from content/en/about/hugo-and-gdpr.md)26
-rw-r--r--content/en/about/security.md (renamed from content/en/about/security-model.md)19
-rw-r--r--content/en/about/what-is-hugo.md57
-rw-r--r--content/en/commands/hugo.md3
-rw-r--r--content/en/commands/hugo_completion.md1
-rw-r--r--content/en/commands/hugo_completion_bash.md1
-rw-r--r--content/en/commands/hugo_completion_fish.md1
-rw-r--r--content/en/commands/hugo_completion_powershell.md1
-rw-r--r--content/en/commands/hugo_completion_zsh.md1
-rw-r--r--content/en/commands/hugo_config.md16
-rw-r--r--content/en/commands/hugo_config_mounts.md12
-rw-r--r--content/en/commands/hugo_convert.md1
-rw-r--r--content/en/commands/hugo_convert_toJSON.md1
-rw-r--r--content/en/commands/hugo_convert_toTOML.md1
-rw-r--r--content/en/commands/hugo_convert_toYAML.md1
-rw-r--r--content/en/commands/hugo_deploy.md1
-rw-r--r--content/en/commands/hugo_env.md1
-rw-r--r--content/en/commands/hugo_gen.md1
-rw-r--r--content/en/commands/hugo_gen_chromastyles.md10
-rw-r--r--content/en/commands/hugo_gen_doc.md1
-rw-r--r--content/en/commands/hugo_gen_man.md1
-rw-r--r--content/en/commands/hugo_import.md1
-rw-r--r--content/en/commands/hugo_import_jekyll.md1
-rw-r--r--content/en/commands/hugo_list.md10
-rw-r--r--content/en/commands/hugo_list_all.md5
-rw-r--r--content/en/commands/hugo_list_drafts.md5
-rw-r--r--content/en/commands/hugo_list_expired.md5
-rw-r--r--content/en/commands/hugo_list_future.md5
-rw-r--r--content/en/commands/hugo_list_published.md45
-rw-r--r--content/en/commands/hugo_mod.md1
-rw-r--r--content/en/commands/hugo_mod_clean.md16
-rw-r--r--content/en/commands/hugo_mod_get.md1
-rw-r--r--content/en/commands/hugo_mod_graph.md14
-rw-r--r--content/en/commands/hugo_mod_init.md12
-rw-r--r--content/en/commands/hugo_mod_npm.md1
-rw-r--r--content/en/commands/hugo_mod_npm_pack.md12
-rw-r--r--content/en/commands/hugo_mod_tidy.md12
-rw-r--r--content/en/commands/hugo_mod_vendor.md12
-rw-r--r--content/en/commands/hugo_mod_verify.md14
-rw-r--r--content/en/commands/hugo_new.md1
-rw-r--r--content/en/commands/hugo_new_content.md18
-rw-r--r--content/en/commands/hugo_new_site.md1
-rw-r--r--content/en/commands/hugo_new_theme.md1
-rw-r--r--content/en/commands/hugo_server.md95
-rw-r--r--content/en/commands/hugo_server_trust.md1
-rw-r--r--content/en/commands/hugo_version.md1
-rw-r--r--content/en/content-management/_common/_index.md2
-rw-r--r--content/en/content-management/_index.md4
-rw-r--r--content/en/content-management/archetypes.md33
-rw-r--r--content/en/content-management/build-options.md32
-rw-r--r--content/en/content-management/comments.md42
-rw-r--r--content/en/content-management/content-adapters.md355
-rw-r--r--content/en/content-management/cross-references.md18
-rw-r--r--content/en/content-management/data-sources.md126
-rw-r--r--content/en/content-management/diagrams.md24
-rw-r--r--content/en/content-management/formats.md166
-rw-r--r--content/en/content-management/front-matter.md477
-rw-r--r--content/en/content-management/image-processing/index.md26
-rw-r--r--content/en/content-management/markdown-attributes.md115
-rw-r--r--content/en/content-management/mathematics.md17
-rw-r--r--content/en/content-management/menus.md5
-rw-r--r--content/en/content-management/multilingual.md168
-rw-r--r--content/en/content-management/organization/index.md33
-rw-r--r--content/en/content-management/page-bundles.md214
-rw-r--r--content/en/content-management/page-resources.md110
-rw-r--r--content/en/content-management/related.md2
-rw-r--r--content/en/content-management/sections.md5
-rw-r--r--content/en/content-management/shortcodes.md295
-rw-r--r--content/en/content-management/static-files.md68
-rw-r--r--content/en/content-management/summaries.md137
-rw-r--r--content/en/content-management/syntax-highlighting.md8
-rw-r--r--content/en/content-management/taxonomies.md27
-rw-r--r--content/en/content-management/toc.md117
-rw-r--r--content/en/content-management/urls.md46
-rw-r--r--content/en/contribute/_index.md4
-rw-r--r--content/en/contribute/development.md30
-rw-r--r--content/en/contribute/documentation.md82
-rw-r--r--content/en/functions/_common/_index.md2
-rw-r--r--content/en/functions/_common/go-html-template-package.md14
-rw-r--r--content/en/functions/_index.md4
-rw-r--r--content/en/functions/collections/After.md4
-rw-r--r--content/en/functions/collections/Complement.md2
-rw-r--r--content/en/functions/collections/Dictionary.md35
-rw-r--r--content/en/functions/collections/First.md2
-rw-r--r--content/en/functions/collections/IndexFunction.md86
-rw-r--r--content/en/functions/collections/KeyVals.md6
-rw-r--r--content/en/functions/collections/NewScratch.md4
-rw-r--r--content/en/functions/collections/Querify.md25
-rw-r--r--content/en/functions/collections/Slice.md10
-rw-r--r--content/en/functions/collections/Sort.md2
-rw-r--r--content/en/functions/collections/Where.md16
-rw-r--r--content/en/functions/compare/Default.md2
-rw-r--r--content/en/functions/compare/Eq.md2
-rw-r--r--content/en/functions/compare/Ge.md8
-rw-r--r--content/en/functions/compare/Gt.md8
-rw-r--r--content/en/functions/compare/Le.md8
-rw-r--r--content/en/functions/compare/Lt.md8
-rw-r--r--content/en/functions/compare/Ne.md2
-rw-r--r--content/en/functions/data/GetCSV.md28
-rw-r--r--content/en/functions/data/GetJSON.md28
-rw-r--r--content/en/functions/debug/Dump.md33
-rw-r--r--content/en/functions/debug/Timer.md2
-rw-r--r--content/en/functions/diagrams/Goat.md16
-rw-r--r--content/en/functions/fmt/Errorf.md5
-rw-r--r--content/en/functions/fmt/Erroridf.md11
-rw-r--r--content/en/functions/fmt/Warnf.md7
-rw-r--r--content/en/functions/fmt/Warnidf.md43
-rw-r--r--content/en/functions/fmt/_common/_index.md2
-rw-r--r--content/en/functions/global/page.md6
-rw-r--r--content/en/functions/global/site.md10
-rw-r--r--content/en/functions/go-template/_common/_index.md2
-rw-r--r--content/en/functions/go-template/define.md4
-rw-r--r--content/en/functions/go-template/else.md6
-rw-r--r--content/en/functions/go-template/end.md10
-rw-r--r--content/en/functions/go-template/if.md2
-rw-r--r--content/en/functions/go-template/range.md8
-rw-r--r--content/en/functions/go-template/return.md2
-rw-r--r--content/en/functions/go-template/template.md4
-rw-r--r--content/en/functions/go-template/with.md2
-rw-r--r--content/en/functions/hugo/Generator.md2
-rw-r--r--content/en/functions/hugo/IsMultihost.md40
-rw-r--r--content/en/functions/hugo/IsMultilingual.md37
-rw-r--r--content/en/functions/hugo/Version.md2
-rw-r--r--content/en/functions/hugo/WorkingDir.md2
-rw-r--r--content/en/functions/images/Config.md6
-rw-r--r--content/en/functions/images/Dither.md162
-rw-r--r--content/en/functions/images/Filter.md2
-rw-r--r--content/en/functions/images/Padding.md2
-rw-r--r--content/en/functions/images/Process.md2
-rw-r--r--content/en/functions/images/UnsharpMask.md6
-rw-r--r--content/en/functions/images/_common/_index.md2
-rw-r--r--content/en/functions/images/_common/apply-image-filter.md4
-rw-r--r--content/en/functions/inflect/Singularize.md2
-rw-r--r--content/en/functions/js/Build.md23
-rw-r--r--content/en/functions/lang/FormatNumberCustom.md2
-rw-r--r--content/en/functions/math/Counter.md4
-rw-r--r--content/en/functions/os/Getenv.md2
-rw-r--r--content/en/functions/partials/Include.md17
-rw-r--r--content/en/functions/partials/IncludeCached.md2
-rw-r--r--content/en/functions/resources/ByType.md2
-rw-r--r--content/en/functions/resources/Concat.md6
-rw-r--r--content/en/functions/resources/Copy.md2
-rw-r--r--content/en/functions/resources/ExecuteAsTemplate.md6
-rw-r--r--content/en/functions/resources/FromString.md24
-rw-r--r--content/en/functions/resources/Get.md2
-rw-r--r--content/en/functions/resources/GetMatch.md2
-rw-r--r--content/en/functions/resources/GetRemote.md31
-rw-r--r--content/en/functions/resources/Match.md2
-rw-r--r--content/en/functions/resources/ToCSS.md10
-rw-r--r--content/en/functions/resources/_common/_index.md2
-rw-r--r--content/en/functions/safe/CSS.md48
-rw-r--r--content/en/functions/safe/HTML.md43
-rw-r--r--content/en/functions/safe/HTMLAttr.md53
-rw-r--r--content/en/functions/safe/JS.md50
-rw-r--r--content/en/functions/safe/JSStr.md29
-rw-r--r--content/en/functions/safe/URL.md72
-rw-r--r--content/en/functions/strings/ContainsNonSpace.md4
-rw-r--r--content/en/functions/strings/CountRunes.md2
-rw-r--r--content/en/functions/strings/Diff/diff-screen-capture.pngbin0 -> 7290 bytes
-rw-r--r--content/en/functions/strings/Diff/index.md33
-rw-r--r--content/en/functions/strings/FindRESubmatch.md2
-rw-r--r--content/en/functions/strings/RuneCount.md2
-rw-r--r--content/en/functions/strings/SliceString.md20
-rw-r--r--content/en/functions/strings/Split.md2
-rw-r--r--content/en/functions/strings/Substr.md13
-rw-r--r--content/en/functions/strings/Trim.md2
-rw-r--r--content/en/functions/strings/Truncate.md2
-rw-r--r--content/en/functions/time/Duration.md2
-rw-r--r--content/en/functions/time/Now.md2
-rw-r--r--content/en/functions/time/ParseDuration.md2
-rw-r--r--content/en/functions/time/_common/_index.md2
-rw-r--r--content/en/functions/transform/HTMLUnescape.md2
-rw-r--r--content/en/functions/transform/Markdownify.md6
-rw-r--r--content/en/functions/transform/Unmarshal.md31
-rw-r--r--content/en/functions/urls/AbsLangURL.md34
-rw-r--r--content/en/functions/urls/AbsURL.md36
-rw-r--r--content/en/functions/urls/Anchorize.md4
-rw-r--r--content/en/functions/urls/JoinPath.md2
-rw-r--r--content/en/functions/urls/Parse.md1
-rw-r--r--content/en/functions/urls/RelLangURL.md38
-rw-r--r--content/en/functions/urls/RelURL.md40
-rw-r--r--content/en/functions/urls/_common/_index.md2
-rw-r--r--content/en/functions/urls/_common/anchorize-vs-urlize.md4
-rw-r--r--content/en/getting-started/_index.md4
-rw-r--r--content/en/getting-started/configuration-markup.md282
-rw-r--r--content/en/getting-started/configuration.md243
-rw-r--r--content/en/getting-started/directory-structure.md57
-rw-r--r--content/en/getting-started/external-learning-resources/build-websites-with-hugo.pngbin0 -> 18058 bytes
-rw-r--r--content/en/getting-started/external-learning-resources/hia.jpgbin66768 -> 0 bytes
-rw-r--r--content/en/getting-started/external-learning-resources/hugo-in-action.pngbin0 -> 22891 bytes
-rw-r--r--content/en/getting-started/external-learning-resources/index.md75
-rw-r--r--content/en/getting-started/glossary.md138
-rw-r--r--content/en/getting-started/quick-start.md12
-rw-r--r--content/en/getting-started/usage.md14
-rw-r--r--content/en/hosting-and-deployment/_index.md4
-rw-r--r--content/en/hosting-and-deployment/hosting-on-github/index.md13
-rw-r--r--content/en/hosting-and-deployment/hosting-on-gitlab.md6
-rw-r--r--content/en/hosting-and-deployment/hosting-on-netlify.md145
-rw-r--r--content/en/hosting-and-deployment/hosting-on-netlify/index.md129
-rw-r--r--content/en/hosting-and-deployment/hosting-on-netlify/netlify-step-02.pngbin0 -> 8618 bytes
-rw-r--r--content/en/hosting-and-deployment/hosting-on-netlify/netlify-step-03.pngbin0 -> 15960 bytes
-rw-r--r--content/en/hosting-and-deployment/hosting-on-netlify/netlify-step-04.pngbin0 -> 10563 bytes
-rw-r--r--content/en/hosting-and-deployment/hosting-on-netlify/netlify-step-05.pngbin0 -> 5097 bytes
-rw-r--r--content/en/hosting-and-deployment/hosting-on-netlify/netlify-step-06.pngbin0 -> 24253 bytes
-rw-r--r--content/en/hosting-and-deployment/hosting-on-netlify/netlify-step-07.pngbin0 -> 2952 bytes
-rw-r--r--content/en/hosting-and-deployment/hosting-on-netlify/netlify-step-08.pngbin0 -> 8539 bytes
-rw-r--r--content/en/hosting-and-deployment/hosting-on-netlify/netlify-step-09.pngbin0 -> 11745 bytes
-rw-r--r--content/en/hosting-and-deployment/hosting-on-netlify/netlify-step-10.pngbin0 -> 7194 bytes
-rw-r--r--content/en/hosting-and-deployment/hosting-on-netlify/netlify-step-11.pngbin0 -> 2330 bytes
-rw-r--r--content/en/hosting-and-deployment/hosting-on-netlify/netlify-step-12.pngbin0 -> 5795 bytes
-rw-r--r--content/en/hosting-and-deployment/hosting-on-netlify/netlify-step-13.pngbin0 -> 10431 bytes
-rw-r--r--content/en/hugo-modules/_index.md6
-rw-r--r--content/en/hugo-modules/configuration.md2
-rw-r--r--content/en/hugo-modules/use-modules.md2
-rwxr-xr-xcontent/en/hugo-pipes/_index.md4
-rw-r--r--content/en/hugo-pipes/js.md27
-rw-r--r--content/en/hugo-pipes/transpile-sass-to-css.md8
-rw-r--r--content/en/installation/_common/03-prebuilt-binaries.md2
-rw-r--r--content/en/installation/_common/_index.md2
-rw-r--r--content/en/installation/_index.md4
-rw-r--r--content/en/installation/linux.md21
-rw-r--r--content/en/methods/_common/_index.md2
-rw-r--r--content/en/methods/_common/next-prev-on-page-vs-next-prev-on-pages.md16
-rw-r--r--content/en/methods/_index.md5
-rw-r--r--content/en/methods/menu-entry/KeyName.md2
-rw-r--r--content/en/methods/menu-entry/Menu.md4
-rw-r--r--content/en/methods/menu-entry/Name.md4
-rw-r--r--content/en/methods/menu-entry/Page.md6
-rw-r--r--content/en/methods/menu-entry/Title.md6
-rw-r--r--content/en/methods/menu-entry/URL.md2
-rw-r--r--content/en/methods/menu-entry/Weight.md2
-rw-r--r--content/en/methods/menu-entry/_common/_index.md2
-rw-r--r--content/en/methods/menu/ByName.md2
-rw-r--r--content/en/methods/menu/ByWeight.md2
-rw-r--r--content/en/methods/page/AllTranslations.md8
-rw-r--r--content/en/methods/page/BundleType.md2
-rw-r--r--content/en/methods/page/CodeOwners.md2
-rw-r--r--content/en/methods/page/Content.md2
-rw-r--r--content/en/methods/page/Data.md2
-rw-r--r--content/en/methods/page/Date.md4
-rw-r--r--content/en/methods/page/Description.md4
-rw-r--r--content/en/methods/page/ExpiryDate.md4
-rw-r--r--content/en/methods/page/File.md35
-rw-r--r--content/en/methods/page/Fragments.md12
-rw-r--r--content/en/methods/page/FuzzyWordCount.md2
-rw-r--r--content/en/methods/page/GetPage.md4
-rw-r--r--content/en/methods/page/HeadingsFiltered.md2
-rw-r--r--content/en/methods/page/InSection.md4
-rw-r--r--content/en/methods/page/IsAncestor.md6
-rw-r--r--content/en/methods/page/IsDescendant.md6
-rw-r--r--content/en/methods/page/Keywords.md6
-rw-r--r--content/en/methods/page/Language.md4
-rw-r--r--content/en/methods/page/Lastmod.md6
-rw-r--r--content/en/methods/page/LinkTitle.md2
-rw-r--r--content/en/methods/page/NextInSection.md8
-rw-r--r--content/en/methods/page/Pages.md2
-rw-r--r--content/en/methods/page/Paginator.md2
-rw-r--r--content/en/methods/page/Param.md1
-rw-r--r--content/en/methods/page/Params.md5
-rw-r--r--content/en/methods/page/Parent.md2
-rw-r--r--content/en/methods/page/Path.md157
-rw-r--r--content/en/methods/page/Plain.md4
-rw-r--r--content/en/methods/page/PlainWords.md4
-rw-r--r--content/en/methods/page/PrevInSection.md8
-rw-r--r--content/en/methods/page/PublishDate.md4
-rw-r--r--content/en/methods/page/RawContent.md4
-rw-r--r--content/en/methods/page/RegularPages.md2
-rw-r--r--content/en/methods/page/Render.md4
-rw-r--r--content/en/methods/page/RenderShortcodes.md13
-rw-r--r--content/en/methods/page/RenderString.md2
-rw-r--r--content/en/methods/page/Resources.md10
-rw-r--r--content/en/methods/page/Scratch.md27
-rw-r--r--content/en/methods/page/Section.md4
-rw-r--r--content/en/methods/page/Sections.md4
-rw-r--r--content/en/methods/page/Site.md2
-rw-r--r--content/en/methods/page/Sitemap.md15
-rw-r--r--content/en/methods/page/Sites.md4
-rw-r--r--content/en/methods/page/Store.md27
-rw-r--r--content/en/methods/page/Summary.md8
-rw-r--r--content/en/methods/page/TableOfContents.md3
-rw-r--r--content/en/methods/page/Title.md16
-rw-r--r--content/en/methods/page/Translations.md8
-rw-r--r--content/en/methods/page/Truncated.md4
-rw-r--r--content/en/methods/page/WordCount.md2
-rw-r--r--content/en/methods/page/_common/_index.md2
-rw-r--r--content/en/methods/page/_common/output-format-definition.md2
-rw-r--r--content/en/methods/pager/First.md44
-rw-r--r--content/en/methods/pager/HasNext.md72
-rw-r--r--content/en/methods/pager/HasPrev.md72
-rw-r--r--content/en/methods/pager/Last.md44
-rw-r--r--content/en/methods/pager/Next.md44
-rw-r--r--content/en/methods/pager/NumberOfElements.md25
-rw-r--r--content/en/methods/pager/PageGroups.md29
-rw-r--r--content/en/methods/pager/PageNumber.md31
-rw-r--r--content/en/methods/pager/PageSize.md24
-rw-r--r--content/en/methods/pager/Pagers.md30
-rw-r--r--content/en/methods/pager/Pages.md22
-rw-r--r--content/en/methods/pager/Prev.md44
-rw-r--r--content/en/methods/pager/TotalNumberOfElements.md25
-rw-r--r--content/en/methods/pager/TotalPages.md41
-rw-r--r--content/en/methods/pager/URL.md39
-rw-r--r--content/en/methods/pager/_index.md14
-rw-r--r--content/en/methods/pages/_common/_index.md2
-rw-r--r--content/en/methods/resource/Colors.md164
-rw-r--r--content/en/methods/resource/Content.md2
-rw-r--r--content/en/methods/resource/Data.md4
-rw-r--r--content/en/methods/resource/Err.md2
-rw-r--r--content/en/methods/resource/Exif.md4
-rw-r--r--content/en/methods/resource/Filter.md2
-rw-r--r--content/en/methods/resource/Key.md7
-rw-r--r--content/en/methods/resource/Name.md63
-rw-r--r--content/en/methods/resource/Params.md2
-rw-r--r--content/en/methods/resource/Permalink.md1
-rw-r--r--content/en/methods/resource/Process.md10
-rw-r--r--content/en/methods/resource/Publish.md1
-rw-r--r--content/en/methods/resource/RelPermalink.md1
-rw-r--r--content/en/methods/resource/Title.md58
-rw-r--r--content/en/methods/resource/_common/_index.md2
-rw-r--r--content/en/methods/shortcode/Get.md22
-rw-r--r--content/en/methods/shortcode/Inner.md20
-rw-r--r--content/en/methods/shortcode/InnerDeindent.md8
-rw-r--r--content/en/methods/shortcode/IsNamedParams.md4
-rw-r--r--content/en/methods/shortcode/Name.md8
-rw-r--r--content/en/methods/shortcode/Ordinal.md4
-rw-r--r--content/en/methods/shortcode/Params.md6
-rw-r--r--content/en/methods/shortcode/Parent.md6
-rw-r--r--content/en/methods/shortcode/Position.md8
-rw-r--r--content/en/methods/shortcode/Scratch.md4
-rw-r--r--content/en/methods/shortcode/Site.md2
-rw-r--r--content/en/methods/site/AllPages.md2
-rw-r--r--content/en/methods/site/BaseURL.md8
-rw-r--r--content/en/methods/site/Data.md12
-rw-r--r--content/en/methods/site/DisqusShortname.md2
-rw-r--r--content/en/methods/site/GetPage.md2
-rw-r--r--content/en/methods/site/GoogleAnalytics.md2
-rw-r--r--content/en/methods/site/IsDevelopment.md2
-rw-r--r--content/en/methods/site/IsMultiLingual.md8
-rw-r--r--content/en/methods/site/IsServer.md2
-rw-r--r--content/en/methods/site/Language.md14
-rw-r--r--content/en/methods/site/Languages.md4
-rw-r--r--content/en/methods/site/LastChange.md12
-rw-r--r--content/en/methods/site/Lastmod.md23
-rw-r--r--content/en/methods/site/Menus.md6
-rw-r--r--content/en/methods/site/Pages.md2
-rw-r--r--content/en/methods/site/Params.md4
-rw-r--r--content/en/methods/site/Sites.md6
-rw-r--r--content/en/methods/site/Taxonomies.md2
-rw-r--r--content/en/methods/taxonomy/Alphabetical.md2
-rw-r--r--content/en/methods/taxonomy/ByCount.md2
-rw-r--r--content/en/methods/taxonomy/Get.md4
-rw-r--r--content/en/methods/taxonomy/Page.md26
-rw-r--r--content/en/methods/taxonomy/_common/_index.md2
-rw-r--r--content/en/methods/taxonomy/_common/get-a-taxonomy-object.md10
-rw-r--r--content/en/methods/taxonomy/_common/ordered-taxonomy-element-methods.md2
-rw-r--r--content/en/methods/time/Format.md4
-rw-r--r--content/en/methods/time/Round.md26
-rw-r--r--content/en/methods/time/Truncate.md24
-rw-r--r--content/en/methods/time/YearDay.md2
-rw-r--r--content/en/news/_index.md5
-rw-r--r--content/en/quick-reference/_index.md4
-rw-r--r--content/en/quick-reference/emojis.md10
-rw-r--r--content/en/quick-reference/page-collections.md2
-rw-r--r--content/en/render-hooks/_common/_index.md (renamed from content/en/variables/_common/_index.md)2
-rw-r--r--content/en/render-hooks/_common/pageinner.md42
-rw-r--r--content/en/render-hooks/_index.md17
-rwxr-xr-xcontent/en/render-hooks/code-blocks.md152
-rwxr-xr-xcontent/en/render-hooks/headings.md79
-rwxr-xr-xcontent/en/render-hooks/images.md163
-rwxr-xr-xcontent/en/render-hooks/introduction.md85
-rwxr-xr-xcontent/en/render-hooks/links.md133
-rw-r--r--content/en/showcase/forestry/index.md2
-rw-r--r--content/en/showcase/keycdn/index.md2
-rw-r--r--content/en/showcase/quiply-employee-communications-app/index.md2
-rw-r--r--content/en/templates/404.md70
-rw-r--r--content/en/templates/_index.md4
-rw-r--r--content/en/templates/base.md2
-rw-r--r--content/en/templates/data-templates.md177
-rw-r--r--content/en/templates/embedded.md223
-rw-r--r--content/en/templates/homepage.md11
-rw-r--r--content/en/templates/internal.md221
-rw-r--r--content/en/templates/introduction.md821
-rw-r--r--content/en/templates/lists/index.md50
-rw-r--r--content/en/templates/menu-templates.md8
-rw-r--r--content/en/templates/output-formats.md74
-rw-r--r--content/en/templates/pagination.md13
-rw-r--r--content/en/templates/partials.md4
-rw-r--r--content/en/templates/render-hooks.md183
-rw-r--r--content/en/templates/robots.md5
-rw-r--r--content/en/templates/rss.md13
-rw-r--r--content/en/templates/section-templates.md34
-rw-r--r--content/en/templates/shortcode-templates.md108
-rw-r--r--content/en/templates/single-page-templates.md8
-rw-r--r--content/en/templates/sitemap-template.md27
-rw-r--r--content/en/templates/taxonomy-templates.md107
-rw-r--r--content/en/templates/views.md12
-rw-r--r--content/en/tools/_index.md4
-rw-r--r--content/en/tools/editors.md2
-rw-r--r--content/en/tools/front-ends.md8
-rw-r--r--content/en/tools/migrations.md5
-rw-r--r--content/en/tools/other.md19
-rw-r--r--content/en/tools/search.md4
-rw-r--r--content/en/troubleshooting/_index.md4
-rw-r--r--content/en/troubleshooting/audit/index.md2
-rw-r--r--content/en/troubleshooting/faq.md49
-rw-r--r--content/en/troubleshooting/inspection.md38
-rw-r--r--content/en/troubleshooting/logging.md16
-rw-r--r--content/en/troubleshooting/performance.md26
-rw-r--r--content/en/variables/_common/consistent-terminology.md20
-rw-r--r--content/en/variables/_index.md16
-rw-r--r--content/en/variables/file.md18
-rw-r--r--content/en/variables/git.md18
-rw-r--r--content/en/variables/menu-entry.md16
-rw-r--r--content/en/variables/page.md63
-rw-r--r--content/en/variables/pages.md39
-rw-r--r--content/en/variables/shortcode.md16
-rw-r--r--content/en/variables/site.md55
-rw-r--r--content/en/variables/taxonomy.md21
-rw-r--r--data/docs.yaml199
-rw-r--r--data/embedded_template_urls.toml36
-rw-r--r--data/homepagetweets.toml102
-rw-r--r--data/page_filters.yaml2
-rw-r--r--go.mod2
-rw-r--r--go.sum8
-rw-r--r--hugo.toml2
-rw-r--r--layouts/_default/baseof.html124
-rw-r--r--layouts/partials/math.html16
-rw-r--r--netlify.toml2
-rw-r--r--static/images/hosting-and-deployment/hosting-on-netlify/netlify-add-new-site.jpgbin25643 -> 0 bytes
-rw-r--r--static/images/hosting-and-deployment/hosting-on-netlify/netlify-authorize-added-permissions.jpgbin46713 -> 0 bytes
-rw-r--r--static/images/hosting-and-deployment/hosting-on-netlify/netlify-create-new-site-step-1.jpgbin37855 -> 0 bytes
-rw-r--r--static/images/hosting-and-deployment/hosting-on-netlify/netlify-create-new-site-step-2.jpgbin42233 -> 0 bytes
-rw-r--r--static/images/hosting-and-deployment/hosting-on-netlify/netlify-create-new-site-step-3.jpgbin36939 -> 0 bytes
-rw-r--r--static/images/hosting-and-deployment/hosting-on-netlify/netlify-deploy-published.jpgbin18930 -> 0 bytes
-rw-r--r--static/images/hosting-and-deployment/hosting-on-netlify/netlify-deploying-site.gifbin783315 -> 0 bytes
-rw-r--r--static/images/hosting-and-deployment/hosting-on-netlify/netlify-first-authorize.jpgbin44374 -> 0 bytes
-rw-r--r--static/images/hosting-and-deployment/hosting-on-netlify/netlify-live-site.jpgbin37306 -> 0 bytes
-rw-r--r--static/images/hosting-and-deployment/hosting-on-netlify/netlify-push-to-deploy.jpgbin21536 -> 0 bytes
-rw-r--r--static/images/hosting-and-deployment/hosting-on-netlify/netlify-signup.jpgbin37118 -> 0 bytes
-rw-r--r--static/shared/branding/hugo-tall.png (renamed from static/share/hugo-tall.png)bin9971 -> 9971 bytes
-rw-r--r--static/shared/branding/made-with-hugo-dark.png (renamed from static/share/made-with-hugo-dark.png)bin8764 -> 8764 bytes
-rw-r--r--static/shared/branding/made-with-hugo-long-dark.png (renamed from static/share/made-with-hugo-long-dark.png)bin9116 -> 9116 bytes
-rw-r--r--static/shared/branding/made-with-hugo-long.png (renamed from static/share/made-with-hugo-long.png)bin9318 -> 9318 bytes
-rw-r--r--static/shared/branding/made-with-hugo.png (renamed from static/share/made-with-hugo.png)bin8900 -> 8900 bytes
-rw-r--r--static/shared/branding/powered-by-hugo-dark.png (renamed from static/share/powered-by-hugo-dark.png)bin3545 -> 3545 bytes
-rw-r--r--static/shared/branding/powered-by-hugo-long-dark.png (renamed from static/share/powered-by-hugo-long-dark.png)bin3857 -> 3857 bytes
-rw-r--r--static/shared/branding/powered-by-hugo-long.png (renamed from static/share/powered-by-hugo-long.png)bin3773 -> 3773 bytes
-rw-r--r--static/shared/branding/powered-by-hugo.png (renamed from static/share/powered-by-hugo.png)bin3527 -> 3527 bytes
-rw-r--r--static/shared/examples/data/books.json55
-rw-r--r--static/shared/examples/images/interpreting-the-french-revolution.webpbin0 -> 12852 bytes
-rw-r--r--static/shared/examples/images/les-misérables.webpbin0 -> 13520 bytes
-rw-r--r--static/shared/examples/images/the-ancien-régime-and-the-revolution.webpbin0 -> 6946 bytes
-rw-r--r--static/shared/examples/images/the-hunchback-of-notre-dame.webpbin0 -> 23780 bytes
475 files changed, 7683 insertions, 4608 deletions
diff --git a/.cspell.json b/.cspell.json
index de66ff601..95e3ed5ce 100644
--- a/.cspell.json
+++ b/.cspell.json
@@ -20,13 +20,11 @@
],
"ignoreRegExpList": [
"# cspell: ignore fenced code blocks",
- "^(\\s*`{3,}).*[\\s\\S]*?^\\1",
+ "^(\\s*`{3,}).*[\\s\\S]*?^\\1$",
"# cspell: ignore words joined with dot",
"\\w+\\.\\w+",
"# cspell: ignore strings within backticks",
"`.+`",
- "# cspell: ignore strings within single quotes",
- "'.+'",
"# cspell: ignore strings within double quotes",
"\".+\"",
"# cspell: ignore strings within brackets",
@@ -42,14 +40,11 @@
],
"language": "en",
"words": [
- "antialiasing",
- "codeowners",
"composability",
"configurators",
"defang",
"deindent",
"downscale",
- "downscaled",
"downscaling",
"exif",
"geolocalized",
@@ -57,60 +52,99 @@
"marshal",
"marshaling",
"multihost",
+ "multiplatfom",
"performantly",
"preconfigured",
"prerendering",
"redirection",
"redirections",
- "shortcode",
- "shortcodes",
"subexpression",
- "subexpressions",
- "suppressable",
+ "suppressible",
"templating",
"transpile",
- "transpiles",
"unmarshal",
- "unmarshals",
"unmarshaling",
+ "unmarshals",
+ "# ----------------------------------------------------------------------",
+ "# cspell: ignore hugo terminology",
+ "# ----------------------------------------------------------------------",
+ "attrlink",
+ "canonify",
+ "codeowners",
+ "eturl",
+ "getenv",
+ "gohugo",
+ "gohugoio",
+ "keyvals",
+ "leftdelim",
+ "linkify",
+ "numworkermultiplier",
+ "rightdelim",
+ "shortcode",
+ "stringifier",
+ "struct",
+ "toclevels",
+ "zgotmplz",
"# ----------------------------------------------------------------------",
"# cspell: ignore foreign language words",
"# ----------------------------------------------------------------------",
"bezpieczeństwo",
+ "buch",
+ "descripción",
"dokumentation",
+ "erklärungen",
"libros",
+ "mercredi",
"miesiąc",
"miesiąc",
- "miesięcy",
+ "miesiąca",
+ "miesiące",
"miesięcy",
"misérables",
+ "mittwoch",
+ "muchos",
+ "novembre",
+ "otro",
+ "pocos",
+ "produkte",
"projekt",
+ "prywatność",
+ "referenz",
"régime",
"# ----------------------------------------------------------------------",
- "# cspell: ignore proper nouns",
+ "# cspell: ignore names",
"# ----------------------------------------------------------------------",
+ "Atishay",
+ "Cosette",
"Eliott",
+ "Furet",
"Gregor",
"Jaco",
+ "Lanczos",
+ "Ninke",
"Noll",
"Pastorius",
"Samsa",
+ "Stucki",
+ "Thénardier",
"# ----------------------------------------------------------------------",
"# cspell: ignore operating systems and software packages",
"# ----------------------------------------------------------------------",
"asciidoctor",
"brotli",
+ "cifs",
"corejs",
"disqus",
+ "docutils",
+ "dpkg",
"doas",
"eopkg",
"gitee",
- "gohugoio",
"goldmark",
- "KaTeX",
+ "katex",
"kubuntu",
"lubuntu",
- "MathJax",
+ "mathjax",
"nosql",
"pandoc",
"pkgin",
@@ -119,21 +153,19 @@
"# ----------------------------------------------------------------------",
"# cspell: ignore miscellaneous",
"# ----------------------------------------------------------------------",
+ "achristie",
+ "ddmaurier",
"dring",
- "getenv",
- "gohugo",
"inor",
+ "jausten",
"jdoe",
+ "jsmith",
"milli",
"rgba",
"rsmith",
- "stringifier",
- "struct",
"tdewolff",
"tjones",
- "toclevels",
- "vals",
- "xfeff",
- "zgotmplz"
+ "wcag",
+ "xfeff"
]
}
diff --git a/_vendor/github.com/gohugoio/gohugoioTheme/data/sponsors.toml b/_vendor/github.com/gohugoio/gohugoioTheme/data/sponsors.toml
index c8986a8c6..8e485b2a4 100644
--- a/_vendor/github.com/gohugoio/gohugoioTheme/data/sponsors.toml
+++ b/_vendor/github.com/gohugoio/gohugoioTheme/data/sponsors.toml
@@ -6,13 +6,12 @@
bgcolor = "#ffffff"
[[banners]]
- name = "CloudCannon"
- link = "https://cloudcannon.com/hugo-cms/"
- logo = "/images/sponsors/cloudcannon-white.svg"
- utm_campaign = "HugoSponsorship"
- utm_source = "sponsor"
- utm_content = "gohugo"
- bgcolor = "#034AD8"
+ name = "Route4Me"
+ link = "https://route4me.com"
+ title = "Route Planning & Route Optimization Software"
+ utm_campaign = "hugosponsor"
+ bgcolor = "#334799"
+ link_attr = "style='color: #ffffff; font-weight: bold; text-decoration: none; text-align: center'"
[[banners]]
name = "Your Company?"
@@ -20,3 +19,4 @@
utm_campaign = "hugosponsor"
show_on_hover = true
bgcolor = "#4e4f4f"
+ link_attr = "style='color: #ffffff; font-weight: bold; text-decoration: none; text-align: center'"
diff --git a/_vendor/github.com/gohugoio/gohugoioTheme/layouts/_default/_markup/render-link.html b/_vendor/github.com/gohugoio/gohugoioTheme/layouts/_default/_markup/render-link.html
index 5583d53d7..9b6cad114 100644
--- a/_vendor/github.com/gohugoio/gohugoioTheme/layouts/_default/_markup/render-link.html
+++ b/_vendor/github.com/gohugoio/gohugoioTheme/layouts/_default/_markup/render-link.html
@@ -1,4 +1,4 @@
-{{- /* Last modified: 2023-09-04T09:23:04-07:00 */}}
+{{- /* Last modified: 2024-04-26T13:54:00-07:00 */}}
{{- /*
Copyright 2023 Veriphor LLC
@@ -118,7 +118,7 @@ either of these shortcodes in conjunction with this render hook.
{{- $attrs = merge $attrs (dict "rel" "external") }}
{{- else }}
{{- with $u.Path }}
- {{- with $p := or ($.Page.GetPage .) ($.Page.GetPage (strings.TrimRight "/" .)) }}
+ {{- with $p := or ($.PageInner.GetPage .) ($.PageInner.GetPage (strings.TrimRight "/" .)) }}
{{- /* Destination is a page. */}}
{{- $href := .RelPermalink }}
{{- with $u.RawQuery }}
@@ -137,7 +137,7 @@ either of these shortcodes in conjunction with this render hook.
{{- end }}
{{- $attrs = dict "href" $href }}
{{- else }}
- {{- with $.Page.Resources.Get $u.Path }}
+ {{- with $.PageInner.Resources.Get $u.Path }}
{{- /* Destination is a page resource; drop query and fragment. */}}
{{- $attrs = dict "href" .RelPermalink }}
{{- else }}
@@ -185,14 +185,14 @@ either of these shortcodes in conjunction with this render hook.
{{- end }}
{{- end }}
{{- end }}
-{{- with .Title }}
- {{- $attrs = merge $attrs (dict "title" .) }}
-{{- end -}}
+{{- $attrs = merge $attrs (dict "title" (.Title | transform.HTMLEscape)) }}
{{- /* Render anchor element. */ -}}
<a
{{- range $k, $v := $attrs }}
- {{- printf " %s=%q" $k $v | safeHTMLAttr }}
+ {{- if $v }}
+ {{- printf " %s=%q" $k $v | safeHTMLAttr }}
+ {{- end }}
{{- end -}}
>{{ .Text | safeHTML }}</a>
diff --git a/_vendor/github.com/gohugoio/gohugoioTheme/layouts/index.rss.xml b/_vendor/github.com/gohugoio/gohugoioTheme/layouts/index.rss.xml
index 1d3498a1e..26afc1816 100644
--- a/_vendor/github.com/gohugoio/gohugoioTheme/layouts/index.rss.xml
+++ b/_vendor/github.com/gohugoio/gohugoioTheme/layouts/index.rss.xml
@@ -1,38 +1,68 @@
+{{- printf "<?xml version=\"1.0\" encoding=\"utf-8\" standalone=\"yes\"?>" | safeHTML }}
<rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom">
<channel>
- <title>{{ .Site.Title }} – {{ .Title }}</title>
+ <title>Hugo News</title>
+ <description>Recent news about Hugo, a static site generator written in Go, optimized for speed and designed for flexibility.</description>
<link>{{ .Permalink }}</link>
- <description>Recent Hugo news from gohugo.io</description>
- <generator>Hugo -- gohugo.io</generator>{{ with .Site.LanguageCode }}
- <language>{{.}}</language>{{end}}{{ with .Site.Author.email }}
- <managingEditor>{{.}}{{ with $.Site.Author.name }} ({{.}}){{end}}</managingEditor>{{end}}{{ with .Site.Author.email }}
- <webMaster>{{.}}{{ with $.Site.Author.name }} ({{.}}){{end}}</webMaster>{{end}}{{ with .Site.Copyright }}
- <copyright>{{.}}</copyright>{{end}}{{ if not .Date.IsZero }}
- <lastBuildDate>{{ .Date.Format "Mon, 02 Jan 2006 15:04:05 -0700" | safeHTML }}</lastBuildDate>{{ end }}
- <image>
- <url>{{ "img/hugo.png" | absURL }}</url>
- <title>GoHugo.io</title>
- <link>{{ .Permalink }}</link>
- </image>
- {{ with .OutputFormats.Get "RSS" }}
- {{ printf "<atom:link href=%q rel=\"self\" type=%q />" .Permalink .MediaType | safeHTML }}
- {{ end }}
- {{ range first 50 (where .Site.RegularPages "Type" "in" (slice "news" "showcase")) }}
- <item>
- <title>{{ .Section | title }}: {{ .Title }}</title>
- <link>{{ .Permalink }}</link>
- <pubDate>{{ .Date.Format "Mon, 02 Jan 2006 15:04:05 -0700" | safeHTML }}</pubDate>
- {{ with .Site.Author.email }}<author>{{.}}{{ with $.Site.Author.name }} ({{.}}){{end}}</author>{{end}}
- <guid>{{ .Permalink }}</guid>
- <description>
- {{ $img := (.Resources.ByType "image").GetMatch "*featured*" }}
- {{ with $img }}
- {{ $img := .Resize "640x" }}
- {{ printf "<![CDATA[<img src=\"%s\" width=\"%d\" height=\"%d\"/>]]>" $img.Permalink $img.Width $img.Height | safeHTML }}
- {{ end }}
- {{ .Content | html }}
- </description>
- </item>
- {{ end }}
+ <generator>Hugo {{ hugo.Version }}</generator>
+ <language>{{ or site.Language.LanguageCode site.Language.Lang }}</language>
+ {{- with site.Copyright }}
+ <copyright>{{ . }}</copyright>
+ {{- end }}
+ {{- with .OutputFormats.Get "RSS" }}
+ {{ printf "<atom:link href=%q rel=\"self\" type=%q />" .Permalink .MediaType | safeHTML }}
+ {{- end }}
+
+ {{- $news_items := slice }}
+
+ {{- /* Get releases from GitHub. */}}
+ {{- $u := "https://api.github.com/repos/gohugoio/hugo/releases" }}
+ {{- $releases := partial "utilities/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 }}
+ <lastBuildDate>{{ (index $news_items 0).PublishDate.Format "Mon, 02 Jan 2006 15:04:05 -0700" | safeHTML }}</lastBuildDate>
+
+ {{- /* Render items. */}}
+ {{- range $news_items }}
+ <item>
+ <title>{{ .Title }}</title>
+ <link>{{ .Permalink }}</link>
+ <pubDate>{{ .PublishDate.Format "Mon, 02 Jan 2006 15:04:05 -0700" | safeHTML }}</pubDate>
+ <guid>{{ .Permalink }}</guid>
+ <description>{{ .Summary | transform.XMLEscape | safeHTML }}</description>
+ </item>
+ {{- end }}
</channel>
-</rss> \ No newline at end of file
+</rss>
diff --git a/_vendor/github.com/gohugoio/gohugoioTheme/layouts/news/list.html b/_vendor/github.com/gohugoio/gohugoioTheme/layouts/news/list.html
index 5165c8a13..a41e45a2c 100644
--- a/_vendor/github.com/gohugoio/gohugoioTheme/layouts/news/list.html
+++ b/_vendor/github.com/gohugoio/gohugoioTheme/layouts/news/list.html
@@ -18,7 +18,7 @@
{{/* Get releases from GitHub. */}}
{{ $u := "https://api.github.com/repos/gohugoio/hugo/releases" }}
- {{ $releases := partial "inline/get-remote-data.html" $u }}
+ {{ $releases := partial "utilities/get-remote-data.html" $u }}
{{ $releases = where $releases "draft" false }}
{{ $releases = where $releases "prerelease" false }}
{{ range $releases | first 20 }}
@@ -55,16 +55,3 @@
</div>
{{ end }}
-
-{{ define "partials/inline/get-remote-data.html" }}
- {{ $u := . }}
- {{ $r := "" }}
- {{ with $r = resources.GetRemote $u }}
- {{ with .Err }}
- {{ errorf "%s" . }}
- {{ end }}
- {{ else }}
- {{ errorf "Unable to get remote resource %q" $u }}
- {{ end }}
- {{ return ($r | transform.Unmarshal) }}
-{{ end }}
diff --git a/_vendor/github.com/gohugoio/gohugoioTheme/layouts/news/list.xml b/_vendor/github.com/gohugoio/gohugoioTheme/layouts/news/list.xml
new file mode 100644
index 000000000..40bca59eb
--- /dev/null
+++ b/_vendor/github.com/gohugoio/gohugoioTheme/layouts/news/list.xml
@@ -0,0 +1,68 @@
+{{- printf "<?xml version=\"1.0\" encoding=\"utf-8\" standalone=\"yes\"?>" | safeHTML }}
+<rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom">
+ <channel>
+ <title>Hugo News</title>
+ <description>Recent news about Hugo, a static site generator written in Go, optimized for speed and designed for flexibility.</description>
+ <link>{{ .Permalink }}</link>
+ <generator>Hugo {{ hugo.Version }}</generator>
+ <language>{{ or site.Language.LanguageCode site.Language.Lang }}</language>
+ {{- with site.Copyright }}
+ <copyright>{{ . }}</copyright>
+ {{- end }}
+ {{- with .OutputFormats.Get "RSS" }}
+ {{ printf "<atom:link href=%q rel=\"self\" type=%q />" .Permalink .MediaType | safeHTML }}
+ {{- end }}
+
+ {{- $news_items := slice }}
+
+ {{- /* Get releases from GitHub. */}}
+ {{- $u := "https://api.github.com/repos/gohugoio/hugo/releases" }}
+ {{- $releases := partial "utilities/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 .Pages }}
+ {{- $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 }}
+ <lastBuildDate>{{ (index $news_items 0).PublishDate.Format "Mon, 02 Jan 2006 15:04:05 -0700" | safeHTML }}</lastBuildDate>
+
+ {{- /* Render items. */}}
+ {{- range $news_items }}
+ <item>
+ <title>{{ .Title }}</title>
+ <link>{{ .Permalink }}</link>
+ <pubDate>{{ .PublishDate.Format "Mon, 02 Jan 2006 15:04:05 -0700" | safeHTML }}</pubDate>
+ <guid>{{ .Permalink }}</guid>
+ <description>{{ .Summary | transform.XMLEscape | safeHTML }}</description>
+ </item>
+ {{- end }}
+ </channel>
+</rss>
diff --git a/_vendor/github.com/gohugoio/gohugoioTheme/layouts/partials/home-page-sections/open-source-involvement.html b/_vendor/github.com/gohugoio/gohugoioTheme/layouts/partials/home-page-sections/open-source-involvement.html
index 5300fb7a8..865a5161e 100644
--- a/_vendor/github.com/gohugoio/gohugoioTheme/layouts/partials/home-page-sections/open-source-involvement.html
+++ b/_vendor/github.com/gohugoio/gohugoioTheme/layouts/partials/home-page-sections/open-source-involvement.html
@@ -1,6 +1,6 @@
<div class="w-100 center pt5">
<div class="w-100 w-40-l tc center">
- <img src="/images/GitHub-Mark-64px.png" alt="Github Logo" class="tc center">
+ <img src="/images/Github.svg" alt="Github Logo" class="tc center">
</div>
</div>
diff --git a/_vendor/github.com/gohugoio/gohugoioTheme/layouts/partials/home-page-sections/sponsors.html b/_vendor/github.com/gohugoio/gohugoioTheme/layouts/partials/home-page-sections/sponsors.html
index 6838ce36a..3b7f6bfef 100644
--- a/_vendor/github.com/gohugoio/gohugoioTheme/layouts/partials/home-page-sections/sponsors.html
+++ b/_vendor/github.com/gohugoio/gohugoioTheme/layouts/partials/home-page-sections/sponsors.html
@@ -25,26 +25,30 @@
{{ $query_params := .query_params | default "" }}
{{ $url := printf "%s?%s%s" .link $query_params (querify "utm_source" (.utm_source | default $utmSource ) "utm_medium" "banner" "utm_campaign" (.utm_campaign | default "hugosponsor") "utm_content" (.utm_content | default "gohugoio")) | safeURL }}
{{ $logo := resources.Get .logo }}
- {{ if hugo.IsProduction }}
- {{ $gtagID := printf "Sponsor %s %s" .name $gtag | title }}
- <a
- href="{{ $url }}"
- onclick="trackOutboundLink({{ printf "'%s', '%s'" $gtagID $url | safeJS }});"
- class="w-100 grow pa3{{ if .show_on_hover }}
- show-on-hover
- {{ end }}"
- style="">
- {{ with $logo }}{{ .Content | safeHTML }}{{ end }}
- </a>
+ {{ $gtagID := printf "Sponsor %s %s" .name $gtag | title }}
+ {{ $classes := "" }}
+ {{ if .show_on_hover }}
+ {{ $classes = printf "%s show-on-hover" $classes }}
+ {{ end }}
+ {{ if $isFooter }}
+ {{ $classes = printf "%s f3" $classes }}
{{ else }}
- <a
- href="{{ $url }}"
- class="w-100 grow pa3{{ if .show_on_hover }}
- show-on-hover
- {{ end }}">
- {{ with $logo }}{{ .Content | safeHTML }}{{ end }}
- </a>
+ {{ $classes = printf "%s f1" $classes }}
{{ end }}
+ <a
+ href="{{ $url }}"
+ title="{{ .title | default .name }}"
+ {{ if hugo.IsProduction }}
+ onclick="trackOutboundLink({{ printf "'%s', '%s'" $gtagID $url | safeJS }});"
+ {{ end }}
+ class="w-100 grow pa3 {{ $classes }}"
+ {{ with .link_attr }}{{ . | safeHTMLAttr }}{{ end }}>
+ {{ with $logo }}
+ {{ .Content | safeHTML }}
+ {{ else }}
+ {{ .name }}
+ {{ end }}
+ </a>
</div>
{{ end }}
</div>
diff --git a/_vendor/github.com/gohugoio/gohugoioTheme/layouts/partials/utilities/get-remote-data.html b/_vendor/github.com/gohugoio/gohugoioTheme/layouts/partials/utilities/get-remote-data.html
new file mode 100644
index 000000000..69ac41da4
--- /dev/null
+++ b/_vendor/github.com/gohugoio/gohugoioTheme/layouts/partials/utilities/get-remote-data.html
@@ -0,0 +1,23 @@
+{{/*
+Parses the serialized data from the given URL and returns a map or an array.
+
+Supports CSV, JSON, TOML, YAML, and XML.
+
+@param {string} . The URL from which to retrieve the serialized data.
+@returns {any}
+
+@example {{ partial "get-remote-data.html" "https://example.org/foo.json" }}
+*/}}
+
+{{ $url := . }}
+{{ $data := dict }}
+{{ with resources.GetRemote $url }}
+ {{ with .Err }}
+ {{ errorf "%s" . }}
+ {{ else }}
+ {{ $data = .Content | transform.Unmarshal }}
+ {{ end }}
+{{ else }}
+ {{ errorf "Unable to get remote resource %q" $url }}
+{{ end }}
+{{ return $data }}
diff --git a/_vendor/github.com/gohugoio/gohugoioTheme/layouts/shortcodes/eturl.html b/_vendor/github.com/gohugoio/gohugoioTheme/layouts/shortcodes/eturl.html
new file mode 100644
index 000000000..c0cf30aec
--- /dev/null
+++ b/_vendor/github.com/gohugoio/gohugoioTheme/layouts/shortcodes/eturl.html
@@ -0,0 +1,36 @@
+{{- /*
+Renders an absolute URL to the source code for an embedded template.
+
+Accepts either positional or named parameters, and depends on the
+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 -}}
+{{- end -}}
diff --git a/_vendor/github.com/gohugoio/gohugoioTheme/layouts/shortcodes/img.html b/_vendor/github.com/gohugoio/gohugoioTheme/layouts/shortcodes/img.html
index 50d4da9ed..dd8c60e18 100644
--- a/_vendor/github.com/gohugoio/gohugoioTheme/layouts/shortcodes/img.html
+++ b/_vendor/github.com/gohugoio/gohugoioTheme/layouts/shortcodes/img.html
@@ -119,8 +119,8 @@ Renders the given image using the given filter, if any.
{{- end }}
{{- $validFilters := slice
- "autoorient" "brightness" "colorbalance" "colorize" "contrast" "gamma"
- "gaussianblur" "grayscale" "hue" "invert" "none" "opacity" "overlay"
+ "autoorient" "brightness" "colorbalance" "colorize" "contrast" "dither"
+ "gamma" "gaussianblur" "grayscale" "hue" "invert" "none" "opacity" "overlay"
"padding" "pixelate" "process" "saturation" "sepia" "sigmoid" "text"
"unsharpmask"
}}
@@ -198,6 +198,8 @@ Renders the given image using the given filter, if any.
{{- $ctx = merge $ctx (dict "argName" "percentage" "argValue" (index $filterArgs 0) "min" -100 "max" 100) }}
{{- template "validate-arg-value" $ctx }}
{{- $f = images.Contrast (index $filterArgs 0) }}
+{{- else if eq $filter "dither" }}
+ {{- $f = images.Dither }}
{{- else if eq $filter "gamma" }}
{{- $ctx = merge $ctx (dict "argsRequired" 1) }}
{{- template "validate-arg-count" $ctx }}
@@ -354,7 +356,7 @@ Renders the given image using the given filter, if any.
{{- if $u.IsAbs }}
{{- with resources.GetRemote $u.String }}
{{- with .Err }}
- {{- errorf "%s" }}
+ {{- errorf "%s" . }}
{{- else }}
{{- /* This is a remote resource. */}}
{{- $r = . }}
diff --git a/_vendor/github.com/gohugoio/gohugoioTheme/layouts/shortcodes/new-in.html b/_vendor/github.com/gohugoio/gohugoioTheme/layouts/shortcodes/new-in.html
index e22a91f3d..606d2219c 100644
--- a/_vendor/github.com/gohugoio/gohugoioTheme/layouts/shortcodes/new-in.html
+++ b/_vendor/github.com/gohugoio/gohugoioTheme/layouts/shortcodes/new-in.html
@@ -27,9 +27,7 @@ button will be hidden if any of the following conditions is true:
{{- warnf "This call to the %q shortcode should be removed: %s. The button is now hidden because the specified version (%s) is older than the display threshold." $.Name $.Position $version }}
{{- end }}
{{- else }}
- <button class="bg-white hover:bg-gray-100 text-gray-800 font-semibold py-2 mr2 px-4 border border-gray-400 rounded shadow">
- <a href="{{ printf "https://github.com/gohugoio/hugo/releases/tag/v%s" $version }}">New in v{{ $version }}</a>
- </button>
+ <a class="dib f5 fw6 ba bw1 b--gray ph2 mt1" href="{{ printf "https://github.com/gohugoio/hugo/releases/tag/v%s" $version }}">New in v{{ $version }}</a>
{{- end }}
{{- else }}
{{- errorf "The %q shortcode requires a positional parameter (version). See %s" .Name .Position }}
diff --git a/_vendor/github.com/gohugoio/gohugoioTheme/static/images/GitHub-Mark-64px.png b/_vendor/github.com/gohugoio/gohugoioTheme/static/images/GitHub-Mark-64px.png
deleted file mode 100644
index 9965f8d33..000000000
--- a/_vendor/github.com/gohugoio/gohugoioTheme/static/images/GitHub-Mark-64px.png
+++ /dev/null
Binary files differ
diff --git a/_vendor/github.com/gohugoio/gohugoioTheme/static/images/Github.svg b/_vendor/github.com/gohugoio/gohugoioTheme/static/images/Github.svg
new file mode 100644
index 000000000..f202ff878
--- /dev/null
+++ b/_vendor/github.com/gohugoio/gohugoioTheme/static/images/Github.svg
@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="64" height="64" viewBox="0 0 24 24"><path d="M12 0C5.374 0 0 5.373 0 12c0 5.302 3.438 9.8 8.207 11.387.599.111.793-.261.793-.577v-2.234c-3.338.726-4.033-1.416-4.033-1.416-.546-1.387-1.333-1.756-1.333-1.756-1.089-.745.083-.729.083-.729 1.205.084 1.839 1.237 1.839 1.237 1.07 1.834 2.807 1.304 3.492.997.107-.775.418-1.305.762-1.604-2.665-.305-5.467-1.334-5.467-5.931 0-1.311.469-2.381 1.236-3.221-.124-.303-.535-1.524.117-3.176 0 0 1.008-.322 3.301 1.23A11.5 11.5 0 0 1 12 5.803c1.02.005 2.047.138 3.006.404 2.291-1.552 3.297-1.23 3.297-1.23.653 1.653.242 2.874.118 3.176.77.84 1.235 1.911 1.235 3.221 0 4.609-2.807 5.624-5.479 5.921.43.372.823 1.102.823 2.222v3.293c0 .319.192.694.801.576C20.566 21.797 24 17.3 24 12c0-6.627-5.373-12-12-12"/></svg> \ No newline at end of file
diff --git a/_vendor/modules.txt b/_vendor/modules.txt
index a63ac09b9..100c6fc6f 100644
--- a/_vendor/modules.txt
+++ b/_vendor/modules.txt
@@ -1 +1 @@
-# github.com/gohugoio/gohugoioTheme v0.0.0-20240201183016-8e648a3b5342
+# github.com/gohugoio/gohugoioTheme v0.0.0-20240619093131-b595d5fb8c52
diff --git a/assets/images/examples/zion-national-park-grayscale.jpg b/assets/images/examples/zion-national-park-grayscale.jpg
deleted file mode 100644
index 908bd88c6..000000000
--- a/assets/images/examples/zion-national-park-grayscale.jpg
+++ /dev/null
Binary files differ
diff --git a/config/_default/menus/menus.en.toml b/config/_default/menus/menus.en.toml
index cd337cbee..b0da48817 100644
--- a/config/_default/menus/menus.en.toml
+++ b/config/_default/menus/menus.en.toml
@@ -1,6 +1,6 @@
[[docs]]
identifier = 'about'
-name = 'About Hugo'
+name = 'About'
pageRef = '/about/'
weight = 10
@@ -15,60 +15,60 @@ name = 'Getting started'
weight = 30
identifier = 'getting-started'
pageRef = '/getting-started/'
+
+[[docs]]
+name = 'Quick reference'
+weight = 40
+identifier = 'quick-reference'
+pageRef = '/quick-reference/'
post = 'break'
[[docs]]
name = 'Content management'
-weight = 40
+weight = 50
identifier = 'content-management'
post = 'expanded'
pageRef = '/content-management/'
[[docs]]
name = 'Templates'
-weight = 50
+weight = 60
identifier = 'templates'
pageRef = '/templates/'
[[docs]]
name = 'Functions'
-weight = 60
+weight = 70
identifier = 'functions'
pageRef = '/functions/'
[[docs]]
name = 'Methods'
-weight = 70
+weight = 80
identifier = 'methods'
pageRef = '/methods/'
[[docs]]
-name = 'Quick reference'
-weight = 80
-identifier = 'quick-reference'
-pageRef = '/quick-reference/'
-
-[[docs]]
-name = 'Variables'
-weight = 85
-identifier = 'variables'
-pageRef = '/variables/'
+name = 'Render hooks'
+weight = 90
+identifier = 'render-hooks'
+pageRef = '/render-hooks/'
[[docs]]
name = 'Hugo Modules'
-weight = 90
+weight = 100
identifier = 'modules'
pageRef = '/hugo-modules/'
[[docs]]
name = 'Hugo Pipes'
-weight = 100
+weight = 110
identifier = 'hugo-pipes'
pageRef = '/hugo-pipes/'
[[docs]]
name = 'CLI'
-weight = 110
+weight = 120
post = 'break'
identifier = 'commands'
pageRef = '/commands/'
@@ -77,25 +77,25 @@ pageRef = '/commands/'
[[docs]]
name = 'Troubleshooting'
-weight = 120
+weight = 130
identifier = 'troubleshooting'
pageRef = '/troubleshooting/'
[[docs]]
name = 'Developer tools'
-weight = 130
+weight = 140
identifier = 'developer-tools'
pageRef = '/tools/'
[[docs]]
name = 'Hosting and deployment'
-weight = 140
+weight = 150
identifier = 'hosting-and-deployment'
pageRef = '/hosting-and-deployment/'
[[docs]]
name = 'Contribute'
-weight = 150
+weight = 160
post = 'break'
identifier = 'contribute'
pageRef = '/contribute/'
diff --git a/content/en/_index.md b/content/en/_index.md
index 69d40ebcf..96ba0c413 100644
--- a/content/en/_index.md
+++ b/content/en/_index.md
@@ -15,7 +15,7 @@ features:
- 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.
+ 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
diff --git a/content/en/about/_index.md b/content/en/about/_index.md
index 3a8319029..333a9ba36 100644
--- a/content/en/about/_index.md
+++ b/content/en/about/_index.md
@@ -1,16 +1,16 @@
---
title: About Hugo
-linkTitle: Overview
-description: Hugo's features, roadmap, license, and motivation.
+linkTitle: In this section
+description: Learn about Hugo and its features, security model, and privacy protections.
categories: []
keywords: []
menu:
docs:
- identifier: about-hugo-overview
+ identifier: about-hugo-in-this-section
parent: about
weight: 10
weight: 10
aliases: [/about-hugo/,/docs/]
---
-Hugo is not your average static site generator.
+Learn about Hugo and its features, privacy protections, and security model.
diff --git a/content/en/about/benefits.md b/content/en/about/benefits.md
deleted file mode 100644
index 82952c4e6..000000000
--- a/content/en/about/benefits.md
+++ /dev/null
@@ -1,36 +0,0 @@
----
-title: Benefits of static site generators
-linkTitle: Static site generators
-description: Improved performance, security and ease of use are just a few of the reasons static site generators are so appealing.
-categories: [about]
-keywords: [ssg,static,performance,security]
-menu:
- docs:
- parent: about
- weight: 40
-weight: 40
----
-
-The purpose of website generators is to render content into HTML files. Most are "dynamic site generators." That means the HTTP server---i.e., the program that sends files to the browser to be viewed---runs the generator to create a new HTML file every time an end user requests a page.
-
-Over time, dynamic site generators were programmed to cache their HTML files to prevent unnecessary delays in delivering pages to end users. A cached page is a static version of a web page.
-
-Hugo takes caching a step further and all HTML files are rendered on your computer. You can review the files locally before copying them to the computer hosting the HTTP server. Since the HTML files aren't generated dynamically, we say that Hugo is a *static site generator*.
-
-This has many benefits. The most noticeable is performance. HTTP servers are *very* good at sending files---so good, in fact, that you can effectively serve the same number of pages with a fraction of the memory and CPU needed for a dynamic site.
-
-## More on static site generators
-
-* ["An Introduction to Static Site Generators", David Walsh]
-* ["Hugo vs. WordPress page load speed comparison: Hugo leaves WordPress in its dust", GettingThingsTech][hugovwordpress]
-* ["Static Site Generators", O'Reilly]
-* [StaticGen: Top Open-Source Static Site Generators (GitHub Stars)]
-* ["Top 10 Static Website Generators", Netlify blog]
-* ["The Resurgence of Static", dotCMS][dotcms]
-
-["An Introduction to Static Site Generators", David Walsh]: https://davidwalsh.name/introduction-static-site-generators
-["Static Site Generators", O'Reilly]: https://github.com/gohugoio/hugoDocs/files/1242701/static-site-generators.pdf
-["Top 10 Static Website Generators", Netlify blog]: https://www.netlify.com/blog/2016/05/02/top-ten-static-website-generators/
-[hugovwordpress]: https://gettingthingstech.com/hugo-vs.-wordpress-page-load-speed-comparison-hugo-leaves-wordpress-in-its-dust/
-[StaticGen: Top Open-Source Static Site Generators (GitHub Stars)]: https://www.staticgen.com/
-[dotcms]: https://dotcms.com/blog/post/the-resurgence-of-static
diff --git a/content/en/about/features.md b/content/en/about/features.md
index a94ce5526..ff7e9ce13 100644
--- a/content/en/about/features.md
+++ b/content/en/about/features.md
@@ -1,6 +1,6 @@
---
-title: Hugo features
-description: Hugo boasts blistering speed, robust content management, and a powerful templating language making it a great fit for all kinds of static websites.
+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]
keywords: []
menu:
@@ -11,70 +11,126 @@ weight: 30
toc: true
---
-## General
-
-* [Extremely fast] build times (&lt; 1 ms per page)
-* Completely cross platform, with [easy installation][install] on macOS, Linux, Windows, and more
-* Renders changes on the fly with [LiveReload] as you develop
-* [Powerful theming]
-* [Host your site anywhere][hostanywhere]
-
-## Organization
-
-* Straightforward [organization for your projects], including website sections
-* Customizable [URLs]
-* Support for configurable [taxonomies], including categories and tags
-* [Sort content] as you desire through powerful template [functions]
-* Automatic [table of contents] generation
-* [Dynamic menu] creation
-* [Pretty URLs] support
-* [Permalink] pattern support
-* Redirects via [aliases]
-
-## Content
-
-* Native Markdown and Emacs Org-Mode support, as well as other languages via *external helpers* (see [supported formats])
-* TOML, YAML, and JSON metadata support in [front matter]
-* Customizable [homepage]
-* Multiple [content types]
-* Automatic and user defined [content summaries]
-* [Shortcodes] to enable rich content inside of Markdown
-* ["Minutes to Read"][pagevars] functionality
-* ["WordCount"][pagevars] functionality
-
-## Additional features
-
-* Integrated [Disqus] comment support
-* Integrated [Google Analytics] support
-* Automatic [RSS] creation
-* Support for [Go] HTML templates
-* [Syntax highlighting] powered by [Chroma]
-
-[aliases]: /content-management/urls/#aliases
-[Chroma]: https://github.com/alecthomas/chroma
-[content summaries]: /content-management/summaries/
-[content types]: /content-management/types/
-[Disqus]: https://disqus.com/
-[Dynamic menu]: /templates/menu-templates/
-[Extremely fast]: https://github.com/bep/hugo-benchmark
-[front matter]: /content-management/front-matter/
-[functions]: /functions/
-[Go]: https://pkg.go.dev/html/template
-[Google Analytics]: https://google-analytics.com/
-[homepage]: /templates/homepage/
-[hostanywhere]: /hosting-and-deployment/
-[install]: /installation/
-[LiveReload]: /getting-started/usage/
-[organization for your projects]: /getting-started/directory-structure/
-[pagevars]: /variables/page/
-[Permalink]: /content-management/urls/#permalinks
-[Powerful theming]: /hugo-modules/theme-components/
-[Pretty URLs]: /content-management/urls/
-[RSS]: /templates/rss/
+## Framework
+
+[Multiplatform]
+: Install Hugo's single executable on Linux, macOS, Windows, and more.
+
+[Multilingual]
+: 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.
+
+[Output formats]
+: Render each page of your site to one or more output formats, with granular control by page kind, section, and path. While HTML is the default output format, you can add JSON, RSS, CSV, and more. For example, create a REST API to access content.
+
+[Templates]
+: Create templates usings variables, functions, and methods to transform your content, resources, and data into a published page. While HTML templates are the most common, you can create templates for any output format.
+
+[Themes]
+: Reduce development time and cost by using one of the hundreds of themes contributed by the Hugo community. Themes are available for corporate sites, documentation projects, image portfolios, landing pages, personal and professional blogs, resumes, CVs, and more.
+
+[Modules]
+: Reduce development time and cost by creating or importing packaged combinations of archetypes, assets, content, data, templates, translation tables, static files, or configuration settings. A module may serve as the basis for a new site, or to augment an existing site.
+
+[Privacy]
+: Configure the behavior of Hugo's embedded templates and shortcodes to facilitate compliance with regional privacy regulations, including the [GDPR] and [CCPA].
+
+[Security]
+: 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. Other protections prevent "shelling out" to arbitrary applications, limit access to specific environment variables, prevent connections to arbitrary remote data sources, and more.
+
+## Content authoring
+
+[Content formats]
+: Create your content using Markdown, HTML, AsciiDoc, Emacs Org Mode, Pandoc, or reStructuredText. Markdown is the default content format, conforming to the [CommonMark] and [GitHub Flavored Markdown] specifications.
+
+[Markdown attributes]
+: Apply HTML attributes such as `class` and `id` to Markdown images and block elements including blockquotes, fenced code blocks, headings, horizontal rules, lists, paragraphs, and tables.
+
+[Markdown extensions]
+: Leverage the embedded Markdown extensions to create tables, definition lists, footnotes, task lists, inserted text, mark text, subscripts, superscripts, and more.
+
+[Markdown render hooks]
+: Override the conversion of Markdown to HTML when rendering fenced code blocks, headings, images, and links. For example, render every standalone image as an HTML `figure` element.
+
+[Diagrams]
+: Use fenced code blocks and Markdown render hooks to include diagrams in your content.
+
+[Mathematics]
+: Include mathematical equations and expressions in Markdown using LaTeX or TeX typesetting syntax.
+
+[Syntax highlighting]
+: Syntactically highlight code examples using Hugo's embedded syntax highlighter, enabled by default for fenced code blocks in Markdown. The syntax highlighter supports hundreds of code languages and dozens of styles.
+
+[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.
+
+## Content management
+
+[Content adapters]
+: Create content adapters to dynamically add content when building your site. For example, use a content adapter to create pages from a remote data source such as JSON, TOML, YAML, or XML.
+
+[Taxonomies]
+: Classify content to establish simple or complex logical relationships between pages. For example, create an authors taxonomy, and assign one or more authors to each page. Among other uses, the taxonomy system provides an inverted, weighted index to render a list of related pages, ordered by relevance.
+
+[Data]
+: Augment your content using local or remote data sources including CSV, JSON, TOML, YAML, and XML. For example, create a shortcode to render an HTML table from a remote CSV file.
+
+[Menus]
+: Provide rapid access to content via Hugo's menu system, configured automatically, globally, or on a page-by-page basis. The menu system is a key component of Hugo's multilingual architecture.
+
+[URL management]
+: Serve any page from any path via global configuration or on a page-by-page basis.
+
+
+## Asset pipelines
+
+[CSS bundling]
+: Transpile Sass to CSS, bundle, tree shake, minify, create source maps, perform SRI hashing, and integrate with PostCSS.
+
+[JavaScript bundling]
+: Transpile TypeScript and JSX to JavaScript, bundle, tree shake, minify, create source maps, and perform SRI hashing.
+
+[Image processing]
+: Convert, resize, crop, rotate, adjust colors, apply filters, overlay text and images, and extract EXIF data.
+
+## Performance
+
+[Caching]
+: Reduce build time and cost by rendering a partial template once then cache the result, either globally or within a given context. For example, cache the result of an asset pipeline to prevent reprocessing on every rendered page.
+
+[Segmentation]
+: Reduce build time and cost by partitioning your sites into segments. For example, render the home page and the "news section" every hour, and render the entire site once a week.
+
+[Minification]
+: Minify HTML, CSS, and JavaScript to reduce file size, bandwidth consumption, and loading times.
+
+[CCPA]: https://en.wikipedia.org/wiki/California_Consumer_Privacy_Act
+[CSS bundling]: /functions/resources/tocss/
+[Caching]: /functions/partials/includecached/
+[CommonMark]: https://spec.commonmark.org/current/
+[Content adapters]: /content-management/content-adapters/
+[Content formats]: /content-management/formats/
+[Data]: /content-management/data-sources/
+[Diagrams]: /content-management/diagrams/
+[GDPR]: https://en.wikipedia.org/wiki/General_Data_Protection_Regulation
+[GitHub Flavored Markdown]: https://github.github.com/gfm/
+[Image processing]: /content-management/image-processing/
+[JavaScript bundling]: /functions/js/build/
+[Markdown attributes]: /content-management/markdown-attributes/
+[Markdown extensions]: /getting-started/configuration-markup/#goldmark-extensions
+[Markdown render hooks]: /render-hooks/introduction/
+[Mathematics]: /content-management/mathematics/
+[Menus]: /content-management/menus/
+[Minification]: /getting-started/configuration/#configure-minify
+[Modules]: https://gohugo.io/hugo-modules/
+[Multilingual]: /content-management/multilingual/
+[Multiplatform]: /installation/
+[Output formats]: /templates/output-formats/
+[Privacy]: /about/privacy/
+[Security]: /about/security/
+[Segmentation]: /getting-started/configuration/#configure-segments
[Shortcodes]: /content-management/shortcodes/
-[sort content]: /templates/
-[supported formats]: /content-management/formats/
[Syntax highlighting]: /content-management/syntax-highlighting/
-[table of contents]: /content-management/toc/
-[taxonomies]: /content-management/taxonomies/
-[URLs]: /content-management/urls/
+[Taxonomies]: /content-management/taxonomies/
+[Templates]: templates/introduction/
+[Themes]: https://themes.gohugo.io/
+[URL management]: /content-management/urls/
diff --git a/content/en/about/introduction.md b/content/en/about/introduction.md
new file mode 100644
index 000000000..d89938eed
--- /dev/null
+++ b/content/en/about/introduction.md
@@ -0,0 +1,39 @@
+---
+title: Introduction
+description: Hugo is a static site generator written in Go, optimized for speed and designed for flexibility.
+categories: [about]
+keywords: []
+menu:
+ docs:
+ identifier: about-introduction
+ parent: about
+ weight: 20
+weight: 20
+aliases: [/about/what-is-hugo/,/about/benefits/]
+---
+
+Hugo is a [static site generator] written in [Go], optimized for speed and designed for flexibility. With its advanced templating system and fast asset pipelines, Hugo renders a complete site in seconds, often less.
+
+Due to its flexible framework, multilingual support, and powerful taxonomy system, Hugo is widely used to create:
+
+- Corporate, government, nonprofit, education, news, event, and project sites
+- Documentation sites
+- Image portfolios
+- Landing pages
+- Business, professional, and personal blogs
+- Resumes and CVs
+
+Use Hugo's embedded web server during development to instantly see changes to content, structure, behavior, and presentation. Then deploy the site to your host, or push changes to your Git provider for automated builds and deployment.
+
+And with [Hugo Modules], you can share content, assets, data, translations, themes, templates, and configuration with other projects via public or private Git repositories.
+
+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
+
+{{< youtube 0RKpf3rK57I >}}
diff --git a/content/en/about/license.md b/content/en/about/license.md
index e488bb87a..f434b233e 100644
--- a/content/en/about/license.md
+++ b/content/en/about/license.md
@@ -2,12 +2,12 @@
title: License
description: Hugo is released under the Apache 2.0 license.
categories: [about]
-keywords: [license,apache]
+keywords: [apache]
menu:
docs:
parent: about
- weight: 70
-weight: 70
+ weight: 60
+weight: 60
---
## Apache License
diff --git a/content/en/about/hugo-and-gdpr.md b/content/en/about/privacy.md
index daf4e80f0..dcc3b3439 100644
--- a/content/en/about/hugo-and-gdpr.md
+++ b/content/en/about/privacy.md
@@ -1,16 +1,16 @@
---
-title: Hugo and the General Data Protection Regulation
-linkTitle: Hugo and the GDPR
-description: About how to configure your Hugo site to meet the new regulations.
+title: Privacy
+linkTitle: Privacy
+description: Configure your site to facilitate compliance with regional privacy regulations.
categories: [about]
keywords: ["GDPR", "Privacy", "Data Protection"]
menu:
docs:
parent: about
- weight: 60
-weight: 60
+ weight: 40
+weight: 40
toc: true
-aliases: [/privacy/,/gdpr/]
+aliases: [/gdpr/,/about/hugo-and-gdpr/]
---
General Data Protection Regulation ([GDPR](https://en.wikipedia.org/wiki/General_Data_Protection_Regulation)) is a regulation in EU law on data protection and privacy for all individuals within the European Union and the European Economic Area. It became enforceable on 25 May 2018.
@@ -22,7 +22,7 @@ aliases: [/privacy/,/gdpr/]
Note that:
* These settings have their defaults setting set to _off_, i.e. how it worked before Hugo `0.41`. You must do your own evaluation of your site and apply the appropriate settings.
- * These settings work with the [internal templates](/templates/internal/). Some theme may contain custom templates for embedding services like Google Analytics. In that case these options have no effect.
+ * These settings work with the [embedded templates](/templates/embedded/). Some theme may contain custom templates for embedding services like Google Analytics. In that case these options have no effect.
* We will continue this work and improve this further in future Hugo versions.
## All privacy settings
@@ -36,8 +36,6 @@ disable = false
[privacy.googleAnalytics]
disable = false
respectDoNotTrack = false
-anonymizeIP = false
-useSessionStorage = false
[privacy.instagram]
disable = false
simple = false
@@ -78,19 +76,9 @@ disable = true
### GoogleAnalytics
-anonymizeIP
-: Enabling this will make it so the users' IP addresses are anonymized within Google Analytics.
-
respectDoNotTrack
: Enabling this will make the GA templates respect the "Do Not Track" HTTP header.
-useSessionStorage
-: Enabling this will disable the use of Cookies and use Session Storage to Store the GA Client ID.
-
-{{% note %}}
-`useSessionStorage` is not supported when using Google Analytics v4 (gtag.js).
-{{% /note %}}
-
### Instagram
simple
diff --git a/content/en/about/security-model.md b/content/en/about/security.md
index af1dd7d75..29f2c7ed1 100644
--- a/content/en/about/security-model.md
+++ b/content/en/about/security.md
@@ -1,5 +1,6 @@
---
-title: Hugo's security model
+title: Security model
+linkTitle: Security
description: A summary of Hugo's security model.
categories: [about]
keywords: [security,privacy]
@@ -9,7 +10,7 @@ menu:
weight: 50
weight: 50
toc: true
-aliases: [/security/]
+aliases: [/about/security-model/]
---
## Runtime security
@@ -21,9 +22,8 @@ But when developing and building your site, the runtime is the `hugo` executable
**Hugo's main approach is that of sandboxing and a security policy with strict defaults:**
* 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.
-* Only the main project can walk symbolic links.
* User-defined components have read-only access to the filesystem.
-* We shell out to some external binaries to support [Asciidoctor](/content-management/formats/#list-of-content-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.
+* 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.
## Security policy
@@ -33,7 +33,16 @@ The default configuration is listed below. Any build using features not in the a
{{< code-toggle config=security />}}
-Note that these and other configuration settings in Hugo can be overridden by the OS environment. If you want to block all remote HTTP fetching of data:
+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
diff --git a/content/en/about/what-is-hugo.md b/content/en/about/what-is-hugo.md
deleted file mode 100644
index e4326d173..000000000
--- a/content/en/about/what-is-hugo.md
+++ /dev/null
@@ -1,57 +0,0 @@
----
-title: What is Hugo
-description: Hugo is a fast and modern static site generator written in Go, and designed to make website creation fun again.
-categories: [about]
-keywords: []
-menu:
- docs:
- parent: about
- weight: 20
-weight: 20
-toc: true
-aliases: [/overview/introduction/,/about/why-i-built-hugo/]
----
-
-Hugo is a general-purpose website framework. Technically speaking, Hugo is a [static site generator]. Unlike systems that dynamically build a page with each visitor request, Hugo builds pages when you create or update your content. Since websites are viewed far more often than they are edited, Hugo is designed to provide an optimal viewing experience for your website's end users and an ideal writing experience for website authors.
-
-Websites built with Hugo are extremely fast and secure. Hugo sites can be hosted anywhere, including [Netlify], [Heroku], [GoDaddy], [DreamHost], [GitHub Pages], [GitLab Pages], [Surge], [Firebase], [Google Cloud Storage], [Amazon S3], [Rackspace], [Azure], and [CloudFront] and work well with CDNs. Hugo sites run without the need for a database or dependencies on expensive runtimes like Ruby, Python, or PHP.
-
-We think of Hugo as the ideal website creation tool with nearly instant build times, able to rebuild whenever a change is made.
-
-## How fast is Hugo?
-
-{{< youtube "CdiDYZ51a2o" >}}
-
-## What does Hugo do?
-
-In technical terms, Hugo takes a source directory of files and templates and uses these as input to create a complete website.
-
-## Who should use Hugo?
-
-Hugo is for people that prefer writing in a text editor over a browser.
-
-Hugo is for people who want to hand code their own website without worrying about setting up complicated runtimes, dependencies and databases.
-
-Hugo is for people building a blog, a company site, a portfolio site, documentation, a single landing page, or a website with thousands of pages.
-
-[@spf13]: https://twitter.com/spf13
-[Amazon S3]: https://aws.amazon.com/s3/
-[Azure]: https://docs.microsoft.com/en-us/azure/storage/blobs/storage-blob-static-website
-[CloudFront]: https://aws.amazon.com/cloudfront/
-[DreamHost]: https://www.dreamhost.com/
-[Firebase]: https://firebase.google.com/docs/hosting/
-[GitHub Pages]: https://pages.github.com/
-[GitLab Pages]: https://about.gitlab.com/features/pages/
-[Go language]: https://go.dev/
-[GoDaddy]: https://www.godaddy.com/
-[Google Cloud Storage]: https://cloud.google.com/storage/
-[Heroku]: https://www.heroku.com/
-[Jekyll]: https://jekyllrb.com/
-[Middleman]: https://middlemanapp.com/
-[Nanoc]: https://nanoc.ws/
-[Netlify]: https://netlify.com
-[Rackspace]: https://www.rackspace.com/cloud/files
-[Surge]: https://surge.sh
-[contributing to it]: https://github.com/gohugoio/hugo
-[rackspace]: https://www.rackspace.com/openstack/public/files
-[static site generator]: /about/benefits/
diff --git a/content/en/commands/hugo.md b/content/en/commands/hugo.md
index fa8f6d1ed..cfbe66053 100644
--- a/content/en/commands/hugo.md
+++ b/content/en/commands/hugo.md
@@ -56,7 +56,8 @@ hugo [flags]
--printPathWarnings print warnings on duplicate target paths etc.
--printUnusedTemplates print warnings on unused templates.
--quiet build in quiet mode
- --renderToMemory render to memory (only useful for benchmark testing)
+ --renderSegments strings named segments to render (configured in the segments config)
+ -M, --renderToMemory render to memory (mostly useful when running the server)
-s, --source string filesystem path to read files relative from
--templateMetrics display metrics about template executions
--templateMetricsHints calculate some improvement hints when combined with --templateMetrics
diff --git a/content/en/commands/hugo_completion.md b/content/en/commands/hugo_completion.md
index c9b370da6..21635e81e 100644
--- a/content/en/commands/hugo_completion.md
+++ b/content/en/commands/hugo_completion.md
@@ -31,6 +31,7 @@ See each sub-command's help for details on how to use the generated script.
--ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern
--logLevel string log level (debug|info|warn|error)
--quiet build in quiet mode
+ -M, --renderToMemory render to memory (mostly useful when running the server)
-s, --source string filesystem path to read files relative from
--themesDir string filesystem path to themes directory
-v, --verbose verbose output
diff --git a/content/en/commands/hugo_completion_bash.md b/content/en/commands/hugo_completion_bash.md
index 875ecfc19..bface97c6 100644
--- a/content/en/commands/hugo_completion_bash.md
+++ b/content/en/commands/hugo_completion_bash.md
@@ -54,6 +54,7 @@ hugo completion bash
--ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern
--logLevel string log level (debug|info|warn|error)
--quiet build in quiet mode
+ -M, --renderToMemory render to memory (mostly useful when running the server)
-s, --source string filesystem path to read files relative from
--themesDir string filesystem path to themes directory
-v, --verbose verbose output
diff --git a/content/en/commands/hugo_completion_fish.md b/content/en/commands/hugo_completion_fish.md
index 87b84a702..3a9cf0df2 100644
--- a/content/en/commands/hugo_completion_fish.md
+++ b/content/en/commands/hugo_completion_fish.md
@@ -45,6 +45,7 @@ hugo completion fish [flags]
--ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern
--logLevel string log level (debug|info|warn|error)
--quiet build in quiet mode
+ -M, --renderToMemory render to memory (mostly useful when running the server)
-s, --source string filesystem path to read files relative from
--themesDir string filesystem path to themes directory
-v, --verbose verbose output
diff --git a/content/en/commands/hugo_completion_powershell.md b/content/en/commands/hugo_completion_powershell.md
index 77cfeda5f..593573cee 100644
--- a/content/en/commands/hugo_completion_powershell.md
+++ b/content/en/commands/hugo_completion_powershell.md
@@ -42,6 +42,7 @@ hugo completion powershell [flags]
--ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern
--logLevel string log level (debug|info|warn|error)
--quiet build in quiet mode
+ -M, --renderToMemory render to memory (mostly useful when running the server)
-s, --source string filesystem path to read files relative from
--themesDir string filesystem path to themes directory
-v, --verbose verbose output
diff --git a/content/en/commands/hugo_completion_zsh.md b/content/en/commands/hugo_completion_zsh.md
index 84856b6b3..c227c6125 100644
--- a/content/en/commands/hugo_completion_zsh.md
+++ b/content/en/commands/hugo_completion_zsh.md
@@ -56,6 +56,7 @@ hugo completion zsh [flags]
--ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern
--logLevel string log level (debug|info|warn|error)
--quiet build in quiet mode
+ -M, --renderToMemory render to memory (mostly useful when running the server)
-s, --source string filesystem path to read files relative from
--themesDir string filesystem path to themes directory
-v, --verbose verbose output
diff --git a/content/en/commands/hugo_config.md b/content/en/commands/hugo_config.md
index 3ec3748a3..fac513dce 100644
--- a/content/en/commands/hugo_config.md
+++ b/content/en/commands/hugo_config.md
@@ -18,13 +18,14 @@ hugo config [command] [flags]
### Options
```
- -b, --baseURL string hostname (and path) to the root, e.g. https://spf13.com/
- --cacheDir string filesystem path to cache directory
- -c, --contentDir string filesystem path to content directory
- --format string preferred file format (toml, yaml or json) (default "toml")
- -h, --help help for config
- --lang string the language to display config for. Defaults to the first language defined.
- -t, --theme strings themes to use (located in /themes/THEMENAME/)
+ -b, --baseURL string hostname (and path) to the root, e.g. https://spf13.com/
+ --cacheDir string filesystem path to cache directory
+ -c, --contentDir string filesystem path to content directory
+ --format string preferred file format (toml, yaml or json) (default "toml")
+ -h, --help help for config
+ --lang string the language to display config for. Defaults to the first language defined.
+ --renderSegments strings named segments to render (configured in the segments config)
+ -t, --theme strings themes to use (located in /themes/THEMENAME/)
```
### Options inherited from parent commands
@@ -39,6 +40,7 @@ hugo config [command] [flags]
--ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern
--logLevel string log level (debug|info|warn|error)
--quiet build in quiet mode
+ -M, --renderToMemory render to memory (mostly useful when running the server)
-s, --source string filesystem path to read files relative from
--themesDir string filesystem path to themes directory
-v, --verbose verbose output
diff --git a/content/en/commands/hugo_config_mounts.md b/content/en/commands/hugo_config_mounts.md
index 90b171912..42c8b29aa 100644
--- a/content/en/commands/hugo_config_mounts.md
+++ b/content/en/commands/hugo_config_mounts.md
@@ -14,11 +14,12 @@ hugo config mounts [flags] [args]
### Options
```
- -b, --baseURL string hostname (and path) to the root, e.g. https://spf13.com/
- --cacheDir string filesystem path to cache directory
- -c, --contentDir string filesystem path to content directory
- -h, --help help for mounts
- -t, --theme strings themes to use (located in /themes/THEMENAME/)
+ -b, --baseURL string hostname (and path) to the root, e.g. https://spf13.com/
+ --cacheDir string filesystem path to cache directory
+ -c, --contentDir string filesystem path to content directory
+ -h, --help help for mounts
+ --renderSegments strings named segments to render (configured in the segments config)
+ -t, --theme strings themes to use (located in /themes/THEMENAME/)
```
### Options inherited from parent commands
@@ -33,6 +34,7 @@ hugo config mounts [flags] [args]
--ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern
--logLevel string log level (debug|info|warn|error)
--quiet build in quiet mode
+ -M, --renderToMemory render to memory (mostly useful when running the server)
-s, --source string filesystem path to read files relative from
--themesDir string filesystem path to themes directory
-v, --verbose verbose output
diff --git a/content/en/commands/hugo_convert.md b/content/en/commands/hugo_convert.md
index 07f7f9c13..7b18ee6f8 100644
--- a/content/en/commands/hugo_convert.md
+++ b/content/en/commands/hugo_convert.md
@@ -33,6 +33,7 @@ See convert's subcommands toJSON, toTOML and toYAML for more information.
--ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern
--logLevel string log level (debug|info|warn|error)
--quiet build in quiet mode
+ -M, --renderToMemory render to memory (mostly useful when running the server)
-s, --source string filesystem path to read files relative from
--themesDir string filesystem path to themes directory
-v, --verbose verbose output
diff --git a/content/en/commands/hugo_convert_toJSON.md b/content/en/commands/hugo_convert_toJSON.md
index 23d6a1032..1dfb33aa0 100644
--- a/content/en/commands/hugo_convert_toJSON.md
+++ b/content/en/commands/hugo_convert_toJSON.md
@@ -35,6 +35,7 @@ hugo convert toJSON [flags] [args]
--logLevel string log level (debug|info|warn|error)
-o, --output string filesystem path to write files to
--quiet build in quiet mode
+ -M, --renderToMemory render to memory (mostly useful when running the server)
-s, --source string filesystem path to read files relative from
--themesDir string filesystem path to themes directory
--unsafe enable less safe operations, please backup first
diff --git a/content/en/commands/hugo_convert_toTOML.md b/content/en/commands/hugo_convert_toTOML.md
index 431547a79..ddd6b8270 100644
--- a/content/en/commands/hugo_convert_toTOML.md
+++ b/content/en/commands/hugo_convert_toTOML.md
@@ -35,6 +35,7 @@ hugo convert toTOML [flags] [args]
--logLevel string log level (debug|info|warn|error)
-o, --output string filesystem path to write files to
--quiet build in quiet mode
+ -M, --renderToMemory render to memory (mostly useful when running the server)
-s, --source string filesystem path to read files relative from
--themesDir string filesystem path to themes directory
--unsafe enable less safe operations, please backup first
diff --git a/content/en/commands/hugo_convert_toYAML.md b/content/en/commands/hugo_convert_toYAML.md
index 03f7fbb25..bddbb88a5 100644
--- a/content/en/commands/hugo_convert_toYAML.md
+++ b/content/en/commands/hugo_convert_toYAML.md
@@ -35,6 +35,7 @@ hugo convert toYAML [flags] [args]
--logLevel string log level (debug|info|warn|error)
-o, --output string filesystem path to write files to
--quiet build in quiet mode
+ -M, --renderToMemory render to memory (mostly useful when running the server)
-s, --source string filesystem path to read files relative from
--themesDir string filesystem path to themes directory
--unsafe enable less safe operations, please backup first
diff --git a/content/en/commands/hugo_deploy.md b/content/en/commands/hugo_deploy.md
index b4ab3e618..a606083fc 100644
--- a/content/en/commands/hugo_deploy.md
+++ b/content/en/commands/hugo_deploy.md
@@ -44,6 +44,7 @@ hugo deploy [flags] [args]
--ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern
--logLevel string log level (debug|info|warn|error)
--quiet build in quiet mode
+ -M, --renderToMemory render to memory (mostly useful when running the server)
-s, --source string filesystem path to read files relative from
--themesDir string filesystem path to themes directory
-v, --verbose verbose output
diff --git a/content/en/commands/hugo_env.md b/content/en/commands/hugo_env.md
index 076ddef26..9b73cea5f 100644
--- a/content/en/commands/hugo_env.md
+++ b/content/en/commands/hugo_env.md
@@ -33,6 +33,7 @@ hugo env [flags] [args]
--ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern
--logLevel string log level (debug|info|warn|error)
--quiet build in quiet mode
+ -M, --renderToMemory render to memory (mostly useful when running the server)
-s, --source string filesystem path to read files relative from
--themesDir string filesystem path to themes directory
-v, --verbose verbose output
diff --git a/content/en/commands/hugo_gen.md b/content/en/commands/hugo_gen.md
index 5c8bd6f2c..ea1696db9 100644
--- a/content/en/commands/hugo_gen.md
+++ b/content/en/commands/hugo_gen.md
@@ -25,6 +25,7 @@ A collection of several useful generators.
--ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern
--logLevel string log level (debug|info|warn|error)
--quiet build in quiet mode
+ -M, --renderToMemory render to memory (mostly useful when running the server)
-s, --source string filesystem path to read files relative from
--themesDir string filesystem path to themes directory
-v, --verbose verbose output
diff --git a/content/en/commands/hugo_gen_chromastyles.md b/content/en/commands/hugo_gen_chromastyles.md
index 3ec890412..cc244878c 100644
--- a/content/en/commands/hugo_gen_chromastyles.md
+++ b/content/en/commands/hugo_gen_chromastyles.md
@@ -20,10 +20,11 @@ hugo gen chromastyles [flags] [args]
### Options
```
- -h, --help help for chromastyles
- --highlightStyle string style used for highlighting lines (see https://github.com/alecthomas/chroma)
- --linesStyle string style used for line numbers (see https://github.com/alecthomas/chroma)
- --style string highlighter style (see https://xyproto.github.io/splash/docs/) (default "friendly")
+ -h, --help help for chromastyles
+ --highlightStyle string foreground and background colors for highlighted lines, e.g. --highlightStyle "#fff000 bg:#000fff"
+ --lineNumbersInlineStyle string foreground and background colors for inline line numbers, e.g. --lineNumbersInlineStyle "#fff000 bg:#000fff"
+ --lineNumbersTableStyle string foreground and background colors for table line numbers, e.g. --lineNumbersTableStyle "#fff000 bg:#000fff"
+ --style string highlighter style (see https://xyproto.github.io/splash/docs/) (default "friendly")
```
### Options inherited from parent commands
@@ -38,6 +39,7 @@ hugo gen chromastyles [flags] [args]
--ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern
--logLevel string log level (debug|info|warn|error)
--quiet build in quiet mode
+ -M, --renderToMemory render to memory (mostly useful when running the server)
-s, --source string filesystem path to read files relative from
--themesDir string filesystem path to themes directory
-v, --verbose verbose output
diff --git a/content/en/commands/hugo_gen_doc.md b/content/en/commands/hugo_gen_doc.md
index 13fb23106..84493ab98 100644
--- a/content/en/commands/hugo_gen_doc.md
+++ b/content/en/commands/hugo_gen_doc.md
@@ -39,6 +39,7 @@ hugo gen doc [flags] [args]
--ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern
--logLevel string log level (debug|info|warn|error)
--quiet build in quiet mode
+ -M, --renderToMemory render to memory (mostly useful when running the server)
-s, --source string filesystem path to read files relative from
--themesDir string filesystem path to themes directory
-v, --verbose verbose output
diff --git a/content/en/commands/hugo_gen_man.md b/content/en/commands/hugo_gen_man.md
index 6a63a583e..40267def2 100644
--- a/content/en/commands/hugo_gen_man.md
+++ b/content/en/commands/hugo_gen_man.md
@@ -36,6 +36,7 @@ hugo gen man [flags] [args]
--ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern
--logLevel string log level (debug|info|warn|error)
--quiet build in quiet mode
+ -M, --renderToMemory render to memory (mostly useful when running the server)
-s, --source string filesystem path to read files relative from
--themesDir string filesystem path to themes directory
-v, --verbose verbose output
diff --git a/content/en/commands/hugo_import.md b/content/en/commands/hugo_import.md
index a6bd40f34..71af58f8b 100644
--- a/content/en/commands/hugo_import.md
+++ b/content/en/commands/hugo_import.md
@@ -31,6 +31,7 @@ Import requires a subcommand, e.g. `hugo import jekyll jekyll_root_path target_p
--ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern
--logLevel string log level (debug|info|warn|error)
--quiet build in quiet mode
+ -M, --renderToMemory render to memory (mostly useful when running the server)
-s, --source string filesystem path to read files relative from
--themesDir string filesystem path to themes directory
-v, --verbose verbose output
diff --git a/content/en/commands/hugo_import_jekyll.md b/content/en/commands/hugo_import_jekyll.md
index af751348c..729413671 100644
--- a/content/en/commands/hugo_import_jekyll.md
+++ b/content/en/commands/hugo_import_jekyll.md
@@ -36,6 +36,7 @@ hugo import jekyll [flags] [args]
--ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern
--logLevel string log level (debug|info|warn|error)
--quiet build in quiet mode
+ -M, --renderToMemory render to memory (mostly useful when running the server)
-s, --source string filesystem path to read files relative from
--themesDir string filesystem path to themes directory
-v, --verbose verbose output
diff --git a/content/en/commands/hugo_list.md b/content/en/commands/hugo_list.md
index 294a8eaa4..9fab42ca9 100644
--- a/content/en/commands/hugo_list.md
+++ b/content/en/commands/hugo_list.md
@@ -31,6 +31,7 @@ List requires a subcommand, e.g. hugo list drafts
--ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern
--logLevel string log level (debug|info|warn|error)
--quiet build in quiet mode
+ -M, --renderToMemory render to memory (mostly useful when running the server)
-s, --source string filesystem path to read files relative from
--themesDir string filesystem path to themes directory
-v, --verbose verbose output
@@ -39,8 +40,9 @@ List requires a subcommand, e.g. hugo list drafts
### SEE ALSO
* [hugo](/commands/hugo/) - hugo builds your site
-* [hugo list all](/commands/hugo_list_all/) - List all posts
-* [hugo list drafts](/commands/hugo_list_drafts/) - List all drafts
-* [hugo list expired](/commands/hugo_list_expired/) - List all posts already expired
-* [hugo list future](/commands/hugo_list_future/) - List all posts dated in the future
+* [hugo list all](/commands/hugo_list_all/) - List all content
+* [hugo list drafts](/commands/hugo_list_drafts/) - List draft content
+* [hugo list expired](/commands/hugo_list_expired/) - List expired content
+* [hugo list future](/commands/hugo_list_future/) - List future content
+* [hugo list published](/commands/hugo_list_published/) - List published content
diff --git a/content/en/commands/hugo_list_all.md b/content/en/commands/hugo_list_all.md
index 49f692de0..d8dc10c9e 100644
--- a/content/en/commands/hugo_list_all.md
+++ b/content/en/commands/hugo_list_all.md
@@ -5,11 +5,11 @@ url: /commands/hugo_list_all/
---
## hugo list all
-List all posts
+List all content
### Synopsis
-List all of the posts in your content directory, include drafts, future and expired pages.
+List all content including draft, future, and expired.
```
hugo list all [flags] [args]
@@ -33,6 +33,7 @@ hugo list all [flags] [args]
--ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern
--logLevel string log level (debug|info|warn|error)
--quiet build in quiet mode
+ -M, --renderToMemory render to memory (mostly useful when running the server)
-s, --source string filesystem path to read files relative from
--themesDir string filesystem path to themes directory
-v, --verbose verbose output
diff --git a/content/en/commands/hugo_list_drafts.md b/content/en/commands/hugo_list_drafts.md
index e84e582e6..f1015bbb5 100644
--- a/content/en/commands/hugo_list_drafts.md
+++ b/content/en/commands/hugo_list_drafts.md
@@ -5,11 +5,11 @@ url: /commands/hugo_list_drafts/
---
## hugo list drafts
-List all drafts
+List draft content
### Synopsis
-List all of the drafts in your content directory.
+List draft content.
```
hugo list drafts [flags] [args]
@@ -33,6 +33,7 @@ hugo list drafts [flags] [args]
--ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern
--logLevel string log level (debug|info|warn|error)
--quiet build in quiet mode
+ -M, --renderToMemory render to memory (mostly useful when running the server)
-s, --source string filesystem path to read files relative from
--themesDir string filesystem path to themes directory
-v, --verbose verbose output
diff --git a/content/en/commands/hugo_list_expired.md b/content/en/commands/hugo_list_expired.md
index 43feb5d8e..35f6636e1 100644
--- a/content/en/commands/hugo_list_expired.md
+++ b/content/en/commands/hugo_list_expired.md
@@ -5,11 +5,11 @@ url: /commands/hugo_list_expired/
---
## hugo list expired
-List all posts already expired
+List expired content
### Synopsis
-List all of the posts in your content directory which has already expired.
+List content with a past expiration date.
```
hugo list expired [flags] [args]
@@ -33,6 +33,7 @@ hugo list expired [flags] [args]
--ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern
--logLevel string log level (debug|info|warn|error)
--quiet build in quiet mode
+ -M, --renderToMemory render to memory (mostly useful when running the server)
-s, --source string filesystem path to read files relative from
--themesDir string filesystem path to themes directory
-v, --verbose verbose output
diff --git a/content/en/commands/hugo_list_future.md b/content/en/commands/hugo_list_future.md
index 419accd6c..bef162441 100644
--- a/content/en/commands/hugo_list_future.md
+++ b/content/en/commands/hugo_list_future.md
@@ -5,11 +5,11 @@ url: /commands/hugo_list_future/
---
## hugo list future
-List all posts dated in the future
+List future content
### Synopsis
-List all of the posts in your content directory which will be posted in the future.
+List content with a future publication date.
```
hugo list future [flags] [args]
@@ -33,6 +33,7 @@ hugo list future [flags] [args]
--ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern
--logLevel string log level (debug|info|warn|error)
--quiet build in quiet mode
+ -M, --renderToMemory render to memory (mostly useful when running the server)
-s, --source string filesystem path to read files relative from
--themesDir string filesystem path to themes directory
-v, --verbose verbose output
diff --git a/content/en/commands/hugo_list_published.md b/content/en/commands/hugo_list_published.md
new file mode 100644
index 000000000..d53f6d941
--- /dev/null
+++ b/content/en/commands/hugo_list_published.md
@@ -0,0 +1,45 @@
+---
+title: "hugo list published"
+slug: hugo_list_published
+url: /commands/hugo_list_published/
+---
+## hugo list published
+
+List published content
+
+### Synopsis
+
+List content that is not draft, future, or expired.
+
+```
+hugo list published [flags] [args]
+```
+
+### Options
+
+```
+ -h, --help help for published
+```
+
+### Options inherited from parent commands
+
+```
+ --clock string set the clock used by Hugo, e.g. --clock 2021-11-06T22:30:00.00+09:00
+ --config string config file (default is hugo.yaml|json|toml)
+ --configDir string config dir (default "config")
+ --debug debug output
+ -d, --destination string filesystem path to write files to
+ -e, --environment string build environment
+ --ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern
+ --logLevel string log level (debug|info|warn|error)
+ --quiet build in quiet mode
+ -M, --renderToMemory render to memory (mostly useful when running the server)
+ -s, --source string filesystem path to read files relative from
+ --themesDir string filesystem path to themes directory
+ -v, --verbose verbose output
+```
+
+### SEE ALSO
+
+* [hugo list](/commands/hugo_list/) - Listing out various types of content
+
diff --git a/content/en/commands/hugo_mod.md b/content/en/commands/hugo_mod.md
index dc712b1de..7fe9dc18d 100644
--- a/content/en/commands/hugo_mod.md
+++ b/content/en/commands/hugo_mod.md
@@ -40,6 +40,7 @@ See https://gohugo.io/hugo-modules/ for more information.
--ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern
--logLevel string log level (debug|info|warn|error)
--quiet build in quiet mode
+ -M, --renderToMemory render to memory (mostly useful when running the server)
-s, --source string filesystem path to read files relative from
--themesDir string filesystem path to themes directory
-v, --verbose verbose output
diff --git a/content/en/commands/hugo_mod_clean.md b/content/en/commands/hugo_mod_clean.md
index c1c2b0c0d..e7d933da7 100644
--- a/content/en/commands/hugo_mod_clean.md
+++ b/content/en/commands/hugo_mod_clean.md
@@ -18,13 +18,14 @@ hugo mod clean [flags] [args]
### Options
```
- --all clean entire module cache
- -b, --baseURL string hostname (and path) to the root, e.g. https://spf13.com/
- --cacheDir string filesystem path to cache directory
- -c, --contentDir string filesystem path to content directory
- -h, --help help for clean
- --pattern string pattern matching module paths to clean (all if not set), e.g. "**hugo*"
- -t, --theme strings themes to use (located in /themes/THEMENAME/)
+ --all clean entire module cache
+ -b, --baseURL string hostname (and path) to the root, e.g. https://spf13.com/
+ --cacheDir string filesystem path to cache directory
+ -c, --contentDir string filesystem path to content directory
+ -h, --help help for clean
+ --pattern string pattern matching module paths to clean (all if not set), e.g. "**hugo*"
+ --renderSegments strings named segments to render (configured in the segments config)
+ -t, --theme strings themes to use (located in /themes/THEMENAME/)
```
### Options inherited from parent commands
@@ -39,6 +40,7 @@ hugo mod clean [flags] [args]
--ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern
--logLevel string log level (debug|info|warn|error)
--quiet build in quiet mode
+ -M, --renderToMemory render to memory (mostly useful when running the server)
-s, --source string filesystem path to read files relative from
--themesDir string filesystem path to themes directory
-v, --verbose verbose output
diff --git a/content/en/commands/hugo_mod_get.md b/content/en/commands/hugo_mod_get.md
index f4803d723..0b8a622f6 100644
--- a/content/en/commands/hugo_mod_get.md
+++ b/content/en/commands/hugo_mod_get.md
@@ -64,6 +64,7 @@ hugo mod get [flags] [args]
--ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern
--logLevel string log level (debug|info|warn|error)
--quiet build in quiet mode
+ -M, --renderToMemory render to memory (mostly useful when running the server)
-s, --source string filesystem path to read files relative from
--themesDir string filesystem path to themes directory
-v, --verbose verbose output
diff --git a/content/en/commands/hugo_mod_graph.md b/content/en/commands/hugo_mod_graph.md
index a2e2b51a3..506bff278 100644
--- a/content/en/commands/hugo_mod_graph.md
+++ b/content/en/commands/hugo_mod_graph.md
@@ -20,12 +20,13 @@ hugo mod graph [flags] [args]
### Options
```
- -b, --baseURL string hostname (and path) to the root, e.g. https://spf13.com/
- --cacheDir string filesystem path to cache directory
- --clean delete module cache for dependencies that fail verification
- -c, --contentDir string filesystem path to content directory
- -h, --help help for graph
- -t, --theme strings themes to use (located in /themes/THEMENAME/)
+ -b, --baseURL string hostname (and path) to the root, e.g. https://spf13.com/
+ --cacheDir string filesystem path to cache directory
+ --clean delete module cache for dependencies that fail verification
+ -c, --contentDir string filesystem path to content directory
+ -h, --help help for graph
+ --renderSegments strings named segments to render (configured in the segments config)
+ -t, --theme strings themes to use (located in /themes/THEMENAME/)
```
### Options inherited from parent commands
@@ -40,6 +41,7 @@ hugo mod graph [flags] [args]
--ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern
--logLevel string log level (debug|info|warn|error)
--quiet build in quiet mode
+ -M, --renderToMemory render to memory (mostly useful when running the server)
-s, --source string filesystem path to read files relative from
--themesDir string filesystem path to themes directory
-v, --verbose verbose output
diff --git a/content/en/commands/hugo_mod_init.md b/content/en/commands/hugo_mod_init.md
index 49b2609e1..dcea44b4b 100644
--- a/content/en/commands/hugo_mod_init.md
+++ b/content/en/commands/hugo_mod_init.md
@@ -25,11 +25,12 @@ hugo mod init [flags] [args]
### Options
```
- -b, --baseURL string hostname (and path) to the root, e.g. https://spf13.com/
- --cacheDir string filesystem path to cache directory
- -c, --contentDir string filesystem path to content directory
- -h, --help help for init
- -t, --theme strings themes to use (located in /themes/THEMENAME/)
+ -b, --baseURL string hostname (and path) to the root, e.g. https://spf13.com/
+ --cacheDir string filesystem path to cache directory
+ -c, --contentDir string filesystem path to content directory
+ -h, --help help for init
+ --renderSegments strings named segments to render (configured in the segments config)
+ -t, --theme strings themes to use (located in /themes/THEMENAME/)
```
### Options inherited from parent commands
@@ -44,6 +45,7 @@ hugo mod init [flags] [args]
--ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern
--logLevel string log level (debug|info|warn|error)
--quiet build in quiet mode
+ -M, --renderToMemory render to memory (mostly useful when running the server)
-s, --source string filesystem path to read files relative from
--themesDir string filesystem path to themes directory
-v, --verbose verbose output
diff --git a/content/en/commands/hugo_mod_npm.md b/content/en/commands/hugo_mod_npm.md
index fcd834798..763b3c247 100644
--- a/content/en/commands/hugo_mod_npm.md
+++ b/content/en/commands/hugo_mod_npm.md
@@ -33,6 +33,7 @@ hugo mod npm [command] [flags]
--ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern
--logLevel string log level (debug|info|warn|error)
--quiet build in quiet mode
+ -M, --renderToMemory render to memory (mostly useful when running the server)
-s, --source string filesystem path to read files relative from
--themesDir string filesystem path to themes directory
-v, --verbose verbose output
diff --git a/content/en/commands/hugo_mod_npm_pack.md b/content/en/commands/hugo_mod_npm_pack.md
index 30214d556..47d3e28b9 100644
--- a/content/en/commands/hugo_mod_npm_pack.md
+++ b/content/en/commands/hugo_mod_npm_pack.md
@@ -28,11 +28,12 @@ hugo mod npm pack [flags] [args]
### Options
```
- -b, --baseURL string hostname (and path) to the root, e.g. https://spf13.com/
- --cacheDir string filesystem path to cache directory
- -c, --contentDir string filesystem path to content directory
- -h, --help help for pack
- -t, --theme strings themes to use (located in /themes/THEMENAME/)
+ -b, --baseURL string hostname (and path) to the root, e.g. https://spf13.com/
+ --cacheDir string filesystem path to cache directory
+ -c, --contentDir string filesystem path to content directory
+ -h, --help help for pack
+ --renderSegments strings named segments to render (configured in the segments config)
+ -t, --theme strings themes to use (located in /themes/THEMENAME/)
```
### Options inherited from parent commands
@@ -47,6 +48,7 @@ hugo mod npm pack [flags] [args]
--ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern
--logLevel string log level (debug|info|warn|error)
--quiet build in quiet mode
+ -M, --renderToMemory render to memory (mostly useful when running the server)
-s, --source string filesystem path to read files relative from
--themesDir string filesystem path to themes directory
-v, --verbose verbose output
diff --git a/content/en/commands/hugo_mod_tidy.md b/content/en/commands/hugo_mod_tidy.md
index 803ef1c5b..6d024564f 100644
--- a/content/en/commands/hugo_mod_tidy.md
+++ b/content/en/commands/hugo_mod_tidy.md
@@ -14,11 +14,12 @@ hugo mod tidy [flags] [args]
### Options
```
- -b, --baseURL string hostname (and path) to the root, e.g. https://spf13.com/
- --cacheDir string filesystem path to cache directory
- -c, --contentDir string filesystem path to content directory
- -h, --help help for tidy
- -t, --theme strings themes to use (located in /themes/THEMENAME/)
+ -b, --baseURL string hostname (and path) to the root, e.g. https://spf13.com/
+ --cacheDir string filesystem path to cache directory
+ -c, --contentDir string filesystem path to content directory
+ -h, --help help for tidy
+ --renderSegments strings named segments to render (configured in the segments config)
+ -t, --theme strings themes to use (located in /themes/THEMENAME/)
```
### Options inherited from parent commands
@@ -33,6 +34,7 @@ hugo mod tidy [flags] [args]
--ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern
--logLevel string log level (debug|info|warn|error)
--quiet build in quiet mode
+ -M, --renderToMemory render to memory (mostly useful when running the server)
-s, --source string filesystem path to read files relative from
--themesDir string filesystem path to themes directory
-v, --verbose verbose output
diff --git a/content/en/commands/hugo_mod_vendor.md b/content/en/commands/hugo_mod_vendor.md
index 3a829d5fd..6f96caec2 100644
--- a/content/en/commands/hugo_mod_vendor.md
+++ b/content/en/commands/hugo_mod_vendor.md
@@ -20,11 +20,12 @@ hugo mod vendor [flags] [args]
### Options
```
- -b, --baseURL string hostname (and path) to the root, e.g. https://spf13.com/
- --cacheDir string filesystem path to cache directory
- -c, --contentDir string filesystem path to content directory
- -h, --help help for vendor
- -t, --theme strings themes to use (located in /themes/THEMENAME/)
+ -b, --baseURL string hostname (and path) to the root, e.g. https://spf13.com/
+ --cacheDir string filesystem path to cache directory
+ -c, --contentDir string filesystem path to content directory
+ -h, --help help for vendor
+ --renderSegments strings named segments to render (configured in the segments config)
+ -t, --theme strings themes to use (located in /themes/THEMENAME/)
```
### Options inherited from parent commands
@@ -39,6 +40,7 @@ hugo mod vendor [flags] [args]
--ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern
--logLevel string log level (debug|info|warn|error)
--quiet build in quiet mode
+ -M, --renderToMemory render to memory (mostly useful when running the server)
-s, --source string filesystem path to read files relative from
--themesDir string filesystem path to themes directory
-v, --verbose verbose output
diff --git a/content/en/commands/hugo_mod_verify.md b/content/en/commands/hugo_mod_verify.md
index b647a2cbb..d3f639fea 100644
--- a/content/en/commands/hugo_mod_verify.md
+++ b/content/en/commands/hugo_mod_verify.md
@@ -18,12 +18,13 @@ hugo mod verify [flags] [args]
### Options
```
- -b, --baseURL string hostname (and path) to the root, e.g. https://spf13.com/
- --cacheDir string filesystem path to cache directory
- --clean delete module cache for dependencies that fail verification
- -c, --contentDir string filesystem path to content directory
- -h, --help help for verify
- -t, --theme strings themes to use (located in /themes/THEMENAME/)
+ -b, --baseURL string hostname (and path) to the root, e.g. https://spf13.com/
+ --cacheDir string filesystem path to cache directory
+ --clean delete module cache for dependencies that fail verification
+ -c, --contentDir string filesystem path to content directory
+ -h, --help help for verify
+ --renderSegments strings named segments to render (configured in the segments config)
+ -t, --theme strings themes to use (located in /themes/THEMENAME/)
```
### Options inherited from parent commands
@@ -38,6 +39,7 @@ hugo mod verify [flags] [args]
--ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern
--logLevel string log level (debug|info|warn|error)
--quiet build in quiet mode
+ -M, --renderToMemory render to memory (mostly useful when running the server)
-s, --source string filesystem path to read files relative from
--themesDir string filesystem path to themes directory
-v, --verbose verbose output
diff --git a/content/en/commands/hugo_new.md b/content/en/commands/hugo_new.md
index ef0ff4cd4..2146f85fc 100644
--- a/content/en/commands/hugo_new.md
+++ b/content/en/commands/hugo_new.md
@@ -36,6 +36,7 @@ Ensure you run this within the root directory of your site.
--ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern
--logLevel string log level (debug|info|warn|error)
--quiet build in quiet mode
+ -M, --renderToMemory render to memory (mostly useful when running the server)
-s, --source string filesystem path to read files relative from
--themesDir string filesystem path to themes directory
-v, --verbose verbose output
diff --git a/content/en/commands/hugo_new_content.md b/content/en/commands/hugo_new_content.md
index cc53346ad..f0ea64ab7 100644
--- a/content/en/commands/hugo_new_content.md
+++ b/content/en/commands/hugo_new_content.md
@@ -25,14 +25,15 @@ hugo new content [path] [flags]
### Options
```
- -b, --baseURL string hostname (and path) to the root, e.g. https://spf13.com/
- --cacheDir string filesystem path to cache directory
- -c, --contentDir string filesystem path to content directory
- --editor string edit new content with this editor, if provided
- -f, --force overwrite file if it already exists
- -h, --help help for content
- -k, --kind string content type to create
- -t, --theme strings themes to use (located in /themes/THEMENAME/)
+ -b, --baseURL string hostname (and path) to the root, e.g. https://spf13.com/
+ --cacheDir string filesystem path to cache directory
+ -c, --contentDir string filesystem path to content directory
+ --editor string edit new content with this editor, if provided
+ -f, --force overwrite file if it already exists
+ -h, --help help for content
+ -k, --kind string content type to create
+ --renderSegments strings named segments to render (configured in the segments config)
+ -t, --theme strings themes to use (located in /themes/THEMENAME/)
```
### Options inherited from parent commands
@@ -47,6 +48,7 @@ hugo new content [path] [flags]
--ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern
--logLevel string log level (debug|info|warn|error)
--quiet build in quiet mode
+ -M, --renderToMemory render to memory (mostly useful when running the server)
-s, --source string filesystem path to read files relative from
--themesDir string filesystem path to themes directory
-v, --verbose verbose output
diff --git a/content/en/commands/hugo_new_site.md b/content/en/commands/hugo_new_site.md
index f8a939df5..a79e6f85a 100644
--- a/content/en/commands/hugo_new_site.md
+++ b/content/en/commands/hugo_new_site.md
@@ -37,6 +37,7 @@ hugo new site [path] [flags]
--ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern
--logLevel string log level (debug|info|warn|error)
--quiet build in quiet mode
+ -M, --renderToMemory render to memory (mostly useful when running the server)
-s, --source string filesystem path to read files relative from
--themesDir string filesystem path to themes directory
-v, --verbose verbose output
diff --git a/content/en/commands/hugo_new_theme.md b/content/en/commands/hugo_new_theme.md
index 301c79e0c..c3003200d 100644
--- a/content/en/commands/hugo_new_theme.md
+++ b/content/en/commands/hugo_new_theme.md
@@ -36,6 +36,7 @@ hugo new theme [name] [flags]
--ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern
--logLevel string log level (debug|info|warn|error)
--quiet build in quiet mode
+ -M, --renderToMemory render to memory (mostly useful when running the server)
-s, --source string filesystem path to read files relative from
--themesDir string filesystem path to themes directory
-v, --verbose verbose output
diff --git a/content/en/commands/hugo_server.md b/content/en/commands/hugo_server.md
index 49cd1867b..dada8c43e 100644
--- a/content/en/commands/hugo_server.md
+++ b/content/en/commands/hugo_server.md
@@ -12,8 +12,9 @@ A high performance webserver
Hugo provides its own webserver which builds and serves the site.
While hugo server is high performance, it is a webserver with limited options.
-'hugo server' will avoid writing the rendered and served content to disk,
-preferring to store it in memory.
+The `hugo server` command will by default write and serve files from disk, but
+you can render to memory by using the `--renderToMemory` flag. This can be
+faster in some cases, but it will consume more memory.
By default hugo will also watch your files for any changes you make and
automatically rebuild the site. It will then live reload any open browser pages
@@ -27,51 +28,50 @@ hugo server [command] [flags]
### Options
```
- --appendPort append port to baseURL (default true)
- -b, --baseURL string hostname (and path) to the root, e.g. https://spf13.com/
- --bind string interface to which the server will bind (default "127.0.0.1")
- -D, --buildDrafts include content marked as draft
- -E, --buildExpired include expired content
- -F, --buildFuture include content with publishdate in the future
- --cacheDir string filesystem path to cache directory
- --cleanDestinationDir remove files from destination not found in static directories
- -c, --contentDir string filesystem path to content directory
- --disableBrowserError do not show build errors in the browser
- --disableFastRender enables full re-renders on changes
- --disableKinds strings disable different kind of pages (home, RSS etc.)
- --disableLiveReload watch without enabling live browser reload on rebuild
- --enableGitInfo add Git revision, date, author, and CODEOWNERS info to the pages
- --forceSyncStatic copy all files when static is changed.
- --gc enable to run some cleanup tasks (remove unused cache files) after the build
- -h, --help help for server
- --ignoreCache ignores the cache directory
- -l, --layoutDir string filesystem path to layout directory
- --liveReloadPort int port for live reloading (i.e. 443 in HTTPS proxy situations) (default -1)
- --meminterval string interval to poll memory usage (requires --memstats), valid time units are "ns", "us" (or "µs"), "ms", "s", "m", "h". (default "100ms")
- --memstats string log memory usage to this file
- --minify minify any supported output format (HTML, XML etc.)
- --navigateToChanged navigate to changed content file on live browser reload
- --noBuildLock don't create .hugo_build.lock file
- --noChmod don't sync permission mode of files
- --noHTTPCache prevent HTTP caching
- --noTimes don't sync modification time of files
- --panicOnWarning panic on first WARNING log
- --poll string set this to a poll interval, e.g --poll 700ms, to use a poll based approach to watch for file system changes
- -p, --port int port on which the server will listen (default 1313)
- --printI18nWarnings print missing translations
- --printMemoryUsage print memory usage to screen at intervals
- --printPathWarnings print warnings on duplicate target paths etc.
- --printUnusedTemplates print warnings on unused templates.
- --renderStaticToDisk serve static files from disk and dynamic files from memory
- --renderToDisk serve all files from disk (default is from memory)
- --templateMetrics display metrics about template executions
- --templateMetricsHints calculate some improvement hints when combined with --templateMetrics
- -t, --theme strings themes to use (located in /themes/THEMENAME/)
- --tlsAuto generate and use locally-trusted certificates.
- --tlsCertFile string path to TLS certificate file
- --tlsKeyFile string path to TLS key file
- --trace file write trace to file (not useful in general)
- -w, --watch watch filesystem for changes and recreate as needed (default true)
+ --appendPort append port to baseURL (default true)
+ -b, --baseURL string hostname (and path) to the root, e.g. https://spf13.com/
+ --bind string interface to which the server will bind (default "127.0.0.1")
+ -D, --buildDrafts include content marked as draft
+ -E, --buildExpired include expired content
+ -F, --buildFuture include content with publishdate in the future
+ --cacheDir string filesystem path to cache directory
+ --cleanDestinationDir remove files from destination not found in static directories
+ -c, --contentDir string filesystem path to content directory
+ --disableBrowserError do not show build errors in the browser
+ --disableFastRender enables full re-renders on changes
+ --disableKinds strings disable different kind of pages (home, RSS etc.)
+ --disableLiveReload watch without enabling live browser reload on rebuild
+ --enableGitInfo add Git revision, date, author, and CODEOWNERS info to the pages
+ --forceSyncStatic copy all files when static is changed.
+ --gc enable to run some cleanup tasks (remove unused cache files) after the build
+ -h, --help help for server
+ --ignoreCache ignores the cache directory
+ -l, --layoutDir string filesystem path to layout directory
+ --liveReloadPort int port for live reloading (i.e. 443 in HTTPS proxy situations) (default -1)
+ --minify minify any supported output format (HTML, XML etc.)
+ -N, --navigateToChanged navigate to changed content file on live browser reload
+ --noBuildLock don't create .hugo_build.lock file
+ --noChmod don't sync permission mode of files
+ --noHTTPCache prevent HTTP caching
+ --noTimes don't sync modification time of files
+ --panicOnWarning panic on first WARNING log
+ --poll string set this to a poll interval, e.g --poll 700ms, to use a poll based approach to watch for file system changes
+ -p, --port int port on which the server will listen (default 1313)
+ --pprof enable the pprof server (port 8080)
+ --printI18nWarnings print missing translations
+ --printMemoryUsage print memory usage to screen at intervals
+ --printPathWarnings print warnings on duplicate target paths etc.
+ --printUnusedTemplates print warnings on unused templates.
+ --renderSegments strings named segments to render (configured in the segments config)
+ --renderStaticToDisk serve static files from disk and dynamic files from memory
+ --templateMetrics display metrics about template executions
+ --templateMetricsHints calculate some improvement hints when combined with --templateMetrics
+ -t, --theme strings themes to use (located in /themes/THEMENAME/)
+ --tlsAuto generate and use locally-trusted certificates.
+ --tlsCertFile string path to TLS certificate file
+ --tlsKeyFile string path to TLS key file
+ --trace file write trace to file (not useful in general)
+ -w, --watch watch filesystem for changes and recreate as needed (default true)
```
### Options inherited from parent commands
@@ -86,6 +86,7 @@ hugo server [command] [flags]
--ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern
--logLevel string log level (debug|info|warn|error)
--quiet build in quiet mode
+ -M, --renderToMemory render to memory (mostly useful when running the server)
-s, --source string filesystem path to read files relative from
--themesDir string filesystem path to themes directory
-v, --verbose verbose output
diff --git a/content/en/commands/hugo_server_trust.md b/content/en/commands/hugo_server_trust.md
index b789eb69a..c4cf750fa 100644
--- a/content/en/commands/hugo_server_trust.md
+++ b/content/en/commands/hugo_server_trust.md
@@ -30,6 +30,7 @@ hugo server trust [flags] [args]
--ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern
--logLevel string log level (debug|info|warn|error)
--quiet build in quiet mode
+ -M, --renderToMemory render to memory (mostly useful when running the server)
-s, --source string filesystem path to read files relative from
--themesDir string filesystem path to themes directory
-v, --verbose verbose output
diff --git a/content/en/commands/hugo_version.md b/content/en/commands/hugo_version.md
index cf23e7fef..471edd2bb 100644
--- a/content/en/commands/hugo_version.md
+++ b/content/en/commands/hugo_version.md
@@ -33,6 +33,7 @@ hugo version [flags] [args]
--ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern
--logLevel string log level (debug|info|warn|error)
--quiet build in quiet mode
+ -M, --renderToMemory render to memory (mostly useful when running the server)
-s, --source string filesystem path to read files relative from
--themesDir string filesystem path to themes directory
-v, --verbose verbose output
diff --git a/content/en/content-management/_common/_index.md b/content/en/content-management/_common/_index.md
index 47d5812fb..4328d4d14 100644
--- a/content/en/content-management/_common/_index.md
+++ b/content/en/content-management/_common/_index.md
@@ -7,7 +7,7 @@ cascade:
---
<!--
-Files within this headless branch bundle are markdown snippets. Each file must contain front matter delimiters, though front matter fields are not required.
+Files within this headless branch bundle are Markdown snippets. Each file must contain front matter delimiters, though front matter fields are not required.
Include the rendered content using the "include" shortcode.
-->
diff --git a/content/en/content-management/_index.md b/content/en/content-management/_index.md
index 66af24681..8fb0cf25e 100644
--- a/content/en/content-management/_index.md
+++ b/content/en/content-management/_index.md
@@ -1,12 +1,12 @@
---
title: Content management
-linkTitle: Overview
+linkTitle: In this section
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-overview
+ identifier: content-management-in-this-section
parent: content-management
weight: 10
weight: 10
diff --git a/content/en/content-management/archetypes.md b/content/en/content-management/archetypes.md
index 94f038848..f89c3f6b3 100644
--- a/content/en/content-management/archetypes.md
+++ b/content/en/content-management/archetypes.md
@@ -15,7 +15,7 @@ aliases: [/content/archetypes/]
## Overview
-A content file consists of [front matter] and markup. The markup is typically markdown, but Hugo also supports other [content formats]. Front matter can be TOML, YAML, or JSON.
+A content file consists of [front matter] and markup. The markup is typically Markdown, but Hugo also supports other [content formats]. Front matter can be TOML, YAML, or JSON.
The `hugo new content` command creates a new file in the `content` directory, using an archetype as a template. This is the default archetype:
@@ -70,14 +70,33 @@ If none of these exists, Hugo uses a built-in default archetype.
You can use any [template function] within an archetype. As shown above, the default archetype uses the [`replace`](/functions/strings/replace) function to replace hyphens with spaces when populating the title in front matter.
-Archetypes receive the following objects and values in [context]:
+Archetypes receive the following [context]:
-- `.Date`
-- `.Type`
-- `.Site` (see [details](/variables/site/))
-- `.File` (see [details](/variables/file/))
+Date
+: (`string`) The current date and time, formatted in compliance with RFC3339.
-As shown above, the default archetype passes `.File.ContentBaseName` as the argument to the `replace` function when populating the title in front matter.
+File
+: (`hugolib.fileInfo`) Returns file information for the current page. See [details](/methods/page/file).
+
+Type
+: (`string`) The [content type] inferred from the top-level directory name, or as specified by the `--kind` flag passed to the `hugo new content` command.
+
+[content type]: /getting-started/glossary#content-type
+
+Site
+: (`page.Site`) The current site object. See [details](/methods/site/).
+
+## Alternate date format
+
+To insert date and time with an alternate format, use the [`time.Now`] function:
+
+[`time.Now`]: /functions/time/now/
+
+{{< code-toggle file=archetypes/default.md fm=true >}}
+title = '{{ replace .File.ContentBaseName `-` ` ` | title }}'
+date = '{{ time.Now.Format "2006-01-02" }}'
+draft = true
+{{< /code-toggle >}}
## Include content
diff --git a/content/en/content-management/build-options.md b/content/en/content-management/build-options.md
index e8b3354bf..a279fb651 100644
--- a/content/en/content-management/build-options.md
+++ b/content/en/content-management/build-options.md
@@ -12,10 +12,10 @@ toc: true
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` with these defaults:
{{< code-toggle file=content/example/index.md fm=true >}}
-[_build]
+[build]
list = 'always'
publishResources = true
render = 'always'
@@ -55,17 +55,17 @@ render
- `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
+[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
+[`.Page.GetPage`]: /methods/page/getpage/
+[`.Site.GetPage`]: /methods/site/getpage/
{{% /note %}}
## Example -- headless page
@@ -85,7 +85,7 @@ Set the build options in front matter:
{{< code-toggle file=content/headless/index.md fm=true >}}
title = 'Headless page'
-[_build]
+[build]
list = 'never'
publishResources = false
render = 'never'
@@ -121,7 +121,7 @@ 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
+[branch bundle]: /content-management/page-bundles/
```text
content/
@@ -143,7 +143,7 @@ Set the build options in front matter, using the `cascade` keyword to "cascade"
{{< code-toggle file=content/headless/_index.md fm=true >}}
title = 'Headless section'
[[cascade]]
-[cascade._build]
+[cascade.build]
list = 'local'
publishResources = false
render = 'never'
@@ -201,10 +201,10 @@ Set the build options in front matter, using the `cascade` keyword to "cascade"
{{< code-toggle file=content/glossary/_index.md fm=true >}}
title = 'Glossary'
-[_build]
+[build]
render = 'always'
[[cascade]]
-[cascade._build]
+[cascade.build]
list = 'local'
publishResources = false
render = 'never'
@@ -247,7 +247,7 @@ Set the build options in front matter:
{{< code-toggle file=content/books/_index.md fm=true >}}
title = 'Books'
-[_build]
+[build]
render = 'never'
list = 'never'
{{< /code-toggle >}}
@@ -294,7 +294,7 @@ Set the build options in front matter, using the `cascade` keyword to "cascade"
{{< code-toggle file=content/internal/_index.md >}}
title = 'Internal'
[[cascade]]
-[cascade._build]
+[cascade.build]
render = 'never'
list = 'never'
[cascade._target]
diff --git a/content/en/content-management/comments.md b/content/en/content-management/comments.md
index 6e58b36e4..8f55c413c 100644
--- a/content/en/content-management/comments.md
+++ b/content/en/content-management/comments.md
@@ -37,7 +37,7 @@ For many websites, this is enough configuration. However, you also have the opti
### Render Hugo's built-in Disqus partial template
-Disqus has its own [internal template](/templates/internal/#disqus) available, to render it add the following code where you want comments to appear:
+Disqus has its own [internal template](/templates/embedded/#disqus) available, to render it add the following code where you want comments to appear:
```go-html-template
{{ template "_internal/disqus.html" . }}
@@ -45,25 +45,30 @@ Disqus has its own [internal template](/templates/internal/#disqus) available, t
## Alternatives
-These are some alternatives to Disqus:
-
-* [Cactus Comments](https://cactus.chat/docs/integrations/hugo/) (Open Source, Matrix appservice, Docker install)
-* [Comentario](https://gitlab.com/comentario/comentario) (Open Source, self-hosted, Go/Angular, run locally, in Docker or Kubernetes)
-* [Commento](https://commento.io/) (Open Source, available as a service, local install, or docker image)
-* [Giscus](https://giscus.app/) (Open source, comments system powered by GitHub Discussions)
-* [Graph Comment](https://graphcomment.com/)
-* [Hyvor Talk](https://talk.hyvor.com/) (Available as a service)
-* [IntenseDebate](https://intensedebate.com/)
-* [Isso](https://isso-comments.de/) (Self-hosted, Python) ([tutorial][issotutorial])
-* [Muut](https://muut.com/)
-* [Remark42](https://remark42.com/) (Open source, Golang, Easy to run docker)
-* [ReplyBox](https://getreplybox.com/)
-* [Staticman](https://staticman.net/)
-* [Talkyard](https://blog-comments.talkyard.io/) (Open source, & serverless hosting)
-* [Utterances](https://utteranc.es/) (Open source, GitHub comments widget built on GitHub issues)
+Commercial commenting systems:
+
+- [Emote](https://emote.com/)
+- [Graph Comment](https://graphcomment.com/)
+- [Hyvor Talk](https://talk.hyvor.com/)
+- [IntenseDebate](https://intensedebate.com/)
+- [ReplyBox](https://getreplybox.com/)
+
+Open-source commenting systems:
+
+- [Cactus Comments](https://cactus.chat/docs/integrations/hugo/)
+- [Comentario](https://gitlab.com/comentario/comentario/)
+- [Comma](https://github.com/Dieterbe/comma/)
+- [Commento](https://commento.io/)
+- [Discourse](https://meta.discourse.org/t/embed-discourse-comments-on-another-website-via-javascript/31963)
+- [Giscus](https://giscus.app/)
+- [Isso](https://isso-comments.de/)
+- [Remark42](https://remark42.com/)
+- [Staticman](https://staticman.net/)
+- [Talkyard](https://blog-comments.talkyard.io/)
+- [Utterances](https://utteranc.es/)
[configuration]: /getting-started/configuration/
-[disquspartial]: /templates/internal/#disqus
+[disquspartial]: /templates/embedded/#disqus
[disqussetup]: https://disqus.com/profile/signup/
[forum]: https://discourse.gohugo.io
[front matter]: /content-management/front-matter/
@@ -71,4 +76,3 @@ These are some alternatives to Disqus:
[issotutorial]: https://stiobhart.net/2017-02-24-isso-comments/
[partials]: /templates/partials/
[MongoDB]: https://www.mongodb.com/
-[tweet]: https://twitter.com/spf13
diff --git a/content/en/content-management/content-adapters.md b/content/en/content-management/content-adapters.md
new file mode 100644
index 000000000..11257b895
--- /dev/null
+++ b/content/en/content-management/content-adapters.md
@@ -0,0 +1,355 @@
+---
+title: Content adapters
+description: Create content adapters to dynamically add content when building your site.
+categories: [content management]
+keywords: []
+menu:
+ docs:
+ parent: content-management
+ weight: 290
+weight: 290
+toc: true
+---
+
+{{< new-in 0.126.0 >}}
+
+## Overview
+
+A content adapter is a template that dynamically creates pages when building a site. For example, use a content adapter to create pages from a remote data source such as JSON, TOML, YAML, or XML.
+
+Unlike templates that reside in the layouts directory, content adapters reside in the content directory, no more than one per directory per language. When a content adapter creates a page, the page's [logical path] will be relative to the content adapter.
+
+```text
+content/
+├── articles/
+│ ├── _index.md
+│ ├── article-1.md
+│ └── article-2.md
+├── books/
+│ ├── _content.gotmpl <-- content adapter
+│ └── _index.md
+└── films/
+ ├── _content.gotmpl <-- content adapter
+ └── _index.md
+```
+
+Each content adapter is named _content.gotmpl and uses the same [syntax] as templates in the layouts directory. You can use any of the [template functions] within a content adapter, as well as the methods described below.
+
+## Methods
+
+Use these methods within a content adapter.
+
+###### AddPage
+
+Adds a page to the site.
+
+{{< code file=content/books/_content.gotmpl >}}
+{{ $content := dict
+ "mediaType" "text/markdown"
+ "value" "The _Hunchback of Notre Dame_ was written by Victor Hugo."
+}}
+{{ $page := dict
+ "content" $content
+ "kind" "page"
+ "path" "the-hunchback-of-notre-dame"
+ "title" "The Hunchback of Notre Dame"
+}}
+{{ .AddPage $page }}
+{{< /code >}}
+
+###### AddResource
+
+Adds a page resource to the site.
+
+{{< code file=content/books/_content.gotmpl >}}
+{{ with resources.Get "images/a.jpg" }}
+ {{ $content := dict
+ "mediaType" .MediaType.Type
+ "value" .
+ }}
+ {{ $resource := dict
+ "content" $content
+ "path" "the-hunchback-of-notre-dame/cover.jpg"
+ }}
+ {{ $.AddResource $resource }}
+{{ end }}
+{{< /code >}}
+
+Then retrieve the new page resource with something like:
+
+{{< code file=layouts/_default/single.html >}}
+{{ with .Resources.Get "cover.jpg" }}
+ <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
+{{ end }}
+{{< /code >}}
+
+###### Site
+
+Returns the `Site` to which the pages will be added.
+
+{{< code file=content/books/_content.gotmpl >}}
+{{ .Site.Title }}
+{{< /code >}}
+
+###### 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 >}}
+{{ .Store.Set "key" "value" }}
+{{ .Store.Get "key" }}
+{{< /code >}}
+
+###### 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.
+
+{{< code file=content/books/_content.gotmpl >}}
+{{ .EnableAllLanguages }}
+{{ $content := dict
+ "mediaType" "text/markdown"
+ "value" "The _Hunchback of Notre Dame_ was written by Victor Hugo."
+}}
+{{ $page := dict
+ "content" $content
+ "kind" "page"
+ "path" "the-hunchback-of-notre-dame"
+ "title" "The Hunchback of Notre Dame"
+}}
+{{ .AddPage $page }}
+{{< /code >}}
+
+## Page map
+
+Set any [front matter field] in the map passed to the [`AddPage`](#addpage) method, excluding `markup`. Instead of setting the `markup` field, specify the `content.mediaType` as described below.
+
+This table describes the fields most commonly passed to the `AddPage` method.
+
+Key|Descripion|Required
+:--|:--|:-:
+`content.mediaType`|The content [media type]. Default is `text/markdown`. See [content formats] for examples.|&nbsp;
+`content.value`|The content value as a string.|&nbsp;
+`dates.date`|The page creation date as a `time.Time` value.|&nbsp;
+`dates.expiryDate`|The page expiry date as a `time.Time` value.|&nbsp;
+`dates.lastmod`|The page last modification date as a `time.Time` value.|&nbsp;
+`dates.publishDate`|The page publication date as a `time.Time` value.|&nbsp;
+`kind`|The [page kind]. Default is `page`.|&nbsp;
+`params`|A map of page parameters.|&nbsp;
+`path`|The page's [logical path] relative to the content adapter. Do not include a leading slash or file extension.|:heavy_check_mark:
+`title`|The page title.|&nbsp;
+
+{{% 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 %}}
+
+## Resource map
+
+Construct the map passed to the [`AddResource`](#addresource) method using the fields below.
+
+Key|Descripion|Required
+:--|:--|:-:
+`content.mediaType`|The content [media type].|:heavy_check_mark:
+`content.value`|The content value as a string or resource.|:heavy_check_mark:
+`name`|The resource name.|&nbsp;
+`params`|A map of resource parameters.|&nbsp;
+`path`|The resources's [logical path] relative to the content adapter. Do not include a leading slash.|:heavy_check_mark:
+`title`|The resource title.|&nbsp;
+
+{{% 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 %}}
+
+## Example
+
+Create pages from remote data, where each page represents a book review.
+
+Step 1
+: Create the content structure.
+
+```text
+content/
+└── books/
+ ├── _content.gotmpl <-- content adapter
+ └── _index.md
+```
+
+Step 2
+: Inspect the remote data to determine how to map key-value pairs to front matter fields.
+
+: <https://gohugo.io/shared/examples/data/books.json>
+
+Step 3
+: Create the content adapter.
+
+{{< code file=content/books/_content.gotmpl copy=true >}}
+{{/* Get remote data. */}}
+{{ $data := dict }}
+{{ $url := "https://gohugo.io/shared/examples/data/books.json" }}
+{{ with resources.GetRemote $url }}
+ {{ with .Err }}
+ {{ errorf "Unable to get remote resource %s: %s" $url . }}
+ {{ else }}
+ {{ $data = . | transform.Unmarshal }}
+ {{ end }}
+{{ else }}
+ {{ errorf "Unable to get remote resource %s" $url }}
+{{ end }}
+
+{{/* Add pages and page resources. */}}
+{{ range $data }}
+
+ {{/* Add page. */}}
+ {{ $content := dict "mediaType" "text/markdown" "value" .summary }}
+ {{ $dates := dict "date" (time.AsTime .date) }}
+ {{ $params := dict "author" .author "isbn" .isbn "rating" .rating "tags" .tags }}
+ {{ $page := dict
+ "content" $content
+ "dates" $dates
+ "kind" "page"
+ "params" $params
+ "path" .title
+ "title" .title
+ }}
+ {{ $.AddPage $page }}
+
+ {{/* Add page resource. */}}
+ {{ $item := . }}
+ {{ with $url := $item.cover }}
+ {{ with resources.GetRemote $url }}
+ {{ with .Err }}
+ {{ errorf "Unable to get remote resource %s: %s" $url . }}
+ {{ else }}
+ {{ $content := dict "mediaType" .MediaType.Type "value" .Content }}
+ {{ $params := dict "alt" $item.title }}
+ {{ $resource := dict
+ "content" $content
+ "params" $params
+ "path" (printf "%s/cover.%s" $item.title .MediaType.SubType)
+ }}
+ {{ $.AddResource $resource }}
+ {{ end }}
+ {{ else }}
+ {{ errorf "Unable to get remote resource %s" $url }}
+ {{ end }}
+ {{ end }}
+
+{{ end }}
+{{< /code >}}
+
+Step 4
+: Create a single page template to render each book review.
+
+{{< code file=layouts/books/single.html copy=true >}}
+{{ define "main" }}
+ <h1>{{ .Title }}</h1>
+
+ {{ with .Resources.GetMatch "cover.*" }}
+ <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="{{ .Params.alt }}">
+ {{ end }}
+
+ <p>Author: {{ .Params.author }}</p>
+
+ <p>
+ ISBN: {{ .Params.isbn }}<br>
+ Rating: {{ .Params.rating }}<br>
+ Review date: {{ .Date | time.Format ":date_long" }}
+ </p>
+
+ {{ with .GetTerms "tags" }}
+ <p>Tags:</p>
+ <ul>
+ {{ range . }}
+ <li><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></li>
+ {{ end }}
+ </ul>
+ {{ end }}
+
+ {{ .Content }}
+{{ end }}
+{{< /code >}}
+
+## Multilingual sites
+
+With multilingual sites you can:
+
+1. Create one content adapter for all languages using the [`EnableAllLanguages`](#enablealllanguages) method as described above.
+2. Create content adapters unique to each language. See the examples below.
+
+### Translations by file name
+
+With this site configuration:
+
+{{< code-toggle file=hugo >}}
+[languages.en]
+weight = 1
+
+[languages.de]
+weight = 2
+{{< /code-toggle >}}
+
+Include a language designator in the content adapter's file name.
+
+```text
+content/
+└── books/
+ ├── _content.de.gotmpl
+ ├── _content.en.gotmpl
+ ├── _index.de.md
+ └── _index.en.md
+```
+
+### Translations by content directory
+
+With this site configuration:
+
+{{< code-toggle file=hugo >}}
+[languages.en]
+contentDir = 'content/en'
+weight = 1
+
+[languages.de]
+contentDir = 'content/de'
+weight = 2
+{{< /code-toggle >}}
+
+Create a single content adapter in each directory:
+
+```text
+content/
+├── de/
+│ └── books/
+│ ├── _content.gotmpl
+│ └── _index.md
+└── en/
+ └── books/
+ ├── _content.gotmpl
+ └── _index.md
+```
+
+## Page collisions
+
+Two or more pages collide when they have the same publication path. Due to concurrency, the content of the published page is indeterminate. Consider this example:
+
+```text
+content/
+└── books/
+ ├── _content.gotmpl <-- content adapter
+ ├── _index.md
+ └── the-hunchback-of-notre-dame.md
+```
+
+If the content adapter also creates books/the-hunchback-of-notre-dame, the content of the published page is indeterminate. You can not define the processing order.
+
+To detect page collisions, use the `--printPathWarnings` flag when building your site.
+
+[content formats]: /content-management/formats/#classification
+[front matter field]: /content-management/front-matter/#fields
+[logical path]: /getting-started/glossary/#logical-path
+[media type]: https://en.wikipedia.org/wiki/Media_type
+[page kind]: /getting-started/glossary/#page-kind
+[syntax]: /templates/introduction/
+[template functions]: /functions/
diff --git a/content/en/content-management/cross-references.md b/content/en/content-management/cross-references.md
index 500e388a4..24da0bfda 100644
--- a/content/en/content-management/cross-references.md
+++ b/content/en/content-management/cross-references.md
@@ -16,7 +16,7 @@ The `ref` and `relref` shortcodes display the absolute and relative permalinks t
## Use of `ref` and `relref`
-The `ref` and `relref` shortcodes require a single parameter: 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.
+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
.
@@ -60,7 +60,7 @@ index.md can be reference either by its path or by its containing folder without
{{</* ref "/products/index" */>}} // <- References /products/index.md
```
-To generate a hyperlink using `ref` or `relref` in markdown:
+To generate a hyperlink using `ref` or `relref` in Markdown:
```text
[About]({{</* ref "/about" */>}} "About Us")
@@ -70,9 +70,11 @@ Hugo emits an error or warning if a document cannot be uniquely resolved. The er
### 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:
-```go-html-template
+```text
{{</* relref path="document.md" lang="ja" */>}}
```
@@ -80,7 +82,7 @@ To link to another language version of a document, use this syntax:
To link to another Output Format of a document, use this syntax:
-```go-html-template
+```text
{{</* relref path="document.md" outputFormat="rss" */>}}
```
@@ -88,7 +90,7 @@ To link to another Output Format of a document, use this syntax:
When using Markdown document types, Hugo generates element IDs for every heading on a page. For example:
-```md
+```text
## Reference
```
@@ -100,14 +102,14 @@ produces this HTML:
Get the permalink to a heading by appending the ID to the path when using the `ref` or `relref` shortcodes:
-```go-html-template
+```text
{{</* ref "document.md#reference" */>}}
{{</* relref "document.md#reference" */>}}
```
Generate a custom heading ID by including an attribute. For example:
-```md
+```text
## Reference A {#foo}
## Reference B {id="bar"}
```
@@ -121,7 +123,7 @@ produces this HTML:
Hugo will generate unique element IDs if the same heading appears more than once on a page. For example:
-```md
+```text
## Reference
## Reference
## Reference
diff --git a/content/en/content-management/data-sources.md b/content/en/content-management/data-sources.md
new file mode 100644
index 000000000..40634acef
--- /dev/null
+++ b/content/en/content-management/data-sources.md
@@ -0,0 +1,126 @@
+---
+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
+aliases: [/extras/datafiles/,/extras/datadrivencontent/,/doc/datafiles/,/templates/data-templates/]
+---
+
+Hugo can access and [unmarshal] local and remote data sources including CSV, JSON, TOML, YAML, and XML. Use this data to augment existing content or to create new content.
+
+[unmarshal]: /getting-started/glossary/#unmarshal
+
+A data source might be a file in the data directory, a [global resource], a [page resource], or a [remote resource].
+
+[global resource]: /getting-started/glossary/#global-resource
+[page resource]: /getting-started/glossary/#page-resource
+[remote resource]: /getting-started/glossary/#remote-resource
+
+## Data directory
+
+The data directory in the root of your project may contain one or more data files, in either a flat or nested tree. Hugo merges the data files to create a single data structure, accessible with the `Data` method on a `Site` object.
+
+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 %}}
+
+Theme and module authors may wish to namespace their data files to prevent collisions. For example:
+
+```text
+project/
+└── data/
+ └── mytheme/
+ └── foo.json
+```
+
+{{% note %}}
+Do not place CSV files in the data directory. Access CSV files as page, global, or remote resources.
+{{% /note %}}
+
+See the documentation for the [`Data`] method on `Page` 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.
+
+See the [`transform.Unmarshal`](/functions/transform/unmarshal/#global-resource) documentation for details and examples.
+
+## Page resources
+
+Use the `Resources.Get` method on a `Page` object combined with the `transform.Unmarshal` function to access data files that exist as page resources.
+
+See the [`transform.Unmarshal`](/functions/transform/unmarshal/#page-resource) documentation for details and examples.
+
+## Remote resources
+
+Use the `resources.GetRemote` and `transform.Unmarshal` functions to access remote data.
+
+See the [`transform.Unmarshal`](/functions/transform/unmarshal/#remote-resource) documentation for details and examples.
+
+## Augment existing content
+
+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 >}}
+"name","type","breed","age"
+"Spot","dog","Collie","3"
+"Felix","cat","Malicious","7"
+{{< /code >}}
+
+{{< code file=content/example.md lang=text >}}
+{{</* csv-to-table "pets.csv" */>}}
+{{< /code >}}
+
+{{< code file=layouts/shortcodes/csv-to-table.html >}}
+{{ with $file := .Get 0 }}
+ {{ with resources.Get $file }}
+ {{ with . | transform.Unmarshal }}
+ <table>
+ <thead>
+ <tr>
+ {{ range index . 0 }}
+ <th>{{ . }}</th>
+ {{ end }}
+ </tr>
+ </thead>
+ <tbody>
+ {{ range after 1 . }}
+ <tr>
+ {{ range . }}
+ <td>{{ . }}</td>
+ {{ end }}
+ </tr>
+ {{ end }}
+ </tbody>
+ </table>
+ {{ end }}
+ {{ else }}
+ {{ errorf "The %q shortcode was unable to find %s. See %s" $.Name $file $.Position }}
+ {{ end }}
+{{ 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:
+
+name|type|breed|age
+:--|:--|:--|:--
+Spot|dog|Collie|3
+Felix|cat|Malicious|7
+
+## Create new content
+
+Use [content adapters] to create new content.
+
+[content adapters]: /content-management/content-adapters/
diff --git a/content/en/content-management/diagrams.md b/content/en/content-management/diagrams.md
index 17407098f..8851034c6 100644
--- a/content/en/content-management/diagrams.md
+++ b/content/en/content-management/diagrams.md
@@ -1,20 +1,22 @@
---
title: Diagrams
-description: Use fenced code blocks and markdown render hooks to display 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: 50
-weight: 50
+ weight: 260
+weight: 260
toc: true
---
-{{< new-in 0.93.0 >}}
## GoAT diagrams (ASCII)
-Hugo supports [GoAT](https://github.com/bep/goat) natively. This means that this code block:
+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
@@ -44,19 +46,21 @@ Will be rendered as:
## Mermaid diagrams
-Hugo currently does not provide default templates for Mermaid diagrams. But you can easily add your own. One way to do it would be to create `layouts/_default/_markup/render-codeblock-mermaid.html`:
+Hugo does not provide a built-in template for Mermaid diagrams. Create your own using a [code block render hook]:
-```go-html-template
+[code block render hook]: /render-hooks/code-blocks/
+
+{{< code file=layouts/_default/_markup/render-codeblock-mermaid.html >}}
<pre class="mermaid">
{{- .Inner | safeHTML }}
</pre>
{{ .Page.Store.Set "hasMermaid" true }}
-```
+{{< /code >}}
-And then include this snippet at the bottom of the content template (**Note**: below `.Content` as the render hook is not processed until `.Content` is executed):
+And then include this snippet at the bottom of the content template:
```go-html-template
-{{ if .Page.Store.Get "hasMermaid" }}
+{{ if .Store.Get "hasMermaid" }}
<script type="module">
import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid/dist/mermaid.esm.min.mjs';
mermaid.initialize({ startOnLoad: true });
diff --git a/content/en/content-management/formats.md b/content/en/content-management/formats.md
index 76c8102b5..e96bc5af3 100644
--- a/content/en/content-management/formats.md
+++ b/content/en/content-management/formats.md
@@ -1,6 +1,6 @@
---
title: Content formats
-description: Both HTML and Markdown are supported content formats.
+description: Create your content using Markdown, HTML, Emacs Org Mode, AsciiDoc, Pandoc, or reStructuredText.
categories: [content management]
keywords: [markdown,asciidoc,pandoc,content format]
menu:
@@ -12,82 +12,126 @@ toc: true
aliases: [/content/markdown-extras/,/content/supported-formats/,/doc/supported-formats/]
---
-You can put any file type into your `/content` directories, but Hugo uses the `markup` front matter value if set or the file extension (see `Markup identifiers` in the table below) to determine if the markup needs to be processed, e.g.:
+## Introduction
-* Markdown converted to HTML
-* [Shortcodes](/content-management/shortcodes/) processed
-* Layout applied
+You may mix content formats throughout your site. For example:
-## List of content formats
+```text
+content/
+└── posts/
+ ├── post-1.md
+ ├── post-2.adoc
+ ├── post-3.org
+ ├── post-4.pandoc
+ ├── post-5.rst
+ └── post-6.html
+```
-The current list of content formats in Hugo:
+Regardless of content format, all content must have [front matter], preferably including both `title` and `date`.
-| Name | Markup identifiers | Comment |
-| ------------- | ------------- |-------------|
-| Goldmark | `markdown`, `goldmark` |Note that you can set the default handler of `md` and `markdown` to something else, see [Configure Markup](/getting-started/configuration-markup/).|
-|Emacs Org-Mode|`org`|See [go-org](https://github.com/niklasfasching/go-org).|
-|AsciiDoc|`asciidocext`, `adoc`, `ad`|Needs [Asciidoctor][ascii] installed.|
-|RST|`rst`|Needs [RST](https://docutils.sourceforge.io/rst.html) installed.|
-|Pandoc|`pandoc`, `pdc`|Needs [Pandoc](https://www.pandoc.org/) installed.|
-|HTML|`html`, `htm`|To be treated as a content file, with layout, shortcodes etc., it must have front matter. If not, it will be copied as-is.|
+Hugo selects the content renderer based on the `markup` identifier in front matter, falling back to the file extension. See the [classification](#classification) table below for a list of markup identifiers and recognized file extensions.
-The `markup identifier` is fetched from either the `markup` variable in front matter or from the file extension. For markup-related configuration, see [Configure Markup](/getting-started/configuration-markup/).
+## Formats
-## External helpers
+### Markdown
-Some of the formats in the table above need external helpers installed on your PC. For example, for AsciiDoc files,
-Hugo will try to call the `asciidoctor` command. This means that you will have to install the associated
-tool on your machine to be able to use these formats.
+Create your content in [Markdown] preceded by front matter.
-Hugo passes reasonable default arguments to these external helpers by default:
+Markdown is Hugo's default content format. Hugo natively renders Markdown to HTML using [Goldmark]. Goldmark is fast and conforms to the [CommonMark] and [GitHub Flavored Markdown] specifications. You can [configure Goldmark] in your site configuration.
-- `asciidoctor`: `--no-header-footer -`
-- `rst2html`: `--leave-comments --initial-header-level=2`
-- `pandoc`: `--mathjax`
+Hugo provides custom Markdown features including:
-{{% note %}}
-Because additional formats are external commands, generation performance will rely heavily on the performance of the external tool you are using. As this feature is still in its infancy, feedback is welcome.
-{{% /note %}}
+[Attributes]
+: Apply HTML attributes such as `class` and `id` to Markdown images and block elements including blockquotes, fenced code blocks, headings, horizontal rules, lists, paragraphs, and tables.
-### Asciidoctor
+[Extensions]
+: Leverage the embedded Markdown extensions to create tables, definition lists, footnotes, task lists, inserted text, mark text, subscripts, superscripts, and more.
-The Asciidoctor community offers a wide set of tools for the AsciiDoc format that can be installed additionally to Hugo.
-[See the Asciidoctor docs for installation instructions](https://asciidoctor.org/docs/install-toolchain/). Make sure that also all
-optional extensions like `asciidoctor-diagram` or `asciidoctor-html5s` are installed if required.
+[Mathematics]
+: Include mathematical equations and expressions in Markdown using LaTeX or TeX typesetting syntax.
-{{% note %}}
-External `asciidoctor` command requires Hugo rendering to _disk_ to a specific destination directory. It is required to run Hugo with the command option `--destination`.
-{{% /note %}}
+[Render hooks]
+: Override the conversion of Markdown to HTML when rendering fenced code blocks, headings, images, and links. For example, render every standalone image as an HTML `figure` element.
-Some Asciidoctor parameters can be customized in Hugo. See&nbsp;[details].
+### HTML
-[details]: /getting-started/configuration-markup/#asciidoc
+Create your content in [HTML] preceded by front matter. The content is typically what you would place within an HTML document's `body` or `main` element.
-## Learn markdown
+### Emacs Org Mode
-Markdown syntax is simple enough to learn in a single sitting. The following are excellent resources to get you up and running:
+Create your content in the [Emacs Org Mode] format preceded by front matter. You can use Org Mode keywords for front matter. See [details](/content-management/front-matter/#emacs-org-mode)).
-* [Daring Fireball: Markdown, John Gruber (Creator of Markdown)][fireball]
-* [Markdown Cheatsheet, Adam Pritchard][mdcheatsheet]
-* [Markdown Tutorial (Interactive), Garen Torikian][mdtutorial]
-* [The Markdown Guide, Matt Cone][mdguide]
+### AsciiDoc
-[ascii]: https://asciidoctor.org/
-[config]: /getting-started/configuration/
-[developer tools]: /tools/
-[fireball]: https://daringfireball.net/projects/markdown/
-[gfmtasks]: https://guides.github.com/features/mastering-markdown/#syntax
-[helperssource]: https://github.com/gohugoio/hugo/blob/77c60a3440806067109347d04eb5368b65ea0fe8/helpers/general.go#L65
-[hl]: /content-management/syntax-highlighting/
-[hlsc]: /content-management/shortcodes/#highlight
-[hugocss]: /css/style.css
-[ietf]: https://tools.ietf.org/html/
-[mathjaxdocs]: https://docs.mathjax.org/en/latest/
-[mdcheatsheet]: https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet
-[mdguide]: https://www.markdownguide.org/
-[mdtutorial]: https://www.markdowntutorial.com/
-[org]: https://orgmode.org/
-[pandoc]: https://www.pandoc.org/
-[rest]: https://docutils.sourceforge.io/rst.html
-[sc]: /content-management/shortcodes/
-[sct]: /templates/shortcode-templates/
+Create your content in the [AsciiDoc] format preceded by front matter. Hugo renders AsciiDoc content to HTML using the Asciidoctor executable. You must install Asciidoctor and its dependencies (Ruby) to use the AsciiDoc content format.
+
+You can [configure the AsciiDoc renderer] in your site configuration.
+
+In its default configuration, Hugo passes these CLI flags when calling the Asciidoctor executable:
+
+```text
+--no-header-footer
+```
+
+The CLI flags passed to the Asciidoctor executable depend on configuration. You may inspect the flags when building your site:
+
+```text
+hugo --logLevel info
+```
+
+### Pandoc
+
+Create your content in the [Pandoc] format preceded by front matter. Hugo renders Pandoc content to HTML using the Pandoc executable. You must install Pandoc to use the Pandoc content format.
+
+Hugo passes these CLI flags when calling the Pandoc executable:
+
+```text
+--mathjax
+```
+
+### reStructuredText
+
+Create your content in the [reStructuredText] format preceded by front matter. Hugo renders reStructuredText content to HTML using [Docutils], specifically rst2html. You must install Docutils and its dependencies (Python) to use the reStructuredText content format.
+
+Hugo passes these CLI flags when calling the rst2html executable:
+
+```text
+--leave-comments --initial-header-level=2
+```
+
+## Classification
+
+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`
+
+When converting content to HTML, Hugo uses:
+
+- Native renderers for Markdown, HTML, and Emacs Org mode
+- External renderers for AsciiDoc, Pandoc, and reStructuredText
+
+Native renderers are faster than external renderers.
+
+[AsciiDoc]: https://asciidoc.org/
+[Asciidoctor]: https://asciidoctor.org/
+[Attributes]: /content-management/markdown-attributes/
+[CommonMark]: https://spec.commonmark.org/current/
+[Docutils]: https://docutils.sourceforge.io/
+[Emacs Org Mode]: https://orgmode.org/
+[Extensions]: /getting-started/configuration-markup/#goldmark-extensions
+[GitHub Flavored Markdown]: https://github.github.com/gfm/
+[Goldmark]: https://github.com/yuin/goldmark
+[HTML]: https://developer.mozilla.org/en-US/docs/Learn/Getting_started_with_the_web/HTML_basics
+[Markdown]: https://daringfireball.net/projects/markdown/
+[Mathematics]: /content-management/mathematics/
+[Pandoc]: https://pandoc.org/
+[Render hooks]: https://gohugo.io/render-hooks/introduction/
+[configure Goldmark]: /getting-started/configuration-markup/#goldmark
+[configure the AsciiDoc renderer]: /getting-started/configuration-markup/#asciidoc
+[front matter]: /content-management/front-matter/
+[reStructuredText]: https://docutils.sourceforge.io/rst.html
diff --git a/content/en/content-management/front-matter.md b/content/en/content-management/front-matter.md
index 7dee78db2..2c01f7854 100644
--- a/content/en/content-management/front-matter.md
+++ b/content/en/content-management/front-matter.md
@@ -1,6 +1,6 @@
---
title: Front matter
-description: Hugo allows you to add front matter in yaml, toml, or json to your content files.
+description: Use front matter to add metadata to your content.
categories: [content management]
keywords: [front matter,yaml,toml,json,metadata,archetypes]
menu:
@@ -12,230 +12,419 @@ toc: true
aliases: [/content/front-matter/]
---
-**Front matter** allows you to keep metadata attached to an instance of a [content type]---i.e., embedded inside a content file---and is one of the many features that gives Hugo its strength.
+## Overview
-{{< youtube Yh2xKRJGff4 >}}
+The front matter at the top of each content file is metadata that:
-## Front matter formats
+- Describes the content
+- Augments the content
+- Establishes relationships with other content
+- Controls the published structure of your site
+- Determines template selection
-Hugo supports four formats for front matter, each with their own identifying tokens.
+Provide front matter using a serialization format, one of [JSON], [TOML], or [YAML]. Hugo determines the front matter format by examining the delimiters that separate the front matter from the page content.
-TOML
-: identified by opening and closing `+++`.
+[json]: https://www.json.org/
+[toml]: https://toml.io/
+[yaml]: https://yaml.org/
-YAML
-: identified by opening and closing `---`.
+See examples of front matter delimiters by toggling between the serialization formats below.
-JSON
-: a single JSON object surrounded by '`{`' and '`}`', followed by a new line.
+{{< code-toggle file=content/example.md fm=true >}}
+title = 'Example'
+date = 2024-02-02T04:14:54-08:00
+draft = false
+weight = 10
+[params]
+author = 'John Smith'
+{{< /code-toggle >}}
-ORG
-: a group of Org mode keywords in the format '`#+KEY: VALUE`'. Any line that does not start with `#+` ends the front matter section.
- Array values can either be separated into multiple lines (`#+KEY: VALUE_1` and `#+KEY: VALUE_2`) or a whitespace separated list of strings (`#+KEY[]: VALUE_1 VALUE_2`).
+Front matter fields may be [scalar], [arrays], or [maps] containing [boolean], [integer], [float], or [string] values. Note that the TOML format also supports date/time values using unquoted strings.
-### Example
+[scalar]: /getting-started/glossary/#scalar
+[arrays]: /getting-started/glossary/#array
+[maps]: /getting-started/glossary/#map
+[boolean]: /getting-started/glossary/#boolean
+[integer]: /getting-started/glossary/#integer
+[float]: /getting-started/glossary/#float
+[string]: /getting-started/glossary/#string
-{{< code-toggle >}}
-title = "spf13-vim 3.0 release and new website"
-description = "spf13-vim is a cross platform distribution of vim plugins and resources for Vim."
-tags = [ ".vimrc", "plugins", "spf13-vim", "vim" ]
-date = "2012-04-06"
-categories = [
- "Development",
- "VIM"
-]
-slug = "spf13-vim-3-0-release-and-new-website"
-{{< /code-toggle >}}
+## Fields
-## Front matter variables
+The most common front matter fields are `date`, `draft`, `title`, and `weight`, but you can specify metadata using any of fields below.
-### Predefined
+{{% note %}}
+The field names below are reserved. For example, you cannot create a custom field named `type`. Create custom fields under the `params` key. See the [parameters] section for details.
-There are a few predefined variables that Hugo is aware of. See [Page Variables][pagevars] for how to call many of these predefined variables in your templates.
+[parameters]: #parameters
+{{% /note %}}
-aliases
-: An array of one or more aliases (e.g., old published paths of renamed content) that will be created in the output directory structure . See [Aliases][aliases] for details.
+###### aliases
-audio
-: An array of paths to audio files related to the page; used by the `opengraph` [internal template](/templates/internal) to populate `og:audio`.
+(`string array`) An array of one or more aliases, where each alias is a relative URL that will redirect the browser to the current location. Access these values from a template using the [`Aliases`] method on a `Page` object. See the [aliases] section for details.
-cascade
-: A map of front matter keys whose values are passed down to the page's descendants unless overwritten by self or a closer ancestor's cascade. See [Front Matter Cascade](#front-matter-cascade) for details.
+[`aliases`]: /methods/page/aliases/
+[aliases]: /content-management/urls/#aliases
-date
-: The datetime assigned to this page. This is usually fetched from the `date` field in front matter, but this behavior is configurable.
+###### build
-description
-: The description for the content.
+(`map`) A map of [build options].
-draft
-: If `true`, the content will not be rendered unless the `--buildDrafts` flag is passed to the `hugo` command.
+[build options]: /content-management/build-options/
-expiryDate
-: The datetime at which the content should no longer be published by Hugo; expired content will not be rendered unless the `--buildExpired` flag is passed to the `hugo` command.
+###### cascade {#cascade-field}
-headless
-: If `true`, sets a leaf bundle to be [headless][headless-bundle].
+(`map`) A map of front matter keys whose values are passed down to the page’s descendants unless overwritten by self or a closer ancestor’s cascade. See the [cascade] section for details.
-images
-: An array of paths to images related to the page; used by [internal templates](/templates/internal) such as `_internal/twitter_cards.html`.
+[cascade]: #cascade
-isCJKLanguage
-: If `true`, Hugo will explicitly treat the content as a CJK language; both `.Summary` and `.WordCount` work properly in CJK languages.
+###### date
-keywords
-: The meta keywords for the content.
+(`string`) The date associated with the page, typically the creation date. Note that the TOML format also supports date/time values using unquoted strings. Access this value from a template using the [`Date`] method on a `Page` object.
-layout
-: The layout Hugo should select from the [lookup order][lookup] when rendering the content. If a `type` is not specified in the front matter, Hugo will look for the layout of the same name in the layout directory that corresponds with a content's section. See [Content Types][content type].
+[`date`]: /methods/page/date/
-lastmod
-: The datetime at which the content was last modified.
+###### description
-linkTitle
-: Used for creating links to content; if set, Hugo defaults to using the `linkTitle` before the `title`.
+(`string`) Conceptually different than the page `summary`, the description is typically rendered within a `meta` element within the `head` element of the published HTML file. Access this value from a template using the [`Description`] method on a `Page` object.
-markup
-: **experimental**; specify `"rst"` for reStructuredText (requires`rst2html`) or `"md"` (default) for Markdown.
+[`description`]: /methods/page/description/
-outputs
-: Allows you to specify output formats specific to the content. See [output formats][outputs].
+###### draft
-publishDate
-: If in the future, content will not be rendered unless the `--buildFuture` flag is passed to `hugo`.
+(`bool`)
+If `true`, the page will not be rendered unless you pass the `--buildDrafts` flag to the `hugo` command. Access this value from a template using the [`Draft`] method on a `Page` object.
-resources
-: Used for configuring page bundle resources. See [Page Resources][page-resources].
+[`draft`]: /methods/page/draft/
-series
-: An array of series this page belongs to, as a subset of the `series` [taxonomy](/content-management/taxonomies/); used by the `opengraph` [internal template](/templates/internal) to populate `og:see_also`.
+###### expiryDate
-slug
-: Overrides the last segment of the URL path. Not applicable to section pages. See [URL Management](/content-management/urls/#slug) for details.
+(`string`) The page expiration date. On or after the expiration date, the page will not be rendered unless you pass the `--buildExpired` flag to the `hugo` command. Note that the TOML format also supports date/time values using unquoted strings. Access this value from a template using the [`ExpiryDate`] method on a `Page` object.
-summary
-: Text used when providing a summary of the article in the `.Summary` page variable; details available in the [content-summaries](/content-management/summaries/) section.
+[`expirydate`]: /methods/page/expirydate/
-title
-: The title for the content.
+###### headless
-type
-: The type of the content; this value will be automatically derived from the directory (i.e., the [section]) if not specified in front matter.
+(`bool`) Applicable to [leaf bundles], if `true` this value sets the `render` and `list` [build options] to `never`, creating a headless bundle of [page resources].
-url
-: Overrides the entire URL path. Applicable to regular pages and section pages. See [URL Management](/content-management/urls/#url) for details.
+[leaf bundles]: /content-management/page-bundles/#leaf-bundles
+[page resources]: /content-management/page-resources/
-videos
-: An array of paths to videos related to the page; used by the `opengraph` [internal template](/templates/internal) to populate `og:video`.
+###### isCJKLanguage
-weight
-: used for [ordering your content in lists][ordering]. Lower weight gets higher precedence. So content with lower weight will come first. If set, weights should be non-zero, as 0 is interpreted as an *unset* weight.
+(`bool`) Set to `true` if the content language is in the [CJK] family. This value determines how Hugo calculates word count, and affects the values returned by the [`WordCount`], [`FuzzyWordCount`], [`ReadingTime`], and [`Summary`] methods on a `Page` object.
-{{% note %}}
-If neither `slug` nor `url` is present and [permalinks are not configured otherwise in your site configuration file](/content-management/urls/#permalinks), Hugo will use the file name of your content to create the output URL. See [Content Organization](/content-management/organization) for an explanation of paths in Hugo and [URL Management](/content-management/urls/) for ways to customize Hugo's default behaviors.
-{{% /note %}}
+[`fuzzywordcount`]: /methods/page/wordcount/
+[`readingtime`]: /methods/page/readingtime/
+[`summary`]: /methods/page/summary/
+[`wordcount`]: /methods/page/wordcount/
+[cjk]: /getting-started/glossary/#cjk
-### User-defined
+###### keywords
-You can add fields to your front matter arbitrarily to meet your needs. These user-defined key-values are placed into a single `.Params` variable for use in your templates.
+(`string array`) An array of keywords, typically rendered within a `meta` element within the `head` element of the published HTML file, or used as a [taxonomy] to classify content. Access these values from a template using the [`Keywords`] method on a `Page` object.
-The following fields can be accessed via `.Params.include_toc` and `.Params.show_comments`, respectively. The [Variables] section provides more information on using Hugo's page- and site-level variables in your templates.
+[`keywords`]: /methods/page/keywords/
+[taxonomy]: /getting-started/glossary/#taxonomy
-{{< code-toggle >}}
-include_toc: true
-show_comments: false
-{{</ code-toggle >}}
+<!-- Added in v0.123.0 but purposefully omitted from documentation. -->
+<!--
+kind
+: The kind of page, e.g. "page", "section", "home" etc. This is usually derived from the content path.
+-->
+
+<!-- Added in v0.123.0 but purposefully omitted from documentation. -->
+<!--
+lang
+: The language code for this page. This is usually derived from the module mount or filename.
+-->
+
+###### lastmod
+
+(`string`) The date that the page was last modified. Note that the TOML format also supports date/time values using unquoted strings. Access this value from a template using the [`Lastmod`] method on a `Page` object.
+
+[`lastmod`]: /methods/page/date/
+
+###### layout
+
+(`string`) Provide a template name to [target a specific template], overriding the default [template lookup order]. Set the value to the base file name of the template, excluding its extension. Access this value from a template using the [`Layout`] method on a `Page` object.
+
+[`layout`]: /methods/page/layout/
+[template lookup order]: /templates/lookup-order/
+[target a specific template]: templates/lookup-order/#target-a-template
+
+###### linkTitle
+
+(`string`) Typically a shorter version of the `title`. Access this value from a template using the [`LinkTitle`] method on a `Page` object.
+
+[`linktitle`]: /methods/page/linktitle/
+
+###### markup
+
+(`string`) An identifier corresponding to one of the supported [content formats]. If not provided, Hugo determines the content renderer based on the file extension.
+
+[content formats]: /content-management/formats/#classification
+
+###### menus
+
+(`string`,`string array`, or `map`) If set, Hugo adds the page to the given menu or menus. See the [menus] page for details.
+
+[menus]: /content-management/menus/#define-in-front-matter
+
+###### outputs
+
+(`string array`) The [output formats] to render.
+
+[output formats]: /templates/output-formats/
+
+<!-- Added in v0.123.0 but purposefully omitted from documentation. -->
+<!--
+path
+: The canonical page path.
+-->
+
+###### params
+
+{{< new-in 0.123.0 >}}
+
+(`map`) A map of custom [page parameters].
+
+[page parameters]: #parameters
+
+###### publishDate
+
+(`string`) The page publication date. Before the publication date, the page will not be rendered unless you pass the `--buildFuture` flag to the `hugo` command. Note that the TOML format also supports date/time values using unquoted strings. Access this value from a template using the [`PublishDate`] method on a `Page` object.
+
+[`publishdate`]: /methods/page/publishdate/
+
+###### resources
+
+(`map array`) An array of maps to provide metadata for [page resources].
+
+[page-resources]: /content-management/page-resources/#page-resources-metadata
+
+###### sitemap
+
+(`map`) A map of sitemap options. See the [sitemap templates] page for details. Access these values from a template using the [`Sitemap`] method on a `Page` object.
+
+[sitemap templates]: /templates/sitemap-template/
+[`sitemap`]: /methods/page/sitemap/
+
+###### slug
+
+(`string`) Overrides the last segment of the URL path. Not applicable to section pages. See the [URL management] page for details. Access this value from a template using the [`Slug`] method on a `Page` object.
+
+[`slug`]: /methods/page/slug/
+[URL management]: /content-management/urls/#slug
+
+###### summary
-## Front matter cascade
+(`string`) Conceptually different than the page `description`, the summary either summarizes the content or serves as a teaser to encourage readers to visit the page. Access this value from a template using the [`Summary`] method on a `Page` object.
-Any node or section can pass down to descendants a set of front matter values as long as defined underneath the reserved `cascade` front matter key.
+[`Summary`]: /methods/page/summary/
+
+###### title
+
+(`string`) The page title. Access this value from a template using the [`Title`] method on a `Page` object.
+
+[`title`]: /methods/page/title/
+
+###### translationKey
+
+(`string`) An arbitrary value used to relate two or more translations of the same page, useful when the translated pages do not share a common path. Access this value from a template using the [`TranslationKey`] method on a `Page` object.
+
+[`translationkey`]: /methods/page/translationkey/
+
+###### type
+
+(`string`) The [content type], overriding the value derived from the top level section in which the page resides. Access this value from a template using the [`Type`] method on a `Page` object.
+
+[content type]: /getting-started/glossary/#content-type
+[`type`]: /methods/page/type/
+
+###### url
+
+(`string`) Overrides the entire URL path. Applicable to regular pages and section pages. See the [URL management] page for details.
+
+###### weight
+(`int`) The page [weight], used to order the page within a [page collection]. Access this value from a template using the [`Weight`] method on a `Page` object.
+
+[page collection]: /getting-started/glossary/#page-collection
+[weight]: /getting-started/glossary/#weight
+[`weight`]: /methods/page/weight/
+
+## Parameters
+
+{{< new-in 0.123.0 >}}
+
+Specify custom page parameters under the `params` key in front matter:
+
+{{< code-toggle file=content/example.md fm=true >}}
+title = 'Example'
+date = 2024-02-02T04:14:54-08:00
+draft = false
+weight = 10
+[params]
+author = 'John Smith'
+{{< /code-toggle >}}
+
+Access these values from a template using the [`Params`] or [`Param`] method on a `Page` object.
+
+[`param`]: /methods/page/param/
+[`params`]: /methods/page/params/
+
+Hugo provides [embedded templates] to optionally insert meta data within the `head` element of your rendered pages. These embedded templates expect the following front matter parameters:
+
+Parameter|Data type|Used by these embedded templates
+:--|:--|:--
+`audio`|`[]string`|[`opengraph.html`]
+`images`|`[]string`|[`opengraph.html`], [`schema.html`], [`twitter_cards.html`]
+`videos`|`[]string`|[`opengraph.html`]
+
+The embedded templates will skip a parameter if not provided in front matter, but will throw an error if the data type is unexpected.
+
+[`opengraph.html`]: {{% eturl opengraph %}}
+[`schema.html`]: {{% eturl schema %}}
+[`twitter_cards.html`]: {{% eturl twitter_cards %}}
+[embedded templates]: /templates/embedded/
+
+## Taxonomies
+
+Classify content by adding taxonomy terms to front matter. For example, with this site configuration:
+
+{{< code-toggle file=hugo >}}
+[taxonomies]
+tag = 'tags'
+genre = 'genres'
+{{< /code-toggle >}}
+
+Add taxonomy terms as shown below:
+
+{{< code-toggle file=content/example.md fm=true >}}
+title = 'Example'
+date = 2024-02-02T04:14:54-08:00
+draft = false
+weight = 10
+tags = ['red','blue']
+genres = ['mystery','romance']
+[params]
+author = 'John Smith'
+{{< /code-toggle >}}
+
+You can add taxonomy terms to the front matter of any these [page kinds]:
+
+- `home`
+- `page`
+- `section`
+- `taxonomy`
+- `term`
+
+[page kinds]: /getting-started/glossary/#page-kind
+
+Access taxonomy terms from a template using the [`Params`] or [`GetTerms`] method on a `Page` object. For example:
+
+{{< code file=layouts/_default/single.html >}}
+{{ with .GetTerms "tags" }}
+ <p>Tags</p>
+ <ul>
+ {{ range . }}
+ <li><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></li>
+ {{ end }}
+ </ul>
+{{ end }}
+{{< /code >}}
+
+[`Params`]: /methods/page/params/
+[`GetTerms`]: /methods/page/getterms/
+
+## Cascade
+
+Any [node] can pass down to its descendants a set of front matter values.
+
+[node]: /getting-started/glossary/#node
### Target specific pages
-The `cascade` block can be a slice with a optional `_target` keyword, allowing for multiple `cascade` values targeting different page sets.
+The `cascade` block can be an array with an optional `_target` keyword, allowing you to target different page sets while cascading values.
-{{< code-toggle >}}
-title ="Blog"
+{{< code-toggle file=content/_index.md fm=true >}}
+title ="Home"
[[cascade]]
+[cascade.params]
background = "yosemite.jpg"
[cascade._target]
-path="/blog/**"
+path="/articles/**"
lang="en"
kind="page"
[[cascade]]
+[cascade.params]
background = "goldenbridge.jpg"
[cascade._target]
kind="section"
{{</ code-toggle >}}
-Keywords available for `_target`:
+Use any combination of these keywords to target a set of pages:
-path
-: A [Glob](https://github.com/gobwas/glob) pattern matching the content path below /content. Expects Unix-styled slashes. Note that this is the virtual path, so it starts at the mount root. The matching supports double-asterisks so you can match for patterns like `/blog/*/**` to match anything from the third level and down.
+###### path {#cascade-path}
-kind
-: A Glob pattern matching the Page's Kind(s), e.g. "{home,section}".
+(`string`) A [Glob](https://github.com/gobwas/glob) pattern matching the content path below /content. Expects Unix-styled slashes. Note that this is the virtual path, so it starts at the mount root. The matching supports double-asterisks so you can match for patterns like `/blog/*/**` to match anything from the third level and down.
-lang
-: A Glob pattern matching the Page's language, e.g. "{en,sv}".
+###### kind {#cascade-kind}
+
+(`string`) A Glob pattern matching the Page's Kind(s), e.g. "{home,section}".
+
+###### lang {#cascade-lang}
-environment
-: A Glob pattern matching the build environment, e.g. "{production,development}"
+(`string`) A Glob pattern matching the Page's language, e.g. "{en,sv}".
+
+###### environment {#cascade-environment}
+
+(`string`) A Glob pattern matching the build environment, e.g. "{production,development}"
Any of the above can be omitted.
{{% note %}}
-When making a site that supports multiple languages, defining a `[[cascade]]` is recommended to be done in [Site Config](../../getting-started/configuration/#cascade) to prevent duplication.
+With a multilingual site it may be more efficient to define the `cascade` values in your site configuration to avoid duplicating the `cascade` values on the section, taxonomy, or term page for each language.
-If you instead define a `[[cascade]]` in front matter for multiple languages, an `content/XX/foo/_index.md` file needs to be made on a per-language basis, with `XX` the glob pattern matching the Page's language. In this case, the **lang** keyword is ignored.
+With a multilingual site, if you choose to define the `cascade` values in front matter, you must create a section, taxonomy, or term page for each language; the `lang` keyword is ignored.
{{% /note %}}
### Example
-In `content/blog/_index.md`
-
-{{< code-toggle >}}
-title: Blog
-cascade:
- banner: images/typewriter.jpg
+{{< code-toggle file=content/posts/_index.md fm=true >}}
+date = 2024-02-01T21:25:36-08:00
+title = 'Posts'
+[cascade]
+ [cascade.params]
+ banner = 'images/typewriter.jpg'
{{</ code-toggle >}}
-With the above example the Blog section page and its descendants will return `images/typewriter.jpg` when `.Params.banner` is invoked unless:
+With the above example the posts section page and its descendants will return `images/typewriter.jpg` when `.Params.banner` is invoked unless:
- Said descendant has its own `banner` value set
- Or a closer ancestor node has its own `cascade.banner` value set.
-## Order content through front matter
+## Emacs Org Mode
-You can assign content-specific `weight` in the front matter of your content. These values are especially useful for [ordering][ordering] in list views. You can use `weight` for ordering of content and the convention of [`<TAXONOMY>_weight`][taxweight] for ordering content within a taxonomy. See [Ordering and Grouping Hugo Lists][lists] to see how `weight` can be used to organize your content in list views.
+If your [content format] is [Emacs Org Mode], you may provide front matter using Org Mode keywords. For example:
-## Override global markdown configuration
+{{< code file=content/example.org lang=text >}}
+#+TITLE: Example
+#+DATE: 2024-02-02T04:14:54-08:00
+#+DRAFT: false
+#+AUTHOR: John Smith
+#+GENRES: mystery
+#+GENRES: romance
+#+TAGS: red
+#+TAGS: blue
+#+WEIGHT: 10
+{{< /code >}}
-It's possible to set some options for Markdown rendering in a content's front matter as an override to the [rendering options set in your project configuration][config].
+Note that you can also specify array elements on a single line:
-## Front matter format specs
+{{< code file=content/example.org lang=text >}}
+#+TAGS[]: red blue
+{{< /code >}}
-- [TOML Spec][toml]
-- [YAML Spec][yaml]
-- [JSON Spec][json]
-
-[variables]: /variables/
-[aliases]: /content-management/urls/#aliases
-[archetype]: /content-management/archetypes/
-[config]: /getting-started/configuration/
-[content type]: /content-management/types/
-[contentorg]: /content-management/organization/
-[headless-bundle]: /content-management/page-bundles/#headless-bundle
-[json]: https://www.ecma-international.org/publications/files/ECMA-ST/ECMA-404.pdf
-[lists]: /templates/lists/#sort-content
-[lookup]: /templates/lookup-order/
-[ordering]: /templates/lists/
-[outputs]: /templates/output-formats/
-[page-resources]: /content-management/page-resources/
-[pagevars]: /variables/page/
-[section]: /content-management/sections/
-[taxweight]: /content-management/taxonomies/
-[toml]: https://toml.io/
-[urls]: /content-management/urls/
-[variables]: /variables/
-[yaml]: https://yaml.org/spec/
+[content format]: /content-management/formats/
+[emacs org mode]: https://orgmode.org/
diff --git a/content/en/content-management/image-processing/index.md b/content/en/content-management/image-processing/index.md
index 9a4f55da1..292aa8a4d 100644
--- a/content/en/content-management/image-processing/index.md
+++ b/content/en/content-management/image-processing/index.md
@@ -249,19 +249,21 @@ You may also access EXIF fields individually, using the [`lang.FormatNumber`] fu
{{ end }}
```
-#### EXIF variables
+#### EXIF methods
-.Date
-: Image creation date/time. Format with the [time.Format] function.
+Date
+: (`time.Time`) Returns the image creation date/time. Format with the [`time.Format`]function.
-.Lat
-: GPS latitude in degrees.
+[time.Format]: /functions/time/format/
-.Long
-: GPS longitude in degrees.
+Lat
+: (`float64`) Returns the GPS latitude in degrees.
-.Tags
-: A collection of the available EXIF tags for this image. You may include or exclude specific tags from this collection in the [site configuration](#exif-data).
+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 in the [site configuration].
## Image processing options
@@ -500,11 +502,11 @@ If you change image processing methods or options, or if you rename or remove im
hugo --gc
```
-[time.Format]: /functions/time/format
+
[`anchor`]: /content-management/image-processing#anchor
[mounted]: /hugo-modules/configuration#module-configuration-mounts
-[page bundle]: /content-management/page-bundles
-[`lang.FormatNumber`]: /functions/lang/formatnumber
+[page bundle]: /content-management/page-bundles/
+[`lang.FormatNumber`]: /functions/lang/formatnumber/
[filters]: /functions/images/filter/#image-filters
[github.com/disintegration/imaging]: <https://github.com/disintegration/imaging#image-resizing>
[Smartcrop]: <https://github.com/muesli/smartcrop#smartcrop>
diff --git a/content/en/content-management/markdown-attributes.md b/content/en/content-management/markdown-attributes.md
new file mode 100644
index 000000000..9c62c4fba
--- /dev/null
+++ b/content/en/content-management/markdown-attributes.md
@@ -0,0 +1,115 @@
+---
+title: Markdown attributes
+description: Use Markdown attributes to add HTML attributes when rendering Markdown to HTML.
+categories: [content management]
+keywords: [goldmark,markdown]
+menu:
+ docs:
+ parent: content-management
+ weight: 240
+weight: 240
+toc: true
+---
+
+## Overview
+
+Hugo supports Markdown attributes on images and block elements including blockquotes, fenced code blocks, headings, horizontal rules, lists, paragraphs, and tables.
+
+For example:
+
+```text
+This is a paragraph.
+{class="foo bar" id="baz"}
+```
+
+With `class` and `id` you can use shorthand notation:
+
+```text
+This is a paragraph.
+{.foo .bar #baz}
+```
+
+Hugo renders both of these to:
+
+```html
+<p class="foo bar" id="baz">This is a paragraph.</p>
+```
+
+## Block elements
+
+Update your site configuration to enable Markdown attributes for block-level elements.
+
+{{< code-toggle file=hugo >}}
+[markup.goldmark.parser.attribute]
+title = true # default is true
+block = true # default is false
+{{< /code-toggle >}}
+
+
+## Standalone images
+
+By default, when the [Goldmark] Markdown renderer encounters a standalone image element (no other elements or text on the same line), it wraps the image element within a paragraph element per the [CommonMark specification].
+
+[CommonMark specification]: https://spec.commonmark.org/current/
+[Goldmark]: https://github.com/yuin/goldmark
+
+If you were to place an attribute list beneath an image element, Hugo would apply the attributes to the surrounding paragraph, not the image.
+
+To apply attributes to a standalone image element, you must disable the default wrapping behavior:
+
+{{< code-toggle file=hugo >}}
+[markup.goldmark.parser]
+wrapStandAloneImageWithinParagraph = false # default is true
+{{< /code-toggle >}}
+
+## Usage
+
+You may add [global HTML attributes], or HTML attributes specific to the current element type. Consistent with its content security model, Hugo removes HTML event attributes such as `onclick` and `onmouseover`.
+
+[global HTML attributes]: https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes
+
+The attribute list consists of one or more key-value pairs, separated by spaces or commas, wrapped by braces. You must quote string values that contain spaces. Unlike HTML, boolean attributes must have both key and value.
+
+For example:
+
+```text
+> This is a blockquote.
+{class="foo bar" hidden=hidden}
+```
+
+Hugo renders this to:
+
+```html
+<blockquote class="foo bar" hidden="hidden">
+ <p>This is a blockquote.</p>
+</blockquote>
+```
+
+In most cases, place the attribute list beneath the markup element. For headings and fenced code blocks, place the attribute list on the right.
+
+Element|Position of attribute list
+:--|:--
+blockquote | bottom
+fenced code block | right
+heading | right
+horizontal rule | bottom
+image | bottom
+list | bottom
+paragraph | bottom
+table | bottom
+
+For example:
+
+````text
+## Section 1 {class=foo}
+
+```bash {class=foo linenos=inline}
+declare a=1
+echo "${a}"
+```
+
+This is a paragraph.
+{class=foo}
+````
+
+As shown above, the attribute list for fenced code blocks is not limited to HTML attributes. You can also configure syntax highlighting by passing one or more of [these options](/functions/transform/highlight/#options).
diff --git a/content/en/content-management/mathematics.md b/content/en/content-management/mathematics.md
index b4dca75b1..a01a166dc 100644
--- a/content/en/content-management/mathematics.md
+++ b/content/en/content-management/mathematics.md
@@ -1,14 +1,14 @@
---
-title: Mathematics in markdown
+title: Mathematics in Markdown
linkTitle: Mathematics
-description: Include mathematical equations and expressions in your markdown using LaTeX or TeX typesetting syntax.
+description: Include mathematical equations and expressions in your Markdown using LaTeX or TeX typesetting syntax.
categories: [content management]
keywords: [chemical,chemistry,latex,math,mathjax,tex,typesetting]
menu:
docs:
parent: content-management
- weight: 250
-weight: 250
+ weight: 270
+weight: 270
toc: true
math: true
---
@@ -45,11 +45,11 @@ The approach described below avoids reliance on platform-specific features like
## Setup
-Follow these instructions to include mathematical equations and expressions in your markdown using LaTeX or TeX typesetting syntax.
+Follow these instructions to include mathematical equations and expressions in your Markdown using LaTeX or TeX typesetting syntax.
###### Step 1
-Enable and configure the Goldmark [passthrough extension] in your site configuration. The passthrough extension preserves raw markdown within delimited snippets of text, including the delimiters themselves.
+Enable and configure the Goldmark [passthrough extension] in your site configuration. The passthrough extension preserves raw Markdown within delimited snippets of text, including the delimiters themselves.
{{< code-toggle file=hugo copy=true >}}
[markup.goldmark.extensions.passthrough]
@@ -122,7 +122,7 @@ The example above loads the partial template if you have set the `math` paramete
###### Step 4
-Include mathematical equations and expressions in your markdown using LaTeX or TeX typesetting syntax.
+Include mathematical equations and expressions in your Markdown using LaTeX or TeX typesetting syntax.
{{< code file=content/math-examples.md copy=true >}}
This is an inline \(a^*=x-b^*\) equation.
@@ -152,8 +152,9 @@ If you set the `math` parameter to `false` in your site configuration, you must
{{< code-toggle file=content/math-examples.md fm=true >}}
title = 'Math examples'
-math = true
date = 2024-01-24T18:09:49-08:00
+[params]
+math = true
{{< /code-toggle >}}
## Inline delimiters
diff --git a/content/en/content-management/menus.md b/content/en/content-management/menus.md
index 1f5d1ef71..1f8595816 100644
--- a/content/en/content-management/menus.md
+++ b/content/en/content-management/menus.md
@@ -34,7 +34,7 @@ Although you can use these methods in combination when defining a menu, the menu
## Define automatically
-To automatically define menu entries for each top-level section of your site, enable the section pages menu in your site configuration.
+To automatically define a menu entry for each top-level [section] of your site, enable the section pages menu in your site configuration.
{{< code-toggle file=hugo >}}
sectionPagesMenu = "main"
@@ -167,7 +167,7 @@ Each menu entry defined in site configuration requires two or more properties:
- Specify `name` and `url` for external links
pageRef
-: (`string`) The file path of the target page, relative to the `content` directory. Omit language code and file extension. Required for *internal* links.
+: (`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
:--|:--
@@ -229,4 +229,5 @@ See [menu templates].
[localize]: /content-management/multilingual/#menus
[menu templates]: /templates/menu-templates/
[multilingual]: /content-management/multilingual/#menus
+[section]: /getting-started/glossary/#section
[template]: /templates/menu-templates/
diff --git a/content/en/content-management/multilingual.md b/content/en/content-management/multilingual.md
index ea9f71787..22e2c186a 100644
--- a/content/en/content-management/multilingual.md
+++ b/content/en/content-management/multilingual.md
@@ -1,7 +1,7 @@
---
title: Multilingual mode
linkTitle: Multilingual
-description: Hugo supports the creation of websites with multiple languages side by side.
+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:
@@ -13,16 +13,24 @@ toc: true
aliases: [/content/multilingual/,/tutorials/create-a-multilingual-site/]
---
-You should define the available languages in a `languages` section in your site configuration.
-
-Also See [Hugo Multilingual Part 1: Content translation].
-
## Configure languages
This is the default language configuration:
{{< code-toggle config=languages />}}
+In the above, `en` is the language key.
+
+{{% note %}}
+Each language key must conform to the syntax described in [RFC 5646]. You must use hyphens to separate subtags. For example:
+
+- `en`
+- `en-GB`
+- `pt-BR`
+
+[RFC 5646]: https://datatracker.ietf.org/doc/html/rfc5646#section-2.1
+{{% /note %}}
+
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 >}}
@@ -55,11 +63,11 @@ subtitle = 'Reference, Tutorials, and Explanations'
{{< /code-toggle >}}
defaultContentLanguage
-: (`string`) The project's default language tag as defined by [RFC 5646]. Must be lower case, and must match one of the defined language keys. Default is `en`. Examples:
+: (`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`
+- `en-GB`
+- `pt-BR`
defaultContentLanguageInSubdir
: (`bool`) If `true`, Hugo renders the default language site in a subdirectory matching the `defaultContentLanguage`. Default is `false`.
@@ -71,7 +79,7 @@ disabled
: (`bool`) If `true`, Hugo will not render content for this language. Default is `false`.
languageCode
-: (`string`) The language tag as defined by [RFC 5646]. This value may include upper and lower case characters, hyphens, or underscores, and 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:
+: (`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`
@@ -84,7 +92,7 @@ languageName
: (`string`) The language name, typically used when rendering a language switcher.
title
-: (`string`) The language title. When set, this overrides the site title for this language.
+: (`string`) The site title for this langauge (optional).
weight
: (`int`) The language weight. When set to a non-zero value, this is the primary sort criteria for this language.
@@ -92,7 +100,7 @@ weight
[`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
+[RFC 5646]: https://datatracker.ietf.org/doc/html/rfc5646#section-2.1
[translating by file name]: #translation-by-file-name
### Changes in Hugo 0.112.0
@@ -150,9 +158,8 @@ Note that you cannot disable the default content language.
### Configure multilingual multihost
-From **Hugo 0.31** we support multiple languages in a multihost configuration. See [this issue](https://github.com/gohugoio/hugo/issues/4027) for details.
-This means that you can now configure a `baseURL` per `language`:
+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.
@@ -162,17 +169,16 @@ Example:
{{< code-toggle file=hugo >}}
[languages]
-[languages.fr]
-baseURL = "https://example.fr"
-languageName = "Français"
-weight = 1
-title = "En Français"
-
-[languages.en]
-baseURL = "https://example.org/"
-languageName = "English"
-weight = 2
-title = "In English"
+ [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
{{</ code-toggle >}}
With the above, the two sites will be generated into `public` with their own root:
@@ -309,7 +315,7 @@ To create a list of links to translated content, use a template similar to the f
<ul>
{{ range .Translations }}
<li>
- <a href="{{ .RelPermalink }}">{{ .Lang }}: {{ .LinkTitle }}{{ if .IsPage }} ({{ i18n "wordCount" . }}){{ end }}</a>
+ <a href="{{ .RelPermalink }}">{{ .Language.Lang }}: {{ .LinkTitle }}{{ if .IsPage }} ({{ i18n "wordCount" . }}){{ end }}</a>
</li>
{{ end }}
</ul>
@@ -334,96 +340,9 @@ The above also uses the [`i18n` function][i18func] described in the next section
## Translation of strings
-Hugo uses [go-i18n] to support string translations. [See the project's source repository][go-i18n-source] to find tools that will help you manage your translation workflows.
-
-Translations are collected from the `themes/<THEME>/i18n/` folder (built into the theme), as well as translations present in `i18n/` at the root of your project. In the `i18n`, the translations will be merged and take precedence over what is in the theme folder. Language files should be named according to [RFC 5646] with names such as `en-US.toml`, `fr.toml`, etc.
-
-Artificial languages with private use subtags as defined in [RFC 5646 &#167; 2.2.7](https://datatracker.ietf.org/doc/html/rfc5646#section-2.2.7) are also supported. You may omit the `art-x-` prefix for brevity. For example:
-
-```text
-art-x-hugolang
-hugolang
-```
-
-Private use subtags must not exceed 8 alphanumeric characters.
-
-### Query basic translation
-
-From within your templates, use the [`i18n`] function like this:
-
-[`i18n`]: /functions/lang/translate
-
-```go-html-template
-{{ i18n "home" }}
-```
-
-The function will search for the `"home"` id:
-
-{{< code-toggle file=i18n/en-US >}}
-[home]
-other = "Home"
-{{< /code-toggle >}}
-
-The result will be
+See the [`lang.Translate`] template function.
-```text
-Home
-```
-
-### Query a flexible translation with variables
-
-Often you will want to use the page variables in the translation strings. To do so, pass the `.` context when calling `i18n`:
-
-```go-html-template
-{{ i18n "wordCount" . }}
-```
-
-The function will pass the `.` context to the `"wordCount"` id:
-
-{{< code-toggle file=i18n/en-US >}}
-[wordCount]
-other = "This article has {{ .WordCount }} words."
-{{< /code-toggle >}}
-
-Assume `.WordCount` in the context has value is 101. The result will be:
-
-```text
-This article has 101 words.
-```
-
-### Query a singular/plural translation
-
-To enable pluralization when translating, pass a map with a numeric `.Count` property to the `i18n` function. The example below uses `.ReadingTime` variable which has a built-in `.Count` property.
-
-```go-html-template
-{{ i18n "readingTime" .ReadingTime }}
-```
-
-The function will read `.Count` from `.ReadingTime` and evaluate whether the number is singular (`one`) or plural (`other`). After that, it will pass to `readingTime` id in `i18n/en-US.toml` file:
-
-{{< code-toggle file=i18n/en-US >}}
-[readingTime]
-one = "One minute to read"
-other = "{{ .Count }} minutes to read"
-{{< /code-toggle >}}
-
-Assuming `.ReadingTime.Count` in the context has value is 525600. The result will be:
-
-```text
-525600 minutes to read
-```
-
-If `.ReadingTime.Count` in the context has value is 1. The result is:
-
-```text
-One minute to read
-```
-
-In case you need to pass a custom data: (`(dict "Count" numeric_value_only)` is minimum requirement)
-
-```go-html-template
-{{ i18n "readingTime" (dict "Count" 25 "FirstArgument" true "SecondArgument" false "Etc" "so on, so far") }}
-```
+[`lang.Translate`]: /functions/lang/translate
## Localization
@@ -676,7 +595,7 @@ To support Multilingual mode in your themes, some considerations must be taken f
* 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` variable will equal `/en` (or whatever your `CurrentLanguage` is). If not enabled, it will be an empty string (and is therefore harmless for single-language Hugo websites).
+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).
## Generate multilingual content with `hugo new content`
@@ -694,23 +613,22 @@ hugo new content content/en/post/test.md
hugo new content content/de/post/test.md
```
-[`abslangurl`]: /functions/urls/abslangurl
+[`abslangurl`]: /functions/urls/abslangurl/
[config]: /getting-started/configuration/
[contenttemplate]: /templates/single-page-templates/
[go-i18n-source]: https://github.com/nicksnyder/go-i18n
[go-i18n]: https://github.com/nicksnyder/go-i18n
[homepage]: /templates/homepage/
[Hugo Multilingual Part 1: Content translation]: https://regisphilibert.com/blog/2018/08/hugo-multilingual-part-1-managing-content-translation/
-[i18func]: /functions/lang/translate
-[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
+[i18func]: /functions/lang/translate/
+[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
-[RFC 5646]: https://tools.ietf.org/html/rfc5646
+[`rellangurl`]: /functions/urls/rellangurl/
[single page templates]: /templates/single-page-templates/
-[`time.Format`]: /functions/time/format
+[`time.Format`]: /functions/time/format/
diff --git a/content/en/content-management/organization/index.md b/content/en/content-management/organization/index.md
index 22b341fcf..e286462d7 100644
--- a/content/en/content-management/organization/index.md
+++ b/content/en/content-management/organization/index.md
@@ -19,13 +19,28 @@ Hugo `0.32` announced page-relative images and other resources packaged into `Pa
These terms are connected, and you also need to read about [Page Resources](/content-management/page-resources) and [Image Processing](/content-management/image-processing) to get the full picture.
-{{< imgproc "1-featured-content-bundles.png" "resize 300x" >}}
-The illustration shows three bundles. Note that the home page bundle cannot contain other content pages, although other files (images etc.) are allowed.
-{{< /imgproc >}}
+```text
+content/
+├── blog/
+│ ├── hugo-is-cool/
+│ │ ├── images/
+│ │ │ ├── funnier-cat.jpg
+│ │ │ └── funny-cat.jpg
+│ │ ├── cats-info.md
+│ │ └── index.md
+│ ├── posts/
+│ │ ├── post1.md
+│ │ └── post2.md
+│ ├── 1-landscape.jpg
+│ ├── 2-sunset.jpg
+│ ├── _index.md
+│ ├── content-1.md
+│ └── content-2.md
+├── 1-logo.png
+└── _index.md
+```
-{{% note %}}
-The bundle documentation is a **work in progress**. We will publish more comprehensive docs about this soon.
-{{% /note %}}
+The file tree above shows three bundles. Note that the home page bundle cannot contain other content pages, although other files (images etc.) are allowed.
## Organization of content source
@@ -52,7 +67,7 @@ Without any additional configuration, the following will automatically work:
## Path breakdown in Hugo
-The following demonstrates the relationships between your content organization and the output URL structure for your Hugo website when it renders. These examples assume you are [using pretty URLs][pretty], which is the default behavior for Hugo. The examples also assume a key-value of `baseURL = "https://example.org"` in your [site's configuration file][config].
+The following demonstrates the relationships between your content organization and the output URL structure for your Hugo website when it renders. These examples assume you are [using pretty URLs][pretty], which is the default behavior for Hugo. The examples also assume a key-value of `baseURL = "https://example.org/"` in your [site's configuration file][config].
### Index pages: `_index.md`
@@ -69,7 +84,7 @@ You can create one `_index.md` for your homepage and one in each of your content
. ⊢--^-⊣
. path slug
. ⊢--^-⊣⊢---^---⊣
-. filepath
+. file path
. ⊢------^------⊣
content/posts/_index.md
```
@@ -140,7 +155,7 @@ The `url` is the entire URL path, defined by the file path and optionally overri
[config]: /getting-started/configuration/
[formats]: /content-management/formats/
[front matter]: /content-management/front-matter/
-[getpage]: /methods/page/getpage
+[getpage]: /methods/page/getpage/
[homepage template]: /templates/homepage/
[homepage]: /templates/homepage/
[lists]: /templates/lists/
diff --git a/content/en/content-management/page-bundles.md b/content/en/content-management/page-bundles.md
index 860fff2bb..af7c2ce14 100644
--- a/content/en/content-management/page-bundles.md
+++ b/content/en/content-management/page-bundles.md
@@ -1,6 +1,6 @@
---
title: Page bundles
-description: Content organization using Page Bundles
+description: Use page bundles to logically associate one or more resources with content.
categories: [content management]
keywords: [page,bundle,leaf,branch]
menu :
@@ -11,173 +11,147 @@ weight: 30
toc: true
---
-Page Bundles are a way to group [Page Resources](/content-management/page-resources/).
+## Introduction
-A Page Bundle can be one of:
+A page bundle is a directory that encapsulates both content and associated resources.
-- Leaf Bundle (leaf means it has no children)
-- Branch Bundle (home page, section, taxonomy terms, taxonomy list)
+By way of example, this site has an "about" page and a "privacy" page:
-| | Leaf Bundle | Branch Bundle |
-|-------------------------------------|----------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| Usage | Collection of content and attachments for single pages | Collection of attachments for section pages (home page, section, taxonomy terms, taxonomy list) |
-| Index file name | `index.md` [^fn:1] | `_index.md` [^fn:1] |
-| Allowed Resources | Page and non-page (like images, PDF, etc.) types | Only non-page (like images, PDF, etc.) types |
-| Where can the Resources live? | At any directory level within the leaf bundle directory. | Only in the directory level **of** the branch bundle directory i.e. the directory containing the `_index.md` ([ref](https://discourse.gohugo.io/t/question-about-content-folder-structure/11822/4?u=kaushalmodi)). |
-| Layout type | [`single`](/templates/single-page-templates/) | [`list`](/templates/lists) |
-| Nesting | Does not allow nesting of more bundles under it | Allows nesting of leaf or branch bundles under it |
-| Example | `content/posts/my-post/index.md` | `content/posts/_index.md` |
-| Content from non-index page files...| Accessed only as page resources | Accessed only as regular pages |
+```text
+content/
+├── about/
+│ ├── index.md
+│ └── welcome.jpg
+└── privacy.md
+```
-## Leaf bundles
+The "about" page is a page bundle. It logically associates a resource with content by bundling them together. Resources within a page bundle are [page resources], accessible with the [`Resources`] method on the `Page` object.
+
+Page bundles are either _leaf bundles_ or _branch bundles_.
+
+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.
+
+{{% note %}}
+In the definitions above and the examples below, the extension of the index file depends on the [content format]. For example, use index.md for Markdown content, index.html for HTML content, index.adoc for AsciiDoc content, etc.
+
+[content format]: /getting-started/glossary/#content-format
+{{% /note %}}
-A _Leaf Bundle_ is a directory at any hierarchy within the `content/`
-directory, that contains an **`index.md`** file.
+## Comparison
-### Examples of leaf bundle organization {#examples-of-leaf-bundle-organization}
+Page bundle characteristics vary by bundle type.
+
+| | Leaf bundle | Branch bundle |
+|---------------------|---------------------------------------------------------|---------------------------------------------------------|
+| Index file | index.md | _index.md |
+| Example | content/about/index.md | content/posts/_index.md |
+| [Page kinds] | `page` | `home`, `section`, `taxonomy`, or `term` |
+| Layout type | [single] | [list] |
+| Descendant pages | None | Zero or more |
+| Resource location | Adjacent to the index file or in a nested subdirectory | Same as a leaf bundles, but excludes descendant bundles |
+| [Resource types] | `page`, `image`, `video`, etc. | all but `page` |
+
+Files with [resource type] `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
+
+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.
```text
content/
├── about
-│ ├── index.md
+│ └── index.md
├── posts
│ ├── my-post
-│ │ ├── content1.md
-│ │ ├── content2.md
-│ │ ├── image1.jpg
-│ │ ├── image2.png
+│ │ ├── content-1.md
+│ │ ├── content-2.md
+│ │ ├── image-1.jpg
+│ │ ├── image-2.png
│ │ └── index.md
│ └── my-other-post
│ └── index.md
-│
└── another-section
- ├── ..
+ ├── foo.md
└── not-a-leaf-bundle
- ├── ..
+ ├── bar.md
└── another-leaf-bundle
└── index.md
```
-In the above example `content/` directory, there are four leaf
-bundles:
+There are four leaf bundles in the example above:
about
-: This leaf bundle is at the root level (directly under
- `content` directory) and has only the `index.md`.
+: This leaf bundle does not contain any page resources.
my-post
-: This leaf bundle has the `index.md`, two other content
- Markdown files and two image files.
+: This leaf bundle contains an index file, two resources of [resource type] `page`, and two resources of resource type `image`.
-- image1, image2:
-These images are page resources of `my-post`
- and only available in `my-post/index.md` resources.
+- content-1, content-2
-- content1, content2:
-These content files are page resources of `my-post`
- and only available in `my-post/index.md` resources.
- They will **not** be rendered 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
+
+ These are resources of resource type `image`, accessible via the `Resources` method on the `Page` object
my-other-post
-: This leaf bundle has only the `index.md`.
+: This leaf bundle does not contain any page resources.
another-leaf-bundle
-: This leaf bundle is nested under couple of
- directories. This bundle also has only the `index.md`.
+: This leaf bundle does not contain any page resources.
{{% note %}}
-The hierarchy depth at which a leaf bundle is created does not matter,
-as long as it is not inside another **leaf** bundle.
+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 %}}
-### Headless bundle
-
-A headless bundle is a bundle that is configured to not get published
-anywhere:
-
-- It will have no `Permalink` and no rendered HTML in `public/`.
-- It will not be part of `.Site.RegularPages`, etc.
-
-But you can get it by `.Site.GetPage`. Here is an example:
-
-```go-html-template
-{{ $headless := .Site.GetPage "/some-headless-bundle" }}
-{{ $reusablePages := $headless.Resources.Match "author*" }}
-<h2>Authors</h2>
-{{ range $reusablePages }}
- <h3>{{ .Title }}</h3>
- {{ .Content }}
-{{ end }}
-```
-
-_In this example, we are assuming the `some-headless-bundle` to be a headless
- bundle containing one or more **page** resources whose `.Name` matches
- `"author*"`._
-
-Explanation of the above example:
-
-1. Get the `some-headless-bundle` Page "object".
-2. Collect a _slice_ of resources in this _Page Bundle_ that matches
- `"author*"` using `.Resources.Match`.
-3. Loop through that _slice_ of nested pages, and output their `.Title` and
- `.Content`.
-
----
-
-A leaf bundle can be made headless by adding below in the front matter
-(in the `index.md`):
-
-{{< code-toggle file=content/headless/index.md fm=true >}}
-headless = true
-{{< /code-toggle >}}
-
-There are many use cases of such headless page bundles:
-
-- Shared media galleries
-- Reusable page content "snippets"
-
## Branch bundles
-A _Branch Bundle_ is any directory at any hierarchy within the
-`content/` directory, that contains at least an **`_index.md`** file.
-
-This `_index.md` can also be directly under the `content/` directory.
-
-{{% note %}}
-Here `md` (markdown) is used just as an example. You can use any file
-type as a content resource as long as it is a content type recognized by Hugo.
-{{% /note %}}
-
-### Examples of branch bundle organization
+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/
-├── branch-bundle-1
-│ ├── branch-content1.md
-│ ├── branch-content2.md
-│ ├── image1.jpg
-│ ├── image2.png
+├── branch-bundle-1/
+│ ├── _index.md
+│ ├── content-1.md
+│ ├── content-2.md
+│ ├── image-1.jpg
+│ └── image-2.png
+├── branch-bundle-2/
+│ ├── a-leaf-bundle/
+│ │ └── index.md
│ └── _index.md
-└── branch-bundle-2
- ├── _index.md
- └── a-leaf-bundle
- └── index.md
+└── _index.md
```
-In the above example `content/` directory, there are two branch
-bundles (and a leaf bundle):
+There are three branch bundles in the example above:
+
+home page
+: This branch bundle contains an index file, two descendant branch bundles, and no resources.
branch-bundle-1
-: This branch bundle has the `_index.md`, two
- other content Markdown files and two image files.
+: This branch bundle contains an index file, two resources of [resource type] `page`, and two resources of resource type `image`.
branch-bundle-2
-: This branch bundle has the `_index.md` and a
- nested leaf bundle.
+: This branch bundle contains an index file and a leaf bundle.
{{% note %}}
-The hierarchy depth at which a branch bundle is created does not
-matter.
+Create branch bundles at any depth within the content directory, but a leaf bundle may not contain another bundle. Leaf bundles do not have descendants.
{{% /note %}}
-[^fn:1]: The `.md` extension is just an example. The extension can be `.html`, `.json` or any valid MIME type.
+
+## Headless bundles
+
+Use [build options] in front matter to create an unpublished leaf or branch bundle whose content and resources you can include in other pages.
+
+[`Resources`]: /methods/page/resources/
+[build options]: content-management/build-options/
+[list]: /templates/lists/
+[page kinds]: /getting-started/glossary/#page-kind
+[page resources]: /content-management/page-resources/
+[resource type]: /getting-started/glossary/#resource-type
+[resource types]: /getting-started/glossary/#resource-type
+[single]: /templates/single-page-templates/
diff --git a/content/en/content-management/page-resources.md b/content/en/content-management/page-resources.md
index f141510bb..6f746488c 100644
--- a/content/en/content-management/page-resources.md
+++ b/content/en/content-management/page-resources.md
@@ -10,6 +10,7 @@ menu:
weight: 80
toc: true
---
+
Page resources are only accessible from [page bundles](/content-management/page-bundles), those directories with `index.md` or
`_index.md` files at their root. Page resources are only available to the
page with which they are bundled.
@@ -114,7 +115,7 @@ GetMatch
.Resources.Match "*sunset.jpg" 🚫
```
-## Page resources metadata
+## Metadata
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).
@@ -133,7 +134,7 @@ title
: Sets the value returned in `Title`
params
-: A map of custom key/values.
+: A map of custom key-value pairs.
### Resources metadata example
@@ -201,3 +202,108 @@ the `Name` and `Title` will be assigned to the resource files as follows:
| guide.pdf | `"pdf-file-2.pdf` | `"guide.pdf"` |
| other\_specs.pdf | `"pdf-file-3.pdf` | `"Specification #1"` |
| photo\_specs.pdf | `"pdf-file-4.pdf` | `"Specification #2"` |
+
+## Multilingual
+
+{{< new-in 0.123.0 >}}
+
+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 %}}
+
+Consider this site configuration:
+
+{{< code-toggle file=hugo >}}
+defaultContentLanguage = 'de'
+defaultContentLanguageInSubdir = true
+
+[languages.de]
+languageCode = 'de-DE'
+languageName = 'Deutsch'
+weight = 1
+
+[languages.en]
+languageCode = 'en-US'
+languageName = 'English'
+weight = 2
+{{< /code-toggle >}}
+
+And this content:
+
+```text
+content/
+└── my-bundle/
+ ├── a.jpg <-- shared page resource
+ ├── b.jpg <-- shared page resource
+ ├── c.de.jpg
+ ├── c.en.jpg
+ ├── index.de.md
+ └── index.en.md
+```
+
+With v0.122.0 and earlier, Hugo duplicated the shared page resources, creating copies for each language:
+
+```text
+public/
+├── de/
+│ ├── my-bundle/
+│ │ ├── a.jpg <-- shared page resource
+│ │ ├── b.jpg <-- shared page resource
+│ │ ├── c.de.jpg
+│ │ └── index.html
+│ └── index.html
+├── en/
+│ ├── my-bundle/
+│ │ ├── a.jpg <-- shared page resource (duplicate)
+│ │ ├── b.jpg <-- shared page resource (duplicate)
+│ │ ├── c.en.jpg
+│ │ └── index.html
+│ └── index.html
+└── index.html
+
+```
+
+With v0.123.0 and later, Hugo places the shared resources in the page bundle for the default content language:
+
+```text
+public/
+├── de/
+│ ├── my-bundle/
+│ │ ├── a.jpg <-- shared page resource
+│ │ ├── b.jpg <-- shared page resource
+│ │ ├── c.de.jpg
+│ │ └── index.html
+│ └── index.html
+├── en/
+│ ├── my-bundle/
+│ │ ├── c.en.jpg
+│ │ └── index.html
+│ └── index.html
+└── index.html
+```
+
+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 %}}
+
+Although duplicating shared page resources is inefficient, you can enable this feature in your site configuration if desired:
+
+{{< code-toggle file=hugo >}}
+[markup.goldmark]
+duplicateResourceFiles = true
+{{< /code-toggle >}}
diff --git a/content/en/content-management/related.md b/content/en/content-management/related.md
index e73dfc32a..478b55a99 100644
--- a/content/en/content-management/related.md
+++ b/content/en/content-management/related.md
@@ -150,7 +150,7 @@ 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 {{< new-in 0.111.0 >}}
-: (`int`) A percentage (0-100) used to remove common keywords from the index. As an example, setting this to `50` will remove all keywords that are used in more than 50% of the documents in the index. Default is `0`.
+: (`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.
diff --git a/content/en/content-management/sections.md b/content/en/content-management/sections.md
index 1b694ce44..0c2f8f0e2 100644
--- a/content/en/content-management/sections.md
+++ b/content/en/content-management/sections.md
@@ -77,7 +77,10 @@ With the file structure from the [example above](#overview):
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` collection instead of the `.Pages` collection in the list template. See&nbsp;[details](/variables/page/#page-collections).
+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.
diff --git a/content/en/content-management/shortcodes.md b/content/en/content-management/shortcodes.md
index bbc2b0cc8..87c9f0825 100644
--- a/content/en/content-management/shortcodes.md
+++ b/content/en/content-management/shortcodes.md
@@ -27,9 +27,9 @@ In addition to cleaner Markdown, shortcodes can be updated any time to reflect n
{{< youtube 2xkNJL4gJ9E >}}
-In your content files, a shortcode can be called by calling `{{%/* shortcodename parameters */%}}`. Shortcode parameters are space delimited, and parameters with internal spaces can be quoted.
+In your content files, a shortcode can be called by calling `{{%/* shortcodename arguments */%}}`. Shortcode arguments are space delimited, and arguments with internal spaces must be quoted.
-The first word in the shortcode declaration is always the name of the shortcode. Parameters follow the name. Depending upon how the shortcode is defined, the parameters may be named, positional, or both, although you can't mix parameter types in a single call. The format for named parameters models that of HTML with the format `name="value"`.
+The first word in the shortcode declaration is always the name of the shortcode. Arguments follow the name. Depending upon how the shortcode is defined, the arguments may be named, positional, or both, although you can't mix argument types in a single call. The format for named arguments models that of HTML with the format `name="value"`.
Some shortcodes use or require closing shortcodes. Again like HTML, the opening and closing shortcodes match (name only) with the closing declaration, which is prepended with a slash.
@@ -45,20 +45,20 @@ Here are two examples of paired shortcodes:
The examples above use two different delimiters, the difference being the `%` character in the first and the `<>` characters in the second.
-### Shortcodes with raw string parameters
+### Shortcodes with raw string arguments
-You can pass multiple lines as parameters to a shortcode by using raw string literals:
+You can pass multiple lines as arguments to a shortcode by using raw string literals:
```go-html-template
{{</* myshortcode `This is some <b>HTML</b>,
and a new line with a "quoted string".` */>}}
```
-### Shortcodes with markdown
+### Shortcodes with Markdown
Shortcodes using the `%` as the outer-most delimiter will be fully rendered when sent to the content renderer. This means that the rendered output from a shortcode can be part of the page's table of contents, footnotes, etc.
-### Shortcodes without markdown
+### Shortcodes without Markdown
The `<` character indicates that the shortcode's inner content does *not* need further rendering. Often shortcodes without Markdown include internal HTML:
@@ -68,17 +68,21 @@ The `<` character indicates that the shortcode's inner content does *not* need f
### Nested shortcodes
-You can call shortcodes within other shortcodes by creating your own templates that leverage the `.Parent` variable. `.Parent` allows you to check the context in which the shortcode is being called. See [Shortcode templates][sctemps].
+You can call shortcodes within other shortcodes by creating your own templates that leverage the `.Parent` method. `.Parent` allows you to check the context in which the shortcode is being called. See [Shortcode templates][sctemps].
-## Use Hugo's built-in shortcodes
+## Embedded shortcodes
-Hugo ships with a set of predefined shortcodes that represent very common usage. These shortcodes are provided for author convenience and to keep your Markdown content clean.
+Use these embedded shortcodes as needed.
-### `figure`
+### figure
-`figure` is an extension of the image syntax in Markdown, which does not provide a shorthand for the more semantic [HTML5 `<figure>` element][figureelement].
+{{% 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 %}}
-The `figure` shortcode can use the following named parameters:
+The `figure` shortcode can use the following named arguments:
src
: URL of the image to be displayed.
@@ -87,10 +91,10 @@ link
: If the image needs to be hyperlinked, URL of the destination.
target
-: Optional `target` attribute for the URL if `link` parameter is set.
+: Optional `target` attribute for the URL if `link` argument is set.
rel
-: Optional `rel` attribute for the URL if `link` parameter is set.
+: Optional `rel` attribute for the URL if `link` argument is set.
alt
: Alternate text for the image if the image cannot be displayed.
@@ -119,13 +123,13 @@ attr
attrlink
: If the attribution text needs to be hyperlinked, URL of the destination.
-#### Example `figure` input
+Example usage:
-{{< code file=figure-input-example.md >}}
+```text
{{</* figure src="elephant.jpg" title="An elephant at sunset" */>}}
-{{< /code >}}
+```
-#### Example `figure` output
+Rendered:
```html
<figure>
@@ -134,7 +138,13 @@ attrlink
</figure>
```
-### `gist`
+### gist
+
+{{% note %}}
+To override Hugo's embedded `gist` shortcode, copy the [source code] to a file with the same name in the layouts/shortcodes directory.
+
+[source code]: {{% eturl gist %}}
+{{% /note %}}
To display a GitHub [gist] with this URL:
@@ -144,7 +154,7 @@ To display a GitHub [gist] with this URL:
https://gist.github.com/user/50a7482715eac222e230d1e64dd9a89b
```
-Include this in your markdown:
+Include this in your Markdown:
```text
{{</* gist user 50a7482715eac222e230d1e64dd9a89b */>}}
@@ -164,7 +174,13 @@ Rendered:
{{< gist jmooring 23932424365401ffa5e9d9810102a477 list.html >}}
-### `highlight`
+### 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.
+
+[source code]: {{% eturl highlight %}}
+{{% /note %}}
To display a highlighted code sample:
@@ -204,113 +220,148 @@ Rendered:
{{ end }}
{{< /highlight >}}
-### `instagram`
+### instagram
-The `instagram` shortcode uses Facebook's **oEmbed Read** feature. The Facebook [developer documentation] states:
+{{% 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 %}}
-- This permission or feature requires successful completion of the App Review process before your app can access live data. [Learn More]
-- This permission or feature is only available with business verification. You may also need to sign additional contracts before your app can access data. [Learn More Here]
+To display an Instagram post with this URL:
-[developer documentation]: https://developers.facebook.com/docs/features-reference/oembed-read
-[Learn More]: https://developers.facebook.com/docs/app-review
-[Learn More Here]: https://developers.facebook.com/docs/development/release/business-verification
+```text
+https://www.instagram.com/p/CxOWiQNP2MO/
+```
-You must obtain an Access Token to use the `instagram` shortcode.
+Include this in your Markdown:
-If your site configuration is private:
+```text
+{{</* instagram CxOWiQNP2MO */>}}
+```
-{{< code-toggle file=hugo >}}
-[services.instagram]
-accessToken = 'xxx'
-{{< /code-toggle >}}
+Rendered:
-If your site configuration is _not_ private, set the Access Token with an environment variable:
+{{< instagram CxOWiQNP2MO >}}
-```sh
-HUGO_SERVICES_INSTAGRAM_ACCESSTOKEN=xxx hugo --gc --minify
-```
+### param
{{% note %}}
-If you are using a Client Access Token, you must combine the Access Token with your App ID using a pipe symbol (`APPID|ACCESSTOKEN`).
+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 %}}
-To display an Instagram post with this URL:
+The `param` shortcode renders a parameter from the page's front matter, falling back to a site parameter of the same name. The shortcode throws an error if the parameter does not exist.
+
+Example usage:
```text
-https://www.instagram.com/p/BWNjjyYFxVx/
+{{</* param testparam */>}}
```
-Include this in your markdown:
+Access nested values by [chaining] the [identifiers]:
+
+[chaining]: /getting-started/glossary/#chain
+[identifiers]: /getting-started/glossary/#identifier
```text
-{{</* instagram BWNjjyYFxVx */>}}
+{{</* param my.nested.param */>}}
```
-### `param`
+### ref
-Gets a value from the current `Page's` parameters set in front matter, with a fallback to the site parameter value. It will log an `ERROR` if the parameter with the given key could not be found in either.
+{{% note %}}
+To override Hugo's embedded `ref` shortcode, copy the [source code] to a file with the same name in the layouts/shortcodes directory.
-```sh
-{{</* param testparam */>}}
-```
+Always use the `{{%/* */%}}` notation when calling this shortcode.
-Since `testparam` is a parameter defined in front matter of this page with the value `Hugo Rocks!`, the above will print:
+[source code]: {{% eturl ref %}}
+{{% /note %}}
-{{< param testparam >}}
+The `ref` shortcode returns the permalink of the given page reference.
-To access deeply nested parameters, use "dot syntax", e.g:
+Example usage:
-```sh
-{{</* param "my.nested.param" */>}}
+```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" */%}})
```
-### `ref` and `relref`
+Rendered:
-These shortcodes will look up the pages by their relative path (e.g., `blog/post.md`) or their logical name (`post.md`) and return the permalink (`ref`) or relative permalink (`relref`) for the found page.
+```html
+<a href="http://example.org/posts/post-1/">Post 1</a>
+<a href="http://example.org/posts/post-1/">Post 1</a>
+<a href="http://example.org/posts/post-1/#foo">Post 1</a>
+<a href="http://example.org/posts/post-1/#foo">Post 1</a>
+```
-`ref` and `relref` also make it possible to make fragmentary links that work for the header links generated by Hugo.
+### relref
{{% note %}}
-Read a more extensive description of `ref` and `relref` in the [cross references](/content-management/cross-references/) documentation.
+To override Hugo's embedded `relref` shortcode, copy the [source code] to a file with the same name in the layouts/shortcodes directory.
+
+Always use the `{{%/* */%}}` notation when calling this shortcode.
+
+[source code]: {{% eturl relref %}}
{{% /note %}}
-`ref` and `relref` take exactly one required parameter of _reference_, quoted and in position `0`.
+The `relref` shortcode returns the permalink of the given page reference.
-#### Example `ref` and `relref` input
+Example usage:
-```go-html-template
-[Neat]({{</* ref "blog/neat.md" */>}})
-[Who]({{</* relref "about.md#who" */>}})
+```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" */%}})
```
-#### Example `ref` and `relref` output
-
-Assuming that standard Hugo pretty URLs are turned on.
+Rendered:
```html
-<a href="https://example.org/blog/neat">Neat</a>
-<a href="/about/#who">Who</a>
+<a href="/posts/post-1/">Post 1</a>
+<a href="/posts/post-1/">Post 1</a>
+<a href="/posts/post-1/#foo">Post 1</a>
+<a href="/posts/post-1/#foo">Post 1</a>
```
-### `tweet`
+### twitter
+
+{{% note %}}
+To override Hugo's embedded `twitter` shortcode, copy the [source code] to a file with the same name in the layouts/shortcodes directory.
+
+You may call the `twitter` shortcode by using its `tweet` alias.
+
+[source code]: {{% eturl twitter %}}
+{{% /note %}}
To display a Twitter post with this URL:
```txt
-https://twitter.com/SanDiegoZoo/status/1453110110599868418
+https://x.com/SanDiegoZoo/status/1453110110599868418
```
-Include this in your markdown:
+Include this in your Markdown:
```text
-{{</* tweet user="SanDiegoZoo" id="1453110110599868418" */>}}
+{{</* twitter user="SanDiegoZoo" id="1453110110599868418" */>}}
```
Rendered:
-{{< tweet user="SanDiegoZoo" id="1453110110599868418" >}}
+{{< twitter user="SanDiegoZoo" id="1453110110599868418" >}}
-### `vimeo`
+### vimeo
+
+{{% 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 %}}
To display a Vimeo video with this URL:
@@ -318,7 +369,7 @@ To display a Vimeo video with this URL:
https://vimeo.com/channels/staffpicks/55073825
```
-Include this in your markdown:
+Include this in your Markdown:
```text
{{</* vimeo 55073825 */>}}
@@ -329,76 +380,98 @@ Rendered:
{{< vimeo 55073825 >}}
{{% note %}}
-If you want to further customize the visual styling of the YouTube or Vimeo output, add a `class` named parameter when calling the shortcode. The new `class` will be added to the `<div>` that wraps the `<iframe>` *and* will remove the inline styles. Note that you will need to call the `id` as a named parameter as well. You can also give the vimeo video a descriptive title with `title`.
+If you want to further customize the visual styling, add a `class` argument when calling the shortcode. The new `class` will be added to the `<div>` that wraps the `<iframe>` *and* will remove the inline styles. Note that you will need to call the `id` as a named argument as well. You can also give the vimeo video a descriptive title with `title`.
```go
{{</* vimeo id="146022717" class="my-vimeo-wrapper-class" title="My vimeo video" */>}}
```
{{% /note %}}
-### `youtube`
+### youtube
-The `youtube` shortcode embeds a responsive video player for [YouTube videos]. Only the ID of the video is required, e.g.:
+{{% note %}}
+To override Hugo's embedded `youtube` shortcode, copy the [source code] to a file with the same name in the layouts/shortcodes directory.
-```txt
-https://www.youtube.com/watch?v=w7Ft2ymGmfc
+[source code]: {{% eturl youtube %}}
+{{% /note %}}
+
+To display a YouTube video with this URL:
+
+```text
+https://www.youtube.com/watch?v=0RKpf3rK57I
```
-#### Example `youtube` input
+Include this in your Markdown:
-Copy the YouTube video ID that follows `v=` in the video's URL and pass it to the `youtube` shortcode:
+```text
+{{</* youtube 0RKpf3rK57I */>}}
+```
-{{< code file=example-youtube-input.md >}}
-{{</* youtube w7Ft2ymGmfc */>}}
-{{< /code >}}
+Rendered:
-Furthermore, you can automatically start playback of the embedded video by setting the `autoplay` parameter to `true`. Remember that you can't mix named and unnamed parameters, so you'll need to assign the yet unnamed video ID to the parameter `id`:
+{{< youtube 0RKpf3rK57I >}}
-{{< code file=example-youtube-input-with-autoplay.md >}}
-{{</* youtube id="w7Ft2ymGmfc" autoplay="true" */>}}
-{{< /code >}}
+The youtube shortcode accepts these named arguments:
-For [accessibility reasons](https://dequeuniversity.com/tips/provide-iframe-titles), it's best to provide a title for your YouTube video. You can do this using the shortcode by providing a `title` parameter. If no title is provided, a default of "YouTube Video" will be used.
+id
+: (`string`) The video `id`. Optional if the `id` is provided as a positional argument as shown in the example above.
-{{< code file=example-youtube-input-with-title.md >}}
-{{</* youtube id="w7Ft2ymGmfc" title="A New Hugo Site in Under Two Minutes" */>}}
-{{< /code >}}
+allowFullScreen
+{{< new-in 0.125.0 >}}
+: (`bool`) Whether the `iframe` element can activate full screen mode. Default is `true`.
-#### Example `youtube` output
+autoplay
+ {{< new-in 0.125.0 >}}
+: (`bool`) Whether to automatically play the video. Forces `mute` to `true`. Default is `false`.
-Using the preceding `youtube` example, the following HTML will be added to your rendered website's markup:
+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.
-{{< code file=example-youtube-output.html >}}
-{{< youtube id="w7Ft2ymGmfc" autoplay="true" >}}
-{{< /code >}}
+controls
+{{< new-in 0.125.0 >}}
+: (`bool`) Whether to display the video controls. Default is `true`.
-#### Example `youtube` display
+end
+{{< 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.
-Using the preceding `youtube` example (without `autoplay="true"`), the following simulates the displayed experience for visitors to your website. Naturally, the final display will be contingent on your style sheets and surrounding markup. The video is also include in the [Quick Start of the Hugo documentation][quickstart].
+loading
+{{< new-in 0.125.0 >}}
+: (`string`) The loading attribute of the `iframe` element, either `eager` or `lazy`. Default is `eager`.
-{{< youtube w7Ft2ymGmfc >}}
+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`.
+
+mute
+{{< 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 >}}
+: (`int`) The time, measured in seconds from the start of the video, when the player should start playing the video.
+
+title
+: (`string`) The `title` attribute of the `iframe` element. Defaults to "YouTube video".
+
+Example using some of the above:
+
+```text
+{{</* youtube id=0RKpf3rK57I start=30 end=60 loading=lazy */>}}
+```
## Privacy configuration
-To learn how to configure your Hugo site to meet the new EU privacy regulation, see [Hugo and the GDPR].
+To learn how to configure your Hugo site to meet the new EU privacy regulation, see [privacy protections].
## Create custom shortcodes
To learn more about creating custom shortcodes, see the [shortcode template documentation].
-[`figure` shortcode]: #figure
-[contentmanagementsection]: /content-management/formats/
-[examplegist]: https://gist.github.com/spf13/7896402
-[figureelement]: https://html5doctor.com/the-figure-figcaption-elements/
-[Hugo and the GDPR]: /about/hugo-and-gdpr/
-[Instagram]: https://www.instagram.com/
-[pagevariables]: /variables/page/
+[privacy protections]: /about/privacy/
[partials]: /templates/partials/
[quickstart]: /getting-started/quick-start/
[sctemps]: /templates/shortcode-templates/
-[scvars]: /variables/shortcode/
[shortcode template documentation]: /templates/shortcode-templates/
-[templatessection]: /templates/
[Vimeo]: https://vimeo.com/
[YouTube Videos]: https://www.youtube.com/
-[YouTube Input shortcode]: #youtube
diff --git a/content/en/content-management/static-files.md b/content/en/content-management/static-files.md
deleted file mode 100644
index c1197ede1..000000000
--- a/content/en/content-management/static-files.md
+++ /dev/null
@@ -1,68 +0,0 @@
----
-title: Static files
-description: Files that get served **statically** (as-is, no modification) on the site root.
-categories: [content management]
-keywords: [source, directories]
-menu:
- docs:
- parent: content-management
- weight: 200
-weight: 200
-toc: true
-aliases: [/static-files]
----
-
-By default, the `static/` directory in the site project is used for
-all **static files** (e.g. stylesheets, JavaScript, images). The static files are served on the site root path (eg. if you have the file `static/image.png` you can access it using `http://{server-url}/image.png`, to include it in a document you can use `![Example image](/image.png) )`.
-
-Hugo can be configured to look into a different directory, or even
-**multiple directories** for such static files by configuring the
-`staticDir` parameter in the [site configuration]. All the files in all the
-static directories will form a union filesystem.
-
-This union filesystem will be served from your site root. So a file
-`<SITE PROJECT>/static/me.png` will be accessible as
-`<MY_BASEURL>/me.png`.
-
-Here's an example of setting `staticDir` and `staticDir2` for a
-multi-language site:
-
-{{< code-toggle file=hugo >}}
-staticDir = ["static1", "static2"]
-
-[languages]
-[languages.en]
-staticDir2 = "static_en"
-baseURL = "https://example.org/"
-languageName = "English"
-weight = 2
-title = "In English"
-[languages.no]
-staticDir = ["staticDir_override", "static_no"]
-baseURL = "https://example.no"
-languageName = "Norsk"
-weight = 1
-title = "På norsk"
-{{</ code-toggle >}}
-
-In the above, with no theme used:
-
-- The English site will get its static files as a union of "static1",
- "static2" and "static_en". On file duplicates, the right-most
- version will win.
-- The Norwegian site will get its static files as a union of
- "staticDir_override" and "static_no".
-
-Note 1
-: The **2** (can be a number between 0 and 10) in `staticDir2` is
- added to tell Hugo that you want to **add** this directory to the
- global set of static directories defined using `staticDir`. Using
- `staticDir` on the language level would replace the global value (as
- can be seen in the Norwegian site case).
-
-Note 2
-: The example above is a [multihost setup]. In a regular setup, all
- the static directories will be available to all sites.
-
-[site configuration]: /getting-started/configuration/#all-configuration-settings
-[multihost setup]: /content-management/multilingual/#configure-multilingual-multihost
diff --git a/content/en/content-management/summaries.md b/content/en/content-management/summaries.md
index 22ed3fc81..7b81cf0a0 100644
--- a/content/en/content-management/summaries.md
+++ b/content/en/content-management/summaries.md
@@ -1,7 +1,7 @@
---
title: Content summaries
linkTitle: Summaries
-description: Hugo generates summaries of your content.
+description: Create and render content summaries.
categories: [content management]
keywords: [summaries,abstracts,read more]
menu:
@@ -13,98 +13,105 @@ toc: true
aliases: [/content/summaries/,/content-management/content-summaries/]
---
+<!-- Do not remove the manual summary divider below. -->
+<!-- If you do, you will break its first literal usage on this page. -->
<!--more-->
-With the use of the `.Summary` [page variable][pagevariables], Hugo generates summaries of content to use as a short version in summary views.
+You can define a content summary manually, in front matter, or automatically. A manual content summary takes precedence over a front matter summary, and a front matter summary takes precedence over an automatic summary.
-## Summary splitting options
+Review the [comparison table](#comparison) below to understand the characteristics of each summary type.
-* Automatic Summary Split
-* Manual Summary Split
-* Front Matter Summary
+## Manual summary
-It is natural to accompany the summary with links to the original content, and a common design pattern is to see this link in the form of a "Read More ..." button. See the `.RelPermalink`, `.Permalink`, and `.Truncated` [page variables][pagevariables].
+Use a `<!--more-->` divider to indicate the end of the content summary. Hugo will not render the summary divider itself.
-### Automatic summary splitting
+{{< code file=content/sample.md >}}
++++
+title: 'Example'
+date: 2024-05-26T09:10:33-07:00
++++
-By default, Hugo automatically takes the first 70 words of your content as its summary and stores it into the `.Summary` page variable for use in your templates. You may customize the summary length by setting `summaryLength` in your [site configuration](/getting-started/configuration/).
+Thénardier was not mistaken. The man was sitting there, and letting
+Cosette get somewhat rested.
-{{% note %}}
-You can customize how HTML tags in the summary are loaded using functions such as `plainify` and `safeHTML`.
-{{% /note %}}
+<!--more-->
-{{% note %}}
-The Hugo-defined summaries are set to use word count calculated by splitting the text by one or more consecutive whitespace characters. If you are creating content in a `CJK` language and want to use Hugo's automatic summary splitting, set `hasCJKLanguage` to `true` in your [site configuration](/getting-started/configuration/).
-{{% /note %}}
+The inn-keeper walked round the brushwood and presented himself
+abruptly to the eyes of those whom he was in search of.
+{{< /code >}}
-### Manual summary splitting
+When using the Emacs Org Mode [content format], use a `# more` divider to indicate the end of the content summary.
-Alternatively, you may add the `<!--more-->` summary divider where you want to split the article.
+[content format]: /content-management/formats/
-For [Org mode content][org], use `# more` where you want to split the article.
+## Front matter summary
-Content that comes before the summary divider will be used as that content's summary and stored in the `.Summary` page variable with all HTML formatting intact.
+Use front matter to define a summary independent of content.
-{{% note %}}
-The concept of a *summary divider* is not unique to Hugo. It is also called the "more tag" or "excerpt separator" in other literature.
-{{% /note %}}
+{{< code file=content/sample.md >}}
++++
+title: 'Example'
+date: 2024-05-26T09:10:33-07:00
+summary: 'Learn more about _Les Misérables_ by Victor Hugo.'
++++
-Pros
-: Freedom, precision, and improved rendering. All HTML tags and formatting are preserved.
+Thénardier was not mistaken. The man was sitting there, and letting
+Cosette get somewhat rested. The inn-keeper walked round the
+brushwood and presented himself abruptly to the eyes of those whom
+he was in search of.
+{{< /code >}}
-Cons
-: Extra work for content authors, since they need to remember to type `<!--more-->` (or `# more` for [org content][org]) in each content file. This can be automated by adding the summary divider below the front matter of an [archetype](/content-management/archetypes/).
+## Automatic summary
-{{% note %}}
-Be careful to enter `<!--more-->` exactly; i.e., all lowercase and with no whitespace.
-{{% /note %}}
+If you have not defined the summary manually or in front matter, Hugo automatically defines the summary based on the [`summaryLength`] in your site configuration.
-### Front matter summary
+[`summaryLength`]: /getting-started/configuration/#summarylength
-You might want your summary to be something other than the text that starts the article. In this case you can provide a separate summary in the `summary` variable of the article front matter.
+{{< code file=content/sample.md >}}
++++
+title: 'Example'
+date: 2024-05-26T09:10:33-07:00
++++
+
+Thénardier was not mistaken. The man was sitting there, and letting
+Cosette get somewhat rested. The inn-keeper walked round the
+brushwood and presented himself abruptly to the eyes of those whom
+he was in search of.
+{{< /code >}}
-Pros
-: Complete freedom of text independent of the content of the article. Markup can be used within the summary.
+For example, with a `summaryLength` of 10, the automatic summary will be:
-Cons
-: Extra work for content authors as they need to write an entirely separate piece of text as the summary of the article.
+```text
+Thénardier was not mistaken. The man was sitting there, and letting
+Cosette get somewhat rested.
+```
-## Summary selection order
+Note that the `summaryLength` is an approximate number of words.
-Because there are multiple ways in which a summary can be specified it is useful to understand the order of selection Hugo follows when deciding on the text to be returned by `.Summary`. It is as follows:
+## Comparison
-1. If there is a `<!--more-->` summary divider present in the article, the text up to the divider will be provided as per the manual summary split method
-2. If there is a `summary` variable in the article front matter the value of the variable will be provided as per the front matter summary method
-3. The text at the start of the article will be provided as per the automatic summary split method
+Each summary type has different characteristics:
-{{% note %}}
-Hugo uses the _first_ of the above steps that returns text. So if, for example, your article has both `summary` variable in its front matter and a `<!--more-->` summary divider Hugo will use the manual summary split method.
-{{% /note %}}
+Type|Precedence|Renders markdown|Renders shortcodes|Strips HTML tags|Wraps single lines with `<p>`
+:--|:-:|:-:|:-:|:-:|:-:
+Manual|1|:heavy_check_mark:|:heavy_check_mark:|:x:|:heavy_check_mark:
+Front&nbsp;matter|2|:heavy_check_mark:|:x:|:x:|:x:
+Automatic|3|:heavy_check_mark:|:heavy_check_mark:|:heavy_check_mark:|:x:
-## Example: first 10 articles with summaries
+## Rendering
-You can show content summaries with the following code. You could use the following snippet, for example, in a [section template].
+Render the summary in a template by calling the [`Summary`] method on a `Page` object.
-{{< code file=page-list-with-summaries.html >}}
-{{ range first 10 .Pages }}
- <article>
- <!-- this <div> includes the title summary -->
- <div>
- <h2><a href="{{ .RelPermalink }}">{{ .Title }}</a></h2>
- {{ .Summary }}
- </div>
+[`Summary`]: /methods/page/summary
+
+```go-html-template
+{{ range site.RegularPages }}
+ <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
+ <div class="summary">
+ {{ .Summary }}
{{ if .Truncated }}
- <!-- This <div> includes a read more link, but only if the summary is truncated... -->
- <div>
- <a href="{{ .RelPermalink }}">Read More…</a>
- </div>
+ <a href="{{ .RelPermalink }}">More ...</a>
{{ end }}
- </article>
+ </div>
{{ end }}
-{{< /code >}}
-
-Note how the `.Truncated` boolean variable value may be used to hide the "Read More..." link when the content is not truncated; i.e., when the summary contains the entire article.
-
-[org]: /content-management/formats/
-[pagevariables]: /variables/page/
-[section template]: /templates/section-templates/
+```
diff --git a/content/en/content-management/syntax-highlighting.md b/content/en/content-management/syntax-highlighting.md
index 62071cd46..070279c4c 100644
--- a/content/en/content-management/syntax-highlighting.md
+++ b/content/en/content-management/syntax-highlighting.md
@@ -6,8 +6,8 @@ keywords: [highlighting,chroma,code blocks,syntax]
menu:
docs:
parent: content-management
- weight: 240
-weight: 240
+ weight: 250
+weight: 250
toc: true
aliases: [/extras/highlighting/,/extras/highlight/,/tools/syntax-highlighting/]
---
@@ -20,7 +20,7 @@ See [Configure Highlight](/getting-started/configuration-markup#highlight).
## Generate syntax highlighter CSS
-If you run with `markup.highlight.noClasses=false` in your site configuration, you need a style sheet.
+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).
You can generate one with Hugo:
@@ -32,7 +32,7 @@ Run `hugo gen chromastyles -h` for more options. See https://xyproto.github.io/s
## Highlight shortcode
-Highlighting is carried out via the built-in [`highlight` shortcode](/content-management/shortcodes/#highlight). It takes exactly one required parameter for the programming language to be highlighted and requires a closing shortcode.
+Highlighting is carried out via the built-in [`highlight` shortcode](/content-management/shortcodes/#highlight). It takes exactly one required argument for the programming language to be highlighted and requires a closing tag.
Options:
diff --git a/content/en/content-management/taxonomies.md b/content/en/content-management/taxonomies.md
index 94f2f6357..764e41a8f 100644
--- a/content/en/content-management/taxonomies.md
+++ b/content/en/content-management/taxonomies.md
@@ -130,26 +130,15 @@ If you want to disable all taxonomies altogether, see the use of `disableKinds`
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 %}}
-## Add taxonomies to content
+## Assign terms to content
-Once a taxonomy is defined at the site level, any piece of content can be assigned to it, regardless of [content type] or [content section].
-
-Assigning content to a taxonomy is done in the [front matter]. Simply create a variable with the *plural* name of the taxonomy and assign all terms you want to apply to the instance of the content type.
-
-{{% note %}}
-If you would like the ability to quickly generate content files with preconfigured taxonomies or terms, read the docs on [Hugo archetypes](/content-management/archetypes/).
-{{% /note %}}
-
-### Example: front matter with taxonomies
+To assign one or more terms to a page, create a front matter field using the plural name of the taxonomy, then add terms to the corresponding array. For example:
{{< code-toggle file=content/example.md fm=true >}}
-title = "Hugo: A fast and flexible static site generator"
-tags = [ "Development", "Go", "fast", "Blogging" ]
-categories = [ "Development" ]
-series = [ "Go Web Dev" ]
-slug = "hugo"
-project_url = "https://github.com/gohugoio/hugo"
-{{</ code-toggle >}}
+title = 'Example'
+tags = ['Tag A','Tag B']
+categories = ['Category A','Category B']
+{{< /code-toggle >}}
## Order taxonomies
@@ -182,7 +171,7 @@ wikipedia: "https://en.wikipedia.org/wiki/Bruce_Willis"
[content type]: /content-management/types/
[documentation on archetypes]: /content-management/archetypes/
[front matter]: /content-management/front-matter/
-[taxonomy list templates]: /templates/taxonomy-templates/#taxonomy-list-templates
+[taxonomy list templates]: /templates/taxonomy-templates/#taxonomy-templates
[taxonomy templates]: /templates/taxonomy-templates/
-[terms within the taxonomy]: /templates/taxonomy-templates/#taxonomy-terms-templates
+[terms within the taxonomy]: /templates/taxonomy-templates/#term-templates
[site configuration]: /getting-started/configuration/
diff --git a/content/en/content-management/toc.md b/content/en/content-management/toc.md
deleted file mode 100644
index 69021ac45..000000000
--- a/content/en/content-management/toc.md
+++ /dev/null
@@ -1,117 +0,0 @@
----
-title: Table of contents
-description: Hugo can automatically parse Markdown content and create a Table of Contents you can use in your templates.
-categories: [content management]
-keywords: [table of contents, toc]
-menu:
- docs:
- parent: content-management
- weight: 210
-weight: 210
-toc: true
-aliases: [/extras/toc/]
----
-
-{{% note %}}
-
-Previously, there was no out-of-the-box way to specify which heading levels you want the TOC to render. [See the related GitHub discussion (#1778)](https://github.com/gohugoio/hugo/issues/1778). As such, the resulting `<nav id="TableOfContents"><ul></ul></nav>` was going to start at `<h1>` when pulling from `{{ .Content }}`.
-
-Hugo [v0.60.0](https://github.com/gohugoio/hugo/releases/tag/v0.60.0) made a switch to [Goldmark](https://github.com/yuin/goldmark/) as the default library for Markdown which has improved and configurable implementation of TOC. Take a look at [how to configure TOC](/getting-started/configuration-markup/#table-of-contents) for Goldmark renderer.
-
-{{% /note %}}
-
-## Usage
-
-Create your Markdown the way you normally would with the appropriate headings. Here is some example content:
-
-```md
-<!-- Your front matter up here -->
-
-## Introduction
-
-One morning, when Gregor Samsa woke from troubled dreams, he found himself transformed in his bed into a horrible vermin.
-
-## My Heading
-
-He lay on his armour-like back, and if he lifted his head a little he could see his brown belly, slightly domed and divided by arches into stiff sections. The bedding was hardly able to cover it and seemed ready to slide off any moment.
-
-### My Subheading
-
-A collection of textile samples lay spread out on the table - Samsa was a traveling salesman - and above it there hung a picture that he had recently cut out of an illustrated magazine and housed in a nice, gilded frame. It showed a lady fitted out with a fur hat and fur boa who sat upright, raising a heavy fur muff that covered the whole of her lower arm towards the viewer. Gregor then turned to look out the window at the dull weather. Drops
-```
-
-Hugo will take this Markdown and create a table of contents from `## Introduction`, `## My Heading`, and `### My Subheading` and then store it in the [page variable][pagevars]`.TableOfContents`.
-
-The built-in `.TableOfContents` variables outputs a `<nav id="TableOfContents">` element with a child `<ul>`, whose child `<li>` elements begin with appropriate HTML headings. See [the available settings](/getting-started/configuration-markup/#table-of-contents) to configure what heading levels you want to include in TOC.
-
-## Template example: basic TOC
-
-The following is an example of a very basic [single page template]:
-
-{{< code file=layout/_default/single.html >}}
-{{ define "main" }}
- <main>
- <article>
- <header>
- <h1>{{ .Title }}</h1>
- </header>
- {{ .Content }}
- </article>
- <aside>
- {{ .TableOfContents }}
- </aside>
- </main>
-{{ end }}
-{{< /code >}}
-
-## Template example: TOC partial
-
-The following is a [partial template][partials] that adds slightly more logic for page-level control over your table of contents. It assumes you are using a `toc` field in your content's [front matter] that, unless specifically set to `false`, will add a TOC to any page with a `.WordCount` (see [Page Variables][pagevars]) greater than 400. This example also demonstrates how to use [conditionals] in your templating:
-
-{{< code file=layouts/partials/toc.html >}}
-{{ if and (gt .WordCount 400 ) (.Params.toc) }}
-<aside>
- <header>
- <h2>{{ .Title }}</h2>
- </header>
- {{ .TableOfContents }}
-</aside>
-{{ end }}
-{{< /code >}}
-
-{{% note %}}
-With the preceding example, even pages with > 400 words *and* `toc` not set to `false` will not render a table of contents if there are no headings in the page for the `{{ .TableOfContents }}` variable to pull from.
-{{% /note %}}
-
-## Usage with AsciiDoc
-
-Hugo supports table of contents with AsciiDoc content format.
-
-In the header of your content file, specify the AsciiDoc TOC directives necessary to ensure that the table of contents is generated. Hugo will use the generated TOC to populate the page variable `.TableOfContents` in the same way as described for Markdown. See example below:
-
-```asciidoc
-// <!-- Your front matter up here -->
-:toc:
-// Set toclevels to be at least your hugo [markup.tableOfContents.endLevel] configuration key
-:toclevels: 4
-
-== Introduction
-
-One morning, when Gregor Samsa woke from troubled dreams, he found himself transformed in his bed into a horrible vermin.
-
-== My Heading
-
-He lay on his armour-like back, and if he lifted his head a little he could see his brown belly, slightly domed and divided by arches into stiff sections. The bedding was hardly able to cover it and seemed ready to slide off any moment.
-
-=== My Subheading
-
-A collection of textile samples lay spread out on the table - Samsa was a traveling salesman - and above it there hung a picture that he had recently cut out of an illustrated magazine and housed in a nice, gilded frame. It showed a lady fitted out with a fur hat and fur boa who sat upright, raising a heavy fur muff that covered the whole of her lower arm towards the viewer. Gregor then turned to look out the window at the dull weather. Drops
-```
-
-Hugo will take this AsciiDoc and create a table of contents store it in the page variable `.TableOfContents`, in the same as described for Markdown.
-
-[conditionals]: /templates/introduction/#conditionals
-[front matter]: /content-management/front-matter/
-[pagevars]: /variables/page/
-[partials]: /templates/partials/
-[single page template]: /templates/single-page-templates/
diff --git a/content/en/content-management/urls.md b/content/en/content-management/urls.md
index a91fe21c0..9dbeed12a 100644
--- a/content/en/content-management/urls.md
+++ b/content/en/content-management/urls.md
@@ -89,12 +89,10 @@ If you set both `slug` and `url` in front matter, the `url` value takes preceden
### 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].
+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.
-[page kind]: /templates/section-templates/#page-kinds
-
#### Monolingual examples {#permalinks-monolingual-examples}
With this content structure:
@@ -235,46 +233,46 @@ public/
#### Tokens
-Use these tokens when defining the URL pattern. The `date` field in front matter determines the value of time-related tokens.
+Use these tokens when defining the URL pattern.
`:year`
-: the 4-digit year
+: The 4-digit year as defined in the front matter `date` field.
`:month`
-: the 2-digit month
+: The 2-digit month as defined in the front matter `date` field.
`:monthname`
-: the name of the month
+: The name of the month as defined in the front matter `date` field.
`:day`
-: the 2-digit day
+: The 2-digit day as defined in the front matter `date` field.
`:weekday`
-: the 1-digit day of the week (Sunday = 0)
+: 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
+: 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
+: The 1- to 3-digit day of the year as defined in the front matter `date` field.
`:section`
-: the content's 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.
+: 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 content's 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 content's slug (or title if no slug is provided in the front matter)
-
-`:slugorfilename`
-: the content's slug (or file name if no slug is provided in the front matter)
+: 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)
+: 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:
@@ -307,7 +305,7 @@ 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].
+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 %}}
@@ -423,10 +421,12 @@ Hugo renders alias files before rendering pages. A new page with the previous fi
### Customize
-Create a new template (`layouts/alias.html`) to customize the content of the alias files. The template receives the following context:
+To override Hugo's embedded `alias` template, copy the [source code] to a file with the same name in the layouts directory. The template receives the following context:
Permalink
-: the link to the page being aliased
+: The link to the page being aliased.
Page
-: the Page data for the page being aliased
+: The Page data for the page being aliased.
+
+[source code]: {{% eturl alias %}}
diff --git a/content/en/contribute/_index.md b/content/en/contribute/_index.md
index ca7a18c36..87af8fa79 100644
--- a/content/en/contribute/_index.md
+++ b/content/en/contribute/_index.md
@@ -1,12 +1,12 @@
---
title: Contribute to the Hugo project
-linkTitle: Overview
+linkTitle: In this section
description: Contribute to Hugo development, documentation, and themes.
categories: []
keywords: []
menu:
docs:
- identifier: contribute-overview
+ identifier: contribute-in-this-section
parent: contribute
weight: 10
weight: 10
diff --git a/content/en/contribute/development.md b/content/en/contribute/development.md
index c2eaa93ad..07d4c4457 100644
--- a/content/en/contribute/development.md
+++ b/content/en/contribute/development.md
@@ -11,8 +11,6 @@ weight: 20
toc: true
---
-
-
## Introduction
You can contribute to the Hugo project by:
@@ -146,3 +144,31 @@ Step 9
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
+
+You can build, install, and test Hugo at any point in its development history. The examples below build and install the extended version of Hugo.
+
+To build and install the latest release:
+
+```sh
+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/[email protected]
+```
+
+To build and install at the latest commit on the master branch:
+
+```sh
+CGO_ENABLED=1 go install -tags extended github.com/gohugoio/hugo@master
+```
+
+To build and install at a specific commit:
+
+```sh
+CGO_ENABLED=1 go install -tags extended github.com/gohugoio/hugo@0851c17
+```
diff --git a/content/en/contribute/documentation.md b/content/en/contribute/documentation.md
index b0c376839..61c603d6c 100644
--- a/content/en/contribute/documentation.md
+++ b/content/en/contribute/documentation.md
@@ -24,13 +24,13 @@ For documentation related to a new feature, please include the documentation cha
### Markdown
-Please follow these markdown guidelines:
+Please follow these guidelines:
- 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
-- Do not mix [raw HTML] within markdown
+- 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
@@ -44,15 +44,18 @@ Although we do not strictly adhere to the [Microsoft Writing Style Guide], it is
Please link to the [glossary of terms] when necessary, and use the terms consistently throughout the documentation. Of special note:
- The term "front matter" is two words unless you are referring to the configuration key
+- 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
+- Capitalize the word "Markdown"
+- Hyphenate the term "open-source" when used an adjective.
#### Page titles and headings
Please follow these guidelines for page titles and headings:
- Use sentence-style capitalization
-- Avoid markdown in headings and page titles
+- Avoid formatted strings in headings and page titles
- Shorter is better
#### Use active voice with present tense
@@ -92,11 +95,11 @@ Other guidelines to consider:
- 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.
-#### Level 6 markdown headings
+#### Level 6 headings
-Level 6 markdown headings are styled as `dt` elements. This was implemented to support a [glossary] with linkable terms.
+Level 6 headings are styled as `dt` elements. This was implemented to support a [glossary] with linkable terms.
-[glossary]: /getting-started/glossary
+[glossary]: /getting-started/glossary/
## Code examples
@@ -202,26 +205,6 @@ Rendered:
These shortcodes are commonly used throughout the documentation. Other shortcodes are available for specialized use.
-### deprecated-in
-
-Use the “deprecated-in” shortcode to indicate that a feature is deprecated:
-
-```text
-{{%/* deprecated-in 0.120.0 */%}}
-Use [`hugo.IsServer`] instead.
-
-[`hugo.IsServer`]: /functions/hugo/isserver
-{{%/* /deprecated-in */%}}
-```
-
-Rendered:
-
-{{% deprecated-in 0.120.0 %}}
-Use [`hugo.IsServer`] instead.
-
-[`hugo.IsServer`]: /functions/hugo/isserver
-{{% /deprecated-in %}}
-
### code
Use the "code" shortcode for other code examples that require a file name. See the [code examples] above. This shortcode takes these arguments:
@@ -233,7 +216,7 @@ 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`.
+: (`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`.
### code-toggle
@@ -248,17 +231,54 @@ file
fm
: (`bool`) Whether the example is front matter. Default is `false`.
+
+### 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 */%}}
+```
+
+Rendered:
+
+{{% 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).
+
+```text
+This is a link to the [embedded alias template].
+
+[embedded alias template]: {{%/* eturl alias */%}}
+```
+
+Rendered:
+
+This is a link to the [embedded alias template].
+
+[embedded alias template]: {{% eturl alias %}}
+
### new-in
Use the "new-in" shortcode to indicate a new feature:
```text
-{{</* new-in 0.120.0 */>}}
+{{</* new-in 0.127.0 */>}}
```
Rendered:
-{{< new-in 0.120.0 >}}
+{{< new-in 0.127.0 >}}
### note
@@ -288,7 +308,7 @@ Use the "new-in" shortcode to indicate a new feature:
{{</* new-in 0.120.0 */>}}
{{< /code >}}
-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&nbsp;[details](https://github.com/gohugoio/hugoDocs/blob/master/layouts/shortcodes/new-in.html).
+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&nbsp;[details](https://github.com/gohugoio/hugoDocs/blob/master/_vendor/github.com/gohugoio/gohugoioTheme/layouts/shortcodes/new-in.html).
## Deprecated features
@@ -298,7 +318,7 @@ Use the "deprecated-in" shortcode to indicate that a feature is deprecated:
{{%/* deprecated-in 0.120.0 */%}}
Use [`hugo.IsServer`] instead.
-[`hugo.IsServer`]: /functions/hugo/isserver
+[`hugo.IsServer`]: /functions/hugo/isserver/
{{%/* /deprecated-in */%}}
{{< /code >}}
diff --git a/content/en/functions/_common/_index.md b/content/en/functions/_common/_index.md
index 47d5812fb..4328d4d14 100644
--- a/content/en/functions/_common/_index.md
+++ b/content/en/functions/_common/_index.md
@@ -7,7 +7,7 @@ cascade:
---
<!--
-Files within this headless branch bundle are markdown snippets. Each file must contain front matter delimiters, though front matter fields are not required.
+Files within this headless branch bundle are Markdown snippets. Each file must contain front matter delimiters, though front matter fields are not required.
Include the rendered content using the "include" shortcode.
-->
diff --git a/content/en/functions/_common/go-html-template-package.md b/content/en/functions/_common/go-html-template-package.md
new file mode 100644
index 000000000..b622f2b76
--- /dev/null
+++ b/content/en/functions/_common/go-html-template-package.md
@@ -0,0 +1,14 @@
+---
+# Do not remove front matter.
+---
+
+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.
+
+To generate HTML output that is safe against code injection, the html/template package escapes strings in certain contexts.
+
+[text/template]: https://pkg.go.dev/text/template
+[html/template]: https://pkg.go.dev/html/template
diff --git a/content/en/functions/_index.md b/content/en/functions/_index.md
index b4b58eada..bf69df016 100644
--- a/content/en/functions/_index.md
+++ b/content/en/functions/_index.md
@@ -1,12 +1,12 @@
---
title: Functions
-linkTitle: Overview
+linkTitle: In this section
description: A list of Hugo template functions including examples.
categories: []
keywords: []
menu:
docs:
- identifier: functions-overview
+ identifier: functions-in-this-section
parent: functions
weight: 10
weight: 10
diff --git a/content/en/functions/collections/After.md b/content/en/functions/collections/After.md
index 0cf25c7dd..38cf755a0 100644
--- a/content/en/functions/collections/After.md
+++ b/content/en/functions/collections/After.md
@@ -65,7 +65,7 @@ You can use `after` in combination with the [`first`] function and Hugo's [power
{{ end }}
{{< /code >}}
-[`first`]: /functions/collections/first
-[list/section page]: /templates/section-templates
+[`first`]: /functions/collections/first/
+[list/section page]: /templates/section-templates/
[lists]: /templates/lists/#sort-content
[`slice`]: /functions/collections/slice/
diff --git a/content/en/functions/collections/Complement.md b/content/en/functions/collections/Complement.md
index b2a4b42a4..1c785de0b 100644
--- a/content/en/functions/collections/Complement.md
+++ b/content/en/functions/collections/Complement.md
@@ -58,7 +58,7 @@ To list everything except blog articles (`blog`) and frequently asked questions
{{% note %}}
Although the example above demonstrates the `complement` function, you could use the [`where`] function as well:
-[`where`]: /functions/collections/where
+[`where`]: /functions/collections/where/
{{% /note %}}
```go-html-template
diff --git a/content/en/functions/collections/Dictionary.md b/content/en/functions/collections/Dictionary.md
index f46b02e75..2ac875d28 100644
--- a/content/en/functions/collections/Dictionary.md
+++ b/content/en/functions/collections/Dictionary.md
@@ -1,6 +1,6 @@
---
title: collections.Dictionary
-description: Creates a map from a list of key and value pairs.
+description: Returns a map composed of the given key-value pairs.
categories: []
keywords: []
action:
@@ -8,10 +8,12 @@ action:
related:
- functions/collections/Slice
returnType: mapany
- signatures: ['collections.Dictionary KEY VALUE [VALUE...]']
+ signatures: ['collections.Dictionary [VALUE...]']
aliases: [/functions/dict]
---
+Specify the key-value pairs as individual arguments:
+
```go-html-template
{{ $m := dict "a" 1 "b" 2 }}
```
@@ -25,6 +27,12 @@ The above produces this data structure:
}
```
+To create an empty map:
+
+```go-html-template
+{{ $m := dict }}
+```
+
Note that the `key` can be either a `string` or a `string slice`. The latter is useful to create a deeply nested structure, e.g.:
@@ -43,26 +51,3 @@ The above produces this data structure:
}
}
```
-
-## Pass values to a partial template
-
-The partial below creates an SVG and expects `fill`, `height` and `width` from the caller:
-
-### Partial definition
-
-{{< code file=layouts/partials/svgs/external-links.svg >}}
-<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink"
-fill="{{ .fill }}" width="{{ .width }}" height="{{ .height }}" viewBox="0 0 32 32" aria-label="External Link">
-<path d="M25.152 16.576v5.696q0 2.144-1.504 3.648t-3.648 1.504h-14.848q-2.144 0-3.648-1.504t-1.504-3.648v-14.848q0-2.112 1.504-3.616t3.648-1.536h12.576q0.224 0 0.384 0.16t0.16 0.416v1.152q0 0.256-0.16 0.416t-0.384 0.16h-12.576q-1.184 0-2.016 0.832t-0.864 2.016v14.848q0 1.184 0.864 2.016t2.016 0.864h14.848q1.184 0 2.016-0.864t0.832-2.016v-5.696q0-0.256 0.16-0.416t0.416-0.16h1.152q0.256 0 0.416 0.16t0.16 0.416zM32 1.152v9.12q0 0.48-0.352 0.8t-0.8 0.352-0.8-0.352l-3.136-3.136-11.648 11.648q-0.16 0.192-0.416 0.192t-0.384-0.192l-2.048-2.048q-0.192-0.16-0.192-0.384t0.192-0.416l11.648-11.648-3.136-3.136q-0.352-0.352-0.352-0.8t0.352-0.8 0.8-0.352h9.12q0.48 0 0.8 0.352t0.352 0.8z"></path>
-</svg>
-{{< /code >}}
-
-### Partial call
-
-The `fill`, `height` and `width` values can be stored in one object with `dict` and passed to the partial:
-
-{{< code file=layouts/_default/list.html >}}
-{{ partial "svgs/external-links.svg" (dict "fill" "#01589B" "width" 10 "height" 20 ) }}
-{{< /code >}}
-
-[partials]: /templates/partials/
diff --git a/content/en/functions/collections/First.md b/content/en/functions/collections/First.md
index cb2397af1..07634d6b8 100644
--- a/content/en/functions/collections/First.md
+++ b/content/en/functions/collections/First.md
@@ -34,4 +34,4 @@ Use `first` and [`where`] together.
{{ end }}
```
-[`where`]: /functions/collections/where
+[`where`]: /functions/collections/where/
diff --git a/content/en/functions/collections/IndexFunction.md b/content/en/functions/collections/IndexFunction.md
index 6482884fd..977e14d1e 100644
--- a/content/en/functions/collections/IndexFunction.md
+++ b/content/en/functions/collections/IndexFunction.md
@@ -1,6 +1,6 @@
---
title: collections.Index
-description: Looks up the index(es) or key(s) of the data structure passed into it.
+description: Returns the object, element, or value associated with the given key or keys.
categories: []
keywords: []
action:
@@ -8,88 +8,44 @@ action:
related: []
returnType: any
signatures:
- - collections.Index COLLECTION INDEXES
- - collections.Index COLLECTION KEYS
+ - collections.Index COLLECTION KEY...
aliases: [/functions/index,/functions/index-function]
---
-The `index` functions returns the result of indexing its first argument by the following arguments. Each indexed item must be a map or a slice, e.g.:
+Each indexed item must be a map or a slice:
```go-html-template
-{{ $slice := slice "a" "b" "c" }}
-{{ index $slice 0 }} → a
-{{ index $slice 1 }} → b
+{{ $s := slice "a" "b" "c" }}
+{{ index $s 0 }} → a
+{{ index $s 1 }} → b
-{{ $map := dict "a" 100 "b" 200 }}
-{{ index $map "b" }} → 200
+{{ $m := dict "a" 100 "b" 200 }}
+{{ index $m "b" }} → 200
```
-The function takes multiple indices as arguments, and this can be used to get nested values, e.g.:
+Use two or more keys to access a nested value:
```go-html-template
-{{ $map := dict "a" 100 "b" 200 "c" (slice 10 20 30) }}
-{{ index $map "c" 1 }} → 20
-{{ $map := dict "a" 100 "b" 200 "c" (dict "d" 10 "e" 20) }}
-{{ index $map "c" "e" }} → 20
-```
-
-You may write multiple indices as a slice:
-
-```go-html-template
-{{ $map := dict "a" 100 "b" 200 "c" (dict "d" 10 "e" 20) }}
-{{ $slice := slice "c" "e" }}
-{{ index $map $slice }} → 20
-```
-
-## Example: load data from a path based on front matter parameters
+{{ $m := dict "a" 100 "b" 200 "c" (slice 10 20 30) }}
+{{ index $m "c" 1 }} → 20
-Assume you want to add a `location = ""` field to your front matter for every article written in `content/vacations/`. You want to use this field to populate information about the location at the bottom of the article in your `single.html` template. You also have a directory in `data/locations/` that looks like the following:
-
-```text
-data/
- └── locations/
- ├── abilene.toml
- ├── chicago.toml
- ├── oslo.toml
- └── provo.toml
+{{ $m := dict "a" 100 "b" 200 "c" (dict "d" 10 "e" 20) }}
+{{ index $m "c" "e" }} → 20
```
-Here is an example:
-
-{{< code-toggle file=data/locations/oslo >}}
-website = "https://www.oslo.kommune.no"
-pop_city = 658390
-pop_metro = 1717900
-{{< /code-toggle >}}
-
-The example we will use will be an article on Oslo, whose front matter should be set to exactly the same name as the corresponding file name in `data/locations/`:
-
-{{< code-toggle file=content/articles/oslo.md fm=true >}}
-title = "My Norwegian Vacation"
-location = "oslo"
-{{< /code-toggle >}}
-
-The content of `oslo.toml` can be accessed from your template using the following node path: `.Site.Data.locations.oslo`. However, the specific file you need is going to change according to the front matter.
-
-This is where the `index` function is needed. `index` takes 2 arguments in this use case:
-
-1. The node path
-2. A string corresponding to the desired data; e.g.&mdash;
+You may also use a slice of keys to access a nested value:
```go-html-template
-{{ index .Site.Data.locations "oslo" }}
+{{ $m := dict "a" 100 "b" 200 "c" (dict "d" 10 "e" 20) }}
+{{ $s := slice "c" "e" }}
+{{ index $m $s }} → 20
```
-The variable for `.Params.location` is a string and can therefore replace `oslo` in the example above:
+Use the `collections.Index` function to access a nested value when the key is variable. For example, these are equivalent:
```go-html-template
-{{ index .Site.Data.locations .Params.location }}
-=> map[website:https://www.oslo.kommune.no pop_city:658390 pop_metro:1717900]
-```
+{{ .Site.Params.foo }}
-Now the call will return the specific file according to the location specified in the content's front matter, but you will likely want to write specific properties to the template. You can do this by continuing down the node path via dot notation (`.`):
-
-```go-html-template
-{{ (index .Site.Data.locations .Params.location).pop_city }}
-=> 658390
+{{ $k := "foo" }}
+{{ index .Site.Params $k }}
```
diff --git a/content/en/functions/collections/KeyVals.md b/content/en/functions/collections/KeyVals.md
index 3d21ca6fd..6a2109e78 100644
--- a/content/en/functions/collections/KeyVals.md
+++ b/content/en/functions/collections/KeyVals.md
@@ -8,13 +8,13 @@ action:
related:
- methods/pages/Related
returnType: types.KeyValues
- signatures: [collections.KeyVals KEY VALUES...]
+ signatures: [collections.KeyVals KEY VALUE...]
aliases: [/functions/keyvals]
---
-The primary application for this function is the definition of the `namedSlices` parameter in the options map passed to the [`Related`] method on the `Pages` object.
+The primary application for this function is the definition of the `namedSlices` value in the options map passed to the [`Related`] method on the `Pages` object.
-[`Related`]: /methods/pages/related
+[`Related`]: /methods/pages/related/
See [related content](/content-management/related).
diff --git a/content/en/functions/collections/NewScratch.md b/content/en/functions/collections/NewScratch.md
index 96f85a8d0..cee20d754 100644
--- a/content/en/functions/collections/NewScratch.md
+++ b/content/en/functions/collections/NewScratch.md
@@ -15,8 +15,8 @@ action:
The `collections.NewScratch` function creates a locally scoped [scratch pad] to store and manipulate data. To create a scratch pad that is attached to a `Page` object, use the [`Scratch`] or [`Store`] method.
-[`Scratch`]: /methods/page/scratch
-[`Store`]: /methods/page/store
+[`Scratch`]: /methods/page/scratch/
+[`Store`]: /methods/page/store/
[scratch pad]: /getting-started/glossary/#scratch-pad
## Methods
diff --git a/content/en/functions/collections/Querify.md b/content/en/functions/collections/Querify.md
index ea0434fc5..07e27bd7e 100644
--- a/content/en/functions/collections/Querify.md
+++ b/content/en/functions/collections/Querify.md
@@ -1,6 +1,6 @@
---
title: collections.Querify
-description: Takes a set or slice of key-value pairs and returns a query string to be appended to URLs.
+description: Returns a URL query string composed of the given key-value pairs.
categories: []
keywords: []
action:
@@ -9,24 +9,29 @@ action:
- functions/go-template/urlquery.md
returnType: string
signatures:
- - collections.Querify VALUE [VALUE...]
- - collections.Querify COLLECTION
+ - collections.Querify [VALUE...]
aliases: [/functions/querify]
---
-`querify` takes a set or slice of key-value pairs and returns a [query string](https://en.wikipedia.org/wiki/Query_string) that can be appended to a URL.
+Specify the key-value pairs as individual arguments, or as a slice. The following are equivalent:
-The following examples create a link to a search results page on Google.
```go-html-template
-<a href="https://www.google.com?{{ (querify "q" "test" "page" 3) | safeURL }}">Search</a>
+{{ collections.Querify "a" 1 "b" 2 }}
+{{ collections.Querify (slice "a" 1 "b" 2) }}
+```
+
+To append a query string to a URL:
+
+```go-html-template
+{{ $qs := collections.Querify "a" 1 "b" 2 }}
+{{ $href := printf "https://example.org?%s" $qs }}
-{{ $qs := slice "q" "test" "page" 3 }}
-<a href="https://www.google.com?{{ (querify $qs) | safeURL }}">Search</a>
+<a href="{{ $href }}">Link</a>
```
-Both of these examples render the following HTML:
+Hugo renders this to:
```html
-<a href="https://www.google.com?page=3&q=test">Search</a>
+<a href="https://example.org?a=1&amp;b=2">Link</a>
```
diff --git a/content/en/functions/collections/Slice.md b/content/en/functions/collections/Slice.md
index 56c068d4b..385f9b658 100644
--- a/content/en/functions/collections/Slice.md
+++ b/content/en/functions/collections/Slice.md
@@ -1,6 +1,6 @@
---
title: collections.Slice
-description: Creates a slice of all passed arguments.
+description: Returns a slice composed of the given values.
categories: []
keywords: []
action:
@@ -8,7 +8,7 @@ action:
related:
- functions/collections/Dictionary
returnType: any
- signatures: [collections.Slice ITEM...]
+ signatures: ['collections.Slice [VALUE...]']
aliases: [/functions/slice]
---
@@ -16,3 +16,9 @@ aliases: [/functions/slice]
{{ $s := slice "a" "b" "c" }}
{{ $s }} → [a b c]
```
+
+To create an empty slice:
+
+```go-html-template
+{{ $s := slice }}
+```
diff --git a/content/en/functions/collections/Sort.md b/content/en/functions/collections/Sort.md
index 2277f883c..815260f20 100644
--- a/content/en/functions/collections/Sort.md
+++ b/content/en/functions/collections/Sort.md
@@ -144,7 +144,7 @@ After sorting:
{{% 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
+[sorting and grouping methods]: /methods/pages/
{{% /note %}}
In this contrived example, sort the site's regular pages by `.Type` in descending order:
diff --git a/content/en/functions/collections/Where.md b/content/en/functions/collections/Where.md
index f18ae507b..629d11eeb 100644
--- a/content/en/functions/collections/Where.md
+++ b/content/en/functions/collections/Where.md
@@ -12,7 +12,7 @@ toc: true
aliases: [/functions/where]
---
-The `where` function returns the given collection, removing elements that do not satisfy the comparison condition. The comparison condition is comprised of the `KEY`, `OPERATOR`, and `VALUE` arguments:
+The `where` function returns the given collection, removing elements that do not satisfy the comparison condition. The comparison condition is composed of the `KEY`, `OPERATOR`, and `VALUE` arguments:
```text
collections.Where COLLECTION KEY [OPERATOR] VALUE
@@ -204,10 +204,10 @@ 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
+[`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:
@@ -243,7 +243,7 @@ To return a collection of future events:
{{ $futureEvents := where $events "Params.eventDate" "gt" now }}
```
-When working with YAML or JSON, or quoted TOML values, custom dates are strings; you cannot compare them with `time.Time` values. String comparisons may be possible if the custom date layout is consistent from one page to the next. However, to be safe, filter the pages by ranging through the collection:
+When working with YAML or JSON, or quoted TOML values, custom dates are strings; you cannot compare them with `time.Time` values. String comparisons may be possible if the custom date layout is consistent from one page to the next. To be safe, filter the pages by ranging through the collection:
```go-html-template
{{ $events := where .Site.RegularPages "Type" "events" }}
@@ -288,7 +288,7 @@ 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
+[`MainSections`]: /methods/site/mainsections/
```go-html-template
{{ $pages := where .Site.RegularPages "Section" "in" .Site.MainSections }}
@@ -403,7 +403,7 @@ To exclude a page with an undefined field from a boolean _inequality_ test:
2. Create a collection using a nil comparison
3. Subtract the second collection from the first collection using the [`collections.Complement`] function.
-[`collections.Complement`]: /functions/collections/complement
+[`collections.Complement`]: /functions/collections/complement/
This template:
diff --git a/content/en/functions/compare/Default.md b/content/en/functions/compare/Default.md
index 1e6bd7968..bf859d51c 100644
--- a/content/en/functions/compare/Default.md
+++ b/content/en/functions/compare/Default.md
@@ -21,7 +21,7 @@ When the second argument is the boolean `false` value, the `default` function re
To set a default value based on truthiness, use the [`or`] operator instead.
-[`or`]: /functions/go-template/or
+[`or`]: /functions/go-template/or/
{{% /note %}}
The `default` function returns the second argument if set:
diff --git a/content/en/functions/compare/Eq.md b/content/en/functions/compare/Eq.md
index 49350e676..a877aeddf 100644
--- a/content/en/functions/compare/Eq.md
+++ b/content/en/functions/compare/Eq.md
@@ -25,3 +25,5 @@ aliases: [/functions/eq]
{{ eq 1 2 1 }} → true
{{ eq 1 2 2 }} → false
```
+
+You can also use the `compare.Eq` function to compare strings, boolean values, dates, slices, maps, and pages.
diff --git a/content/en/functions/compare/Ge.md b/content/en/functions/compare/Ge.md
index 479ecf990..ce1fd2302 100644
--- a/content/en/functions/compare/Ge.md
+++ b/content/en/functions/compare/Ge.md
@@ -30,3 +30,11 @@ aliases: [/functions/ge]
{{ ge 2 1 2 }} → true
{{ ge 2 2 1 }} → true
```
+
+Use the `compare.Ge` function to compare other data types as well:
+
+```go-html-template
+{{ ge "ab" "a" }} → true
+{{ ge time.Now (time.AsTime "1964-12-30") }} → true
+{{ ge true false }} → true
+```
diff --git a/content/en/functions/compare/Gt.md b/content/en/functions/compare/Gt.md
index 0af289ce2..9ff3b0c89 100644
--- a/content/en/functions/compare/Gt.md
+++ b/content/en/functions/compare/Gt.md
@@ -30,3 +30,11 @@ aliases: [/functions/gt]
{{ gt 2 1 2 }} → false
{{ gt 2 2 1 }} → false
```
+
+Use the `compare.Gt` function to compare other data types as well:
+
+```go-html-template
+{{ gt "ab" "a" }} → true
+{{ gt time.Now (time.AsTime "1964-12-30") }} → true
+{{ gt true false }} → true
+```
diff --git a/content/en/functions/compare/Le.md b/content/en/functions/compare/Le.md
index 319d376f6..a0fbed29d 100644
--- a/content/en/functions/compare/Le.md
+++ b/content/en/functions/compare/Le.md
@@ -30,3 +30,11 @@ aliases: [/functions/le]
{{ le 2 1 2 }} → false
{{ le 2 2 1 }} → false
```
+
+Use the `compare.Le` function to compare other data types as well:
+
+```go-html-template
+{{ le "ab" "a" }} → false
+{{ le time.Now (time.AsTime "1964-12-30") }} → false
+{{ le true false }} → false
+```
diff --git a/content/en/functions/compare/Lt.md b/content/en/functions/compare/Lt.md
index 3fe8f1d2c..b306a97b5 100644
--- a/content/en/functions/compare/Lt.md
+++ b/content/en/functions/compare/Lt.md
@@ -30,3 +30,11 @@ aliases: [/functions/lt]
{{ lt 2 1 2 }} → false
{{ lt 2 2 1 }} → false
```
+
+Use the `compare.Lt` function to compare other data types as well:
+
+```go-html-template
+{{ lt "ab" "a" }} → false
+{{ lt time.Now (time.AsTime "1964-12-30") }} → false
+{{ lt true false }} → false
+```
diff --git a/content/en/functions/compare/Ne.md b/content/en/functions/compare/Ne.md
index 2d9f826fc..dbe0a3898 100644
--- a/content/en/functions/compare/Ne.md
+++ b/content/en/functions/compare/Ne.md
@@ -25,3 +25,5 @@ aliases: [/functions/ne]
{{ ne 1 2 1 }} → false
{{ ne 1 2 2 }} → true
```
+
+You can also use the `compare.Ne` function to compare strings, boolean values, dates, slices, maps, and pages.
diff --git a/content/en/functions/data/GetCSV.md b/content/en/functions/data/GetCSV.md
index d61ea791d..c35d48f67 100644
--- a/content/en/functions/data/GetCSV.md
+++ b/content/en/functions/data/GetCSV.md
@@ -15,6 +15,18 @@ action:
toc: true
---
+{{% deprecated-in 0.123.0 %}}
+Instead, use [`transform.Unmarshal`] with a [global], [page], or [remote] resource.
+
+See the [remote data example].
+
+[`transform.Unmarshal`]: /functions/transform/unmarshal/
+[global]: /getting-started/glossary/#global-resource
+[page]: /getting-started/glossary/#page-resource
+[remote data example]: /functions/resources/getremote/#remote-data
+[remote]: /getting-started/glossary/#remote-resource
+{{% /deprecated-in %}}
+
Given the following directory structure:
```text
@@ -31,7 +43,7 @@ Access the data with either of the following:
```
{{% note %}}
-When working with local data, the filepath is relative to the working directory.
+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 %}}
@@ -81,7 +93,7 @@ my-project/
```
```go-html-template
-{{ $data := "" }}
+{{ $data := dict }}
{{ $p := "data/pets.csv" }}
{{ with resources.Get $p }}
{{ $opts := dict "delimiter" "," }}
@@ -105,7 +117,7 @@ my-project/
```
```go-html-template
-{{ $data := "" }}
+{{ $data := dict }}
{{ $p := "pets.csv" }}
{{ with .Resources.Get $p }}
{{ $opts := dict "delimiter" "," }}
@@ -120,7 +132,7 @@ my-project/
Consider using the [`resources.GetRemote`] function with [`transform.Unmarshal`] when accessing a remote resource to improve error handling and cache control.
```go-html-template
-{{ $data := "" }}
+{{ $data := dict }}
{{ $u := "https://example.org/pets.csv" }}
{{ with resources.GetRemote $u }}
{{ with .Err }}
@@ -134,7 +146,7 @@ Consider using the [`resources.GetRemote`] function with [`transform.Unmarshal`]
{{ end }}
```
-[`Resources.Get`]: methods/page/Resources
-[`resources.GetRemote`]: /functions/resources/getremote
-[`resources.Get`]: /functions/resources/get
-[`transform.Unmarshal`]: /functions/transform/unmarshal
+[`Resources.Get`]: /methods/page/resources/
+[`resources.GetRemote`]: /functions/resources/getremote/
+[`resources.Get`]: /functions/resources/get/
+[`transform.Unmarshal`]: /functions/transform/unmarshal/
diff --git a/content/en/functions/data/GetJSON.md b/content/en/functions/data/GetJSON.md
index 4db3c8988..348021226 100644
--- a/content/en/functions/data/GetJSON.md
+++ b/content/en/functions/data/GetJSON.md
@@ -15,6 +15,18 @@ action:
toc: true
---
+{{% deprecated-in 0.123.0 %}}
+Instead, use [`transform.Unmarshal`] with a [global], [page], or [remote] resource.
+
+See the [remote data example].
+
+[`transform.Unmarshal`]: /functions/transform/unmarshal/
+[global]: /getting-started/glossary/#global-resource
+[page]: /getting-started/glossary/#page-resource
+[remote data example]: /functions/resources/getremote/#remote-data
+[remote]: /getting-started/glossary/#remote-resource
+{{% /deprecated-in %}}
+
Given the following directory structure:
```text
@@ -31,7 +43,7 @@ Access the data with either of the following:
```
{{% note %}}
-When working with local data, the filepath is relative to the working directory.
+When working with local data, the file path is relative to the working directory.
{{% /note %}}
Access remote data with either of the following:
@@ -86,7 +98,7 @@ my-project/
```
```go-html-template
-{{ $data := "" }}
+{{ $data := dict }}
{{ $p := "data/books.json" }}
{{ with resources.Get $p }}
{{ $data = . | transform.Unmarshal }}
@@ -109,7 +121,7 @@ my-project/
```
```go-html-template
-{{ $data := "" }}
+{{ $data := dict }}
{{ $p := "books.json" }}
{{ with .Resources.Get $p }}
{{ $data = . | transform.Unmarshal }}
@@ -123,7 +135,7 @@ my-project/
Consider using the [`resources.GetRemote`] function with [`transform.Unmarshal`] when accessing a remote resource to improve error handling and cache control.
```go-html-template
-{{ $data := "" }}
+{{ $data := dict }}
{{ $u := "https://example.org/books.json" }}
{{ with resources.GetRemote $u }}
{{ with .Err }}
@@ -136,7 +148,7 @@ Consider using the [`resources.GetRemote`] function with [`transform.Unmarshal`]
{{ end }}
```
-[`Resources.Get`]: methods/page/Resources
-[`resources.GetRemote`]: /functions/resources/getremote
-[`resources.Get`]: /functions/resources/get
-[`transform.Unmarshal`]: /functions/transform/unmarshal
+[`Resources.Get`]: /methods/page/resources/
+[`resources.GetRemote`]: /functions/resources/getremote/
+[`resources.Get`]: /functions/resources/get/
+[`transform.Unmarshal`]: /functions/transform/unmarshal/
diff --git a/content/en/functions/debug/Dump.md b/content/en/functions/debug/Dump.md
index d3161605f..67b264bed 100644
--- a/content/en/functions/debug/Dump.md
+++ b/content/en/functions/debug/Dump.md
@@ -11,33 +11,22 @@ action:
---
```go-html-template
-{{ $data := "" }}
-{{ $p := "data/books.json" }}
-{{ with resources.Get $p }}
- {{ $opts := dict "delimiter" "," }}
- {{ $data = . | transform.Unmarshal $opts }}
-{{ else }}
- {{ errorf "Unable to get resource %q" $p }}
-{{ end }}
+<pre>{{ debug.Dump site.Data.books }}</pre>
```
-```go-html-template
-<pre>{{ debug.Dump $data }}</pre>
-```
-
-```text
-[]interface {}{
- map[string]interface {}{
+```json
+[
+ {
"author": "Victor Hugo",
- "rating": 5.0,
- "title": "Les Misérables",
+ "rating": 4,
+ "title": "The Hunchback of Notre Dame"
},
- map[string]interface {}{
+ {
"author": "Victor Hugo",
- "rating": 4.0,
- "title": "The Hunchback of Notre Dame",
- },
-}
+ "rating": 5,
+ "title": "Les Misérables"
+ }
+]
```
{{% note %}}
diff --git a/content/en/functions/debug/Timer.md b/content/en/functions/debug/Timer.md
index ae6c3188f..02ab63110 100644
--- a/content/en/functions/debug/Timer.md
+++ b/content/en/functions/debug/Timer.md
@@ -33,5 +33,5 @@ hugo --logLevel info
The results are displayed in the console at the end of the build. You can have as many timers as you want and if you don't stop them, they will be stopped at the end of build.
```text
-INFO timer: name TestSqrt total 12.429355ms
+INFO timer: name TestSqrt count 1002 duration 2.496017496s average 2.491035ms median 2.282291ms
```
diff --git a/content/en/functions/diagrams/Goat.md b/content/en/functions/diagrams/Goat.md
index 2b31d9824..69a099bb7 100644
--- a/content/en/functions/diagrams/Goat.md
+++ b/content/en/functions/diagrams/Goat.md
@@ -11,10 +11,10 @@ action:
toc: true
---
-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 `diagram.Goat` function converts ASCII art to an SVG diagram, returning a [GoAT] diagram object with the following methods:
[GoAT]: https://github.com/blampe/goat#readme
-[render hook]: https://gohugo.io/templates/render-hooks/
+[code block render hook]: /render-hooks/code-blocks/
Inner
: (`template.HTML`) Returns the SVG child elements without a wrapping `svg` element, allowing you to create your own wrapper.
@@ -30,9 +30,11 @@ Height
## GoAT Diagrams
-Hugo natively supports [GoAT] diagrams.
+Hugo natively supports [GoAT](https://github.com/bep/goat) diagrams with an [embedded code block render hook].
-This markdown:
+[embedded code block render hook]: {{% eturl render-codeblock-goat %}}
+
+This Markdown:
````
```goat
@@ -60,9 +62,7 @@ Which appears in your browser as:
'---' '-' '+' '+' '---'
```
-To customize rendering, override Hugo's [built-in code block render hook] for GoAT diagrams.
-
-[built-in code block render hook]: https://github.com/gohugoio/hugo/blob/master/tpl/tplimpl/embedded/templates/_default/_markup/render-codeblock-goat.html
+To customize rendering, override Hugo's [embedded code block render hook] for GoAT diagrams.
## Code block render hook
@@ -83,7 +83,7 @@ By way of example, let's create a code block render hook to render GoAT diagrams
</figure>
{{< /code >}}
-This markdown:
+This Markdown:
{{< code file=content/example.md lang=text >}}
```goat {class="foo" caption="Diagram 1: Example"}
diff --git a/content/en/functions/fmt/Errorf.md b/content/en/functions/fmt/Errorf.md
index bbdd62c53..93f546351 100644
--- a/content/en/functions/fmt/Errorf.md
+++ b/content/en/functions/fmt/Errorf.md
@@ -8,6 +8,7 @@ action:
related:
- functions/fmt/Erroridf
- functions/fmt/Warnf
+ - functions/fmt/Warnidf
returnType: string
signatures: ['fmt.Errorf FORMAT [INPUT]']
aliases: [/functions/errorf]
@@ -18,9 +19,9 @@ aliases: [/functions/errorf]
The `errorf` function evaluates the format string, then prints the result to the ERROR log and fails the build.
```go-html-template
-{{ errorf "The %q shortcode requires a src parameter. See %s" .Name .Position }}
+{{ errorf "The %q shortcode requires a src argument. See %s" .Name .Position }}
```
Use the [`erroridf`] function to allow optional suppression of specific errors.
-[`erroridf`]: /functions/fmt/erroridf
+[`erroridf`]: /functions/fmt/erroridf/
diff --git a/content/en/functions/fmt/Erroridf.md b/content/en/functions/fmt/Erroridf.md
index 9884f4935..f442f09bf 100644
--- a/content/en/functions/fmt/Erroridf.md
+++ b/content/en/functions/fmt/Erroridf.md
@@ -1,6 +1,6 @@
---
title: fmt.Erroridf
-description: Log a suppressable ERROR from a template.
+description: Log a suppressible ERROR from a template.
categories: []
keywords: []
action:
@@ -8,6 +8,7 @@ action:
related:
- functions/fmt/Errorf
- functions/fmt/Warnf
+ - functions/fmt/Warnidf
returnType: string
signatures: ['fmt.Erroridf ID FORMAT [INPUT]']
aliases: [/functions/erroridf]
@@ -15,7 +16,7 @@ aliases: [/functions/erroridf]
{{% include "functions/fmt/_common/fmt-layout.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 `ignoreErrors` array in your site configuration.
+The `erroridf` function evaluates the format string, then prints the result to the ERROR log and fails the build. Unlike the [`errorf`] function, you may suppress errors logged by the `erroridf` function by adding the message ID to the `ignoreLogs` array in your site configuration.
This template code:
@@ -28,13 +29,13 @@ Produces this console log:
```text
ERROR You should consider fixing this.
You can suppress this error by adding the following to your site configuration:
-ignoreErrors = ['error-42']
+ignoreLogs = ['error-42']
```
To suppress this message:
{{< code-toggle file=hugo >}}
-ignoreErrors = ["error-42"]
+ignoreLogs = ["error-42"]
{{< /code-toggle >}}
-[`errorf`]: /functions/fmt/errorf
+[`errorf`]: /functions/fmt/errorf/
diff --git a/content/en/functions/fmt/Warnf.md b/content/en/functions/fmt/Warnf.md
index 0a90251d3..f4fa22474 100644
--- a/content/en/functions/fmt/Warnf.md
+++ b/content/en/functions/fmt/Warnf.md
@@ -8,6 +8,7 @@ action:
related:
- functions/fmt/Errorf
- functions/fmt/Erroridf
+ - functions/fmt/Warnidf
returnType: string
signatures: ['fmt.Warnf FORMAT [INPUT]']
aliases: [/functions/warnf]
@@ -21,6 +22,8 @@ The `warnf` function evaluates the format string, then prints the result to the
{{ warnf "The %q shortcode was unable to find %s. See %s" .Name $file .Position }}
```
+Use the [`warnidf`] function to allow optional suppression of specific warnings.
+
To prevent suppression of duplicate messages when using `warnf` for debugging, make each message unique with the [`math.Counter`] function. For example:
@@ -30,4 +33,6 @@ To prevent suppression of duplicate messages when using `warnf` for debugging, m
{{ end }}
```
-[`math.Counter`]: /functions/math/counter
+[`math.Counter`]: /functions/math/counter/
+
+[`warnidf`]: /functions/fmt/warnidf/
diff --git a/content/en/functions/fmt/Warnidf.md b/content/en/functions/fmt/Warnidf.md
new file mode 100644
index 000000000..cbe75816e
--- /dev/null
+++ b/content/en/functions/fmt/Warnidf.md
@@ -0,0 +1,43 @@
+---
+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]']
+aliases: [/functions/warnidf]
+---
+
+{{< new-in 0.123.0 >}}
+
+{{% include "functions/fmt/_common/fmt-layout.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.
+
+This template code:
+
+```go-html-template
+{{ warnidf "warning-42" "You should consider fixing this." }}
+```
+
+Produces this console log:
+
+```text
+WARN You should consider fixing this.
+You can suppress this warning by adding the following to your site configuration:
+ignoreLogs = ['warning-42']
+```
+
+To suppress this message:
+
+{{< code-toggle file=hugo >}}
+ignoreLogs = ["warning-42"]
+{{< /code-toggle >}}
+
+[`warnf`]: /functions/fmt/warnf/
diff --git a/content/en/functions/fmt/_common/_index.md b/content/en/functions/fmt/_common/_index.md
index 47d5812fb..4328d4d14 100644
--- a/content/en/functions/fmt/_common/_index.md
+++ b/content/en/functions/fmt/_common/_index.md
@@ -7,7 +7,7 @@ cascade:
---
<!--
-Files within this headless branch bundle are markdown snippets. Each file must contain front matter delimiters, though front matter fields are not required.
+Files within this headless branch bundle are Markdown snippets. Each file must contain front matter delimiters, though front matter fields are not required.
Include the rendered content using the "include" shortcode.
-->
diff --git a/content/en/functions/global/page.md b/content/en/functions/global/page.md
index 6c96b747e..b7a8161dc 100644
--- a/content/en/functions/global/page.md
+++ b/content/en/functions/global/page.md
@@ -35,7 +35,7 @@ Do not use the global `page` function in shortcodes, partials called by shortcod
## 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 `.` variable 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], [partial], or [render hook], it is not always practical or possible to access the `Page` object.
@@ -101,8 +101,8 @@ 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/
+[`partialCached`]: /functions/partials/includecached/
[content view]: /getting-started/glossary/#content-view
[partial]: /getting-started/glossary/#partial
[render hook]: /getting-started/glossary/#render-hook
diff --git a/content/en/functions/global/site.md b/content/en/functions/global/site.md
index a097e471b..a4879fee0 100644
--- a/content/en/functions/global/site.md
+++ b/content/en/functions/global/site.md
@@ -12,17 +12,19 @@ action:
aliases: [/functions/site]
---
-At the top level of a template that receives the `Site` object in context, these are equivalent:
+Use the `site` function to return the `Site` object regardless of current context.
```go-html-template
-{{ .Site.Params.foo }}
{{ site.Params.foo }}
```
-When the `Site` object is not in context, use the global `site` function:
+When the `Site` object is in context you can use the `Site` property:
```go-html-template
-{{ site.Params.foo }}
+<!-- current context -->
+{{ .Site.Params.foo }}
+<!-- template context -->
+{{ $.Site.Params.foo }}
```
{{% note %}}
diff --git a/content/en/functions/go-template/_common/_index.md b/content/en/functions/go-template/_common/_index.md
index 47d5812fb..4328d4d14 100644
--- a/content/en/functions/go-template/_common/_index.md
+++ b/content/en/functions/go-template/_common/_index.md
@@ -7,7 +7,7 @@ cascade:
---
<!--
-Files within this headless branch bundle are markdown snippets. Each file must contain front matter delimiters, though front matter fields are not required.
+Files within this headless branch bundle are Markdown snippets. Each file must contain front matter delimiters, though front matter fields are not required.
Include the rendered content using the "include" shortcode.
-->
diff --git a/content/en/functions/go-template/define.md b/content/en/functions/go-template/define.md
index 4d09c14f3..f15dd6ff0 100644
--- a/content/en/functions/go-template/define.md
+++ b/content/en/functions/go-template/define.md
@@ -48,8 +48,8 @@ Use with the [`template`] function:
{{ end }}
```
-[`block`]: /functions/go-template/block
-[`template`]: /functions/go-template/block
+[`block`]: /functions/go-template/block/
+[`template`]: /functions/go-template/block/
[`partial`]: /functions/partials/include/
{{% include "functions/go-template/_common/text-template.md" %}}
diff --git a/content/en/functions/go-template/else.md b/content/en/functions/go-template/else.md
index ccb8b722c..698998bd8 100644
--- a/content/en/functions/go-template/else.md
+++ b/content/en/functions/go-template/else.md
@@ -64,6 +64,6 @@ Use `else if` to check multiple conditions.
{{% include "functions/go-template/_common/text-template.md" %}}
-[`if`]: /functions/go-template/if
-[`with`]: /functions/go-template/with
-[`range`]: /functions/go-template/range
+[`if`]: /functions/go-template/if/
+[`with`]: /functions/go-template/with/
+[`range`]: /functions/go-template/range/
diff --git a/content/en/functions/go-template/end.md b/content/en/functions/go-template/end.md
index 07d004de5..6fb5bbfd6 100644
--- a/content/en/functions/go-template/end.md
+++ b/content/en/functions/go-template/end.md
@@ -58,8 +58,8 @@ Use with the [`define`] statement:
{{% include "functions/go-template/_common/text-template.md" %}}
-[`block`]: /functions/go-template/block
-[`define`]: /functions/go-template/define
-[`if`]: /functions/go-template/if
-[`range`]: /functions/go-template/range
-[`with`]: /functions/go-template/with
+[`block`]: /functions/go-template/block/
+[`define`]: /functions/go-template/define/
+[`if`]: /functions/go-template/if/
+[`range`]: /functions/go-template/range/
+[`with`]: /functions/go-template/with/
diff --git a/content/en/functions/go-template/if.md b/content/en/functions/go-template/if.md
index e63c382e1..19c887f25 100644
--- a/content/en/functions/go-template/if.md
+++ b/content/en/functions/go-template/if.md
@@ -51,4 +51,4 @@ Use `else if` to check multiple conditions.
{{% include "functions/go-template/_common/text-template.md" %}}
-[`else`]: /functions/go-template/else
+[`else`]: /functions/go-template/else/
diff --git a/content/en/functions/go-template/range.md b/content/en/functions/go-template/range.md
index e2f401371..dff3eed72 100644
--- a/content/en/functions/go-template/range.md
+++ b/content/en/functions/go-template/range.md
@@ -75,7 +75,7 @@ This template will render the page title three times:
Gaining a thorough understanding of context is critical for anyone writing template code.
{{% /note %}}
-[`seq`]: functions/collections/seq/
+[`seq`]: /functions/collections/seq/
[context]: /getting-started/glossary/#context
## Array or slice of scalars
@@ -194,6 +194,6 @@ Unlike ranging over an array or slice, Hugo sorts by key when ranging over a map
{{% include "functions/go-template/_common/text-template.md" %}}
-[`else`]: /functions/go-template/else
-[`break`]: /functions/go-template/break
-[`continue`]: /functions/go-template/continue
+[`else`]: /functions/go-template/else/
+[`break`]: /functions/go-template/break/
+[`continue`]: /functions/go-template/continue/
diff --git a/content/en/functions/go-template/return.md b/content/en/functions/go-template/return.md
index 2a166c718..e09522a58 100644
--- a/content/en/functions/go-template/return.md
+++ b/content/en/functions/go-template/return.md
@@ -80,7 +80,7 @@ See additional examples in the [partial templates] section.
## Usage
{{% note %}}
-Unlike `return` statements in other languages, Hugo executes the first occurrence of the `return` statement regardless of its position within logical blocks
+Unlike `return` statements in other languages, Hugo executes the first occurrence of the `return` statement regardless of its position within logical blocks.
{{% /note %}}
A partial that returns a value must contain only one `return` statement, placed at the end of the template.
diff --git a/content/en/functions/go-template/template.md b/content/en/functions/go-template/template.md
index a78ec5c65..687d8b0c8 100644
--- a/content/en/functions/go-template/template.md
+++ b/content/en/functions/go-template/template.md
@@ -13,7 +13,7 @@ action:
signatures: ['template NAME [CONTEXT]']
---
-Use the `template` function to execute [internal templates]. For example:
+Use the `template` function to execute [embedded templates]. For example:
```go-html-template
{{ range (.Paginate .Pages).Pages }}
@@ -46,4 +46,4 @@ The example above can be rewritten using an [inline partial] template:
[`partial`]: /functions/partials/include/
[inline partial]: /templates/partials/#inline-partials
-[internal templates]: /templates/internal
+[embedded templates]: /templates/embedded/
diff --git a/content/en/functions/go-template/with.md b/content/en/functions/go-template/with.md
index 0f3255b1a..3a73d54bb 100644
--- a/content/en/functions/go-template/with.md
+++ b/content/en/functions/go-template/with.md
@@ -84,4 +84,4 @@ Gaining a thorough understanding of context is critical for anyone writing templ
{{% include "functions/go-template/_common/text-template.md" %}}
-[`else`]: /functions/go-template/else
+[`else`]: /functions/go-template/else/
diff --git a/content/en/functions/hugo/Generator.md b/content/en/functions/hugo/Generator.md
index 907c37681..3bf74fd61 100644
--- a/content/en/functions/hugo/Generator.md
+++ b/content/en/functions/hugo/Generator.md
@@ -11,5 +11,5 @@ action:
---
```go-html-template
-{{ hugo.Generator }} → <meta name="generator" content="Hugo 0.122.0">
+{{ hugo.Generator }} → <meta name="generator" content="Hugo 0.126.0">
```
diff --git a/content/en/functions/hugo/IsMultihost.md b/content/en/functions/hugo/IsMultihost.md
new file mode 100644
index 000000000..2b582636b
--- /dev/null
+++ b/content/en/functions/hugo/IsMultihost.md
@@ -0,0 +1,40 @@
+---
+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]
+---
+
+{{< new-in v0.124.0 >}}
+
+Site configuration:
+
+{{< code-toggle file=hugo >}}
+defaultContentLanguage = 'de'
+defaultContentLanguageInSubdir = true
+[languages]
+ [languages.de]
+ baseURL = 'https://de.example.org/'
+ languageCode = 'de-DE'
+ languageName = 'Deutsch'
+ title = 'Projekt Dokumentation'
+ weight = 1
+ [languages.en]
+ baseURL = 'https://en.example.org/'
+ languageCode = 'en-US'
+ languageName = 'English'
+ title = 'Project Documentation'
+ weight = 2
+{{< /code-toggle >}}
+
+Template:
+
+```go-html-template
+{{ hugo.IsMultihost }} → true
+```
diff --git a/content/en/functions/hugo/IsMultilingual.md b/content/en/functions/hugo/IsMultilingual.md
new file mode 100644
index 000000000..e436ab160
--- /dev/null
+++ b/content/en/functions/hugo/IsMultilingual.md
@@ -0,0 +1,37 @@
+---
+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]
+---
+
+{{< new-in v0.124.0 >}}
+
+Site configuration:
+
+{{< code-toggle file=hugo >}}
+defaultContentLanguage = 'de'
+defaultContentLanguageInSubdir = true
+[languages]
+ [languages.de]
+ languageCode = 'de-DE'
+ languageName = 'Deutsch'
+ title = 'Projekt Dokumentation'
+ weight = 1
+ [languages.en]
+ languageCode = 'en-US'
+ languageName = 'English'
+ title = 'Project Documentation'
+ weight = 2
+{{< /code-toggle >}}
+
+Template:
+
+```go-html-template
+{{ hugo.IsMultilingual }} → true
+```
diff --git a/content/en/functions/hugo/Version.md b/content/en/functions/hugo/Version.md
index 5a312e81a..e83953645 100644
--- a/content/en/functions/hugo/Version.md
+++ b/content/en/functions/hugo/Version.md
@@ -11,5 +11,5 @@ action:
---
```go-html-template
-{{ hugo.Version }} → 0.122.0
+{{ hugo.Version }} → 0.126.0
```
diff --git a/content/en/functions/hugo/WorkingDir.md b/content/en/functions/hugo/WorkingDir.md
index ac3835ea8..6a838a865 100644
--- a/content/en/functions/hugo/WorkingDir.md
+++ b/content/en/functions/hugo/WorkingDir.md
@@ -13,3 +13,5 @@ action:
```go-html-template
{{ hugo.WorkingDir }} → /home/user/projects/my-hugo-site
```
+
+{{< new-in 0.112.0 >}}
diff --git a/content/en/functions/images/Config.md b/content/en/functions/images/Config.md
index 0a4d225bc..89c6ad604 100644
--- a/content/en/functions/images/Config.md
+++ b/content/en/functions/images/Config.md
@@ -27,10 +27,10 @@ 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], [page], and [remote] resources. See the [image processing] section for details.
-[`Width`]: /methods/resource/width
-[`Height`]: /methods/resource/height
+[`Width`]: /methods/resource/width/
+[`Height`]: /methods/resource/height/
[global]: /getting-started/glossary/#global-resource
-[image processing]: /content-management/image-processing
+[image processing]: /content-management/image-processing/
[page]: /getting-started/glossary/#page-resource
[remote]: /getting-started/glossary/#remote-resource
{{% /note %}}
diff --git a/content/en/functions/images/Dither.md b/content/en/functions/images/Dither.md
new file mode 100644
index 000000000..7193ba847
--- /dev/null
+++ b/content/en/functions/images/Dither.md
@@ -0,0 +1,162 @@
+---
+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
+---
+
+{{< new-in 0.123.0 >}}
+
+## Options
+
+colors
+: (`string array`) A slice of two or more colors that make up the dithering palette, each expressed as an RGB or RGBA [hexadecimal] value, with or without a leading hash mark. The default values are opaque black (`000000ff`) and opaque white (`ffffffff`).
+
+[hexadecimal]: https://developer.mozilla.org/en-US/docs/Web/CSS/hex-color
+
+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`.
+
+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`.
+
+## Usage
+
+Create the options map:
+
+```go-html-template
+{{ $opts := dict
+ "colors" (slice "222222" "808080" "dddddd")
+ "method" "ClusteredDot4x4"
+ "strength" 0.85
+}}
+```
+
+Create the filter:
+
+```go-html-template
+{{ $filter := images.Dither $opts }}
+```
+
+Or create the filter using the default settings:
+
+```go-html-template
+{{ $filter := images.Dither }}
+```
+
+{{% include "functions/images/_common/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
+
+Error diffusion dithering methods:
+
+- Atkinson
+- Burkes
+- FalseFloydSteinberg
+- FloydSteinberg
+- JarvisJudiceNinke
+- Sierra
+- Sierra2
+- Sierra2_4A
+- Sierra3
+- SierraLite
+- Simple2D
+- StevenPigeon
+- Stucki
+- TwoRowSierra
+
+Ordered dithering methods:
+
+- ClusteredDot4x4
+- ClusteredDot6x6
+- ClusteredDot6x6_2
+- ClusteredDot6x6_3
+- ClusteredDot8x8
+- ClusteredDotDiagonal16x16
+- ClusteredDotDiagonal6x6
+- ClusteredDotDiagonal8x8
+- ClusteredDotDiagonal8x8_2
+- ClusteredDotDiagonal8x8_3
+- ClusteredDotHorizontalLine
+- ClusteredDotSpiral5x5
+- ClusteredDotVerticalLine
+- Horizontal3x5
+- Vertical5x3
+
+## Example
+
+This example uses the default dithering options.
+
+{{< img
+ src="images/examples/zion-national-park.jpg"
+ alt="Zion National Park"
+ filter="Dither"
+ filterArgs=""
+ example=true
+>}}
+
+## Recommendations
+
+Regardless of dithering method, do both of the following to obtain the best results:
+
+1. Scale the image _before_ dithering
+2. Output the image to a lossless format such as GIF or PNG
+
+The example below does both of these, and it sets the dithering palette to the three most dominant colors in the image.
+
+
+```go-html-template
+{{ with resources.Get "original.jpg" }}
+ {{ $opts := dict
+ "method" "ClusteredDotSpiral5x5"
+ "colors" (first 3 .Colors)
+ }}
+ {{ $filters := slice
+ (images.Process "resize 800x")
+ (images.Dither $opts)
+ (images.Process "png")
+ }}
+ {{ with . | images.Filter $filters }}
+ <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
+ {{ end }}
+{{ end }}
+```
+
+For best results, if the dithering palette is grayscale, convert the image to grayscale before dithering.
+
+```go-html-template
+{{ $opts := dict "colors" (slice "222" "808080" "ddd") }}
+{{ $filters := slice
+ (images.Process "resize 800x")
+ (images.Grayscale)
+ (images.Dither $opts)
+ (images.Process "png")
+}}
+{{ with images.Filter $filters . }}
+ <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
+{{ end }}
+```
+
+The example above:
+
+1. Resizes the image to be 800 px wide
+2. Converts the image to grayscale
+3. Dithers the image using the default (`FloydSteinberg`) dithering method with a grayscale palette
+4. Converts the image to the PNG format
diff --git a/content/en/functions/images/Filter.md b/content/en/functions/images/Filter.md
index 450a64814..2961d7f47 100644
--- a/content/en/functions/images/Filter.md
+++ b/content/en/functions/images/Filter.md
@@ -40,7 +40,7 @@ To apply two or more filters, executing from left to right:
You can also apply image filters using the [`Filter`] method on a `Resource` object.
-[`Filter`]: /methods/resource/filter
+[`Filter`]: /methods/resource/filter/
## Example
diff --git a/content/en/functions/images/Padding.md b/content/en/functions/images/Padding.md
index 139626596..90cb6a74d 100644
--- a/content/en/functions/images/Padding.md
+++ b/content/en/functions/images/Padding.md
@@ -32,7 +32,7 @@ Create the filter:
Combine with the [`Colors`] method to create a border with one of the image's most dominant colors:
-[`Colors`]: /methods/resource/colors
+[`Colors`]: /methods/resource/colors/
```go-html-template
{{ with resources.Get "images/original.jpg" }}
diff --git a/content/en/functions/images/Process.md b/content/en/functions/images/Process.md
index a5e4d88dd..e562f7fbf 100644
--- a/content/en/functions/images/Process.md
+++ b/content/en/functions/images/Process.md
@@ -18,7 +18,7 @@ toc: true
This filter has the same options as the [`Process`] method on a `Resource` object, but using it as a filter may be more effective if you need to apply multiple filters to an image.
-[`Process`]: /methods/resource/process
+[`Process`]: /methods/resource/process/
The process specification is a space-delimited, case-insensitive list of one or more of the following in any sequence:
diff --git a/content/en/functions/images/UnsharpMask.md b/content/en/functions/images/UnsharpMask.md
index 57a74a54a..9ea58f2b6 100644
--- a/content/en/functions/images/UnsharpMask.md
+++ b/content/en/functions/images/UnsharpMask.md
@@ -13,11 +13,11 @@ action:
toc: true
---
-The sigma parameter 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.
+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.
-The amount parameter controls how much darker and how much lighter the edge borders become. Typically between 0.5 and 1.5.
+The amount argument controls how much darker and how much lighter the edge borders become. Typically between 0.5 and 1.5.
-The threshold parameter controls the minimum brightness change that will be sharpened. Typically between 0 and 0.05.
+The threshold argument controls the minimum brightness change that will be sharpened. Typically between 0 and 0.05.
## Usage
diff --git a/content/en/functions/images/_common/_index.md b/content/en/functions/images/_common/_index.md
index 47d5812fb..4328d4d14 100644
--- a/content/en/functions/images/_common/_index.md
+++ b/content/en/functions/images/_common/_index.md
@@ -7,7 +7,7 @@ cascade:
---
<!--
-Files within this headless branch bundle are markdown snippets. Each file must contain front matter delimiters, though front matter fields are not required.
+Files within this headless branch bundle are Markdown snippets. Each file must contain front matter delimiters, though front matter fields are not required.
Include the rendered content using the "include" shortcode.
-->
diff --git a/content/en/functions/images/_common/apply-image-filter.md b/content/en/functions/images/_common/apply-image-filter.md
index acd3a733d..15eddb485 100644
--- a/content/en/functions/images/_common/apply-image-filter.md
+++ b/content/en/functions/images/_common/apply-image-filter.md
@@ -4,7 +4,7 @@
Apply the filter using the [`images.Filter`] function:
-[`images.Filter`]: /functions/images/filter
+[`images.Filter`]: /functions/images/filter/
```go-html-template
{{ with resources.Get "images/original.jpg" }}
@@ -16,7 +16,7 @@ Apply the filter using the [`images.Filter`] function:
You can also apply the filter using the [`Filter`] method on a `Resource` object:
-[`Filter`]: methods/resource/filter
+[`Filter`]: /methods/resource/filter/
```go-html-template
{{ with resources.Get "images/original.jpg" }}
diff --git a/content/en/functions/inflect/Singularize.md b/content/en/functions/inflect/Singularize.md
index 29b543257..d2a8572f6 100644
--- a/content/en/functions/inflect/Singularize.md
+++ b/content/en/functions/inflect/Singularize.md
@@ -16,5 +16,3 @@ aliases: [/functions/singularize]
```go-html-template
{{ "cats" | singularize }} → cat
```
-
-See also the `.Data.Singular` [taxonomy variable](/variables/taxonomy/) for singularizing taxonomy names.
diff --git a/content/en/functions/js/Build.md b/content/en/functions/js/Build.md
index 835785486..7a3cdc43f 100644
--- a/content/en/functions/js/Build.md
+++ b/content/en/functions/js/Build.md
@@ -111,6 +111,29 @@ format
sourceMap
: (`string`) Whether to generate `inline` or `external` source maps from esbuild. External source maps will be written to the target with the output file name + ".map". Input source maps can be read from js.Build and node modules and combined into the output source maps. By default, source maps are not created.
+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(<App />, container);
+```
+
### Import JS code from /assets
`js.Build` has full support for the virtual union file system in [Hugo Modules](/hugo-modules/). You can see some simple examples in this [test project](https://github.com/gohugoio/hugoTestProjectJSModImports), but in short this means that you can do this:
diff --git a/content/en/functions/lang/FormatNumberCustom.md b/content/en/functions/lang/FormatNumberCustom.md
index 0b72f4983..5b24aa2c1 100644
--- a/content/en/functions/lang/FormatNumberCustom.md
+++ b/content/en/functions/lang/FormatNumberCustom.md
@@ -31,4 +31,4 @@ For a simpler function that adapts to the current language, see [`lang.FormatNum
{{% include "functions/_common/locales.md" %}}
-[`lang.FormatNumber`]: /functions/lang/formatnumber
+[`lang.FormatNumber`]: /functions/lang/formatnumber/
diff --git a/content/en/functions/math/Counter.md b/content/en/functions/math/Counter.md
index 7f53bdd0c..457806b8e 100644
--- a/content/en/functions/math/Counter.md
+++ b/content/en/functions/math/Counter.md
@@ -27,8 +27,8 @@ 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
+[`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.
diff --git a/content/en/functions/os/Getenv.md b/content/en/functions/os/Getenv.md
index 084d498ce..2b7a08881 100644
--- a/content/en/functions/os/Getenv.md
+++ b/content/en/functions/os/Getenv.md
@@ -32,7 +32,7 @@ getenv = ['^HUGO_', '^CI$', '^USER$', '^HOME$']
Read more about Hugo's [security policy].
-[security policy]: /about/security-model/#security-policy
+[security policy]: /about/security/#security-policy
## Examples
diff --git a/content/en/functions/partials/Include.md b/content/en/functions/partials/Include.md
index e08b32fd1..6da7e33bc 100644
--- a/content/en/functions/partials/Include.md
+++ b/content/en/functions/partials/Include.md
@@ -17,7 +17,7 @@ aliases: [/functions/partial]
Without a [`return`] statement, the `partial` function returns a string of type `template.HTML`. With a `return` statement, the `partial` function can return any data type.
-[`return`]: /functions/go-template/return
+[`return`]: /functions/go-template/return/
In this example we have three partial templates:
@@ -48,21 +48,24 @@ The "footer" partial renders the site footer. In this contrived example, the foo
{{ partial "breadcrumbs.html" }}
```
-You can pass anything in context: a page, a page collection, a scalar value, a slice, or a map. For example:
+You can pass anything in context: a page, a page collection, a scalar value, a slice, or a map. In this example we pass the current page and three scalar values:
```go-html-template
-{{ $student := dict
+{{ $ctx := dict
+ "page" .
"name" "John Doe"
"major" "Finance"
"gpa" 4.0
}}
-{{ partial "render-student-info.html" $student }}
+{{ partial "render-student-info.html" $ctx }}
```
Then, within the partial template:
```go-html-template
-<p>{{ .name }} is majoring in {{ .major }}. Their grade point average is {{ .gpa }}.</p>
+<p>{{ .name }} is majoring in {{ .major }}.</p>
+<p>Their grade point average is {{ .gpa }}.</p>
+<p>See <a href="{{ .page.RelPermalink }}">details.</a></p>
```
To return a value from a partial template, it must contain only one `return` statement, placed at the end of the template:
@@ -79,7 +82,7 @@ To return a value from a partial template, it must contain only one `return` sta
See&nbsp;[details][`return`].
-[`return`]: /functions/go-template/return
+[`return`]: /functions/go-template/return/
[breadcrumb navigation]: /content-management/sections/#ancestors-and-descendants
-[details]: /functions/go-template/return
+[details]: /functions/go-template/return/
diff --git a/content/en/functions/partials/IncludeCached.md b/content/en/functions/partials/IncludeCached.md
index 66ef4a6ac..8b57c3399 100644
--- a/content/en/functions/partials/IncludeCached.md
+++ b/content/en/functions/partials/IncludeCached.md
@@ -62,4 +62,4 @@ To return a value from a partial template, it must contain only one `return` sta
See&nbsp;[details][`return`].
-[`return`]: /functions/go-template/return
+[`return`]: /functions/go-template/return/
diff --git a/content/en/functions/resources/ByType.md b/content/en/functions/resources/ByType.md
index a5df3befb..bc5cca533 100644
--- a/content/en/functions/resources/ByType.md
+++ b/content/en/functions/resources/ByType.md
@@ -28,7 +28,7 @@ This function operates on global resources. A global resource is a file within t
For page resources, use the [`Resources.ByType`] method on the Page object.
-[`Resources.ByType`]: /methods/page/resources
+[`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 809ee83d0..40577f47d 100644
--- a/content/en/functions/resources/Concat.md
+++ b/content/en/functions/resources/Concat.md
@@ -15,9 +15,9 @@ The `resources.Concat` function returns a concatenated slice of resources, cachi
Hugo publishes the resource to the target path when you call its [`Publish`], [`Permalink`], or [`RelPermalink`] methods.
[media type]: https://en.wikipedia.org/wiki/Media_type
-[`publish`]: /methods/resource/publish
-[`permalink`]: /methods/resource/permalink
-[`relpermalink`]: /methods/resource/relpermalink
+[`publish`]: /methods/resource/publish/
+[`permalink`]: /methods/resource/permalink/
+[`relpermalink`]: /methods/resource/relpermalink/
```go-html-template
{{ $plugins := resources.Get "js/plugins.js" }}
diff --git a/content/en/functions/resources/Copy.md b/content/en/functions/resources/Copy.md
index f8e962aee..e25f91313 100644
--- a/content/en/functions/resources/Copy.md
+++ b/content/en/functions/resources/Copy.md
@@ -25,8 +25,6 @@ The relative URL of the new published resource will be:
/img/new-image-name.jpg
```
-The target path must be different than the source path, as shown in the example above.
-
{{% note %}}
Use the `resources.Copy` function with global, page, and remote resources.
{{% /note %}}
diff --git a/content/en/functions/resources/ExecuteAsTemplate.md b/content/en/functions/resources/ExecuteAsTemplate.md
index 5f7e58413..381647f7b 100644
--- a/content/en/functions/resources/ExecuteAsTemplate.md
+++ b/content/en/functions/resources/ExecuteAsTemplate.md
@@ -15,9 +15,9 @@ The `resources.ExecuteAsTemplate` function returns a resource created from a Go
Hugo publishes the resource to the target path when you call its [`Publish`], [`Permalink`], or [`RelPermalink`] methods.
-[`publish`]: /methods/resource/publish
-[`permalink`]: /methods/resource/permalink
-[`relpermalink`]: /methods/resource/relpermalink
+[`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:
diff --git a/content/en/functions/resources/FromString.md b/content/en/functions/resources/FromString.md
index d559058c3..1ab3f3200 100644
--- a/content/en/functions/resources/FromString.md
+++ b/content/en/functions/resources/FromString.md
@@ -15,17 +15,17 @@ The `resources.FromString` function returns a resource created from a string, ca
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
+[`publish`]: /methods/resource/publish/
+[`permalink`]: /methods/resource/permalink/
+[`relpermalink`]: /methods/resource/relpermalink/
Let's say you need to publish a file named "site.json" in the root of your public directory, containing the build date, the Hugo version used to build the site, and the date that the content was last modified. For example:
```json
{
- "build_date": "2023-10-03T10:50:40-07:00",
- "hugo_version": "0.122.0",
- "last_modified": "2023-10-02T15:21:27-07:00"
+ "build_date": "2024-02-19T12:27:05-08:00",
+ "hugo_version": "0.126.0",
+ "last_modified": "2024-02-19T12:01:42-08:00"
}
```
@@ -37,7 +37,7 @@ Place this in your baseof.html template:
{{ $m := dict
"hugo_version" hugo.Version
"build_date" (now.Format $rfc3339)
- "last_modified" (site.LastChange.Format $rfc3339)
+ "last_modified" (site.Lastmod.Format $rfc3339)
}}
{{ $json := jsonify $m }}
{{ $r := resources.FromString "site.json" $json }}
@@ -47,7 +47,7 @@ Place this in your baseof.html template:
The example above:
-1. Creates a map with the relevant key/value pairs using the [`dict`] function
+1. Creates a map with the relevant key-value pairs using the [`dict`] function
2. Encodes the map as a JSON string using the [`jsonify`] function
3. Creates a resource from the JSON string using the `resources.FromString` function
4. Publishes the file to the root of the public directory using the resource's `.Publish` method
@@ -61,7 +61,7 @@ Combine `resources.FromString` with [`resources.ExecuteAsTemplate`] if your stri
{{ $m := dict
"hugo_version" hugo.Version
"build_date" (now.Format $rfc3339)
- "last_modified" (site.LastChange.Format $rfc3339)
+ "last_modified" (site.Lastmod.Format $rfc3339)
}}
{{ $json := jsonify $m }}
`
@@ -72,6 +72,6 @@ Combine `resources.FromString` with [`resources.ExecuteAsTemplate`] if your stri
{{ end }}
```
-[`dict`]: /functions/collections/dictionary
-[`jsonify`]: /functions/encoding/jsonify
-[`resources.ExecuteAsTemplate`]: /functions/resources/executeastemplate
+[`dict`]: /functions/collections/dictionary/
+[`jsonify`]: /functions/encoding/jsonify/
+[`resources.ExecuteAsTemplate`]: /functions/resources/executeastemplate/
diff --git a/content/en/functions/resources/Get.md b/content/en/functions/resources/Get.md
index a8b75d52b..3ae291c42 100644
--- a/content/en/functions/resources/Get.md
+++ b/content/en/functions/resources/Get.md
@@ -26,5 +26,5 @@ This function operates on global resources. A global resource is a file within t
For page resources, use the [`Resources.Get`] method on the Page object.
-[`Resources.Get`]: /methods/page/resources
+[`Resources.Get`]: /methods/page/resources/
{{% /note %}}
diff --git a/content/en/functions/resources/GetMatch.md b/content/en/functions/resources/GetMatch.md
index fde26c09d..aa2f1ccbb 100644
--- a/content/en/functions/resources/GetMatch.md
+++ b/content/en/functions/resources/GetMatch.md
@@ -26,7 +26,7 @@ This function operates on global resources. A global resource is a file within t
For page resources, use the [`Resources.GetMatch`] method on the Page object.
-[`Resources.GetMatch`]: /methods/page/resources
+[`Resources.GetMatch`]: /methods/page/resources/
{{% /note %}}
Hugo determines a match using a case-insensitive [glob pattern].
diff --git a/content/en/functions/resources/GetRemote.md b/content/en/functions/resources/GetRemote.md
index 4a6540572..556bfbeca 100644
--- a/content/en/functions/resources/GetRemote.md
+++ b/content/en/functions/resources/GetRemote.md
@@ -69,11 +69,11 @@ You can also change the request method and set the request body:
When retrieving remote data, use the [`transform.Unmarshal`] function to [unmarshal] the response.
-[`transform.Unmarshal`]: /functions/transform/unmarshal
+[`transform.Unmarshal`]: /functions/transform/unmarshal/
[unmarshal]: /getting-started/glossary/#unmarshal
```go-html-template
-{{ $data := "" }}
+{{ $data := dict }}
{{ $url := "https://example.org/books.json" }}
{{ with resources.GetRemote $url }}
{{ with .Err }}
@@ -86,11 +86,21 @@ 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 %}}
+
## Error handling
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.
-[`Err`]: /methods/resource/err
+[`Err`]: /methods/resource/err/
```go-html-template
{{ $url := "https://broken-example.org/images/a.jpg" }}
@@ -124,7 +134,7 @@ To log an error as a warning instead of an error:
The [`Data`] method on a resource returned by the `resources.GetRemote` function returns information from the HTTP response.
-[`Data`]: /methods/resource/data
+[`Data`]: /methods/resource/data/
```go-html-template
{{ $url := "https://example.org/images/a.jpg" }}
@@ -194,22 +204,15 @@ For example, you will see the error above if you attempt to download an executab
Although the allowlist contains entries for common media types, you may encounter situations where Hugo is unable to resolve the media type of a file that you know to be safe. In these situations, edit your site configuration to add the media type to the allowlist. For example:
-```text
+{{< code-toggle file=hugo >}}
[security.http]
-mediaTypes=['application/vnd\.api\+json']
-```
+mediaTypes = ['^image/avif$','^application/vnd\.api\+json$']
+{{< /code-toggle >}}
Note that the entry above is:
- An _addition_ to the allowlist; it does not _replace_ the allowlist
- An array of regular expressions
-For example, to add two entries to the allowlist:
-
-```text
-[security.http]
-mediaTypes=['application/vnd\.api\+json','image/avif']
-```
-
[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 0044351f1..f23d56f63 100644
--- a/content/en/functions/resources/Match.md
+++ b/content/en/functions/resources/Match.md
@@ -26,7 +26,7 @@ This function operates on global resources. A global resource is a file within t
For page resources, use the [`Resources.Match`] method on the Page object.
-[`Resources.Match`]: /methods/page/resources
+[`Resources.Match`]: /methods/page/resources/
{{% /note %}}
Hugo determines a match using a case-insensitive [glob pattern].
diff --git a/content/en/functions/resources/ToCSS.md b/content/en/functions/resources/ToCSS.md
index 19ef33a64..df03267e8 100644
--- a/content/en/functions/resources/ToCSS.md
+++ b/content/en/functions/resources/ToCSS.md
@@ -46,7 +46,7 @@ targetPath
: (`string`) If not set, the transformed resource's target path will be the original path of the asset file with its extension replaced by `.css`.
vars
-: (`map`) A map of key/value pairs that will be available in the `hugo:vars` namespace. Useful for [initializing Sass variables from Hugo templates](https://discourse.gohugo.io/t/42053/).
+: (`map`) A map of key-value pairs that will be available in the `hugo:vars` namespace. Useful for [initializing Sass variables from Hugo templates](https://discourse.gohugo.io/t/42053/).
```scss
// LibSass
@@ -139,8 +139,8 @@ To install Dart Sass for your builds on GitLab Pages, the `.gitlab-ci.yml` file
```yaml
variables:
- HUGO_VERSION: 0.122.0
- DART_SASS_VERSION: 1.70.0
+ HUGO_VERSION: 0.126.0
+ DART_SASS_VERSION: 1.77.1
GIT_DEPTH: 0
GIT_STRATEGY: clone
GIT_SUBMODULE_STRATEGY: recursive
@@ -173,8 +173,8 @@ To install Dart Sass for your builds on Netlify, the `netlify.toml` file should
```toml
[build.environment]
-HUGO_VERSION = "0.122.0"
-DART_SASS_VERSION = "1.70.0"
+HUGO_VERSION = "0.126.0"
+DART_SASS_VERSION = "1.77.1"
TZ = "America/Los_Angeles"
[build]
diff --git a/content/en/functions/resources/_common/_index.md b/content/en/functions/resources/_common/_index.md
index b57b688b3..cb36fea41 100644
--- a/content/en/functions/resources/_common/_index.md
+++ b/content/en/functions/resources/_common/_index.md
@@ -6,7 +6,7 @@ _build:
---
<!--
-Files within this headless branch bundle are markdown snippets. Each file must contain front matter delimiters, though front matter fields are not required.
+Files within this headless branch bundle are Markdown snippets. Each file must contain front matter delimiters, though front matter fields are not required.
Include the rendered content using the "include" shortcode.
-->
diff --git a/content/en/functions/safe/CSS.md b/content/en/functions/safe/CSS.md
index 08307fb15..05ca25e11 100644
--- a/content/en/functions/safe/CSS.md
+++ b/content/en/functions/safe/CSS.md
@@ -1,6 +1,6 @@
---
title: safe.CSS
-description: Declares the given string as safe CSS string.
+description: Declares the given string as a safe CSS string.
categories: []
keywords: []
action:
@@ -13,21 +13,57 @@ action:
- functions/safe/URL
returnType: template.CSS
signatures: [safe.CSS INPUT]
+toc: true
aliases: [/functions/safecss]
---
-In this context, *safe* means CSS content that matches any of the following:
+## Introduction
+
+{{% include "functions/_common/go-html-template-package.md" %}}
+
+## Usage
+
+Use the `safe.CSS` function to encapsulate known safe content that matches any of:
1. The CSS3 stylesheet production, such as `p { color: purple }`.
2. The CSS3 rule production, such as `a[href=~"https:"].foo#bar`.
3. CSS3 declaration productions, such as `color: red; margin: 2px`.
4. The CSS3 value production, such as `rgba(0, 0, 255, 127)`.
-Example: Given `style = "color: red;"` defined in the front matter of your `.md` file:
+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.
+
+[Go documentation]: https://pkg.go.dev/html/template#CSS
+
+## Example
+
+Without a safe declaration:
-* `<p style="{{ .Params.style | safeCSS }}">…</p>` &rarr; `<p style="color: red;">…</p>`
-* `<p style="{{ .Params.style }}">…</p>` &rarr; `<p style="ZgotmplZ">…</p>`
+```go-html-template
+{{ $style := "color: red;" }}
+<p style="{{ $style }}">foo</p>
+```
+
+Hugo renders the above to:
+
+```html
+<p style="ZgotmplZ">foo</p>
+```
{{% note %}}
-`ZgotmplZ` is a special value that indicates that unsafe content reached a CSS or URL context.
+`ZgotmplZ` is a special value that indicates that unsafe content reached a CSS or URL context at runtime.
{{% /note %}}
+
+To declare the string as safe:
+
+```go-html-template
+{{ $style := "color: red;" }}
+<p style="{{ $style | safeCSS }}">foo</p>
+```
+
+Hugo renders the above to:
+
+```html
+<p style="color: red;">foo</p>
+```
diff --git a/content/en/functions/safe/HTML.md b/content/en/functions/safe/HTML.md
index ecc4f1346..ad1b3a681 100644
--- a/content/en/functions/safe/HTML.md
+++ b/content/en/functions/safe/HTML.md
@@ -13,27 +13,48 @@ action:
- functions/safe/URL
returnType: template.HTML
signatures: [safe.HTML INPUT]
+toc: true
aliases: [/functions/safehtml]
---
-It should not be used for HTML from a third-party, or HTML with unclosed tags or comments.
+## Introduction
-Given a site-wide [`hugo.toml`][config] with the following `copyright` value:
+{{% include "functions/_common/go-html-template-package.md" %}}
-{{< code-toggle file=hugo >}}
-copyright = "© 2015 Jane Doe. <a href=\"https://creativecommons.org/licenses/by/4.0/\">Some rights reserved</a>."
-{{< /code-toggle >}}
+## Usage
-`{{ .Site.Copyright | safeHTML }}` in a template would then output:
+Use the `safe.HTML` function to encapsulate a known safe HTML document fragment. It should not be used for HTML from a third-party, or HTML with unclosed tags or comments.
-```html
-© 2015 Jane Doe. <a href="https://creativecommons.org/licenses/by/4.0/">Some rights reserved</a>.
+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.
+
+[Go documentation]: https://pkg.go.dev/html/template#HTML
+
+## Example
+
+Without a safe declaration:
+
+```go-html-template
+{{ $html := "<em>emphasized</em>" }}
+{{ $html }}
```
-However, without the `safeHTML` function, html/template assumes `.Site.Copyright` to be unsafe and therefore escapes all HTML tags and renders the whole string as plain text:
+Hugo renders the above to:
```html
-<p>© 2015 Jane Doe. &lt;a href=&#34;https://creativecommons.org/licenses by/4.0/&#34;&gt;Some rights reserved&lt;/a&gt;.</p>
+&lt;em&gt;emphasized&lt;/em&gt;
```
-[config]: /getting-started/configuration/
+To declare the string as safe:
+
+```go-html-template
+{{ $html := "<em>emphasized</em>" }}
+{{ $html | safeHTML }}
+```
+
+Hugo renders the above to:
+
+```html
+<em>emphasized</em>
+```
diff --git a/content/en/functions/safe/HTMLAttr.md b/content/en/functions/safe/HTMLAttr.md
index 198fc8ff3..d01a3908a 100644
--- a/content/en/functions/safe/HTMLAttr.md
+++ b/content/en/functions/safe/HTMLAttr.md
@@ -1,6 +1,6 @@
---
title: safe.HTMLAttr
-description: Declares the given key/value pair as a safe HTML attribute.
+description: Declares the given key-value pair as a safe HTML attribute.
categories: []
keywords: []
action:
@@ -13,43 +13,54 @@ action:
- functions/safe/URL
returnType: template.HTMLAttr
signatures: [safe.HTMLAttr INPUT]
+toc: true
aliases: [/functions/safehtmlattr]
---
-Given a site configuration that contains this menu entry:
+## Introduction
-{{< code-toggle file=hugo >}}
-[[menus.main]]
- name = "IRC"
- url = "irc://irc.freenode.net/#golang"
-{{< /code-toggle >}}
+{{% include "functions/_common/go-html-template-package.md" %}}
-Attempting to use the `url` value directly in an attribute:
+## 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.
+
+[Go documentation]: https://pkg.go.dev/html/template#HTMLAttr
+
+## Example
+
+Without a safe declaration:
```go-html-template
-{{ range site.Menus.main }}
- <a href="{{ .URL }}">{{ .Name }}</a>
+{{ with .Date }}
+ {{ $humanDate := time.Format "2 Jan 2006" . }}
+ {{ $machineDate := time.Format "2006-01-02T15:04:05-07:00" . }}
+ <time datetime="{{ $machineDate }}">{{ $humanDate }}</time>
{{ end }}
```
-Will produce:
+Hugo renders the above to:
```html
-<a href="#ZgotmplZ">IRC</a>
+<time datetime="2024-05-26T07:19:55&#43;02:00">26 May 2024</time>
```
-`ZgotmplZ` is a special value, inserted by Go's [template/html] package, that indicates that unsafe content reached a CSS or URL context.
-
-To indicate that the HTML attribute is safe:
+To declare the key-value pair as safe:
```go-html-template
-{{ range site.Menus.main }}
- <a {{ printf "href=%q" .URL | safeHTMLAttr }}>{{ .Name }}</a>
+{{ with .Date }}
+ {{ $humanDate := time.Format "2 Jan 2006" . }}
+ {{ $machineDate := time.Format "2006-01-02T15:04:05-07:00" . }}
+ <time {{ printf "datetime=%q" $machineDate | safeHTMLAttr }}>{{ $humanDate }}</time>
{{ end }}
```
-{{% note %}}
-As demonstrated above, you must pass the HTML attribute name _and_ value through the function. Applying `safeHTMLAttr` to the attribute value has no effect.
-{{% /note %}}
+Hugo renders the above to:
-[template/html]: https://pkg.go.dev/html/template
+```html
+<time datetime="2024-05-26T07:19:55+02:00">26 May 2024</time>
+```
diff --git a/content/en/functions/safe/JS.md b/content/en/functions/safe/JS.md
index 65279b89b..d0d3a227a 100644
--- a/content/en/functions/safe/JS.md
+++ b/content/en/functions/safe/JS.md
@@ -13,14 +13,54 @@ action:
- functions/safe/URL
returnType: template.JS
signatures: [safe.JS INPUT]
+toc: true
aliases: [/functions/safejs]
---
-In this context, *safe* means the string encapsulates a known safe EcmaScript5 Expression (e.g., `(x + y * z())`).
+## Introduction
-Template authors are responsible for ensuring that typed expressions do not break the intended precedence and that there is no statement/expression ambiguity as when passing an expression like `{ foo:bar() }\n['foo']()`, which is both a valid expression and a valid program with a very different meaning.
+{{% include "functions/_common/go-html-template-package.md" %}}
-Example: Given `hash = "619c16f"` defined in the front matter of your `.md` file:
+## Usage
-* `<script>var form_{{ .Params.hash | safeJS }};…</script>` &rarr; `<script>var form_619c16f;…</script>`
-* `<script>var form_{{ .Params.hash }};…</script>` &rarr; `<script>var form_"619c16f";…</script>`
+Use the `safe.JS` function to encapsulate a known safe EcmaScript5 Expression.
+
+Template authors are responsible for ensuring that typed expressions do not break the intended precedence and that there is no statement/expression ambiguity as when passing an expression like `{ foo: bar() }\n['foo']()`, which is both a valid Expression and a valid Program with a very different meaning.
+
+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.
+
+Using the `safe.JS` function to include valid but untrusted JSON is not safe. A safe alternative is to parse the JSON with the [`transform.Unmarshal`] function and then pass the resultant object into the template, where it will be converted to sanitized JSON when presented in a JavaScript context.
+
+[`transform.Unmarshal`]: /functions/transform/unmarshal/
+
+See the [Go documentation] for details.
+
+[Go documentation]: https://pkg.go.dev/html/template#JS
+
+## Example
+
+Without a safe declaration:
+
+```go-html-template
+{{ $js := "x + y" }}
+<script>const a = {{ $js }}</script>
+```
+
+Hugo renders the above to:
+
+```html
+<script>const a = "x + y"</script>
+```
+
+To declare the string as safe:
+
+```go-html-template
+{{ $js := "x + y" }}
+<script>const a = {{ $js | safeJS }}</script>
+```
+
+Hugo renders the above to:
+
+```html
+<script>const a = x + y</script>
+```
diff --git a/content/en/functions/safe/JSStr.md b/content/en/functions/safe/JSStr.md
index 36d2b36fa..e7e232d1b 100644
--- a/content/en/functions/safe/JSStr.md
+++ b/content/en/functions/safe/JSStr.md
@@ -13,12 +13,27 @@ action:
- functions/safe/URL
returnType: template.JSStr
signatures: [safe.JSStr INPUT]
+toc: true
aliases: [/functions/safejsstr]
---
-Encapsulates a sequence of characters meant to be embedded between quotes in a JavaScript expression. 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.
-
-Without declaring a variable to be a safe JavaScript string:
+## Introduction
+
+{{% include "functions/_common/go-html-template-package.md" %}}
+
+## Usage
+
+Use the `safe.JSStr` function to encapsulate a sequence of characters meant to be embedded between quotes in a JavaScript expression.
+
+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.
+
+[Go documentation]: https://pkg.go.dev/html/template#JSStr
+
+## Example
+
+Without a safe declaration:
```go-html-template
{{ $title := "Lilo & Stitch" }}
@@ -27,7 +42,7 @@ Without declaring a variable to be a safe JavaScript string:
</script>
```
-Rendered:
+Hugo renders the above to:
```html
<script>
@@ -35,7 +50,7 @@ Rendered:
</script>
```
-To avoid escaping by Go's [html/template] package:
+To declare the string as safe:
```go-html-template
{{ $title := "Lilo & Stitch" }}
@@ -44,12 +59,10 @@ To avoid escaping by Go's [html/template] package:
</script>
```
-Rendered:
+Hugo renders the above to:
```html
<script>
const a = "Title: " + "Lilo & Stitch";
</script>
```
-
-[html/template]: https://pkg.go.dev/html/template
diff --git a/content/en/functions/safe/URL.md b/content/en/functions/safe/URL.md
index 2da6895e5..e4b3224da 100644
--- a/content/en/functions/safe/URL.md
+++ b/content/en/functions/safe/URL.md
@@ -13,58 +13,56 @@ action:
- functions/safe/JSStr
returnType: template.URL
signatures: [safe.URL INPUT]
+toc: true
aliases: [/functions/safeurl]
---
-`safeURL` declares the provided string as a "safe" URL or URL substring (see [RFC 3986]). A URL like `javascript:checkThatFormNotEditedBeforeLeavingPage()` from a trusted source should go in the page, but by default dynamic `javascript:` URLs are filtered out since they are a frequently exploited injection vector.
+## Introduction
-Without `safeURL`, only the URI schemes `http:`, `https:` and `mailto:` are considered safe by Go templates. If any other URI schemes (e.g., `irc:` and `javascript:`) are detected, the whole URL will be replaced with `#ZgotmplZ`. This is to "defang" any potential attack in the URL by rendering it useless.
+{{% include "functions/_common/go-html-template-package.md" %}}
-The following examples use a [site `hugo.toml`][configuration] with the following [menu entry][menus]:
+## Usage
-{{< code-toggle file=hugo >}}
-[[menus.main]]
-name = "IRC: #golang at freenode"
-url = "irc://irc.freenode.net/#golang"
-{{< /code-toggle >}}
+Use the `safe.URL` function to encapsulate a known safe URL or URL substring. Schemes other than the following are considered unsafe:
-The following is an example of a sidebar partial that may be used in conjunction with the preceding front matter example:
+- `http:`
+- `https:`
+- `mailto:`
-{{< code file=layouts/partials/bad-url-sidebar-menu.html >}}
-<!-- This unordered list may be part of a sidebar menu -->
-<ul>
- {{ range .Site.Menus.main }}
- <li><a href="{{ .URL }}">{{ .Name }}</a></li>
- {{ end }}
-</ul>
-{{< /code >}}
+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.
-This partial would produce the following HTML output:
+See the [Go documentation] for details.
+
+[Go documentation]: https://pkg.go.dev/html/template#URL
+
+## Example
+
+Without a safe declaration:
+
+```go-html-template
+{{ $href := "irc://irc.freenode.net/#golang" }}
+<a href="{{ $href }}">IRC</a>
+```
+
+Hugo renders the above to:
```html
-<!-- This unordered list may be part of a sidebar menu -->
-<ul>
- <li><a href="#ZgotmplZ">IRC: #golang at freenode</a></li>
-</ul>
+<a href="#ZgotmplZ">IRC</a>
```
-The odd output can be remedied by adding ` | safeURL` to our `.URL` page variable:
+{{% note %}}
+`ZgotmplZ` is a special value that indicates that unsafe content reached a CSS or URL context at runtime.
+{{% /note %}}
+
+To declare the string as safe:
-{{< code file=layouts/partials/correct-url-sidebar-menu.html >}}
-<!-- This unordered list may be part of a sidebar menu -->
-<ul>
- <li><a href="{{ .URL | safeURL }}">{{ .Name }}</a></li>
-</ul>
-{{< /code >}}
+```go-html-template
+{{ $href := "irc://irc.freenode.net/#golang" }}
+<a href="{{ $href | safeURL }}">IRC</a>
+```
-With the `.URL` page variable piped through `safeURL`, we get the desired output:
+Hugo renders the above to:
```html
-<ul class="sidebar-menu">
- <li><a href="irc://irc.freenode.net/#golang">IRC: #golang at freenode</a></li>
-</ul>
+<a href="irc://irc.freenode.net/#golang">IRC</a>
```
-
-[configuration]: /getting-started/configuration/
-[menus]: /content-management/menus/
-[RFC 3986]: https://tools.ietf.org/html/rfc3986
diff --git a/content/en/functions/strings/ContainsNonSpace.md b/content/en/functions/strings/ContainsNonSpace.md
index 188aa14ba..d4c72eea0 100644
--- a/content/en/functions/strings/ContainsNonSpace.md
+++ b/content/en/functions/strings/ContainsNonSpace.md
@@ -1,6 +1,6 @@
---
title: strings.ContainsNonSpace
-description: Reports whether the given string contains any non-space characters as defined by Unicode’s White Space property.
+description: Reports whether the given string contains any non-space characters as defined by Unicode's White Space property.
categories: []
keywords: []
action:
@@ -24,7 +24,7 @@ aliases: [/functions/strings.containsnonspace]
{{ strings.ContainsNonSpace "\n abc" }} → true
```
-Common white space characters include:
+Common whitespace characters include:
```text
'\t', '\n', '\v', '\f', '\r', ' '
diff --git a/content/en/functions/strings/CountRunes.md b/content/en/functions/strings/CountRunes.md
index 10788e174..87d9da680 100644
--- a/content/en/functions/strings/CountRunes.md
+++ b/content/en/functions/strings/CountRunes.md
@@ -21,4 +21,4 @@ In contrast with the [`strings.RuneCount`] function, which counts every rune in
{{ "Hello, 世界" | strings.CountRunes }} → 8
```
-[`strings.RuneCount`]: /functions/strings/runecount
+[`strings.RuneCount`]: /functions/strings/runecount/
diff --git a/content/en/functions/strings/Diff/diff-screen-capture.png b/content/en/functions/strings/Diff/diff-screen-capture.png
new file mode 100644
index 000000000..62baa4563
--- /dev/null
+++ b/content/en/functions/strings/Diff/diff-screen-capture.png
Binary files differ
diff --git a/content/en/functions/strings/Diff/index.md b/content/en/functions/strings/Diff/index.md
new file mode 100644
index 000000000..be7bfd911
--- /dev/null
+++ b/content/en/functions/strings/Diff/index.md
@@ -0,0 +1,33 @@
+---
+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]
+---
+
+{{< new-in 0.125.0 >}}
+
+Use `strings.Diff` to compare two strings and render a highlighted diff:
+
+```go-html-template
+{{ $want := `
+<p>The product of 6 and 7 is 42.</p>
+<p>The product of 7 and 6 is 42.</p>
+`}}
+
+{{ $got := `
+<p>The product of 6 and 7 is 42.</p>
+<p>The product of 7 and 6 is 13.</p>
+`}}
+
+{{ $diff := strings.Diff "want" $want "got" $got }}
+{{ transform.Highlight $diff "diff" }}
+```
+
+Rendered:
+
+![sreen capture](diff-screen-capture.png)
diff --git a/content/en/functions/strings/FindRESubmatch.md b/content/en/functions/strings/FindRESubmatch.md
index 302d1d9b4..3feb15bbd 100644
--- a/content/en/functions/strings/FindRESubmatch.md
+++ b/content/en/functions/strings/FindRESubmatch.md
@@ -30,7 +30,7 @@ By default, `findRESubmatch` finds all matches. You can limit the number of matc
## Practical example
-This markdown:
+This Markdown:
```text
- [Example](https://example.org)
diff --git a/content/en/functions/strings/RuneCount.md b/content/en/functions/strings/RuneCount.md
index 46fedf01f..86aab0c64 100644
--- a/content/en/functions/strings/RuneCount.md
+++ b/content/en/functions/strings/RuneCount.md
@@ -21,4 +21,4 @@ In contrast with the [`strings.CountRunes`] function, which excludes whitespace,
{{ "Hello, 世界" | strings.RuneCount }} → 9
```
-[`strings.CountRunes`]: /functions/strings/countrunes
+[`strings.CountRunes`]: /functions/strings/countrunes/
diff --git a/content/en/functions/strings/SliceString.md b/content/en/functions/strings/SliceString.md
index 2f33f8f65..ee4ed9081 100644
--- a/content/en/functions/strings/SliceString.md
+++ b/content/en/functions/strings/SliceString.md
@@ -1,20 +1,26 @@
---
title: strings.SliceString
-description: Creates a slice of a half-open range, including start and end indices.
+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: []
+ related:
+ - functions/strings/Substr
returnType: string
- signatures: ['strings.SliceString STRING START [END]']
+ signatures: ['strings.SliceString STRING [START] [END]']
aliases: [/functions/slicestr]
---
-For example, 1 and 4 creates a slice including elements 1 through&nbsp;3.
-The `end` index can be omitted; it defaults to the string's length.
+The START and END positions are zero-based, where `0` represents the first character of the string. If START is not specified, the substring will begin at position `0`. If END is not specified, the substring will end after the last character.
```go-html-template
-{{ slicestr "BatMan" 3 }}` → Man
-{{ slicestr "BatMan" 0 3 }}` → Bat
+{{ slicestr "BatMan" }} → BatMan
+{{ slicestr "BatMan" 3 }} → Man
+{{ slicestr "BatMan" 0 3 }} → Bat
```
+
+The START and END arguments represent the endpoints of a [half-open interval], a concept that may be difficult to grasp when first encountered. You may find that the [`strings.Substr`] function is easier to understand.
+
+[half-open interval]: /getting-started/glossary/#interval
+[`strings.Substr`]: /functions/strings/substr/
diff --git a/content/en/functions/strings/Split.md b/content/en/functions/strings/Split.md
index a9973ea63..e3e0ee13e 100644
--- a/content/en/functions/strings/Split.md
+++ b/content/en/functions/strings/Split.md
@@ -22,5 +22,5 @@ Examples:
{{% 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
+[`collections.Delimit`]: /functions/collections/delimit/
{{% /note %}}
diff --git a/content/en/functions/strings/Substr.md b/content/en/functions/strings/Substr.md
index 6c1852f58..19a029e28 100644
--- a/content/en/functions/strings/Substr.md
+++ b/content/en/functions/strings/Substr.md
@@ -1,21 +1,20 @@
---
title: strings.Substr
-description: Extracts parts of a string from a specified character's position and returns the specified number of characters.
+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: []
+ related:
+ - functions/strings/SliceString
returnType: string
- signatures: ['strings.Substr STRING START [LENGTH]']
+ signatures: ['strings.Substr STRING [START] [LENGTH]']
aliases: [/functions/substr]
---
-It normally takes two argument: `start` and `length`. It can also take one argument: `start`, i.e. `length` is omitted, in which case the substring starting from start until the end of the string will be returned.
+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.
-To extract characters from the end of the string, use a negative start number.
-
-If `length` is given and is negative, that number of characters will be omitted from the end of 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.
```go-html-template
{{ substr "abcdef" 0 }} → abcdef
diff --git a/content/en/functions/strings/Trim.md b/content/en/functions/strings/Trim.md
index 6dfac024b..9a87ff206 100644
--- a/content/en/functions/strings/Trim.md
+++ b/content/en/functions/strings/Trim.md
@@ -32,7 +32,7 @@ To remove leading and trailing newline characters and carriage returns:
The `strings.Trim` function is commonly used in shortcodes to remove leading and trailing newlines characters and carriage returns from the content within the opening and closing shortcode tags.
-For example, with this markdown:
+For example, with this Markdown:
```text
{{</* my-shortcode */>}}
diff --git a/content/en/functions/strings/Truncate.md b/content/en/functions/strings/Truncate.md
index 17ae0afc6..2e7693eb5 100644
--- a/content/en/functions/strings/Truncate.md
+++ b/content/en/functions/strings/Truncate.md
@@ -20,5 +20,5 @@ Since Go templates are HTML-aware, `truncate` will intelligently handle normal s
{{% 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
+[`safeHTML`]: /functions/safe/html/
{{% /note %}}
diff --git a/content/en/functions/time/Duration.md b/content/en/functions/time/Duration.md
index f9c26d294..051be7ade 100644
--- a/content/en/functions/time/Duration.md
+++ b/content/en/functions/time/Duration.md
@@ -43,4 +43,4 @@ microseconds|`microsecond`, `us`, `µs`
nanoseconds|`nanosecond`, `ns`
[`time.Duration`]: https://pkg.go.dev/time#Duration
-[methods]: /methods/duration
+[methods]: /methods/duration/
diff --git a/content/en/functions/time/Now.md b/content/en/functions/time/Now.md
index 60e45a91c..28ac7acfc 100644
--- a/content/en/functions/time/Now.md
+++ b/content/en/functions/time/Now.md
@@ -43,6 +43,6 @@ The `time.Now` function returns a `time.Time` value, so you can chain any of the
{{ time.Now.Unix }} → 1697400955 (int64)
```
-[`time.Format`]: /functions/time/format
+[`time.Format`]: /functions/time/format/
[localize]: /getting-started/glossary/#localization
[time methods]: /methods/time/
diff --git a/content/en/functions/time/ParseDuration.md b/content/en/functions/time/ParseDuration.md
index 091914132..d3369b899 100644
--- a/content/en/functions/time/ParseDuration.md
+++ b/content/en/functions/time/ParseDuration.md
@@ -34,4 +34,4 @@ There are 86400 seconds in one day.
```
[`time.Duration`]: https://pkg.go.dev/time#Duration
-[methods]: /methods/duration
+[methods]: /methods/duration/
diff --git a/content/en/functions/time/_common/_index.md b/content/en/functions/time/_common/_index.md
index 47d5812fb..4328d4d14 100644
--- a/content/en/functions/time/_common/_index.md
+++ b/content/en/functions/time/_common/_index.md
@@ -7,7 +7,7 @@ cascade:
---
<!--
-Files within this headless branch bundle are markdown snippets. Each file must contain front matter delimiters, though front matter fields are not required.
+Files within this headless branch bundle are Markdown snippets. Each file must contain front matter delimiters, though front matter fields are not required.
Include the rendered content using the "include" shortcode.
-->
diff --git a/content/en/functions/transform/HTMLUnescape.md b/content/en/functions/transform/HTMLUnescape.md
index 180318077..1c88de672 100644
--- a/content/en/functions/transform/HTMLUnescape.md
+++ b/content/en/functions/transform/HTMLUnescape.md
@@ -25,6 +25,6 @@ In most contexts Go's [html/template] package will escape special characters. To
{{ htmlUnescape "Lilo &amp; Stitch" | safeHTML }}
```
-[`safehtml`]: /functions/safe/html
+[`safehtml`]: /functions/safe/html/
[html entities]: https://developer.mozilla.org/en-us/docs/glossary/entity
[html/template]: https://pkg.go.dev/html/template
diff --git a/content/en/functions/transform/Markdownify.md b/content/en/functions/transform/Markdownify.md
index 8fb1e48ce..7a84f43b7 100644
--- a/content/en/functions/transform/Markdownify.md
+++ b/content/en/functions/transform/Markdownify.md
@@ -1,6 +1,6 @@
---
title: transform.Markdownify
-description: Renders markdown to HTML.
+description: Renders Markdown to HTML.
categories: []
keywords: []
action:
@@ -24,8 +24,8 @@ To keep the wrapping `p` tags for a single paragraph, use the [`RenderString`] m
[`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.
+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]: /templates/render-hooks/
+[Markdown render hooks]: /render-hooks/
[#9692]: https://github.com/gohugoio/hugo/issues/9692
{{% /note %}}
diff --git a/content/en/functions/transform/Unmarshal.md b/content/en/functions/transform/Unmarshal.md
index bc2b663e3..998152eb2 100644
--- a/content/en/functions/transform/Unmarshal.md
+++ b/content/en/functions/transform/Unmarshal.md
@@ -46,10 +46,10 @@ assets/
```
```go-html-template
-{{ $data := "" }}
+{{ $data := dict }}
{{ $path := "data/books.json" }}
{{ with resources.Get $path }}
- {{ with unmarshal . }}
+ {{ with . | transform.Unmarshal }}
{{ $data = . }}
{{ end }}
{{ else }}
@@ -75,10 +75,10 @@ content/
```
```go-html-template
-{{ $data := "" }}
+{{ $data := dict }}
{{ $path := "books.json" }}
{{ with .Resources.Get $path }}
- {{ with unmarshal . }}
+ {{ with . | transform.Unmarshal }}
{{ $data = . }}
{{ end }}
{{ else }}
@@ -95,7 +95,7 @@ content/
A remote resource is a file on a remote server, accessible via HTTP or HTTPS.
```go-html-template
-{{ $data := "" }}
+{{ $data := dict }}
{{ $url := "https://example.org/books.json" }}
{{ with resources.GetRemote $url }}
{{ with .Err }}
@@ -112,8 +112,15 @@ A remote resource is a file on a remote server, accessible via HTTP or HTTPS.
{{ end }}
```
-[resource]: /getting-started/glossary/#resource
-[page bundle]: /content-management/page-bundles
+{{% 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 %}}
## Options
@@ -166,7 +173,7 @@ When unmarshaling an XML file, do not include the root node when accessing data.
Get the remote data:
```go-html-template
-{{ $data := "" }}
+{{ $data := dict }}
{{ $url := "https://example.org/books/index.xml" }}
{{ with resources.GetRemote $url }}
{{ with .Err }}
@@ -182,7 +189,7 @@ Get the remote data:
Inspect the data structure:
```go-html-template
-<pre>{{ jsonify (dict "indent" " ") $data }}</pre>
+<pre>{{ debug.Dump $data }}</pre>
```
List the book titles:
@@ -245,7 +252,7 @@ Let's add a `lang` attribute to the `title` nodes of our RSS feed, and a namespa
After retrieving the remote data, inspect the data structure:
```go-html-template
-<pre>{{ jsonify (dict "indent" " ") $data }}</pre>
+<pre>{{ debug.Dump $data }}</pre>
```
Each item node looks like this:
@@ -288,5 +295,7 @@ Hugo renders this to:
</ul>
```
-[`index`]: /functions/collections/indexfunction
+[`index`]: /functions/collections/indexfunction/
[identifiers]: https://go.dev/ref/spec#Identifiers
+[resource]: /getting-started/glossary/#resource
+[page bundle]: /content-management/page-bundles/
diff --git a/content/en/functions/urls/AbsLangURL.md b/content/en/functions/urls/AbsLangURL.md
index 876552bb7..67e1781e7 100644
--- a/content/en/functions/urls/AbsLangURL.md
+++ b/content/en/functions/urls/AbsLangURL.md
@@ -20,48 +20,44 @@ Use this function with both monolingual and multilingual configurations. The URL
- The `baseURL` in site configuration
- The language prefix, if any
-In examples that follow, the project is multilingual with content in both Español (`es`) and English (`en`). The default language is Español. The returned values are from the English site.
+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.
### Input does not begin with a slash
-If the input does not begin with a slash, the resulting URL will be correct regardless of the `baseURL`.
+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/`
```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/`
```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
-If the input begins with a slash, the resulting URL will be incorrect when the `baseURL` includes a subdirectory. With a leading slash, the function returns a URL relative to the protocol+host section of the `baseURL`.
+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/`
```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/`
```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
```
-
-{{% note %}}
-The last three examples are not desirable in most situations. As a best practice, never include a leading slash when using this function.
-{{% /note %}}
diff --git a/content/en/functions/urls/AbsURL.md b/content/en/functions/urls/AbsURL.md
index 5b027ae84..1120eac42 100644
--- a/content/en/functions/urls/AbsURL.md
+++ b/content/en/functions/urls/AbsURL.md
@@ -14,53 +14,49 @@ action:
aliases: [/functions/absurl]
---
-With multilingual configurations, use the [`absLangURL`] function instead. The URL returned by this function depends on:
+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
### Input does not begin with a slash
-If the input does not begin with a slash, the resulting URL will be correct regardless of the `baseURL`.
+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/`
```go-html-template
-{{ absURL "" }} → https://example.org/
-{{ absURL "articles" }} → https://example.org/articles
-{{ absURL "style.css" }} → https://example.org/style.css
+{{ absURL "" }} → https://example.org/
+{{ absURL "articles" }} → https://example.org/articles
+{{ absURL "style.css" }} → https://example.org/style.css
```
With `baseURL = https://example.org/docs/`
```go-html-template
-{{ absURL "" }} → https://example.org/docs/
-{{ absURL "articles" }} → https://example.org/docs/articles
-{{ absURL "style.css" }} → https://example.org/docs/style.css
+{{ absURL "" }} → https://example.org/docs/
+{{ absURL "articles" }} → https://example.org/docs/articles
+{{ absURL "style.css" }} → https://example.org/docs/style.css
```
#### Input begins with a slash
-If the input begins with a slash, the resulting URL will be incorrect when the `baseURL` includes a subdirectory. With a leading slash, the function returns a URL relative to the protocol+host section of the `baseURL`.
+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/`
```go-html-template
-{{ absURL "/" }} → https://example.org/
-{{ absURL "/articles" }} → https://example.org/articles
-{{ absURL "/style.css" }} → https://example.org/style.css
+{{ absURL "/" }} → https://example.org/
+{{ absURL "/articles" }} → https://example.org/articles
+{{ absURL "/style.css" }} → https://example.org/style.css
```
With `baseURL = https://example.org/docs/`
```go-html-template
-{{ absURL "/" }} → https://example.org/
-{{ absURL "/articles" }} → https://example.org/articles
-{{ absURL "/style.css" }} → https://example.org/style.css
+{{ absURL "/" }} → https://example.org/
+{{ absURL "/articles" }} → https://example.org/articles
+{{ absURL "/style.css" }} → https://example.org/style.css
```
-{{% note %}}
-The last three examples are not desirable in most situations. As a best practice, never include a leading slash when using this function.
-{{% /note %}}
-
-[`absLangURL`]: /functions/urls/abslangurl/
+[`urls.AbsLangURL`]: /functions/urls/abslangurl/
diff --git a/content/en/functions/urls/Anchorize.md b/content/en/functions/urls/Anchorize.md
index 72b3d54a9..f3939675a 100644
--- a/content/en/functions/urls/Anchorize.md
+++ b/content/en/functions/urls/Anchorize.md
@@ -16,14 +16,14 @@ aliases: [/functions/anchorize]
## Sanitizing logic
-With the default markdown renderer, Goldmark, the sanitizing logic is controlled by your site configuration:
+With the default Markdown renderer, Goldmark, the sanitizing logic is controlled by your site configuration:
{{< code-toggle file=hugo >}}
[markup.goldmark.parser]
autoHeadingIDType = 'github'
{{< /code-toggle >}}
-This controls the behavior of the `anchorize` function and the generation of heading IDs when rendering markdown to HTML.
+This controls the behavior of the `anchorize` function and the generation of heading IDs when rendering Markdown to HTML.
Set `autoHeadingIDType` to one of:
diff --git a/content/en/functions/urls/JoinPath.md b/content/en/functions/urls/JoinPath.md
index 7acecb506..d9822cfda 100644
--- a/content/en/functions/urls/JoinPath.md
+++ b/content/en/functions/urls/JoinPath.md
@@ -27,4 +27,4 @@ aliases: [/functions/urls.joinpath]
Unlike the [`path.Join`] function, `urls.JoinPath` retains consecutive leading slashes.
-[`path.Join`]: /functions/path/join
+[`path.Join`]: /functions/path/join/
diff --git a/content/en/functions/urls/Parse.md b/content/en/functions/urls/Parse.md
index 2eb4eeadf..a64116254 100644
--- a/content/en/functions/urls/Parse.md
+++ b/content/en/functions/urls/Parse.md
@@ -19,6 +19,7 @@ The `urls.Parse` function parses a URL into a [URL structure](https://godoc.org/
{{ $url := "https://example.org:123/foo?a=6&b=7#bar" }}
{{ $u := urls.Parse $url }}
+{{ $u.String }} → https://example.org:123/foo?a=6&b=7#bar
{{ $u.IsAbs }} → true
{{ $u.Scheme }} → https
{{ $u.Host }} → example.org:123
diff --git a/content/en/functions/urls/RelLangURL.md b/content/en/functions/urls/RelLangURL.md
index 2c1037038..883e7dda2 100644
--- a/content/en/functions/urls/RelLangURL.md
+++ b/content/en/functions/urls/RelLangURL.md
@@ -17,51 +17,49 @@ aliases: [/functions/rellangurl]
Use this function with both monolingual and multilingual configurations. The URL returned by this function depends on:
- Whether the input begins with a slash
-- The `baseURL` in site configuration
+- The `baseURL` in your site configuration
- The language prefix, if any
-In examples that follow, the project is multilingual with content in both Español (`es`) and English (`en`). The default language is Español. The returned values are from the English site.
+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.
### Input does not begin with a slash
-If the input does not begin with a slash, the resulting URL will be correct regardless of the `baseURL`.
+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
-{{ relLangURL "" }} → /en/
-{{ relLangURL "articles" }} → /en/articles
-{{ relLangURL "style.css" }} → /en/style.css
+{{ relLangURL "" }} → /en/
+{{ relLangURL "articles" }} → /en/articles
+{{ relLangURL "style.css" }} → /en/style.css
+{{ relLangURL "https://example.org/foo" }} → /en/foo
```
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 "" }} → /docs/en/
+{{ relLangURL "articles" }} → /docs/en/articles
+{{ relLangURL "style.css" }} → /docs/en/style.css
+{{ relLangURL "https://example.org/docs/foo" }} → /docs/en/foo
```
#### Input begins with a slash
-If the input begins with a slash, the resulting URL will be incorrect when the `baseURL` includes a subdirectory. With a leading slash, the function returns a URL relative to the protocol+host section of the `baseURL`.
+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/`
```go-html-template
-{{ relLangURL "/" }} → /en/
-{{ relLangURL "/articles" }} → /en/articles
-{{ relLangURL "/style.css" }} → /en/style.css
+{{ relLangURL "/" }} → /en/
+{{ relLangURL "/articles" }} → /en/articles
+{{ relLangURL "/style.css" }} → /en/style.css
```
With `baseURL = https://example.org/docs/`
```go-html-template
-{{ relLangURL "/" }} → /en/
-{{ relLangURL "/articles" }} → /en/articles
-{{ relLangURL "/style.css" }} → /en/style.css
+{{ relLangURL "/" }} → /en/
+{{ relLangURL "/articles" }} → /en/articles
+{{ relLangURL "/style.css" }} → /en/style.css
```
-
-{{% note %}}
-The last three examples are not desirable in most situations. As a best practice, never include a leading slash when using this function.
-{{% /note %}}
diff --git a/content/en/functions/urls/RelURL.md b/content/en/functions/urls/RelURL.md
index 9320c2827..18ac24d10 100644
--- a/content/en/functions/urls/RelURL.md
+++ b/content/en/functions/urls/RelURL.md
@@ -14,53 +14,51 @@ action:
aliases: [/functions/relurl]
---
-With multilingual configurations, use the [`relLangURL`] function instead. The URL returned by this function depends on:
+With multilingual configurations, use the [`urls.RelLangURL`] function instead. The URL returned by this function depends on:
- Whether the input begins with a slash
-- The `baseURL` in site configuration
+- The `baseURL` in your site configuration
### Input does not begin with a slash
-If the input does not begin with a slash, the resulting URL will be correct regardless of the `baseURL`.
+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 "" }} → /
+{{ relURL "articles" }} → /articles
+{{ relURL "style.css" }} → /style.css
+{{ relURL "https://example.org/foo" }} → /foo
```
With `baseURL = https://example.org/docs/`
```go-html-template
-{{ relURL "" }} → /docs/
-{{ relURL "articles" }} → /docs/articles
-{{ relURL "style.css" }} → /docs/style.css
+{{ relURL "" }} → /docs/
+{{ relURL "articles" }} → /docs/articles
+{{ relURL "style.css" }} → /docs/style.css
+{{ relURL "https://example.org/docs/foo" }} → /docs/foo
```
#### Input begins with a slash
-If the input begins with a slash, the resulting URL will be incorrect when the `baseURL` includes a subdirectory. With a leading slash, the function returns a URL relative to the protocol+host section of the `baseURL`.
+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/`
```go-html-template
-{{ relURL "/" }} → /
-{{ relURL "/articles" }} → /articles
-{{ relURL "style.css" }} → /style.css
+{{ relURL "/" }} → /
+{{ relURL "/articles" }} → /articles
+{{ relURL "/style.css" }} → /style.css
```
With `baseURL = https://example.org/docs/`
```go-html-template
-{{ relURL "/" }} → /
-{{ relURL "/articles" }} → /articles
-{{ relURL "/style.css" }} → /style.css
+{{ relURL "/" }} → /
+{{ relURL "/articles" }} → /articles
+{{ relURL "/style.css" }} → /style.css
```
-{{% note %}}
-The last three examples are not desirable in most situations. As a best practice, never include a leading slash when using this function.
-{{% /note %}}
-
-[`relLangURL`]: /functions/urls/rellangurl/
+[`urls.RelLangURL`]: /functions/urls/rellangurl/
diff --git a/content/en/functions/urls/_common/_index.md b/content/en/functions/urls/_common/_index.md
index 47d5812fb..4328d4d14 100644
--- a/content/en/functions/urls/_common/_index.md
+++ b/content/en/functions/urls/_common/_index.md
@@ -7,7 +7,7 @@ cascade:
---
<!--
-Files within this headless branch bundle are markdown snippets. Each file must contain front matter delimiters, though front matter fields are not required.
+Files within this headless branch bundle are Markdown snippets. Each file must contain front matter delimiters, though front matter fields are not required.
Include the rendered content using the "include" shortcode.
-->
diff --git a/content/en/functions/urls/_common/anchorize-vs-urlize.md b/content/en/functions/urls/_common/anchorize-vs-urlize.md
index 0f01bcf78..718c14098 100644
--- a/content/en/functions/urls/_common/anchorize-vs-urlize.md
+++ b/content/en/functions/urls/_common/anchorize-vs-urlize.md
@@ -4,8 +4,8 @@
The [`anchorize`] and [`urlize`] functions are similar:
-[`anchorize`]: /functions/urls/anchorize
-[`urlize`]: /functions/urls/urlize
+[`anchorize`]: /functions/urls/anchorize/
+[`urlize`]: /functions/urls/urlize/
- Use the `anchorize` function to generate an HTML `id` attribute value
- Use the `urlize` function to sanitize a string for usage in a URL
diff --git a/content/en/getting-started/_index.md b/content/en/getting-started/_index.md
index 780b96a62..1648f0224 100644
--- a/content/en/getting-started/_index.md
+++ b/content/en/getting-started/_index.md
@@ -1,12 +1,12 @@
---
title: Getting started
-linkTitle: Overview
+linkTitle: In this section
description: Quick start and guides for installing Hugo on your preferred operating system.
categories: []
keywords: []
menu:
docs:
- identifier: getting-started-overview
+ identifier: getting-started-in-this-section
parent: getting-started
weight: 10
weight: 10
diff --git a/content/en/getting-started/configuration-markup.md b/content/en/getting-started/configuration-markup.md
index 607301d3a..ab3dfa221 100644
--- a/content/en/getting-started/configuration-markup.md
+++ b/content/en/getting-started/configuration-markup.md
@@ -2,7 +2,7 @@
title: Configure markup
description: Configure rendering of markup to HTML.
categories: [getting started,fundamentals]
-keywords: [configuration,highlighting]
+keywords: [markup,markdown,goldmark,asciidoc,asciidoctor,highlighting]
menu:
docs:
parent: getting-started
@@ -14,16 +14,16 @@ toc: true
## Default handler
-By default, Hugo uses [Goldmark] to render markdown to HTML.
+Hugo uses [Goldmark] to render Markdown to HTML.
{{< code-toggle file=hugo >}}
[markup]
defaultMarkdownHandler = 'goldmark'
{{< /code-toggle >}}
-Files with the `.md` or `.markdown` extension are processed as markdown, provided that you have not specified a different [content format] using the `markup` field in front matter.
+Files with the `.md` 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.
+To use a different renderer for Markdown files, specify one of `asciidocext`, `org`, `pandoc`, or `rst` in your site configuration.
defaultMarkdownHandler|Description
:--|:--
@@ -33,41 +33,86 @@ defaultMarkdownHandler|Description
`pandoc`|[Pandoc]
`rst`|[reStructuredText]
-To use Asciidoc, Pandoc, or reStructuredText you must install the relevant renderer and update your [security policy].
+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 alternate 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).
+Unless you need a unique capability provided by one of the alternate 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/#list-of-content-formats
+[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-model/#security-policy
+[security policy]: /about/security/#security-policy
## Goldmark
-This is the default configuration for the Goldmark markdown renderer:
+This is the default configuration for the Goldmark Markdown renderer:
{{< code-toggle config=markup.goldmark />}}
-For details on the extensions, refer to the [Goldmark documentation](https://github.com/yuin/goldmark/#built-in-extensions).
+### 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 extension
+
+{{< new-in 0.126.0 >}}
+
+Configure the extras extension to enable [inserted text], [mark text], [subscript], and [superscript] elements in Markdown.
+
+Element|Markdown|Rendered
+:--|:--|:--
+Inserted text|`++foo++`|`<ins>foo</ins>`
+Mark text|`==bar==`|`<mark>bar</mark>`
+Subscript|`H~2~O`|`H<sub>2</sub>O`
+Superscript|`1^st^`|`1<sup>st</sup>`
+
+[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
+
+#### Passthrough extension
+
+{{< new-in 0.122.0 >}}
-Some settings explained:
+Enable the passthrough extension to include mathematical equations and expressions in Markdown using LaTeX or TeX typesetting syntax. See [mathematics in Markdown] for details.
-hardWraps
-: By default, Goldmark ignores newlines within a paragraph. Set to `true` to render newlines as `<br>` elements.
+[mathematics in Markdown]: content-management/mathematics/
-unsafe
-: By default, Goldmark does not render raw HTML and potentially dangerous links. If you have lots of inline HTML and/or JavaScript, you may need to turn this on.
+#### Typographer extension
-typographer
-: The typographer extension replaces certain character combinations with HTML entities as specified below:
+The Typographer extension replaces certain character combinations with HTML entities as specified below:
Markdown|Replaced by|Description
:--|:--|:--
@@ -82,104 +127,164 @@ Markdown|Replaced by|Description
`”`|`&rdquo;`|right double quote
`’`|`&rsquo;`|right single quote
-attribute
-: Enable custom attribute support for titles and blocks by adding attribute lists inside single curly brackets (`{.myclass class="class1 class2" }`) and placing it _after the Markdown element it decorates_, on the same line for titles and on a new line directly below for blocks.
+### Goldmark settings explained
-Hugo supports adding attributes (e.g. CSS classes) to Markdown blocks, e.g. tables, lists, paragraphs etc.
+Most of the Goldmark settings above are self-explanatory, but some require explanation.
-A blockquote with a CSS class:
+###### duplicateResourceFiles
-```md
-> foo
-> bar
-{.myclass}
-```
+{{< new-in 0.123.0 >}}
-There are some current limitations: For tables you can currently only apply it to the full table, and for lists the `ul`/`ol`-nodes only, e.g.:
-
-```md
-* Fruit
- * Apple
- * Orange
- * Banana
- {.fruits}
-* Dairy
- * Milk
- * Cheese
- {.dairies}
-{.list}
-```
+(`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`.
-Note that attributes in [code fences](/content-management/syntax-highlighting/#highlighting-in-code-fences) must come after the opening tag, with any other highlighting processing instruction, e.g.:
+[multilingual page resources]: /content-management/page-resources/#multilingual
-````txt
-```go {.myclass linenos=table,hl_lines=[8,"15-17"],linenostart=199}
-// ... code
-```
-````
+{{% 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
-autoHeadingIDType ("github")
-: The strategy used for creating auto IDs (anchor names). Available types are `github`, `github-ascii` and `blackfriday`. `github` produces GitHub-compatible IDs, `github-ascii` will drop any non-ASCII characters after accent normalization, and `blackfriday` will make the IDs compatible with Blackfriday, the default Markdown engine before Hugo 0.60. Note that if Goldmark is your default Markdown engine, this is also the strategy used in the [anchorize](/functions/urls/anchorize) template func.
+This is also the strategy used by the [anchorize](/functions/urls/anchorize) template function. Default is `github`.
-## Asciidoc
+###### parser.attribute.block
-This is the default configuration for the AsciiDoc markdown renderer:
+(`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 />}}
-attributes
-: (`map`) Variables to be referenced in your AsciiDoc file. This is a list of variable name/value maps. See Asciidoctor’s [attributes].
+### AsciiDoc settings explained
+
+###### attributes
+
+(`map`) A map of key-value pairs, each a document attributes,See Asciidoctor’s [attributes].
[attributes]: https://asciidoctor.org/docs/asciidoc-syntax-quick-reference/#attributes-and-substitutions
-backend:
-: (`string`) Don’t change this unless you know what you are doing.
+###### backend
+
+(`string`) The backend output file format. Default is `html5`.
-extensions
-: (`[]string`) Possible extensions are `asciidoctor-html5s`, `asciidoctor-bibtex`, `asciidoctor-diagram`, `asciidoctor-interdoc-reftext`, `asciidoctor-katex`, `asciidoctor-latex`, `asciidoctor-mathematical`, and `asciidoctor-question`.
+###### extensions
-failureLevel
-: (`string`) The minimum logging level that triggers a non-zero exit code (failure).
+(`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`.
-noHeaderOrFooter
-: (`bool`) Output an embeddable document, which excludes the header, the footer, and everything outside the body of the document. Don’t change this unless you know what you are doing.
+{{% 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 %}}
-preserveTOC
-: (`bool`) By default, Hugo removes the table of contents generated by Asciidoctor and provides it through the built-in variable `.TableOfContents` to enable further customization and better integration with the various Hugo themes. This option can be set to true to preserve Asciidoctor’s TOC in the generated page.
+###### failureLevel
-safeMode
-: (`string`) Safe mode level `unsafe`, `safe`, `server`, or `secure`. Don’t change this unless you know what you are doing.
+(`string`) The minimum logging level that triggers a non-zero exit code (failure). Default is `fatal`.
-sectionNumbers
-: (`bool`) Auto-number section titles.
+###### noHeaderOrFooter
-trace
-: (`bool`) Include backtrace information on errors.
+(`bool`) If `true`, outputs an embeddable document, which excludes the header, the footer, and everything outside the body of the document. Default is `true`.
-verbose
-: (`bool`) Verbosely print processing information and configuration file checks to stderr.
+###### preserveTOC
-workingFolderCurrent
-: (`bool`) Sets the working directory to be the same as that of the AsciiDoc file being processed, so that [include] will work with relative paths. This setting uses the asciidoctor cli parameter --base-dir and attribute outdir=. For rendering diagrams with [asciidoctor-diagram], `workingFolderCurrent` must be set to `true`.
+(`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`.
-[asciidoctor-diagram]: https://asciidoctor.org/docs/asciidoctor-diagram/
-[include]: https://asciidoctor.org/docs/asciidoc-syntax-quick-reference/#include-files
+[`TableOfContents`]: /methods/page/tableofcontents/
+
+###### safeMode
-Notice that for security concerns only extensions that do not have path separators (either `\`, `/` or `.`) are allowed. That means that extensions can only be invoked if they are in the Ruby's `$LOAD_PATH` (ie. most likely, the extension has been installed by the user). Any extension declared relative to the website's path will not be accepted.
+(`string`) The safe mode level, one of `unsafe`, `safe`, `server`, or `secure`. Default is `unsafe`.
-Example of how to set extensions and attributes:
+###### sectionNumbers
-```yml
+(`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 troubleshooting
-In a complex Asciidoctor environment it is sometimes helpful to debug the exact call to your external helper with all
-parameters. Run Hugo with `-v`. You will get an output like
+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 -] ...
@@ -200,19 +305,18 @@ For CSS, see [Generate Syntax Highlighter CSS](/content-management/syntax-highli
## Table of contents
+This is the default configuration for the table of contents, applicable to Goldmark and Asciidoctor:
+
{{< code-toggle config=markup.tableOfContents />}}
-These settings only works for the Goldmark renderer:
+###### startLevel
-startLevel
-: The heading level, values starting at 1 (`h1`), to start render the table of contents.
+(`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
-: The heading level, inclusive, to stop render the table of contents.
+###### endLevel
-ordered
-: If `true`, generates an ordered list instead of an unordered list.
+(`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`.
-## Render hooks
+###### ordered
-See [Markdown Render Hooks](/templates/render-hooks/).
+(`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
index 3ce0077ba..35c7d780e 100644
--- a/content/en/getting-started/configuration.md
+++ b/content/en/getting-started/configuration.md
@@ -73,15 +73,11 @@ my-project/
│ ├── menus.en.toml
│ ├── menus.de.toml
│ └── params.toml
- ├── production/
- │ ├── hugo.toml
- │ └── params.toml
- └── staging/
- ├── hugo.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`, `server`, `services`, `sitemap`, and `taxonomies`.
+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
@@ -226,25 +222,33 @@ See [Configure Build](#configure-build).
###### buildFuture
-(`bool`) Include content with publishdate in the future. Default is `false`.
+(`bool`) Include content with a future publication date. Default is `false`.
###### caches
See [Configure File Caches](#configure-file-caches).
+###### 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 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#front-matter-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#front-matter-cascade). For a multilingual website, define the `[[cascade]]` in [Site Config](../../getting-started/configuration/#cascade).
+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 %}}
###### canonifyURLs
-(`bool`) Enable to turn relative URLs into absolute. Default is `false`. See&nbsp;[details](/content-management/urls/#canonical-urls).
+(`bool`) See [details](/content-management/urls/#canonical-urls) before enabling this feature. Default is `false`.
###### cleanDestinationDir
@@ -324,8 +328,11 @@ See [image processing configuration](/content-management/image-processing/#imagi
(`string`) A language tag as defined by [RFC 5646](https://datatracker.ietf.org/doc/html/rfc5646). This value is used to populate:
-- The `<language>` element in the internal [RSS template](https://github.com/gohugoio/hugo/blob/master/tpl/tplimpl/embedded/templates/_default/rss.xml)
-- The `lang` attribute of the `<html>` element in the internal [alias template](https://github.com/gohugoio/hugo/blob/master/tpl/tplimpl/embedded/templates/alias.html)
+- The `<language>` element in the embedded [RSS template]({{% eturl rss %}})
+- The `lang` attribute of the `<html>` 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
@@ -369,7 +376,7 @@ Module configuration see [module configuration](/hugo-modules/configuration/).
###### outputFormats
-See [Configure Output Formats](#configure-additional-output-formats).
+See [custom output formats].
###### paginate
@@ -385,27 +392,33 @@ See [Content Management](/content-management/urls/#permalinks).
###### pluralizeListTitles
-(`bool`) Pluralize titles in lists. Default is `true`.
+(`bool`) Whether to pluralize automatic list titles. Applicable to section pages. Default is `true`.
###### publishDir
(`string`) The directory to 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`) Enable this to make all relative URLs relative to content root. Note that this does not affect absolute URLs. Default is `false`. See&nbsp;[details](/content-management/urls/#relative-urls).
+(`bool`) See [details](/content-management/urls/#relative-urls) before enabling this feature. Default is `false`.
-###### refLinksErrorLevel
+###### renderSegments
-(`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`.
+{{< new-in 0.124.0 >}}
-###### refLinksNotFoundURL
-
-(`string`) URL to be used as a placeholder when a page reference cannot be found in `ref` or `relref`. Is used as-is.
+(`string slice`) 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.
###### removePathAccents
@@ -421,7 +434,11 @@ See [Menus](/content-management/menus/#define-automatically).
###### security
-See [Security Policy](/about/security-model/#security-policy).
+See [Security Policy](/about/security/#security-policy).
+
+###### segments
+
+See [Segments](#configure-segments).
###### sitemap
@@ -429,7 +446,9 @@ Default [sitemap configuration](/templates/sitemap-template/#configuration).
###### summaryLength
-(`int`) The length of text in words to show in a [`.Summary`](/content-management/summaries/#automatic-summary-splitting). Default is `70`.
+(`int`) Applicable to automatic summaries, the approximate number of words to render when calling the [`Summary`] method on a `Page` object. Default is `70`.
+
+[`Summary`]: /methods/page/summary/
###### taxonomies
@@ -605,6 +624,39 @@ 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.
@@ -626,15 +678,31 @@ firstupper
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
+[`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], typically one of `development`, `staging`, or `production`.
+
+[environment]: /getting-started/glossary/#environment
+
+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
-: Can be set to increase or reduce the number of workers used in parallel processing in Hugo. If not set, the number of logical CPUs will be used.
+: (`int`) The number of workers used in parallel processing. Default is the number of logical CPUs.
## Configure with environment variables
@@ -726,10 +794,6 @@ The above will try first to extract the value for `.Date` from the file name, th
`: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 additional output formats
-
-Hugo v0.20 introduced the ability to render your content to multiple output formats (e.g., to JSON, AMP html, or CSV). See [Output Formats] for information on how to add these values to your Hugo project's configuration file.
-
## Configure minify
See the [tdewolff/minify] project page for details.
@@ -769,7 +833,7 @@ dir
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 env variable `HUGO_CACHEDIR`.
+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:
@@ -779,10 +843,123 @@ If this is not set, Hugo will use, in order of preference:
If you want to know the current value of `cacheDir`, you can run `hugo config`, e.g: `hugo config | grep cachedir`.
-[`time`]: /functions/time/astime
-[`.Site.Params`]: /variables/site/
-[directory structure]: /getting-started/directory-structure
+[`time`]: /functions/time/astime/
+[`.Site.Params`]: /method/site/params/
+[directory structure]: /getting-started/directory-structure/
[lookup order]: /templates/lookup-order/
-[Output Formats]: /templates/output-formats/
+[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](#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] of the page.
+
+output
+: The [output format] 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/
+[kind]: /getting-started/glossary/#page-kind
+[output format]: /getting-started/glossary/#output-format
+[type]: /getting-started/glossary/#content-type
+
diff --git a/content/en/getting-started/directory-structure.md b/content/en/getting-started/directory-structure.md
index f91849375..2331d8838 100644
--- a/content/en/getting-started/directory-structure.md
+++ b/content/en/getting-started/directory-structure.md
@@ -78,38 +78,49 @@ my-site/
Each of the subdirectories contributes to the content, structure, behavior, or presentation of your site.
-archetypes
-: The `archetypes` directory contains templates for new content. See&nbsp;[details](/content-management/archetypes/).
+###### 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&nbsp;[details](/hugo-pipes/introduction/).
+The `archetypes` directory contains templates for new content. See&nbsp;[details](/content-management/archetypes/).
-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&nbsp;[details](/getting-started/configuration/#configuration-directory).
+###### assets
-content
-: The `content` directory contains the markup files (typically markdown) and page resources that comprise the content of your site. See&nbsp;[details](/content-management/organization/).
+The `assets` directory contains global resources typically passed through an asset pipeline. This includes resources such as images, CSS, Sass, JavaScript, and TypeScript. See&nbsp;[details](/hugo-pipes/introduction/).
-data
-: The `data` directory contains data files (JSON, TOML, YAML, or XML) that augment content, configuration, localization, and navigation. See&nbsp;[details](/templates/data-templates/).
+###### config
-i18n
-: The `i18n` directory contains translation tables for multilingual sites. See&nbsp;[details](/content-management/multilingual/).
+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&nbsp;[details](/getting-started/configuration/#configuration-directory).
-layouts
-: The layouts directory contains templates to transform content, data, and resources into a complete website. See&nbsp;[details](/templates/).
+###### content
-public
-: The `public` directory contains the published website, generated when you run the `hugo` command. Hugo recreates this directory and its content as needed. See&nbsp;[details](/getting-started/usage/#build-your-site).
+The `content` directory contains the markup files (typically Markdown) and page resources that comprise the content of your site. See&nbsp;[details](/content-management/organization/).
-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.
+###### data
-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](/getting-started/glossary/#page-bundle) and [asset pipelines](/hugo-pipes/introduction/), the `static` directory was also used for images, CSS, and JavaScript. See&nbsp;[details](/content-management/static-files/).
+The `data` directory contains data files (JSON, TOML, YAML, or XML) that augment content, configuration, localization, and navigation. See&nbsp;[details](/content-management/data-sources/).
-themes
-: The `themes` directory contains one or more [themes](/getting-started/glossary/#theme), each in its own subdirectory.
+###### i18n
+
+The `i18n` directory contains translation tables for multilingual sites. See&nbsp;[details](/content-management/multilingual/).
+
+###### layouts
+
+The layouts directory contains templates to transform content, data, and resources into a complete website. See&nbsp;[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&nbsp;[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](/getting-started/glossary/#page-bundle) 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](/getting-started/glossary/#theme), each in its own subdirectory.
## Union file system
@@ -150,7 +161,7 @@ target = 'content'
{{% note %}}
When you overlay one directory on top of another, you must mount both directories.
-If you think you need a symbolic link in your project directory, use Hugo's union file system instead.
+Hugo does not follow symbolic links. If you need the functionality provided by symbolic links, use Hugo's union file system instead.
{{% /note %}}
After mounting, the union file system has this structure:
diff --git a/content/en/getting-started/external-learning-resources/build-websites-with-hugo.png b/content/en/getting-started/external-learning-resources/build-websites-with-hugo.png
new file mode 100644
index 000000000..ebed7e89f
--- /dev/null
+++ b/content/en/getting-started/external-learning-resources/build-websites-with-hugo.png
Binary files differ
diff --git a/content/en/getting-started/external-learning-resources/hia.jpg b/content/en/getting-started/external-learning-resources/hia.jpg
deleted file mode 100644
index 601947a70..000000000
--- a/content/en/getting-started/external-learning-resources/hia.jpg
+++ /dev/null
Binary files differ
diff --git a/content/en/getting-started/external-learning-resources/hugo-in-action.png b/content/en/getting-started/external-learning-resources/hugo-in-action.png
new file mode 100644
index 000000000..7bc5c9930
--- /dev/null
+++ b/content/en/getting-started/external-learning-resources/hugo-in-action.png
Binary files differ
diff --git a/content/en/getting-started/external-learning-resources/index.md b/content/en/getting-started/external-learning-resources/index.md
index 634439bc6..d30305c2e 100644
--- a/content/en/getting-started/external-learning-resources/index.md
+++ b/content/en/getting-started/external-learning-resources/index.md
@@ -1,6 +1,6 @@
---
title: External learning resources
-description: A list of tutorials and books on Hugo.
+description: Use these third-party resources to learn Hugo.
categories: [getting started]
keywords: [books, tutorials, learning, usage]
menu:
@@ -8,30 +8,83 @@ menu:
parent: getting-started
weight: 70
weight: 70
+toc: true
---
## Books
### Hugo In Action
-[![Hugo In Action](hia.jpg)](https://www.manning.com/books/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.
-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.
+[{{< img src="hugo-in-action.png" alt="Book cover: Hugo in Action" filter="process" filterArgs="resize x350 webp">}}](https://www.manning.com/books/hugo-in-action/)
+
+Author: Atishay Jain\
+Publisher: [Manning Publications](https://www.manning.com/books/hugo-in-action/)\
+Publication date: March 2022\
+Length: 488 pages\
+ISBN: 9781617297007
-[Hugo In Action Home Page](https://www.manning.com/books/hugo-in-action)
### Build Websites with Hugo
-[Build Websites with Hugo - Fast Web Development with Markdown (2020)](https://pragprog.com/titles/bhhugo/) by Brian P. Hogan.
+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/)
+
+
+Author: Brian P. Hogan\
+Publisher: [Pragmatic Bookshelf](https://pragprog.com/titles/bhhugo/build-websites-with-hugo/)\
+Publication date: May 2020\
+Length: 154 pages\
+ISBN: 9781680507263
+
+## Videos
+
+### 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.
+
+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/)
+1. [Hugo Partials](https://cloudcannon.com/tutorials/hugo-beginner-tutorial/hugo-partials/)
+1. [Hugo templating basics](https://cloudcannon.com/tutorials/hugo-beginner-tutorial/hugo-templating-basics/)
+1. [Blogging in Hugo](https://cloudcannon.com/tutorials/hugo-beginner-tutorial/blogging-in-hugo/)
+1. [Using Data in Hugo](https://cloudcannon.com/tutorials/hugo-beginner-tutorial/using-data-in-hugo/)
-## Beginner tutorials
+Creator: Mike Neumegen\
+Affiliation: [CloudCannon](https://cloudcannon.com/)\
+Creation date: April 2022
-### Hugo tutorial by CloudCannon
+#### Hugo Static Site Generator
-[Step-by-step written tutorial](https://cloudcannon.com/community/learn/hugo-beginner-tutorial/) to teach you the basics of creating a Hugo site.
+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!
-## Video tutorials
-* Mike Dane explains the various features of Hugo via dedicated tutorials on [YouTube](https://www.youtube.com/watch?list=PLLAZ4kZ9dFpOnyRlyS-liKL5ReHDcj4G3&v=qtIqKaDlqXo).
+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/)
+1. [Mac Installation](https://www.giraffeacademy.com/static-site-generators/hugo/installing-hugo-on-mac/)
+1. [Creating A New Site](https://www.giraffeacademy.com/static-site-generators/hugo/hugo-directory-structure/)
+1. [Installing & Using Themes](https://www.giraffeacademy.com/static-site-generators/hugo/installing-using-themes/)
+1. [Content Organization](https://www.giraffeacademy.com/static-site-generators/hugo/content-organization/)
+1. [Front Matter](https://www.giraffeacademy.com/static-site-generators/hugo/front-matter/)
+1. [Archetypes](https://www.giraffeacademy.com/static-site-generators/hugo/archetypes/)
+1. [Shortcodes](https://www.giraffeacademy.com/static-site-generators/hugo/archetypes/)
+1. [Taxonomies](https://www.giraffeacademy.com/static-site-generators/hugo/taxonomies/)
+1. [Template Basics](https://www.giraffeacademy.com/static-site-generators/hugo/introduction-to-templates/)
+1. [List Page Templates](https://www.giraffeacademy.com/static-site-generators/hugo/list-page-templates/)
+1. [Single Page Templates](https://www.giraffeacademy.com/static-site-generators/hugo/single-page-templates/)
+1. [Home Page Templates](https://www.giraffeacademy.com/static-site-generators/hugo/home-page-templates/)
+1. [Section Templates](https://www.giraffeacademy.com/static-site-generators/hugo/section-templates/)
+1. [Block Templates](https://www.giraffeacademy.com/static-site-generators/hugo/block-templates/)
+1. [Variables](https://www.giraffeacademy.com/static-site-generators/hugo/variables/)
+1. [Functions](https://www.giraffeacademy.com/static-site-generators/hugo/functions/)
+1. [Conditionals](https://www.giraffeacademy.com/static-site-generators/hugo/conditionals/)
+1. [Data Templates](https://www.giraffeacademy.com/static-site-generators/hugo/data-templates/)
+1. [Partial Templates](https://www.giraffeacademy.com/static-site-generators/hugo/partial-templates/)
+1. [Shortcode Templates](https://www.giraffeacademy.com/static-site-generators/hugo/shortcode-templates/)
+1. [Building & Hosting](https://www.giraffeacademy.com/static-site-generators/hugo/building-&-hosting/)
-* [Introduction to building your first Hugo site](https://cloudcannon.com/community/learn/hugo-beginner-tutorial/) by Mike Neumegen.
+Creator: Mike Dane\
+Affiliation: [Giraffe Academy](https://www.giraffeacademy.com/)\
+Creation date: September 2017
diff --git a/content/en/getting-started/glossary.md b/content/en/getting-started/glossary.md
index d4c1d0e26..c86c3fc97 100644
--- a/content/en/getting-started/glossary.md
+++ b/content/en/getting-started/glossary.md
@@ -11,25 +11,28 @@ weight: 60
# Use level 6 headings for each term in the glossary.
---
-[A](#action)
-[B](#bool)
-[C](#cache)
-[D](#default-sort-order)
-[E](#environment)
-[F](#field)
-[G](#global-resource)
-[I](#identifier)
-[K](#kind)
-[L](#layout)
-[M](#map)
-[O](#object)
-[P](#page-bundle)
-[R](#regular-page)
-[S](#scalar)
-[T](#taxonomic-weight)
-[U](#unmarshal)
-[V](#variable)
-[W](#walk)
+[A](#action)&nbsp;
+[B](#bool)&nbsp;
+[C](#cache)&nbsp;
+[D](#default-sort-order)&nbsp;
+[E](#environment)&nbsp;
+[F](#field)&nbsp;
+[G](#global-resource)&nbsp;
+[H](#headless-bundle)&nbsp;
+[I](#identifier)&nbsp;
+[K](#kind)&nbsp;
+[L](#layout)&nbsp;
+[M](#map)&nbsp;
+[N](#node)&nbsp;
+[O](#object)&nbsp;
+[P](#page-bundle)&nbsp;
+[R](#regular-page)&nbsp;
+[S](#scalar)&nbsp;
+[T](#taxonomic-weight)&nbsp;
+[U](#unmarshal)&nbsp;
+[V](#variable)&nbsp;
+[W](#walk)&nbsp;
+[Z](#zero-time)&nbsp;
###### action
@@ -57,7 +60,7 @@ A data type with two possible values, either `true` or `false`.
###### branch bundle
-A [page bundle](#page-bundle) with an&nbsp;_index.md file and zero or more [resources](#resource). Analogous to a physical branch, a branch bundle may have descendants including regular pages, [leaf bundles](/getting-started/glossary/#leaf-bundle), and other branch bundles. See&nbsp;[details](/content-management/page-bundles/).
+A directory that contains an _index.md file and zero or more [resources](#resource). 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. See&nbsp;[details](/content-management/page-bundles/).
###### build
@@ -75,13 +78,25 @@ A software component that stores data so that future requests for the same data
Within a template, to connect one or more [identifiers](#identifier) with a dot. An identifier can represent a method, object, or field. For example, `.Site.Params.author.name` or `.Date.UTC.Hour`.
+###### CJK
+
+A collective term for the Chinese, Japanese, and Korean languages. See [details](https://en.wikipedia.org/wiki/CJK_characters).
+
+###### CLI
+
+Command line interface.
+
###### collection
An [array](#array), [slice](#slice), or [map](#map).
+###### content adapter
+
+A template that dynamically creates pages when building a site. For example, use a content adapter to create pages from a remote data source such as JSON, TOML, YAML, or XML. See&nbsp;[details](/content-management/content-adapters/).
+
###### content format
-A markup language for creating content. Typically markdown, but may also be HTML, AsciiDoc, Org, Pandoc, or reStructuredText. See&nbsp;[details](/content-management/formats/).
+A markup language for creating content. Typically Markdown, but may also be HTML, AsciiDoc, Org, Pandoc, or reStructuredText. See&nbsp;[details](/content-management/formats/).
###### content type
@@ -93,7 +108,7 @@ A template called with the `.Page.Render` method. See&nbsp;[details](/templates/
###### context
-Represented by a dot "." within a [template action](#template-action), context is the current location in a data structure. For example, while iterating over a [collection](#collection) of pages, the context within each iteration is the page's data structure. The context received by each template depends on template type and/or how it was called. See&nbsp;[details](/templates/introduction/#the-dot).
+Represented by a dot "." within a [template action](#template-action), context is the current location in a data structure. For example, while iterating over a [collection](#collection) of pages, the context within each iteration is the page's data structure. The context received by each template depends on template type and/or how it was called. See&nbsp;[details](/templates/introduction/#context).
###### default sort order
@@ -107,15 +122,15 @@ A member of a slice or array.
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.
+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
+[`hugo.Environment`]: /functions/hugo/environment/
###### field
-A predefined key/value pair in front matter such as `date` or `title`. See&nbsp;also&nbsp;[parameter](#parameter).
+A predefined key-value pair in front matter such as `date` or `title`. See&nbsp;also&nbsp;[parameter](#parameter).
###### flag
@@ -146,10 +161,14 @@ Used within a [template action](#template-action), a function takes one or more
A file within the assets directory, or within any directory [mounted](/hugo-modules/configuration/#module-configuration-mounts) to the assets directory. Capture one or more global resources using the [`resources.Get`], [`resources.GetMatch`], [`resources.Match`], or [`resources.ByType`] functions.
-[`resources.Get`]: /functions/resources/get
-[`resources.GetMatch`]: /functions/resources/getmatch
-[`resources.Match`]: /functions/resources/match
-[`resources.ByType`]: /functions/resources/byType
+[`resources.Get`]: /functions/resources/get/
+[`resources.GetMatch`]: /functions/resources/getmatch/
+[`resources.Match`]: /functions/resources/match/
+[`resources.ByType`]: /functions/resources/byType/
+
+###### headless bundle
+
+An unpublished leaf or branch bundle whose content and resources you can include in other pages. See [build options](/content-management/build-options/).
###### identifier
@@ -187,7 +206,7 @@ See [template](#template).
###### leaf bundle
-A [page bundle](#page-bundle) with an index.md file and zero or more [resources](#resource). Analogous to a physical leaf, a leaf bundle is at the end of a branch. Hugo ignores content (but not resources) beneath the leaf bundle. See&nbsp;[details](/content-management/page-bundles/).
+A directory that contains an index.md file and zero or more [resources](#resource). Analogous to a physical leaf, a leaf bundle is at the end of a branch. It has no descendants. See&nbsp;[details](/content-management/page-bundles/).
###### list page
@@ -197,13 +216,19 @@ Any [page kind](#page-kind) that receives a page [collection](#collection) in [c
Adaptation of a site to meet language and regional requirements. This includes translations, language-specific media, date and currency formats, etc. See&nbsp;[details](/content-management/multilingual/) and the [W3C definition](https://www.w3.org/International/questions/qa-i18n). Abbreviated l10n.
+###### logical path
+
+{{< new-in 0.123.0 >}}
+
+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. <!-- You may also set this value using the `path` front matter field. --> See [examples](/methods/page/path/#examples).
+
###### map
An unordered group of elements, each indexed by a unique key. See the [Go&nbsp;documentation](https://go.dev/ref/spec#Map_types) for details.
-###### markdown attribute
+###### Markdown attribute
-A list of attributes, containing one or more key/value pairs, separated by spaces or commas, and wrapped by braces. Apply markdown attributes to images and block-level elements including blockquotes, fenced code blocks, headings, horizontal rules, lists, paragraphs, and tables. See&nbsp;[details](/getting-started/configuration-markup/#goldmark).
+A list of attributes, containing one or more key-value pairs, separated by spaces or commas, and wrapped by braces. Apply Markdown attributes to images and block-level elements including blockquotes, fenced code blocks, headings, horizontal rules, lists, paragraphs, and tables. See&nbsp;[details](/getting-started/configuration-markup/#goldmark).
###### marshal
@@ -217,6 +242,14 @@ Used within a [template action](#template-action) and associated with an [object
Like a [theme](#theme), a module is a packaged combination of [archetypes](#archetype), assets, content, data, [templates](#template), translation tables, static files, or configuration settings. A module may serve as the basis for a new site, or to augment an existing site. See&nbsp;[details](/hugo-modules/).
+###### node
+
+A class of [page kinds](#page-kind) including `home`, `section`, `taxonomy`, and `term`.
+
+###### noop
+
+An abbreviated form of "no operation", a _noop_ is a statement that does nothing.
+
###### object
A data structure with or without associated [methods](#method).
@@ -225,8 +258,8 @@ A data structure with or without associated [methods](#method).
Created by invoking the [`Alphabetical`] or [`ByCount`] method on a [taxonomy object](#taxonomy-object), which is a [map](#map), an ordered taxonomy is a [slice](#slice), where each element is an object that contains the [term](#term) and a slice of its [weighted pages](#weighted-page).
-[`Alphabetical`]: /methods/taxonomy/alphabetical
-[`ByCount`]: /methods/taxonomy/bycount
+[`Alphabetical`]: /methods/taxonomy/alphabetical/
+[`ByCount`]: /methods/taxonomy/bycount/
###### output format
@@ -242,7 +275,7 @@ A slice of page objects.
###### page kind
-A classification of pages, one of `home`, `page`, `section`, `taxonomy`, or `term`. See&nbsp;[details](/templates/section-templates/#page-kinds).
+A classification of pages, one of `home`, `page`, `section`, `taxonomy`, or `term`. See&nbsp;[details](/methods/page/kind/).
Note that there are also `RSS`, `sitemap`, `robotsTXT`, and `404` page kinds, but these are only available during the rendering of each of these respective page's kind and therefore *not* available in any of the `Pages` collections.
@@ -266,7 +299,7 @@ The process of [paginating](#paginate) a [section](#section) list.
###### parameter
-Typically, a user-defined key/value pair at the site or page level, but may also refer to a configuration setting or an [argument](#argument). See&nbsp;also&nbsp;[field](#field).
+Typically, a user-defined key-value pair at the site or page level, but may also refer to a configuration setting or an [argument](#argument). See&nbsp;also&nbsp;[field](#field).
###### partial
@@ -300,7 +333,7 @@ The host-relative URL of a published resource or a rendered page.
###### render hook
-A [template](#template) that overrides standard markdown rendering. See&nbsp;[details](/templates/render-hooks/).
+A [template](#template) that overrides standard Markdown rendering. See&nbsp;[details](/render-hooks).
###### remote resource
@@ -312,17 +345,24 @@ Any file consumed by the build process to augment or generate content, structure
Hugo supports three types of resources: [global](#global-resource), [page](#page-resource), and [remote](#remote-resource)
+###### resource type
+
+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/
+
###### scalar
A single value, one of [string](#string), [integer](#integer), [floating point](#floating-point), or [boolean](#boolean).
###### scratch pad
-Conceptually, a [map](#map) with [methods](#method) to set, get, update, and delete values. Attach the data structure to a `Page` object using the [`Scratch`] or [`Store`] methods, or created a locally scoped scratch pad using the [`newScratch`] function.
+Conceptually, a [map](#map) with [methods](#method) to set, get, update, and delete values. Attach the data structure to a `Page` object using the [`Scratch`] or [`Store`] methods, or create a locally scoped scratch pad using the [`newScratch`] function.
-[`Scratch`]: /methods/page/scratch
-[`Store`]: /methods/page/store
-[`newScratch`]: /functions/collections/newscratch
+[`Scratch`]: /methods/page/scratch/
+[`Store`]: /methods/page/store/
+[`newScratch`]: /functions/collections/newscratch/
###### section
@@ -334,7 +374,7 @@ Content with the "section" [page kind](#page-kind). Typically a listing of [regu
###### shortcode
-A [template](#template) called from within markdown, taking zero or more [arguments](#argument). See&nbsp;[details](/content-management/shortcodes/).
+A [template](#template) called from within Markdown, taking zero or more [arguments](#argument). See&nbsp;[details](/content-management/shortcodes/).
###### slice
@@ -344,6 +384,14 @@ A numbered sequence of elements. Unlike Go's [array](#array) data type, slices a
A sequence of bytes. For example, `"What is 6 times 7?"`&nbsp;.
+###### string literal (interpreted)
+
+Interpreted string literals are character sequences between double quotes, as in "foo". Within the quotes, any character may appear except a newline and an unescaped double quote. The text between the quotes forms the value of the literal, with backslash escapes interpreted. See [details](https://go.dev/ref/spec#String_literals).
+
+###### string literal (raw)
+
+Raw string literals are character sequences between backticks, as in \`bar\`. Within the backticks, any character may appear except a backtick. Backslashes have no special meaning and the string may contain newlines. Carriage return characters ('\r') inside raw string literals are discarded from the raw string value. See [details](https://go.dev/ref/spec#String_literals).
+
###### taxonomic weight
Defined in front matter and unique to each taxonomy, this [weight](#weight) determines the sort order of page collections contained within a [taxonomy object](#taxonomy-object). See&nbsp;[details](/templates/taxonomy-templates/#assign-weight).
@@ -394,7 +442,7 @@ To transform a serialized object into a data structure. For example, transformin
###### variable
-A user-defined [identifier](#identifier) prefaced with a `$` symbol, representing a value of any data type, initialized or assigned within a [template action](#template-action). For example, `$foo`&nbsp;and&nbsp;`$bar` are variables.
+A user-defined [identifier](#identifier) prepended with a `$` symbol, representing a value of any data type, initialized or assigned within a [template action](#template-action). For example, `$foo`&nbsp;and&nbsp;`$bar` are variables.
###### walk
@@ -407,3 +455,7 @@ Used to position an element within a collection sorted by weight. Assign weights
###### weighted page
Contained within a [taxonomy object](#taxonomy-object), a weighted page is a [map](#map) with two elements: a `Page` object, and its [taxonomic weight](#taxonomic-weight) as defined in front matter. Access the elements using the `Page` and `Weight` keys.
+
+###### zero time
+
+The _zero time_ is January 1, 0001, 00:00:00 UTC. Formatted per [RFC3339](https://www.rfc-editor.org/rfc/rfc3339) the _zero time_ is 0001-01-01T00:00:00-00:00.
diff --git a/content/en/getting-started/quick-start.md b/content/en/getting-started/quick-start.md
index a6c54b54c..6e67cb73b 100644
--- a/content/en/getting-started/quick-start.md
+++ b/content/en/getting-started/quick-start.md
@@ -110,7 +110,7 @@ Press `Ctrl + C` to stop Hugo's development server.
Add a new page to your site.
```text
-hugo new content posts/my-first-post.md
+hugo new content content/posts/my-first-post.md
```
Hugo created the file in the `content/posts` directory. Open the file with your editor.
@@ -125,7 +125,7 @@ draft = true
Notice the `draft` value in the [front matter] is `true`. By default, Hugo does not publish draft content when you build the site. Learn more about [draft, future, and expired content].
-Add some [markdown] to the body of the post, but do not change the `draft` value.
+Add some [Markdown] to the body of the post, but do not change the `draft` value.
[markdown]: https://commonmark.org/help/
@@ -151,8 +151,10 @@ hugo server -D
View your site at the URL displayed in your terminal. Keep the development server running as you continue to add and change content.
+When satisfied with your new content, set the front matter `draft` parameter to `false`.
+
{{% note %}}
-Hugo's rendering engine conforms to the CommonMark [specification] for markdown. The CommonMark organization provides a useful [live testing tool] powered by the reference implementation.
+Hugo's rendering engine conforms to the CommonMark [specification] for Markdown. The CommonMark organization provides a useful [live testing tool] powered by the reference implementation.
[live testing tool]: https://spec.commonmark.org/dingus/
[specification]: https://spec.commonmark.org/
@@ -216,13 +218,13 @@ 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
-[directory structure]: /getting-started/directory-structure
+[directory structure]: /getting-started/directory-structure/
[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
+[front matter]: /content-management/front-matter/
[Git submodule]: https://git-scm.com/book/en/v2/Git-Tools-Submodules
[hosting and deployment]: /hosting-and-deployment/
[Install Git]: https://git-scm.com/book/en/v2/Getting-Started-Installing-Git
diff --git a/content/en/getting-started/usage.md b/content/en/getting-started/usage.md
index 268aed2e4..b19920907 100644
--- a/content/en/getting-started/usage.md
+++ b/content/en/getting-started/usage.md
@@ -23,7 +23,7 @@ hugo version
You should see something like:
```text
-hugo v0.122.0-b9a03bd59d5f71a529acb3e33f995e0ef332b3aa+extended linux/amd64 BuildDate=2024-01-26T15:54:24Z VendorInfo=gohugoio
+hugo v0.123.0-3c8a4713908e48e6523f058ca126710397aa4ed5+extended linux/amd64 BuildDate=2024-02-19T16:32:38Z VendorInfo=gohugoio
```
## Display available commands
@@ -65,6 +65,16 @@ Hugo allows you to set `draft`, `date`, `publishDate`, and `expiryDate` in the [
- The `publishDate` is in the future
- The `expiryDate` is in the past
+{{< new-in 0.123.0 >}}
+
+{{% note %}}
+Hugo publishes descendants of draft, future, and expired [node] 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
+[node]: /getting-started/glossary/#node
+{{% /note %}}
+
You can override the default behavior when running `hugo` or `hugo server` with command line flags:
```sh
@@ -130,7 +140,7 @@ public/
├── categories/
│ ├── index.html
│ └── index.xml <-- RSS feed for this section
-├── post/
+├── posts/
│ ├── my-first-post/
│ │ └── index.html
│ ├── index.html
diff --git a/content/en/hosting-and-deployment/_index.md b/content/en/hosting-and-deployment/_index.md
index 35fd3cf05..b6f54d3fa 100644
--- a/content/en/hosting-and-deployment/_index.md
+++ b/content/en/hosting-and-deployment/_index.md
@@ -1,12 +1,12 @@
---
title: Hosting and deployment
-linkTitle: Overview
+linkTitle: In this section
description: Site builds, automated deployments, and popular hosting solutions.
categories: []
keywords: []
menu:
docs:
- identifier: hosting-and-deployment-overview
+ identifier: hosting-and-deployment-in-this-section
parent: hosting-and-deployment
weight: 1
weight: 1
diff --git a/content/en/hosting-and-deployment/hosting-on-github/index.md b/content/en/hosting-and-deployment/hosting-on-github/index.md
index c3da5ba3e..5460193a7 100644
--- a/content/en/hosting-and-deployment/hosting-on-github/index.md
+++ b/content/en/hosting-and-deployment/hosting-on-github/index.md
@@ -1,8 +1,8 @@
---
title: Host on GitHub Pages
-description: Deploy Hugo as a GitHub Pages project or personal/organizational site and automate the whole process with GitHub Actions
+description: Host your site on GitHub Pages with continuous deployment using project, user, or organization pages.
categories: [hosting and deployment]
-keywords: [hosting,github]
+keywords: [hosting]
menu:
docs:
parent: hosting-and-deployment
@@ -10,8 +10,6 @@ toc: true
aliases: [/tutorials/github-pages-blog/]
---
-GitHub provides free and fast static hosting over SSL for personal, organization, or project pages directly from a GitHub repository via its GitHub Pages service and automating development workflows and build with GitHub Actions.
-
## Prerequisites
1. [Create a GitHub account]
@@ -99,7 +97,7 @@ jobs:
build:
runs-on: ubuntu-latest
env:
- HUGO_VERSION: 0.122.0
+ HUGO_VERSION: 0.127.0
steps:
- name: Install Hugo CLI
run: |
@@ -122,13 +120,14 @@ jobs:
# For maximum backward compatibility with Hugo modules
HUGO_ENVIRONMENT: production
HUGO_ENV: production
+ TZ: America/Los_Angeles
run: |
hugo \
--gc \
--minify \
--baseURL "${{ steps.pages.outputs.base_url }}/"
- name: Upload artifact
- uses: actions/upload-pages-artifact@v2
+ uses: actions/upload-pages-artifact@v3
with:
path: ./public
@@ -142,7 +141,7 @@ jobs:
steps:
- name: Deploy to GitHub Pages
id: deployment
- uses: actions/deploy-pages@v3
+ uses: actions/deploy-pages@v4
{{< /code >}}
Step 7
diff --git a/content/en/hosting-and-deployment/hosting-on-gitlab.md b/content/en/hosting-and-deployment/hosting-on-gitlab.md
index 87c764f00..c628922cd 100644
--- a/content/en/hosting-and-deployment/hosting-on-gitlab.md
+++ b/content/en/hosting-and-deployment/hosting-on-gitlab.md
@@ -27,8 +27,8 @@ Define your [CI/CD](https://docs.gitlab.com/ee/ci/quick_start/) jobs by creating
{{< code file=.gitlab-ci.yml copy=true >}}
variables:
- DART_SASS_VERSION: 1.70.0
- HUGO_VERSION: 0.122.0
+ DART_SASS_VERSION: 1.77.1
+ HUGO_VERSION: 0.126.0
NODE_VERSION: 20.x
GIT_DEPTH: 0
GIT_STRATEGY: clone
@@ -36,7 +36,7 @@ variables:
TZ: America/Los_Angeles
image:
- name: golang:1.20.6-bookworm
+ name: golang:1.22.1-bookworm
pages:
script:
diff --git a/content/en/hosting-and-deployment/hosting-on-netlify.md b/content/en/hosting-and-deployment/hosting-on-netlify.md
deleted file mode 100644
index 2dcdd95f5..000000000
--- a/content/en/hosting-and-deployment/hosting-on-netlify.md
+++ /dev/null
@@ -1,145 +0,0 @@
----
-title: Host on Netlify
-description: Netlify can host your Hugo site with CDN, continuous deployment, 1-click HTTPS, an admin GUI, and its own CLI.
-categories: [hosting and deployment]
-keywords: [hosting,netlify]
-menu:
- docs:
- parent: hosting-and-deployment
-toc: true
----
-
-[Netlify][netlify] provides continuous deployment services, global CDN, ultra-fast DNS, atomic deploys, instant cache invalidation, one-click SSL, a browser-based interface, a CLI, and many other features for managing your Hugo website.
-
-## Assumptions
-
-* You have an account with GitHub, GitLab, or Bitbucket.
-* You have completed the [Quick Start] or have a Hugo website you are ready to deploy and share with the world.
-* You do not already have a Netlify account.
-
-## Create a Netlify account
-
-Go to [app.netlify.com] and select your preferred sign up method. This will likely be a hosted Git provider, although you also have the option to sign up with an email address.
-
-The following examples use GitHub, but other git providers will follow a similar process.
-
-![Screenshot of the homepage for app.netlify.com, containing links to the most popular hosted git solutions.](/images/hosting-and-deployment/hosting-on-netlify/netlify-signup.jpg)
-
-Selecting GitHub will bring up an authorization modal for authentication. Select "Authorize application."
-
-![Screenshot of the authorization popup for Netlify and GitHub.](/images/hosting-and-deployment/hosting-on-netlify/netlify-first-authorize.jpg)
-
-## Create a new site with continuous deployment
-
-You're now already a Netlify member and should be brought to your new dashboard. Select "New site from git."
-
-![Screenshot of the blank Netlify admin panel with no sites and highlighted 'add new site' button'](/images/hosting-and-deployment/hosting-on-netlify/netlify-add-new-site.jpg)
-
-Netlify will then start walking you through the steps necessary for continuous deployment. First, you'll need to select your git provider again, but this time you are giving Netlify added permissions to your repositories.
-
-![Screenshot of step 1 of create a new site for Netlify: selecting the git provider](/images/hosting-and-deployment/hosting-on-netlify/netlify-create-new-site-step-1.jpg)
-
-And then again with the GitHub authorization modal:
-
-![Screenshot of step 1 of create a new site for Netlify: selecting the git provider](/images/hosting-and-deployment/hosting-on-netlify/netlify-authorize-added-permissions.jpg)
-
-Select the repo you want to use for continuous deployment. If you have a large number of repositories, you can filter through them in real time using repo search:
-
-![Screenshot of step 1 of create a new site for Netlify: selecting the git provider](/images/hosting-and-deployment/hosting-on-netlify/netlify-create-new-site-step-2.jpg)
-
-Once selected, you'll be brought to a screen for basic setup. Here you can select the branch you want to publish, your [build command], and your publish (i.e. deploy) directory. The publish directory should mirror that of what you've set in your [site configuration], the default of which is `public`. The following steps assume you are publishing from the `master` branch.
-
-## Configure Hugo version in Netlify
-
-You can [set Hugo version](https://www.netlify.com/blog/2017/04/11/netlify-plus-hugo-0.20-and-beyond/) for your environments in `netlify.toml` file or set `HUGO_VERSION` as a build environment variable in the Netlify console.
-
-For production:
-
-{{< code file=netlify.toml >}}
-[context.production.environment]
- HUGO_VERSION = "0.122.0"
-{{< /code >}}
-
-For testing:
-
-{{< code file=netlify.toml >}}
-[context.deploy-preview.environment]
- HUGO_VERSION = "0.122.0"
-{{< /code >}}
-
-The Netlify configuration file can be a little hard to understand and get right for the different environment, and you may get some inspiration and tips from this site's `netlify.toml`:
-
-{{< readfile file=netlify.toml highlight=toml >}}
-
-## Build and deploy site
-
-In the Netlify console, selecting "Deploy site" will immediately take you to a terminal for your build:.
-
-![Animated gif of deploying a site to Netlify, including the terminal read out for the build.](/images/hosting-and-deployment/hosting-on-netlify/netlify-deploying-site.gif)
-
-Once the build is finished---this should only take a few seconds--you should now see a "Hero Card" at the top of your screen letting you know the deployment is successful. The Hero Card is the first element that you see in most pages. It allows you to see a quick summary of the page and gives access to the most common/pertinent actions and information. You'll see that the URL is automatically generated by Netlify. You can update the URL in "Settings."
-
-![Screenshot of successful deploy badge at the top of a deployments screen from within the Netlify admin.](/images/hosting-and-deployment/hosting-on-netlify/netlify-deploy-published.jpg)
-
-![Screenshot of homepage to https://hugo-netlify-example.netlify.com, which is mostly dummy text](/images/hosting-and-deployment/hosting-on-netlify/netlify-live-site.jpg)
-
-[Visit the live site][visit].
-
-Now every time you push changes to your hosted git repository, Netlify will rebuild and redeploy your site.
-
-See [this blog post](https://www.netlify.com/blog/2017/04/11/netlify-plus-hugo-0.20-and-beyond/) for more details about how Netlify handles Hugo versions.
-
-## Use Hugo themes with Netlify
-
-The `git clone` method for installing themes is not supported by Netlify. If you were to use `git clone`, it would require you to recursively remove the `.git` subdirectory from the theme folder and would therefore prevent compatibility with future versions of the theme.
-
-A *better* approach is to install a theme as a proper git submodule. You can [read the GitHub documentation for submodules][ghsm] or those found on [Git's website][gitsm] for more information, but the command is similar to that of `git clone`:
-
-```txt
-cd themes
-git submodule add https://github.com/<THEMECREATOR>/<THEMENAME>
-```
-
-It is recommended to only use stable versions of a theme (if it’s versioned) and always check the changelog. This can be done by checking out a specific release within the theme's directory.
-
-Switch to the theme's directory and list all available versions:
-
-```txt
-cd themes/<theme>
-git tag
-# exit with q
-```
-
-You can checkout a specific version as follows:
-
-```txt
-git checkout tags/<version-name>
-```
-
-You can update a theme to the latest version by executing the following command in the *root* directory of your project:
-
-```txt
-git submodule update --rebase --remote
-```
-
-## Next steps
-
-You now have a live website served over HTTPS, distributed through CDN, and configured for continuous deployment. Dig deeper into the Netlify documentation:
-
-1. [Using a Custom Domain]
-2. [Setting up HTTPS on Custom Domains][httpscustom]
-3. [Redirects and Rewrite Rules]
-
-[app.netlify.com]: https://app.netlify.com
-[build command]: /getting-started/usage/#build-your-site
-[site configuration]: /getting-started/configuration/
-[ghsm]: https://github.com/blog/2104-working-with-submodules
-[gitsm]: https://git-scm.com/book/en/v2/Git-Tools-Submodules
-[httpscustom]: https://www.netlify.com/docs/ssl/
-[hugoversions]: https://github.com/netlify/build-image/blob/master/Dockerfile#L216
-[netlify]: https://www.netlify.com/
-[netlifysignup]: https://app.netlify.com/signup
-[Quick Start]: /getting-started/quick-start/
-[Redirects and Rewrite Rules]: https://www.netlify.com/docs/redirects/
-[Using a Custom Domain]: https://www.netlify.com/docs/custom-domains/
-[visit]: https://hugo-netlify-example.netlify.com
diff --git a/content/en/hosting-and-deployment/hosting-on-netlify/index.md b/content/en/hosting-and-deployment/hosting-on-netlify/index.md
new file mode 100644
index 000000000..b297bca02
--- /dev/null
+++ b/content/en/hosting-and-deployment/hosting-on-netlify/index.md
@@ -0,0 +1,129 @@
+---
+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
+---
+
+## Prerequisites
+
+1. [Create a Netlify account]
+2. [Install Git]
+3. [Create a Hugo site] and test it locally with `hugo server`
+4. Commit the changes to your local repository
+4. Push the local repository to your [GitHub], [GitLab], or [Bitbucket] account
+
+[Bitbucket]: https://bitbucket.org/product
+[Create a Hugo site]: /getting-started/quick-start/
+[Create a Netlify account]: https://app.netlify.com/signup
+[GitHub]: https://github.com
+[GitLab]: https://about.gitlab.com/
+[Install Git]: https://git-scm.com/book/en/v2/Getting-Started-Installing-Git
+
+## Procedure
+
+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 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.
+
+![screen capture](netlify-step-03.png)
+
+Step 4
+: Press the **Configure Netlify on GitHub** button.
+
+![screen capture](netlify-step-04.png)
+
+Step 5
+: Install the Netlify app by selecting your GitHub account.
+
+![screen capture](netlify-step-05.png)
+
+Step 6
+: Press the **Install** button.
+
+![screen capture](netlify-step-06.png)
+
+Step 7
+: Click on the site's repository from the list.
+
+![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)
+
+Step 11
+: Press the "Deploy my new site" button at the bottom of the page.
+
+![screen capture](netlify-step-11.png)
+
+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-12.png)
+
+Step 13
+: Press the **Open production deploy** button to view the live site.
+
+![screen capture](netlify-step-13.png)
+
+## Configuration file
+
+In the procedure above we configured our site using the Netlify user interface. Most site owners find it easier to use a configuration file checked into source control.
+
+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 >}}
+[build.environment]
+HUGO_VERSION = "0.126.0"
+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 >}}
+[build.environment]
+HUGO_VERSION = "0.126.0"
+DART_SASS_VERSION = "1.77.1"
+TZ = "America/Los_Angeles"
+
+[build]
+publish = "public"
+command = """\
+ curl -LJO https://github.com/sass/dart-sass/releases/download/${DART_SASS_VERSION}/dart-sass-${DART_SASS_VERSION}-linux-x64.tar.gz && \
+ tar -xf dart-sass-${DART_SASS_VERSION}-linux-x64.tar.gz && \
+ rm dart-sass-${DART_SASS_VERSION}-linux-x64.tar.gz && \
+ 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/hosting-and-deployment/hosting-on-netlify/netlify-step-02.png
new file mode 100644
index 000000000..31fceff27
--- /dev/null
+++ b/content/en/hosting-and-deployment/hosting-on-netlify/netlify-step-02.png
Binary files differ
diff --git a/content/en/hosting-and-deployment/hosting-on-netlify/netlify-step-03.png b/content/en/hosting-and-deployment/hosting-on-netlify/netlify-step-03.png
new file mode 100644
index 000000000..7b98e0b8f
--- /dev/null
+++ b/content/en/hosting-and-deployment/hosting-on-netlify/netlify-step-03.png
Binary files differ
diff --git a/content/en/hosting-and-deployment/hosting-on-netlify/netlify-step-04.png b/content/en/hosting-and-deployment/hosting-on-netlify/netlify-step-04.png
new file mode 100644
index 000000000..31304894b
--- /dev/null
+++ b/content/en/hosting-and-deployment/hosting-on-netlify/netlify-step-04.png
Binary files differ
diff --git a/content/en/hosting-and-deployment/hosting-on-netlify/netlify-step-05.png b/content/en/hosting-and-deployment/hosting-on-netlify/netlify-step-05.png
new file mode 100644
index 000000000..6d6eef01d
--- /dev/null
+++ b/content/en/hosting-and-deployment/hosting-on-netlify/netlify-step-05.png
Binary files differ
diff --git a/content/en/hosting-and-deployment/hosting-on-netlify/netlify-step-06.png b/content/en/hosting-and-deployment/hosting-on-netlify/netlify-step-06.png
new file mode 100644
index 000000000..1b766a785
--- /dev/null
+++ b/content/en/hosting-and-deployment/hosting-on-netlify/netlify-step-06.png
Binary files differ
diff --git a/content/en/hosting-and-deployment/hosting-on-netlify/netlify-step-07.png b/content/en/hosting-and-deployment/hosting-on-netlify/netlify-step-07.png
new file mode 100644
index 000000000..7bb3b6eca
--- /dev/null
+++ b/content/en/hosting-and-deployment/hosting-on-netlify/netlify-step-07.png
Binary files differ
diff --git a/content/en/hosting-and-deployment/hosting-on-netlify/netlify-step-08.png b/content/en/hosting-and-deployment/hosting-on-netlify/netlify-step-08.png
new file mode 100644
index 000000000..df8e9e59f
--- /dev/null
+++ b/content/en/hosting-and-deployment/hosting-on-netlify/netlify-step-08.png
Binary files differ
diff --git a/content/en/hosting-and-deployment/hosting-on-netlify/netlify-step-09.png b/content/en/hosting-and-deployment/hosting-on-netlify/netlify-step-09.png
new file mode 100644
index 000000000..3f925accc
--- /dev/null
+++ b/content/en/hosting-and-deployment/hosting-on-netlify/netlify-step-09.png
Binary files differ
diff --git a/content/en/hosting-and-deployment/hosting-on-netlify/netlify-step-10.png b/content/en/hosting-and-deployment/hosting-on-netlify/netlify-step-10.png
new file mode 100644
index 000000000..e9196d0ce
--- /dev/null
+++ b/content/en/hosting-and-deployment/hosting-on-netlify/netlify-step-10.png
Binary files differ
diff --git a/content/en/hosting-and-deployment/hosting-on-netlify/netlify-step-11.png b/content/en/hosting-and-deployment/hosting-on-netlify/netlify-step-11.png
new file mode 100644
index 000000000..2ac2b08af
--- /dev/null
+++ b/content/en/hosting-and-deployment/hosting-on-netlify/netlify-step-11.png
Binary files differ
diff --git a/content/en/hosting-and-deployment/hosting-on-netlify/netlify-step-12.png b/content/en/hosting-and-deployment/hosting-on-netlify/netlify-step-12.png
new file mode 100644
index 000000000..e251305a4
--- /dev/null
+++ b/content/en/hosting-and-deployment/hosting-on-netlify/netlify-step-12.png
Binary files differ
diff --git a/content/en/hosting-and-deployment/hosting-on-netlify/netlify-step-13.png b/content/en/hosting-and-deployment/hosting-on-netlify/netlify-step-13.png
new file mode 100644
index 000000000..f955f6369
--- /dev/null
+++ b/content/en/hosting-and-deployment/hosting-on-netlify/netlify-step-13.png
Binary files differ
diff --git a/content/en/hugo-modules/_index.md b/content/en/hugo-modules/_index.md
index cbff13ad0..01fc21e50 100644
--- a/content/en/hugo-modules/_index.md
+++ b/content/en/hugo-modules/_index.md
@@ -1,12 +1,12 @@
---
title: Hugo Modules
-linkTitle: Overview
+linkTitle: In this section
description: How to use Hugo Modules.
categories: []
keywords: []
menu:
docs:
- identifier: hugo-modules-overview
+ identifier: hugo-modules-in-this-section
parent: modules
weight: 10
weight: 10
@@ -20,7 +20,7 @@ You can combine modules in any combination you like, and even mount directories
Hugo Modules are powered by Go Modules. For more information about Go Modules, see:
-- [https://github.com/golang/go/wiki/Modules](https://github.com/golang/go/wiki/Modules)
+- [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:
diff --git a/content/en/hugo-modules/configuration.md b/content/en/hugo-modules/configuration.md
index ce9e97d81..3aec4699b 100644
--- a/content/en/hugo-modules/configuration.md
+++ b/content/en/hugo-modules/configuration.md
@@ -147,7 +147,7 @@ When you add a mount, the default mount for the concerned target root is ignored
{{< /code-toggle >}}
source
-: The source directory of the mount. For the main project, this can be either project-relative or absolute and even a symbolic link. For other modules it must be project-relative.
+: 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
: Where it should be mounted into Hugo's virtual filesystem. It must start with one of Hugo's component folders: `static`, `content`, `layouts`, `data`, `assets`, `i18n`, or `archetypes`. E.g. `content/blog`.
diff --git a/content/en/hugo-modules/use-modules.md b/content/en/hugo-modules/use-modules.md
index 295ff2061..913e4f775 100644
--- a/content/en/hugo-modules/use-modules.md
+++ b/content/en/hugo-modules/use-modules.md
@@ -21,7 +21,7 @@ toc: true
Use `hugo mod init` to initialize a new Hugo Module. If it fails to guess the module path, you must provide it as an argument, e.g.:
```sh
-hugo mod init github.com/gohugoio/myShortcodes
+hugo mod init github.com/<your_user>/<your_project>
```
Also see the [CLI Doc](/commands/hugo_mod_init/).
diff --git a/content/en/hugo-pipes/_index.md b/content/en/hugo-pipes/_index.md
index edc41b7a2..6e4190b87 100755
--- a/content/en/hugo-pipes/_index.md
+++ b/content/en/hugo-pipes/_index.md
@@ -1,11 +1,11 @@
---
title: Hugo Pipes
-linkTitle: Overview
+linkTitle: In this section
categories: []
keywords: []
menu:
docs:
- identifier: hugo-pipes-overview
+ identifier: hugo-pipes-in-this-section
parent: hugo-pipes
weight: 10
weight: 10
diff --git a/content/en/hugo-pipes/js.md b/content/en/hugo-pipes/js.md
index 9d2bbbd82..ddde8313a 100644
--- a/content/en/hugo-pipes/js.md
+++ b/content/en/hugo-pipes/js.md
@@ -17,7 +17,7 @@ action:
## Usage
-Any JavaScript resource file can be transpiled and "tree shaken" using `js.Build` which takes for argument either a string for the filepath or a dict of options listed below.
+Any JavaScript resource file can be transpiled and "tree shaken" using `js.Build` which takes for argument either a string for the file path or a dict of options listed below.
### Options
@@ -25,7 +25,7 @@ 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.
-params {{< new-in "0.96.0" >}}
+params
: (`map` or `slice`) Params that can be imported as JSON in your JS files, e.g.:
```go-html-template
@@ -95,6 +95,29 @@ format
sourceMap
: (`string`) Whether to generate `inline` or `external` source maps from esbuild. External source maps will be written to the target with the output file name + ".map". Input source maps can be read from js.Build and node modules and combined into the output source maps. By default, source maps are not created.
+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(<App />, container);
+```
+
### Import JS code from /assets
`js.Build` has full support for the virtual union file system in [Hugo Modules](/hugo-modules/). You can see some simple examples in this [test project](https://github.com/gohugoio/hugoTestProjectJSModImports), but in short this means that you can do this:
diff --git a/content/en/hugo-pipes/transpile-sass-to-css.md b/content/en/hugo-pipes/transpile-sass-to-css.md
index 998adad82..ba5c39966 100644
--- a/content/en/hugo-pipes/transpile-sass-to-css.md
+++ b/content/en/hugo-pipes/transpile-sass-to-css.md
@@ -43,7 +43,7 @@ targetPath
: (`string`) If not set, the transformed resource's target path will be the original path of the asset file with its extension replaced by `.css`.
vars {{< new-in 0.109.0 >}}
-: (`map`) A map of key/value pairs that will be available in the `hugo:vars` namespace. Useful for [initializing Sass variables from Hugo templates](https://discourse.gohugo.io/t/42053/).
+: (`map`) A map of key-value pairs that will be available in the `hugo:vars` namespace. Useful for [initializing Sass variables from Hugo templates](https://discourse.gohugo.io/t/42053/).
```scss
// LibSass
@@ -136,8 +136,8 @@ To install Dart Sass for your builds on GitLab Pages, the `.gitlab-ci.yml` file
```yaml
variables:
- HUGO_VERSION: 0.122.0
- DART_SASS_VERSION: 1.70.0
+ HUGO_VERSION: 0.126.0
+ DART_SASS_VERSION: 1.77.1
GIT_DEPTH: 0
GIT_STRATEGY: clone
GIT_SUBMODULE_STRATEGY: recursive
@@ -171,7 +171,7 @@ To install Dart Sass for your builds on Netlify, the `netlify.toml` file should
```toml
[build.environment]
HUGO_VERSION = "0.122.2"
-DART_SASS_VERSION = "1.70.0"
+DART_SASS_VERSION = "1.77.1"
TZ = "America/Los_Angeles"
[build]
diff --git a/content/en/installation/_common/03-prebuilt-binaries.md b/content/en/installation/_common/03-prebuilt-binaries.md
index d3465fa5d..55f7cb85b 100644
--- a/content/en/installation/_common/03-prebuilt-binaries.md
+++ b/content/en/installation/_common/03-prebuilt-binaries.md
@@ -16,7 +16,7 @@ Please consult your operating system documentation if you need help setting file
If you do not see a prebuilt binary for the desired edition, operating system, and architecture, install Hugo using one of the methods described below.
-[commit information]: /variables/git
+[commit information]: /methods/page/gitinfo/
[Git]: https://git-scm.com/
[Go]: https://go.dev/
[Hugo Modules]: /hugo-modules/
diff --git a/content/en/installation/_common/_index.md b/content/en/installation/_common/_index.md
index 47d5812fb..4328d4d14 100644
--- a/content/en/installation/_common/_index.md
+++ b/content/en/installation/_common/_index.md
@@ -7,7 +7,7 @@ cascade:
---
<!--
-Files within this headless branch bundle are markdown snippets. Each file must contain front matter delimiters, though front matter fields are not required.
+Files within this headless branch bundle are Markdown snippets. Each file must contain front matter delimiters, though front matter fields are not required.
Include the rendered content using the "include" shortcode.
-->
diff --git a/content/en/installation/_index.md b/content/en/installation/_index.md
index ca405b755..7e445a07d 100644
--- a/content/en/installation/_index.md
+++ b/content/en/installation/_index.md
@@ -1,13 +1,13 @@
---
title: Installation
-linkTitle: Overview
+linkTitle: In this section
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-overview
+ identifier: installation-in-this-section
parent: installation
weight: 10
weight: 10
diff --git a/content/en/installation/linux.md b/content/en/installation/linux.md
index 7b75f149b..769011212 100644
--- a/content/en/installation/linux.md
+++ b/content/en/installation/linux.md
@@ -96,6 +96,7 @@ 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/
@@ -105,6 +106,24 @@ You can also download Debian packages from the [latest release] page.
[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
+ ```
+
+2. Install using the Paludis package manager:
+
+
+ ```sh
+ cave resolve -x repository/heirecka
+ cave resolve -x hugo
+ ```
+
### Fedora
Derivatives of the [Fedora] distribution of Linux include [CentOS], [Red Hat Enterprise Linux], and others. To install the extended edition of Hugo:
@@ -119,7 +138,7 @@ sudo dnf install hugo
### Gentoo
-Derivatives of the [Gentoo] distribution of Linux include [Calculate Linux], [Funtoo], and others. Follow the instructions below to install the extended edition of Hugo:
+Derivatives of the [Gentoo] distribution of Linux include [Calculate Linux], [Funtoo], and others. To install the extended edition of Hugo:
1. Specify the `extended` [USE] flag in /etc/portage/package.use/hugo:
diff --git a/content/en/methods/_common/_index.md b/content/en/methods/_common/_index.md
index 47d5812fb..4328d4d14 100644
--- a/content/en/methods/_common/_index.md
+++ b/content/en/methods/_common/_index.md
@@ -7,7 +7,7 @@ cascade:
---
<!--
-Files within this headless branch bundle are markdown snippets. Each file must contain front matter delimiters, though front matter fields are not required.
+Files within this headless branch bundle are Markdown snippets. Each file must contain front matter delimiters, though front matter fields are not required.
Include the rendered content using the "include" shortcode.
-->
diff --git a/content/en/methods/_common/next-prev-on-page-vs-next-prev-on-pages.md b/content/en/methods/_common/next-prev-on-page-vs-next-prev-on-pages.md
index 4ae3a0f39..f65037878 100644
--- a/content/en/methods/_common/next-prev-on-page-vs-next-prev-on-pages.md
+++ b/content/en/methods/_common/next-prev-on-page-vs-next-prev-on-pages.md
@@ -9,10 +9,10 @@ The `Next` and `Prev` methods on a `Pages` object are more flexible than the `Ne
[`PAGES.Next`] and [`PAGES.Prev`]|locally defined|✔️
[`PAGE.Next`] and [`PAGE.Prev`]|globally defined|❌
-[`PAGES.Next`]: /methods/pages/next
-[`PAGES.Prev`]: /methods/pages/prev
-[`PAGE.Next`]: /methods/page/next
-[`PAGE.Prev`]: /methods/page/prev
+[`PAGES.Next`]: /methods/pages/next/
+[`PAGES.Prev`]: /methods/pages/prev/
+[`PAGE.Next`]: /methods/page/next/
+[`PAGE.Prev`]: /methods/page/prev/
locally defined
: Build the page collection every time you call `PAGES.Next` and `PAGES.Prev`. Navigation between pages is relative to the current page's position within the local collection, independent of the global collection.
@@ -31,7 +31,7 @@ With a global collection, the navigation sort order is fixed, using Hugo's defau
For example, with a global collection sorted by title, the navigation sort order will use Hugo's default sort order. This is probably not what you want or expect. For this reason, the `Next` and `Prev` methods on a `Pages` object are generally a better choice.
-[date]: /methods/page/date
-[weight]: /methods/page/weight
-[linkTitle]: /methods/page/linktitle
-[title]: /methods/page/title
+[date]: /methods/page/date/
+[weight]: /methods/page/weight/
+[linkTitle]: /methods/page/linktitle/
+[title]: /methods/page/title/
diff --git a/content/en/methods/_index.md b/content/en/methods/_index.md
index c12bd9d4d..bab637ddb 100644
--- a/content/en/methods/_index.md
+++ b/content/en/methods/_index.md
@@ -1,16 +1,17 @@
---
title: Methods
-linkTitle: Overview
+linkTitle: In this section
description: A list of Hugo template methods including examples.
categories: []
keywords: []
menu:
docs:
- identifier: methods-overview
+ 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/menu-entry/KeyName.md b/content/en/methods/menu-entry/KeyName.md
index 4b43596b0..409cb31d6 100644
--- a/content/en/methods/menu-entry/KeyName.md
+++ b/content/en/methods/menu-entry/KeyName.md
@@ -36,4 +36,4 @@ This example uses the `KeyName` method when querying the translation table on a
In the example above, we need to pass the value returned by `.KeyName` through the [`lower`] function because the keys in the translation table are lowercase.
-[`lower`]: functions/strings/tolower
+[`lower`]: /functions/strings/tolower/
diff --git a/content/en/methods/menu-entry/Menu.md b/content/en/methods/menu-entry/Menu.md
index 6827519bd..63f148c1a 100644
--- a/content/en/methods/menu-entry/Menu.md
+++ b/content/en/methods/menu-entry/Menu.md
@@ -19,6 +19,6 @@ action:
Use this method with the [`IsMenuCurrent`] and [`HasMenuCurrent`] methods on a `Page` object to set "active" and "ancestor" classes on a rendered entry. See [this example].
-[`HasMenuCurrent`]: /methods/page/hasmenucurrent
-[`IsMenuCurrent`]: /methods/page/ismenucurrent
+[`HasMenuCurrent`]: /methods/page/hasmenucurrent/
+[`IsMenuCurrent`]: /methods/page/ismenucurrent/
[this example]: /templates/menu-templates/#example
diff --git a/content/en/methods/menu-entry/Name.md b/content/en/methods/menu-entry/Name.md
index d722da07c..d77c65cb5 100644
--- a/content/en/methods/menu-entry/Name.md
+++ b/content/en/methods/menu-entry/Name.md
@@ -13,8 +13,8 @@ If you define the menu entry [automatically], the `Name` method returns the page
If you define the menu entry [in front matter] or [in site configuration], the `Name` method returns the `name` property, falling back to the page’s `LinkTitle`, then to its `Title`.
-[`LinkTitle`]: /methods/page/linktitle
-[`Title`]: /methods/page/title
+[`LinkTitle`]: /methods/page/linktitle/
+[`Title`]: /methods/page/title/
[automatically]: /content-management/menus/#define-automatically
[in front matter]: /content-management/menus/#define-in-front-matter
[in site configuration]: /content-management/menus/#define-in-site-configuration
diff --git a/content/en/methods/menu-entry/Page.md b/content/en/methods/menu-entry/Page.md
index b75e4af55..bd8c1625e 100644
--- a/content/en/methods/menu-entry/Page.md
+++ b/content/en/methods/menu-entry/Page.md
@@ -46,8 +46,8 @@ If the entry is not associated with a page, we use its `url` and `name` properti
See the [menu templates] section for more information.
-[`LinkTitle`]: /methods/page/linktitle
-[`RelPermalink`]: /methods/page/relpermalink
+[`LinkTitle`]: /methods/page/linktitle/
+[`RelPermalink`]: /methods/page/relpermalink/
[define menu entries]: /content-management/menus/
[menu templates]: /templates/menu-templates/#page-references
-[methods]: /methods/page
+[methods]: /methods/page/
diff --git a/content/en/methods/menu-entry/Title.md b/content/en/methods/menu-entry/Title.md
index c1eec2cc0..4082e4e93 100644
--- a/content/en/methods/menu-entry/Title.md
+++ b/content/en/methods/menu-entry/Title.md
@@ -11,10 +11,10 @@ action:
If you define the menu entry [automatically], the `Title` 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 `title` property, falling back to the page’s `LinkTitle`, then to its `Title`.
+If you define the menu entry [in front matter] or [in site configuration], the `Title` method returns the `title` property, falling back to the page’s `LinkTitle`, then to its `Title`.
-[`LinkTitle`]: /methods/page/linktitle
-[`Title`]: /methods/page/title
+[`LinkTitle`]: /methods/page/linktitle/
+[`Title`]: /methods/page/title/
[automatically]: /content-management/menus/#define-automatically
[in front matter]: /content-management/menus/#define-in-front-matter
[in site configuration]: /content-management/menus/#define-in-site-configuration
diff --git a/content/en/methods/menu-entry/URL.md b/content/en/methods/menu-entry/URL.md
index c2b314b58..bf3ec044a 100644
--- a/content/en/methods/menu-entry/URL.md
+++ b/content/en/methods/menu-entry/URL.md
@@ -20,4 +20,4 @@ For menu entries associated with a page, the `URL` method returns the page's [`R
</ul>
```
-[`RelPermalink`]: /methods/page/relpermalink
+[`RelPermalink`]: /methods/page/relpermalink/
diff --git a/content/en/methods/menu-entry/Weight.md b/content/en/methods/menu-entry/Weight.md
index 7b0c24ae8..eab935736 100644
--- a/content/en/methods/menu-entry/Weight.md
+++ b/content/en/methods/menu-entry/Weight.md
@@ -13,7 +13,7 @@ If you define the menu entry [automatically], the `Weight` method returns the pa
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
+[`Weight`]: /methods/page/weight/
[automatically]: /content-management/menus/#define-automatically
[in front matter]: /content-management/menus/#define-in-front-matter
[in site configuration]: /content-management/menus/#define-in-site-configuration
diff --git a/content/en/methods/menu-entry/_common/_index.md b/content/en/methods/menu-entry/_common/_index.md
index 47d5812fb..4328d4d14 100644
--- a/content/en/methods/menu-entry/_common/_index.md
+++ b/content/en/methods/menu-entry/_common/_index.md
@@ -7,7 +7,7 @@ cascade:
---
<!--
-Files within this headless branch bundle are markdown snippets. Each file must contain front matter delimiters, though front matter fields are not required.
+Files within this headless branch bundle are Markdown snippets. Each file must contain front matter delimiters, though front matter fields are not required.
Include the rendered content using the "include" shortcode.
-->
diff --git a/content/en/methods/menu/ByName.md b/content/en/methods/menu/ByName.md
index 04f25c22d..2e28016b6 100644
--- a/content/en/methods/menu/ByName.md
+++ b/content/en/methods/menu/ByName.md
@@ -62,4 +62,4 @@ You can also sort menu entries using the [`sort`] function. For example, to sort
When using the sort function with menu entries, specify any of the following keys: `Identifier`, `Name`, `Parent`, `Post`, `Pre`, `Title`, `URL`, or `Weight`.
-[`sort`]: /functions/collections/sort
+[`sort`]: /functions/collections/sort/
diff --git a/content/en/methods/menu/ByWeight.md b/content/en/methods/menu/ByWeight.md
index d5cb0444b..3774619be 100644
--- a/content/en/methods/menu/ByWeight.md
+++ b/content/en/methods/menu/ByWeight.md
@@ -73,4 +73,4 @@ You can also sort menu entries using the [`sort`] function. For example, to sort
When using the sort function with menu entries, specify any of the following keys: `Identifier`, `Name`, `Parent`, `Post`, `Pre`, `Title`, `URL`, or `Weight`.
-[`sort`]: /functions/collections/sort
+[`sort`]: /functions/collections/sort/
diff --git a/content/en/methods/page/AllTranslations.md b/content/en/methods/page/AllTranslations.md
index b8cc65179..51d82d4f9 100644
--- a/content/en/methods/page/AllTranslations.md
+++ b/content/en/methods/page/AllTranslations.md
@@ -1,6 +1,6 @@
---
title: AllTranslations
-description: Returns all translation of the given page, including the given page.
+description: Returns all translations of the given page, including the current language.
categories: []
keywords: []
action:
@@ -63,9 +63,9 @@ And this template:
{{ with .AllTranslations }}
<ul>
{{ range . }}
- {{ $langName := or .Language.LanguageName .Language.Lang }}
- {{ $langCode := or .Language.LanguageCode .Language.Lang }}
- <li><a href="{{ .RelPermalink }}" hreflang="{{ $langCode }}">{{ .LinkTitle }} ({{ $langName }})</a></li>
+ <li>
+ <a href="{{ .RelPermalink }}" hreflang="{{ .Language.LanguageCode }}">{{ .LinkTitle }} ({{ or .Language.LanguageName .Language.Lang }})</a>
+ </li>
{{ end }}
</ul>
{{ end }}
diff --git a/content/en/methods/page/BundleType.md b/content/en/methods/page/BundleType.md
index 77d1d72eb..5254757ee 100644
--- a/content/en/methods/page/BundleType.md
+++ b/content/en/methods/page/BundleType.md
@@ -5,7 +5,7 @@ categories: []
keywords: []
action:
related: []
- returnType: files.ContentClass
+ returnType: string
signatures: [PAGE.BundleType]
---
diff --git a/content/en/methods/page/CodeOwners.md b/content/en/methods/page/CodeOwners.md
index 068c4591f..c0baf26ad 100644
--- a/content/en/methods/page/CodeOwners.md
+++ b/content/en/methods/page/CodeOwners.md
@@ -63,4 +63,4 @@ Render the code owners for each content page:
Combine this method with [`resources.GetRemote`] to retrieve names and avatars from your Git provider by querying their API.
-[`resources.GetRemote`]: functions/resources/getremote
+[`resources.GetRemote`]: /functions/resources/getremote/
diff --git a/content/en/methods/page/Content.md b/content/en/methods/page/Content.md
index 40a057f02..a9d38367c 100644
--- a/content/en/methods/page/Content.md
+++ b/content/en/methods/page/Content.md
@@ -13,7 +13,7 @@ action:
signatures: [PAGE.Content]
---
-The `Content` method on a `Page` object renders markdown and shortcodes to HTML. The content does not include front matter.
+The `Content` method on a `Page` object renders Markdown and shortcodes to HTML. The content does not include front matter.
[shortcodes]: /getting-started/glossary/#shortcode
diff --git a/content/en/methods/page/Data.md b/content/en/methods/page/Data.md
index 4eccde6ff..aea1042d4 100644
--- a/content/en/methods/page/Data.md
+++ b/content/en/methods/page/Data.md
@@ -74,7 +74,7 @@ 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
+[taxonomy methods]: /methods/taxonomy/
{{% /note %}}
Learn more about [taxonomy templates].
diff --git a/content/en/methods/page/Date.md b/content/en/methods/page/Date.md
index 83192f94c..113d6ca09 100644
--- a/content/en/methods/page/Date.md
+++ b/content/en/methods/page/Date.md
@@ -33,7 +33,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&nbsp;[details].
-[`time.Format`]: /functions/time/format
+[`time.Format`]: /functions/time/format/
[details]: /getting-started/configuration/#configure-dates
-[time methods]: /methods/time
+[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 fbb43b8b5..67171fe01 100644
--- a/content/en/methods/page/Description.md
+++ b/content/en/methods/page/Description.md
@@ -10,7 +10,7 @@ action:
signatures: [PAGE.Description]
---
-Conceptually different that a [content summary], a page description is typically used in metadata about the page.
+Conceptually different from a [content summary], a page description is typically used in metadata about the page.
{{< code-toggle file=content/recipes/sushi.md fm=true >}}
title = 'How to make spicy tuna hand rolls'
@@ -25,4 +25,4 @@ description = 'Instructions for making spicy tuna hand rolls.'
</head>
{{< /code >}}
-[content summary]: /content-management/summaries
+[content summary]: /content-management/summaries/
diff --git a/content/en/methods/page/ExpiryDate.md b/content/en/methods/page/ExpiryDate.md
index 353546449..9b95ebc65 100644
--- a/content/en/methods/page/ExpiryDate.md
+++ b/content/en/methods/page/ExpiryDate.md
@@ -29,7 +29,7 @@ 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&nbsp;[details].
-[`time.Format`]: /functions/time/format
+[`time.Format`]: /functions/time/format/
[details]: /getting-started/configuration/#configure-dates
-[time methods]: /methods/time
+[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 44b752215..d59171577 100644
--- a/content/en/methods/page/File.md
+++ b/content/en/methods/page/File.md
@@ -22,7 +22,9 @@ content/
└── book-2.md
```
-Code defensively by verifying file existence as shown in each of the examples below.
+{{% note %}}
+Code defensively by verifying file existence as shown in the examples below.
+{{% /note %}}
## Methods
@@ -80,13 +82,17 @@ The path separators (slash or backslash) in `Path`, `Dir`, and `Filename` depend
{{ end }}
```
-###### Lang
+###### IsContentAdapter
+
+{{< new-in 0.126.0 >}}
+
+(`bool`) Reports whether the file is a [content adapter].
-(`string`) The language associated with the given file.
+[content adapter]: /content-management/content-adapters/
```go-html-template
{{ with .File }}
- {{ .Lang }}
+ {{ .IsContentAdapter }}
{{ end }}
```
@@ -110,6 +116,16 @@ The path separators (slash or backslash) in `Path`, `Dir`, and `Filename` depend
{{ end }}
```
+###### Section
+
+(`string`) The name of the top level section in which the file resides.
+
+```go-html-template
+{{ with .File }}
+ {{ .Section }}
+{{ end }}
+```
+
###### TranslationBaseName
(`string`) The file name, excluding the extension and language identifier.
@@ -157,9 +173,10 @@ ContentBaseName|a|b|news
Dir|news/|news/b/|news/
Ext|md|md|md
Filename|/home/user/...|/home/user/...|/home/user/...
-Lang|en|en|en
+IsContentAdapter|false|false|false
LogicalName|a.en.md|index.en.md|_index.en.md
Path|news/a.en.md|news/b/index.en.md|news/_index.en.md
+Section|news|news|news
TranslationBaseName|a|index|_index
UniqueID|15be14b...|186868f...|7d9159d...
@@ -171,13 +188,7 @@ Some of the pages on a site may not be backed by a file. For example:
- Taxonomy pages
- Term pages
-Without a backing file, Hugo will throw a warning if you attempt to access a `.File` property. For example:
-
-```text
-WARN .File.ContentBaseName on zero object. Wrap it in if or with...
-```
-
-To code defensively, first check for file existence:
+Without a backing file, Hugo will throw an error if you attempt to access a `.File` property. To code defensively, first check for file existence:
```go-html-template
{{ with .File }}
diff --git a/content/en/methods/page/Fragments.md b/content/en/methods/page/Fragments.md
index 89f82d2ce..7bcad1ef9 100644
--- a/content/en/methods/page/Fragments.md
+++ b/content/en/methods/page/Fragments.md
@@ -21,7 +21,7 @@ In a URL, whether absolute or relative, the [fragment] links to an `id` attribut
path fragment
```
-Hugo assigns an `id` attribute to each markdown [ATX] and [setext] heading within the page content. You can override the `id` with a [markdown attribute] as needed. This creates the relationship between an entry in the [table of contents] (TOC) and a heading on the page.
+Hugo assigns an `id` attribute to each Markdown [ATX] and [setext] heading within the page content. You can override the `id` with a [Markdown attribute] as needed. This creates the relationship between an entry in the [table of contents] (TOC) and a heading on the page.
Use the `Fragments` method on a `Page` object to create a table of contents with the `Fragments.ToHTML` method, or by [walking] the `Fragments.Map` data structure.
@@ -31,21 +31,21 @@ Headings
: (`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
-<pre>{{ .Fragments.Headings | jsonify (dict "indent" " ") }}</pre>
+<pre>{{ debug.Dump .Fragments.Headings }}</pre>
```
HeadingsMap
: (`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
-<pre>{{ .Fragments.HeadingsMap | jsonify (dict "indent" " ") }}</pre>
+<pre>{{ debug.Dump .Fragments.HeadingsMap }}</pre>
```
Identifiers
: (`slice`) A slice containing the `id` of each heading on the page. To inspect the data structure:
```go-html-template
-<pre>{{ .Fragments.Identifiers | jsonify (dict "indent" " ") }}</pre>
+<pre>{{ debug.Dump .Fragments.Identifiers }}</pre>
```
Identifiers.Contains ID
@@ -100,7 +100,7 @@ When using the `Fragments` methods within a shortcode, call the shortcode using
[fragment]: /getting-started/glossary/#fragment
[markdown attribute]: /getting-started/glossary/#markdown-attribute
[setext]: https://spec.commonmark.org/0.30/#setext-headings
-[table of contents]: /methods/page/tableofcontents
+[table of contents]: /methods/page/tableofcontents/
[walking]: /getting-started/glossary/#walk
-[`tableofcontents`]: /methods/page/tableofcontents
+[`tableofcontents`]: /methods/page/tableofcontents/
[render hook]: /getting-started/glossary/#render-hook
diff --git a/content/en/methods/page/FuzzyWordCount.md b/content/en/methods/page/FuzzyWordCount.md
index 600ad48d5..8523edf8c 100644
--- a/content/en/methods/page/FuzzyWordCount.md
+++ b/content/en/methods/page/FuzzyWordCount.md
@@ -17,4 +17,4 @@ action:
To get the exact word count, use the [`WordCount`] method.
-[`WordCount`]: /methods/page/wordcount
+[`WordCount`]: /methods/page/wordcount/
diff --git a/content/en/methods/page/GetPage.md b/content/en/methods/page/GetPage.md
index b1f192d58..9b4ced345 100644
--- a/content/en/methods/page/GetPage.md
+++ b/content/en/methods/page/GetPage.md
@@ -13,7 +13,7 @@ aliases: [/functions/getpage]
The `GetPage` method is also available on a `Site` object. See&nbsp;[details].
-[details]: /methods/site/getpage
+[details]: /methods/site/getpage/
When using the `GetPage` method on the `Page` object, specify a path relative to the current directory or relative to the content directory.
@@ -36,7 +36,7 @@ content/
└── _index.md
```
-The examples below depict the result of rendering works/paintings/the-mona-list.md with a single page template:
+The examples below depict the result of rendering works/paintings/the-mona-lisa.md with a single page template:
```go-html-template
{{ with .GetPage "starry-night" }}
diff --git a/content/en/methods/page/HeadingsFiltered.md b/content/en/methods/page/HeadingsFiltered.md
index a39c48da1..d741b57ce 100644
--- a/content/en/methods/page/HeadingsFiltered.md
+++ b/content/en/methods/page/HeadingsFiltered.md
@@ -14,5 +14,5 @@ action:
Use in conjunction with the [`Related`] method on a [`Pages`] object. See&nbsp;[details].
[`Pages`]: /methods/pages/
-[`Related`]: /methods/pages/related
+[`Related`]: /methods/pages/related/
[details]: /content-management/related/#index-content-headings-in-related-content
diff --git a/content/en/methods/page/InSection.md b/content/en/methods/page/InSection.md
index b98fbc808..41ce918f3 100644
--- a/content/en/methods/page/InSection.md
+++ b/content/en/methods/page/InSection.md
@@ -98,5 +98,5 @@ Gaining a thorough understanding of context is critical for anyone writing templ
{{% /note %}}
[context]: /getting-started/glossary/#context
-[`with`]: /functions/go-template/with
-[`else`]: /functions/go-template/else
+[`with`]: /functions/go-template/with/
+[`else`]: /functions/go-template/else/
diff --git a/content/en/methods/page/IsAncestor.md b/content/en/methods/page/IsAncestor.md
index ca23c0868..8ace8463c 100644
--- a/content/en/methods/page/IsAncestor.md
+++ b/content/en/methods/page/IsAncestor.md
@@ -1,6 +1,6 @@
---
title: IsAncestor
-description: Reports whether PAGE1 in an ancestor of PAGE2.
+description: Reports whether PAGE1 is an ancestor of PAGE2.
categories: []
keywords: []
action:
@@ -96,5 +96,5 @@ Gaining a thorough understanding of context is critical for anyone writing templ
{{% /note %}}
[context]: /getting-started/glossary/#context
-[`with`]: /functions/go-template/with
-[`else`]: /functions/go-template/else
+[`with`]: /functions/go-template/with/
+[`else`]: /functions/go-template/else/
diff --git a/content/en/methods/page/IsDescendant.md b/content/en/methods/page/IsDescendant.md
index f1042564e..2c0599d91 100644
--- a/content/en/methods/page/IsDescendant.md
+++ b/content/en/methods/page/IsDescendant.md
@@ -1,6 +1,6 @@
---
title: IsDescendant
-description: Reports whether PAGE1 in a descendant of PAGE2.
+description: Reports whether PAGE1 is a descendant of PAGE2.
categories: []
keywords: []
action:
@@ -95,5 +95,5 @@ Gaining a thorough understanding of context is critical for anyone writing templ
{{% /note %}}
[context]: /getting-started/glossary/#context
-[`with`]: /functions/go-template/with
-[`else`]: /functions/go-template/else
+[`with`]: /functions/go-template/with/
+[`else`]: /functions/go-template/else/
diff --git a/content/en/methods/page/Keywords.md b/content/en/methods/page/Keywords.md
index 5ad37ce51..ef68c27f5 100644
--- a/content/en/methods/page/Keywords.md
+++ b/content/en/methods/page/Keywords.md
@@ -11,7 +11,7 @@ action:
By default, Hugo evaluates the keywords when creating collections of [related content].
-[related content]: /content-management/related
+[related content]: /content-management/related/
{{< code-toggle file=content/recipes/sushi.md fm=true >}}
title = 'How to make spicy tuna hand rolls'
@@ -32,7 +32,7 @@ Or use the [delimit] function:
{{ delimit .Keywords ", " ", and " }} → tuna, sriracha, nori, and rice
```
-[delimit]: /functions/collections/delimit
+[delimit]: /functions/collections/delimit/
Keywords are also a useful [taxonomy]:
@@ -43,4 +43,4 @@ keyword = 'keywords'
category = 'categories'
{{< /code-toggle >}}
-[taxonomy]: /content-management/taxonomies
+[taxonomy]: /content-management/taxonomies/
diff --git a/content/en/methods/page/Language.md b/content/en/methods/page/Language.md
index 4e65107da..321b44e56 100644
--- a/content/en/methods/page/Language.md
+++ b/content/en/methods/page/Language.md
@@ -34,7 +34,7 @@ Lang
```
LanguageCode
-: (`string`) The language code from the site configuration.
+: (`string`) The language code from the site configuration. Falls back to `Lang` if not defined.
```go-html-template
{{ .Language.LanguageCode }} → de-DE
@@ -61,5 +61,5 @@ Weight
{{ .Language.Weight }} → 2
```
-[details]: /methods/site/language
+[details]: /methods/site/language/
[RFC 5646]: https://datatracker.ietf.org/doc/html/rfc5646
diff --git a/content/en/methods/page/Lastmod.md b/content/en/methods/page/Lastmod.md
index c1692233d..78760d556 100644
--- a/content/en/methods/page/Lastmod.md
+++ b/content/en/methods/page/Lastmod.md
@@ -33,8 +33,8 @@ In the example above we explicitly set the last modification date in front matte
Learn more about [date configuration].
-[`gitinfo`]: /methods/page/gitinfo
-[`time.format`]: /functions/time/format
+[`gitinfo`]: /methods/page/gitinfo/
+[`time.format`]: /functions/time/format/
[date configuration]: /getting-started/configuration/#configure-dates
-[time methods]: /methods/time
+[time methods]: /methods/time/
[time.time]: https://pkg.go.dev/time#time
diff --git a/content/en/methods/page/LinkTitle.md b/content/en/methods/page/LinkTitle.md
index 746e433bb..0ce32e641 100644
--- a/content/en/methods/page/LinkTitle.md
+++ b/content/en/methods/page/LinkTitle.md
@@ -12,7 +12,7 @@ action:
The `LinkTitle` method returns the `linkTitle` field as defined in front matter, falling back to the value returned by the [`Title`] method.
-[`Title`]: /methods/page/title
+[`Title`]: /methods/page/title/
{{< code-toggle file=content/articles/healthy-desserts.md fm=true >}}
title = 'Seventeen delightful recipes for healthy desserts'
diff --git a/content/en/methods/page/NextInSection.md b/content/en/methods/page/NextInSection.md
index 73f82d754..59a35d03d 100644
--- a/content/en/methods/page/NextInSection.md
+++ b/content/en/methods/page/NextInSection.md
@@ -65,7 +65,7 @@ With the `PrevInSection` and `NextInSection` methods, the navigation sort order
For example, with a page collection sorted by title, the navigation sort order will use Hugo’s default sort order. This is probably not what you want or expect. For this reason, the Next and Prev methods on a Pages object are generally a better choice.
-[date]: /methods/page/date
-[weight]: /methods/page/weight
-[linkTitle]: /methods/page/linktitle
-[title]: /methods/page/title
+[date]: /methods/page/date/
+[weight]: /methods/page/weight/
+[linkTitle]: /methods/page/linktitle/
+[title]: /methods/page/title/
diff --git a/content/en/methods/page/Pages.md b/content/en/methods/page/Pages.md
index 2f329eeec..d446292e2 100644
--- a/content/en/methods/page/Pages.md
+++ b/content/en/methods/page/Pages.md
@@ -75,7 +75,7 @@ In the last example, the collection includes pages in the resources subdirectory
{{% note %}}
When used with a `Site` object, the `Pages` method recursively returns all pages within the site. See&nbsp;[details].
-[details]: /methods/site/pages
+[details]: /methods/site/pages/
{{% /note %}}
```go-html-template
diff --git a/content/en/methods/page/Paginator.md b/content/en/methods/page/Paginator.md
index b1540286a..b411e6ec0 100644
--- a/content/en/methods/page/Paginator.md
+++ b/content/en/methods/page/Paginator.md
@@ -28,7 +28,7 @@ Although simple to invoke, with the `Paginator` method you can neither filter no
The [`Paginate`] method is more flexible, and strongly recommended.
-[`paginate`]: /methods/page/paginate
+[`paginate`]: /methods/page/paginate/
{{% /note %}}
{{% note %}}
diff --git a/content/en/methods/page/Param.md b/content/en/methods/page/Param.md
index b2932d981..daf09a5b4 100644
--- a/content/en/methods/page/Param.md
+++ b/content/en/methods/page/Param.md
@@ -29,6 +29,7 @@ Content:
title = 'Example'
date = 2023-01-01
draft = false
+[params]
display_toc = false
{{< /code-toggle >}}
diff --git a/content/en/methods/page/Params.md b/content/en/methods/page/Params.md
index 13416ada7..219b5de9d 100644
--- a/content/en/methods/page/Params.md
+++ b/content/en/methods/page/Params.md
@@ -17,8 +17,9 @@ With this front matter:
{{< code-toggle file=content/news/annual-conference.md >}}
title = 'Annual conference'
date = 2023-10-17T15:11:37-07:00
+[params]
display_related = true
-[author]
+[params.author]
name = 'John Smith'
{{< /code-toggle >}}
@@ -38,6 +39,6 @@ In the template example above, each of the keys is a valid identifier. For examp
{{ index .Params "key-with-hyphens" }} → 2023
```
-[`index`]: /functions/collections/indexfunction
+[`index`]: /functions/collections/indexfunction/
[chaining]: /getting-started/glossary/#chain
[identifiers]: /getting-started/glossary/#identifier
diff --git a/content/en/methods/page/Parent.md b/content/en/methods/page/Parent.md
index 9d9ed7ea3..db01eb589 100644
--- a/content/en/methods/page/Parent.md
+++ b/content/en/methods/page/Parent.md
@@ -21,7 +21,7 @@ action:
{{% note %}}
The parent section of a regular page is the [current section].
-[current section]: /methods/page/currentsection
+[current section]: /methods/page/currentsection/
{{% /note %}}
Consider this content structure:
diff --git a/content/en/methods/page/Path.md b/content/en/methods/page/Path.md
new file mode 100644
index 000000000..b65120d4d
--- /dev/null
+++ b/content/en/methods/page/Path.md
@@ -0,0 +1,157 @@
+---
+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
+---
+
+{{< new-in 0.123.0 >}}
+
+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.
+
+[logical path]: /getting-started/glossary#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
+2. Strips the language identifier
+3. Converts the result to lower case
+4. Replaces spaces with hyphens
+
+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.
+
+## Examples
+
+### Monolingual site
+
+Note that the logical path is independent of content format and URL modifiers.
+
+File path|Front matter slug|Logical path
+:--|:--|:--
+`content/_index.md`||`/`
+`content/posts/_index.md`||`/posts`
+`content/posts/post-1.md`|`foo`|`/posts/post-1`
+`content/posts/post-2.html`|`bar`|`/posts/post-2`
+
+### Multilingual site
+
+Note that the logical path is independent of content format, language identifiers, and URL modifiers.
+
+File path|Front matter slug|Logical path
+:--|:--|:--
+`content/_index.en.md`||`/`
+`content/_index.de.md`||`/`
+`content/posts/_index.en.md`||`/posts`
+`content/posts/_index.de.md`||`/posts`
+`content/posts/posts-1.en.md`|`foo`|`/posts/post-1`
+`content/posts/posts-1.de.md`|`foo`|`/posts/post-1`
+`content/posts/posts-2.en.html`|`bar`|`/posts/post-2`
+`content/posts/posts-2.de.html`|`bar`|`/posts/post-2`
+
+### Pages not backed by a file
+
+The `Path` method on a `Page` object returns a value regardless of whether the page is backed by a file.
+
+```text
+content/
+└── posts/
+ └── post-1.md <-- front matter: tags = ['hugo']
+```
+
+When you build the site:
+
+```text
+public/
+├── posts/
+│ ├── post-1/
+│ │ └── index.html .Page.Path = /posts/post-1
+│ └── index.html .Page.Path = /posts
+├── tags/
+│ ├── hugo/
+│ │ └── index.html .Page.Path = /tags/hugo
+│ └── index.html .Page.Path = /tags
+└── index.html .Page.Path = /
+```
+
+## Finding pages
+
+These methods, functions, and shortcodes use the logical path to find the given page:
+
+Methods|Functions|Shortcodes
+:--|:--|:--
+[`Site.GetPage`]|[`urls.Ref`]|[`ref`]
+[`Page.GetPage`]|[`urls.RelRef`]|[`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`]: /content-management/shortcodes/#ref
+[`relref`]: /content-management/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 %}}
+
+
+## Logical tree
+
+Just as file paths form a file tree, logical paths form a logical tree.
+
+A file tree:
+
+```text
+content/
+└── s1/
+ ├── p1/
+ │ └── index.md
+ └── p2.md
+```
+
+The same content represented as a logical tree:
+
+```text
+content/
+└── s1/
+ ├── p1
+ └── p2
+```
+
+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 %}}
diff --git a/content/en/methods/page/Plain.md b/content/en/methods/page/Plain.md
index 6fdf60b62..3aae1ed61 100644
--- a/content/en/methods/page/Plain.md
+++ b/content/en/methods/page/Plain.md
@@ -13,7 +13,7 @@ action:
signatures: [PAGE.Plain]
---
-The `Plain` method on a `Page` object renders markdown and [shortcodes] to HTML, then strips the HTML [tags]. It does not strip HTML [entities]. The plain content does not include front matter.
+The `Plain` method on a `Page` object renders Markdown and [shortcodes] to HTML, then strips the HTML [tags]. It does not strip HTML [entities]. The plain content does not include front matter.
To prevent Go's [html/template] package from escaping HTML entities, pass the result through the [`htmlUnescape`] function.
@@ -25,4 +25,4 @@ To prevent Go's [html/template] package from escaping HTML entities, pass the re
[html/template]: https://pkg.go.dev/html/template
[entities]: https://developer.mozilla.org/en-US/docs/Glossary/Entity
[tags]: https://developer.mozilla.org/en-US/docs/Glossary/Tag
-[`htmlUnescape`]: /functions/
+[`htmlUnescape`]: /functions/transform/htmlunescape/
diff --git a/content/en/methods/page/PlainWords.md b/content/en/methods/page/PlainWords.md
index 4bc79d241..4f70193fe 100644
--- a/content/en/methods/page/PlainWords.md
+++ b/content/en/methods/page/PlainWords.md
@@ -15,7 +15,7 @@ action:
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 white space characters, as defined by [`unicode.IsSpace`], returning a slice of substrings of s or an empty slice if s contains only white space._
+_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 %}}
@@ -32,5 +32,5 @@ To determine the approximate number of unique words on a page:
{{ .PlainWords | uniq }} → 42
```
-[`Plain`]: /methods/page/plain
+[`Plain`]: /methods/page/plain/
[`strings.Fields`]: https://pkg.go.dev/strings#Fields
diff --git a/content/en/methods/page/PrevInSection.md b/content/en/methods/page/PrevInSection.md
index c09e4580f..e6daf66c4 100644
--- a/content/en/methods/page/PrevInSection.md
+++ b/content/en/methods/page/PrevInSection.md
@@ -66,7 +66,7 @@ With the `PrevInSection` and `NextInSection` methods, the navigation sort order
For example, with a page collection sorted by title, the navigation sort order will use Hugo’s default sort order. This is probably not what you want or expect. For this reason, the Next and Prev methods on a Pages object are generally a better choice.
-[date]: /methods/page/date
-[weight]: /methods/page/weight
-[linkTitle]: /methods/page/linktitle
-[title]: /methods/page/title
+[date]: /methods/page/date/
+[weight]: /methods/page/weight/
+[linkTitle]: /methods/page/linktitle/
+[title]: /methods/page/title/
diff --git a/content/en/methods/page/PublishDate.md b/content/en/methods/page/PublishDate.md
index b1c0717a9..d1f2eb2a1 100644
--- a/content/en/methods/page/PublishDate.md
+++ b/content/en/methods/page/PublishDate.md
@@ -29,7 +29,7 @@ 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&nbsp;[details].
-[`time.Format`]: /functions/time/format
+[`time.Format`]: /functions/time/format/
[details]: /getting-started/configuration/#configure-dates
-[time methods]: /methods/time
+[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 258a294d0..12686c695 100644
--- a/content/en/methods/page/RawContent.md
+++ b/content/en/methods/page/RawContent.md
@@ -25,7 +25,7 @@ This is useful when rendering a page in a plain text [output format].
[Shortcodes] within the content are not rendered. To get the raw content with shortcodes rendered, use the [`RenderShortcodes`] method on a `Page` object.
[shortcodes]: /getting-started/glossary/#shortcode
-[`RenderShortcodes`]: /methods/page/rendershortcodes
+[`RenderShortcodes`]: /methods/page/rendershortcodes/
{{% /note %}}
-[output format]: /templates/output-formats
+[output format]: /templates/output-formats/
diff --git a/content/en/methods/page/RegularPages.md b/content/en/methods/page/RegularPages.md
index b0ca7b1e1..d3327702e 100644
--- a/content/en/methods/page/RegularPages.md
+++ b/content/en/methods/page/RegularPages.md
@@ -72,7 +72,7 @@ In the last example, the collection includes pages in the resources subdirectory
{{% note %}}
When used with the `Site` object, the `RegularPages` method recursively returns all regular pages within the site. See&nbsp;[details].
-[details]: /methods/site/regularpages
+[details]: /methods/site/regularpages/
{{% /note %}}
```go-html-template
diff --git a/content/en/methods/page/Render.md b/content/en/methods/page/Render.md
index bc3f58352..9a70d2bed 100644
--- a/content/en/methods/page/Render.md
+++ b/content/en/methods/page/Render.md
@@ -70,6 +70,6 @@ layouts/_default/li.html
See [content views] for more examples.
-[content views]: /templates/views
-[`partial`]: /functions/partials/include
+[content views]: /templates/views/
+[`partial`]: /functions/partials/include/
[content type]: /getting-started/glossary/#content-type
diff --git a/content/en/methods/page/RenderShortcodes.md b/content/en/methods/page/RenderShortcodes.md
index 4636bf8f5..a4120f69a 100644
--- a/content/en/methods/page/RenderShortcodes.md
+++ b/content/en/methods/page/RenderShortcodes.md
@@ -22,11 +22,12 @@ Use this method in shortcode templates to compose a page from multiple content f
For example:
{{< code file=layouts/shortcodes/include.html >}}
-{{ $p := site.GetPage (.Get 0) }}
-{{ $p.RenderShortcodes }}
+{{ with site.GetPage (.Get 0) }}
+ {{ .RenderShortcodes }}
+{{ end }}
{{< /code >}}
-Then in your markdown:
+Then call the shortcode in your Markdown:
{{< code file=content/about.md lang=md >}}
{{%/* include "/snippets/services.md" */%}}
@@ -34,14 +35,14 @@ Then in your markdown:
{{%/* include "/snippets/leadership.md" */%}}
{{< /code >}}
-Each of the included markdown files can contain calls to other shortcodes.
+Each of the included Markdown files can contain calls to other shortcodes.
## Shortcode notation
In the example above it's important to understand the difference between the two delimiters used when calling a shortcode:
- `{{</* myshortcode */>}}` tells Hugo that the rendered shortcode does not need further processing. For example, the shortcode content is HTML.
-- `{{%/* myshortcode */%}}` tells Hugo that the rendered shortcode needs further processing. For example, the shortcode content is markdown.
+- `{{%/* myshortcode */%}}` tells Hugo that the rendered shortcode needs further processing. For example, the shortcode content is Markdown.
Use the latter for the "include" shortcode described above.
@@ -75,4 +76,4 @@ https://example.org/privacy/
An *emphasized* word.
```
-Note that the shortcode within the content file was rendered, but the surrounding markdown was preserved.
+Note that the shortcode within the content file was rendered, but the surrounding Markdown was preserved.
diff --git a/content/en/methods/page/RenderString.md b/content/en/methods/page/RenderString.md
index 5782cd2b1..1a92c78c6 100644
--- a/content/en/methods/page/RenderString.md
+++ b/content/en/methods/page/RenderString.md
@@ -47,5 +47,5 @@ Render with [Pandoc]:
{{ .RenderString $opts $s }} → <p>H<sub>2</sub>O</p>
```
-[markup identifier]: /content-management/formats/#list-of-content-formats
+[markup identifier]: /content-management/formats/#classification
[pandoc]: https://www.pandoc.org/
diff --git a/content/en/methods/page/Resources.md b/content/en/methods/page/Resources.md
index 140b50020..54a61a2e4 100644
--- a/content/en/methods/page/Resources.md
+++ b/content/en/methods/page/Resources.md
@@ -75,11 +75,11 @@ With the `GetMatch` and `Match` methods, Hugo determines a match using a case-in
{{% include "functions/_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
+[`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
[page bundle]: /getting-started/glossary/#page-bundle
diff --git a/content/en/methods/page/Scratch.md b/content/en/methods/page/Scratch.md
index f9ce7f7fb..8fef31893 100644
--- a/content/en/methods/page/Scratch.md
+++ b/content/en/methods/page/Scratch.md
@@ -1,6 +1,6 @@
---
title: Scratch
-description: Creates a "scratch pad" on the given page to store and manipulate data.
+description: Returns a "scratch pad" on the given page to store and manipulate data.
categories: []
keywords: []
action:
@@ -9,6 +9,7 @@ action:
- functions/collections/NewScratch
returnType: maps.Scratch
signatures: [PAGE.Scratch]
+toc: true
aliases: [/extras/scratch/,/doc/scratch/,/functions/scratch]
---
@@ -16,8 +17,28 @@ The `Scratch` method on a `Page` object creates a [scratch pad] to store and man
To create a locally scoped scratch pad that is not attached to a `Page` object, use the [`newScratch`] function.
-[`Store`]: /methods/page/store
-[`newScratch`]: functions/collections/newscratch
+[`Store`]: /methods/page/store/
+[`newScratch`]: /functions/collections/newscratch/
[scratch pad]: /getting-started/glossary/#scratch-pad
{{% include "methods/page/_common/scratch-methods.md" %}}
+
+## Determinate values
+
+The `Scratch` method is often used to set scratch pad values 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] variable:
+
+[noop]: /getting-started/glossary/#noop
+
+```go-html-template
+{{ $noop := .Content }}
+{{ .Store.Get "mykey" }}
+```
+
+You can also trigger content rendering with the `FuzzyWordCount`, `Len`, `Plain`, `PlainWords`, `ReadingTime`, `Summary`, `Truncated`, and `WordCount` methods. For example:
+
+```go-html-template
+{{ $noop := .WordCount }}
+{{ .Store.Get "mykey" }}
+```
diff --git a/content/en/methods/page/Section.md b/content/en/methods/page/Section.md
index 30c8a9837..8e027a5a1 100644
--- a/content/en/methods/page/Section.md
+++ b/content/en/methods/page/Section.md
@@ -50,5 +50,5 @@ This is similar to using the [`Type`] method with the `where` function
However, if the `type` field in front matter has been defined on one or more pages, the page collection based on `Type` will be different than the page collection based on `Section`.
-[`where`]: /functions/collections/where
-[`Type`]: /methods/page/type
+[`where`]: /functions/collections/where/
+[`Type`]: /methods/page/type/
diff --git a/content/en/methods/page/Sections.md b/content/en/methods/page/Sections.md
index d64440038..4cce1a4fb 100644
--- a/content/en/methods/page/Sections.md
+++ b/content/en/methods/page/Sections.md
@@ -35,11 +35,11 @@ content/
│ ├── bidding.md
│ └── payment.md
├── books/
-│ ├── _index.md <-- front matter: weight = 10
+│ ├── _index.md <-- front matter: weight = 20
│ ├── book-1.md
│ └── book-2.md
├── films/
-│ ├── _index.md <-- front matter: weight = 20
+│ ├── _index.md <-- front matter: weight = 10
│ ├── film-1.md
│ └── film-2.md
└── _index.md
diff --git a/content/en/methods/page/Site.md b/content/en/methods/page/Site.md
index 34748facd..d83c45e0a 100644
--- a/content/en/methods/page/Site.md
+++ b/content/en/methods/page/Site.md
@@ -12,7 +12,7 @@ action:
See [Site methods].
-[Site methods]: /methods/site
+[Site methods]: /methods/site/
```go-html-template
{{ .Site.Title }}
diff --git a/content/en/methods/page/Sitemap.md b/content/en/methods/page/Sitemap.md
index 08ff3f5d0..d6159267d 100644
--- a/content/en/methods/page/Sitemap.md
+++ b/content/en/methods/page/Sitemap.md
@@ -14,15 +14,22 @@ Access to the `Sitemap` method on a `Page` object is restricted to [sitemap temp
## Methods
-ChangeFreq
-: (`string`) How frequently a page is likely to change. Valid values are `always`, `hourly`, `daily`, `weekly`, `monthly`, `yearly`, and `never`. Default is "" (change frequency omitted from rendered 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).
```go-html-template
{{ .Sitemap.ChangeFreq }}
```
-Priority
-: (`float`) The priority of a page relative to any other page on the site. Valid values range from 0.0 to 1.0. Default is -1 (priority omitted from rendered sitemap).
+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).
```go-html-template
{{ .Sitemap.Priority }}
diff --git a/content/en/methods/page/Sites.md b/content/en/methods/page/Sites.md
index 1fbdfcdcd..cd240655e 100644
--- a/content/en/methods/page/Sites.md
+++ b/content/en/methods/page/Sites.md
@@ -52,10 +52,10 @@ Produces a list of links to each home page:
</ul>
```
-To render a link to home page of the primary (first) language:
+To render a link to the home page of the site corresponding to the default content language:
```go-html-template
-{{ with .Sites.First }}
+{{ with .Sites.Default }}
<a href="{{ .Home.Permalink }}">{{ .Title }}</a>
{{ end }}
```
diff --git a/content/en/methods/page/Store.md b/content/en/methods/page/Store.md
index 8bc16034b..e7090fe79 100644
--- a/content/en/methods/page/Store.md
+++ b/content/en/methods/page/Store.md
@@ -1,6 +1,6 @@
---
title: Store
-description: Creates a persistent "scratch pad" on the given page to store and manipulate data.
+description: Returns a persistent "scratch pad" on the given page to store and manipulate data.
categories: []
keywords: []
action:
@@ -9,6 +9,7 @@ action:
- functions/collections/NewScratch
returnType: maps.Scratch
signatures: [PAGE.Store]
+toc: true
aliases: [/functions/store]
---
@@ -16,8 +17,8 @@ The `Store` method on a `Page` object creates a persistent [scratch pad] to stor
To create a locally scoped scratch pad that is not attached to a `Page` object, use the [`newScratch`] function.
-[`Scratch`]: /methods/page/scratch
-[`newScratch`]: functions/collections/newscratch
+[`Scratch`]: /methods/page/scratch/
+[`newScratch`]: /functions/collections/newscratch/
[scratch pad]: /getting-started/glossary/#scratch-pad
## Methods
@@ -102,3 +103,23 @@ Removes the given key.
{{ .Store.Set "greeting" "Hello" }}
{{ .Store.Delete "greeting" }}
```
+
+## Determinate values
+
+The `Store` method is often used to set scratch pad values 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] variable:
+
+[noop]: /getting-started/glossary/#noop
+
+```go-html-template
+{{ $noop := .Content }}
+{{ .Store.Get "mykey" }}
+```
+
+You can also trigger content rendering with the `FuzzyWordCount`, `Len`, `Plain`, `PlainWords`, `ReadingTime`, `Summary`, `Truncated`, and `WordCount` methods. For example:
+
+```go-html-template
+{{ $noop := .WordCount }}
+{{ .Store.Get "mykey" }}
+```
diff --git a/content/en/methods/page/Summary.md b/content/en/methods/page/Summary.md
index 37ce86589..e4542d258 100644
--- a/content/en/methods/page/Summary.md
+++ b/content/en/methods/page/Summary.md
@@ -11,10 +11,14 @@ action:
signatures: [PAGE.Summary]
---
+<!-- Do not remove the manual summary divider below. -->
+<!-- If you do, you will break its first literal usage on this page. -->
+<!--more-->
+
There are three ways to define the [content summary]:
1. Let Hugo create the summary based on the first 70 words. You can change the number of words by setting the `summaryLength` in your site configuration.
-2. Manually split the content with a `<--more-->` tag in markdown. Everything before the tag is included in the summary.
+2. Manually split the content with a `<!--more-->` tag in Markdown. Everything before the tag is included in the summary.
3. Create a `summary` field in front matter.
To list the pages in a section with a summary beneath each link:
@@ -26,4 +30,4 @@ To list the pages in a section with a summary beneath each link:
{{ end }}
```
-[content summary]: /content-management/summaries
+[content summary]: /content-management/summaries/
diff --git a/content/en/methods/page/TableOfContents.md b/content/en/methods/page/TableOfContents.md
index 2ab182e8c..38c3ff17b 100644
--- a/content/en/methods/page/TableOfContents.md
+++ b/content/en/methods/page/TableOfContents.md
@@ -8,9 +8,10 @@ action:
- methods/page/Fragments
returnType: template.HTML
signatures: [PAGE.TableOfContents]
+aliases: [/content-management/toc/]
---
-The `TableOfContents` method on a `Page` object returns an ordered or unordered list of the markdown [ATX] and [setext] headings within the page content.
+The `TableOfContents` method on a `Page` object returns an ordered or unordered list of the Markdown [ATX] and [setext] headings within the page content.
[atx]: https://spec.commonmark.org/0.30/#atx-headings
[setext]: https://spec.commonmark.org/0.30/#setext-headings
diff --git a/content/en/methods/page/Title.md b/content/en/methods/page/Title.md
index 52e46ff44..5c2c98d6b 100644
--- a/content/en/methods/page/Title.md
+++ b/content/en/methods/page/Title.md
@@ -20,19 +20,21 @@ title = 'About us'
{{ .Title }} → About us
```
-With section pages not backed by a file, the `Title` method returns the section name, pluralized and converted to title case.
-
-To disable [pluralization]:
+With section, taxonomy, and term pages not backed by a file, the `Title` method returns the section name, capitalized and pluralized. You can disable these transformations by setting [`capitalizeListTitles`] and [`pluralizeListTitles`] in your site configuration. For example:
{{< code-toggle file=hugo >}}
+capitalizeListTitles = false
pluralizeListTitles = false
{{< /code-toggle >}}
-To change the [title case style], specify one of `ap`, `chicago`, `go`, `firstupper`, or `none`:
+You can change the capitalization style in your site configuration to one of `ap`, `chicago`, `go`, `firstupper`, or `none`. For example:
{{< code-toggle file=hugo >}}
-titleCaseStyle = "ap"
+titleCaseStyle = "firstupper"
{{< /code-toggle >}}
-[pluralization]: /functions/inflect/pluralize
-[title case style]: /getting-started/configuration/#configure-title-case
+ See [details].
+
+[`capitalizeListTitles`]: /getting-started/configuration/#capitalizelisttitles
+[`pluralizeListTitles`]: /getting-started/configuration/#pluralizelisttitles
+[details]: /getting-started/configuration/#configure-title-case
diff --git a/content/en/methods/page/Translations.md b/content/en/methods/page/Translations.md
index 1ed256630..597a9aeb6 100644
--- a/content/en/methods/page/Translations.md
+++ b/content/en/methods/page/Translations.md
@@ -1,6 +1,6 @@
---
title: Translations
-description: Returns all translation of the given page, excluding the current language.
+description: Returns all translations of the given page, excluding the current language.
categories: []
keywords: []
action:
@@ -63,9 +63,9 @@ And this template:
{{ with .Translations }}
<ul>
{{ range . }}
- {{ $langName := or .Language.LanguageName .Language.Lang }}
- {{ $langCode := or .Language.LanguageCode .Language.Lang }}
- <li><a href="{{ .RelPermalink }}" hreflang="{{ $langCode }}">{{ .LinkTitle }} ({{ $langName }})</a></li>
+ <li>
+ <a href="{{ .RelPermalink }}" hreflang="{{ .Language.LanguageCode }}">{{ .LinkTitle }} ({{ or .Language.LanguageName .Language.Lang }})</a>
+ </li>
{{ end }}
</ul>
{{ end }}
diff --git a/content/en/methods/page/Truncated.md b/content/en/methods/page/Truncated.md
index e6051f0cd..0785f40cb 100644
--- a/content/en/methods/page/Truncated.md
+++ b/content/en/methods/page/Truncated.md
@@ -13,7 +13,7 @@ action:
There are three ways to define the [content summary]:
1. Let Hugo create the summary based on the first 70 words. You can change the number of words by setting the `summaryLength` in your site configuration.
-2. Manually split the content with a `<--more-->` tag in markdown. Everything before the tag is included in the summary.
+2. Manually split the content with a `<--more-->` tag in Markdown. Everything before the tag is included in the summary.
3. Create a `summary` field in front matter.
{{% note %}}
@@ -32,4 +32,4 @@ The `Truncated` method returns `true` if the content length exceeds the summary
{{ end }}
```
-[content summary]: /content-management/summaries
+[content summary]: /content-management/summaries/
diff --git a/content/en/methods/page/WordCount.md b/content/en/methods/page/WordCount.md
index bb1fdcf94..70fe407ab 100644
--- a/content/en/methods/page/WordCount.md
+++ b/content/en/methods/page/WordCount.md
@@ -17,4 +17,4 @@ action:
To round up to nearest multiple of 100, use the [`FuzzyWordCount`] method.
-[`FuzzyWordCount`]: /methods/page/fuzzywordcount
+[`FuzzyWordCount`]: /methods/page/fuzzywordcount/
diff --git a/content/en/methods/page/_common/_index.md b/content/en/methods/page/_common/_index.md
index 47d5812fb..4328d4d14 100644
--- a/content/en/methods/page/_common/_index.md
+++ b/content/en/methods/page/_common/_index.md
@@ -7,7 +7,7 @@ cascade:
---
<!--
-Files within this headless branch bundle are markdown snippets. Each file must contain front matter delimiters, though front matter fields are not required.
+Files within this headless branch bundle are Markdown snippets. Each file must contain front matter delimiters, though front matter fields are not required.
Include the rendered content using the "include" shortcode.
-->
diff --git a/content/en/methods/page/_common/output-format-definition.md b/content/en/methods/page/_common/output-format-definition.md
index 25944464a..412c5cee6 100644
--- a/content/en/methods/page/_common/output-format-definition.md
+++ b/content/en/methods/page/_common/output-format-definition.md
@@ -8,4 +8,4 @@ Hugo generates one or more files per page when building a site. For example, whe
[taxonomy]: /getting-started/glossary/#taxonomy
[term]: /getting-started/glossary/#term
[page kind]: /getting-started/glossary/#page-kind
-[details]: /templates/output-formats
+[details]: /templates/output-formats/
diff --git a/content/en/methods/pager/First.md b/content/en/methods/pager/First.md
new file mode 100644
index 000000000..85e2e0dd3
--- /dev/null
+++ b/content/en/methods/pager/First.md
@@ -0,0 +1,44 @@
+---
+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]
+---
+
+Use the `First` method to build navigation between pagers.
+
+```go-html-template
+{{ $pages := where site.RegularPages "Type" "posts" }}
+{{ $paginator := .Paginate $pages }}
+
+{{ range $paginator.Pages }}
+ <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
+{{ end }}
+
+{{ with $paginator }}
+ <ul>
+ {{ with .First }}
+ <li><a href="{{ .URL }}">First</a></li>
+ {{ end }}
+ {{ with .Prev }}
+ <li><a href="{{ .URL }}">Previous</a></li>
+ {{ end }}
+ {{ with .Next }}
+ <li><a href="{{ .URL }}">Next</a></li>
+ {{ end }}
+ {{ with .Last }}
+ <li><a href="{{ .URL }}">Last</a></li>
+ {{ end }}
+ </ul>
+{{ end }}
+```
diff --git a/content/en/methods/pager/HasNext.md b/content/en/methods/pager/HasNext.md
new file mode 100644
index 000000000..e7550d788
--- /dev/null
+++ b/content/en/methods/pager/HasNext.md
@@ -0,0 +1,72 @@
+---
+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]
+---
+
+Use the `HasNext` method to build navigation between pagers.
+
+```go-html-template
+{{ $pages := where site.RegularPages "Type" "posts" }}
+{{ $paginator := .Paginate $pages }}
+
+{{ range $paginator.Pages }}
+ <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
+{{ end }}
+
+{{ with $paginator }}
+ <ul>
+ {{ with .First }}
+ <li><a href="{{ .URL }}">First</a></li>
+ {{ end }}
+ {{ if .HasPrev }}
+ <li><a href="{{ .Prev.URL }}">Previous</a></li>
+ {{ end }}
+ {{ if .HasNext }}
+ <li><a href="{{ .Next.URL }}">Next</a></li>
+ {{ end }}
+ {{ with .Last }}
+ <li><a href="{{ .URL }}">Last</a></li>
+ {{ end }}
+ </ul>
+{{ end }}
+```
+
+You can also write the above without using the `HasNext` method:
+
+```go-html-template
+{{ $pages := where site.RegularPages "Type" "posts" }}
+{{ $paginator := .Paginate $pages }}
+
+{{ range $paginator.Pages }}
+ <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
+{{ end }}
+
+{{ with $paginator }}
+ <ul>
+ {{ with .First }}
+ <li><a href="{{ .URL }}">First</a></li>
+ {{ end }}
+ {{ with .Prev }}
+ <li><a href="{{ .URL }}">Previous</a></li>
+ {{ end }}
+ {{ with .Next }}
+ <li><a href="{{ .URL }}">Next</a></li>
+ {{ end }}
+ {{ with .Last }}
+ <li><a href="{{ .URL }}">Last</a></li>
+ {{ end }}
+ </ul>
+{{ end }}
+```
diff --git a/content/en/methods/pager/HasPrev.md b/content/en/methods/pager/HasPrev.md
new file mode 100644
index 000000000..00d5c1dea
--- /dev/null
+++ b/content/en/methods/pager/HasPrev.md
@@ -0,0 +1,72 @@
+---
+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]
+---
+
+Use the `HasPrev` method to build navigation between pagers.
+
+```go-html-template
+{{ $pages := where site.RegularPages "Type" "posts" }}
+{{ $paginator := .Paginate $pages }}
+
+{{ range $paginator.Pages }}
+ <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
+{{ end }}
+
+{{ with $paginator }}
+ <ul>
+ {{ with .First }}
+ <li><a href="{{ .URL }}">First</a></li>
+ {{ end }}
+ {{ if .HasPrev }}
+ <li><a href="{{ .Prev.URL }}">Previous</a></li>
+ {{ end }}
+ {{ if .HasNext }}
+ <li><a href="{{ .Next.URL }}">Next</a></li>
+ {{ end }}
+ {{ with .Last }}
+ <li><a href="{{ .URL }}">Last</a></li>
+ {{ end }}
+ </ul>
+{{ end }}
+```
+
+You can also write the above without using the `HasPrev` method:
+
+```go-html-template
+{{ $pages := where site.RegularPages "Type" "posts" }}
+{{ $paginator := .Paginate $pages }}
+
+{{ range $paginator.Pages }}
+ <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
+{{ end }}
+
+{{ with $paginator }}
+ <ul>
+ {{ with .First }}
+ <li><a href="{{ .URL }}">First</a></li>
+ {{ end }}
+ {{ with .Prev }}
+ <li><a href="{{ .URL }}">Previous</a></li>
+ {{ end }}
+ {{ with .Next }}
+ <li><a href="{{ .URL }}">Next</a></li>
+ {{ end }}
+ {{ with .Last }}
+ <li><a href="{{ .URL }}">Last</a></li>
+ {{ end }}
+ </ul>
+{{ end }}
+```
diff --git a/content/en/methods/pager/Last.md b/content/en/methods/pager/Last.md
new file mode 100644
index 000000000..074a46943
--- /dev/null
+++ b/content/en/methods/pager/Last.md
@@ -0,0 +1,44 @@
+---
+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]
+---
+
+Use the `Last` method to build navigation between pagers.
+
+```go-html-template
+{{ $pages := where site.RegularPages "Type" "posts" }}
+{{ $paginator := .Paginate $pages }}
+
+{{ range $paginator.Pages }}
+ <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
+{{ end }}
+
+{{ with $paginator }}
+ <ul>
+ {{ with .First }}
+ <li><a href="{{ .URL }}">First</a></li>
+ {{ end }}
+ {{ with .Prev }}
+ <li><a href="{{ .URL }}">Previous</a></li>
+ {{ end }}
+ {{ with .Next }}
+ <li><a href="{{ .URL }}">Next</a></li>
+ {{ end }}
+ {{ with .Last }}
+ <li><a href="{{ .URL }}">Last</a></li>
+ {{ end }}
+ </ul>
+{{ end }}
+```
diff --git a/content/en/methods/pager/Next.md b/content/en/methods/pager/Next.md
new file mode 100644
index 000000000..099ac198e
--- /dev/null
+++ b/content/en/methods/pager/Next.md
@@ -0,0 +1,44 @@
+---
+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]
+---
+
+Use the `Next` method to build navigation between pagers.
+
+```go-html-template
+{{ $pages := where site.RegularPages "Type" "posts" }}
+{{ $paginator := .Paginate $pages }}
+
+{{ range $paginator.Pages }}
+ <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
+{{ end }}
+
+{{ with $paginator }}
+ <ul>
+ {{ with .First }}
+ <li><a href="{{ .URL }}">First</a></li>
+ {{ end }}
+ {{ with .Prev }}
+ <li><a href="{{ .URL }}">Previous</a></li>
+ {{ end }}
+ {{ with .Next }}
+ <li><a href="{{ .URL }}">Next</a></li>
+ {{ end }}
+ {{ with .Last }}
+ <li><a href="{{ .URL }}">Last</a></li>
+ {{ end }}
+ </ul>
+{{ end }}
+```
diff --git a/content/en/methods/pager/NumberOfElements.md b/content/en/methods/pager/NumberOfElements.md
new file mode 100644
index 000000000..3980cdfe2
--- /dev/null
+++ b/content/en/methods/pager/NumberOfElements.md
@@ -0,0 +1,25 @@
+---
+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]
+---
+
+```go-html-template
+{{ $pages := where site.RegularPages "Type" "posts" }}
+{{ $paginator := .Paginate $pages }}
+
+{{ range $paginator.Pages }}
+ <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
+{{ end }}
+
+{{ with $paginator }}
+ {{ .NumberOfElements }}
+{{ end }}
+```
diff --git a/content/en/methods/pager/PageGroups.md b/content/en/methods/pager/PageGroups.md
new file mode 100644
index 000000000..9dee18c0d
--- /dev/null
+++ b/content/en/methods/pager/PageGroups.md
@@ -0,0 +1,29 @@
+---
+title: PageGroups
+description: Returns the page groups in the current pager.
+categories: []
+keywords: []
+action:
+ related:
+ - methods/page/Paginate
+ returnType: page.PagesGroup
+ signatures: [PAGER.PageGroups]
+---
+
+Use the `PageGroups` method with any of the [grouping methods].
+
+[grouping methods]: /quick-reference/page-collections/#group
+
+```go-html-template
+{{ $pages := where site.RegularPages "Type" "posts" }}
+{{ $paginator := .Paginate ($pages.GroupByDate "Jan 2006") }}
+
+{{ range $paginator.PageGroups }}
+ <h2>{{ .Key }}</h2>
+ {{ range .Pages }}
+ <h3><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h3>
+ {{ end }}
+{{ end }}
+
+{{ template "_internal/pagination.html" . }}
+```
diff --git a/content/en/methods/pager/PageNumber.md b/content/en/methods/pager/PageNumber.md
new file mode 100644
index 000000000..0d99c5a15
--- /dev/null
+++ b/content/en/methods/pager/PageNumber.md
@@ -0,0 +1,31 @@
+---
+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]
+---
+
+Use the `PageNumber` method to build navigation between pagers.
+
+```go-html-template
+{{ $pages := where site.RegularPages "Type" "posts" }}
+{{ $paginator := .Paginate $pages }}
+
+{{ range $paginator.Pages }}
+ <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
+{{ end }}
+
+{{ with $paginator }}
+ <ul>
+ {{ range .Pagers }}
+ <li><a href="{{ .URL }}">{{ .PageNumber }}</a></li>
+ {{ end }}
+ </ul>
+{{ end }}
+```
diff --git a/content/en/methods/pager/PageSize.md b/content/en/methods/pager/PageSize.md
new file mode 100644
index 000000000..a400f929a
--- /dev/null
+++ b/content/en/methods/pager/PageSize.md
@@ -0,0 +1,24 @@
+---
+title: PageSize
+description: Returns the maximum number of pages per pager.
+categories: []
+keywords: []
+action:
+ related:
+ - methods/page/Paginate
+ returnType: int
+ signatures: [PAGER.PageSize]
+---
+
+```go-html-template
+{{ $pages := where site.RegularPages "Type" "posts" }}
+{{ $paginator := .Paginate $pages }}
+
+{{ range $paginator.Pages }}
+ <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
+{{ end }}
+
+{{ with $paginator }}
+ {{ .PageSize }}
+{{ end }}
+```
diff --git a/content/en/methods/pager/Pagers.md b/content/en/methods/pager/Pagers.md
new file mode 100644
index 000000000..5f167c13e
--- /dev/null
+++ b/content/en/methods/pager/Pagers.md
@@ -0,0 +1,30 @@
+---
+title: Pagers
+description: Returns the pagers collection.
+categories: []
+keywords: []
+action:
+ related:
+ - methods/page/Paginate
+ returnType: page.pagers
+ signatures: [PAGER.Pagers]
+---
+
+Use the `Pagers` method to build navigation between pagers.
+
+```go-html-template
+{{ $pages := where site.RegularPages "Type" "posts" }}
+{{ $paginator := .Paginate $pages }}
+
+{{ range $paginator.Pages }}
+ <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
+{{ end }}
+
+{{ with $paginator }}
+ <ul>
+ {{ range .Pagers }}
+ <li><a href="{{ .URL }}">{{ .PageNumber }}</a></li>
+ {{ end }}
+ </ul>
+{{ end }}
+```
diff --git a/content/en/methods/pager/Pages.md b/content/en/methods/pager/Pages.md
new file mode 100644
index 000000000..1c049d53b
--- /dev/null
+++ b/content/en/methods/pager/Pages.md
@@ -0,0 +1,22 @@
+---
+title: Pages
+description: Returns the pages in the current pager.
+categories: []
+keywords: []
+action:
+ related:
+ - methods/page/Paginate
+ returnType: page.Pages
+ signatures: [PAGER.Pages]
+---
+
+```go-html-template
+{{ $pages := where site.RegularPages "Type" "posts" }}
+{{ $paginator := .Paginate $pages }}
+
+{{ range $paginator.Pages }}
+ <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
+{{ end }}
+
+{{ template "_internal/pagination.html" . }}
+```
diff --git a/content/en/methods/pager/Prev.md b/content/en/methods/pager/Prev.md
new file mode 100644
index 000000000..c129c6a5a
--- /dev/null
+++ b/content/en/methods/pager/Prev.md
@@ -0,0 +1,44 @@
+---
+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]
+---
+
+Use the `Prev` method to build navigation between pagers.
+
+```go-html-template
+{{ $pages := where site.RegularPages "Type" "posts" }}
+{{ $paginator := .Paginate $pages }}
+
+{{ range $paginator.Pages }}
+ <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
+{{ end }}
+
+{{ with $paginator }}
+ <ul>
+ {{ with .First }}
+ <li><a href="{{ .URL }}">First</a></li>
+ {{ end }}
+ {{ with .Prev }}
+ <li><a href="{{ .URL }}">Previous</a></li>
+ {{ end }}
+ {{ with .Next }}
+ <li><a href="{{ .URL }}">Next</a></li>
+ {{ end }}
+ {{ with .Last }}
+ <li><a href="{{ .URL }}">Last</a></li>
+ {{ end }}
+ </ul>
+{{ end }}
+```
diff --git a/content/en/methods/pager/TotalNumberOfElements.md b/content/en/methods/pager/TotalNumberOfElements.md
new file mode 100644
index 000000000..3cd1c8dad
--- /dev/null
+++ b/content/en/methods/pager/TotalNumberOfElements.md
@@ -0,0 +1,25 @@
+---
+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]
+---
+
+```go-html-template
+{{ $pages := where site.RegularPages "Type" "posts" }}
+{{ $paginator := .Paginate $pages }}
+
+{{ range $paginator.Pages }}
+ <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
+{{ end }}
+
+{{ with $paginator }}
+ {{ .TotalNumberOfElements }}
+{{ end }}
+```
diff --git a/content/en/methods/pager/TotalPages.md b/content/en/methods/pager/TotalPages.md
new file mode 100644
index 000000000..e305beeff
--- /dev/null
+++ b/content/en/methods/pager/TotalPages.md
@@ -0,0 +1,41 @@
+---
+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]
+---
+
+Use the `TotalPages` method to build navigation between pagers.
+
+```go-html-template
+{{ $pages := where site.RegularPages "Type" "posts" }}
+{{ $paginator := .Paginate $pages }}
+
+{{ range $paginator.Pages }}
+ <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
+{{ end }}
+
+{{ with $paginator }}
+ <p>Pager {{ .PageNumber }} of {{ .TotalPages }}</p>
+ <ul>
+ {{ with .First }}
+ <li><a href="{{ .URL }}">First</a></li>
+ {{ end }}
+ {{ with .Prev }}
+ <li><a href="{{ .URL }}">Previous</a></li>
+ {{ end }}
+ {{ with .Next }}
+ <li><a href="{{ .URL }}">Next</a></li>
+ {{ end }}
+ {{ with .Last }}
+ <li><a href="{{ .URL }}">Last</a></li>
+ {{ end }}
+ </ul>
+{{ end }}
+```
diff --git a/content/en/methods/pager/URL.md b/content/en/methods/pager/URL.md
new file mode 100644
index 000000000..3daddbbd5
--- /dev/null
+++ b/content/en/methods/pager/URL.md
@@ -0,0 +1,39 @@
+---
+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]
+---
+
+Use the `URL` method to build navigation between pagers.
+
+```go-html-template
+{{ $pages := where site.RegularPages "Type" "posts" }}
+{{ $paginator := .Paginate $pages }}
+
+{{ range $paginator.Pages }}
+ <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
+{{ end }}
+
+{{ with $paginator }}
+ <ul>
+ {{ with .First }}
+ <li><a href="{{ .URL }}">First</a></li>
+ {{ end }}
+ {{ with .Prev }}
+ <li><a href="{{ .URL }}">Previous</a></li>
+ {{ end }}
+ {{ with .Next }}
+ <li><a href="{{ .URL }}">Next</a></li>
+ {{ end }}
+ {{ with .Last }}
+ <li><a href="{{ .URL }}">Last</a></li>
+ {{ end }}
+ </ul>
+{{ end }}
+```
diff --git a/content/en/methods/pager/_index.md b/content/en/methods/pager/_index.md
new file mode 100644
index 000000000..58a1def7b
--- /dev/null
+++ b/content/en/methods/pager/_index.md
@@ -0,0 +1,14 @@
+---
+title: Pager methods
+linkTitle: Pager
+description: Use these methods with Pager objects when paginating a 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/_common/_index.md b/content/en/methods/pages/_common/_index.md
index 47d5812fb..4328d4d14 100644
--- a/content/en/methods/pages/_common/_index.md
+++ b/content/en/methods/pages/_common/_index.md
@@ -7,7 +7,7 @@ cascade:
---
<!--
-Files within this headless branch bundle are markdown snippets. Each file must contain front matter delimiters, though front matter fields are not required.
+Files within this headless branch bundle are Markdown snippets. Each file must contain front matter delimiters, though front matter fields are not required.
Include the rendered content using the "include" shortcode.
-->
diff --git a/content/en/methods/resource/Colors.md b/content/en/methods/resource/Colors.md
index 1452d558f..b062210ba 100644
--- a/content/en/methods/resource/Colors.md
+++ b/content/en/methods/resource/Colors.md
@@ -5,18 +5,174 @@ categories: []
keywords: []
action:
related: []
- returnType: '[]string'
+ returnType: '[]images.Color'
signatures: [RESOURCE.Colors]
+toc: true
+math: true
---
{{< new-in 0.104.0 >}}
+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 "methods/resource/_common/global-page-remote-resources.md" %}}
+
+## Methods
+
+Each color is an object with the following methods:
+
+ColorHex
+{{< new-in 0.125.0 >}}
+: (`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.
+
+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
+
+## Sorting
+
+As a contrived example, create a table of an image's dominant colors with the most dominant color first, and display the relative luminance of each dominant color:
+
```go-html-template
{{ with resources.Get "images/a.jpg" }}
- {{ .Colors }} → [#bebebd #514947 #768a9a #647789 #90725e #a48974]
+ <table>
+ <thead>
+ <tr>
+ <th>Color</th>
+ <th>Relative luminance</th>
+ </tr>
+ </thead>
+ <tbody>
+ {{ range .Colors }}
+ <tr>
+ <td>{{ .ColorHex }}</td>
+ <td>{{ .Luminance | lang.FormatNumber 4 }}</td>
+ </tr>
+ {{ end }}
+ </tbody>
+ </table>
{{ end }}
```
-This method is fast, but if you also scale down your images, it would be good for performance to extract the colors from the scaled image.
+Hugo renders this to:
-{{% include "methods/resource/_common/global-page-remote-resources.md" %}}
+ColorHex|Relative luminance
+:--|:--
+`#bebebd`|`0.5145`
+`#514947`|`0.0697`
+`#768a9a`|`0.2436`
+`#647789`|`0.1771`
+`#90725e`|`0.1877`
+`#a48974`|`0.2704`
+
+To sort by dominance with the least dominant color first:
+
+```go-html-template
+{{ range .Colors | collections.Reverse }}
+```
+
+To sort by relative luminance with the darkest color first:
+
+```go-html-template
+{{ range sort .Colors "Luminance" }}
+```
+
+To sort by relative luminance with the lightest color first, use either of these constructs:
+
+```go-html-template
+{{ range sort .Colors "Luminance" | collections.Reverse }}
+{{ range sort .Colors "Luminance" "desc" }}
+```
+
+## Examples
+
+### Image borders
+
+To add a 5 pixel border to an image using the most dominant color:
+
+```go-html-template
+{{ with resources.Get "images/a.jpg" }}
+ {{ $mostDominant := index .Colors 0 }}
+ {{ $filter := images.Padding 5 $mostDominant }}
+ {{ with .Filter $filter }}
+ <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
+ {{ end }}
+{{ end }}
+```
+
+To add a 5 pixel border to an image using the darkest dominant color:
+
+```go-html-template
+{{ with resources.Get "images/a.jpg" }}
+ {{ $darkest := index (sort .Colors "Luminance") 0 }}
+ {{ $filter := images.Padding 5 $darkest }}
+ {{ with .Filter $filter }}
+ <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
+ {{ end }}
+{{ end }}
+```
+
+### Light text on dark background
+
+To create a text box where the foreground and background colors are derived from an image's lightest and darkest dominant colors:
+
+```go-html-template
+{{ with resources.Get "images/a.jpg" }}
+ {{ $darkest := index (sort .Colors "Luminance") 0 }}
+ {{ $lightest := index (sort .Colors "Luminance" "desc") 0 }}
+ <div style="background: {{ $darkest }};">
+ <div style="color: {{ $lightest }};">
+ <p>This is light text on a dark background.</p>
+ </div>
+ </div>
+{{ end }}
+```
+
+### WCAG contrast ratio
+
+In the previous example we placed light text on a dark background, but does this color combination conform to [WCAG] guidelines for either the [minimum] or the [enhanced] contrast ratio?
+
+The WCAG defines the [contrast ratio] as:
+
+$$contrast\ ratio = { L_1 + 0.05 \over L_2 + 0.05 }$$
+
+where $L_1$ is the relative luminance of the lightest color and $L_2$ is the relative luminance of the darkest color.
+
+Calculate the contrast ratio to determine WCAG conformance:
+
+```go-html-template
+{{ with resources.Get "images/a.jpg" }}
+ {{ $lightest := index (sort .Colors "Luminance" "desc") 0 }}
+ {{ $darkest := index (sort .Colors "Luminance") 0 }}
+ {{ $cr := div
+ (add $lightest.Luminance 0.05)
+ (add $darkest.Luminance 0.05)
+ }}
+ {{ if ge $cr 7.5 }}
+ {{ printf "The %.2f contrast ratio conforms to WCAG Level AAA." $cr }}
+ {{ else if ge $cr 4.5 }}
+ {{ printf "The %.2f contrast ratio conforms to WCAG Level AA." $cr }}
+ {{ else }}
+ {{ printf "The %.2f contrast ratio does not conform to WCAG guidelines." $cr }}
+ {{ end }}
+{{ end }}
+```
+
+
+[WCAG]: https://en.wikipedia.org/wiki/Web_Content_Accessibility_Guidelines
+[contrast ratio]: https://www.w3.org/TR/WCAG21/#dfn-contrast-ratio
+[enhanced]: https://www.w3.org/WAI/WCAG22/quickref/?showtechniques=145#contrast-enhanced
+[minimum]: https://www.w3.org/WAI/WCAG22/quickref/?showtechniques=145#contrast-minimum
diff --git a/content/en/methods/resource/Content.md b/content/en/methods/resource/Content.md
index a5945ff65..4135113e9 100644
--- a/content/en/methods/resource/Content.md
+++ b/content/en/methods/resource/Content.md
@@ -12,7 +12,7 @@ toc:
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
+[resource type]: /methods/resource/resourcetype/
{{< code file=assets/quotations/kipling.txt >}}
He travels the fastest who travels alone.
diff --git a/content/en/methods/resource/Data.md b/content/en/methods/resource/Data.md
index 0fbaf6199..43108fce8 100644
--- a/content/en/methods/resource/Data.md
+++ b/content/en/methods/resource/Data.md
@@ -13,7 +13,7 @@ action:
The `Data` method on a resource returned by the [`resources.GetRemote`] function returns information from the HTTP response.
-[`resources.GetRemote`]: functions/resources/getremote
+[`resources.GetRemote`]: /functions/resources/getremote/
```go-html-template
{{ $url := "https://example.org/images/a.jpg" }}
@@ -50,4 +50,4 @@ TransferEncoding
: (`string`) The transfer encoding.
-[`resources.GetRemote`]: functions/resources/getremote
+[`resources.GetRemote`]: /functions/resources/getremote/
diff --git a/content/en/methods/resource/Err.md b/content/en/methods/resource/Err.md
index f4b410aa7..6baa30e47 100644
--- a/content/en/methods/resource/Err.md
+++ b/content/en/methods/resource/Err.md
@@ -13,7 +13,7 @@ action:
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.
-[`resources.GetRemote`]: functions/resources/getremote
+[`resources.GetRemote`]: /functions/resources/getremote/
In this example we send an HTTP request to a nonexistent domain:
diff --git a/content/en/methods/resource/Exif.md b/content/en/methods/resource/Exif.md
index 765b4c92f..1d00ef3bc 100644
--- a/content/en/methods/resource/Exif.md
+++ b/content/en/methods/resource/Exif.md
@@ -15,7 +15,7 @@ Applicable to JPEG and TIFF images, the `Exif` method on an image `Resource` obj
## Methods
Date
-: (`time.Time`) Returns the image creation date/time. Format with the [`time.Format`]function.
+: (`time.Time`) Returns the image creation date/time. Format with the [`time.Format`] function.
Lat
: (`float64`) Returns the GPS latitude in degrees.
@@ -75,4 +75,4 @@ To list specific values:
[exif]: https://en.wikipedia.org/wiki/Exif
[site configuration]: /content-management/image-processing/#exif-data
-[`time.Format`]: /functions/time/format
+[`time.Format`]: /functions/time/format/
diff --git a/content/en/methods/resource/Filter.md b/content/en/methods/resource/Filter.md
index 329168da7..9db6bbe17 100644
--- a/content/en/methods/resource/Filter.md
+++ b/content/en/methods/resource/Filter.md
@@ -39,7 +39,7 @@ To apply two or more filters, executing from left to right:
You can also apply image filters using the [`images.Filter`] function.
-[`images.Filter`]: /functions/images/filter
+[`images.Filter`]: /functions/images/filter/
{{% 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
index 15927aea9..deeba9ab3 100644
--- a/content/en/methods/resource/Key.md
+++ b/content/en/methods/resource/Key.md
@@ -1,6 +1,7 @@
---
title: Key
description: Returns the unique key for the given resource, equivalent to its publishing path.
+draft: true
categories: []
keywords: []
action:
@@ -40,6 +41,6 @@ The `Key` method is useful if you need to get the resource's publishing path wit
{{% include "methods/resource/_common/global-page-remote-resources.md" %}}
-[`Permalink`]: /methods/resource/permalink
-[`RelPermalink`]: /methods/resource/relpermalink
-[`resources.Copy`]: /functions/resources/copy
+[`Permalink`]: /methods/resource/permalink/
+[`RelPermalink`]: /methods/resource/relpermalink/
+[`resources.Copy`]: /functions/resources/copy/
diff --git a/content/en/methods/resource/Name.md b/content/en/methods/resource/Name.md
index 01b75e5b2..694b67baa 100644
--- a/content/en/methods/resource/Name.md
+++ b/content/en/methods/resource/Name.md
@@ -1,6 +1,6 @@
---
title: Name
-description: Returns the name of the given resource as optionally defined in front matter, falling back to a relative path or hashed file name depending on resource type.
+description: Returns the name of the given resource as optionally defined in front matter, falling back to its file path.
categories: []
keywords: []
action:
@@ -20,51 +20,63 @@ With a [global resource], the `Name` method returns the path to the resource, re
```text
assets/
└── images/
- └── a.jpg
+ └── Sunrise in Bryce Canyon.jpg
```
```go-html-template
-{{ with resources.Get "images/a.jpg" }}
- {{ .Name }} → images/a.jpg
+{{ with resources.Get "images/Sunrise in Bryce Canyon.jpg" }}
+ {{ .Name }} → /images/Sunrise in Bryce Canyon.jpg
{{ end }}
```
## Page resource
-With a [page resource], the `Name` method returns the path to the resource, relative to the page bundle.
+With a [page resource], if you create an element in the `resources` array in front matter, the `Name` method returns the value of the `name` parameter.
```text
content/
-├── posts/
-│ ├── post-1/
-│ │ ├── images/
-│ │ │ └── a.jpg
-│ │ └── index.md
-│ └── _index.md
+├── example/
+│ ├── images/
+│ │ └── a.jpg
+│ └── index.md
└── _index.md
```
+{{< code-toggle file=content/example/index.md fm=true >}}
+title = 'Example'
+[[resources]]
+src = 'images/a.jpg'
+name = 'Sunrise in Bryce Canyon'
+{{< /code-toggle >}}
+
```go-html-template
{{ with .Resources.Get "images/a.jpg" }}
- {{ .Name }} → images/a.jpg
+ {{ .Name }} → Sunrise in Bryce Canyon
{{ end }}
```
-If you create an element in the `resources` array in front matter, the `Name` method returns the value of the `name` parameter:
+You can also capture the image by specifying its `name` instead of its path:
-{{< code-toggle file=content/posts/post-1.md fm=true >}}
-title = 'Post 1'
-[[resources]]
-src = 'images/a.jpg'
-name = 'cat'
-title = 'Felix the cat'
-[resources.params]
-temperament = 'malicious'
-{{< /code-toggle >}}
+```go-html-template
+{{ with .Resources.Get "Sunrise in Bryce Canyon" }}
+ {{ .Name }} → Sunrise in Bryce Canyon
+{{ end }}
+```
+
+If you do not create an element in the `resources` array in front matter, the `Name` method returns the file path, relative to the page bundle.
+
+```text
+content/
+├── example/
+│ ├── images/
+│ │ └── Sunrise in Bryce Canyon.jpg
+│ └── index.md
+└── _index.md
+```
```go-html-template
-{{ with .Resources.Get "cat" }}
- {{ .Name }} → cat
+{{ with .Resources.Get "images/Sunrise in Bryce Canyon.jpg" }}
+ {{ .Name }} → images/Sunrise in Bryce Canyon.jpg
{{ end }}
```
## Remote resource
@@ -73,10 +85,11 @@ With a [remote resource], the `Name` method returns a hashed file name.
```go-html-template
{{ with resources.GetRemote "https://example.org/images/a.jpg" }}
- {{ .Name }} → a_18432433023265451104.jpg
+ {{ .Name }} → /a_18432433023265451104.jpg
{{ end }}
```
[global resource]: /getting-started/glossary/#global-resource
+[logical path]: /getting-started/glossary/#logical-path
[page resource]: /getting-started/glossary/#page-resource
[remote resource]: /getting-started/glossary/#remote-resource
diff --git a/content/en/methods/resource/Params.md b/content/en/methods/resource/Params.md
index 275182c46..ff6707f0b 100644
--- a/content/en/methods/resource/Params.md
+++ b/content/en/methods/resource/Params.md
@@ -62,4 +62,4 @@ Hugo renders:
See the [page resources] section for more information.
-[page resources]: /content-management/page-resources
+[page resources]: /content-management/page-resources/
diff --git a/content/en/methods/resource/Permalink.md b/content/en/methods/resource/Permalink.md
index ab0ad41b0..e0fa9aa87 100644
--- a/content/en/methods/resource/Permalink.md
+++ b/content/en/methods/resource/Permalink.md
@@ -7,7 +7,6 @@ action:
related:
- methods/resource/RelPermalink
- methods/resource/Publish
- - methods/resource/Key
returnType: string
signatures: [RESOURCE.Permalink]
---
diff --git a/content/en/methods/resource/Process.md b/content/en/methods/resource/Process.md
index 3c88492df..550b06401 100644
--- a/content/en/methods/resource/Process.md
+++ b/content/en/methods/resource/Process.md
@@ -59,8 +59,8 @@ The `Process` method is also available as a filter, which is more effective if y
example=true
>}}
-[`Crop`]: /methods/resource/crop
-[`Fill`]: /methods/resource/fill
-[`Fit`]: /methods/resource/fit
-[`Resize`]: /methods/resource/resize
-[`images.Process`]: /functions/images/process
+[`Crop`]: /methods/resource/crop/
+[`Fill`]: /methods/resource/fill/
+[`Fit`]: /methods/resource/fit/
+[`Resize`]: /methods/resource/resize/
+[`images.Process`]: /functions/images/process/
diff --git a/content/en/methods/resource/Publish.md b/content/en/methods/resource/Publish.md
index b090bfe5a..05344c658 100644
--- a/content/en/methods/resource/Publish.md
+++ b/content/en/methods/resource/Publish.md
@@ -7,7 +7,6 @@ action:
related:
- methods/resource/Permalink
- methods/resource/RelPermalink
- - methods/resource/Key
returnType: nil
signatures: [RESOURCE.Publish]
---
diff --git a/content/en/methods/resource/RelPermalink.md b/content/en/methods/resource/RelPermalink.md
index 2b96c35d7..190cdf64a 100644
--- a/content/en/methods/resource/RelPermalink.md
+++ b/content/en/methods/resource/RelPermalink.md
@@ -7,7 +7,6 @@ action:
related:
- methods/resource/Permalink
- methods/resource/Publish
- - methods/resource/Key
returnType: string
signatures: [RESOURCE.RelPermalink]
---
diff --git a/content/en/methods/resource/Title.md b/content/en/methods/resource/Title.md
index e30f86d2e..c620c2448 100644
--- a/content/en/methods/resource/Title.md
+++ b/content/en/methods/resource/Title.md
@@ -20,73 +20,65 @@ With a [global resource], the `Title` method returns the path to the resource, r
```text
assets/
└── images/
- └── a.jpg
+ └── Sunrise in Bryce Canyon.jpg
```
```go-html-template
-{{ with resources.Get "images/a.jpg" }}
- {{ .Title }} → images/a.jpg
+{{ with resources.Get "images/Sunrise in Bryce Canyon.jpg" }}
+ {{ .Title }} → /images/Sunrise in Bryce Canyon.jpg
{{ end }}
```
## Page resource
-With a [page resource], the `Title` method returns the path to the resource, relative to the page bundle.
+With a [page resource], if you create an element in the `resources` array in front matter, the `Title` method returns the value of the `title` parameter.
```text
content/
-├── posts/
-│ ├── post-1/
-│ │ ├── images/
-│ │ │ └── a.jpg
-│ │ └── index.md
-│ └── _index.md
+├── example/
+│ ├── images/
+│ │ └── a.jpg
+│ └── index.md
└── _index.md
```
-```go-html-template
-{{ with .Resources.Get "images/a.jpg" }}
- {{ .Title }} → images/a.jpg
-{{ end }}
-```
-
-If you create an element in the `resources` array in front matter, the `Title` method returns the value of the `title` parameter:
-
-{{< code-toggle file=content/posts/post-1.md fm=true >}}
-title = 'Post 1'
+{{< code-toggle file=content/example/index.md fm=true >}}
+title = 'Example'
[[resources]]
src = 'images/a.jpg'
-name = 'cat'
-title = 'Felix the cat'
-[resources.params]
-temperament = 'malicious'
+title = 'A beautiful sunrise in Bryce Canyon'
{{< /code-toggle >}}
```go-html-template
-{{ with .Resources.Get "cat" }}
- {{ .Title }} → Felix the cat
+{{ with .Resources.Get "images/a.jpg" }}
+ {{ .Title }} → A beautiful sunrise in Bryce Canyon
{{ end }}
```
-If the page resource is a content file, the `Title` methods return the `title` field as defined in front matter.
+If you do not create an element in the `resources` array in front matter, the `Title` method returns the file path, relative to the page bundle.
```text
content/
-├── lessons/
-│ ├── lesson-1/
-│ │ ├── _objectives.md <-- resource type = page
-│ │ └── index.md
-│ └── _index.md
+├── example/
+│ ├── images/
+│ │ └── Sunrise in Bryce Canyon.jpg
+│ └── index.md
└── _index.md
```
+```go-html-template
+{{ with .Resources.Get "Sunrise in Bryce Canyon.jpg" }}
+ {{ .Title }} → images/Sunrise in Bryce Canyon.jpg
+{{ end }}
+```
+
## Remote resource
With a [remote resource], the `Title` method returns a hashed file name.
```go-html-template
{{ with resources.GetRemote "https://example.org/images/a.jpg" }}
- {{ .Title }} → a_18432433023265451104.jpg
+ {{ .Title }} → /a_18432433023265451104.jpg
{{ end }}
```
diff --git a/content/en/methods/resource/_common/_index.md b/content/en/methods/resource/_common/_index.md
index 47d5812fb..4328d4d14 100644
--- a/content/en/methods/resource/_common/_index.md
+++ b/content/en/methods/resource/_common/_index.md
@@ -7,7 +7,7 @@ cascade:
---
<!--
-Files within this headless branch bundle are markdown snippets. Each file must contain front matter delimiters, though front matter fields are not required.
+Files within this headless branch bundle are Markdown snippets. Each file must contain front matter delimiters, though front matter fields are not required.
Include the rendered content using the "include" shortcode.
-->
diff --git a/content/en/methods/shortcode/Get.md b/content/en/methods/shortcode/Get.md
index cd674614f..8874c7649 100644
--- a/content/en/methods/shortcode/Get.md
+++ b/content/en/methods/shortcode/Get.md
@@ -1,6 +1,6 @@
---
title: Get
-description: Returns the value of the given parameter.
+description: Returns the value of the given argument.
categories: []
keywords: []
action:
@@ -8,44 +8,44 @@ action:
- methods/shortcode/IsNamedParams
- methods/shortcode/Params
returnType: any
- signatures: [SHORTCODE.Get PARAM]
+ signatures: [SHORTCODE.Get ARG]
toc: true
---
-Specify the parameter by position or by name. When calling a shortcode within markdown, use either positional or named parameters, but not both.
+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 parameters, some support named parameters, and others support both. Refer to the shortcode's documentation for usage details.
+Some shortcodes support positional arguments, some support named arguments, and others support both. Refer to the shortcode's documentation for usage details.
{{% /note %}}
-## Positional parameters
+## Positional arguments
-This shortcode call uses positional parameters:
+This shortcode call uses positional arguments:
{{< code file=content/about.md lang=md >}}
{{</* myshortcode "Hello" "world" */>}}
{{< /code >}}
-To retrieve parameters by position:
+To retrieve arguments by position:
{{< code file=layouts/shortcodes/myshortcode.html >}}
{{ printf "%s %s." (.Get 0) (.Get 1) }} → Hello world.
{{< /code >}}
-## Named parameters
+## Named arguments
-This shortcode call uses named parameters:
+This shortcode call uses named arguments:
{{< code file=content/about.md lang=md >}}
{{</* myshortcode greeting="Hello" firstName="world" */>}}
{{< /code >}}
-To retrieve parameters by name:
+To retrieve arguments by name:
{{< code file=layouts/shortcodes/myshortcode.html >}}
{{ printf "%s %s." (.Get "greeting") (.Get "firstName") }} → Hello world.
{{< /code >}}
{{% note %}}
-Parameter names are case-sensitive.
+Argument names are case-sensitive.
{{% /note %}}
diff --git a/content/en/methods/shortcode/Inner.md b/content/en/methods/shortcode/Inner.md
index de7c284cb..9271adb34 100644
--- a/content/en/methods/shortcode/Inner.md
+++ b/content/en/methods/shortcode/Inner.md
@@ -46,13 +46,13 @@ 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 [`trim`] function as shown above to remove both carriage returns and newlines.
+Content between opening and closing shortcode tags may include leading and/or trailing newlines, depending on placement within the Markdown. Use the [`trim`] function as shown above to remove both carriage returns and newlines.
-[`trim`]: /functions/strings/trim
+[`trim`]: /functions/strings/trim/
{{% /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.
+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 %}}
@@ -60,7 +60,7 @@ In the example above, the value returned by `Inner` is markdown, but it was rend
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
+[`RenderString`]: /methods/page/renderstring/
{{< code file=layouts/shortcodes/card.html >}}
<div class="card">
@@ -86,8 +86,8 @@ Hugo renders this to:
You can use the [`markdownify`] function instead of the `RenderString` method, but the latter is more flexible. See&nbsp;[details].
-[details]: /methods/page/renderstring
-[`markdownify`]: /functions/transform/markdownify
+[details]: /methods/page/renderstring/
+[`markdownify`]: /functions/transform/markdownify/
## Use alternate notation
@@ -99,9 +99,9 @@ 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.
+When you use the `{{%/* */%}}` notation, Hugo renders the entire shortcode as Markdown, requiring the following changes.
-First, configure the renderer to allow raw HTML within markdown:
+First, configure the renderer to allow raw HTML within Markdown:
{{< code-toggle file=hugo >}}
[markup.goldmark.renderer]
@@ -110,7 +110,7 @@ unsafe = true
This configuration is not unsafe if _you_ control the content. Read more about Hugo's [security model].
-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.
+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 >}}
<div class="card">
@@ -150,4 +150,4 @@ When using the `{{%/* */%}}` notation, do not pass the value returned by `Inner`
[commonmark]: https://commonmark.org/
[indentation]: https://spec.commonmark.org/0.30/#indented-code-blocks
[raw html blocks]: https://spec.commonmark.org/0.30/#html-blocks
-[security model]: /about/security-model/
+[security model]: /about/security/
diff --git a/content/en/methods/shortcode/InnerDeindent.md b/content/en/methods/shortcode/InnerDeindent.md
index 136412bc7..b5f5cf206 100644
--- a/content/en/methods/shortcode/InnerDeindent.md
+++ b/content/en/methods/shortcode/InnerDeindent.md
@@ -14,7 +14,7 @@ Similar to the [`Inner`] method, `InnerDeindent` returns the content between ope
This allows us to effectively bypass the rules governing [indentation] as provided in the [CommonMark] specification.
-Consider this markdown, an unordered list with a small gallery of thumbnail images within each list item:
+Consider this Markdown, an unordered list with a small gallery of thumbnail images within each list item:
{{< code file=content/about.md lang=md >}}
- Gallery one
@@ -42,7 +42,7 @@ With this shortcode, calling `Inner` instead of `InnerDeindent`:
</div>
{{< /code >}}
-Hugo renders the markdown to:
+Hugo renders the Markdown to:
```html
<ul>
@@ -73,7 +73,7 @@ Although technically correct per the CommonMark specification, this is not what
</div>
{{< /code >}}
-Hugo renders the markdown to:
+Hugo renders the Markdown to:
```html
<ul>
@@ -96,4 +96,4 @@ Hugo renders the markdown to:
[commonmark]: https://commonmark.org/
[indentation]: https://spec.commonmark.org/0.30/#indented-code-blocks
-[`Inner`]: /methods/shortcode/inner
+[`Inner`]: /methods/shortcode/inner/
diff --git a/content/en/methods/shortcode/IsNamedParams.md b/content/en/methods/shortcode/IsNamedParams.md
index 83eeb2f74..a1d93ddac 100644
--- a/content/en/methods/shortcode/IsNamedParams.md
+++ b/content/en/methods/shortcode/IsNamedParams.md
@@ -1,6 +1,6 @@
---
title: IsNamedParams
-description: Reports whether the shortcode call uses named parameters.
+description: Reports whether the shortcode call uses named arguments.
categories: []
keywords: []
action:
@@ -10,7 +10,7 @@ action:
signatures: [SHORTCODE.IsNamedParams]
---
-To support both positional and named parameters when calling a shortcode, use the `IsNamedParams` method to determine how the shortcode was called.
+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:
diff --git a/content/en/methods/shortcode/Name.md b/content/en/methods/shortcode/Name.md
index 18bddfe1f..fcf92718f 100644
--- a/content/en/methods/shortcode/Name.md
+++ b/content/en/methods/shortcode/Name.md
@@ -11,19 +11,19 @@ action:
signatures: [SHORTCODE.Name]
---
-The `Name` method is useful for error reporting. For example, if your shortcode requires a "greeting" parameter:
+The `Name` method is useful for error reporting. For example, if your shortcode requires a "greeting" argument:
{{< code file=layouts/shortcodes/myshortcode.html >}}
{{ $greeting := "" }}
{{ with .Get "greeting" }}
{{ $greeting = . }}
{{ else }}
- {{ errorf "The %q shortcode requires a 'greeting' parameter. See %s" .Name .Position }}
+ {{ errorf "The %q shortcode requires a 'greeting' argument. See %s" .Name .Position }}
{{ end }}
{{< /code >}}
-In the absence of a "greeting" parameter, Hugo will throw an error message and fail the build:
+In the absence of a "greeting" argument, Hugo will throw an error message and fail the build:
```text
-ERROR The "myshortcode" shortcode requires a 'greeting' parameter. See "/home/user/project/content/about.md:11:1"
+ERROR The "myshortcode" shortcode requires a 'greeting' argument. See "/home/user/project/content/about.md:11:1"
```
diff --git a/content/en/methods/shortcode/Ordinal.md b/content/en/methods/shortcode/Ordinal.md
index 954940258..6f3580d0f 100644
--- a/content/en/methods/shortcode/Ordinal.md
+++ b/content/en/methods/shortcode/Ordinal.md
@@ -32,7 +32,7 @@ This shortcode performs error checking, then renders an HTML `img` element with
{{ errorf "The %q shortcode was unable to find %s. See %s" $.Name $src $.Position }}
{{ end }}
{{ else }}
- {{ errorf "The %q shortcode requires a 'src' parameter. See %s" .Name .Position }}
+ {{ errorf "The %q shortcode requires a 'src' argument. See %s" .Name .Position }}
{{ end }}
{{< /code >}}
@@ -46,5 +46,5 @@ 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.
-[`with`]: /functions/go-template/with
+[`with`]: /functions/go-template/with/
{{% /note %}}
diff --git a/content/en/methods/shortcode/Params.md b/content/en/methods/shortcode/Params.md
index 63df768a6..c0772e36a 100644
--- a/content/en/methods/shortcode/Params.md
+++ b/content/en/methods/shortcode/Params.md
@@ -1,6 +1,6 @@
---
title: Params
-description: Returns a collection of the shortcode parameters.
+description: Returns a collection of the shortcode arguments.
categories: []
keywords: []
action:
@@ -10,7 +10,7 @@ action:
signatures: [SHORTCODE.Params]
---
-When you call a shortcode using positional parameters, the `Params` method returns a slice.
+When you call a shortcode using positional arguments, the `Params` method returns a slice.
{{< code file=content/about.md lang=md >}}
{{</* myshortcode "Hello" "world" */>}}
@@ -21,7 +21,7 @@ When you call a shortcode using positional parameters, the `Params` method retur
{{ index .Params 1 }} → world
{{< /code >}}
-When you call a shortcode using named parameters, the `Params` method returns a map.
+When you call a shortcode using named arguments, the `Params` method returns a map.
{{< code file=content/about.md lang=md >}}
{{</* myshortcode greeting="Hello" name="world" */>}}
diff --git a/content/en/methods/shortcode/Parent.md b/content/en/methods/shortcode/Parent.md
index 50ae521da..c500af375 100644
--- a/content/en/methods/shortcode/Parent.md
+++ b/content/en/methods/shortcode/Parent.md
@@ -9,7 +9,7 @@ action:
signatures: [SHORTCODE.Parent]
---
-This is useful for inheritance of common shortcode parameters from the root.
+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.
@@ -45,6 +45,6 @@ Welcome. Today is {{</* now */>}}.
The "now" shortcode formats the current time using:
-1. The `dateFormat` parameter passed to the "now" shortcode, if present
-2. The `dateFormat` parameter passed to the "greeting" shortcode, if present
+1. The `dateFormat` argument passed to the "now" shortcode, if present
+2. The `dateFormat` argument passed to the "greeting" shortcode, if present
3. The default layout string defined at the top of the shortcode
diff --git a/content/en/methods/shortcode/Position.md b/content/en/methods/shortcode/Position.md
index 565a158bf..6f047c01b 100644
--- a/content/en/methods/shortcode/Position.md
+++ b/content/en/methods/shortcode/Position.md
@@ -11,21 +11,21 @@ action:
signatures: [SHORTCODE.Position]
---
-The `Position` method is useful for error reporting. For example, if your shortcode requires a "greeting" parameter:
+The `Position` method is useful for error reporting. For example, if your shortcode requires a "greeting" argument:
{{< code file=layouts/shortcodes/myshortcode.html >}}
{{ $greeting := "" }}
{{ with .Get "greeting" }}
{{ $greeting = . }}
{{ else }}
- {{ errorf "The %q shortcode requires a 'greeting' parameter. See %s" .Name .Position }}
+ {{ errorf "The %q shortcode requires a 'greeting' argument. See %s" .Name .Position }}
{{ end }}
{{< /code >}}
-In the absence of a "greeting" parameter, Hugo will throw an error message and fail the build:
+In the absence of a "greeting" argument, Hugo will throw an error message and fail the build:
```text
-ERROR The "myshortcode" shortcode requires a 'greeting' parameter. See "/home/user/project/content/about.md:11:1"
+ERROR The "myshortcode" shortcode requires a 'greeting' argument. See "/home/user/project/content/about.md:11:1"
```
{{% note %}}
diff --git a/content/en/methods/shortcode/Scratch.md b/content/en/methods/shortcode/Scratch.md
index 3ab195a3f..fcfc99d53 100644
--- a/content/en/methods/shortcode/Scratch.md
+++ b/content/en/methods/shortcode/Scratch.md
@@ -1,6 +1,6 @@
---
title: Scratch
-description: Creates a "scratch pad" scoped to the shortcode to store and manipulate data.
+description: Returns a "scratch pad" scoped to the shortcode to store and manipulate data.
categories: []
keywords: []
action:
@@ -16,7 +16,7 @@ The `Scratch` method within a shortcode creates a [scratch pad] to store and man
With the introduction of the [`newScratch`] function, and the ability to [assign values to template variables] after initialization, the `Scratch` method within a shortcode is obsolete.
[assign values to template variables]: https://go.dev/doc/go1.11#text/template
-[`newScratch`]: functions/collections/newscratch
+[`newScratch`]: /functions/collections/newscratch/
{{% /note %}}
[scratch pad]: /getting-started/glossary/#scratch-pad
diff --git a/content/en/methods/shortcode/Site.md b/content/en/methods/shortcode/Site.md
index fa2d274de..af2a755ee 100644
--- a/content/en/methods/shortcode/Site.md
+++ b/content/en/methods/shortcode/Site.md
@@ -12,7 +12,7 @@ action:
See [Site methods].
-[Site methods]: /methods/site
+[Site methods]: /methods/site/
```go-html-template
{{ .Site.Title }}
diff --git a/content/en/methods/site/AllPages.md b/content/en/methods/site/AllPages.md
index 8df6348f9..e02c2cbbc 100644
--- a/content/en/methods/site/AllPages.md
+++ b/content/en/methods/site/AllPages.md
@@ -16,7 +16,7 @@ This method returns all page [kinds] in all languages. That includes the home pa
In most cases you should use the [`RegularPages`] method instead.
-[`RegularPages`]: methods/site/regularpages
+[`RegularPages`]: /methods/site/regularpages/
[kinds]: /getting-started/glossary/#page-kind
```go-html-template
diff --git a/content/en/methods/site/BaseURL.md b/content/en/methods/site/BaseURL.md
index f9c43bca3..ea965a568 100644
--- a/content/en/methods/site/BaseURL.md
+++ b/content/en/methods/site/BaseURL.md
@@ -30,8 +30,8 @@ There is almost never a good reason to use this method in your templates. Its us
Use the [`absURL`], [`absLangURL`], [`relURL`], or [`relLangURL`] functions instead.
-[`absURL`]: /functions/urls/absURL
-[`absLangURL`]: /functions/urls/absLangURL
-[`relURL`]: /functions/urls/relURL
-[`relLangURL`]: /functions/urls/relLangURL
+[`absURL`]: /functions/urls/absURL/
+[`absLangURL`]: /functions/urls/absLangURL/
+[`relURL`]: /functions/urls/relURL/
+[`relLangURL`]: /functions/urls/relLangURL/
{{% /note %}}
diff --git a/content/en/methods/site/Data.md b/content/en/methods/site/Data.md
index b78caddec..65cdadd01 100644
--- a/content/en/methods/site/Data.md
+++ b/content/en/methods/site/Data.md
@@ -20,7 +20,7 @@ Use the `Data` method on a `Site` object to access data within the data director
{{% 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
+[`transform.Unmarshal`]: /functions/transform/unmarshal/
{{% /note %}}
Consider this data directory:
@@ -101,8 +101,14 @@ To find a fiction book by ISBN:
{{ end }}
```
-In the template examples above, each of the keys is a valid identifier. For example, none of the keys contains a hyphen. To access a key that is not a valid identifier, use the [`index`] function:
+In the template examples above, each of the keys is a valid [identifier]. For example, none of the keys contains a hyphen. To access a key that is not a valid identifier, use the [`index`] function. For example:
-[`index`]: /functions/collections/indexfunction
+[identifier]: /getting-started/glossary/#identifier
+
+```go-html-template
+{{ index .Site.Data.books "historical-fiction" }}
+```
+
+[`index`]: /functions/collections/indexfunction/
[chaining]: /getting-started/glossary/#chain
[identifiers]: /getting-started/glossary/#identifier
diff --git a/content/en/methods/site/DisqusShortname.md b/content/en/methods/site/DisqusShortname.md
index 2d4447485..0e900ac4e 100644
--- a/content/en/methods/site/DisqusShortname.md
+++ b/content/en/methods/site/DisqusShortname.md
@@ -13,5 +13,5 @@ expiryDate: 2024-10-30 # deprecated 2023-10-30
{{% deprecated-in 0.120.0 %}}
Use [`Site.Config.Services.Disqus.Shortname`] instead.
-[`Site.Config.Services.Disqus.Shortname`]: /methods/site/config
+[`Site.Config.Services.Disqus.Shortname`]: /methods/site/config/
{{% /deprecated-in %}}
diff --git a/content/en/methods/site/GetPage.md b/content/en/methods/site/GetPage.md
index b7d4b8f32..3505e582a 100644
--- a/content/en/methods/site/GetPage.md
+++ b/content/en/methods/site/GetPage.md
@@ -13,7 +13,7 @@ toc: true
The `GetPage` method is also available on `Page` objects, allowing you to specify a path relative to the current page. See&nbsp;[details].
-[details]: /methods/page/getpage
+[details]: /methods/page/getpage/
When using the `GetPage` method on a `Site` object, specify a path relative to the content directory.
diff --git a/content/en/methods/site/GoogleAnalytics.md b/content/en/methods/site/GoogleAnalytics.md
index 50f479b49..c58974452 100644
--- a/content/en/methods/site/GoogleAnalytics.md
+++ b/content/en/methods/site/GoogleAnalytics.md
@@ -13,5 +13,5 @@ expiryDate: 2024-10-30 # deprecated 2023-10-30
{{% deprecated-in 0.120.0 %}}
Use [`Site.Config.Services.GoogleAnalytics.ID`] instead.
-[`Site.Config.Services.GoogleAnalytics.ID`]: /methods/site/config
+[`Site.Config.Services.GoogleAnalytics.ID`]: /methods/site/config/
{{% /deprecated-in %}}
diff --git a/content/en/methods/site/IsDevelopment.md b/content/en/methods/site/IsDevelopment.md
index c009ba0de..6f443316b 100644
--- a/content/en/methods/site/IsDevelopment.md
+++ b/content/en/methods/site/IsDevelopment.md
@@ -13,7 +13,7 @@ expiryDate: 2024-10-30 # deprecated 2023-10-30
{{% deprecated-in 0.120.0 %}}
Use [`hugo.IsDevelopment`] instead.
-[`hugo.IsDevelopment`]: /functions/hugo/isdevelopment
+[`hugo.IsDevelopment`]: /functions/hugo/isdevelopment/
{{% /deprecated-in %}}
```go-html-template
diff --git a/content/en/methods/site/IsMultiLingual.md b/content/en/methods/site/IsMultiLingual.md
index 61cc5e462..a14283787 100644
--- a/content/en/methods/site/IsMultiLingual.md
+++ b/content/en/methods/site/IsMultiLingual.md
@@ -1,6 +1,6 @@
---
title: IsMultiLingual
-description: Reports whether the site is multilingual.
+description: Reports whether there are two or more configured languages.
categories: []
keywords: []
action:
@@ -9,6 +9,12 @@ action:
signatures: [SITE.IsMultiLingual]
---
+{{% deprecated-in 0.124.0 %}}
+Use [`hugo.IsMultilingual`] instead.
+
+[`hugo.IsMultilingual`]: /functions/hugo/ismultilingual/
+{{% /deprecated-in %}}
+
Site configuration:
{{< code-toggle file=hugo >}}
diff --git a/content/en/methods/site/IsServer.md b/content/en/methods/site/IsServer.md
index 3d5ce41b5..a688c553a 100644
--- a/content/en/methods/site/IsServer.md
+++ b/content/en/methods/site/IsServer.md
@@ -13,7 +13,7 @@ expiryDate: 2024-10-30 # deprecated 2023-10-30
{{% deprecated-in 0.120.0 %}}
Use [`hugo.IsServer`] instead.
-[`hugo.IsServer`]: /functions/hugo/isserver
+[`hugo.IsServer`]: /functions/hugo/isserver/
{{% /deprecated-in %}}
```go-html-template
diff --git a/content/en/methods/site/Language.md b/content/en/methods/site/Language.md
index 1babc099b..7179038e4 100644
--- a/content/en/methods/site/Language.md
+++ b/content/en/methods/site/Language.md
@@ -35,7 +35,7 @@ Lang
```
LanguageCode
-: (`string`) The language code from the site configuration.
+: (`string`) The language code from the site configuration. Falls back to `Lang` if not defined.
```go-html-template
{{ .Site.Language.LanguageCode }} → de-DE
@@ -68,16 +68,10 @@ Some of the methods above are commonly used in a base template as attributes for
```go-html-template
<html
- lang="{{ or site.Language.LanguageCode site.Language.Lang }}"
- dir="{{ or site.Language.LanguageDirection `ltr` }}
+ lang="{{ .Site.Language.LanguageCode }}"
+ dir="{{ or .Site.Language.LanguageDirection `ltr` }}
>
```
-The example above uses the global [`site`] function instead of accessing the `Site` object via the `.Site` notation.
-
-Also note that each attribute has a fallback value assigned via the [`or`] operator.
-
-[details]: /methods/page/language
+[details]: /methods/page/language/
[RFC 5646]: https://datatracker.ietf.org/doc/html/rfc5646
-[`or`]: /functions/go-template/or
-[`site`]: /functions/global/site
diff --git a/content/en/methods/site/Languages.md b/content/en/methods/site/Languages.md
index 26bdefc21..cfa1ade6b 100644
--- a/content/en/methods/site/Languages.md
+++ b/content/en/methods/site/Languages.md
@@ -12,10 +12,10 @@ action:
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.
-To view the data structure:
+To inspect the data structure:
```go-html-template
-<pre>{{ jsonify (dict "indent" " ") .Site.Languages }}</pre>
+<pre>{{ debug.Dump .Site.Languages }}</pre>
```
With this site configuration:
diff --git a/content/en/methods/site/LastChange.md b/content/en/methods/site/LastChange.md
index aceee691d..2a8c3e491 100644
--- a/content/en/methods/site/LastChange.md
+++ b/content/en/methods/site/LastChange.md
@@ -9,13 +9,19 @@ action:
signatures: [SITE.LastChange]
---
+{{% deprecated-in 0.123.0 %}}
+Use [`.Site.Lastmod`] instead.
+
+[`.Site.Lastmod`]: /methods/site/lastmod/
+{{% /deprecated-in %}}
+
The `LastChange` method on a `Site` object returns a [`time.Time`] value. Use this with time [functions] and [methods]. For example:
```go-html-template
-{{ .Site.LastChange | time.Format ":date_long" }} → October 16, 2023
+{{ .Site.LastChange | time.Format ":date_long" }} → January 31, 2024
```
[`time.Time`]: https://pkg.go.dev/time#Time
-[functions]: /functions/time
-[methods]: /methods/time
+[functions]: /functions/time/
+[methods]: /methods/time/
diff --git a/content/en/methods/site/Lastmod.md b/content/en/methods/site/Lastmod.md
new file mode 100644
index 000000000..081481956
--- /dev/null
+++ b/content/en/methods/site/Lastmod.md
@@ -0,0 +1,23 @@
+---
+title: Lastmod
+description: Returns the last modification date of site content.
+categories: []
+keywords: []
+action:
+ related: []
+ returnType: time.Time
+ signatures: [SITE.Lastmod]
+---
+
+{{< new-in 0.123.0 >}}
+
+The `Lastmod` method on a `Site` object returns a [`time.Time`] value. Use this with time [functions] and [methods]. For example:
+
+```go-html-template
+{{ .Site.Lastmod | time.Format ":date_long" }} → January 31, 2024
+
+```
+
+[`time.Time`]: https://pkg.go.dev/time#Time
+[functions]: /functions/time/
+[methods]: /methods/time/
diff --git a/content/en/methods/site/Menus.md b/content/en/methods/site/Menus.md
index c204fe97b..98ce4e879 100644
--- a/content/en/methods/site/Menus.md
+++ b/content/en/methods/site/Menus.md
@@ -88,7 +88,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-templates
+[menu templates]: /templates/menu-templates/
-[`partial`]: /functions/partials/include
-[`partialCached`]: /functions/partials/includecached
+[`partial`]: /functions/partials/include/
+[`partialCached`]: /functions/partials/includecached/
diff --git a/content/en/methods/site/Pages.md b/content/en/methods/site/Pages.md
index 583e98c11..ac6e13c4a 100644
--- a/content/en/methods/site/Pages.md
+++ b/content/en/methods/site/Pages.md
@@ -16,7 +16,7 @@ This method returns all page [kinds] in the current language. That includes the
In most cases you should use the [`RegularPages`] method instead.
-[`RegularPages`]: methods/site/regularpages
+[`RegularPages`]: /methods/site/regularpages/
[kinds]: /getting-started/glossary/#page-kind
```go-html-template
diff --git a/content/en/methods/site/Params.md b/content/en/methods/site/Params.md
index 518d93bf3..95e016b81 100644
--- a/content/en/methods/site/Params.md
+++ b/content/en/methods/site/Params.md
@@ -33,7 +33,7 @@ Access the custom parameters by [chaining] the [identifiers]:
{{ .Site.Params.author.name }} → John Smith
{{ $layout := .Site.Params.layouts.rfc_1123 }}
-{{ .Site.LastChange.Format $layout }} → Tue, 17 Oct 2023 13:21:02 PDT
+{{ .Site.Lastmod.Format $layout }} → Tue, 17 Oct 2023 13:21:02 PDT
```
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:
@@ -42,6 +42,6 @@ In the template example above, each of the keys is a valid identifier. For examp
{{ index .Site.Params "copyright-year" }} → 2023
```
-[`index`]: /functions/collections/indexfunction
+[`index`]: /functions/collections/indexfunction/
[chaining]: /getting-started/glossary/#chain
[identifiers]: /getting-started/glossary/#identifier
diff --git a/content/en/methods/site/Sites.md b/content/en/methods/site/Sites.md
index f7bafd3ed..ac287d3b4 100644
--- a/content/en/methods/site/Sites.md
+++ b/content/en/methods/site/Sites.md
@@ -1,6 +1,6 @@
---
title: Sites
-description: Returns a collection of all Site objects, one for each language, ordered by language weight.
+description: Returns a collection of all Site objects, one for each language, ordered by default content language then by language weight.
categories: []
keywords: []
action:
@@ -49,10 +49,10 @@ Produces a list of links to each home page:
</ul>
```
-To render a link to home page of the primary (first) language:
+To render a link to the home page of the site corresponding to the default content language:
```go-html-template
-{{ with .Site.Sites.First }}
+{{ with .Site.Sites.Default }}
<a href="{{ .Home.Permalink }}">{{ .Title }}</a>
{{ end }}
```
diff --git a/content/en/methods/site/Taxonomies.md b/content/en/methods/site/Taxonomies.md
index 72bfc75d5..219fe188b 100644
--- a/content/en/methods/site/Taxonomies.md
+++ b/content/en/methods/site/Taxonomies.md
@@ -95,5 +95,5 @@ Hugo's taxonomy system is powerful, allowing you to classify content and create
Please see the [taxonomies] section for a complete explanation and examples.
-[taxonomies]: content-management/taxonomies/
+[taxonomies]: /content-management/taxonomies/
{{% /note %}}
diff --git a/content/en/methods/taxonomy/Alphabetical.md b/content/en/methods/taxonomy/Alphabetical.md
index 7845dbf3d..ea90cfdf9 100644
--- a/content/en/methods/taxonomy/Alphabetical.md
+++ b/content/en/methods/taxonomy/Alphabetical.md
@@ -34,7 +34,7 @@ To reverse the sort order:
To inspect the data structure:
```go-html-template
-<pre>{{ jsonify (dict "indent" " ") $taxonomyObject.Alphabetical }}</pre>
+<pre>{{ debug.Dump $taxonomyObject.Alphabetical }}</pre>
```
{{% include "methods/taxonomy/_common/ordered-taxonomy-element-methods.md" %}}
diff --git a/content/en/methods/taxonomy/ByCount.md b/content/en/methods/taxonomy/ByCount.md
index 40f58420a..68143ccff 100644
--- a/content/en/methods/taxonomy/ByCount.md
+++ b/content/en/methods/taxonomy/ByCount.md
@@ -34,7 +34,7 @@ To reverse the sort order:
To inspect the data structure:
```go-html-template
-<pre>{{ jsonify (dict "indent" " ") $taxonomyObject.ByCount }}</pre>
+<pre>{{ debug.Dump $taxonomyObject.ByCount }}</pre>
```
{{% include "methods/taxonomy/_common/ordered-taxonomy-element-methods.md" %}}
diff --git a/content/en/methods/taxonomy/Get.md b/content/en/methods/taxonomy/Get.md
index 3bac86f08..79d25b704 100644
--- a/content/en/methods/taxonomy/Get.md
+++ b/content/en/methods/taxonomy/Get.md
@@ -43,7 +43,7 @@ You could also use the [`index`] function, but the syntax is more verbose:
To inspect the data structure:
```go-html-template
-<pre>{{ jsonify (dict "indent" " ") $weightedPages }}</pre>
+<pre>{{ debug.Dump $weightedPages }}</pre>
```
## Example
@@ -66,7 +66,7 @@ Hugo renders:
```
[chaining]: /getting-started/glossary/#chain
-[`index`]: /functions/collections/indexfunction
+[`index`]: /functions/collections/indexfunction/
[identifier]: /getting-started/glossary/#identifier
[term]: /getting-started/glossary/#term
[weighted pages]: /getting-started/glossary/#weighted-page
diff --git a/content/en/methods/taxonomy/Page.md b/content/en/methods/taxonomy/Page.md
new file mode 100644
index 000000000..e148ac5c7
--- /dev/null
+++ b/content/en/methods/taxonomy/Page.md
@@ -0,0 +1,26 @@
+---
+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]
+---
+
+{{< new-in 0.125.0 >}}
+
+This `TAXONOMY` method returns nil if the taxonomy has no terms, so you must code defensively:
+
+```go-html-template
+{{ with .Site.Taxonomies.tags.Page }}
+ <a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a>
+{{ end }}
+```
+
+This is rendered to:
+
+```html
+<a href="/tags/">Tags</a>
+```
diff --git a/content/en/methods/taxonomy/_common/_index.md b/content/en/methods/taxonomy/_common/_index.md
index 47d5812fb..4328d4d14 100644
--- a/content/en/methods/taxonomy/_common/_index.md
+++ b/content/en/methods/taxonomy/_common/_index.md
@@ -7,7 +7,7 @@ cascade:
---
<!--
-Files within this headless branch bundle are markdown snippets. Each file must contain front matter delimiters, though front matter fields are not required.
+Files within this headless branch bundle are Markdown snippets. Each file must contain front matter delimiters, though front matter fields are not required.
Include the rendered content using the "include" shortcode.
-->
diff --git a/content/en/methods/taxonomy/_common/get-a-taxonomy-object.md b/content/en/methods/taxonomy/_common/get-a-taxonomy-object.md
index 4c4fc42c9..6bf86cd85 100644
--- a/content/en/methods/taxonomy/_common/get-a-taxonomy-object.md
+++ b/content/en/methods/taxonomy/_common/get-a-taxonomy-object.md
@@ -41,7 +41,7 @@ To capture the "genres" taxonomy object when rendering its page with a taxonomy
To inspect the data structure:
```go-html-template
-<pre>{{ jsonify (dict "indent" " ") $taxonomyObject }}</pre>
+<pre>{{ debug.Dump $taxonomyObject }}</pre>
```
Although the [`Alphabetical`] and [`ByCount`] methods provide a better data structure for ranging through the taxonomy, you can render the weighted pages by term directly from the `Taxonomy` object:
@@ -60,9 +60,9 @@ Although the [`Alphabetical`] and [`ByCount`] methods provide a better data stru
In the example above, the first anchor element is a link to the term page.
-[`Alphabetical`]: /methods/taxonomy/alphabetical
-[`ByCount`]: /methods/taxonomy/bycount
+[`Alphabetical`]: /methods/taxonomy/alphabetical/
+[`ByCount`]: /methods/taxonomy/bycount/
-[`data`]: /methods/page/data
+[`data`]: /methods/page/data/
[`terms`]: /methods/page/data/#in-a-taxonomy-template
-[`taxonomies`]: /methods/site/taxonomies
+[`taxonomies`]: /methods/site/taxonomies/
diff --git a/content/en/methods/taxonomy/_common/ordered-taxonomy-element-methods.md b/content/en/methods/taxonomy/_common/ordered-taxonomy-element-methods.md
index 9c94729ba..7201ad318 100644
--- a/content/en/methods/taxonomy/_common/ordered-taxonomy-element-methods.md
+++ b/content/en/methods/taxonomy/_common/ordered-taxonomy-element-methods.md
@@ -21,5 +21,5 @@ Term
WeightedPages
: (`page.WeightedPages`) Returns a slice of weighted pages to which the term is assigned, sorted by [taxonomic weight]. The `Pages` method above is more flexible, allowing you to sort and group.
-[methods]: /methods/pages
+[methods]: /methods/pages/
[taxonomic weight]: /getting-started/glossary/#taxonomic-weight
diff --git a/content/en/methods/time/Format.md b/content/en/methods/time/Format.md
index fc3e2635c..d526b7b64 100644
--- a/content/en/methods/time/Format.md
+++ b/content/en/methods/time/Format.md
@@ -27,7 +27,7 @@ aliases: [/methods/time/format]
To [localize] the return value, use the [`time.Format`] function instead.
[localize]: /getting-started/glossary/#localization
-[`time.Format`]: /functions/time/format
+[`time.Format`]: /functions/time/format/
{{% /note %}}
Use the `Format` method with any `time.Time` value, including the four predefined front matter dates:
@@ -44,7 +44,7 @@ Use the `Format` method with any `time.Time` value, including the four predefine
{{% 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
+[`time.Format`]: /functions/time/format/
{{% /note %}}
## Layout string
diff --git a/content/en/methods/time/Round.md b/content/en/methods/time/Round.md
new file mode 100644
index 000000000..988c56ba9
--- /dev/null
+++ b/content/en/methods/time/Round.md
@@ -0,0 +1,26 @@
+---
+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]
+---
+
+The rounding behavior for halfway values is to round up.
+
+The `Round` method operates on TIME as an absolute duration since the [zero time]; it does not operate on the presentation form of the time. If DURATION is a multiple of one hour, `Round` may return a time with a non-zero minute, depending on the time zone.
+
+```go-html-template
+{{ $t := time.AsTime "2023-01-27T23:44:58-08:00" }}
+{{ $d := time.ParseDuration "1h"}}
+
+{{ ($t.Round $d).Format "2006-01-02T15:04:05-00:00" }} → 2023-01-28T00:00:00-00:00
+```
+
+[zero time]: /getting-started/glossary/#zero-time
diff --git a/content/en/methods/time/Truncate.md b/content/en/methods/time/Truncate.md
new file mode 100644
index 000000000..da6e0b26b
--- /dev/null
+++ b/content/en/methods/time/Truncate.md
@@ -0,0 +1,24 @@
+---
+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]
+---
+
+The `Truncate` method operates on TIME as an absolute duration since the [zero time]; 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.
+
+```go-html-template
+{{ $t := time.AsTime "2023-01-27T23:44:58-08:00" }}
+{{ $d := time.ParseDuration "1h"}}
+
+{{ ($t.Truncate $d).Format "2006-01-02T15:04:05-00:00" }} → 2023-01-27T23:00:00-00:00
+```
+
+[zero time]: /getting-started/glossary/#zero-time
diff --git a/content/en/methods/time/YearDay.md b/content/en/methods/time/YearDay.md
index 40d7d6aab..f380cdffe 100644
--- a/content/en/methods/time/YearDay.md
+++ b/content/en/methods/time/YearDay.md
@@ -1,6 +1,6 @@
---
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.
+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:
diff --git a/content/en/news/_index.md b/content/en/news/_index.md
index e37c33a3c..a1959bd1d 100644
--- a/content/en/news/_index.md
+++ b/content/en/news/_index.md
@@ -1,4 +1,7 @@
---
-title: Hugo News
+title: News
+outputs:
+ - html
+ - rss
aliases: [/release-notes/]
---
diff --git a/content/en/quick-reference/_index.md b/content/en/quick-reference/_index.md
index 492cfa09b..b5f434e2d 100644
--- a/content/en/quick-reference/_index.md
+++ b/content/en/quick-reference/_index.md
@@ -1,12 +1,12 @@
---
title: Quick reference guides
-linkTitle: Overview
+linkTitle: In this section
description: Quick reference guides to Hugo's features, functions, and methods.
categories: []
keywords: []
menu:
docs:
- identifier: quick-reference-overview
+ identifier: quick-reference-in-this-section
parent: quick-reference
weight: 10
weight: 10
diff --git a/content/en/quick-reference/emojis.md b/content/en/quick-reference/emojis.md
index e6b1ed415..8ae01098b 100644
--- a/content/en/quick-reference/emojis.md
+++ b/content/en/quick-reference/emojis.md
@@ -1,6 +1,6 @@
---
title: Emojis
-description: Include emoji shortcodes in your markdown or templates.
+description: Include emoji shortcodes in your Markdown or templates.
categories: [quick reference]
keywords: [emoji]
menu:
@@ -11,13 +11,13 @@ weight: 20
toc: true
---
-Configure Hugo to enable emoji processing in markdown:
+Configure Hugo to enable emoji processing in Markdown:
{{< code-toggle file=hugo >}}
enableEmoji = true
{{< /code-toggle >}}
-With emoji processing enabled, this markdown:
+With emoji processing enabled, this Markdown:
```md
Hello! :wave:
@@ -37,8 +37,8 @@ To process an emoji shortcode from within a template, use the [`emojify`] functi
{{ "Hello! :wave:" | .RenderString }}
```
-[`emojify`]: /functions/transform/emojify
-[`RenderString`]: /methods/page/renderstring
+[`emojify`]: /functions/transform/emojify/
+[`RenderString`]: /methods/page/renderstring/
## Introduction
diff --git a/content/en/quick-reference/page-collections.md b/content/en/quick-reference/page-collections.md
index 795eb494d..eca65a93e 100644
--- a/content/en/quick-reference/page-collections.md
+++ b/content/en/quick-reference/page-collections.md
@@ -31,7 +31,7 @@ Use these `Site` methods when rendering lists on any page.
Use the [`where`] function to filter page collections.
-[`where`]: /functions/collections/where
+[`where`]: /functions/collections/where/
## Sort
diff --git a/content/en/variables/_common/_index.md b/content/en/render-hooks/_common/_index.md
index 47d5812fb..4328d4d14 100644
--- a/content/en/variables/_common/_index.md
+++ b/content/en/render-hooks/_common/_index.md
@@ -7,7 +7,7 @@ cascade:
---
<!--
-Files within this headless branch bundle are markdown snippets. Each file must contain front matter delimiters, though front matter fields are not required.
+Files within this headless branch bundle are Markdown snippets. Each file must contain front matter delimiters, though front matter fields are not required.
Include the rendered content using the "include" shortcode.
-->
diff --git a/content/en/render-hooks/_common/pageinner.md b/content/en/render-hooks/_common/pageinner.md
new file mode 100644
index 000000000..de1316cba
--- /dev/null
+++ b/content/en/render-hooks/_common/pageinner.md
@@ -0,0 +1,42 @@
+---
+# Do not remove front matter.
+---
+
+## PageInner details
+
+{{< new-in 0.125.0 >}}
+
+The primary use case for `PageInner` is to resolve links and [page resources] 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 >}}
+{{ with site.GetPage (.Get 0) }}
+ {{ .RenderShortcodes }}
+{{ end }}
+{{< /code >}}
+
+Then call the shortcode in your Markdown:
+
+{{< code file=content/posts/p1.md >}}
+{{%/* include "/posts/p2" */%}}
+{{< /code >}}
+
+Any render hook triggered while rendering `/posts/p2` will get:
+
+- `/posts/p1` when calling `Page`
+- `/posts/p2` when calling `PageInner`
+
+`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 %}}
+
+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 %}})
+
+[`RenderShortcodes`]: /methods/page/rendershortcodes/
+[page resources]: /getting-started/glossary/#page-resource
diff --git a/content/en/render-hooks/_index.md b/content/en/render-hooks/_index.md
new file mode 100644
index 000000000..8cf72c4e8
--- /dev/null
+++ b/content/en/render-hooks/_index.md
@@ -0,0 +1,17 @@
+---
+title: Render hooks
+linkTitle: In this section
+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/code-blocks.md b/content/en/render-hooks/code-blocks.md
new file mode 100755
index 000000000..0c11c7864
--- /dev/null
+++ b/content/en/render-hooks/code-blocks.md
@@ -0,0 +1,152 @@
+---
+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]
+keywords: []
+menu:
+ docs:
+ parent: render-hooks
+ weight: 30
+weight: 30
+toc: true
+---
+
+## Markdown
+
+This Markdown example contains a fenced code block:
+
+{{< code file=content/example.md lang=text >}}
+```bash {class="my-class" id="my-codeblock" lineNos=inline tabWidth=2}
+declare a=1
+echo "$a"
+exit
+```
+{{< /code >}}
+
+A fenced code block consists of:
+
+- A leading [code fence]
+- An optional [info string]
+- 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)
+- An optional space-delimited or comma-delimited list of attributes (everything within braces)
+
+The attributes in the info string can be generic attributes or highlighting options.
+
+In the example above, the _generic attributes_ are `class` and `id`. In the absence of special handling within a code block render hook, Hugo adds each generic attribute to the HTML element surrounding the rendered code block. Consistent with its content security model, Hugo removes HTML event attributes such as `onclick` and `onmouseover`. Generic attributes are typically global HTML attributes, but you may include custom attributes as well.
+
+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 %}}
+
+## Context
+
+Code block render hook templates receive the following [context]:
+
+[context]: /getting-started/glossary/#context
+
+###### Attributes
+
+(`map`) The generic attributes from the info string.
+
+###### Inner
+
+(`string`) The content between the leading and trailing code fences, excluding the info string.
+
+###### Options
+
+(`map`) The highlighting options from the info string.
+
+###### Ordinal
+
+(`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.
+
+## 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 >}}
+{{ $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.
+
+```text
+layouts/
+└── _default/
+ └── _markup/
+ ├── render-codeblock-mermaid.html
+ ├── render-codeblock-python.html
+ └── render-codeblock.html
+```
+
+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 >}}
+<pre class="mermaid">
+ {{- .Inner | safeHTML }}
+</pre>
+{{ .Page.Store.Set "hasMermaid" true }}
+{{< /code >}}
+
+Then include this snippet at the bottom of the your base template:
+
+{{< code file=layouts/_default/baseof.html copy=true >}}
+{{ if .Store.Get "hasMermaid" }}
+ <script type="module">
+ import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid/dist/mermaid.esm.min.mjs';
+ mermaid.initialize({ startOnLoad: true });
+ </script>
+{{ 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].
+
+[embedded code block render hook]: {{% eturl render-codeblock-goat %}}
+[GoAT diagrams]: /content-management/diagrams/#goat-diagrams-ascii
+
+{{% include "/render-hooks/_common/pageinner.md" %}}
diff --git a/content/en/render-hooks/headings.md b/content/en/render-hooks/headings.md
new file mode 100755
index 000000000..c48bb11e1
--- /dev/null
+++ b/content/en/render-hooks/headings.md
@@ -0,0 +1,79 @@
+---
+title: Heading render hooks
+linkTitle: Headings
+description: Create a heading render hook to override the rendering of Markdown headings to HTML.
+categories: [render hooks]
+keywords: []
+menu:
+ docs:
+ parent: render-hooks
+ weight: 40
+weight: 40
+toc: true
+---
+
+## Context
+
+Heading render hook templates receive the following [context]:
+
+[context]: /getting-started/glossary/#context
+
+###### Anchor
+
+(`string`) The `id` attribute of the heading element.
+
+###### Attributes
+
+(`map`) The Markdown attributes, available if you configure your site as follows:
+
+{{< 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
+
+(`string`) 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 >}}
+<h{{ .Level }} id="{{ .Anchor }}">
+ {{- .Text | safeHTML -}}
+</h{{ .Level }}>
+{{< /code >}}
+
+To add an anchor link to the right of each heading:
+
+{{< code file=layouts/_default/_markup/render-heading.html copy=true >}}
+<h{{ .Level }} id="{{ .Anchor }}">
+ {{ .Text | safeHTML }}
+ <a href="#{{ .Anchor }}">#</a>
+</h{{ .Level }}>
+{{< /code >}}
+
+{{% include "/render-hooks/_common/pageinner.md" %}}
diff --git a/content/en/render-hooks/images.md b/content/en/render-hooks/images.md
new file mode 100755
index 000000000..e68cd1b95
--- /dev/null
+++ b/content/en/render-hooks/images.md
@@ -0,0 +1,163 @@
+---
+title: Image render hooks
+linkTitle: Images
+description: Create an image render to hook override the rendering of Markdown images to HTML.
+categories: [render hooks]
+keywords: []
+menu:
+ docs:
+ parent: render-hooks
+ weight: 50
+weight: 50
+toc: true
+---
+
+## Markdown
+
+A Markdown image has three components: the image description, the image destination, and optionally the image title.
+
+```text
+![white kitten](/images/kitten.jpg "A kitten!")
+ ------------ ------------------ ---------
+ description destination title
+```
+
+These components are passed into the render hook [context] as shown below.
+
+[context]: /getting-started/glossary/#context
+
+## Context
+
+Image render hook templates receive the following context:
+
+###### Attributes
+
+(`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 >}}
+
+###### Destination
+
+(`string`) The image destination.
+
+###### IsBlock
+
+(`bool`) Returns true if a standalone image is not wrapped within a paragraph element.
+
+###### Ordinal
+
+(`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
+
+(`string`) The image description.
+
+###### 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 %}}
+
+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 >}}
+<img src="{{ .Destination | safeURL }}"
+ {{- with .Text }} alt="{{ . }}"{{ end -}}
+ {{- with .Title }} title="{{ . }}"{{ end -}}
+>
+{{- /* chomp trailing newline */ -}}
+{{< /code >}}
+
+To render standalone images within `figure` elements:
+
+{{< code file=layouts/_default/_markup/render-image.html copy=true >}}
+{{- if .IsBlock -}}
+ <figure>
+ <img src="{{ .Destination | safeURL }}"
+ {{- with .Text }} alt="{{ . }}"{{ end -}}
+ >
+ <figcaption>{{ .Title }}</figcaption>
+ </figure>
+{{- else -}}
+ <img src="{{ .Destination | safeURL }}"
+ {{- with .Text }} alt="{{ . }}"{{ end -}}
+ {{- with .Title }} title="{{ . }}"{{ end -}}
+ >
+{{- end -}}
+{{< /code >}}
+
+Note that the above requires the following site configuration:
+
+{{< code-toggle file=hugo >}}
+[markup.goldmark.parser]
+wrapStandAloneImageWithinParagraph = false
+{{< /code-toggle >}}
+
+## Default
+
+{{< new-in 0.123.0 >}}
+
+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
+{{< /code-toggle >}}
+
+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 %}}
+
+The embedded image render hook resolves internal Markdown destinations by looking for a matching [page resource], falling back to a matching [global resource]. Remote destinations are passed through, and the render hook will not throw an error or warning if it is unable to resolve a destination.
+
+[page resource]: /getting-started/glossary/#page-resource
+[global resource]: /getting-started/glossary/#global-resource
+
+You must place global resources in the assets directory. If you have placed your resources in the static directory, and you are unable or unwilling to move them, you must mount the static directory to the assets directory by including both of these entries in your site configuration:
+
+{{< code-toggle file=hugo >}}
+[[module.mounts]]
+source = 'assets'
+target = 'assets'
+
+[[module.mounts]]
+source = 'static'
+target = 'assets'
+{{< /code-toggle >}}
+
+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" %}}
diff --git a/content/en/render-hooks/introduction.md b/content/en/render-hooks/introduction.md
new file mode 100755
index 000000000..ebf95c00f
--- /dev/null
+++ b/content/en/render-hooks/introduction.md
@@ -0,0 +1,85 @@
+---
+title: Introduction
+description: An introduction to Hugo's render hooks.
+categories: [render hooks]
+keywords: []
+menu:
+ docs:
+ identifier: render-hooks-introduction
+ parent: render-hooks
+ weight: 20
+weight: 20
+---
+
+When rendering Markdown to HTML, render hooks override the conversion. Each render hook is a template, with one template for each supported element type:
+
+- [Code blocks](/render-hooks/code-blocks)
+- [Headings](/render-hooks/headings)
+- [Images](/render-hooks/images)
+- [Links](/render-hooks/links)
+
+{{% 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 %}}
+
+For example, consider this Markdown:
+
+```text
+[Hugo](https://gohugo.io)
+
+![kitten](kitten.jpg)
+```
+
+Without link or image render hooks, this example above is rendered to:
+
+```html
+<p><a href="https://gohugo.io">Hugo</a></p>
+<p><img alt="kitten" src="kitten.jpg"></p>
+```
+
+By creating link and image render hooks, you can alter the conversion from Markdown to HTML. For example:
+
+```html
+<p><a href="https://gohugo.io" rel="external">Hugo</a></p>
+<p><img alt="kitten" src="kitten.jpg" width="600" height="400"></p>
+```
+
+Each render hook is a template, with one template for each supported element type:
+
+```text
+layouts/
+└── _default/
+ └── _markup/
+ ├── render-codeblock.html
+ ├── render-heading.html
+ ├── render-image.html
+ └── render-link.html
+```
+
+The template lookup order allows you to create different render hooks for each page [type], [kind], language, and [output format]. For example:
+
+```text
+layouts/
+├── _default/
+│ └── _markup/
+│ ├── render-link.html
+│ └── render-link.text.txt
+├── books/
+│ └── _markup/
+│ ├── render-link.html
+│ └── render-link.text.txt
+└── films/
+ └── _markup/
+ ├── render-link.html
+ └── render-link.text.txt
+```
+
+[kind]: /getting-started/glossary/#page-kind
+[output format]: /getting-started/glossary/#output-format
+[type]: /getting-started/glossary/#content-type
+
+The remaining pages in this section describe each type of render hook, including examples and the context received by each template.
diff --git a/content/en/render-hooks/links.md b/content/en/render-hooks/links.md
new file mode 100755
index 000000000..bf0485068
--- /dev/null
+++ b/content/en/render-hooks/links.md
@@ -0,0 +1,133 @@
+---
+title: Link render hooks
+linkTitle: Links
+description: Create a link render hook to override the rendering of Markdown links to HTML.
+categories: [render hooks]
+keywords: []
+menu:
+ docs:
+ parent: render-hooks
+ weight: 60
+weight: 60
+toc: true
+---
+
+## Markdown
+
+A Markdown link has three components: the link text, the link destination, and optionally the link title.
+
+```text
+[Post 1](/posts/post-1 "My first post")
+ ------ ------------- -------------
+ text destination title
+```
+
+These components are passed into the render hook [context] as shown below.
+
+[context]: /getting-started/glossary/#context
+
+## Context
+
+Link render hook templates receive the following context:
+
+[context]: /getting-started/glossary/#context
+
+###### Destination
+
+(`string`) The link destination.
+
+###### 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 link description as plain text.
+
+###### Text
+
+(`string`) The link description.
+
+###### 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 %}}
+
+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 >}}
+<a href="{{ .Destination | safeURL }}"
+ {{- with .Title }} title="{{ . }}"{{ end -}}
+>
+ {{- with .Text | safeHTML }}{{ . }}{{ end -}}
+</a>
+{{- /* 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 >}}
+{{- $u := urls.Parse .Destination -}}
+<a href="{{ .Destination | safeURL }}"
+ {{- with .Title }} title="{{ . }}"{{ end -}}
+ {{- if $u.IsAbs }} rel="external"{{ end -}}
+>
+ {{- with .Text | safeHTML }}{{ . }}{{ end -}}
+</a>
+{{- /* chomp trailing newline */ -}}
+{{< /code >}}
+
+## Default
+
+{{< new-in 0.123.0 >}}
+
+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
+{{< /code-toggle >}}
+
+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 %}}
+
+The embedded link render hook resolves internal Markdown destinations by looking for a matching page, falling back to a matching [page resource], then falling back to a matching [global resource]. Remote destinations are passed through, and the render hook will not throw an error or warning if it is unable to resolve a destination.
+
+[page resource]: /getting-started/glossary/#page-resource
+[global resource]: /getting-started/glossary/#global-resource
+
+You must place global resources in the assets directory. If you have placed your resources in the static directory, and you are unable or unwilling to move them, you must mount the static directory to the assets directory by including both of these entries in your site configuration:
+
+{{< code-toggle file=hugo >}}
+[[module.mounts]]
+source = 'assets'
+target = 'assets'
+
+[[module.mounts]]
+source = 'static'
+target = 'assets'
+{{< /code-toggle >}}
+
+{{% include "/render-hooks/_common/pageinner.md" %}}
diff --git a/content/en/showcase/forestry/index.md b/content/en/showcase/forestry/index.md
index 32a932a7a..fabcb7cd3 100644
--- a/content/en/showcase/forestry/index.md
+++ b/content/en/showcase/forestry/index.md
@@ -36,7 +36,7 @@ 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://twitter.com/hmncllctv/status/968907474664284160). Nichlas created it using [**3DS Max**](https://www.autodesk.com/products/3ds-max/overview).
+* 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.
diff --git a/content/en/showcase/keycdn/index.md b/content/en/showcase/keycdn/index.md
index d092aa07d..6308b34c4 100644
--- a/content/en/showcase/keycdn/index.md
+++ b/content/en/showcase/keycdn/index.md
@@ -26,5 +26,5 @@ Below is an overview of what we used with Hugo to build our website:
* 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 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/quiply-employee-communications-app/index.md b/content/en/showcase/quiply-employee-communications-app/index.md
index a8c31cc33..e1e426ed2 100644
--- a/content/en/showcase/quiply-employee-communications-app/index.md
+++ b/content/en/showcase/quiply-employee-communications-app/index.md
@@ -24,6 +24,6 @@ With the launch of our Employee Communications app Quiply we created a very simp
As our customer base and demand for marketing and communication started to grow, we needed a solution to easily grow and extend the contents of our web presence. As we do not have the need to serve dynamic content, we decided to use a static site generator. Amongst a couple of others, we tried Hugo and 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.
-Our website which we launched a couple of weeks ago is still growing and new content is being added constantly. By using Hugo, this can be easily done by content authors writing markdown files without always having to touch HTML or CSS code. It is available in German only for the time being, an English version is in the works.
+Our website which we launched a couple of weeks ago is still growing and new content is being added constantly. By using Hugo, this can be easily done by content authors writing Markdown files without always having to touch HTML or CSS code. It is available in German only for the time being, an English version is in the works.
Huge thanks to everyone involved in making Hugo a success.
diff --git a/content/en/templates/404.md b/content/en/templates/404.md
index 7fd27a358..44858f8b1 100644
--- a/content/en/templates/404.md
+++ b/content/en/templates/404.md
@@ -1,7 +1,7 @@
---
title: Custom 404 page
-linkTitle: 404 page
-description: If you know how to create a single page template, you have unlimited options for creating a custom 404.
+linkTitle: 404 template
+description: Create a template to render a 404 error page.
categories: [templates]
keywords: ['404',page not found]
menu:
@@ -11,45 +11,43 @@ menu:
weight: 220
---
-When using Hugo with [GitHub Pages](https://pages.github.com/), you can provide your own template for a [custom 404 error page](https://docs.github.com/en/pages/getting-started-with-github-pages/creating-a-custom-404-page-for-your-github-pages-site) by creating a 404.html template file in the root of your `layouts` folder. When Hugo generates your site, the `404.html` file will be placed in the root.
-
-404 pages will have all the regular [page variables][pagevars] available to use in the templates.
-
-In addition to the standard page variables, the 404 page has access to all site content accessible from `.Pages`.
-
-```txt
-▾ layouts/
- 404.html
-```
-
-## 404.html
-
-This is a basic example of a 404.html template:
+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 >}}
{{ define "main" }}
- <main id="main">
- <div>
- <h1 id="title"><a href="{{ "" | relURL }}">Go Home</a></h1>
- </div>
- </main>
+ <h1>404 Not Found</h1>
+ <p>The page you requested cannot be found.</p>
+ <p>
+ <a href="{{ .Site.Home.RelPermalink }}">
+ Return to the home page
+ </a>
+ </p>
{{ end }}
{{< /code >}}
-## Automatic loading
+For multilingual sites, add the language key to the file name:
-Your 404.html file can be set to load automatically when a visitor enters a mistaken URL path, dependent upon the web serving environment you are using. For example:
-
-* [GitHub Pages](/hosting-and-deployment/hosting-on-github/), [GitLab Pages](/hosting-and-deployment/hosting-on-gitlab/) and [Cloudflare Pages](/hosting-and-deployment/hosting-on-cloudflare-pages/). The 404 page is automatic.
-* Apache. You can specify `ErrorDocument 404 /404.html` in an `.htaccess` file in the root of your site.
-* Nginx. You might specify `error_page 404 /404.html;` in your `nginx.conf` file. [Details here](https://nginx.org/en/docs/http/ngx_http_core_module.html#error_page).
-* Amazon AWS S3. When setting a bucket up for static web serving, you can specify the error file from within the S3 GUI.
-* Amazon CloudFront. You can specify the page in the Error Pages section in the CloudFront Console. [Details here](https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/custom-error-pages.html)
-* Caddy Server. Use the `handle_errors` directive to specify error pages for one or more status codes. [Details here](https://caddyserver.com/docs/caddyfile/directives/handle_errors)
-* Netlify. Add `/* /404.html 404` to `content/_redirects`. [Details Here](https://www.netlify.com/docs/redirects/#custom-404)
-* Azure Static Web App. set `responseOverrides.404.rewrite` and `responseOverrides.404.statusCode` in configfile `staticwebapp.config.json`. [Details here](https://docs.microsoft.com/en-us/azure/static-web-apps/configuration#response-overrides)
-* Azure Storage as Static Web Site Hosting. You can specify the `Error document path` in the Static website configuration page of the Azure portal. [Details here](https://docs.microsoft.com/en-us/azure/storage/blobs/storage-blob-static-website).
-* DigitalOcean App Platform. You can specify `error_document` in your app specification file or use control panel to set up error document. [Details here](https://docs.digitalocean.com/products/app-platform/how-to/manage-static-sites/#configure-a-static-site).
-* [Firebase Hosting](https://firebase.google.com/docs/hosting/full-config#404): `/404.html` automatically gets used as the 404 page.
+```text
+layouts/
+├── 404.de.html
+├── 404.en.html
+└── 404.fr.html
+```
-[pagevars]: /variables/page/
+Your production server redirects the browser to the 404 page when a page is not found. Capabilities and configuration vary by host.
+
+Host|Capabilities and configuration
+:--|:--
+Amazon CloudFront|See [details](https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/GeneratingCustomErrorResponses.html).
+Amazon S3|See [details](https://docs.aws.amazon.com/AmazonS3/latest/userguide/CustomErrorDocSupport.html).
+Apache|See [details](https://httpd.apache.org/docs/2.4/custom-error.html).
+Azure Static Web Apps|See [details](https://learn.microsoft.com/en-us/azure/static-web-apps/configuration#response-overrides).
+Azure Storage|See [details](https://learn.microsoft.com/en-us/azure/storage/blobs/storage-blob-static-website#setting-up-a-static-website).
+Caddy|See [deatils](https://caddyserver.com/docs/caddyfile/directives/handle_errors).
+Cloudflare Pages|See [details](https://developers.cloudflare.com/pages/configuration/serving-pages/#not-found-behavior).
+DigitalOcean App Platform|See [details](https://docs.digitalocean.com/products/app-platform/how-to/manage-static-sites/#configure-a-static-site).
+Firebase|See [details](https://firebase.google.com/docs/hosting/full-config#404).
+GitHub Pages|Redirection to is automatic and not configurable.
+GitLab Pages|See [details](https://docs.gitlab.com/ee/user/project/pages/introduction.html#custom-error-codes-pages).
+NGINX|See [details](https://nginx.org/en/docs/http/ngx_http_core_module.html#error_page).
+Netlify|See [details](https://docs.netlify.com/routing/redirects/redirect-options/).
diff --git a/content/en/templates/_index.md b/content/en/templates/_index.md
index b2197d162..23b2a3eaf 100644
--- a/content/en/templates/_index.md
+++ b/content/en/templates/_index.md
@@ -1,12 +1,12 @@
---
title: Templates
-linkTitle: Overview
+linkTitle: In this section
description: Go templating, template types and lookup order, shortcodes, and data.
categories: []
keywords: []
menu:
docs:
- identifier: templates-overview
+ identifier: templates-in-this-section
parent: templates
weight: 10
weight: 10
diff --git a/content/en/templates/base.md b/content/en/templates/base.md
index 63bf2f9b2..6262e74b8 100644
--- a/content/en/templates/base.md
+++ b/content/en/templates/base.md
@@ -91,7 +91,7 @@ The following shows how you can override both the `"main"` and `"title"` block a
{{ end }}
{{< /code >}}
-[hugolists]: /templates/lists
+[hugolists]: /templates/lists/
[lookup]: /templates/lookup-order/
[rendering the section]: /templates/section-templates/
[singletemplate]: /templates/single-page-templates/
diff --git a/content/en/templates/data-templates.md b/content/en/templates/data-templates.md
deleted file mode 100644
index 435bd70b2..000000000
--- a/content/en/templates/data-templates.md
+++ /dev/null
@@ -1,177 +0,0 @@
----
-title: Data templates
-description: In addition to Hugo's built-in variables, you can specify your own custom data in templates or shortcodes that pull from both local and dynamic sources.
-categories: [templates]
-keywords: [data,dynamic,csv,json,toml,yaml,xml]
-menu:
- docs:
- parent: templates
- weight: 150
-weight: 150
-toc: true
-aliases: [/extras/datafiles/,/extras/datadrivencontent/,/doc/datafiles/]
----
-
-Hugo supports loading data from YAML, JSON, XML, and TOML files located in the `data` directory at the root of your Hugo project.
-
-{{< youtube FyPgSuwIMWQ >}}
-
-## The data directory
-
-The `data` directory should store additional data for Hugo to use when generating your site.
-
-Data files are not for generating standalone pages. They should supplement content files by:
-
-- Extending the content when the front matter fields grow out of control, or
-- Showing a larger dataset in a template (see the example below).
-
-In both cases, it's a good idea to outsource the data in their (own) files.
-
-These files must be YAML, JSON, XML, or TOML files (using the `.yml`, `.yaml`, `.json`, `.xml`, or `.toml` extension). The data will be accessible as a `map` in the `.Site.Data` variable.
-
-To access the data using the `site.Data.filename` notation, the file name must begin with an underscore or a Unicode letter, followed by zero or more underscores, Unicode letters, or Unicode digits. For example:
-
-- `123.json` - Invalid
-- `x123.json` - Valid
-- `_123.json` - Valid
-
-To access the data using the [`index`](/functions/collections/indexfunction) function, the file name is irrelevant. For example:
-
-Data file|Template code
-:--|:--
-`123.json`|`{{ index .Site.Data "123" }}`
-`x123.json`|`{{ index .Site.Data "x123" }}`
-`_123.json`|`{{ index .Site.Data "_123" }}`
-`x-123.json`|`{{ index .Site.Data "x-123" }}`
-
-## Data files in themes
-
-Data Files can also be used in themes.
-
-However, note that the theme data files are merged with the project directory taking precedence. That is, Given two files with the same name and relative path, the data in the file in the root project `data` directory will override the data from the file in the `themes/<THEME>/data` directory *for keys that are duplicated*).
-
-Therefore, theme authors should be careful not to include data files that could be easily overwritten by a user who decides to [customize a theme][customize]. For theme-specific data items that shouldn't be overridden, it can be wise to prefix the folder structure with a namespace; e.g. `mytheme/data/<THEME>/somekey/...`. To check if any such duplicate exists, run hugo with the `-v` flag.
-
-The keys in the map created with data templates from data files will be a dot-chained set of `path`, `filename`, and `key` in the file (if applicable).
-
-This is best explained with an example:
-
-## Examples
-
-### Jaco Pastorius' Solo Discography
-
-[Jaco Pastorius](https://en.wikipedia.org/wiki/Jaco_Pastorius_discography) was a great bass player, but his solo discography is short enough to use as an example. [John Patitucci](https://en.wikipedia.org/wiki/John_Patitucci) is another bass giant.
-
-The example below is a bit contrived, but it illustrates the flexibility of data Files. This example uses TOML as its file format with the two following data files:
-
-* `data/jazz/bass/jacopastorius.toml`
-* `data/jazz/bass/johnpatitucci.toml`
-
-`jacopastorius.toml` contains the content below. `johnpatitucci.toml` contains a similar list:
-
-{{< code-toggle file=data/jazz/bass/jacopastorius >}}
-discography = [
-"1974 - Modern American Music … Period! The Criteria Sessions",
-"1974 - Jaco",
-"1976 - Jaco Pastorius",
-"1981 - Word of Mouth",
-"1981 - The Birthday Concert (released in 1995)",
-"1982 - Twins I & II (released in 1999)",
-"1983 - Invitation",
-"1986 - Broadway Blues (released in 1998)",
-"1986 - Honestly Solo Live (released in 1990)",
-"1986 - Live In Italy (released in 1991)",
-"1986 - Heavy'n Jazz (released in 1992)",
-"1991 - Live In New York City, Volumes 1-7.",
-"1999 - Rare Collection (compilation)",
-"2003 - Punk Jazz: The Jaco Pastorius Anthology (compilation)",
-"2007 - The Essential Jaco Pastorius (compilation)"
-]
-{{< /code-toggle >}}
-
-The list of bass players can be accessed via `.Site.Data.jazz.bass`, a single bass player by adding the file name without the suffix, e.g. `.Site.Data.jazz.bass.jacopastorius`.
-
-You can now render the list of recordings for all the bass players in a template:
-
-```go-html-template
-{{ range $.Site.Data.jazz.bass }}
- {{ partial "artist.html" . }}
-{{ end }}
-```
-
-And then in the `partials/artist.html`:
-
-```go-html-template
-<ul>
-{{ range .discography }}
- <li>{{ . }}</li>
-{{ end }}
-</ul>
-```
-
-Discover a new favorite bass player? Just add another `.toml` file in the same directory.
-
-### Accessing named values in a data file
-
-Assume you have the following data structure in your `user0123` data file located directly in `data/`:
-
-{{< code-toggle file=data/user0123 >}}
-Name: User0123
-"Short Description": "He is a **jolly good** fellow."
-Achievements:
- - "Can create a Key, Value list from Data File"
- - "Learns Hugo"
- - "Reads documentation"
-{{</ code-toggle >}}
-
-You can use the following code to render the `Short Description` in your layout:
-
-```go-html-template
-<div>Short Description of {{ .Site.Data.user0123.Name }}: <p>{{ index .Site.Data.user0123 "Short Description" | markdownify }}</p></div>
-```
-
-Note the use of the [`markdownify`] function. This will send the description through the Markdown rendering engine.
-
-## Remote data
-
-Retrieve remote data using these template functions:
-
-- [`resources.GetRemote`](/functions/resources/getremote) (recommended)
-- [`data.GetCSV`](/functions/data/getcsv)
-- [`data.GetJSON`](/functions/data/getjson)
-
-## LiveReload with data files
-
-There is no chance to trigger a [LiveReload] when the content of a URL changes. However, when a *local* file changes (i.e., `data/*` and `themes/<THEME>/data/*`), a LiveReload will be triggered. Symlinks are not supported. Note too that because downloading data takes a while, Hugo stops processing your Markdown files until the data download has been completed.
-
-{{% note %}}
-If you change any local file and the LiveReload is triggered, Hugo will read the data-driven (URL) content from the cache. If you have disabled the cache (i.e., by running the server with `hugo server --ignoreCache`), Hugo will re-download the content every time LiveReload triggers. This can create *huge* traffic. You may reach API limits quickly.
-{{% /note %}}
-
-## Examples of data-driven content
-
-- Photo gallery JSON powered: [https://github.com/pcdummy/hugo-lightslider-example](https://github.com/pcdummy/hugo-lightslider-example)
-- GitHub Starred Repositories [in a post](https://github.com/SchumacherFM/blog-cs/blob/master/content%2Fposts%2Fgithub-starred.md) using data-driven content in a [custom short code](https://github.com/SchumacherFM/blog-cs/blob/master/layouts%2Fshortcodes%2FghStarred.html).
-
-## Specs for data formats
-
-* [TOML Spec][toml]
-* [YAML Spec][yaml]
-* [JSON Spec][json]
-* [CSV Spec][csv]
-* [XML Spec][xml]
-
-[config]: /getting-started/configuration/
-[csv]: https://tools.ietf.org/html/rfc4180
-[customize]: /hugo-modules/theme-components/
-[json]: https://www.ecma-international.org/publications/files/ECMA-ST/ECMA-404.pdf
-[LiveReload]: /getting-started/usage/#livereload
-[lookup]: /templates/lookup-order/
-[`markdownify`]: /functions/transform/markdownify
-[OAuth]: https://en.wikipedia.org/wiki/OAuth
-[partials]: /templates/partials/
-[toml]: https://toml.io/en/latest
-[variadic]: https://en.wikipedia.org/wiki/Variadic_function
-[vars]: /variables/
-[yaml]: https://yaml.org/spec/
-[xml]: https://www.w3.org/XML/
diff --git a/content/en/templates/embedded.md b/content/en/templates/embedded.md
new file mode 100644
index 000000000..5b2043962
--- /dev/null
+++ b/content/en/templates/embedded.md
@@ -0,0 +1,223 @@
+---
+title: Embedded templates
+description: Hugo provides embedded templates for common use cases.
+categories: [templates]
+keywords: [internal, analytics,]
+menu:
+ docs:
+ parent: templates
+ weight: 190
+weight: 190
+toc: true
+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 %}}
+
+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
+{{ template "_internal/disqus.html" . }}
+```
+
+### Configure Disqus
+
+To use Hugo's Disqus template, first set up a single configuration value:
+
+{{< code-toggle file="hugo" >}}
+[services.disqus]
+shortname = 'your-disqus-shortname'
+{{</ code-toggle >}}
+
+Hugo's Disqus template accesses this value with:
+
+```go-html-template
+{{ .Site.Config.Services.Disqus.Shortname }}
+```
+
+You can also set the following in the front matter for a given piece of content:
+
+- `disqus_identifier`
+- `disqus_title`
+- `disqus_url`
+
+## 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 %}}
+
+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
+{{ template "_internal/google_analytics.html" . }}
+```
+
+### Configure Google Analytics
+
+Provide your tracking ID in your configuration file:
+
+{{< code-toggle file=hugo >}}
+[services.googleAnalytics]
+ID = "G-MEASUREMENT_ID"
+{{</ code-toggle >}}
+
+To use this value in your own template, access the configured ID with `{{ site.Config.Services.GoogleAnalytics.ID }}`.
+
+## 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 %}}
+
+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.
+
+To include the embedded template:
+
+```go-html-template
+{{ template "_internal/opengraph.html" . }}
+```
+
+### Configure Open Graph
+
+Hugo's Open Graph template is configured using a mix of configuration settings and [front matter](/content-management/front-matter/) on individual pages.
+
+{{< code-toggle file=hugo >}}
+[params]
+ description = 'Text about my cool site'
+ images = ['site-feature-image.jpg']
+ title = 'My cool site'
+ [params.social]
+ facebook_admin = 'jsmith'
+[taxonomies]
+ series = 'series'
+{{</ code-toggle >}}
+
+{{< code-toggle file=content/blog/my-post.md fm=true >}}
+title = "Post title"
+description = "Text about this post"
+date = 2024-03-08T08:18:11-08:00
+images = ["post-cover.png"]
+audio = []
+videos = []
+series = []
+tags = []
+{{</ code-toggle >}}
+
+Hugo uses the page title and description for the title and description metadata.
+The first 6 URLs from the `images` array are used for image metadata.
+If [page bundles](/content-management/page-bundles/) are used and the `images` array is empty or undefined, images with file names matching `*feature*` or `*cover*,*thumbnail*` are used for image metadata.
+
+Various optional metadata can also be set:
+
+- Date, published date, and last modified data are used to set the published time metadata if specified.
+- `audio` and `videos` are URL arrays like `images` for the audio and video metadata tags, respectively.
+- The first 6 `tags` on the page are used for the tags metadata.
+- The `series` taxonomy is used to specify related "see also" pages by placing them in the same series.
+
+If using YouTube this will produce a og:video tag like `<meta property="og:video" content="url">`. Use the `https://youtu.be/<id>` format with YouTube videos (example: `https://youtu.be/qtIqKaDlqXo`).
+
+## Schema
+
+{{% note %}}
+To override Hugo's embedded Schema 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 "schema.html" . }}`
+
+[`partial`]: /functions/partials/include/
+[source code]: {{% eturl schema %}}
+{{% /note %}}
+
+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
+{{ template "_internal/schema.html" . }}
+```
+
+## 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 %}}
+
+Hugo includes an embedded template for [X (Twitter) Cards](https://developer.x.com/en/docs/twitter-for-websites/cards/overview/abouts-cards),
+metadata used to attach rich media to Tweets linking to your site.
+
+To include the embedded template:
+
+```go-html-template
+{{ template "_internal/twitter_cards.html" . }}
+```
+
+### Configure X (Twitter) Cards
+
+Hugo's X (Twitter) Card template is configured using a mix of configuration settings and [front-matter](/content-management/front-matter/) values on individual pages.
+
+{{< code-toggle file=hugo >}}
+[params]
+ images = ["site-feature-image.jpg"]
+ description = "Text about my cool site"
+{{</ code-toggle >}}
+
+{{< code-toggle file=content/blog/my-post.md >}}
+title = "Post title"
+description = "Text about this post"
+images = ["post-cover.png"]
+{{</ code-toggle >}}
+
+If `images` aren't specified in the page front-matter, then hugo searches for [image page resources](/content-management/image-processing/) with `feature`, `cover`, or `thumbnail` in their name.
+If no image resources with those names are found, the images defined in the [site config](/getting-started/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 >}}
+[params.social]
+twitter = "GoHugoIO"
+{{</ code-toggle >}}
+
+NOTE: The `@` will be added for you
+
+```html
+<meta name="twitter:site" content="@GoHugoIO"/>
+```
diff --git a/content/en/templates/homepage.md b/content/en/templates/homepage.md
index 59b7472fb..cd5b32604 100644
--- a/content/en/templates/homepage.md
+++ b/content/en/templates/homepage.md
@@ -12,11 +12,8 @@ toc: true
aliases: [/layout/homepage/,/templates/homepage-template/]
---
-Homepage is a `Page` and therefore has all the [page variables][pagevars] and [site variables][sitevars] available for use.
-
-{{% note %}}
The homepage template is the *only* required template for building a site and therefore useful when bootstrapping a new site and template. It is also the only required template if you are developing a single-page website.
-{{% /note %}}
+
{{< youtube ut1xtRZ1QOA >}}
@@ -32,8 +29,6 @@ See the homepage template below or [Content Organization][contentorg] for more i
## Example homepage template
-The following is an example of a homepage template that uses [partial][partials], [base] templates, and a content file at `content/_index.md` to populate the `{{ .Title }}` and `{{ .Content }}` [page variables][pagevars].
-
{{< code file=layouts/index.html >}}
{{ define "main" }}
<main aria-role="main">
@@ -56,10 +51,6 @@ The following is an example of a homepage template that uses [partial][partials]
{{ end }}
{{< /code >}}
-[base]: /templates/base/
[contentorg]: /content-management/organization/
[lists]: /templates/lists/
[lookup]: /templates/lookup-order/
-[pagevars]: /variables/page/
-[partials]: /templates/partials/
-[sitevars]: /variables/site/
diff --git a/content/en/templates/internal.md b/content/en/templates/internal.md
deleted file mode 100644
index 9438bfa6f..000000000
--- a/content/en/templates/internal.md
+++ /dev/null
@@ -1,221 +0,0 @@
----
-title: Internal templates
-description: Hugo ships with a group of boilerplate templates that cover the most common use cases for static websites.
-categories: [templates]
-keywords: [internal, analytics,]
-menu:
- docs:
- parent: templates
- weight: 190
-weight: 190
-toc: true
----
-
-{{% note %}}
-While the following internal templates are called similar to partials, they do *not* observe the partial template lookup order.
-{{% /note %}}
-
-## Google Analytics
-
-Hugo ships with an internal template supporting [Google Analytics 4].
-
-[Google Analytics 4]: https://support.google.com/analytics/answer/10089681
-
-### Configure Google Analytics
-
-Provide your tracking ID in your configuration file:
-
-**Google Analytics 4 (gtag.js)**
-{{< code-toggle file=hugo >}}
-[services.googleAnalytics]
-ID = "G-MEASUREMENT_ID"
-{{</ code-toggle >}}
-
-### Use the Google Analytics template
-
-Include the Google Analytics internal template in your templates where you want the code to appear:
-
-```go-html-template
-{{ template "_internal/google_analytics.html" . }}
-```
-
-To create your own template, access the configured ID with `{{ site.Config.Services.GoogleAnalytics.ID }}`.
-
-## Disqus
-
-Hugo also ships with an internal template for [Disqus comments][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][disqussignup].
-
-### Configure Disqus
-
-To use Hugo's Disqus template, first set up a single configuration value:
-
-{{< code-toggle file="hugo" >}}
-[services.disqus]
-shortname = 'your-disqus-shortname'
-{{</ code-toggle >}}
-
-Hugo's Disqus template accesses this value with:
-
-```go-html-template
-{{ .Site.Config.Services.Disqus.Shortname }}
-```
-
-You can also set the following in the front matter for a given piece of content:
-
-* `disqus_identifier`
-* `disqus_title`
-* `disqus_url`
-
-### Use the Disqus template
-
-To add Disqus, include the following line in the templates where you want your comments to appear:
-
-```go-html-template
-{{ template "_internal/disqus.html" . }}
-```
-
-### Conditional loading of Disqus comments
-
-Users have noticed that enabling Disqus comments when running the Hugo web server on `localhost` (i.e. via `hugo server`) causes the creation of unwanted discussions on the associated Disqus account.
-
-You can create the following `layouts/partials/disqus.html`:
-
-{{< code file=layouts/partials/disqus.html >}}
-<div id="disqus_thread"></div>
-<script type="text/javascript">
-
-(function() {
- // Don't ever inject Disqus on localhost--it creates unwanted
- // discussions from 'localhost:1313' on your Disqus account...
- if (window.location.hostname == "localhost")
- return;
-
- var dsq = document.createElement('script'); dsq.type = 'text/javascript'; dsq.async = true;
- var disqus_shortname = '{{ .Site.Config.Services.Disqus.Shortname }}';
- dsq.src = '//' + disqus_shortname + '.disqus.com/embed.js';
- (document.getElementsByTagName('head')[0] || document.getElementsByTagName('body')[0]).appendChild(dsq);
-})();
-</script>
-<noscript>Please enable JavaScript to view the <a href="https://disqus.com/?ref_noscript">comments powered by Disqus.</a></noscript>
-<a href="https://disqus.com/" class="dsq-brlink">comments powered by <span class="logo-disqus">Disqus</span></a>
-{{< /code >}}
-
-The `if` statement skips the initialization of the Disqus comment injection when you are running on `localhost`.
-
-You can then render your custom Disqus partial template as follows:
-
-```go-html-template
-{{ partial "disqus.html" . }}
-```
-
-## Open Graph
-
-An internal 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.
-
-### Configure Open Graph
-
-Hugo's Open Graph template is configured using a mix of configuration variables and [front-matter](/content-management/front-matter/) on individual pages.
-
-{{< code-toggle file=hugo >}}
-[params]
- title = "My cool site"
- images = ["site-feature-image.jpg"]
- description = "Text about my cool site"
-[taxonomies]
- series = "series"
-{{</ code-toggle >}}
-
-{{< code-toggle file=content/blog/my-post.md >}}
-title = "Post title"
-description = "Text about this post"
-date = "2006-01-02"
-images = ["post-cover.png"]
-audio = []
-videos = []
-series = []
-tags = []
-{{</ code-toggle >}}
-
-Hugo uses the page title and description for the title and description metadata.
-The first 6 URLs from the `images` array are used for image metadata.
-If [page bundles](/content-management/page-bundles/) are used and the `images` array is empty or undefined, images with file names matching `*feature*` or `*cover*,*thumbnail*` are used for image metadata.
-
-Various optional metadata can also be set:
-
-- Date, published date, and last modified data are used to set the published time metadata if specified.
-- `audio` and `videos` are URL arrays like `images` for the audio and video metadata tags, respectively.
-- The first 6 `tags` on the page are used for the tags metadata.
-- The `series` taxonomy is used to specify related "see also" pages by placing them in the same series.
-
-If using YouTube this will produce a og:video tag like `<meta property="og:video" content="url">`. Use the `https://youtu.be/<id>` format with YouTube videos (example: `https://youtu.be/qtIqKaDlqXo`).
-
-### Use the Open Graph template
-
-To add Open Graph metadata, include the following line between the `<head>` tags in your templates:
-
-```go-html-template
-{{ template "_internal/opengraph.html" . }}
-```
-
-## Twitter Cards
-
-An internal template for [Twitter Cards](https://developer.twitter.com/en/docs/twitter-for-websites/cards/overview/abouts-cards),
-metadata used to attach rich media to Tweets linking to your site.
-
-### Configure Twitter Cards
-
-Hugo's Twitter Card template is configured using a mix of configuration variables and [front-matter](/content-management/front-matter/) on individual pages.
-
-{{< code-toggle file=hugo >}}
-[params]
- images = ["site-feature-image.jpg"]
- description = "Text about my cool site"
-{{</ code-toggle >}}
-
-{{< code-toggle file=content/blog/my-post.md >}}
-title = "Post title"
-description = "Text about this post"
-images = ["post-cover.png"]
-{{</ code-toggle >}}
-
-If `images` aren't specified in the page front-matter, then hugo searches for [image page resources](/content-management/image-processing/) with `feature`, `cover`, or `thumbnail` in their name.
-If no image resources with those names are found, the images defined in the [site config](/getting-started/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 >}}
-[params.social]
-twitter = "GoHugoIO"
-{{</ code-toggle >}}
-
-NOTE: The `@` will be added for you
-
-```html
-<meta name="twitter:site" content="@GoHugoIO"/>
-```
-
-### Use the Twitter Cards template
-
-To add Twitter card metadata, include the following line immediately after the `<head>` element in your templates:
-
-```go-html-template
-{{ template "_internal/twitter_cards.html" . }}
-```
-
-## The internal templates
-
-The code for these templates is located [here](https://github.com/gohugoio/hugo/tree/master/tpl/tplimpl/embedded/templates).
-
-* `_internal/disqus.html`
-* `_internal/google_analytics.html`
-* `_internal/opengraph.html`
-* `_internal/pagination.html`
-* `_internal/schema.html`
-* `_internal/twitter_cards.html`
-
-[disqus]: https://disqus.com
-[disqussignup]: https://disqus.com/profile/signup/
diff --git a/content/en/templates/introduction.md b/content/en/templates/introduction.md
index 7fb0ddecf..994e81854 100644
--- a/content/en/templates/introduction.md
+++ b/content/en/templates/introduction.md
@@ -1,672 +1,563 @@
---
-title: Templating
-linkTitle: Templating
-description: Hugo uses Go's `html/template` and `text/template` libraries as the basis for the templating.
+title: Introduction to templating
+linkTitle: Introduction
+description: Create templates to render your content, resources, and data.
categories: [templates,fundamentals]
-keywords: [go]
+keywords: []
menu:
docs:
+ identifier: templates-introduction
parent: templates
weight: 20
weight: 20
toc: true
-aliases: [/layouts/introduction/,/layout/introduction/, /templates/go-templates/]
---
-{{% note %}}
-The following is only a primer on Go Templates. For an in-depth look into Go Templates, check the official [Go docs](https://golang.org/pkg/text/template/).
-{{% /note %}}
-
-Go Templates provide an extremely simple template language that adheres to the belief that only the most basic of logic belongs in the template or view layer.
+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.
-## Basic syntax
+[functions]: /functions/
+[methods]: /methods/
+[variables]: #variables
-Go Templates are HTML files with the addition of [variables][variables] and [functions][functions]. Go Template variables and functions are accessible within `{{ }}`.
+{{% note %}}
+Hugo uses Go's [text/template] and [html/template] packages.
-### Access a predefined variable
+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.
-A _predefined variable_ could be a variable already existing in the
-current scope (like the `.Title` example in the [Variables](#variables) section below) or a custom variable (like the
-`$address` example in that same section).
+By default, Hugo uses the html/template package when rendering HTML files.
-```go-html-template
-{{ .Title }}
-{{ $address }}
-```
+[text/template]: https://pkg.go.dev/text/template
+[html/template]: https://pkg.go.dev/html/template
+{{% /note %}}
-Parameters for functions are separated using spaces. The general syntax is:
+For example, this HTML template initializes the `$v1` and `$v2` variables, then displays them and their product within an HTML paragraph.
```go-html-template
-{{ FUNCTION ARG1 ARG2 .. }}
+{{ $v1 := 6 }}
+{{ $v2 := 7 }}
+<p>The product of {{ $v1 }} and {{ $v2 }} is {{ mul $v1 $v2 }}.</p>
```
-The following example calls the `add` function with inputs of `1` and `2`:
+While HTML templates are the most common, you can create templates for any [output format] including CSV, JSON, RSS, and plain text.
-```go-html-template
-{{ add 1 2 }}
-```
+[output format]: /templates/output-formats/
-#### Methods and fields are accessed via dot notation
+## Context
-Accessing the Page Parameter `bar` defined in a piece of content's [front matter].
+The most important concept to understand before creating a template is _context_, the data passed into each template. The data may be a simple value, or more commonly [objects] and associated [methods].
-```go-html-template
-{{ .Params.bar }}
-```
+[objects]: /getting-started/glossary/#object
+[methods]: /getting-started/glossary/#method
-#### Parentheses can be used to group items together
+For example, a template for a single page receives a `Page` object, and the `Page` object provides methods to return values or perform actions.
-```go-html-template
-{{ if or (isset .Params "alt") (isset .Params "caption") }} Caption {{ end }}
-```
-
-#### A single statement can be split over multiple lines
-
-```go-html-template
-{{ if or
- (isset .Params "alt")
- (isset .Params "caption")
-}}
-```
+### Current context
-#### Raw string literals can include newlines
-
-```go-html-template
-{{ $msg := `Line one.
-Line two.` }}
-```
-
-## Variables
+Within a template, the dot (`.`) represents the current context.
-Each Go Template gets a data object. In Hugo, each template is passed
-a `Page`. In the below example, `.Title` is one of the elements
-accessible in that [`Page` variable][pagevars].
+{{< code file=layouts/_default/single.html >}}
+<h2>{{ .Title }}</h2>
+{{< /code >}}
-With the `Page` being the default scope of a template, the `Title`
-element in current scope (`.` -- "the **dot**") is accessible simply
-by the dot-prefix (`.Title`):
+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].
-```go-html-template
-<title>{{ .Title }}</title>
-```
+[front matter]: /content-management/front-matter/
+[`Title`]: /methods/page/title
-Values can also be stored in custom variables and referenced later:
+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.
-{{% note %}}
-The custom variables need to be prefixed with `$`.
-{{% /note %}}
+[`range`]: /functions/go-template/range/
+[`with`]: /functions/go-template/with/
-```go-html-template
-{{ $address := "123 Main St." }}
-{{ $address }}
-```
+{{< code file=layouts/_default/single.html >}}
+<h2>{{ .Title }}</h2>
-Variables can be re-defined using the `=` operator. The example below
-prints "Var is Hugo Home" on the home page, and "Var is Hugo Page" on
-all other pages:
+{{ range slice "foo" "bar" }}
+ <p>{{ . }}</p>
+{{ end }}
-```go-html-template
-{{ $var := "Hugo Page" }}
-{{ if .IsHome }}
- {{ $var = "Hugo Home" }}
+{{ with "baz" }}
+ <p>{{ . }}</p>
{{ end }}
-Var is {{ $var }}
-```
+{{< /code >}}
-Variable names must conform to Go's naming rules for [identifiers][identifier].
+In the example above, the context changes as we `range` through the [slice] 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:
-## Functions
+[slice]: /getting-started/glossary/#slice
-Go Templates only ship with a few basic functions but also provide a mechanism for applications to extend the original set.
+```html
+<h2>My Page Title</h2>
+<p>foo</p>
+<p>bar</p>
+<p>baz</p>
+```
-[Hugo template functions][functions] provide additional functionality specific to building websites. Functions are called by using their name followed by the required parameters separated by spaces. Template functions cannot be added without recompiling Hugo.
+### Template context
-### Example 1: adding numbers
+Within a `range` or `with` block you can access the context passed into the template by prepending a dollar sign (`$`) to the dot:
-```go-html-template
-{{ add 1 2 }}
-<!-- prints 3 -->
-```
+{{< code file=layouts/_default/single.html >}}
+{{ with "foo" }}
+ <p>{{ $.Title }} - {{ . }}</p>
+{{ end }}
+{{< /code >}}
-### Example 2: comparing numbers
+Hugo renders this to:
-```go-html-template
-{{ lt 1 2 }}
-<!-- prints true (i.e., since 1 is less than 2) -->
+```html
+<p>My Page Title - foo</p>
```
-Note that both examples make use of Go Template's [math][math] functions.
-
{{% note %}}
-There are more boolean operators than those listed in the Hugo docs in the [Go Template documentation](https://golang.org/pkg/text/template/#hdr-Functions).
+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 %}}
-## Includes
+## Actions
-When including another template, you will need to pass it the data that it would
-need to access.
+In the examples above the paired opening and closing braces represent the beginning and end of a template action, a data evaluation or control structure within a template.
-{{% note %}}
-To pass along the current context, please remember to include a trailing **dot**.
-{{% /note %}}
+A template action may contain literal values ([boolean], [string], [integer], and [float]), variables, functions, and methods.
-The templates location will always be starting at the `layouts/` directory
-within Hugo.
+[boolean]: /getting-started/glossary/#boolean
+[string]: /getting-started/glossary/#string
+[integer]: /getting-started/glossary/#integer
+[float]: /getting-started/glossary/#float
-### Partial
+{{< code file=layouts/_default/single.html >}}
+{{ $convertToLower := true }}
+{{ if $convertToLower }}
+ <h2>{{ strings.ToLower .Title }}</h2>
+{{ end }}
+{{< /code >}}
-The [`partial`][partials] function is used to include _partial_ templates using
-the syntax `{{ partial "<PATH>/<PARTIAL>.<EXTENSION>" . }}`.
+In the example above:
-Example of including a `layouts/partials/header.html` partial:
+- `$convertToLower` is a variable
+- `true` is a literal boolean value
+- `strings.ToLower` is a function that converts all characters to lowercase
+- `Title` is a method on a the `Page` object
-```go-html-template
-{{ partial "header.html" . }}
+Hugo renders the above to:
+
+```html
+
+
+ <h2>my page title</h2>
+
```
-### Template
+### Whitespace
-The `template` function was used to include _partial_ templates
-in much older Hugo versions. Now it's useful only for calling
-[_internal_ templates][internal templates]. The syntax is `{{ template
-"_internal/<TEMPLATE>.<EXTENSION>" . }}`.
+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:
-{{% note %}}
-The available **internal** templates can be found
-[here](https://github.com/gohugoio/hugo/tree/master/tpl/tplimpl/embedded/templates).
-{{% /note %}}
+{{< code file=layouts/_default/single.html >}}
+{{- $convertToLower := true -}}
+{{- if $convertToLower -}}
+ <h2>{{ strings.ToLower .Title }}</h2>
+{{- end -}}
+{{< /code >}}
-Example of including the internal `opengraph.html` template:
+Hugo renders this to:
-```go-html-template
-{{ template "_internal/opengraph.html" . }}
+```html
+<h2>my page title</h2>
```
-## Logic
-
-Go Templates provide the most basic iteration and conditional logic.
+Whitespace includes spaces, horizontal tabs, carriage returns, and newlines.
-### Iteration
+### Pipes
-The Go Templates make heavy use of `range` to iterate over a _map_,
-_array_, or _slice_. The following are different examples of how to
-use `range`.
+Within a template action you may [pipe] a value to function or method. The piped value becomes the final argument to the function or method. For example, these are equivalent:
-#### Example 1: using context (`.`)
+[pipe]: /getting-started/glossary/#pipeline
```go-html-template
-{{ range $array }}
- {{ . }} <!-- The . represents an element in $array -->
-{{ end }}
+{{ strings.ToLower "Hugo" }} → hugo
+{{ "Hugo" | strings.ToLower }} → hugo
```
-#### Example 2: declaring a variable name for an array element's value
+You can pipe the result of one function or method into another. For example, these are equivalent:
```go-html-template
-{{ range $elem_val := $array }}
- {{ $elem_val }}
-{{ end }}
+{{ strings.TrimSuffix "o" (strings.ToLower "Hugo") }} → hug
+{{ "Hugo" | strings.ToLower | strings.TrimSuffix "o" }} → hug
```
-#### Example 3: declaring variable names for an array element's index _and_ value
-
-For an array or slice, the first declared variable will map to each
-element's index.
+These are also equivalent:
```go-html-template
-{{ range $elem_index, $elem_val := $array }}
- {{ $elem_index }} -- {{ $elem_val }}
-{{ end }}
+{{ mul 6 (add 2 5) }} → 42
+{{ 5 | add 2 | mul 6 }} → 42
```
-#### Example 4: declaring variable names for a map element's key _and_ value
-
-For a map, the first declared variable will map to each map element's
-key.
-
-```go-html-template
-{{ range $elem_key, $elem_val := $map }}
- {{ $elem_key }} -- {{ $elem_val }}
-{{ end }}
-```
+{{% note %}}
+Remember that the piped value becomes the final argument to the function or method to which you are piping.
+{{% /note %}}
-#### Example 5: conditional on empty _map_, _array_, or _slice_
+### Line splitting
-If the _map_, _array_, or _slice_ passed into the range is zero-length then the else statement is evaluated.
+You can split a template action over two or more lines. For example, these are equivalent:
```go-html-template
-{{ range $array }}
- {{ . }}
-{{ else }}
- <!-- This is only evaluated if $array is empty -->
-{{ end }}
-```
+{{ $v := or .Site.Language.LanguageName .Site.Language.Lang }}
-### Conditionals
+{{ $v := or
+ .Site.Language.LanguageName
+ .Site.Language.Lang
+}}
+```
-`if`, `else`, `with`, `or`, `and` and `not` provide the framework for handling conditional logic in Go Templates. Like `range`, `if` and `with` statements are closed with an `{{ end }}`.
+You can also split [raw string literals] over two or more lines. For example, these are equivalent:
-Go Templates treat the following values as **false**:
+[raw string literals]: /getting-started/glossary/#string-literal-raw
-- `false` (boolean)
-- 0 (integer)
-- any zero-length array, slice, map, or string
+```go-html-template
+{{ $msg := "This is line one.\nThis is line two." }}
-#### Example 1: `with`
+{{ $msg := `This is line one.
+This is line two.`
+}}
+```
-It is common to write "if something exists, do this" kind of
-statements using `with`.
+## Variables
-{{% note %}}
-`with` rebinds the context `.` within its scope (just like in `range`).
-{{% /note %}}
+A variable is a user-defined [identifier] prepended with a dollar sign (`$`), representing a value of any data type, initialized or assigned within a template action. For example, `$foo` and `$bar` are variables.
-It skips the block if the variable is absent, or if it evaluates to
-"false" as explained above.
+[identifier]: /getting-started/glossary/#identifier
-```go-html-template
-{{ with .Params.title }}
- <h4>{{ . }}</h4>
-{{ end }}
-```
+Variables may contain [scalars], [slices], [maps], or [objects].
-#### Example 2: `with` .. `else`
+[scalars]: /getting-started/glossary/#scalar
+[slices]: /getting-started/glossary/#slice
+[maps]: /getting-started/glossary/#map
+[objects]: /getting-started/glossary/#object
-Below snippet uses the "description" front-matter parameter's value if
-set, else uses the default `.Summary` [Page variable][pagevars]:
+Use `:=` to initialize a variable, and use `=` to assign a value to a variable that has been previously initialized. For example:
```go-html-template
-{{ with .Param "description" }}
- {{ . }}
-{{ else }}
- {{ .Summary }}
+{{ $total := 3 }}
+{{ range slice 7 11 21 }}
+ {{ $total = add $total . }}
{{ end }}
+{{ $total }} → 42
```
-See the [`.Param` function][param].
-
-#### Example 3: `if`
+Variables initialized inside of an `if`, `range`, or `with` block are scoped to the block. Variables initialized outside of these blocks are scoped to the template.
-An alternative (and a more verbose) way of writing `with` is using
-`if`. Here, the `.` does not get rebound.
+With variables that represent a slice or map, use the [`index`] function to return the desired value.
-Below example is "Example 1" rewritten using `if`:
+[`index`]: /functions/collections/indexfunction/
```go-html-template
-{{ if isset .Params "title" }}
- <h4>{{ index .Params "title" }}</h4>
-{{ end }}
-```
-
-#### Example 4: `if` .. `else`
-
-Below example is "Example 2" rewritten using `if` .. `else`, and using
-[`isset`] + `.Params` variable (different from the
-[`.Param` **function**][param]) instead:
+{{ $slice := slice "foo" "bar" "baz" }}
+{{ index $slice 2 }} → baz
-```go-html-template
-{{ if (isset .Params "description") }}
- {{ index .Params "description" }}
-{{ else }}
- {{ .Summary }}
-{{ end }}
+{{ $map := dict "a" "foo" "b" "bar" "c" "baz" }}
+{{ index $map "c" }} → baz
```
-#### Example 5: `if` .. `else if` .. `else`
-
-Unlike `with`, `if` can contain `else if` clauses too.
+{{% note %}}
+Slices and arrays are zero-based; element 0 is the first element.
+{{% /note %}}
-```go-html-template
-{{ if (isset .Params "description") }}
- {{ index .Params "description" }}
-{{ else if (isset .Params "summary") }}
- {{ index .Params "summary" }}
-{{ else }}
- {{ .Summary }}
-{{ end }}
-```
+With variables that represent a map or object, [chain] identifiers to return the desired value or to access the desired method.
-#### Example 6: `and` & `or`
+[chain]: /getting-started/glossary/#chain
```go-html-template
-{{ if (and (or (isset .Params "title") (isset .Params "caption")) (isset .Params "attr")) }}
-```
+{{ $map := dict "a" "foo" "b" "bar" "c" "baz" }}
+{{ $map.c }} → baz
-## Pipes
-
-One of the most powerful components of Go Templates is the ability to stack actions one after another. This is done by using pipes. Borrowed from Unix pipes, the concept is simple: each pipeline's output becomes the input of the following pipe.
+{{ $homePage := .Site.Home }}
+{{ $homePage.Title }} → My Homepage
+```
-Because of the very simple syntax of Go Templates, the pipe is essential to being able to chain together function calls. One limitation of the pipes is that they can only work with a single value and that value becomes the last parameter of the next pipeline.
+{{% 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 %}}
-A few simple examples should help convey how to use the pipe.
+## Functions
-### Example 1: `shuffle`
+Used within a template action, a function takes one or more arguments and returns a value. Unlike methods, functions are not associated with an object.
-The following two examples are functionally the same:
+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-html-template
-{{ shuffle (seq 1 5) }}
-```
+[go-templates]: /functions/go-template/
-```go-html-template
-{{ (seq 1 5) | shuffle }}
-```
+Hugo provides hundreds of custom [functions] categorized by namespace. For example, the `strings` namespace includes these and other functions:
-### Example 2: `index`
+[functions]: /functions
-The following accesses the page parameter called "disqus_url" and escapes the HTML. This example also uses the [`index`] function, which is built into Go Templates:
+Function|Alias
+:--|:--
+[`strings.ToLower`](/functions/strings/tolower)|`lower`
+[`strings.ToUpper`](/functions/strings/toupper)|`upper`
+[`strings.Replace`](/functions/strings/replace)|`replace`
-```go-html-template
-{{ index .Params "disqus_url" | html }}
-```
+As shown above, frequently used functions have an alias. Use aliases in your templates to reduce code length.
-### Example 3: `or` with `isset`
+When calling a function, separate the arguments from the function, and from each other, with a space. For example:
```go-html-template
-{{ if or (or (isset .Params "title") (isset .Params "caption")) (isset .Params "attr") }}
-Stuff Here
-{{ end }}
+{{ $total := add 1 2 3 4 }}
```
-Could be rewritten as
-
-```go-html-template
-{{ if isset .Params "caption" | or isset .Params "title" | or isset .Params "attr" }}
-Stuff Here
-{{ end }}
-```
+## Methods
-## Context (aka "the dot") {#the-dot}
+Used within a template action and associated with an object, a method takes zero or more arguments and either returns a value or performs an action.
-The most easily overlooked concept to understand about Go Templates is
-that `{{ . }}` always refers to the **current context**.
+The most commonly accessed objects are the [`Page`] and [`Site`] objects. This is a small sampling of the [methods] available to each object.
-- In the top level of your template, this will be the data set made
- available to it.
-- Inside an iteration, however, it will have the value of the
- current item in the loop; i.e., `{{ . }}` will no longer refer to
- the data available to the entire page.
+[`Site`]: /methods/site/
+[`Page`]: /methods/page/
+[methods]: /methods/
-If you need to access page-level data (e.g., page parameters set in front
-matter) from within the loop, you will likely want to do one of the
-following:
+Object|Method|Description
+:--|:--|:--
+`Page`|[`Date`](methods/page/date/)|Returns the date of the given page.
+`Page`|[`Params`](methods/page/params/)|Returns a map of custom parameters as defined in the front matter of the given page.
+`Page`|[`Title`](methods/page/title/)|Returns the title of the given page.
+`Site`|[`Data`](methods/site/data/)|Returns a data structure composed from the files in the data directory.
+`Site`|[`Params`](methods/site/params/)|Returns a map of custom parameters as defined in the site configuration.
+`Site`|[`Title`](methods/site/title/)|Returns the title as defined in the site configuration.
-### 1. Define a variable independent of context
+Chain the method to its object with a dot (`.`) as shown below, remembering that the leading dot represents the [current context].
-The following shows how to define a variable independent of the context.
+[current context]: #current-context
-{{< code file=tags-range-with-page-variable.html >}}
-{{ $title := .Site.Title }}
-<ul>
-{{ range .Params.tags }}
- <li>
- <a href="/tags/{{ . | urlize }}">{{ . }}</a>
- - {{ $title }}
- </li>
-{{ end }}
-</ul>
+{{< code file=layouts/_default/single.html >}}
+{{ .Site.Title }} → My Site Title
+{{ .Page.Title }} → My Page Title
{{< /code >}}
-{{% note %}}
-Notice how once we have entered the loop (i.e. `range`), the value of `{{ . }}` has changed. We have defined a variable outside the loop (`{{ $title }}`) that we've assigned a value so that we have access to the value from within the loop as well.
-{{% /note %}}
+The context passed into most templates is a `Page` object, so this is equivalent to the previous example:
-### 2. Use `$.` to access the global context
+{{< code file=layouts/_default/single.html >}}
+{{ .Site.Title }} → My Site Title
+{{ .Title }} → My Page Title
+{{< /code >}}
-`$` has special significance in your templates. `$` is set to the starting value of `.` ("the dot") by default. This is a [documented feature of Go text/template][dotdoc]. This means you have access to the global context from anywhere. Here is an equivalent example of the preceding code block but now using `$` to grab `.Site.Title` from the global context:
+Some methods take an argument. Separate the argument from the method with a space. For example:
-{{< code file=range-through-tags-w-global.html >}}
-<ul>
-{{ range .Params.tags }}
- <li>
- <a href="/tags/{{ . | urlize }}">{{ . }}</a>
- - {{ $.Site.Title }}
- </li>
-{{ end }}
-</ul>
+{{< code file=layouts/_default/single.html >}}
+{{ $page := .Page.GetPage "/books/les-miserables" }}
+{{ $page.Title }} → Les Misérables
{{< /code >}}
-{{% note %}}
-The built-in magic of `$` would cease to work if someone were to mischievously redefine the special character; e.g. `{{ $ := .Site }}`. *Don't do it.* You may, of course, recover from this mischief by using `{{ $ := . }}` in a global context to reset `$` to its default value.
-{{% /note %}}
+## Comments
-## Whitespace
+{{% note %}}
+Do not attempt to use HTML comment delimiters to comment out template code.
-Go 1.6 includes the ability to trim the whitespace from either side of a Go tag by including a hyphen (`-`) and space immediately beside the corresponding `{{` or `}}` delimiter.
+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 %}}
-For instance, the following Go Template will include the newlines and horizontal tab in its HTML output:
+Template comments are similar to template actions. Paired opening and closing braces represent the beginning and end of a comment. For example:
-```go-html-template
-<div>
- {{ .Title }}
-</div>
+```text
+{{/* This is an inline comment. */}}
+{{- /* This is an inline comment with adjacent whitespace removed. */ -}}
```
-Which will output:
+Code within a comment is not parsed, executed, or displayed. Comments may be inline, as shown above, or in block form:
-```html
-<div>
- Hello, World!
-</div>
+```text
+{{/*
+This is a block comment.
+*/}}
+
+{{- /*
+This is a block comment with
+adjacent whitespace removed.
+*/ -}}
```
-Leveraging the `-` in the following example will remove the extra white space surrounding the `.Title` variable and remove the newline:
+You may not nest one comment inside of another.
-```go-html-template
-<div>
- {{- .Title -}}
-</div>
-```
+To render an HTML comment, pass a string through the [`safeHTML`] template function. For example:
-Which then outputs:
+[`safeHTML`]: /functions/safe/html
-```html
-<div>Hello, World!</div>
+```go-html-template
+{{ "<!-- I am an HTML comment. -->" | safeHTML }}
+{{ printf "<!-- This is the %s site. -->" .Site.Title | safeHTML }}
```
-Go considers the following characters _whitespace_:
+## Include
-* space
-* horizontal tab
-* carriage return
-* newline
+Use the [`template`] function to include one or more of Hugo's [embedded templates]:
-## Comments
+[embedded templates]: /templates/embedded/
-In order to keep your templates organized and share information throughout your team, you may want to add comments to your templates. There are two ways to do that with Hugo.
+```go-html-template
+{{ template "_internal/google_analytics.html" . }}
+{{ template "_internal/opengraph" . }}
+{{ template "_internal/pagination.html" . }}
+{{ template "_internal/schema.html" . }}
+{{ template "_internal/twitter_cards.html" . }}
+```
-### Go templates comments
+[`partial`]: /functions/partials/include/
+[`partialCached`]: /functions/partials/includecached/
+[`template`]: functions/go-template/template/
-Go Templates support `{{/*` and `*/}}` to open and close a comment block. Nothing within that block will be rendered.
+Use the [`partial`] or [`partialCached`] function to include one or more [partial templates]:
-For example:
+[partial templates]: /templates/partials
```go-html-template
-Bonsoir, {{/* {{ add 0 + 2 }} */}}Eliott.
+{{ partial "breadcrumbs.html" . }}
+{{ partialCached "css.html" . }}
```
-Will render `Bonsoir, Eliott.`, and not care about the syntax error (`add 0 + 2`) in the comment block.
+Create your partial templates in the layouts/partials directory.
-### HTML comments
+{{% note %}}
+In the examples above, note that we are passing the current context (the dot) to each of the templates.
+{{% /note %}}
-You can add html comments by piping a string HTML code comment to `safeHTML`.
+## Examples
-For example:
+This limited set of contrived examples demonstrates some of concepts described above. Please see the [functions], [methods], and [templates] documentation for specific examples.
-```go-html-template
-{{ "<!-- This is an HTML comment -->" | safeHTML }}
-```
+[templates]: /templates/
-If you need variables to construct such HTML comments, just pipe `printf` to `safeHTML`.
+### Conditional blocks
-For example:
+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
-{{ printf "<!-- Our website is named: %s -->" .Site.Title | safeHTML }}
+{{ $var := 42 }}
+{{ if eq $var 6 }}
+ {{ print "var is 6" }}
+{{ else if eq $var 7 }}
+ {{ print "var is 7" }}
+{{ else if eq $var 42 }}
+ {{ print "var is 42" }}
+{{ else }}
+ {{ print "var is something else" }}
+{{ end }}
```
-#### HTML comments containing Go templates
+### Logical operators
-HTML comments are by default stripped, but their content is still evaluated. That means that although the HTML comment will never render any content to the final HTML pages, code contained within the comment may fail the build process.
+See documentation for [`and`] and [`or`].
-{{% note %}}
-Do **not** try to comment out Go Template code using HTML comments.
-{{% /note %}}
+[`and`]: /functions/go-template/and
+[`or`]: /functions/go-template/or
```go-html-template
-<!-- {{ $author := "Emma Goldman" }} was a great woman. -->
-{{ $author }}
-```
+{{ $v1 := true }}
+{{ $v2 := false }}
+{{ $v3 := false }}
+{{ $result := false }}
-The templating engine will strip the content within the HTML comment, but will first evaluate any Go Template code if present within. So the above example will render `Emma Goldman`, as the `$author` variable got evaluated in the HTML comment. But the build would have failed if that code in the HTML comment had an error.
-
-## Hugo parameters
-
-Hugo provides the option of passing values to your template layer through your [site configuration][config] (i.e. for site-wide values) or through the metadata of each specific piece of content (i.e. the [front matter]). You can define any values of any type and use them however you want in your templates, as long as the values are supported by the [front matter format](/content-management/front-matter#front-matter-formats).
+{{ if and $v1 $v2 $v3 }}
+ {{ $result = true }}
+{{ end }}
+{{ $result }} → false
-## Use content (`Page`) parameters
+{{ if or $v1 $v2 $v3 }}
+ {{ $result = true }}
+{{ end }}
+{{ $result }} → true
+```
-You can provide variables to be used by templates in individual content's [front matter].
+### Loops
-An example of this is used in the Hugo docs. Most of the pages benefit from having the table of contents provided, but sometimes the table of contents doesn't make a lot of sense. We've defined a `notoc` variable in our front matter that will prevent a table of contents from rendering when specifically set to `true`.
+See documentation for [`range`], [`else`], and [`end`].
-Here is the example front matter:
+[`range`]: /functions/go-template/range/
-{{< code-toggle file=content/example.md fm=true >}}
-title: Example
-notoc: true
-{{< /code-toggle >}}
-
-Here is an example of corresponding code that could be used inside a `toc.html` [partial template][partials]:
-
-{{< code file=layouts/partials/toc.html >}}
-{{ if not .Params.notoc }}
-<aside>
- <header>
- <a href="#{{ .Title | urlize }}">
- <h3>{{ .Title }}</h3>
- </a>
- </header>
- {{ .TableOfContents }}
-</aside>
-<a href="#" id="toc-toggle"></a>
+```go-html-template
+{{ $s := slice "foo" "bar" "baz" }}
+{{ range $s }}
+ <p>{{ . }}</p>
+{{ else }}
+ <p>The collection is empty</p>
{{ end }}
-{{< /code >}}
+```
-We want the *default* behavior to be for pages to include a TOC unless otherwise specified. This template checks to make sure that the `notoc:` field in this page's front matter is not `true`.
+Use the [`seq`] function to loop a specified number of times:
-## Use site configuration parameters
+[`seq`]: /functions/collections/seq
-You can arbitrarily define as many site-level parameters as you want in your [site's configuration file][config]. These parameters are globally available in your templates.
+```go-html-template
+{{ $total := 0 }}
+{{ range seq 4 }}
+ {{ $total = add $total . }}
+{{ end }}
+{{ $total }} → 10
+```
-For instance, you might declare the following:
+### Rebind context
-{{< code-toggle file=hugo >}}
-params:
- copyrighthtml: "Copyright &#xA9; 2017 John Doe. All Rights Reserved."
- twitteruser: "spf13"
- sidebarrecentlimit: 5
-{{< /code >}}
+See documentation for [`with`], [`else`], and [`end`].
-Within a footer layout, you might then declare a `<footer>` that is only rendered if the `copyrighthtml` parameter is provided. If it *is* provided, you will then need to declare the string is safe to use via the [`safeHTML`] function so that the HTML entity is not escaped again. This would let you easily update just your top-level configuration file each January 1st, instead of hunting through your templates.
+[`with`]: /functions/go-template/with/
```go-html-template
-{{ if .Site.Params.copyrighthtml }}
- <footer>
- <div class="text-center">{{ .Site.Params.CopyrightHTML | safeHTML }}</div>
- </footer>
+{{ $var := "foo" }}
+{{ with $var }}
+ {{ . }} → foo
+{{ else }}
+ {{ print "var is falsy" }}
{{ end }}
```
-An alternative way of writing the "`if`" and then referencing the same value is to use [`with`] instead. `with` rebinds the context (`.`) within its scope and skips the block if the variable is absent:
+### Access site parameters
-{{< code file=layouts/partials/twitter.html >}}
-{{ with .Site.Params.twitteruser }}
- <div>
- <a href="https://twitter.com/{{ . }}" rel="author">
- <img src="/images/twitter.png" width="48" height="48" title="Twitter: {{ . }}" alt="Twitter"></a>
- </div>
-{{ end }}
-{{< /code >}}
+See documentation for the [`Params`](/methods/site/params/) method on a `Site` object.
+
+With this site configuration:
+
+{{< code-toggle file=hugo >}}
+title = 'ABC Widgets'
+baseURL = 'https://example.org'
+[params]
+ subtitle = 'The Best Widgets on Earth'
+ copyright-year = '2023'
+ [params.author]
+ email = '[email protected]'
+ name = 'John Smith'
+ [params.layouts]
+ rfc_1123 = 'Mon, 02 Jan 2006 15:04:05 MST'
+ rfc_3339 = '2006-01-02T15:04:05-07:00'
+{{< /code-toggle >}}
-Finally, you can pull "magic constants" out of your layouts as well. The following uses the [`first`] function, as well as the [`.RelPermalink`][relpermalink] page variable and the [`.Site.Pages`][sitevars] site variable.
+Access the custom site parameters by chaining the identifiers:
```go-html-template
-<nav>
- <h1>Recent Posts</h1>
- <ul>
- {{- range first .Site.Params.SidebarRecentLimit .Site.Pages -}}
- <li><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></li>
- {{- end -}}
- </ul>
-</nav>
+{{ .Site.Params.subtitle }} → The Best Widgets on Earth
+{{ .Site.Params.author.name }} → John Smith
+
+{{ $layout := .Site.Params.layouts.rfc_1123 }}
+{{ .Site.Lastmod.Format $layout }} → Tue, 17 Oct 2023 13:21:02 PDT
```
-## Example: show future events
+### Access page parameters
-Given the following content structure and [front matter]:
+See documentation for the [`Params`](/methods/page/params/) method on a `Page` object.
-```text
-content/
-└── events/
- ├── event-1.md
- ├── event-2.md
- └── event-3.md
-```
+With this front matter:
-{{< code-toggle file=content/events/event-1.md >}}
-title = 'Event 1'
-date = 2021-12-06T10:37:16-08:00
-draft = false
-start_date = 2021-12-05T09:00:00-08:00
-end_date = 2021-12-05T11:00:00-08:00
+{{< code-toggle file=content/news/annual-conference.md >}}
+title = 'Annual conference'
+date = 2023-10-17T15:11:37-07:00
+[params]
+display_related = true
+[params.author]
+ email = '[email protected]'
+ name = 'John Smith'
{{< /code-toggle >}}
-This [partial template][partials] renders future events:
-
-{{< code file=layouts/partials/future-events.html >}}
-<h2>Future Events</h2>
-<ul>
- {{ range where site.RegularPages "Type" "events" }}
- {{ if gt (.Params.start_date | time.AsTime) now }}
- {{ $startDate := .Params.start_date | time.Format ":date_medium" }}
- <li>
- <a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a> - {{ $startDate }}
- </li>
- {{ end }}
- {{ end }}
-</ul>
-{{< /code >}}
+Access the custom page parameters by chaining the identifiers:
-If you restrict front matter to the TOML format, and omit quotation marks surrounding date fields, you can perform date comparisons without casting.
-
-{{< code file=layouts/partials/future-events.html >}}
-<h2>Future Events</h2>
-<ul>
- {{ range where (where site.RegularPages "Type" "events") "Params.start_date" "gt" now }}
- {{ $startDate := .Params.start_date | time.Format ":date_medium" }}
- <li>
- <a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a> - {{ $startDate }}
- </li>
- {{ end }}
-</ul>
-{{< /code >}}
-
-[`first`]: /functions/collections/first
-[`index`]: /functions/collections/indexfunction
-[`isset`]: /functions/collections/isset
-[config]: /getting-started/configuration
-[dotdoc]: https://golang.org/pkg/text/template/#hdr-Variables
-[front matter]: /content-management/front-matter
-[functions]: /functions
-[identifier]: /getting-started/glossary/#identifier
-[internal templates]: /templates/internal
-[math]: /functions/math
-[pagevars]: /variables/page
-[param]: /methods/page/param
-[partials]: /templates/partials
-[relpermalink]: /variables/page
-[`safehtml`]: /functions/safe/html
-[sitevars]: /variables/site
-[variables]: /variables
-[`with`]: /functions/go-template/with
+```go-html-template
+{{ .Params.display_related }} → true
+{{ .Params.author.name }} → John Smith
+```
diff --git a/content/en/templates/lists/index.md b/content/en/templates/lists/index.md
index c26174974..e9b1dc56b 100644
--- a/content/en/templates/lists/index.md
+++ b/content/en/templates/lists/index.md
@@ -34,25 +34,9 @@ The idea of a list page comes from the [hierarchical mental model of the web][me
[![Image demonstrating a hierarchical website sitemap.](site-hierarchy.svg)](site-hierarchy.svg)
-## List defaults
-
-### Default templates
-
-Since section lists and taxonomy lists (N.B., *not* [taxonomy terms lists][taxterms]) are both *lists* with regards to their templates, both have the same terminating default of `_default/list.html` or `themes/<THEME>/layouts/_default/list.html` in their lookup order. In addition, both [section lists][sectiontemps] and [taxonomy lists][taxlists] have their own default list templates in `_default`.
-
-See [Template Lookup Order](/templates/lookup-order/) for the complete reference.
-
## Add content and front matter to list pages
-Since v0.18, [everything in Hugo is a `Page`][bepsays]. This means list pages and the homepage can have associated content files (i.e. `_index.md`) that contain page metadata (i.e., front matter) and content.
-
-This new model allows you to include list-specific front matter via `.Params` and also means that list templates (e.g., `layouts/_default/list.html`) have access to all [page variables][pagevars].
-
-{{% note %}}
-It is important to note that all `_index.md` content files will render according to a *list* template and not according to a [single page template](/templates/single-page-templates/).
-{{% /note %}}
-
-### Example project directory
+Add content and front matter to list pages by creating an _index.md file for `home`, `section`, `taxonomy`, and `term` pages.
The following is an example of a typical Hugo project directory's content:
@@ -93,7 +77,7 @@ You can now access this `_index.md`'s' content in your list template:
<header>
<h1>{{ .Title }}</h1>
</header>
- <!-- "{{ .Content }}" pulls from the markdown content of the corresponding _index.md -->
+ <!-- "{{ .Content }}" pulls from the Markdown content of the corresponding _index.md -->
{{ .Content }}
</article>
<ul>
@@ -152,7 +136,13 @@ Using this same `layouts/_default/list.html` template and applying it to the `qu
{{< /code >}}
{{% note %}}
-The default behavior of Hugo is to pluralize list titles; hence the inflection of the `quote` section to "Quotes" when called with the `.Title` [page variable](/variables/page/). You can change this via the `pluralizeListTitles` directive in your [site configuration](/getting-started/configuration/).
+By default, Hugo capitalizes and pluralizes automatic list titles including section, taxonomy, and term pages. You can disable these transformations by setting [`capitalizeListTitles`] and [`pluralizeListTitles`] in your site configuration.
+
+You can change the capitalization style in your site configuration to one of `ap`, `chicago`, `go`, `firstupper`, or `none`. See [details].
+
+[`capitalizeListTitles`]: /getting-started/configuration/#capitalizelisttitles
+[`pluralizeListTitles`]: /getting-started/configuration/#pluralizelisttitles
+[details]: /getting-started/configuration/#configure-title-case
{{% /note %}}
## Example list templates
@@ -203,10 +193,10 @@ By default, Hugo sorts page collections by:
3. Page [linkTitle], falling back to page [title]
4. Page file path if the page is backed by a file
-[date]: /methods/page/date
-[weight]: /methods/page/weight
-[linkTitle]: /methods/page/linktitle
-[title]: /methods/page/title
+[date]: /methods/page/date/
+[weight]: /methods/page/weight/
+[linkTitle]: /methods/page/linktitle/
+[title]: /methods/page/title/
Change the sort order using any of the methods below.
@@ -235,18 +225,16 @@ See the documentation on [`where`] and
[getpage]: /methods/page/getpage/
[homepage]: /templates/homepage/
[mentalmodel]: https://webstyleguide.com/wsg3/3-information-architecture/3-site-structure.html
-[pagevars]: /variables/page/
[partials]: /templates/partials/
[RSS 2.0]: https://cyber.harvard.edu/rss/rss.html
[rss]: /templates/rss/
[sections]: /content-management/sections/
[sectiontemps]: /templates/section-templates/
-[sitevars]: /variables/site/
-[taxlists]: /templates/taxonomy-templates/#taxonomy-list-templates
-[taxterms]: /templates/taxonomy-templates/#taxonomy-terms-templates
-[taxvars]: /variables/taxonomy/
+[taxlists]: /templates/taxonomy-templates/#taxonomy-templates
+[taxterms]: /templates/taxonomy-templates/#term-templates
+[taxvars]: /methods/taxonomy/
[views]: /templates/views/
-[`where`]: /functions/collections/where
+[`where`]: /functions/collections/where/
[`first`]: /functions/collections/first/
-[main sections]: /methods/site/mainsections
-[`time.Format`]: /functions/time/format
+[main sections]: /methods/site/mainsections/
+[`time.Format`]: /functions/time/format/
diff --git a/content/en/templates/menu-templates.md b/content/en/templates/menu-templates.md
index 8dab65abf..403affe3c 100644
--- a/content/en/templates/menu-templates.md
+++ b/content/en/templates/menu-templates.md
@@ -1,6 +1,6 @@
---
title: Menu templates
-description: Use menu variables and methods in your templates to render a menu.
+description: Create templates to render one or more menus.
categories: [templates]
keywords: [lists,sections,menus]
menu:
@@ -14,7 +14,7 @@ aliases: [/templates/menus/]
## Overview
-After [defining menu entries], use [menu variables and methods] to render a menu.
+After [defining menu entries], use [menu methods] to render a menu.
Three factors determine how to render a menu:
@@ -82,7 +82,7 @@ Call the partial above, passing a menu ID and the current page in context.
## Page references
-Regardless of how you [define menu entries], an entry associated with a page has access to page variables and methods.
+Regardless of how you [define menu entries], an entry associated with a page has access to page context.
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.
@@ -128,5 +128,5 @@ Hugo provides two methods to localize your menu entries. See [multilingual].
[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 variables and methods]: /variables/menu-entry/
+[menu and methods]: /methods/menu/
[multilingual]: /content-management/multilingual/#menus
diff --git a/content/en/templates/output-formats.md b/content/en/templates/output-formats.md
index 0e95f3ffb..ee4dbf0b6 100644
--- a/content/en/templates/output-formats.md
+++ b/content/en/templates/output-formats.md
@@ -63,7 +63,7 @@ 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" "name" "mediaType" "path" "baseName" "rel" "protocol" "isPlainText" "isHTML" "noUgly" "permalinkable" >}}
+{{< 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.
@@ -83,40 +83,56 @@ The above example is fictional, but if used for the homepage on a site with `bas
### Configure output formats
-The following is the full list of configuration options for output formats and their default values:
+Use these parameters when configuring an output format:
-mediaType
-: this must match the `Type` of a defined media type.
+baseName
+: (`string`) The base name of the published file. Default is `index`.
-path
-: sub path to save the output files.
+isHTML
+: (`bool`) If `true`, classifies 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`.
-baseName
-: the base file name for the list file names (homepage, etc.). **Default:** `index`.
+isPlainText
+: (`bool`) If `true`, Hugo parses templates for this output format with Go's [text/template] package instead of the [html/template] package. Default is `false`.
-rel
-: can be used to create `rel` values in `link` tags. **Default:** `alternate`.
+[html/template]: https://pkg.go.dev/html/template
+[text/template]: https://pkg.go.dev/text/template
-protocol
-: will replace the "http://" or "https://" in your `baseURL` for this output format.
+mediaType
+: (`string`) The [media type] of the published file. This must match a defined media type, either [built-in](#media-types) or custom.
-isPlainText
-: use Go's plain text templates parser for the templates. **Default:** `false`.
+[media type]: https://en.wikipedia.org/wiki/Media_type
-isHTML
-: used in situations only relevant for `HTML`-type formats; e.g., page aliases. **Default:** `false`.
+notAlternative
+: (`bool`) If `true`, excludes this output format from the values returned by the [`AlternativeOutputFormats`] method on a `Page` object. Default is `false`.
+
+[`AlternativeOutputFormats`]: /methods/page/alternativeoutputformats/
noUgly
-: used to turn off ugly URLs If `uglyURLs` is set to `true` in your site. **Default:** `false`.
+: (`bool`) If `true`, disables ugly URLs for this output format when `uglyURLs` is `true` in your site configuration. Default is `false`.
-notAlternative
-: enable if it doesn't make sense to include this format in an `AlternativeOutputFormats` format listing on `Page` (e.g., with `CSS`). Note that we use the term _alternative_ and not _alternate_ here, as it does not necessarily replace the other format. **Default:** `false`.
+path
+: (`string`) The path to the directory containing the published files, relative to the root of the publish directory.
permalinkable
-: make `.Permalink` and `.RelPermalink` return the rendering Output Format rather than main ([see below](#link-to-output-formats)). This is enabled by default for `HTML` and `AMP`. **Default:** `false`.
+: (`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`) If `true`, files will be published to the root of the publish directory. Default is `false`.
+
+ugly
+: (`bool`) If `true`, enables uglyURLs for this output format when `uglyURLs` is `false` in your site configuration. Default is `false`.
weight
-: Setting this to a non-zero value will be used as the first sort criteria.
+: (`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
@@ -125,7 +141,7 @@ system.
### Default output formats
-Every `Page` has a [`Kind`][page_kinds] attribute, and the default Output
+Every `Page` has a [`Kind`] attribute, and the default Output
Formats are set based on that.
{{< code-toggle config=outputs />}}
@@ -162,7 +178,10 @@ outputs:
## List output formats
-Each `Page` has both an `.OutputFormats` (all formats, including the current) and an `.AlternativeOutputFormats` variable, the latter of which is useful for creating a `link rel` list in your site's `<head>`:
+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 `<head>`:
+
+[`OutputFormats`]: /methods/page/outputformats
+[`AlternativeOutputFormats`]: /methods/page/alternativeoutputformats
```go-html-template
{{ range .AlternativeOutputFormats -}}
@@ -172,7 +191,10 @@ Each `Page` has both an `.OutputFormats` (all formats, including the current) an
## Link to output formats
-`.Permalink` and `.RelPermalink` on `Page` will return the first output format defined for that page (usually `HTML` if nothing else is defined). This is regardless of the template file they are being called from.
+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
@@ -193,7 +215,7 @@ In order for them to return the output format of the current template file inste
{{ end }}
```
-From content files, you can use the [`ref` or `relref` shortcodes](/content-management/shortcodes/#ref-and-relref):
+From content files, you can use the `ref` or `relref` shortcodes:
```go-html-template
[Neat]({{</* ref "blog/neat.md" "amp" */>}})
@@ -225,4 +247,4 @@ The partial below is a plain text template . The output format is `csv`, and sin
[lookup order]: /templates/lookup-order/
[media type]: https://en.wikipedia.org/wiki/Media_type
[partials]: /templates/partials/
-[page_kinds]: /templates/section-templates/#page-kinds
+[`kind`]: /methods/page/kind/
diff --git a/content/en/templates/pagination.md b/content/en/templates/pagination.md
index 70a9df4cf..36dea0c8e 100644
--- a/content/en/templates/pagination.md
+++ b/content/en/templates/pagination.md
@@ -60,9 +60,16 @@ It is also possible to use the `GroupBy` functions in combination with paginatio
## Build the navigation
-The `.Paginator` contains enough information to build a paginator interface.
+{{% 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" . }}`
+
+[`partial`]: /functions/partials/include/
+[source code]: {{% eturl pagination %}}
+{{% /note %}}
-The easiest way to add this to your pages is to include the built-in template (with `Bootstrap`-compatible styles):
+The easiest way to add this to your pages is to include the embedded template:
```go-html-template
{{ template "_internal/pagination.html" . }}
@@ -151,4 +158,4 @@ The pages are built on the following form (`BLANK` means no value):
[`after`]: /functions/collections/after/
[configuration]: /getting-started/configuration/
[lists]: /templates/lists/
-[`where`]: /functions/collections/where
+[`where`]: /functions/collections/where/
diff --git a/content/en/templates/partials.md b/content/en/templates/partials.md
index afbad1a6c..34d0a9dda 100644
--- a/content/en/templates/partials.md
+++ b/content/en/templates/partials.md
@@ -68,7 +68,7 @@ As shown in the above example directory structure, you can nest your directories
The second argument in a partial call is the variable being passed down. The above examples are passing the `.`, which tells the template receiving the partial to apply the current [context][context].
-This means the partial will *only* be able to access those variables. The partial is isolated and *has no access to the outer scope*. From within the partial, `$.Var` is equivalent to `.Var`.
+This means the partial will *only* be able to access those variables. The partial is isolated and cannot access the outer scope. From within the partial, `$.Var` is equivalent to `.Var`.
## Returning a value from a partial
@@ -177,6 +177,6 @@ The following `footer.html` partial template is used for [spf13.com](https://spf
[customize]: /hugo-modules/theme-components/
[listtemps]: /templates/lists/
[lookup order]: /templates/lookup-order/
-[partialcached]: /functions/partials/includecached
+[partialcached]: /functions/partials/includecached/
[singletemps]: /templates/single-page-templates/
[themes]: /themes/
diff --git a/content/en/templates/render-hooks.md b/content/en/templates/render-hooks.md
deleted file mode 100644
index f91cb6b6e..000000000
--- a/content/en/templates/render-hooks.md
+++ /dev/null
@@ -1,183 +0,0 @@
----
-title: Markdown render hooks
-linkTitle: Render hooks
-description: Render Hooks allow custom templates to override markdown rendering functionality.
-categories: [templates]
-keywords: [markdown]
-toc: true
-menu:
- docs:
- parent: templates
- weight: 200
-weight: 200
----
-
-Note that this is only supported with the [Goldmark](/getting-started/configuration-markup#goldmark) renderer.
-
-You can override certain parts of the default Markdown rendering to HTML by creating templates with base names `render-{kind}` in `layouts/_default/_markup`.
-
-You can also create type/section specific hooks in `layouts/[type/section]/_markup`, e.g.: `layouts/blog/_markup`.
-
-The hook kinds currently supported are:
-
-* `image`
-* `link`
-* `heading`
-* `codeblock`{{< new-in 0.93.0 >}}
-
-You can define [Output-Format-](/templates/output-formats) and [language-](/content-management/multilingual/)specific templates if needed. Your `layouts` folder may look like this:
-
-```text
-layouts/
-└── _default/
- └── _markup/
- ├── render-codeblock-bash.html
- ├── render-codeblock.html
- ├── render-heading.html
- ├── render-image.html
- ├── render-image.rss.xml
- └── render-link.html
-```
-
-Some use cases for the above:
-
-* Resolve link references using `.GetPage`. This would make links portable as you could translate `./my-post.md` (and similar constructs that would work on GitHub) into `/blog/2019/01/01/my-post/` etc.
-* Add `target=_blank` to external links.
-* Resolve and [process](/content-management/image-processing/) images.
-* Add [header links](https://remysharp.com/2014/08/08/automatic-permalinks-for-blog-posts).
-
-## Render hooks for headings, links and images
-
-### Context passed to `render-link` and `render-image`
-
-The `render-link` and `render-image` templates will receive this context:
-
-Page
-: The [Page](/variables/page/) being rendered.
-
-Destination
-: The URL.
-
-Title
-: The title attribute.
-
-Text
-: The rendered (HTML) link text.
-
-PlainText
-: The plain variant of the above.
-
-### Context passed to `render-heading`
-
-The `render-heading` template will receive this context:
-
-Page
-: The [Page](/variables/page/) being rendered.
-
-Level
-: The header level (1--6)
-
-Anchor
-: An auto-generated html id unique to the header within the page
-
-Text
-: The rendered (HTML) text.
-
-PlainText
-: The plain variant of the above.
-
-Attributes (map)
-: A map of attributes (e.g. `id`, `class`). Note that this will currently always be empty for links.
-
-The `render-image` templates will also receive:
-
-IsBlock {{< new-in 0.108.0 >}}
-: Returns true if this is a standalone image and the configuration option [markup.goldmark.parser.wrapStandAloneImageWithinParagraph](/getting-started/configuration-markup/#goldmark) is disabled.
-
-Ordinal {{< new-in 0.108.0 >}}
-: Zero-based ordinal for all the images in the current document.
-
-### Link with title markdown example
-
-```md
-[Text](https://www.gohugo.io "Title")
-```
-
-Here is a code example for how the render-link.html template could look:
-
-{{< code file=layouts/_default/_markup/render-link.html >}}
-<a href="{{ .Destination | safeURL }}"{{ with .Title }} title="{{ . }}"{{ end }}{{ if strings.HasPrefix .Destination "http" }} target="_blank" rel="noopener"{{ end }}>{{ .Text | safeHTML }}</a>
-{{< /code >}}
-
-### Image markdown example
-
-```md
-![Text](https://gohugo.io/images/hugo-logo-wide.svg "Title")
-```
-
-Here is a code example for how the render-image.html template could look:
-
-{{< code file=layouts/_default/_markup/render-image.html >}}
-<p class="md__image">
- <img src="{{ .Destination | safeURL }}" alt="{{ .Text }}" {{ with .Title }} title="{{ . }}"{{ end }} />
-</p>
-{{< /code >}}
-
-### Heading link example
-
-Given this template file
-
-{{< code file=layouts/_default/_markup/render-heading.html >}}
-<h{{ .Level }} id="{{ .Anchor }}">{{ .Text | safeHTML }} <a href="#{{ .Anchor | safeURL }}">¶</a></h{{ .Level }}>
-{{< /code >}}
-
-And this markdown
-
-```md
-### Section A
-```
-
-The rendered html will be
-
-```html
-<h3 id="section-a">Section A <a href="#section-a">¶</a></h3>
-```
-
-## Render hooks for code blocks
-
-{{< new-in 0.93.0 >}}
-
-You can add a hook template for either all code blocks or for a specific type/language (`bash` in the example below):
-
-```goat { class="black f7" }
-layouts
-└── _default
- └── _markup
- └── render-codeblock.html
- └── render-codeblock-bash.html
-```
-
-The default behavior for these code blocks is to do [Code Highlighting](/content-management/syntax-highlighting/#highlighting-in-code-fences), but since you can pass attributes to these code blocks, they can be used for almost anything. One example would be the built-in [GoAT Diagrams](/content-management/diagrams/#goat-diagrams-ascii) or this [Mermaid Diagram Code Block Hook](/content-management/diagrams/#mermaid-diagrams) example.
-
-The context (the ".") you receive in a code block template contains:
-
-Type (string)
-: The type of code block. This will be the programming language, e.g. `bash`, when doing code highlighting.
-
-Attributes (map)
-: Attributes passed in from Markdown (e.g. `{ attrName1=attrValue1 attrName2="attr Value 2" }`).
-
-Options (map)
-: Chroma highlighting processing options. This will only be filled if `Type` is a known [Chroma Lexer](/content-management/syntax-highlighting/#list-of-chroma-highlighting-languages).
-
-Inner (string)
-: The text between the code fences.
-
-Ordinal (integer)
-: Zero-based ordinal for all code blocks in the current document.
-
-Page
-: The owning `Page`.
-
-Position
-: Useful in error logging as it prints the file name and position (linenumber, column), e.g. `{{ errorf "error in code block: %s" .Position }}`.
diff --git a/content/en/templates/robots.md b/content/en/templates/robots.md
index 0efd85ba2..63edb1ca8 100644
--- a/content/en/templates/robots.md
+++ b/content/en/templates/robots.md
@@ -18,7 +18,9 @@ To generate a robots.txt file from a template, change the [site configuration]:
enableRobotsTXT = true
{{< /code-toggle >}}
-By default, Hugo generates robots.txt using an [internal template][internal].
+By default, Hugo generates robots.txt using an [embedded template].
+
+[embedded template]: {{% eturl robots %}}
```text
User-agent: *
@@ -56,4 +58,3 @@ Remember that Hugo copies everything in the [static directory][static] to the ro
{{% /note %}}
[site configuration]: /getting-started/configuration/
-[internal]: https://github.com/gohugoio/hugo/blob/master/tpl/tplimpl/embedded/templates/_default/robots.txt
diff --git a/content/en/templates/rss.md b/content/en/templates/rss.md
index 9a2ce9b3c..635a62499 100644
--- a/content/en/templates/rss.md
+++ b/content/en/templates/rss.md
@@ -1,6 +1,6 @@
---
title: RSS templates
-description: Use the built-in RSS template, or create your own.
+description: Use the embedded RSS template, or create your own.
categories: [templates]
keywords: [rss,xml,templates]
menu:
@@ -25,6 +25,8 @@ term = ['html']
To disable feed generation for all [page kinds]:
+[page kinds]: /getting-started/glossary/#page-kind
+
{{< code-toggle file=hugo >}}
disableKinds = ['rss']
{{< /code-toggle >}}
@@ -65,7 +67,10 @@ Hugo will render this to:
## Custom templates
-Override Hugo's [built-in RSS template] by creating one or more of your own, following the naming conventions as shown in the [template lookup order table].
+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]: #template-lookup-order
For example, to use different templates for home, section, taxonomy, and term pages:
@@ -80,10 +85,6 @@ layouts/
RSS templates receive the `.Page` and `.Site` objects in context.
-[built-in RSS template]: https://github.com/gohugoio/hugo/blob/master/tpl/tplimpl/embedded/templates/_default/rss.xml
-[page kinds]: /getting-started/glossary/#page-kind
-[template lookup order table]: #template-lookup-order
-
## Template lookup order
The table below shows the RSS template lookup order for the different page kinds. The first listing shows the lookup order when running with a theme (`demoTheme`).
diff --git a/content/en/templates/section-templates.md b/content/en/templates/section-templates.md
index 42eb12bec..71f41f5e4 100644
--- a/content/en/templates/section-templates.md
+++ b/content/en/templates/section-templates.md
@@ -1,7 +1,7 @@
---
title: Section page templates
linkTitle: Section templates
-description: Templates used for section pages are **lists** and therefore have all the variables and methods available to list pages.
+description: Use section templates to list members of a section.
categories: [templates]
keywords: [lists,sections,templates]
menu:
@@ -21,26 +21,6 @@ To effectively leverage section page templates, you should first understand Hugo
See [Template Lookup](/templates/lookup-order/).
-## Page kinds
-
-Every `Page` in Hugo has a `.Kind` attribute.
-
-{{% include "content-management/_common/page-kinds.md" %}}
-
-## `.Site.GetPage` with sections
-
-`Kind` can easily be combined with the [`where`] function in your templates to create kind-specific lists of content. This method is ideal for creating lists, but there are times where you may want to fetch just the index page of a single section via the section's path.
-
-The [`.GetPage` function][getpage] looks up an index page of a given `Kind` and `path`.
-
-You can call `.Site.GetPage` with two arguments: `kind` (one of the valid values
-of `Kind` from above) and `kind value`.
-
-Examples:
-
-- `{{ .Site.GetPage "section" "posts" }}`
-- `{{ .Site.GetPage "page" "search" }}`
-
## Example: creating a default section template
{{< code file=layouts/_default/section.html >}}
@@ -69,11 +49,11 @@ The `.Site.GetPage` example that follows assumes the following project directory
.
└── content
├── blog
- │ ├── _index.md # "title: My Hugo Blog" in the front matter
+ │ ├── _index.md <-- title: My Hugo Blog
│ ├── post-1.md
│ ├── post-2.md
│ └── post-3.md
- └── events #Note there is no _index.md file in "events"
+ └── events
├── event-1.md
└── event-2.md
```
@@ -81,7 +61,7 @@ The `.Site.GetPage` example that follows assumes the following project directory
`.Site.GetPage` will return `nil` if no `_index.md` page is found. Therefore, if `content/blog/_index.md` does not exist, the template will output the section name:
```go-html-template
-<h1>{{ with .Site.GetPage "section" "blog" }}{{ .Title }}{{ end }}</h1>
+<h1>{{ with .Site.GetPage "/blog" }}{{ .Title }}{{ end }}</h1>
```
Since `blog` has a section index page with front matter at `content/blog/_index.md`, the above code will return the following result:
@@ -93,7 +73,7 @@ Since `blog` has a section index page with front matter at `content/blog/_index.
If we try the same code with the `events` section, however, Hugo will default to the section title because there is no `content/events/_index.md` from which to pull content and front matter:
```go-html-template
-<h1>{{ with .Site.GetPage "section" "events" }}{{ .Title }}{{ end }}</h1>
+<h1>{{ with .Site.GetPage "/events" }}{{ .Title }}{{ end }}</h1>
```
Which then returns the following:
@@ -103,8 +83,8 @@ Which then returns the following:
```
[contentorg]: /content-management/organization/
-[getpage]: /methods/page/getpage
+[getpage]: /methods/page/getpage/
[lists]: /templates/lists/
[lookup]: /templates/lookup-order/
-[`where`]: /functions/collections/where
+[`where`]: /functions/collections/where/
[sections]: /content-management/sections/
diff --git a/content/en/templates/shortcode-templates.md b/content/en/templates/shortcode-templates.md
index 6e3d968cf..3c8e1d213 100644
--- a/content/en/templates/shortcode-templates.md
+++ b/content/en/templates/shortcode-templates.md
@@ -1,7 +1,7 @@
---
title: Create your own shortcodes
linkTitle: Shortcode templates
-description: You can extend Hugo's built-in shortcodes by creating your own using the same templating syntax as that for single and list pages.
+description: You can extend Hugo's embedded shortcodes by creating your own using the same templating syntax as that for single and list pages.
categories: [templates]
keywords: [shortcodes,templates]
menu:
@@ -16,18 +16,18 @@ toc: true
Shortcodes are a means to consolidate templating into small, reusable snippets that you can embed directly inside your content.
{{% note %}}
-Hugo also ships with built-in shortcodes for common use cases. (See [Content Management: Shortcodes](/content-management/shortcodes/).)
+Hugo also ships with embedded shortcodes for common use cases. (See [Content Management: Shortcodes](/content-management/shortcodes/).)
{{% /note %}}
## Create custom shortcodes
-Hugo's built-in shortcodes cover many common, but not all, use cases. Luckily, Hugo provides the ability to easily create custom shortcodes to meet your website's needs.
+Hugo's embedded shortcodes cover many common, but not all, use cases. Luckily, Hugo provides the ability to easily create custom shortcodes to meet your website's needs.
{{< youtube Eu4zSaKOY4A >}}
### File location
-To create a shortcode, place an HTML template in the `layouts/shortcodes` directory of your [source organization]. Consider the file name carefully since the shortcode name will mirror that of the file but without the `.html` extension. For example, `layouts/shortcodes/myshortcode.html` will be called with either `{{</* myshortcode /*/>}}` or `{{%/* myshortcode /*/%}}`.
+To create a shortcode, place an HTML template in the `layouts/shortcodes` directory. Consider the file name carefully since the shortcode name will mirror that of the file but without the `.html` extension. For example, `layouts/shortcodes/myshortcode.html` will be called with either `{{</* myshortcode /*/>}}` or `{{%/* myshortcode /*/%}}`.
You can organize your shortcodes in subdirectories, e.g. in `layouts/shortcodes/boxes`. These shortcodes would then be accessible with their relative path, e.g:
@@ -44,31 +44,31 @@ Shortcode templates have a simple [lookup order]:
1. `/layouts/shortcodes/<SHORTCODE>.html`
2. `/themes/<THEME>/layouts/shortcodes/<SHORTCODE>.html`
-### Positional vs. named parameters
+### Positional vs. named arguments
-You can create shortcodes using the following types of parameters:
+You can create shortcodes using the following types of arguments:
-* Positional parameters
-* Named parameters
-* Positional *or* named parameters (i.e, "flexible")
+* Positional arguments
+* Named arguments
+* Positional *or* named arguments
-In shortcodes with positional parameters, the order of the parameters is important. If a shortcode has a single required value (e.g., the `youtube` shortcode below), positional parameters work very well and require less typing from content authors.
+In shortcodes with positional arguments, the order of the arguments is important. If a shortcode has a single required value, positional arguments require less typing from content authors.
-For more complex layouts with multiple or optional parameters, named parameters work best. While less terse, named parameters require less memorization from a content author and can be added in a shortcode declaration in any order.
+For more complex layouts with multiple or optional arguments, named arguments work best. While less terse, named arguments require less memorization from a content author and can be added in a shortcode declaration in any order.
-Allowing both types of parameters (i.e., a "flexible" shortcode) is useful for complex layouts where you want to set default values that can be easily overridden by users.
+Allowing both types of arguments is useful for complex layouts where you want to set default values that can be easily overridden by users.
-### Access parameters
+### Access arguments
-All shortcode parameters can be accessed via the `.Get` method. Whether you pass a key (i.e., string) or a number to the `.Get` method depends on whether you are accessing a named or positional parameter, respectively.
+All shortcode arguments can be accessed via the `.Get` method. Whether you pass a string or a number to the `.Get` method depends on whether you are accessing a named or positional argument, respectively.
-To access a parameter by name, use the `.Get` method followed by the named parameter as a quoted string:
+To access an argument by name, use the `.Get` method followed by the named argument as a quoted string:
```go-html-template
{{ .Get "class" }}
```
-To access a parameter by position, use the `.Get` followed by a numeric position, keeping in mind that positional parameters are zero-indexed:
+To access an argument by position, use the `.Get` followed by a numeric position, keeping in mind that positional arguments are zero-indexed:
```go-html-template
{{ .Get 0 }}
@@ -80,13 +80,13 @@ For the second position, you would just use:
{{ .Get 1 }}
```
-`with` is great when the output depends on a parameter being set:
+`with` is great when the output depends on a argument being set:
```go-html-template
{{ with .Get "class" }} class="{{ . }}"{{ end }}
```
-`.Get` can also be used to check if a parameter has been provided. This is
+`.Get` can also be used to check if a argument has been provided. This is
most helpful when the condition depends on either of the values, or both:
```go-html-template
@@ -95,7 +95,7 @@ most helpful when the condition depends on either of the values, or both:
#### `.Inner`
-If a closing shortcode is used, the `.Inner` variable will be populated with the content between the opening and closing shortcodes. To check if `.Inner` contains anything other than white space:
+The `.Inner` method returns the content between the opening and closing shortcode tags. To check if `.Inner` returns anything other than whitespace:
```go-html-template
{{ if strings.ContainsNonSpace .Inner }}
@@ -103,35 +103,33 @@ If a closing shortcode is used, the `.Inner` variable will be populated with the
{{ end }}
```
-A shortcode with content declared via the `.Inner` variable can also be declared without the content and without the closing tag by using the self-closing syntax:
+{{% note %}}
+Any shortcode that calls the `.Inner` method must be closed or self-closed. To call a shortcode using the self-closing sytax
```go-html-template
{{</* innershortcode /*/>}}
```
-{{% note %}}
-Any shortcode that refers to `.Inner` must be closed or self-closed.
-
{{% /note %}}
#### `.Params`
-The `.Params` variable in shortcodes contains the list parameters passed to shortcode for more complicated use cases. You can also access higher-scoped parameters with the following logic:
+The `.Params` method in shortcodes returns the arguments passed to the shortcode for more complicated use cases. You can also access higher-scoped arguments with the following logic:
$.Params
-: these are the parameters passed directly into the shortcode declaration (e.g., a YouTube video ID)
+: these are the arguments passed directly into the shortcode declaration (e.g., a YouTube video ID)
$.Page.Params
: refers to the page's parameters; the "page" in this case refers to the content file in which the shortcode is declared (e.g., a `shortcode_color` field in a content's front matter could be accessed via `$.Page.Params.shortcode_color`).
-$.Page.Site.Params
-: refers to global variables as defined in your [site's configuration file][config].
+$.Site.Params
+: refers to parameters defined in your site configuration.
#### `.IsNamedParams`
-The `.IsNamedParams` variable checks whether the shortcode declaration uses named parameters and returns a boolean value.
+The `.IsNamedParams` method checks whether the shortcode declaration uses named arguments and returns a boolean value.
-For example, you could create an `image` shortcode that can take either a `src` named parameter or the first positional parameter, depending on the preference of the content's author. Let's assume the `image` shortcode is called as follows:
+For example, you could create an `image` shortcode that can take either a `src` named argument or the first positional argument, depending on the preference of the content's author. Let's assume the `image` shortcode is called as follows:
```go-html-template
{{</* image src="images/my-image.jpg" */>}}
@@ -141,25 +139,23 @@ You could then include the following as part of your shortcode templating:
```go-html-template
{{ if .IsNamedParams }}
-<img src="{{ .Get "src" }}" alt="">
+ <img src="{{ .Get "src" }}" alt="">
{{ else }}
-<img src="{{ .Get 0 }}" alt="">
+ <img src="{{ .Get 0 }}" alt="">
{{ end }}
```
See the [example Vimeo shortcode][vimeoexample] below for `.IsNamedParams` in action.
{{% note %}}
-While you can create shortcode templates that accept both positional and named parameters, you *cannot* declare shortcodes in content with a mix of parameter types. Therefore, a shortcode declared like `{{</* image src="images/my-image.jpg" "This is my alt text" */>}}` will return an error.
+While you can create shortcode templates that accept both positional and named arguments, you *cannot* declare shortcodes in content with a mix of argument types. Therefore, a shortcode declared like `{{</* image src="images/my-image.jpg" "This is my alt text" */>}}` will return an error.
{{% /note %}}
-You can also use the variable `.Page` to access all the normal [page variables][pagevars].
-
-Shortcodes can also be nested. In a nested shortcode, you can access the parent shortcode context with the [`.Parent`] shortcode method. This can be very useful for inheritance of common shortcode parameters from the root.
+Shortcodes can also be nested. In a nested shortcode, you can access the parent shortcode context with the [`.Parent`] shortcode method. This can be very useful for inheritance from the root.
### Checking for existence
-You can check if a specific shortcode is used on a page by calling `.HasShortcode` in that page template, providing the name of the shortcode. This is sometimes useful when you want to include specific scripts or styles in the header that are only used by that shortcode.
+You can check if a specific shortcode is used on a page by calling `.HasShortcode` in that page template, providing the name of the shortcode. This is useful when you want to include specific scripts or styles in the header that are only used by that shortcode.
## Custom shortcode examples
@@ -179,7 +175,7 @@ Let's assume you would like to keep mentions of your copyright year current in y
### Single positional example: `youtube`
-Embedded videos are a common addition to Markdown content that can quickly become unsightly. The following is the code used by [Hugo's built-in YouTube shortcode][youtubeshortcode]:
+Embedded videos are a common addition to Markdown content. The following is the code used by [Hugo's built-in YouTube shortcode][youtubeshortcode]:
```go-html-template
{{</* youtube 09jf3ow9jfw */>}}
@@ -307,9 +303,9 @@ The rendered output of the HTML example code block will be as follows:
### Nested shortcode: image gallery
-Hugo's [`.Parent`] shortcode 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 for common shortcode parameters.
+Hugo's [`.Parent`] shortcode 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.
-The following example is contrived but demonstrates the concept. Assume you have a `gallery` shortcode that expects one named `class` parameter:
+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 >}}
<div class="{{ .Get "class" }}">
@@ -317,7 +313,7 @@ The following example is contrived but demonstrates the concept. Assume you have
</div>
{{< /code >}}
-You also have an `img` shortcode with a single named `src` parameter that you want to call inside of `gallery` and other shortcodes, so that the parent defines the context of each `img`:
+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 >}}
{{- $src := .Get "src" -}}
@@ -350,19 +346,20 @@ This will output the following HTML. Note how the first two `img` shortcodes inh
## Error handling in shortcodes
-Use the [errorf](/functions/fmt/errorf) template function and [`.Position`] shortcode method to get useful error messages in shortcodes:
+Use the [`errorf`] template function with the [`Name`] and [`Position`] shortcode methods to generate useful error messages:
-```sh
+{{< code file=layouts/shortcodes/greeting.html >}}
{{ with .Get "name" }}
+ <p>Hello, my name is {{ . }}.</p>
{{ else }}
-{{ errorf "missing value for parameter 'name': %s" .Position }}
+ {{ errorf "The %q shortcode requires a 'name' argument. See %s" .Name .Position }}
{{ end }}
-```
+{{< /code >}}
-When the above fails, you will see an `ERROR` log similar to the below:
+When the above fails, you will see an `ERROR` message such as:
```sh
-ERROR 2018/11/07 10:05:55 missing value for parameter name: "/Users/bep/dev/go/gohugoio/hugo/docs/content/en/variables/shortcodes.md:32:1"
+ERROR The "greeting" shortcode requires a 'name' argument. See "/home/user/project/content/_index.md:12:1"
```
## Inline shortcodes
@@ -386,28 +383,23 @@ And once enabled, you can do this in your content files:
The above will print the current date and time.
- Note that an inline shortcode's inner content is parsed and executed as a Go text template with the same context as a regular shortcode template.
+Note that an inline shortcode's inner content is parsed and executed as a Go text template with the same context as a regular shortcode template.
This means that the current page can be accessed via `.Page.Title` etc. This also means that there are no concept of "nested inline shortcodes".
-The same inline shortcode can be reused later in the same content file, with different parameters if needed, using the self-closing syntax:
+The same inline shortcode can be reused later in the same content file, with different arguments if needed, using the self-closing syntax:
```go-html-template
{{</* time.inline /*/>}}
```
-[basic content files]: /content-management/formats/
+[`.Parent`]: /methods/shortcode/parent/
+[`errorf`]: /functions/fmt/errorf/
+[`Name`]: /methods/shortcode/name/
+[`Position`]: /methods/shortcode/position/
[built-in shortcode]: /content-management/shortcodes/
-[config]: /getting-started/configuration/
-[Content Management: Shortcodes]: /content-management/shortcodes/#using-hugo-s-built-in-shortcodes
-[source organization]: /getting-started/directory-structure/
-[docsshortcodes]: https://github.com/gohugoio/hugo/tree/master/docs/layouts/shortcodes
[figure]: /content-management/shortcodes/#figure
-[hugosc]: /content-management/shortcodes/#using-hugo-s-built-in-shortcodes
[lookup order]: /templates/lookup-order/
-[pagevars]: /variables/page/
-[`.Parent`]: /methods/shortcode/parent/
-[`.Position`]: /methods/shortcode/position/
-[spfscs]: https://github.com/spf13/spf13.com/tree/master/layouts/shortcodes
+[source organization]: /getting-started/directory-structure/
[vimeoexample]: #single-flexible-example-vimeo
[youtubeshortcode]: /content-management/shortcodes/#youtube
diff --git a/content/en/templates/single-page-templates.md b/content/en/templates/single-page-templates.md
index cd8a2715c..9546486f8 100644
--- a/content/en/templates/single-page-templates.md
+++ b/content/en/templates/single-page-templates.md
@@ -18,12 +18,6 @@ See [Template Lookup](/templates/lookup-order/).
## Example single page templates
-Content pages are of the type `page` and will therefore have all the [page variables][pagevars] and [site variables] available to use in their templates.
-
-### `posts/single.html`
-
-This single page template makes use of Hugo [base templates], the [`.Format` function] for dates, the [`.WordCount` page variable][pagevars], and ranges through the single content's specific [taxonomies][pagetaxonomy]. [`with`] is also used to check whether the taxonomies are set in the front matter.
-
{{< code file=layouts/posts/single.html >}}
{{ define "main" }}
<section id="main">
@@ -77,9 +71,7 @@ To easily generate new instances of a content type (e.g., new `.md` files in a s
[`.format` function]: /methods/time/format/
[front matter]: /content-management/front-matter/
[pagetaxonomy]: /templates/taxonomy-templates/#list-terms-assigned-to-a-page
-[pagevars]: /variables/page/
[partials]: /templates/partials/
[section]: /content-management/sections/
-[site variables]: /variables/site/
[spf13]: https://spf13.com/
[`with`]: /functions/go-template/with/
diff --git a/content/en/templates/sitemap-template.md b/content/en/templates/sitemap-template.md
index 07acfdb63..64609f0b9 100644
--- a/content/en/templates/sitemap-template.md
+++ b/content/en/templates/sitemap-template.md
@@ -14,29 +14,35 @@ aliases: [/layout/sitemap/,/templates/sitemap/]
## Overview
-Hugo's built-in sitemap templates conform to v0.9 of the [sitemap protocol].
+Hugo's embedded sitemap templates conform to v0.9 of the [sitemap protocol].
-With a monolingual project, Hugo generates a sitemap.xml file in the root of the [`publishDir`] using the built-in [sitemap.xml] template.
+With a monolingual project, Hugo generates a sitemap.xml file in the root of the [`publishDir`] using the [embedded sitemap template].
With a multilingual project, Hugo generates:
-- A sitemap.xml file in the root of each site (language) using the built-in [sitemap.xml] template
-- A sitemap.xml file in the root of the [`publishDir`] using the built-in [sitemapindex.xml] template
+- 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
-Set the default values for [change frequency] and [priority], and the name of the generated file, in your site configuration.
+These are the default sitemap configuration values. They apply to all pages unless overridden in front matter.
{{< code-toggle config=sitemap />}}
changefreq
-: How frequently a page is likely to change. Valid values are `always`, `hourly`, `daily`, `weekly`, `monthly`, `yearly`, and `never`. Default is `""` (change frequency omitted from rendered sitemap).
+: (`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
-: The name of the generated file. Default is `sitemap.xml`.
+: (`string`) The name of the generated file. Default is `sitemap.xml`.
priority
-: The priority of a page relative to any other page on the site. Valid values range from 0.0 to 1.0. Default is `-1` (priority omitted from rendered sitemap).
+: (`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).
## Override default values
@@ -46,6 +52,7 @@ Override the default values for a given page in front matter.
title = 'News'
[sitemap]
changefreq = 'weekly'
+ disable = true
priority = 0.8
{{</ code-toggle >}}
@@ -72,8 +79,4 @@ disableKinds = ['sitemap']
{{</ code-toggle >}}
[`publishDir`]: /getting-started/configuration#publishdir
-[change frequency]: <https://www.sitemaps.org/protocol.html#changefreqdef>
-[priority]: <https://www.sitemaps.org/protocol.html#priority>
[sitemap protocol]: <https://www.sitemaps.org/protocol.html>
-[sitemap.xml]: <https://github.com/gohugoio/hugo/blob/master/tpl/tplimpl/embedded/templates/_default/sitemap.xml>
-[sitemapindex.xml]: <https://github.com/gohugoio/hugo/blob/master/tpl/tplimpl/embedded/templates/_default/sitemapindex.xml>
diff --git a/content/en/templates/taxonomy-templates.md b/content/en/templates/taxonomy-templates.md
index ff149e940..e83231a5c 100644
--- a/content/en/templates/taxonomy-templates.md
+++ b/content/en/templates/taxonomy-templates.md
@@ -16,44 +16,28 @@ Hugo includes support for user-defined groupings of content called **taxonomies*
Hugo provides multiple ways to use taxonomies throughout your project templates:
-* Order the way content associated with a taxonomy term is displayed in a [taxonomy list template](#taxonomy-list-templates)
-* Order the way the terms for a taxonomy are displayed in a [taxonomy terms template](#taxonomy-terms-templates)
+* Order the way content associated with a taxonomy term is displayed in a [taxonomy template](#taxonomy-templates)
+* Order the way the terms for a taxonomy are displayed in a [term template](#term-templates)
* List a single content's taxonomy terms within a [single page template]
-## Taxonomy list templates
+## Taxonomy templates
-Taxonomy list page templates are lists and therefore have all the variables and methods available to [list pages][lists].
+Taxonomy list page templates are lists and therefore have all the methods available to [list pages][lists].
-### Taxonomy list template lookup order
+### Taxonomy template lookup order
See [Template Lookup](/templates/lookup-order/).
-## Taxonomy terms templates
+## Term templates
-### Taxonomy terms templates lookup order
+### Term template lookup order
See [Template Lookup](/templates/lookup-order/).
### Taxonomy methods
-A Taxonomy is a `map[string]WeightedPages`.
+{{< list-pages-in-section path=/methods/taxonomy/ >}}
-.Get TERM
-: Returns the WeightedPages for a given term. For example: ;
-`site.Taxonomies.tags.Get "tag-a"`.
-
-.Count TERM
-: The number of pieces of content assigned to the given term. For example: \
-`site.Taxonomies.tags.Count "tag-a"`.
-
-.Alphabetical
-: Returns an OrderedTaxonomy (slice) ordered by term.
-
-.ByCount
-: Returns an OrderedTaxonomy (slice) ordered by number of entries.
-
-.Reverse
-: Returns an OrderedTaxonomy (slice) in reverse order. Must be used with an OrderedTaxonomy.
### OrderedTaxonomy
@@ -102,7 +86,7 @@ type WeightedPages []WeightedPage
## Displaying custom metadata in taxonomy terms templates
-If you need to display custom metadata for each taxonomy term, you will need to create a page for that term at `/content/<TAXONOMY>/<TERM>/_index.md` and add your metadata in its front matter, [as explained in the taxonomies documentation](/content-management/taxonomies/#add-custom-metadata-to-a-taxonomy-or-term). Based on the Actors taxonomy example shown there, within your taxonomy terms template, you may access your custom fields by iterating through the variable `.Pages` as such:
+If you need to display custom metadata for each taxonomy term, you will need to create a page for that term at `/content/<TAXONOMY>/<TERM>/_index.md` and add your metadata in its front matter, [as explained in the taxonomies documentation](/content-management/taxonomies/#add-custom-metadata-to-a-taxonomy-or-term). Based on the Actors taxonomy example shown there, within your taxonomy terms template, you may access your custom fields by ranging over the page collection returned by the [`Pages`] method:
```go-html-template
<ul>
@@ -217,9 +201,9 @@ To render a comma-delimited list:
## List content with the same taxonomy term
-If you are using a taxonomy for something like a series of posts, you can list individual pages associated with the same taxonomy. This is also a quick and dirty method for showing related content:
+If you are using a taxonomy for something like a series of posts, you can list individual pages associated with the same term. For example:
+
-### Example: showing content in same series
```go-html-template
<ul>
@@ -233,13 +217,11 @@ If you are using a taxonomy for something like a series of posts, you can list i
This would be very useful in a sidebar as “featured content”. You could even have different sections of “featured content” by assigning different terms to the content.
-### Example: grouping "featured" content
-
```go-html-template
<section id="menu">
<ul>
- {{ range $key, $taxonomy := .Site.Taxonomies.featured }}
- <li>{{ $key }}</li>
+ {{ range $term, $taxonomy := .Site.Taxonomies.featured }}
+ <li>{{ $term }}</li>
<ul>
{{ range $taxonomy.Pages }}
<li><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></li>
@@ -252,14 +234,8 @@ This would be very useful in a sidebar as “featured content”. You could even
## Render a site's taxonomies
-If you wish to display the list of all keys for your site's taxonomy, you can retrieve them from the [`.Site` variable][sitevars] available on every page.
-
-This may take the form of a tag cloud, a menu, or simply a list.
-
The following example displays all terms in a site's tags taxonomy:
-### Example: list all site tags
-
```go-html-template
<ul>
{{ range .Site.Taxonomies.tags }}
@@ -267,52 +243,43 @@ The following example displays all terms in a site's tags taxonomy:
{{ end }}
</ul>
```
-
-### Example: list all taxonomies, terms, and assigned content
-
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 >}}
-<ul>
- {{ range $taxonomy, $terms := site.Taxonomies }}
- <li>
- {{ with site.GetPage $taxonomy }}
- <a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a>
- {{ end }}
- <ul>
- {{ range $term, $weightedPages := $terms }}
+{{ with .Site.Taxonomies }}
+ {{ $numberOfTerms := 0 }}
+ {{ range $taxonomy, $terms := . }}
+ {{ $numberOfTerms = len . | add $numberOfTerms }}
+ {{ end }}
+
+ {{ if gt $numberOfTerms 0 }}
+ <ul>
+ {{ range $taxonomy, $terms := . }}
+ {{ with $terms }}
<li>
<a href="{{ .Page.RelPermalink }}">{{ .Page.LinkTitle }}</a>
<ul>
- {{ range $weightedPages }}
- <li><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></li>
+ {{ range $term, $weightedPages := . }}
+ <li>
+ <a href="{{ .Page.RelPermalink }}">{{ .Page.LinkTitle }}</a>
+ <ul>
+ {{ range $weightedPages }}
+ <li><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></li>
+ {{ end }}
+ </ul>
+ </li>
{{ end }}
</ul>
</li>
{{ end }}
- </ul>
- </li>
- {{ end }}
-</ul>
-{{< /code >}}
-
-## `.Site.GetPage` for taxonomies
-
-Because taxonomies are lists, the [`.GetPage` function][getpage] can be used to get all the pages associated with a particular taxonomy term using a terse syntax. The following ranges over the full list of tags on your site and links to each of the individual taxonomy pages for each term without having to use the more fragile URL construction of the ["List All Site Tags" example above](#example-list-all-site-tags):
-
-{{< code file=links-to-all-tags.html >}}
-{{ $taxo := "tags" }}
-<ul class="{{ $taxo }}">
- {{ with ($.Site.GetPage (printf "/%s" $taxo)) }}
- {{ range .Pages }}
- <li><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></li>
- {{ end }}
+ {{ end }}
+ </ul>
{{ end }}
-</ul>
+{{ end }}
{{< /code >}}
-[getpage]: /methods/page/getpage
+[`Pages`]: /methods/page/pages/
+[getpage]: /methods/page/getpage/
[lists]: /templates/lists/
[renderlists]: /templates/lists/
[single page template]: /templates/single-page-templates/
-[sitevars]: /variables/site/
diff --git a/content/en/templates/views.md b/content/en/templates/views.md
index e49f1debb..4170196b6 100644
--- a/content/en/templates/views.md
+++ b/content/en/templates/views.md
@@ -34,7 +34,7 @@ To create a new view, create a template in each of your different content type d
summary.html
```
-Hugo also has support for a default content template to be used in the event that a specific content view template has not been provided for that type. Content views can also be defined in the `_default` directory and will work the same as list and single templates who eventually trickle down to the `_default` directory as a matter of the lookup order.
+Hugo also has support for a default content view template to be used in the event that a specific content view template has not been provided for that type. Content views can also be defined in the `_default` directory and will work the same as list and single templates who eventually trickle down to the `_default` directory as a matter of the lookup order.
```txt
▾ layouts/
@@ -46,7 +46,7 @@ Hugo also has support for a default content template to be used in the event tha
## Which template will be rendered?
-The following is the [lookup order][lookup] for content views:
+The following is the [lookup order] for content views:
1. `/layouts/<TYPE>/<VIEW>.html`
2. `/layouts/_default/<VIEW>.html`
@@ -74,7 +74,7 @@ In this example, `.Render` is passed into the template to call the [render funct
### `summary.html`
-Hugo will pass the entire page object to the following `summary.html` view template. (See [Page Variables][pagevars] for a complete list.)
+Hugo passes the page object to the following `summary.html` view template.
{{< code file=layouts/_default/summary.html >}}
<article class="post">
@@ -101,13 +101,7 @@ Continuing on the previous example, we can change our render function to use a s
{{< /code >}}
[lists]: /templates/lists/
-[lookup]: /templates/lookup-order/
-[pagevars]: /variables/page/
[render]: /methods/page/render/
[single]: /templates/single-page-templates/
-[spf]: https://spf13.com
-[spfsourceli]: https://github.com/spf13/spf13.com/blob/master/layouts/_default/li.html
-[spfsourcesection]: https://github.com/spf13/spf13.com/blob/master/layouts/_default/section.html
-[spfsourcesummary]: https://github.com/spf13/spf13.com/blob/master/layouts/_default/summary.html
[summaries]: /content-management/summaries/
[taxonomylists]: /templates/taxonomy-templates/
diff --git a/content/en/tools/_index.md b/content/en/tools/_index.md
index 006bed053..9cd72853a 100644
--- a/content/en/tools/_index.md
+++ b/content/en/tools/_index.md
@@ -1,12 +1,12 @@
---
title: Developer tools
-linkTitle: Overview
+linkTitle: In this section
description: In addition to Hugo's powerful CLI, there is a large number of community-developed tool chains for Hugo developers.
categories: []
keywords: []
menu:
docs:
- identifier: developer-tools-overview
+ identifier: developer-tools-in-this-section
parent: developer-tools
weight: 10
weight: 10
diff --git a/content/en/tools/editors.md b/content/en/tools/editors.md
index d94b7af0f..b2e2cc47b 100644
--- a/content/en/tools/editors.md
+++ b/content/en/tools/editors.md
@@ -58,8 +58,6 @@ toc: true
[Vim Hugo Helper]
: A small Vim plugin that facilitates authoring pages and blog posts with Hugo.
-[xxx]: xxx
-
[vim-hugo](https://github.com/phelipetls/vim-hugo)
: A Vim plugin with syntax highlighting for templates and a few other features.
diff --git a/content/en/tools/front-ends.md b/content/en/tools/front-ends.md
index acce84d8d..217f96e2c 100644
--- a/content/en/tools/front-ends.md
+++ b/content/en/tools/front-ends.md
@@ -21,10 +21,16 @@ aliases: [/tools/frontends/]
[DatoCMS](https://www.datocms.com)
: DatoCMS is a fully customizable administrative area for your static websites. Use your favorite website generator, let your clients publish new content independently, and the host the site anywhere you like.
-## Open source
+[PubCrank](https://www.pubcrank.com/)
+: PubCrank is a static site editor which lets you define templates for different front matter layouts in your site. This gives writers an easy-to-use visual interface to create and edit content while maintaining the guardrails that the developer has created. PubCrank is free for local editing.
+
+## Open-source
[Decap CMS](https://decapcms.org/)
: Decap CMS is an open-source, serverless solution for managing Git based content in static sites, and it works on any platform that can host static sites. A [Hugo/Decap CMS starter](https://github.com/decaporg/one-click-hugo-cms) is available to get new projects running quickly.
+[Quiqr Desktop](https://quiqr.org/)
+: Quiqr Desktop is a open-source, cross-platform, offline desktop CMS for Hugo with built-in Git functionality for deploying static sites to any hosting server.
+
[Sveltia CMS](https://github.com/sveltia/sveltia-cms/)
: Sveltia CMS is a drop-in replacement for Decap CMS which is built from the ground up with powerful and performant modern UI library Svelte. Sveltia CMS incorporates i18n into every corner of the product, while striving to radically improve UX, performance and productivity.
diff --git a/content/en/tools/migrations.md b/content/en/tools/migrations.md
index 0e61274c4..3a2cdac35 100644
--- a/content/en/tools/migrations.md
+++ b/content/en/tools/migrations.md
@@ -40,7 +40,7 @@ Alternatively, you can use the [Jekyll import command](/commands/hugo_import_jek
## WordPress
[wordpress-to-hugo-exporter](https://github.com/SchumacherFM/wordpress-to-hugo-exporter)
-: A one-click WordPress plugin that converts all posts, pages, taxonomies, metadata, and settings to Markdown and YAML which can be dropped into Hugo. (Note: If you have trouble using this plugin, you - \s-\scan [export your site for Jekyll](https://wordpress.org/plugins/jekyll-exporter/) and use Hugo's built in Jekyll converter listed above.)
+: A one-click WordPress plugin that converts all posts, pages, taxonomies, metadata, and settings to Markdown and YAML which can be dropped into Hugo. (Note: If you have trouble using this plugin, you can [export your site for Jekyll](https://wordpress.org/plugins/jekyll-exporter/) and use Hugo's built in Jekyll converter listed above.)
[blog2md](https://github.com/palaniraja/blog2md)
: Works with [exported xml](https://en.support.wordpress.com/export/) file of your free YOUR-TLD.wordpress.com website. It also saves approved comments to `YOUR-POST-NAME-comments.md` file along with posts.
@@ -48,6 +48,9 @@ Alternatively, you can use the [Jekyll import command](/commands/hugo_import_jek
[wordhugopress](https://github.com/nantipov/wordhugopress)
: A small utility written in Java, 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 of the multiple WordPress sites into a single Hugo one.
+[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.
+
## Medium
[medium2md](https://github.com/gautamdhameja/medium-2-md)
diff --git a/content/en/tools/other.md b/content/en/tools/other.md
index f5243632c..8edfc4258 100644
--- a/content/en/tools/other.md
+++ b/content/en/tools/other.md
@@ -11,13 +11,14 @@ menu:
weight: 60
---
-And for all the other small things around Hugo:
+And for all the other community projects around Hugo:
-- [hugo-gallery](https://github.com/icecreammatt/hugo-gallery) lets you create an image gallery for Hugo sites.
-- [flickr-hugo-embed](https://github.com/nikhilm/flickr-hugo-embed) prints shortcodes to embed a set of images from an album on Flickr into Hugo.
-- [hugo-openapispec-shortcode](https://github.com/tenfourty/hugo-openapispec-shortcode) A shortcode that allows you to include [Open API Spec](https://openapis.org) (formerly known as Swagger Spec) in a page.
-- [HugoPhotoSwipe](https://github.com/GjjvdBurg/HugoPhotoSwipe) makes it easy to create image galleries using PhotoSwipe.
-- [Hugo SFTP Upload](https://github.com/thomasmey/HugoSftpUpload) Syncs the local build of your Hugo website with your remote web server via SFTP.
-- [Emacs Easy Hugo](https://github.com/masasam/emacs-easy-hugo) Emacs package for writing blog posts in markdown or org-mode and building your site with Hugo.
-- [JAMStack Themes](https://jamstackthemes.dev/ssg/hugo/). JAMStack themes is a collection of site themes filterable by static site generator and supported CMS to help build CMS-connected sites using Hugo (linking to Hugo-specific themes).
-- [plausible-hugo](https://github.com/divinerites/plausible-hugo). Easy Hugo integration for Plausible Analytics, a simple, open-source, lightweight and privacy-friendly web analytics alternative to Google Analytics.
+- [diego](https://github.com/ttybitnik/diego) - A CLI tool that integrates with Hugo to assist in importing and utilizing exported social media data from popular services on Hugo websites.
+- [Emacs Easy Hugo](https://github.com/masasam/emacs-easy-hugo) - Emacs package for writing blog posts in Markdown or org-mode and building your site with Hugo.
+- [Hugo SFTP Upload](https://github.com/thomasmey/HugoSftpUpload) - Sync the local build of your Hugo website with your remote web server via SFTP.
+- [HugoPhotoSwipe](https://github.com/GjjvdBurg/HugoPhotoSwipe) - Make it easy to create image galleries using PhotoSwipe.
+- [JAMStack Themes](https://jamstackthemes.dev/ssg/hugo/) - A collection of site themes filterable by static site generator and supported CMS to help build CMS-connected sites using Hugo (linking to Hugo-specific themes).
+- [flickr-hugo-embed](https://github.com/nikhilm/flickr-hugo-embed) - Print shortcodes to embed a set of images from an album on Flickr into Hugo.
+- [hugo-gallery](https://github.com/icecreammatt/hugo-gallery) - Create an image gallery for Hugo sites.
+- [hugo-openapispec-shortcode](https://github.com/tenfourty/hugo-openapispec-shortcode) - A shortcode that allows you to include [Open API Spec](https://openapis.org) (formerly known as Swagger Spec) in a page.
+- [plausible-hugo](https://github.com/divinerites/plausible-hugo) - Easy Hugo integration for Plausible Analytics, a simple, open-source, lightweight and privacy-friendly web analytics alternative to Google Analytics.
diff --git a/content/en/tools/search.md b/content/en/tools/search.md
index c3db0dc98..921d52f82 100644
--- a/content/en/tools/search.md
+++ b/content/en/tools/search.md
@@ -14,7 +14,7 @@ toc: true
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.
-## Open source
+## Open-source
[Pagefind](https://github.com/cloudcannon/pagefind)
: A fully static search library that aims to perform well on large sites, while using as little of your users' bandwidth as possible.
@@ -32,7 +32,7 @@ A static website with a dynamic search function? Yes, Hugo provides an alternati
: This gist demonstrates how to leverage Hugo's existing build time processing to generate a searchable JSON index used by [Fuse.js](https://fusejs.io/) on the client-side. Although this gist uses Fuse.js for fuzzy matching, any client-side search tool capable of reading JSON indexes will work. Does not require npm, grunt, or other build-time tools except Hugo!
[hugo-search-index](https://www.npmjs.com/package/hugo-search-index)
-: A library containing Gulp tasks and a prebuilt browser script that implements search. Gulp generates a search index from project markdown files.
+: A library containing Gulp tasks and a prebuilt browser script that implements search. Gulp generates a search index from project Markdown files.
[hugofastsearch](https://gist.github.com/cmod/5410eae147e4318164258742dd053993)
: A usability and speed update to "GitHub Gist for Fuse.js integration" — global, keyboard-optimized search.
diff --git a/content/en/troubleshooting/_index.md b/content/en/troubleshooting/_index.md
index 65263ab32..92ba6bc6d 100644
--- a/content/en/troubleshooting/_index.md
+++ b/content/en/troubleshooting/_index.md
@@ -1,12 +1,12 @@
---
title: Troubleshooting
-linkTitle: Overview
+linkTitle: In this section
description: Use these techniques when troubleshooting your site.
categories: []
keywords: []
menu:
docs:
- identifier: troubleshooting-overview
+ identifier: troubleshooting-in-this-section
parent: troubleshooting
weight: 10
weight: 10
diff --git a/content/en/troubleshooting/audit/index.md b/content/en/troubleshooting/audit/index.md
index f00ed8f8d..e0de0d5df 100644
--- a/content/en/troubleshooting/audit/index.md
+++ b/content/en/troubleshooting/audit/index.md
@@ -53,7 +53,7 @@ _Tested with GNU Bash 5.1 and GNU grep 3.7._
### Patterns
`<!-- raw HTML omitted -->`
-: By default, Hugo strips raw HTML from your markdown prior to rendering, and leaves this HTML comment in its place.
+: By default, Hugo strips raw HTML from your Markdown prior to rendering, and leaves this HTML comment in its place.
`ZgotmplZ`
: ZgotmplZ is a special value that indicates that unsafe content reached a CSS or URL context at runtime. See&nbsp;[details].
diff --git a/content/en/troubleshooting/faq.md b/content/en/troubleshooting/faq.md
index 0425ca277..f8106a7db 100644
--- a/content/en/troubleshooting/faq.md
+++ b/content/en/troubleshooting/faq.md
@@ -39,17 +39,6 @@ In the content/_index.md file:
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 section not published?
-
-In the content/section/_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`.
-
###### Why is a given page not published?
In the content/section/page.md file, or in the content/section/page/index.md file:
@@ -94,7 +83,7 @@ You are probably invoking the [`Paginate`] or [`Paginator`] method more than onc
###### 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\
+Use the `{{%/* shortcode */%}}` notation if the shortcode template, or the content between the opening and closing shortcode tags, contains Markdown. Otherwise use the\
`{{</* shortcode */>}}` notation. See&nbsp;[details](/content-management/shortcodes/).
###### Can I use environment variables to control configuration?
@@ -105,6 +94,36 @@ Yes. See&nbsp;[details](/getting-started/configuration/#configure-with-environme
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] 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.
+
+[scratch pad]: /getting-started/glossary/#scratch-pad
+
+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] variable:
+
+[noop]: /getting-started/glossary/#noop
+
+```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`, `FuzzyWordCount`, `Len`, `Plain`, `PlainWords`, `ReadingTime`, `Summary`, `Truncated`, and `WordCount`.
@@ -116,9 +135,9 @@ For other questions please visit the [forum]. A quick search of over 20,000 topi
[requesting help]: https://discourse.gohugo.io/t/requesting-help/9132
{{% /note %}}
-[`Paginate`]: /methods/page/paginate
-[`Paginator`]: /methods/page/paginator
+[`Paginate`]: /methods/page/paginate/
+[`Paginator`]: /methods/page/paginator/
[context]: /getting-started/glossary/#context
[forum]: https://discourse.gohugo.io
-[installation]: /installation
+[installation]: /installation/
[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 826229153..e9fc8ed0f 100644
--- a/content/en/troubleshooting/inspection.md
+++ b/content/en/troubleshooting/inspection.md
@@ -11,10 +11,10 @@ menu:
weight: 40
---
-Use the [`jsonify`] function to inspect a data structure:
+Use the [`debug.Dump`] function to inspect a data structure:
```go-html-template
-<pre>{{ jsonify (dict "indent" " ") .Params }}</pre>
+<pre>{{ debug.Dump .Params }}</pre>
```
```text
@@ -32,33 +32,6 @@ Use the [`jsonify`] function to inspect a data structure:
}
```
-{{% note %}}
-Hugo will throw an error if you attempt to use the construct above to display context that includes a page collection. For example, in a home page template, this will fail:
-
-`{{ jsonify (dict "indent" " ") . }}`
-{{% /note %}}
-
-Use the [`debug.Dump`] function to inspect data types:
-
-```go-html-template
-<pre>{{ debug.Dump .Params }}</pre>
-```
-
-```text
-maps.Params{
- "date": time.Time{},
- "draft": false,
- "iscjklanguage": false,
- "lastmod": time.Time{},
- "publishdate": time.Time{},
- "tags": []string{
- "foo",
- "bar",
- },
- "title": "My first post",
-}
-```
-
Use the [`printf`] function (render) or [`warnf`] function (log to console) to inspect simple data structures. The layout string below displays both value and data type.
```go-html-template
@@ -66,7 +39,6 @@ Use the [`printf`] function (render) or [`warnf`] function (log to console) to i
{{ printf "%[1]v (%[1]T)" $value }} → 42 (int)
```
-[`jsonify`]: /functions/encoding/jsonify
-[`debug.Dump`]: /functions/debug/dump
-[`printf`]: /functions/fmt/printf
-[`warnf`]: /functions/fmt/warnf
+[`debug.Dump`]: /functions/debug/dump/
+[`printf`]: /functions/fmt/printf/
+[`warnf`]: /functions/fmt/warnf/
diff --git a/content/en/troubleshooting/logging.md b/content/en/troubleshooting/logging.md
index 8879c1846..fc6838069 100644
--- a/content/en/troubleshooting/logging.md
+++ b/content/en/troubleshooting/logging.md
@@ -54,3 +54,19 @@ If you do not specify a logging level with the `--logLevel` flag, warnings and e
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 >}}
+
+## LiveReload
+
+To log Hugo's LiveReload requests in your browser, add this query string to the URL when running Hugo's development server:
+
+```text
+debug=LR-verbose
+```
+
+For example:
+
+```text
+http://localhost:1313/?debug=LR-verbose
+```
+
+Then monitor the reload requests in your browser's dev tools console. Make sure the dev tools "preserve log" option is enabled.
diff --git a/content/en/troubleshooting/performance.md b/content/en/troubleshooting/performance.md
index 174d6cfd9..a2df1b08e 100644
--- a/content/en/troubleshooting/performance.md
+++ b/content/en/troubleshooting/performance.md
@@ -1,6 +1,6 @@
---
title: Performance
-description: Use template metrics and timers to identify opportunities to improve performance.
+description: Tools and suggestions for evaluating and improving performance.
categories: [troubleshooting]
keywords: []
menu:
@@ -12,6 +12,24 @@ toc: true
aliases: [/troubleshooting/build-performance/]
---
+## Virus scanning
+
+Virus scanners are an essential component of system protection, but the performance impact can be severe for applications like Hugo that frequently read and write to disk. For example, with Microsoft Defender Antivirus, build times for some sites may increase by 400% or more.
+
+Before building a site, your virus scanner has already evaluated the files in your project directory. Scanning them again while building the site is superfluous. To improve performance, add Hugo's executable to your virus scanner's process exclusion list.
+
+For example, with Microsoft Defender Antivirus:
+
+**Start**&nbsp;> **Settings**&nbsp;> **Privacy&nbsp;&&nbsp;security**&nbsp;> **Windows&nbsp;Security**&nbsp;> **Open&nbsp;Windows&nbsp;Security**&nbsp;> **Virus&nbsp;&&nbsp;threat&nbsp;protection**&nbsp;> **Manage&nbsp;settings**&nbsp;> **Add&nbsp;or&nbsp;remove&nbsp;exclusions**&nbsp;> **Add&nbsp;an&nbsp;exclusion**&nbsp;> **Process**
+
+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 %}}
+
+Other virus scanners have similar exclusion mechanisms. See their respective documentation.
+
## Template metrics
Hugo is fast, but inefficient templates impede performance. Enable template metrics to determine which templates take the most time, and to identify caching opportunities:
@@ -74,8 +92,8 @@ total count
template
: The path to the template, relative to the layouts directory.
-[`partial`]: /functions/partials/include
-[`partialCached`]: /functions/partials/includecached
+[`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.
@@ -86,7 +104,7 @@ Hugo builds pages in parallel where multiple pages are generated simultaneously.
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 parameters to `partialCached` beyond the initial context. See the `partialCached` documentation for more details.
+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 %}}
## Timers
diff --git a/content/en/variables/_common/consistent-terminology.md b/content/en/variables/_common/consistent-terminology.md
deleted file mode 100644
index 8774c817b..000000000
--- a/content/en/variables/_common/consistent-terminology.md
+++ /dev/null
@@ -1,20 +0,0 @@
----
-# Do not remove front matter.
----
-
-{{% note %}}
-We are making an effort to unify our [terminology], and to use these terms consistently throughout the documentation.
-
-Historically, we have inconsistently referred to the items on this page as [functions], [parameters], [variables], or [methods]. They are not functions, parameters, or variables; they are methods.
-
-This page will remain in place as readers become familiar with the unified terminology. See the [methods section] for a list of methods by [object], or the [methods quick reference guide].
-
-[functions]: /getting-started/glossary/#function
-[methods quick reference guide]: /quick-reference/methods
-[methods section]: /methods
-[methods]: /getting-started/glossary/#method
-[object]: /getting-started/glossary/#object
-[parameters]: /getting-started/glossary/#parameter
-[terminology]: /getting-started/glossary/
-[variables]: /getting-started/glossary/#variable
-{{% /note %}}
diff --git a/content/en/variables/_index.md b/content/en/variables/_index.md
deleted file mode 100644
index d8dbf9d67..000000000
--- a/content/en/variables/_index.md
+++ /dev/null
@@ -1,16 +0,0 @@
----
-title: Variables
-linkTitle: Overview
-description: Use these variables in your templates.
-categories: []
-keywords: []
-menu:
- docs:
- identifier: variables-overview
- parent: variables
- weight: 10
-weight: 10
-aliases: [/templates/variables/]
----
-
-{{% include "variables/_common/consistent-terminology.md" %}}
diff --git a/content/en/variables/file.md b/content/en/variables/file.md
deleted file mode 100644
index 248d84991..000000000
--- a/content/en/variables/file.md
+++ /dev/null
@@ -1,18 +0,0 @@
----
-title: File variables
-description: Retrieve file information about any page that is backed by a file.
-categories: [variables]
-keywords: []
-menu:
- docs:
- parent: variables
- weight: 20
-weight: 20
-aliases: [/variables/file-variables/,/variables/files/]
----
-
-{{% include "variables/_common/consistent-terminology.md" %}}
-
-To retrieve file information about any page that is backed by a file, see the documentation for the [`File`] method on a `Page` object.
-
-[`File`]: /methods/page/file
diff --git a/content/en/variables/git.md b/content/en/variables/git.md
deleted file mode 100644
index 3dc473265..000000000
--- a/content/en/variables/git.md
+++ /dev/null
@@ -1,18 +0,0 @@
----
-title: Git variables
-description: Retrieve Git information related to the last commit of any page.
-categories: [variables]
-keywords: []
-menu:
- docs:
- parent: variables
- weight: 30
-weight: 30
-aliases: [/extras/gitinfo/]
----
-
-{{% include "variables/_common/consistent-terminology.md" %}}
-
-To retrieve Git information related to the last commit of any page, see the documentation for the [`GitInfo`] method on a `Page` object.
-
-[`GitInfo`]: /methods/page/gitinfo
diff --git a/content/en/variables/menu-entry.md b/content/en/variables/menu-entry.md
deleted file mode 100644
index 5b90dab6f..000000000
--- a/content/en/variables/menu-entry.md
+++ /dev/null
@@ -1,16 +0,0 @@
----
-title: Menu entry variables
-description: Use these methods in your menu templates.
-categories: [variables]
-keywords: []
-menu:
- docs:
- parent: variables
- weight: 40
-weight: 40
-aliases: [/variables/menus/]
----
-
-{{% include "variables/_common/consistent-terminology.md" %}}
-
-{{< list-pages-in-section path=/methods/menu-entry titlePrefix=. >}}
diff --git a/content/en/variables/page.md b/content/en/variables/page.md
deleted file mode 100644
index 732cf5499..000000000
--- a/content/en/variables/page.md
+++ /dev/null
@@ -1,63 +0,0 @@
----
-title: Page variables
-description: Use these methods with a Page object.
-categories: [variables]
-keywords: []
-menu:
- docs:
- parent: variables
- weight: 50
-weight: 50
-toc: true
----
-
-{{% include "variables/_common/consistent-terminology.md" %}}
-
-## All methods
-
-Use any of these methods in your templates.
-
-{{< list-pages-in-section path=/methods/page titlePrefix=. >}}
-
-## Dates
-
-Use these methods to access content dates.
-
-{{< list-pages-in-section path=/methods/page filter=methods_page_dates filterType=include titlePrefix=. omitElementIDs=true >}}
-
-## Multilingual
-
-Use these methods with your multilingual projects.
-
-{{< list-pages-in-section path=/methods/page filter=methods_page_multilingual filterType=include titlePrefix=. omitElementIDs=true >}}
-
-## Navigation
-
-Use these methods to create navigation links between pages.
-
-{{< list-pages-in-section path=/methods/page filter=methods_page_navigation filterType=include titlePrefix=. omitElementIDs=true >}}
-
-## Page collections
-
-Range through these collections when rendering lists on [section] pages, [taxonomy] pages, [term] pages, and the home page.
-
-[section]: /getting-started/glossary/#section
-[taxonomy]: /getting-started/glossary/#taxonomy
-[term]: /getting-started/glossary/#term
-[context]: /getting-started/glossary/#context
-
-{{< list-pages-in-section path=/methods/page filter=methods_page_page_collections filterType=include titlePrefix=. omitElementIDs=true >}}
-
-## Parameters
-
-Use these methods to access page parameters.
-
-{{< list-pages-in-section path=/methods/page filter=methods_page_parameters filterType=include titlePrefix=. omitElementIDs=true >}}
-
-## Sections
-
-Use these methods to access section pages, and their ancestors and descendants. See&nbsp;[details].
-
-[details]: /content-management/sections/
-
-{{< list-pages-in-section path=/methods/page filter=methods_page_sections filterType=include titlePrefix=. omitElementIDs=true >}}
diff --git a/content/en/variables/pages.md b/content/en/variables/pages.md
deleted file mode 100644
index 24b8fbbf4..000000000
--- a/content/en/variables/pages.md
+++ /dev/null
@@ -1,39 +0,0 @@
----
-title: Pages variables
-description: Use these methods with a collection of Page objects.
-categories: [variables]
-keywords: []
-menu:
- docs:
- parent: variables
- weight: 60
-weight: 60
-toc: true
-aliases: [/variables/site-variables/]
----
-
-{{% include "variables/_common/consistent-terminology.md" %}}
-
-## All methods
-
-Use any of these methods with page collections in your templates.
-
-{{< list-pages-in-section path=/methods/pages titlePrefix=. >}}
-
-## Sort by
-
-Use these methods to sort page collections.
-
-{{< list-pages-in-section path=/methods/pages filter=methods_pages_sort filterType=include titlePrefix=. omitElementIDs=true >}}
-
-## Group by
-
-Use these methods to group page collections.
-
-{{< list-pages-in-section path=/methods/pages filter=methods_pages_group filterType=include titlePrefix=. omitElementIDs=true >}}
-
-## Navigation
-
-Use these methods to create navigation links between pages.
-
-{{< list-pages-in-section path=/methods/pages filter=methods_pages_navigation filterType=include titlePrefix=. omitElementIDs=true >}}
diff --git a/content/en/variables/shortcode.md b/content/en/variables/shortcode.md
deleted file mode 100644
index 57279b5de..000000000
--- a/content/en/variables/shortcode.md
+++ /dev/null
@@ -1,16 +0,0 @@
----
-title: Shortcode variables
-description: Use these methods in your shortcode templates.
-categories: [variables]
-keywords: []
-menu:
- docs:
- parent: variables
- weight: 70
-weight: 70
-aliases: [/variables/shortcodes]
----
-
-{{% include "variables/_common/consistent-terminology.md" %}}
-
-{{< list-pages-in-section path=/methods/shortcode titlePrefix=. >}}
diff --git a/content/en/variables/site.md b/content/en/variables/site.md
deleted file mode 100644
index 532357785..000000000
--- a/content/en/variables/site.md
+++ /dev/null
@@ -1,55 +0,0 @@
----
-title: Site variables
-description: Use these methods with Site objects. A multilingual project will have two or more sites, one for each language.
-categories: [variables]
-keywords: []
-menu:
- docs:
- parent: variables
- weight: 80
-weight: 80
-toc: true
-aliases: [/variables/site-variables/]
----
-
-{{% include "variables/_common/consistent-terminology.md" %}}
-
-## All methods
-
-Use any of these methods in your templates.
-
-{{< list-pages-in-section path=/methods/site titlePrefix=.Site. >}}
-
-## Multilingual
-
-Use these methods with your multilingual projects.
-
-{{< list-pages-in-section path=/methods/site filter=methods_site_multilingual filterType=include titlePrefix=.Site. omitElementIDs=true >}}
-
-[`site`]: /functions/global/site
-[context]: /getting-started/glossary/#context
-[configuration file]: /getting-started/configuration
-
-## Page collections
-
-Range through these collections when rendering lists on any page.
-
-{{< list-pages-in-section path=/methods/site filter=methods_site_page_collections filterType=include titlePrefix=.Site. omitElementIDs=true >}}
-
-## Global site function
-
-Within a partial template, if you did not pass a `Page` or `Site` object in [context], you cannot use this syntax:
-
-```go-html-template
-{{ .Site.SomeMethod }}
-```
-
-Instead, use the global [`site`] function:
-
-```go-html-template
-{{ site.SomeMethod }}
-```
-
-{{% note %}}
-You can use the global site function in all templates to avoid context problems. Its usage is not limited to partial templates.
-{{% /note %}}
diff --git a/content/en/variables/taxonomy.md b/content/en/variables/taxonomy.md
deleted file mode 100644
index ee6d73b2e..000000000
--- a/content/en/variables/taxonomy.md
+++ /dev/null
@@ -1,21 +0,0 @@
----
-title: Taxonomy variables
-description: Use these methods with Taxonomy objects.
-categories: [variables]
-keywords: []
-menu:
- docs:
- parent: variables
- weight: 90
-weight: 90
----
-
-{{% include "variables/_common/consistent-terminology.md" %}}
-
-{{< list-pages-in-section path=/methods/taxonomy titlePrefix=. >}}
-
-{{% note %}}
-Within a taxonomy or term template use the [`Data`] method to retrieve information specific to the taxonomy or term.
-
-[`Data`]: /methods/page/data
-{{% /note %}}
diff --git a/data/docs.yaml b/data/docs.yaml
index 04ef2cb26..603519d76 100644
--- a/data/docs.yaml
+++ b/data/docs.yaml
@@ -208,6 +208,10 @@ chroma:
- dax
Name: Dax
- Aliases:
+ - desktop
+ - desktop_entry
+ Name: Desktop file
+ - Aliases:
- diff
- udiff
Name: Diff
@@ -444,6 +448,10 @@ chroma:
- mason
Name: Mason
- Aliases:
+ - materialize
+ - mzsql
+ Name: Materialize SQL dialect
+ - Aliases:
- mathematica
- mma
- nb
@@ -494,6 +502,9 @@ chroma:
- natural
Name: Natural
- Aliases:
+ - ndisasm
+ Name: NDISASM
+ - Aliases:
- newspeak
Name: Newspeak
- Aliases:
@@ -608,6 +619,9 @@ chroma:
- prolog
Name: Prolog
- Aliases:
+ - promela
+ Name: Promela
+ - Aliases:
- promql
Name: PromQL
- Aliases:
@@ -674,6 +688,9 @@ chroma:
- registry
Name: reg
- Aliases:
+ - rego
+ Name: Rego
+ - Aliases:
- rst
- rest
- restructuredtext
@@ -683,6 +700,9 @@ chroma:
- arexx
Name: Rexx
- Aliases:
+ - spec
+ Name: RPMSpec
+ - Aliases:
- rb
- ruby
- duby
@@ -906,6 +926,20 @@ chroma:
- zig
Name: Zig
config:
+ HTTPCache:
+ cache:
+ for:
+ excludes:
+ - '**'
+ includes: null
+ polls:
+ - disable: true
+ for:
+ excludes: null
+ includes:
+ - '**'
+ high: 0s
+ low: 0s
archeTypeDir: archetypes
assetDir: assets
author: {}
@@ -917,14 +951,8 @@ config:
disableTags: false
enable: false
cacheBusters:
- - source: assets/.*\.(js|ts|jsx|tsx)
- target: (js|scripts|javascript)
- - source: assets/.*\.(css|sass|scss)$
- target: (css|styles|scss|sass)
- source: (postcss|tailwind)\.config\.js
target: (css|styles|scss|sass)
- - source: assets/.*\.(.*)$
- target: $1
noJSConfigInAssets: false
useResourceCacheWhen: fallback
buildDrafts: false
@@ -951,6 +979,7 @@ config:
dir: :cacheDir/modules
maxAge: -1
canonifyURLs: false
+ capitalizeListTitles: true
cascade: []
cleanDestinationDir: false
contentDir: content
@@ -1007,8 +1036,8 @@ config:
hasCJKLanguage: false
i18nDir: i18n
ignoreCache: false
- ignoreErrors: null
ignoreFiles: []
+ ignoreLogs: null
ignoreVendorPaths: ""
imaging:
bgColor: '#ffffff'
@@ -1041,6 +1070,7 @@ config:
workingFolderCurrent: false
defaultMarkdownHandler: goldmark
goldmark:
+ duplicateResourceFiles: false
extensions:
cjk:
eastAsianLineBreaks: false
@@ -1048,6 +1078,15 @@ config:
enable: false
escapedSpace: false
definitionList: true
+ extras:
+ insert:
+ enable: false
+ mark:
+ enable: false
+ subscript:
+ enable: false
+ superscript:
+ enable: false
footnote: true
linkify: true
linkifyProtocol: https
@@ -1078,6 +1117,11 @@ config:
autoHeadingID: true
autoHeadingIDType: github
wrapStandAloneImageWithinParagraph: true
+ renderHooks:
+ image:
+ enableDefault: false
+ link:
+ enableDefault: false
renderer:
hardWraps: false
unsafe: false
@@ -1178,6 +1222,12 @@ config:
delimiter: .
suffixes:
- webp
+ text/asciidoc:
+ delimiter: .
+ suffixes:
+ - adoc
+ - asciidoc
+ - ad
text/calendar:
delimiter: .
suffixes:
@@ -1194,6 +1244,7 @@ config:
delimiter: .
suffixes:
- html
+ - htm
text/javascript:
delimiter: .
suffixes:
@@ -1208,11 +1259,25 @@ config:
delimiter: .
suffixes:
- md
+ - mdown
- markdown
+ text/org:
+ delimiter: .
+ suffixes:
+ - org
+ text/pandoc:
+ delimiter: .
+ suffixes:
+ - pandoc
+ - pdc
text/plain:
delimiter: .
suffixes:
- txt
+ text/rst:
+ delimiter: .
+ suffixes:
+ - rst
text/tsx:
delimiter: .
suffixes:
@@ -1352,143 +1417,154 @@ config:
isHTML: true
isPlainText: false
mediaType: text/html
- name: amp
noUgly: false
notAlternative: false
path: amp
permalinkable: true
protocol: ""
rel: amphtml
+ root: false
+ ugly: false
weight: 0
calendar:
baseName: index
isHTML: false
isPlainText: true
mediaType: text/calendar
- name: calendar
noUgly: false
notAlternative: false
path: ""
permalinkable: false
protocol: webcal://
rel: alternate
+ root: false
+ ugly: false
weight: 0
css:
baseName: styles
isHTML: false
isPlainText: true
mediaType: text/css
- name: css
noUgly: false
notAlternative: true
path: ""
permalinkable: false
protocol: ""
rel: stylesheet
+ root: false
+ ugly: false
weight: 0
csv:
baseName: index
isHTML: false
isPlainText: true
mediaType: text/csv
- name: csv
noUgly: false
notAlternative: false
path: ""
permalinkable: false
protocol: ""
rel: alternate
+ root: false
+ ugly: false
weight: 0
html:
baseName: index
isHTML: true
isPlainText: false
mediaType: text/html
- name: html
noUgly: false
notAlternative: false
path: ""
permalinkable: true
protocol: ""
rel: canonical
+ root: false
+ ugly: false
weight: 10
json:
baseName: index
isHTML: false
isPlainText: true
mediaType: application/json
- name: json
noUgly: false
notAlternative: false
path: ""
permalinkable: false
protocol: ""
rel: alternate
+ root: false
+ ugly: false
weight: 0
markdown:
baseName: index
isHTML: false
isPlainText: true
mediaType: text/markdown
- name: markdown
noUgly: false
notAlternative: false
path: ""
permalinkable: false
protocol: ""
rel: alternate
+ root: false
+ ugly: false
weight: 0
robots:
baseName: robots
isHTML: false
isPlainText: true
mediaType: text/plain
- name: robots
noUgly: false
notAlternative: false
path: ""
permalinkable: false
protocol: ""
rel: alternate
+ root: true
+ ugly: false
weight: 0
rss:
baseName: index
isHTML: false
isPlainText: false
mediaType: application/rss+xml
- name: rss
noUgly: true
notAlternative: false
path: ""
permalinkable: false
protocol: ""
rel: alternate
+ root: false
+ ugly: false
weight: 0
sitemap:
baseName: sitemap
isHTML: false
isPlainText: false
mediaType: application/xml
- name: sitemap
- noUgly: true
+ noUgly: false
notAlternative: false
path: ""
permalinkable: false
protocol: ""
rel: sitemap
+ root: false
+ ugly: true
weight: 0
webappmanifest:
baseName: manifest
isHTML: false
isPlainText: true
mediaType: application/manifest+json
- name: webappmanifest
noUgly: false
notAlternative: true
path: ""
permalinkable: false
protocol: ""
rel: manifest
+ root: false
+ ugly: false
weight: 0
outputs:
home:
@@ -1524,10 +1600,8 @@ config:
disqus:
disable: false
googleAnalytics:
- anonymizeIP: false
disable: false
respectDoNotTrack: false
- useSessionStorage: false
instagram:
disable: false
simple: false
@@ -1573,6 +1647,7 @@ config:
toLower: false
relativeURLs: false
removePathAccents: false
+ renderSegments: null
resourceDir: resources
sectionPagesMenu: ""
security:
@@ -1584,7 +1659,7 @@ config:
- ^npx$
- ^postcss$
osEnv:
- - (?i)^((HTTPS?|NO)_PROXY|PATH(EXT)?|APPDATA|TE?MP|TERM|GO\w+|(XDG_CONFIG_)?HOME|USERPROFILE|SSH_AUTH_SOCK|DISPLAY|LANG)$
+ - (?i)^((HTTPS?|NO)_PROXY|PATH(EXT)?|APPDATA|TE?MP|TERM|GO\w+|(XDG_CONFIG_)?HOME|USERPROFILE|SSH_AUTH_SOCK|DISPLAY|LANG|SYSTEMDRIVE)$
funcs:
getenv:
- ^HUGO_
@@ -1595,6 +1670,7 @@ config:
- (?i)GET|POST
urls:
- .*
+ segments: {}
server:
headers: null
redirects:
@@ -1616,6 +1692,7 @@ config:
disableInlineCSS: false
sitemap:
changeFreq: ""
+ disable: false
filename: sitemap.xml
priority: -1
social: null
@@ -1658,6 +1735,8 @@ config_helpers:
_merge: none
frontmatter:
_merge: none
+ httpcache:
+ _merge: none
imaging:
_merge: none
languages:
@@ -1692,6 +1771,8 @@ config_helpers:
_merge: none
security:
_merge: none
+ segments:
+ _merge: none
server:
_merge: none
services:
@@ -2494,7 +2575,7 @@ tpl:
- shuffle
Args:
- l
- Description: Shuffle returns list l in a randomised order.
+ Description: Shuffle returns list l in a randomized order.
Examples: []
Slice:
Aliases:
@@ -2762,8 +2843,8 @@ tpl:
{{ $m.Set "Hugo" "Rocks!" }}
{{ $m.Values | debug.Dump | safeHTML }}
- |-
- map[string]interface {}{
- "Hugo": "Rocks!",
+ {
+ "Hugo": "Rocks!"
}
TestDeprecationErr:
Aliases: null
@@ -2886,7 +2967,7 @@ tpl:
- format
- args
Description: Printf returns string representation of args formatted with the
- layouut in format.
+ layout in format.
Examples:
- - '{{ printf "%s!" "works" }}'
- works!
@@ -2913,6 +2994,20 @@ tpl:
Examples:
- - '{{ warnf "%s." "warning" }}'
- ""
+ Warnidf:
+ Aliases:
+ - warnidf
+ Args:
+ - id
+ - format
+ - args
+ Description: |-
+ Warnidf formats args according to a format specifier and logs an WARNING and
+ an information text that the warning with the given id can be suppressed in config.
+ It returns an empty string.
+ Examples:
+ - - '{{ warnidf "my-warn-id" "%s." "warning" }}'
+ - ""
Warnmf:
Aliases: null
Args: null
@@ -2939,6 +3034,21 @@ tpl:
Args: null
Description: ""
Examples: null
+ IsMultiHost:
+ Aliases: null
+ Args: null
+ Description: ""
+ Examples: null
+ IsMultihost:
+ Aliases: null
+ Args: null
+ Description: ""
+ Examples: null
+ IsMultilingual:
+ Aliases: null
+ Args: null
+ Description: ""
+ Examples: null
IsProduction:
Aliases: null
Args: null
@@ -2994,6 +3104,11 @@ tpl:
Args: null
Description: ""
Examples: null
+ Dither:
+ Aliases: null
+ Args: null
+ Description: ""
+ Examples: null
Filter:
Aliases: null
Args: null
@@ -3688,14 +3803,6 @@ tpl:
- s
Description: JSStr returns the given string as a html/template JSStr content.
Examples: []
- SanitizeURL:
- Aliases:
- - sanitizeURL
- - sanitizeurl
- Args:
- - s
- Description: SanitizeURL returns the string s as html/template URL content.
- Examples: []
URL:
Aliases:
- safeURL
@@ -3756,7 +3863,7 @@ tpl:
Args: null
Description: ""
Examples: null
- GetIdentity:
+ ForEeachIdentityByName:
Aliases: null
Args: null
Description: ""
@@ -3766,11 +3873,6 @@ tpl:
Args: null
Description: ""
Examples: null
- GetPageWithTemplateInfo:
- Aliases: null
- Args: null
- Description: ""
- Examples: null
GoogleAnalytics:
Aliases: null
Args: null
@@ -3796,6 +3898,11 @@ tpl:
Args: null
Description: ""
Examples: null
+ Key:
+ Aliases: null
+ Args: null
+ Description: ""
+ Examples: null
Language:
Aliases: null
Args: null
@@ -3821,6 +3928,11 @@ tpl:
Args: null
Description: ""
Examples: null
+ Lastmod:
+ Aliases: null
+ Args: null
+ Description: ""
+ Examples: null
MainSections:
Aliases: null
Args: null
@@ -3950,6 +4062,11 @@ tpl:
- s
Description: CountWords returns the approximate word count in s.
Examples: []
+ Diff:
+ Aliases: null
+ Args: null
+ Description: ""
+ Examples: null
FindRE:
Aliases:
- findRE
@@ -4514,5 +4631,5 @@ tpl:
- urlize
Args:
- s
- Description: URLize returns the the strings s formatted as an URL.
+ Description: URLize returns the strings s formatted as an URL.
Examples: []
diff --git a/data/embedded_template_urls.toml b/data/embedded_template_urls.toml
new file mode 100644
index 000000000..7bb2e4eee
--- /dev/null
+++ b/data/embedded_template_urls.toml
@@ -0,0 +1,36 @@
+# Used by the embedded template URL (eturl.html) shortcode.
+# Quoted all keys because some are not valid identifiers.
+
+# BaseURL
+'base_url' = 'https://github.com/gohugoio/hugo/blob/master/tpl/tplimpl/embedded/templates'
+
+# Templates
+'alias' = 'alias.html'
+'disqus' = 'disqus.html'
+'google_analytics' = 'google_analytics.html'
+'opengraph' = 'opengraph.html'
+'pagination' = 'pagination.html'
+'schema' = 'schema.html'
+'twitter_cards' = 'twitter_cards.html'
+
+'robots' = '_default/robots.txt'
+'rss' = '_default/rss.xml'
+'sitemap' = '_default/sitemap.xml'
+'sitemapindex' = '_default/sitemapindex.xml'
+
+# Render hooks
+'render-image' = '_default/_markup/render-image.html'
+'render-link' = '_default/_markup/render-link.html'
+'render-codeblock-goat' = '_default/_markup/render-codeblock-goat.html'
+
+# Shortcodes
+'figure' = 'shortcodes/figure.html'
+'gist' = 'shortcodes/gist.html'
+'highlight' = 'shortcodes/highlight.html'
+'instagram' = 'shortcodes/instagram.html'
+'param' = 'shortcodes/param.html'
+'ref' = 'shortcodes/ref.html'
+'relref' = 'shortcodes/relref.html'
+'twitter' = 'shortcodes/twitter.html'
+'vimeo' = 'shortcodes/vimeo.html'
+'youtube' = 'shortcodes/youtube.html'
diff --git a/data/homepagetweets.toml b/data/homepagetweets.toml
index cde241f01..b440c21df 100644
--- a/data/homepagetweets.toml
+++ b/data/homepagetweets.toml
@@ -2,264 +2,264 @@
name = "Heinrich Hartmann"
twitter_handle = "@heinrichhartman"
quote = "Working with @GoHugoIO is such a joy. Having worked with #Jekyll in the past, the near instant preview is a big win! Did not expect this to make such a huge difference."
-link = "https://twitter.com/heinrichhartman/status/1199736512264462341"
+link = "https://x.com/heinrichhartman/status/1199736512264462341"
date = 2019-11-12T00:00:00Z
[[tweet]]
name = "Joshua Steven‏‏"
twitter_handle = "@jscarto"
-quote = "Can't overstate how much I enjoy <a href='https://twitter.com/gohugoio' target='_blank'>@GoHugoIO</a>. My site is relatively small, but *18 ms* to build the whole thing made template development and proofing a breeze."
-link = "https://twitter.com/jscarto/status/1039648827815485440"
+quote = "Can't overstate how much I enjoy <a href='https://x.com/gohugoio' target='_blank'>@GoHugoIO</a>. My site is relatively small, but *18 ms* to build the whole thing made template development and proofing a breeze."
+link = "https://x.com/jscarto/status/1039648827815485440"
date = 2018-09-12T00:00:00Z
[[tweet]]
name = "Christophe Diericx"
twitter_handle = "@spcrngr_"
-quote = "The more I use <a href='https://gohugo.io' target='_blank'>gohugo.io</a>, the more I really like it. Super intuitive/powerful static site generator...great job <a href='https://twitter.com/gohugoio' target='_blank'>@GoHugoIO</a>"
-link = "https://twitter.com/spcrngr_/status/870863020905435136"
+quote = "The more I use <a href='https://gohugo.io' target='_blank'>gohugo.io</a>, the more I really like it. Super intuitive/powerful static site generator...great job <a href='https://x.com/gohugoio' target='_blank'>@GoHugoIO</a>"
+link = "https://x.com/spcrngr_/status/870863020905435136"
date = 2017-06-03T00:00:00Z
[[tweet]]
name = "marcoscan"
twitter_handle = "@marcoscan"
-quote = "Blog migrated from <a href='https://twitter.com/WordPress' target='_blank'>@WordPress</a> to <a href='https://twitter.com/GoHugoIO' target='_blank'>@GoHugoIO</a>, with a little refresh of my theme, Vim shortcuts and a full featured deploy script <a href='https://twitter.com/hashtag/gohugo?src=hash' target='_blank'>#gohugo</a>"
-link = "https://twitter.com/marcoscan/status/869661175960752129"
+quote = "Blog migrated from <a href='https://x.com/WordPress' target='_blank'>@WordPress</a> to <a href='https://x.com/GoHugoIO' target='_blank'>@GoHugoIO</a>, with a little refresh of my theme, Vim shortcuts and a full featured deploy script <a href='https://x.com/hashtag/gohugo?src=hash' target='_blank'>#gohugo</a>"
+link = "https://x.com/marcoscan/status/869661175960752129"
date = 2017-05-30T00:00:00Z
[[tweet]]
name = "Sandra Kuipers"
twitter_handle = "@SKuipersDesign"
-quote = "Who knew static site building could be fun 🤔 Learning <a href='https://twitter.com/hashtag/gohugo?src=hash'>#gohugo</a> today"
-link = "https://twitter.com/SKuipersDesign/status/868796256902029312"
+quote = "Who knew static site building could be fun 🤔 Learning <a href='https://x.com/hashtag/gohugo?src=hash'>#gohugo</a> today"
+link = "https://x.com/SKuipersDesign/status/868796256902029312"
date = 2017-05-28T00:00:00Z
[[tweet]]
name = "Netlify"
twitter_handle = "@Netlify"
-quote = "Top Ten Static Site Generators of 2017. Congrats to the top 3: 1. <a href='https://twitter.com/jekyllrb'>@Jekyllrb</a> 2. <a href='https://twitter.com/GoHugoIO'>@GoHugoIO</a> 3. <a href='https://twitter.com/hexojs'>@hexojs</a>"
-link = "https://twitter.com/Netlify/status/868122279221362688"
+quote = "Top Ten Static Site Generators of 2017. Congrats to the top 3: 1. <a href='https://x.com/jekyllrb'>@Jekyllrb</a> 2. <a href='https://x.com/GoHugoIO'>@GoHugoIO</a> 3. <a href='https://x.com/hexojs'>@hexojs</a>"
+link = "https://x.com/Netlify/status/868122279221362688"
date = 2017-05-26T00:00:00Z
[[tweet]]
name = "Phil Hawksworth"
twitter_handle = "@philhawksworth"
-quote = "I've been keen on <a href='https://twitter.com/hashtag/JAMStack?src=hash' target='_blank'>#JAMStack</a> for some time, but <a href='https://twitter.com/gohugoio' target='_blank'>@GoHugoIO</a> is wooing me all over again. Great fun to build with. And speeeeedy."
-link = "https://twitter.com/philhawksworth/status/866684170512326657"
+quote = "I've been keen on <a href='https://x.com/hashtag/JAMStack?src=hash' target='_blank'>#JAMStack</a> for some time, but <a href='https://x.com/gohugoio' target='_blank'>@GoHugoIO</a> is wooing me all over again. Great fun to build with. And speeeeedy."
+link = "https://x.com/philhawksworth/status/866684170512326657"
date = 2017-05-22T00:00:00Z
[[tweet]]
name = "Aras Pranckevicius"
twitter_handle = "@aras_p"
-quote = "I've probably said it before...but having Hugo rebuild the whole website in 300ms is amazing. <a href='https://gohugo.io' target='_blank'>gohugo.io</a>, <a href='https://twitter.com/hashtag/gohugo' target='_blank'>#gohugo</a>"
-link = "https://twitter.com/aras_p/status/861157286823288832"
+quote = "I've probably said it before...but having Hugo rebuild the whole website in 300ms is amazing. <a href='https://gohugo.io' target='_blank'>gohugo.io</a>, <a href='https://x.com/hashtag/gohugo' target='_blank'>#gohugo</a>"
+link = "https://x.com/aras_p/status/861157286823288832"
date = 2017-05-07T00:00:00Z
[[tweet]]
name = "Hans Beck"
twitter_handle = "@EnrichedGamesHB"
-quote = "Diving deeper into <a href='https://twitter.com/GoHugoIO' target='_blank' rel='noopener noreferrer'>@GoHugoIO</a>. A lot of docs there, top work! But I've the impressed that <a href='https://twitter.com/hashtag/gohugo' target='_blank' rel='noopener noreferrer'>#gohugo</a> is far easier than its feels from the docs!"
-link = "https://twitter.com/EnrichedGamesHB/status/836854762440130560"
+quote = "Diving deeper into <a href='https://x.com/GoHugoIO' target='_blank' rel='noopener noreferrer'>@GoHugoIO</a>. A lot of docs there, top work! But I've the impressed that <a href='https://x.com/hashtag/gohugo' target='_blank' rel='noopener noreferrer'>#gohugo</a> is far easier than its feels from the docs!"
+link = "https://x.com/EnrichedGamesHB/status/836854762440130560"
date = 2017-03-01T00:00:00Z
[[tweet]]
name = "Alan Richardson"
twitter_handle = "@eviltester"
-quote = "I migrated the <a href='https://twitter.com/BlackOpsTesting' target='_blank' rel='noopener noreferrer'> @BlackOpsTesting </a>.com website from docpad to Hugo last weekend. http://gohugo.io/ Super Fast HTML Generation <a href='https://twitter.com/spf13' target='_blank' rel='noopener noreferrer'> @spf13 </a>"
-link = "https://twitter.com/eviltester/status/553520335115808768"
+quote = "I migrated the <a href='https://x.com/BlackOpsTesting' target='_blank' rel='noopener noreferrer'> @BlackOpsTesting </a>.com website from docpad to Hugo last weekend. http://gohugo.io/ Super Fast HTML Generation <a href='https://x.com/spf13' target='_blank' rel='noopener noreferrer'> @spf13 </a>"
+link = "https://x.com/eviltester/status/553520335115808768"
date = 2015-01-09T00:00:00Z
[[tweet]]
name = "Janez Čadež‏"
twitter_handle = "@jamziSLO"
-quote = "Building <a href='https://twitter.com/garazaFRI' target='_blank' rel='noopener noreferrer'>@garazaFRI</a> website in <a href='https://twitter.com/hashtag/hugo' target='_blank' rel='noopener noreferrer'>#hugo</a>. This static site generator is soooo damn fast! <a href='https://twitter.com/hashtag/gohugo' target='_blank' rel='noopener noreferrer'>#gohugo</a> <a href='https://twitter.com/hashtag/golang' target='_blank' rel='noopener noreferrer'>#golang</a>"
-link = "https://twitter.com/jamziSLO/status/817720283977183234"
+quote = "Building <a href='https://x.com/garazaFRI' target='_blank' rel='noopener noreferrer'>@garazaFRI</a> website in <a href='https://x.com/hashtag/hugo' target='_blank' rel='noopener noreferrer'>#hugo</a>. This static site generator is soooo damn fast! <a href='https://x.com/hashtag/gohugo' target='_blank' rel='noopener noreferrer'>#gohugo</a> <a href='https://x.com/hashtag/golang' target='_blank' rel='noopener noreferrer'>#golang</a>"
+link = "https://x.com/jamziSLO/status/817720283977183234"
date = 2017-01-07T00:00:00Z
[[tweet]]
name = "Execute‏‏"
twitter_handle = "@executerun"
-quote = "Hah, <a href='https://twitter.com/hashtag/gohugo' target='_blank' rel='noopener noreferrer'>#gohugo</a>. I was working with <a href='https://twitter.com/hashtag/gohugo' target='_blank' rel='noopener noreferrer'>#gohugo</a> on <a href='https://twitter.com/hashtag/linux' target='_blank' rel='noopener noreferrer'>#linux</a> but now I realised how easy is to set-up it on <a href='https://twitter.com/hashtag/windows' target='_blank' rel='noopener noreferrer'>#windows</a>. Just need to add binary to <a href='https://twitter.com/hashtag/path' target='_blank' rel='noopener noreferrer'>#path</a>!"
-link = "https://twitter.com/executerun/status/809753145270272005"
+quote = "Hah, <a href='https://x.com/hashtag/gohugo' target='_blank' rel='noopener noreferrer'>#gohugo</a>. I was working with <a href='https://x.com/hashtag/gohugo' target='_blank' rel='noopener noreferrer'>#gohugo</a> on <a href='https://x.com/hashtag/linux' target='_blank' rel='noopener noreferrer'>#linux</a> but now I realised how easy is to set-up it on <a href='https://x.com/hashtag/windows' target='_blank' rel='noopener noreferrer'>#windows</a>. Just need to add binary to <a href='https://x.com/hashtag/path' target='_blank' rel='noopener noreferrer'>#path</a>!"
+link = "https://x.com/executerun/status/809753145270272005"
date = 2016-12-16T00:00:00Z
[[tweet]]
name = "Baron Schwartz"
twitter_handle = "@xaprb"
-quote = "Hugo is impressively capable. It's a static site generator by <a href='https://twitter.com/spf13'> @spf13 </a> written in <a href='https://twitter.com/hashtag/golang?src=hash'> #golang </a> . Just upgraded to latest release; very powerful. "
-link = "https://twitter.com/xaprb/status/556894866488455169"
+quote = "Hugo is impressively capable. It's a static site generator by <a href='https://x.com/spf13'> @spf13 </a> written in <a href='https://x.com/hashtag/golang?src=hash'> #golang </a> . Just upgraded to latest release; very powerful. "
+link = "https://x.com/xaprb/status/556894866488455169"
date = 2015-01-18T00:00:00Z
[[tweet]]
name = "Dave Cottlehuber"
twitter_handle = "@dch__"
quote = "I just fell in love with #hugo, a static site/blog engine written by @spf13 in #golang + stellar docs"
-link = "https://twitter.com/dch__/status/460158115498176512"
+link = "https://x.com/dch__/status/460158115498176512"
date = 2014-04-26T00:00:00Z
[[tweet]]
name = "David Caunt"
twitter_handle = "@dcaunt"
quote = "I had a play with Hugo and it was good, uses Markdown files for content"
-link = "https://twitter.com/dcaunt/statuses/406466996277374976"
+link = "https://x.com/dcaunt/statuses/406466996277374976"
date = 2013-11-29T00:00:00Z
[[tweet]]
name = "David Gay"
twitter_handle = "@oddshocks"
quote = "Hugo is super-rad."
-link = "https://twitter.com/oddshocks/statuses/405083217893421056"
+link = "https://x.com/oddshocks/statuses/405083217893421056"
date = 2013-11-25T00:00:00Z
[[tweet]]
name = "Diti"
twitter_handle = "@DitiPengi"
quote = "The dev version of Hugo is AWESOME! &lt;3 I promise, I will try to learn go ASAP and help contribute to the project! Just too great!"
-link = "https://twitter.com/DitiPengi/status/472470974051676160"
+link = "https://x.com/DitiPengi/status/472470974051676160"
date = 2014-05-30T00:00:00Z
[[tweet]]
name = "Douglas Stephen "
twitter_handle = "@DougStephenJr"
quote = "Even as a long-time Octopress fan, I’ve gotta admit that this project Hugo looks very very cool"
-link = "https://twitter.com/DougStephenJr/statuses/364512471660249088"
+link = "https://x.com/DougStephenJr/statuses/364512471660249088"
date = 2013-08-05T00:00:00Z
[[tweet]]
name = "Hugo Rodger-Brown"
twitter_handle = "@hugorodgerbrown"
quote = "Finally someone builds me my own static site generator"
-link = "https://twitter.com/hugorodgerbrown/statuses/364417910153818112"
+link = "https://x.com/hugorodgerbrown/statuses/364417910153818112"
date = 2013-05-08T00:00:00Z
[[tweet]]
name = "Hugo Roy"
twitter_handle = "@hugoroyd"
quote = "Finally the answer to the question my parents have been asking: What does Hugo do?"
-link = "https://twitter.com/hugoroyd/status/501704796727173120"
+link = "https://x.com/hugoroyd/status/501704796727173120"
date = 2014-08-19T00:00:00Z
[[tweet]]
name = "Daniel Miessler"
twitter_handle = "@DanielMiessler"
quote = "Websites for named vulnerabilities should run on static site generator platforms like Hugo. Read-only + burst traffic = static."
-link = "https://twitter.com/DanielMiessler/status/704703841673957376"
+link = "https://x.com/DanielMiessler/status/704703841673957376"
date = 2016-03-01T00:00:00Z
[[tweet]]
name = "Javier Segura"
twitter_handle = "@jsegura"
quote = "Another site generated with Hugo here! I'm getting in love with it."
-link = "https://twitter.com/jsegura/status/465978434154659841"
+link = "https://x.com/jsegura/status/465978434154659841"
date = 2014-05-12T00:00:00Z
[[tweet]]
name = "Jim Biancolo"
twitter_handle = "@jimbiancolo"
quote = "I’m loving the static site generator renaissance we are currently enjoying. Hugo is new, looks great, written in Go"
-link = "https://twitter.com/jimbiancolo/statuses/408678420348813314"
+link = "https://x.com/jimbiancolo/statuses/408678420348813314"
date = 2013-05-12T00:00:00Z
[[tweet]]
name = "Jip J. Dekker"
twitter_handle = "@jipjdekker"
quote = "Building a personal website in Hugo. Works like a charm. And written in @golang!"
-link = "https://twitter.com/jipjdekker/status/413783548735152131"
+link = "https://x.com/jipjdekker/status/413783548735152131"
date = 2013-12-19T00:00:00Z
[[tweet]]
name = "Jose Gonzalvo"
twitter_handle = "@jgonzalvo"
quote = "Checking out Hugo; Loving it so far. Like Jekyll but not so blog-oriented and written in go"
-link = "https://twitter.com/jgonzalvo/statuses/408177855819173888"
+link = "https://x.com/jgonzalvo/statuses/408177855819173888"
date = 2013-12-04T00:00:00Z
[[tweet]]
name = "Josh Matz"
twitter_handle = "@joshmatz"
quote = "A static site generator without the long build times? Yes, please!"
-link = "https://twitter.com/joshmatz/statuses/364437436870696960"
+link = "https://x.com/joshmatz/statuses/364437436870696960"
date = 2013-08-05T00:00:00Z
[[tweet]]
name = "Kieran Healy"
twitter_handle = "@kjhealy"
quote = "OK, so in today's speed battle of static site generators, @spf13's hugo is kicking everyone's ass, by miles."
-link = "https://twitter.com/kjhealy/status/437349384809115648"
+link = "https://x.com/kjhealy/status/437349384809115648"
date = 2014-02-22T00:00:00Z
[[tweet]]
name = "Ludovic Chabant"
twitter_handle = "@ludovicchabant"
quote = "Good work on Hugo, I’m impressed with the speed!"
-link = "https://twitter.com/ludovicchabant/statuses/408806199602053120"
+link = "https://x.com/ludovicchabant/statuses/408806199602053120"
date = 2013-12-06T00:00:00Z
[[tweet]]
name = "Luke Holder"
twitter_handle = "@lukeholder"
quote = "this is AWESOME. a single little executable and so fast."
-link = "https://twitter.com/lukeholder/status/430352287936946176"
+link = "https://x.com/lukeholder/status/430352287936946176"
date = 2014-02-03T00:00:00Z
[[tweet]]
name = "Markus Eliasson"
twitter_handle = "@markuseliasson"
quote = "Hugo is fast, dead simple to setup and well documented"
-link = "https://twitter.com/markuseliasson/status/501594865877008384"
+link = "https://x.com/markuseliasson/status/501594865877008384"
date = 2014-08-19T00:00:00Z
[[tweet]]
name = "mercime"
twitter_handle = "@mercime_one"
quote = "Hugo: Makes the Web Fun Again"
-link = "https://twitter.com/mercime_one/status/500547145087205377"
+link = "https://x.com/mercime_one/status/500547145087205377"
date = 2014-08-16T00:00:00Z
[[tweet]]
name = "Michael Whatcott"
twitter_handle = "@mdwhatcott"
quote = "One more satisfied #Hugo blogger. Thanks @spf13 and friends!"
-link = "https://twitter.com/mdwhatcott/status/469980686531571712"
+link = "https://x.com/mdwhatcott/status/469980686531571712"
date = 2014-05-23T00:00:00Z
[[tweet]]
name = "Nathan Toups"
twitter_handle = "@rojoroboto"
quote = "I love Hugo! My site is generated with it now http://rjrbt.io"
-link = "https://twitter.com/rojoroboto/status/423439915620106242"
+link = "https://x.com/rojoroboto/status/423439915620106242"
date = 2014-01-15T00:00:00Z
[[tweet]]
name = "Ruben Solvang"
twitter_handle = "@messo85"
quote = "#Hugo is the new @jekyllrb / @middlemanapp! Faster, easier and runs everywhere."
-link = "https://twitter.com/messo85/status/472825062027182081"
+link = "https://x.com/messo85/status/472825062027182081"
date = 2014-05-31T00:00:00Z
[[tweet]]
name = "Ryan Martinsen"
twitter_handle = "@popthestack"
quote = "Also, I re-launched my blog (it looks the same as before) using Hugo, a *fast* static engine. Very happy with it. <a href='http://gohugo.io/'>gohugo.io</a>"
-link = "https://twitter.com/popthestack/status/549972754125307904"
+link = "https://x.com/popthestack/status/549972754125307904"
date = 2014-12-30T00:00:00Z
[[tweet]]
name = "The Lone Cuber"
twitter_handle = "@TheLoneCuber"
quote = "Jekyll is dead to me these days though... long live Hugo! Hugo is *by far* the best in its field. Thanks for making it happen."
-link = "https://twitter.com/TheLoneCuber/status/495716684456398848"
+link = "https://x.com/TheLoneCuber/status/495716684456398848"
date = 2014-08-02T00:00:00Z
[[tweet]]
name = "The Lone Cuber"
twitter_handle = "@TheLoneCuber"
quote = "Finally, a publishing platform that's a joy to use. #NoMoreBarriers"
-link = "https://twitter.com/TheLoneCuber/status/495731334711488512"
+link = "https://x.com/TheLoneCuber/status/495731334711488512"
date = 2014-08-02T00:00:00Z
[[tweet]]
name = "WorkHTML"
twitter_handle = "@workhtml"
-quote = "<a href='https://twitter.com/hashtag/Hugo?src=hash'> #Hugo </a> A very good alternative for <a href='https://twitter.com/hashtag/wordpress?src=hash'> #wordpress </a> !!! A fast and modern static website engine <a href='http://gohugo.io/'> gohugo.io </a>"
-link = "https://twitter.com/workhtml/status/563064361301053440"
+quote = "<a href='https://x.com/hashtag/Hugo?src=hash'> #Hugo </a> A very good alternative for <a href='https://x.com/hashtag/wordpress?src=hash'> #wordpress </a> !!! A fast and modern static website engine <a href='http://gohugo.io/'> gohugo.io </a>"
+link = "https://x.com/workhtml/status/563064361301053440"
date = 2015-02-04T00:00:00Z
diff --git a/data/page_filters.yaml b/data/page_filters.yaml
index 2a3a8625d..a4969e9b7 100644
--- a/data/page_filters.yaml
+++ b/data/page_filters.yaml
@@ -12,6 +12,7 @@ functions_fmt_logging:
- /functions/fmt/errorf
- /functions/fmt/erroridf
- /functions/fmt/warnf
+ - /functions/fmt/warnidf
functions_images_no_filters:
- /functions/images/filter
- /functions/images/config
@@ -21,6 +22,7 @@ methods_site_multilingual:
- /methods/site/languageprefix
- /methods/site/languages
methods_site_page_collections:
+ - /methods/site/allpages
- /methods/site/pages
- /methods/site/regularpages
- /methods/site/sections
diff --git a/go.mod b/go.mod
index e3420f6ae..ca0acd79f 100644
--- a/go.mod
+++ b/go.mod
@@ -2,4 +2,4 @@ module github.com/gohugoio/hugoDocs
go 1.16
-require github.com/gohugoio/gohugoioTheme v0.0.0-20240201183016-8e648a3b5342 // indirect
+require github.com/gohugoio/gohugoioTheme v0.0.0-20240619093131-b595d5fb8c52 // indirect
diff --git a/go.sum b/go.sum
index e6a4fcd6c..a1664d320 100644
--- a/go.sum
+++ b/go.sum
@@ -1,2 +1,6 @@
-github.com/gohugoio/gohugoioTheme v0.0.0-20240201183016-8e648a3b5342 h1:jQaO+i2osHeIZ+V7Dvo7CPqN6jPwMRjt7b9QaX7HXE4=
-github.com/gohugoio/gohugoioTheme v0.0.0-20240201183016-8e648a3b5342/go.mod h1:GOYeAPQJ/ok8z7oz1cjfcSlsFpXrmx6VkzQ5RpnyhZM=
+github.com/gohugoio/gohugoioTheme v0.0.0-20240426212330-f38e99e0d88d h1:EaFz80Aqh3Ej20VmUSNe3K+F0NbT8UueXLP/VqkK9Dw=
+github.com/gohugoio/gohugoioTheme v0.0.0-20240426212330-f38e99e0d88d/go.mod h1:GOYeAPQJ/ok8z7oz1cjfcSlsFpXrmx6VkzQ5RpnyhZM=
+github.com/gohugoio/gohugoioTheme v0.0.0-20240508091825-b23e8e2d2419 h1:cQ/44eDHK0tVImTtSx/9sWWZv+RynH/oB4R7ASbQNAE=
+github.com/gohugoio/gohugoioTheme v0.0.0-20240508091825-b23e8e2d2419/go.mod h1:GOYeAPQJ/ok8z7oz1cjfcSlsFpXrmx6VkzQ5RpnyhZM=
+github.com/gohugoio/gohugoioTheme v0.0.0-20240619093131-b595d5fb8c52 h1:dPJxUU4SevIZ7OS1DIVOrJ7p8I/QM00pXGRfAtKgQmU=
+github.com/gohugoio/gohugoioTheme v0.0.0-20240619093131-b595d5fb8c52/go.mod h1:GOYeAPQJ/ok8z7oz1cjfcSlsFpXrmx6VkzQ5RpnyhZM=
diff --git a/hugo.toml b/hugo.toml
index 209231663..63cc32798 100644
--- a/hugo.toml
+++ b/hugo.toml
@@ -29,7 +29,7 @@ ID = 'G-MBZGKNMDWC'
[outputs]
home = ["HTML", "RSS", "REDIR", "HEADERS"]
- section = ["HTML", "RSS"]
+ section = ["HTML"]
[mediaTypes]
[mediaTypes."text/netlify"]
diff --git a/layouts/_default/baseof.html b/layouts/_default/baseof.html
deleted file mode 100644
index beb2d8619..000000000
--- a/layouts/_default/baseof.html
+++ /dev/null
@@ -1,124 +0,0 @@
-<!doctype html>
-<html
- class="no-js"
- lang="{{ with $.Site.LanguageCode }}
- {{ . }}
- {{ else }}
- en-us
- {{ end }}
- ">
- <head>
- <meta charset="utf-8" />
- {{/* https://www.zachleat.com/web/preload/ */}}
- <link
- rel="preload"
- href="{{ "fonts/muli-latin-200.woff2" | absURL }}"
- as="font"
- type="font/woff2"
- crossorigin />
- <link
- rel="preload"
- href="{{ "fonts/muli-latin-400.woff2" | absURL }}"
- as="font"
- type="font/woff2"
- crossorigin />
- <link
- rel="preload"
- href="{{ "fonts/muli-latin-800.woff2" | absURL }}"
- as="font"
- type="font/woff2"
- crossorigin />
-
- <meta http-equiv="X-UA-Compatible" content="IE=edge" />
- {{/* NOTE: the Site's title, and if there is a page title, that is set too */}}
- <title>
- {{ block "title" . }}
- {{ with .Title }}{{ . }} | {{ end }}{{ .Site.Title }}
- {{ end }}
-
- </title>
-
- <meta name="viewport" content="width=device-width,minimum-scale=1" />
- {{ hugo.Generator }}
-
- {{ if hugo.IsProduction }}
- <meta name="robots" content="index, follow" />
- {{ else }}
- <meta name="robots" content="noindex, nofollow" />
- {{ end }}
-
- {{ range .AlternativeOutputFormats -}}
- <link
- rel="{{ .Rel }}"
- type="{{ .MediaType.Type }}"
- href="{{ .Permalink | safeURL }}" />
- {{ end -}}
-
- {{ $isDev := eq hugo.Environment "development" }}
- {{ $stylesheet := resources.Get "output/css/app.css" }}
- {{ if not $isDev }}
- {{ $stylesheet = $stylesheet | minify | fingerprint }}
- {{ end }}
- {{ with $stylesheet }}
- {{ if $isDev }}
- <link
- rel="stylesheet"
- href="{{ .RelPermalink }}"
- crossorigin="anonymous" />
- {{ else }}
- <link
- rel="stylesheet"
- href="{{ .RelPermalink }}"
- integrity="{{ .Data.Integrity }}"
- crossorigin="anonymous" />
- {{ end }}
- {{ $.Scratch.Set "stylesheet" . }}
- {{ end }}
-
-
- <meta
- name="description"
- content="{{ with .Description }}
- {{ . }}
- {{ else }}
- {{ with .Site.Params.description }}{{ . }}{{ end }}
- {{ end }}
- " />
-
- {{ block "scripts" . }}
- {{- partial "site-scripts.html" . -}}
- {{ end }}
- {{ partial "site-manifest.html" . }}
- {{- partial "head-additions.html" . -}}
- {{- partial "opengraph/opengraph.html" . -}}
- {{- template "_internal/schema.html" . -}}
- {{- partial "opengraph/twitter_cards.html" . -}}
-
- {{ if hugo.IsProduction }}
- {{ partial "gtag.html" . }}
- {{ end }}
-
- {{ $hasMath := .Param "math" }}
- {{ if $hasMath }}
- {{ partialCached "math.html" . }}
- {{ end }}
-
- </head>
-
- <body
- class="ma0 sans-serif bg-primary-color-light{{ with getenv "HUGO_ENV" }}
- {{ . }}
- {{ end }} {{ if $hasMath }}{{ print " dn" }}{{ end }}">
- {{ partial "hooks/after-body-start.html" . }}
- {{ block "nav" . }}{{ partial "site-nav.html" . }}{{ end }}
- {{ block "header" . }}{{ end }}
- <main role="main" class="content-with-sidebar min-vh-100 pb7 pb0-ns">
- {{ block "main" . }}{{ end }}
- </main>
-
- {{ block "footer" . }}{{ partialCached "site-footer.html" . }}{{ end }}
-
- {{ partial "hooks/before-body-end.html" . }}
-
- </body>
-</html>
diff --git a/layouts/partials/math.html b/layouts/partials/math.html
deleted file mode 100644
index b1eb5c8db..000000000
--- a/layouts/partials/math.html
+++ /dev/null
@@ -1,16 +0,0 @@
-<script id="MathJax-script" async src="https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-chtml.js"></script>
-<script>
- MathJax = {
- tex: {
- inlineMath: [['$', '$'], ['\\(', '\\)']], // inline
- displayMath: [['$$', '$$'], ['\\[', '\\]']] // block
- },
- startup: {
- pageReady: () => {
- return MathJax.startup.defaultPageReady().then(() => {
- document.body.classList.remove("dn");
- });
- }
- }
- };
-</script>
diff --git a/netlify.toml b/netlify.toml
index c65cd903e..54f157413 100644
--- a/netlify.toml
+++ b/netlify.toml
@@ -3,7 +3,7 @@
command = "hugo --gc --minify"
[build.environment]
- HUGO_VERSION = "0.122.0"
+ HUGO_VERSION = "0.127.0"
[context.production.environment]
HUGO_ENV = "production"
diff --git a/static/images/hosting-and-deployment/hosting-on-netlify/netlify-add-new-site.jpg b/static/images/hosting-and-deployment/hosting-on-netlify/netlify-add-new-site.jpg
deleted file mode 100644
index 17698d34a..000000000
--- a/static/images/hosting-and-deployment/hosting-on-netlify/netlify-add-new-site.jpg
+++ /dev/null
Binary files differ
diff --git a/static/images/hosting-and-deployment/hosting-on-netlify/netlify-authorize-added-permissions.jpg b/static/images/hosting-and-deployment/hosting-on-netlify/netlify-authorize-added-permissions.jpg
deleted file mode 100644
index eaae924e4..000000000
--- a/static/images/hosting-and-deployment/hosting-on-netlify/netlify-authorize-added-permissions.jpg
+++ /dev/null
Binary files differ
diff --git a/static/images/hosting-and-deployment/hosting-on-netlify/netlify-create-new-site-step-1.jpg b/static/images/hosting-and-deployment/hosting-on-netlify/netlify-create-new-site-step-1.jpg
deleted file mode 100644
index 347477dd2..000000000
--- a/static/images/hosting-and-deployment/hosting-on-netlify/netlify-create-new-site-step-1.jpg
+++ /dev/null
Binary files differ
diff --git a/static/images/hosting-and-deployment/hosting-on-netlify/netlify-create-new-site-step-2.jpg b/static/images/hosting-and-deployment/hosting-on-netlify/netlify-create-new-site-step-2.jpg
deleted file mode 100644
index 18bfd6fed..000000000
--- a/static/images/hosting-and-deployment/hosting-on-netlify/netlify-create-new-site-step-2.jpg
+++ /dev/null
Binary files differ
diff --git a/static/images/hosting-and-deployment/hosting-on-netlify/netlify-create-new-site-step-3.jpg b/static/images/hosting-and-deployment/hosting-on-netlify/netlify-create-new-site-step-3.jpg
deleted file mode 100644
index 6f9b6477c..000000000
--- a/static/images/hosting-and-deployment/hosting-on-netlify/netlify-create-new-site-step-3.jpg
+++ /dev/null
Binary files differ
diff --git a/static/images/hosting-and-deployment/hosting-on-netlify/netlify-deploy-published.jpg b/static/images/hosting-and-deployment/hosting-on-netlify/netlify-deploy-published.jpg
deleted file mode 100644
index ed5eaf3c8..000000000
--- a/static/images/hosting-and-deployment/hosting-on-netlify/netlify-deploy-published.jpg
+++ /dev/null
Binary files differ
diff --git a/static/images/hosting-and-deployment/hosting-on-netlify/netlify-deploying-site.gif b/static/images/hosting-and-deployment/hosting-on-netlify/netlify-deploying-site.gif
deleted file mode 100644
index c1f27c236..000000000
--- a/static/images/hosting-and-deployment/hosting-on-netlify/netlify-deploying-site.gif
+++ /dev/null
Binary files differ
diff --git a/static/images/hosting-and-deployment/hosting-on-netlify/netlify-first-authorize.jpg b/static/images/hosting-and-deployment/hosting-on-netlify/netlify-first-authorize.jpg
deleted file mode 100644
index 748122e89..000000000
--- a/static/images/hosting-and-deployment/hosting-on-netlify/netlify-first-authorize.jpg
+++ /dev/null
Binary files differ
diff --git a/static/images/hosting-and-deployment/hosting-on-netlify/netlify-live-site.jpg b/static/images/hosting-and-deployment/hosting-on-netlify/netlify-live-site.jpg
deleted file mode 100644
index 3edc49c43..000000000
--- a/static/images/hosting-and-deployment/hosting-on-netlify/netlify-live-site.jpg
+++ /dev/null
Binary files differ
diff --git a/static/images/hosting-and-deployment/hosting-on-netlify/netlify-push-to-deploy.jpg b/static/images/hosting-and-deployment/hosting-on-netlify/netlify-push-to-deploy.jpg
deleted file mode 100644
index f23626218..000000000
--- a/static/images/hosting-and-deployment/hosting-on-netlify/netlify-push-to-deploy.jpg
+++ /dev/null
Binary files differ
diff --git a/static/images/hosting-and-deployment/hosting-on-netlify/netlify-signup.jpg b/static/images/hosting-and-deployment/hosting-on-netlify/netlify-signup.jpg
deleted file mode 100644
index cd9a218b4..000000000
--- a/static/images/hosting-and-deployment/hosting-on-netlify/netlify-signup.jpg
+++ /dev/null
Binary files differ
diff --git a/static/share/hugo-tall.png b/static/shared/branding/hugo-tall.png
index 001ce5eb3..001ce5eb3 100644
--- a/static/share/hugo-tall.png
+++ b/static/shared/branding/hugo-tall.png
Binary files differ
diff --git a/static/share/made-with-hugo-dark.png b/static/shared/branding/made-with-hugo-dark.png
index c6cadf283..c6cadf283 100644
--- a/static/share/made-with-hugo-dark.png
+++ b/static/shared/branding/made-with-hugo-dark.png
Binary files differ
diff --git a/static/share/made-with-hugo-long-dark.png b/static/shared/branding/made-with-hugo-long-dark.png
index 1e49995fb..1e49995fb 100644
--- a/static/share/made-with-hugo-long-dark.png
+++ b/static/shared/branding/made-with-hugo-long-dark.png
Binary files differ
diff --git a/static/share/made-with-hugo-long.png b/static/shared/branding/made-with-hugo-long.png
index c5df534cf..c5df534cf 100644
--- a/static/share/made-with-hugo-long.png
+++ b/static/shared/branding/made-with-hugo-long.png
Binary files differ
diff --git a/static/share/made-with-hugo.png b/static/shared/branding/made-with-hugo.png
index 52dfd19e5..52dfd19e5 100644
--- a/static/share/made-with-hugo.png
+++ b/static/shared/branding/made-with-hugo.png
Binary files differ
diff --git a/static/share/powered-by-hugo-dark.png b/static/shared/branding/powered-by-hugo-dark.png
index a8e2ebc80..a8e2ebc80 100644
--- a/static/share/powered-by-hugo-dark.png
+++ b/static/shared/branding/powered-by-hugo-dark.png
Binary files differ
diff --git a/static/share/powered-by-hugo-long-dark.png b/static/shared/branding/powered-by-hugo-long-dark.png
index 1b760b1bf..1b760b1bf 100644
--- a/static/share/powered-by-hugo-long-dark.png
+++ b/static/shared/branding/powered-by-hugo-long-dark.png
Binary files differ
diff --git a/static/share/powered-by-hugo-long.png b/static/shared/branding/powered-by-hugo-long.png
index 37131359d..37131359d 100644
--- a/static/share/powered-by-hugo-long.png
+++ b/static/shared/branding/powered-by-hugo-long.png
Binary files differ
diff --git a/static/share/powered-by-hugo.png b/static/shared/branding/powered-by-hugo.png
index 27ff099d5..27ff099d5 100644
--- a/static/share/powered-by-hugo.png
+++ b/static/shared/branding/powered-by-hugo.png
Binary files differ
diff --git a/static/shared/examples/data/books.json b/static/shared/examples/data/books.json
new file mode 100644
index 000000000..ae2f36db2
--- /dev/null
+++ b/static/shared/examples/data/books.json
@@ -0,0 +1,55 @@
+[
+ {
+ "author": "Victor Hugo",
+ "cover": "https://gohugo.io/shared/examples/images/the-hunchback-of-notre-dame.webp",
+ "date": "2024-05-06",
+ "isbn": "978-0140443530",
+ "rating": 4,
+ "summary": "In the vaulted Gothic towers of **Notre-Dame Cathedral** lives Quasimodo, the hunchbacked bellringer. Mocked and shunned for his appearance, he is pitied only by Esmerelda, a beautiful gypsy dancer to whom he becomes completely devoted. Esmerelda, however, has also attracted the attention of the sinister archdeacon Claude Frollo, and when she rejects his lecherous approaches, Frollo hatches a plot to destroy her, that only Quasimodo can prevent. Victor Hugo's sensational, evocative novel brings life to the medieval Paris he loved, and mourns its passing in one of the greatest historical romances of the nineteenth century.",
+ "tags": [
+ "fiction",
+ "historical"
+ ],
+ "title": "The Hunchback of Notre Dame"
+ },
+ {
+ "author": "Victor Hugo",
+ "cover": "https://gohugo.io/shared/examples/images/les-misérables.webp",
+ "date": "2022-12-30",
+ "isbn": "978-0451419439",
+ "rating": 5,
+ "summary": "Introducing one of the most **famous characters** in literature, Jean Valjean—the noble peasant imprisoned for stealing a loaf of bread—Les Misérables ranks among the greatest novels of all time. In it, Victor Hugo takes readers deep into the Parisian underworld, immerses them in a battle between good and evil, and carries them to the barricades during the uprising of 1832 with a breathtaking realism that is unsurpassed in modern prose.",
+ "tags": [
+ "fiction",
+ "historical",
+ "revolution"
+ ],
+ "title": "Les Misérables"
+ },
+ {
+ "author": "Alexis de Tocqueville",
+ "cover": "https://gohugo.io/shared/examples/images/the-ancien-régime-and-the-revolution.webp",
+ "date": "2023-04-01",
+ "isbn": "978-0141441641",
+ "rating": 3,
+ "summary": "The Ancien Régime and the Revolution is a comparison of **revolutionary France** and the despotic rule it toppled. Alexis de Tocqueville (1805–59) is an objective observer of both periods – providing a merciless critique of the ancien régime, with its venality, oppression and inequality, yet acknowledging the reforms introduced under Louis XVI, and claiming that the post-Revolution state was in many ways as tyrannical as that of the King; its once lofty and egalitarian ideals corrupted and forgotten. Writing in the 1850s, Tocqueville wished to expose the return to despotism he witnessed in his own time under Napoleon III, by illuminating the grand, but ultimately doomed, call to liberty made by the French people in 1789. His eloquent and instructive study raises questions about liberty, nationalism and justice that remain urgent today.",
+ "tags": [
+ "nonfiction",
+ "revolution"
+ ],
+ "title": "The Ancien Régime and the Revolution"
+ },
+ {
+ "author": "François Furet",
+ "cover": "https://gohugo.io/shared/examples/images/interpreting-the-french-revolution.webp",
+ "date": "2024-01-12",
+ "isbn": "978-0521280495",
+ "rating": 5,
+ "summary": "The French Revolution is an historical event **unlike any other**. It is more than just a topic of intellectual interest: it has become part of a moral and political heritage. But after two centuries, this central event in French history has usually been thought of in much the same terms as it was by its contemporaries. There have been many accounts of the French Revolution, and though their opinions differ, they have often been commemorative or anniversary interpretations of the original event. The dividing line of revolutionary historiography, in intellectual terms, is therefore not between the right and the left, but between commemorative and conceptual history, as exemplified respectively in the works of Michelet and Tocquevifle. In this book, François Furet analyses how an event like the French Revolution can be conceptualised, and identifies the radically new changes the Revolution produced as well as the continuity it provided, albeit under the appearance of change. This question has become a riddle for the European left, answered neither by Marx nor by the theorists of our own century. In his analysis of the tragic relevance of the Revolution, Furet both refers to contemporary experience and discusses various elements in the work of Alexis de Tocclueville and that of Augustin Cochin, which has never been systematically applied by historians of the Revolution. Furet's book is based on the complementary ideas of these two writers in an attempt to cut through the apparent and misleading clarity of various contradictory views of the Revolution, and to help decipher some of the enigmatic problems of revolutionary ideology. It will be of value to historians of modern Europe and their students; to political, social and economic historians; to sociologists; and to students of political thought.",
+ "tags": [
+ "nonfiction",
+ "revolution"
+ ],
+ "title": "Interpreting the French Revolution"
+ }
+]
diff --git a/static/shared/examples/images/interpreting-the-french-revolution.webp b/static/shared/examples/images/interpreting-the-french-revolution.webp
new file mode 100644
index 000000000..4004b6613
--- /dev/null
+++ b/static/shared/examples/images/interpreting-the-french-revolution.webp
Binary files differ
diff --git a/static/shared/examples/images/les-misérables.webp b/static/shared/examples/images/les-misérables.webp
new file mode 100644
index 000000000..e336a5f16
--- /dev/null
+++ b/static/shared/examples/images/les-misérables.webp
Binary files differ
diff --git a/static/shared/examples/images/the-ancien-régime-and-the-revolution.webp b/static/shared/examples/images/the-ancien-régime-and-the-revolution.webp
new file mode 100644
index 000000000..f35183945
--- /dev/null
+++ b/static/shared/examples/images/the-ancien-régime-and-the-revolution.webp
Binary files differ
diff --git a/static/shared/examples/images/the-hunchback-of-notre-dame.webp b/static/shared/examples/images/the-hunchback-of-notre-dame.webp
new file mode 100644
index 000000000..f13e2224a
--- /dev/null
+++ b/static/shared/examples/images/the-hunchback-of-notre-dame.webp
Binary files differ