diff options
Diffstat (limited to 'content/en')
423 files changed, 7056 insertions, 4236 deletions
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 (< 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.| +`content.value`|The content value as a string.| +`dates.date`|The page creation date as a `time.Time` value.| +`dates.expiryDate`|The page expiry date as a `time.Time` value.| +`dates.lastmod`|The page last modification date as a `time.Time` value.| +`dates.publishDate`|The page publication date as a `time.Time` value.| +`kind`|The [page kind]. Default is `page`.| +`params`|A map of page parameters.| +`path`|The page's [logical path] relative to the content adapter. Do not include a leading slash or file extension.|:heavy_check_mark: +`title`|The page title.| + +{{% note %}} +While `path` is the only required field, we recommend setting `title` as well. + +When setting the `path`, Hugo transforms the given string to a logical path. For example, setting `path` to `A B C` produces a logical path of `/section/a-b-c`. +{{% /note %}} + +## 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.| +`params`|A map of resource parameters.| +`path`|The resources's [logical path] relative to the content adapter. Do not include a leading slash.|:heavy_check_mark: +`title`|The resource title.| + +{{% note %}} +If the `content.value` is a string Hugo creates a new resource. If the `content.value` is a resource, Hugo obtains the value from the existing resource. + +When setting the `path`, Hugo transforms the given string to a logical path. For example, setting `path` to `A B C/cover.jpg` produces a logical path of `/section/a-b-c/cover.jpg`. +{{% /note %}} + +## 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 [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 § 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 [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 ` )`. - -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 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 [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 [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.— +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&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 [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 [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>` → `<p style="color: red;">…</p>` -* `<p style="{{ .Params.style }}">…</p>` → `<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. <a href="https://creativecommons.org/licenses by/4.0/">Some rights reserved</a>.</p> +<em>emphasized</em> ``` -[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+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>` → `<script>var form_619c16f;…</script>` -* `<script>var form_{{ .Params.hash }};…</script>` → `<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 Binary files differnew file mode 100644 index 000000000..62baa4563 --- /dev/null +++ b/content/en/functions/strings/Diff/diff-screen-capture.png 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: + + 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 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 & 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 `”`|`”`|right double quote `’`|`’`|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 [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 [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 [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 [details](/hugo-pipes/introduction/). +The `archetypes` directory contains templates for new content. See [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 [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 [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 [details](/hugo-pipes/introduction/). -data -: The `data` directory contains data files (JSON, TOML, YAML, or XML) that augment content, configuration, localization, and navigation. See [details](/templates/data-templates/). +###### config -i18n -: The `i18n` directory contains translation tables for multilingual sites. See [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 [details](/getting-started/configuration/#configuration-directory). -layouts -: The layouts directory contains templates to transform content, data, and resources into a complete website. See [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 [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 [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 [details](/content-management/static-files/). +The `data` directory contains data files (JSON, TOML, YAML, or XML) that augment content, configuration, localization, and navigation. See [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 [details](/content-management/multilingual/). + +###### layouts + +The layouts directory contains templates to transform content, data, and resources into a complete website. See [details](/templates/). + +###### public + +The `public` directory contains the published website, generated when you run the `hugo` or `hugo server` commands. Hugo recreates this directory and its content as needed. See [details](/getting-started/usage/#build-your-site). + +###### resources + +The `resources` directory contains cached output from Hugo's asset pipelines, generated when you run the `hugo` or `hugo server` commands. By default this cache directory includes CSS and images. Hugo recreates this directory and its content as needed. + +###### static + +The `static` directory contains files that will be copied to the public directory when you build your site. For example: `favicon.ico`, `robots.txt`, and files that verify site ownership. Before the introduction of [page bundles](/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 Binary files differnew file mode 100644 index 000000000..ebed7e89f --- /dev/null +++ b/content/en/getting-started/external-learning-resources/build-websites-with-hugo.png diff --git a/content/en/getting-started/external-learning-resources/hia.jpg b/content/en/getting-started/external-learning-resources/hia.jpg Binary files differdeleted file mode 100644 index 601947a70..000000000 --- a/content/en/getting-started/external-learning-resources/hia.jpg +++ /dev/null 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 Binary files differnew file mode 100644 index 000000000..7bc5c9930 --- /dev/null +++ b/content/en/getting-started/external-learning-resources/hugo-in-action.png 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 -[](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) +[B](#bool) +[C](#cache) +[D](#default-sort-order) +[E](#environment) +[F](#field) +[G](#global-resource) +[H](#headless-bundle) +[I](#identifier) +[K](#kind) +[L](#layout) +[M](#map) +[N](#node) +[O](#object) +[P](#page-bundle) +[R](#regular-page) +[S](#scalar) +[T](#taxonomic-weight) +[U](#unmarshal) +[V](#variable) +[W](#walk) +[Z](#zero-time) ###### 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 _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 [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 [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 [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 [details](/content-management/formats/). +A markup language for creating content. Typically Markdown, but may also be HTML, AsciiDoc, Org, Pandoc, or reStructuredText. See [details](/content-management/formats/). ###### content type @@ -93,7 +108,7 @@ A template called with the `.Page.Render` method. See [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 [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 [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 also [parameter](#parameter). +A predefined key-value pair in front matter such as `date` or `title`. See also [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 [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 [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 [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 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 [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 [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 [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 [details](/templates/section-templates/#page-kinds). +A classification of pages, one of `home`, `page`, `section`, `taxonomy`, or `term`. See [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 also [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 also [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 [details](/templates/render-hooks/). +A [template](#template) that overrides standard Markdown rendering. See [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 [details](/content-management/shortcodes/). +A [template](#template) called from within Markdown, taking zero or more [arguments](#argument). See [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?"` . +###### 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 [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` and `$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` and `$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. - - - -Selecting GitHub will bring up an authorization modal for authentication. Select "Authorize application." - - - -## 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." - - - -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. - - - -And then again with the GitHub authorization modal: - - - -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: - - - -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:. - - - -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." - - - - - -[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. + + + +Step 3 +: Authorize Netlify to connect with your GitHub account by pressing the **Authorize Netlify** button. + + + +Step 4 +: Press the **Configure Netlify on GitHub** button. + + + +Step 5 +: Install the Netlify app by selecting your GitHub account. + + + +Step 6 +: Press the **Install** button. + + + +Step 7 +: Click on the site's repository from the list. + + + +Step 8 +: Set the site name and branch from which to deploy. + + + +Step 9 +: Define the build settings, press the **Add environment variables** button, then press the **New variable** button. + + + +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 + + + +Step 11 +: Press the "Deploy my new site" button at the bottom of the page. + + + +Step 12 +: At the bottom of the screen, wait for the deploy to complete, then click on the deploy log entry. + + + +Step 13 +: Press the **Open production deploy** button to view the live site. + + + +## 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 Binary files differnew file mode 100644 index 000000000..31fceff27 --- /dev/null +++ b/content/en/hosting-and-deployment/hosting-on-netlify/netlify-step-02.png 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 Binary files differnew file mode 100644 index 000000000..7b98e0b8f --- /dev/null +++ b/content/en/hosting-and-deployment/hosting-on-netlify/netlify-step-03.png 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 Binary files differnew file mode 100644 index 000000000..31304894b --- /dev/null +++ b/content/en/hosting-and-deployment/hosting-on-netlify/netlify-step-04.png 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 Binary files differnew file mode 100644 index 000000000..6d6eef01d --- /dev/null +++ b/content/en/hosting-and-deployment/hosting-on-netlify/netlify-step-05.png 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 Binary files differnew file mode 100644 index 000000000..1b766a785 --- /dev/null +++ b/content/en/hosting-and-deployment/hosting-on-netlify/netlify-step-06.png 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 Binary files differnew file mode 100644 index 000000000..7bb3b6eca --- /dev/null +++ b/content/en/hosting-and-deployment/hosting-on-netlify/netlify-step-07.png 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 Binary files differnew file mode 100644 index 000000000..df8e9e59f --- /dev/null +++ b/content/en/hosting-and-deployment/hosting-on-netlify/netlify-step-08.png 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 Binary files differnew file mode 100644 index 000000000..3f925accc --- /dev/null +++ b/content/en/hosting-and-deployment/hosting-on-netlify/netlify-step-09.png 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 Binary files differnew file mode 100644 index 000000000..e9196d0ce --- /dev/null +++ b/content/en/hosting-and-deployment/hosting-on-netlify/netlify-step-10.png 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 Binary files differnew file mode 100644 index 000000000..2ac2b08af --- /dev/null +++ b/content/en/hosting-and-deployment/hosting-on-netlify/netlify-step-11.png 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 Binary files differnew file mode 100644 index 000000000..e251305a4 --- /dev/null +++ b/content/en/hosting-and-deployment/hosting-on-netlify/netlify-step-12.png 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 Binary files differnew file mode 100644 index 000000000..f955f6369 --- /dev/null +++ b/content/en/hosting-and-deployment/hosting-on-netlify/netlify-step-13.png 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 [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 [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 [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 [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 [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] email = '[email protected]' 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 [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 [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 [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 [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 + + ------------ ------------------ --------- + 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) + + +``` + +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 © 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 [](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 - -``` - -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 [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 [details](/content-management/shortcodes/). ###### Can I use environment variables to control configuration? @@ -105,6 +94,36 @@ Yes. See [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** > **Settings** > **Privacy & security** > **Windows Security** > **Open Windows Security** > **Virus & threat protection** > **Manage settings** > **Add or remove exclusions** > **Add an exclusion** > **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 [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 %}} |
