From: Bjørn Erik Pedersen Date: Fri, 9 Aug 2024 13:17:43 +0000 (+0200) Subject: Merge commit 'a6e635ca7d905d9ec3ffd708db2694f680b03aae' X-Git-Url: http://git.maquefel.me/?a=commitdiff_plain;h=e99eba39e7f9f9fed454a7671635052600685cea;p=brevno-suite%2Fhugo Merge commit 'a6e635ca7d905d9ec3ffd708db2694f680b03aae' --- e99eba39e7f9f9fed454a7671635052600685cea diff --cc docs/.cspell.json index 95e3ed5ce,000000000..01d248e25 mode 100644,000000..100644 --- a/docs/.cspell.json +++ b/docs/.cspell.json @@@ -1,171 -1,0 +1,173 @@@ +{ + "version": "0.2", + "allowCompoundWords": true, + "files": [ + "**/*.md" + ], + "flagWords": [ + "alot", + "hte", + "langauge", + "reccommend", + "seperate", + "teh" + ], + "ignorePaths": [ + "**/emojis.md", + "**/commands/*", + "**/showcase/*", + "**/tools/*" + ], + "ignoreRegExpList": [ + "# cspell: ignore fenced code blocks", + "^(\\s*`{3,}).*[\\s\\S]*?^\\1$", + "# cspell: ignore words joined with dot", + "\\w+\\.\\w+", + "# cspell: ignore strings within backticks", + "`.+`", + "# cspell: ignore strings within double quotes", + "\".+\"", + "# cspell: ignore strings within brackets", + "\\[.+\\]", + "# cspell: ignore strings within parentheses", + "\\(.+\\)", + "# cspell: ignore words that begin with a slash", + "/\\w+", + "# cspell: ignore everything within action delimiters", + "\\{\\{.+\\}\\}", + "# cspell: ignore everything after a right arrow", + "\\s+→\\s+.+" + ], + "language": "en", + "words": [ + "composability", + "configurators", + "defang", + "deindent", + "downscale", + "downscaling", + "exif", + "geolocalized", + "grayscale", + "marshal", + "marshaling", + "multihost", + "multiplatfom", + "performantly", + "preconfigured", + "prerendering", + "redirection", + "redirections", + "subexpression", + "suppressible", + "templating", + "transpile", + "unmarshal", + "unmarshaling", + "unmarshals", + "# ----------------------------------------------------------------------", + "# cspell: ignore hugo terminology", + "# ----------------------------------------------------------------------", + "attrlink", + "canonify", + "codeowners", ++ "dynacache", + "eturl", + "getenv", + "gohugo", + "gohugoio", + "keyvals", + "leftdelim", + "linkify", + "numworkermultiplier", + "rightdelim", + "shortcode", + "stringifier", + "struct", + "toclevels", + "zgotmplz", + "# ----------------------------------------------------------------------", + "# cspell: ignore foreign language words", + "# ----------------------------------------------------------------------", + "bezpieczeństwo", ++ "blatt", + "buch", + "descripción", + "dokumentation", + "erklärungen", + "libros", + "mercredi", + "miesiąc", + "miesiąc", + "miesiąca", + "miesiące", + "miesięcy", + "misérables", + "mittwoch", + "muchos", + "novembre", + "otro", + "pocos", + "produkte", + "projekt", + "prywatność", + "referenz", + "régime", + "# ----------------------------------------------------------------------", + "# cspell: ignore names", + "# ----------------------------------------------------------------------", + "Atishay", + "Cosette", + "Eliott", + "Furet", + "Gregor", + "Jaco", + "Lanczos", + "Ninke", + "Noll", + "Pastorius", + "Samsa", + "Stucki", + "Thénardier", + "# ----------------------------------------------------------------------", + "# cspell: ignore operating systems and software packages", + "# ----------------------------------------------------------------------", + "asciidoctor", + "brotli", + "cifs", + "corejs", + "disqus", + "docutils", + "dpkg", + "doas", + "eopkg", + "gitee", + "goldmark", + "katex", + "kubuntu", + "lubuntu", + "mathjax", + "nosql", + "pandoc", + "pkgin", + "rclone", + "xubuntu", + "# ----------------------------------------------------------------------", + "# cspell: ignore miscellaneous", + "# ----------------------------------------------------------------------", + "achristie", + "ddmaurier", + "dring", + "inor", + "jausten", + "jdoe", + "jsmith", + "milli", + "rgba", + "rsmith", + "tdewolff", + "tjones", + "wcag", + "xfeff" + ] +} diff --cc docs/_vendor/github.com/gohugoio/gohugoioTheme/assets/images/sponsors/Route4MeLogoBlueOnWhite.svg index 000000000,000000000..d4334e8d8 new file mode 100644 --- /dev/null +++ b/docs/_vendor/github.com/gohugoio/gohugoioTheme/assets/images/sponsors/Route4MeLogoBlueOnWhite.svg @@@ -1,0 -1,0 +1,15 @@@ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ diff --cc docs/_vendor/github.com/gohugoio/gohugoioTheme/data/sponsors.toml index 8e485b2a4,000000000..33d550449 mode 100644,000000..100644 --- a/docs/_vendor/github.com/gohugoio/gohugoioTheme/data/sponsors.toml +++ b/docs/_vendor/github.com/gohugoio/gohugoioTheme/data/sponsors.toml @@@ -1,22 -1,0 +1,23 @@@ +[[banners]] + name = "Linode" + link = "https://www.linode.com/" + logo = "images/sponsors/linode-logo.svg" + utm_campaign = "hugosponsor" + bgcolor = "#ffffff" + +[[banners]] - name = "Route4Me" - link = "https://route4me.com" - title = "Route Planning & Route Optimization Software" - utm_campaign = "hugosponsor" - bgcolor = "#334799" - link_attr = "style='color: #ffffff; font-weight: bold; text-decoration: none; text-align: center'" ++ name = "Route4Me" ++ link = "https://route4me.com/" ++ title = "Route Planning & Route Optimization Software" ++ no_query_params = true ++ utm_campaign = "hugosponsor" ++ bgcolor = "#334799" ++ link_attr = "style='color: #ffffff; font-weight: bold; text-decoration: none; text-align: center'" + +[[banners]] + name = "Your Company?" + link = "https://bep.is/en/hugo-sponsor-2023-01/" + utm_campaign = "hugosponsor" + show_on_hover = true + bgcolor = "#4e4f4f" + link_attr = "style='color: #ffffff; font-weight: bold; text-decoration: none; text-align: center'" diff --cc docs/_vendor/github.com/gohugoio/gohugoioTheme/layouts/index.html index 3df97ae42,000000000..dff88d393 mode 100644,000000..100644 --- a/docs/_vendor/github.com/gohugoio/gohugoioTheme/layouts/index.html +++ b/docs/_vendor/github.com/gohugoio/gohugoioTheme/layouts/index.html @@@ -1,27 -1,0 +1,27 @@@ +{{ define "header" }} + {{ partial "hero.html" . }} + {{ partial "boxes-small-news.html" . }} +{{ end }} + +{{ define "main" }} +
+ {{- partial "home-page-sections/features-icons.html" . -}} +
+ + {{ partial "home-page-sections/sponsors.html" (dict "cx" . "gtag" "home" ) }} + + {{- partial "home-page-sections/features-single.html" . -}} + - {{- partial "home-page-sections/showcase.html" . -}} ++ {{/*- partial "home-page-sections/showcase.html" . -*/}} + +
+ {{- partial "home-page-sections/installation.html" . -}} +
+ +
+ {{- partial "home-page-sections/tweets.html" . -}} +
+
+ {{- partial "home-page-sections/open-source-involvement.html" . -}} +
+{{ end }} diff --cc docs/_vendor/github.com/gohugoio/gohugoioTheme/layouts/partials/home-page-sections/sponsors.html index 3b7f6bfef,000000000..84033c42c mode 100644,000000..100644 --- a/docs/_vendor/github.com/gohugoio/gohugoioTheme/layouts/partials/home-page-sections/sponsors.html +++ b/docs/_vendor/github.com/gohugoio/gohugoioTheme/layouts/partials/home-page-sections/sponsors.html @@@ -1,57 -1,0 +1,60 @@@ +{{ $classes_box := "ba b--dark-gray bg-light-gray br3 flex flex-column flex-wrap items-center justify-center ph3 pv4 mb4 w-100 w-30-l " }} +{{ $gtag := .gtag | default "unknown" }} +{{ $classes_box := "ba b--dark-gray bg-light-gray br3 flex flex-column flex-wrap items-center justify-center ph3 pv4 mb4 w-100 w-30-l " }} +{{ $gtag := .gtag | default "unknown" }} +{{ $isFooter := (eq $gtag "footer") }} +{{ $utmSource := cond $isFooter "hugofooter" "hugohome" }} +{{ with .cx.Site.Data.sponsors }} + +
+
+

Hugo Sponsors

+
+ {{ range .banners }} +
+ {{ $query_params := .query_params | default "" }} - {{ $url := printf "%s?%s%s" .link $query_params (querify "utm_source" (.utm_source | default $utmSource ) "utm_medium" "banner" "utm_campaign" (.utm_campaign | default "hugosponsor") "utm_content" (.utm_content | default "gohugoio")) | safeURL }} ++ {{ $url := .link }} ++ {{ if not .no_query_params }} ++ {{ $url = printf "%s?%s%s" .link $query_params (querify "utm_source" (.utm_source | default $utmSource ) "utm_medium" "banner" "utm_campaign" (.utm_campaign | default "hugosponsor") "utm_content" (.utm_content | default "gohugoio")) | safeURL }} ++ {{ end }} + {{ $logo := resources.Get .logo }} + {{ $gtagID := printf "Sponsor %s %s" .name $gtag | title }} + {{ $classes := "" }} + {{ if .show_on_hover }} + {{ $classes = printf "%s show-on-hover" $classes }} + {{ end }} + {{ if $isFooter }} + {{ $classes = printf "%s f3" $classes }} + {{ else }} + {{ $classes = printf "%s f1" $classes }} + {{ end }} + + {{ with $logo }} + {{ .Content | safeHTML }} + {{ else }} + {{ .name }} + {{ end }} + +
+ {{ end }} +
+
+
+{{ end }} diff --cc docs/_vendor/modules.txt index 100c6fc6f,000000000..1bde873a0 mode 100644,000000..100644 --- a/docs/_vendor/modules.txt +++ b/docs/_vendor/modules.txt @@@ -1,1 -1,0 +1,1 @@@ - # github.com/gohugoio/gohugoioTheme v0.0.0-20240619093131-b595d5fb8c52 ++# github.com/gohugoio/gohugoioTheme v0.0.0-20240728210410-d42c342ce472 diff --cc docs/config/_default/menus/menus.en.toml index b0da48817,000000000..3f4e76879 mode 100644,000000..100644 --- a/docs/config/_default/menus/menus.en.toml +++ b/docs/config/_default/menus/menus.en.toml @@@ -1,152 -1,0 +1,152 @@@ +[[docs]] +identifier = 'about' +name = 'About' +pageRef = '/about/' +weight = 10 + +[[docs]] +name = 'Installation' +weight = 20 +identifier = 'installation' +pageRef = '/installation/' + +[[docs]] +name = 'Getting started' +weight = 30 +identifier = 'getting-started' +pageRef = '/getting-started/' + +[[docs]] +name = 'Quick reference' +weight = 40 +identifier = 'quick-reference' +pageRef = '/quick-reference/' +post = 'break' + +[[docs]] +name = 'Content management' +weight = 50 +identifier = 'content-management' +post = 'expanded' +pageRef = '/content-management/' + +[[docs]] +name = 'Templates' +weight = 60 +identifier = 'templates' +pageRef = '/templates/' + +[[docs]] +name = 'Functions' +weight = 70 +identifier = 'functions' +pageRef = '/functions/' + +[[docs]] +name = 'Methods' +weight = 80 +identifier = 'methods' +pageRef = '/methods/' + +[[docs]] +name = 'Render hooks' +weight = 90 +identifier = 'render-hooks' +pageRef = '/render-hooks/' + +[[docs]] +name = 'Hugo Modules' +weight = 100 +identifier = 'modules' +pageRef = '/hugo-modules/' + +[[docs]] +name = 'Hugo Pipes' +weight = 110 +identifier = 'hugo-pipes' +pageRef = '/hugo-pipes/' + +[[docs]] +name = 'CLI' +weight = 120 +post = 'break' +identifier = 'commands' +pageRef = '/commands/' + +# Low level items + +[[docs]] +name = 'Troubleshooting' +weight = 130 +identifier = 'troubleshooting' +pageRef = '/troubleshooting/' + +[[docs]] +name = 'Developer tools' +weight = 140 +identifier = 'developer-tools' +pageRef = '/tools/' + +[[docs]] +name = 'Hosting and deployment' +weight = 150 +identifier = 'hosting-and-deployment' +pageRef = '/hosting-and-deployment/' + +[[docs]] +name = 'Contribute' +weight = 160 +post = 'break' +identifier = 'contribute' +pageRef = '/contribute/' + +######## QUICKLINKS + +[[quicklinks]] +identifier = 'fundamentals' +name = 'Fundamentals' +pageRef = '/tags/fundamentals/' +weight = 1 + +######## GLOBAL ITEMS TO BE SHARED WITH THE HUGO SITES + +[[global]] +name = 'News' +weight = 1 +identifier = 'news' +pageRef = '/news/' + +[[global]] +name = 'Docs' +weight = 5 +identifier = 'docs' +url = '/documentation/' + +[[global]] +name = 'Themes' +weight = 10 +identifier = 'themes' +url = 'https://themes.gohugo.io/' + - [[global]] - name = 'Showcase' - weight = 20 - identifier = 'showcase' - pageRef = '/showcase/' ++# [[global]] ++# name = 'Showcase' ++# weight = 20 ++# identifier = 'showcase' ++# pageRef = '/showcase/' + +# Anything with a weight > 100 gets an external icon + +[[global]] +name = 'Community' +weight = 150 +icon = true +identifier = 'community' +post = 'external' +url = 'https://discourse.gohugo.io/' + +[[global]] +name = 'GitHub' +weight = 200 +identifier = 'github' +post = 'external' +url = 'https://github.com/gohugoio/hugo' diff --cc docs/content/en/about/features.md index ff7e9ce13,000000000..cb710aa4b mode 100644,000000..100644 --- a/docs/content/en/about/features.md +++ b/docs/content/en/about/features.md @@@ -1,136 -1,0 +1,139 @@@ +--- +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: + docs: + parent: about + weight: 30 +weight: 30 +toc: true +--- + +## 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. ++: Create templates using 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. ++[Image processing] ++: Convert, resize, crop, rotate, adjust colors, apply filters, overlay text and images, and extract EXIF data. + +[JavaScript bundling] +: Transpile TypeScript and JSX to JavaScript, bundle, tree shake, minify, create source maps, and perform SRI hashing. + - [Image processing] - : Convert, resize, crop, rotate, adjust colors, apply filters, overlay text and images, and extract EXIF data. ++[Sass processing] ++: Transpile Sass to CSS, bundle, tree shake, minify, create source maps, perform SRI hashing, and integrate with PostCSS. ++ ++[Tailwind CSS processing] ++: Compile Tailwind CSS utility classes into standard CSS, bundle, tree shake, optimize, minify, perform SRI hashing, and integrate with PostCSS. + +## 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/ ++[Sass processing]: /functions/css/Sass/ +[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/ +[Syntax highlighting]: /content-management/syntax-highlighting/ ++[Tailwind CSS processing]: /functions/css/tailwindcss/ +[Taxonomies]: /content-management/taxonomies/ +[Templates]: templates/introduction/ +[Themes]: https://themes.gohugo.io/ +[URL management]: /content-management/urls/ diff --cc docs/content/en/about/privacy.md index dcc3b3439,000000000..a3491f864 mode 100644,000000..100644 --- a/docs/content/en/about/privacy.md +++ b/docs/content/en/about/privacy.md @@@ -1,122 -1,0 +1,122 @@@ +--- +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: 40 +weight: 40 +toc: true +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. + - **Hugo is a static site generator. By using Hugo you are already standing on very solid ground. Static HTML files on disk are much easier to reason about compared to server and database driven web sites.** ++ **Hugo is a static site generator. By using Hugo you are already standing on very solid ground. Static HTML files on disk are much easier to reason about compared to server and database driven websites.** + + But even static websites can integrate with external services, so from version `0.41`, Hugo provides a **privacy configuration** that covers the relevant built-in templates. + + 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 [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 + +Below are all privacy settings and their default value. These settings need to be put in your site configuration (e.g. `hugo.toml`). + +{{< code-toggle file=hugo >}} +[privacy] +[privacy.disqus] +disable = false +[privacy.googleAnalytics] +disable = false +respectDoNotTrack = false +[privacy.instagram] +disable = false +simple = false +[privacy.twitter] +disable = false +enableDNT = false +simple = false +[privacy.vimeo] +disable = false +enableDNT = false +simple = false +[privacy.youtube] +disable = false +privacyEnhanced = false +{{< /code-toggle >}} + +## Disable all services + +An example privacy configuration that disables all the relevant services in Hugo. With this configuration, the other settings will not matter. + +{{< code-toggle file=hugo >}} +[privacy] +[privacy.disqus] +disable = true +[privacy.googleAnalytics] +disable = true +[privacy.instagram] +disable = true +[privacy.twitter] +disable = true +[privacy.vimeo] +disable = true +[privacy.youtube] +disable = true +{{< /code-toggle >}} + +## The privacy settings explained + +### GoogleAnalytics + +respectDoNotTrack +: Enabling this will make the GA templates respect the "Do Not Track" HTTP header. + +### Instagram + +simple +: If simple mode is enabled, a static and no-JS version of the Instagram image card will be built. Note that this only supports image cards and the image itself will be fetched from Instagram's servers. + +**Note:** If you use the _simple mode_ for Instagram and a site styled with Bootstrap 4, you may want to disable the inline styles provided by Hugo: + +{{< code-toggle file=hugo >}} +[services] +[services.instagram] +disableInlineCSS = true +{{< /code-toggle >}} + +### Twitter + +enableDNT +: Enabling this for the twitter/tweet shortcode, the tweet and its embedded page on your site are not used for purposes that include personalized suggestions and personalized ads. + +simple +: If simple mode is enabled, a static and no-JS version of a tweet will be built. + +**Note:** If you use the _simple mode_ for Twitter, you may want to disable the inline styles provided by Hugo: + +{{< code-toggle file=hugo >}} +[services] +[services.twitter] +disableInlineCSS = true +{{< /code-toggle >}} + +### YouTube + +privacyEnhanced +: When you turn on privacy-enhanced mode, YouTube won’t store information about visitors on your website unless the user plays the embedded video. + +### Vimeo + +enableDNT +: Enabling this for the vimeo shortcode, the Vimeo player will be blocked from tracking any session data, including all cookies and stats. + +simple +: If simple mode is enabled, the video thumbnail is fetched from Vimeo's servers and it is overlaid with a play button. If the user clicks to play the video, it will open in a new tab directly on Vimeo's website. diff --cc docs/content/en/content-management/comments.md index 8f55c413c,000000000..721f1fe5a mode 100644,000000..100644 --- a/docs/content/en/content-management/comments.md +++ b/docs/content/en/content-management/comments.md @@@ -1,78 -1,0 +1,78 @@@ +--- +title: Comments +description: Hugo ships with an internal Disqus template, but this isn't the only commenting system that will work with your new Hugo website. +categories: [content management] +keywords: [sections,content,organization] +menu: + docs: + parent: content-management + weight: 220 +weight: 220 +toc: true +aliases: [/extras/comments/] +--- + +Hugo ships with support for [Disqus](https://disqus.com/), a third-party service that provides comment and community capabilities to websites via JavaScript. + +Your theme may already support Disqus, but if not, it is easy to add to your templates via [Hugo's built-in Disqus partial][disquspartial]. + +## Add Disqus + +Hugo comes with all the code you need to load Disqus into your templates. Before adding Disqus to your site, you'll need to [set up an account][disqussetup]. + +### Configure Disqus + +Disqus comments require you set a single value in your [site's configuration file][configuration] like so: + +{{< code-toggle file=hugo >}} +[services.disqus] +shortname = 'your-disqus-shortname' +{{}} + +For many websites, this is enough configuration. However, you also have the option to set the following in the [front matter] of a single content file: + +* `disqus_identifier` +* `disqus_title` +* `disqus_url` + +### Render Hugo's built-in Disqus partial template + +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" . }} +``` + +## Alternatives + +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/embedded/#disqus +[disqussetup]: https://disqus.com/profile/signup/ +[forum]: https://discourse.gohugo.io +[front matter]: /content-management/front-matter/ +[kaijuissue]: https://github.com/spf13/kaiju/issues/new +[issotutorial]: https://stiobhart.net/2017-02-24-isso-comments/ - [partials]: /templates/partials/ ++[partials]: /templates/partial/ +[MongoDB]: https://www.mongodb.com/ diff --cc docs/content/en/content-management/content-adapters.md index 11257b895,000000000..ea5ec62ca mode 100644,000000..100644 --- a/docs/content/en/content-management/content-adapters.md +++ b/docs/content/en/content-management/content-adapters.md @@@ -1,355 -1,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" }} + +{{ 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. + +: + +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. ++: Create a single template to render each book review. + +{{< code file=layouts/books/single.html copy=true >}} +{{ define "main" }} +

{{ .Title }}

+ + {{ with .Resources.GetMatch "cover.*" }} + {{ .Params.alt }} + {{ end }} + +

Author: {{ .Params.author }}

+ +

+ ISBN: {{ .Params.isbn }}
+ Rating: {{ .Params.rating }}
+ Review date: {{ .Date | time.Format ":date_long" }} +

+ + {{ with .GetTerms "tags" }} +

Tags:

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

Reference

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

Reference A

+

Reference B

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

Reference

+

Reference

+

Reference

+``` + +## Ref and RelRef Configuration + +The behavior can be configured in `hugo.toml`: + +refLinksErrorLevel ("ERROR") +: When using `ref` or `relref` to resolve page links and a link cannot resolved, it will be logged with this log level. Valid values are `ERROR` (default) or `WARNING`. Any `ERROR` will fail the build (`exit -1`). + +refLinksNotFoundURL +: URL to be used as a placeholder when a page reference cannot be found in `ref` or `relref`. Is used as-is. - - [lists]: /templates/lists/ - [output formats]: /templates/output-formats/ - [shortcode]: /content-management/shortcodes/ diff --cc docs/content/en/content-management/data-sources.md index 40634acef,000000000..c009fb7f3 mode 100644,000000..100644 --- a/docs/content/en/content-management/data-sources.md +++ b/docs/content/en/content-management/data-sources.md @@@ -1,126 -1,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. ++See the documentation for the [`Data`] method on a `Site` object for details and examples. + +[`Data`]: /methods/site/data/ + +## Global resources + +Use the `resources.Get` and `transform.Unmarshal` functions to access data files that exist as global resources. + +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 >}} +{{}} +{{< /code >}} + +{{< code file=layouts/shortcodes/csv-to-table.html >}} +{{ with $file := .Get 0 }} + {{ with resources.Get $file }} + {{ with . | transform.Unmarshal }} + + + + {{ range index . 0 }} + + {{ end }} + + + + {{ range after 1 . }} + + {{ range . }} + + {{ end }} + + {{ end }} + +
{{ . }}
{{ . }}
+ {{ 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 --cc docs/content/en/content-management/front-matter.md index 2c01f7854,000000000..3ac2a63bc mode 100644,000000..100644 --- a/docs/content/en/content-management/front-matter.md +++ b/docs/content/en/content-management/front-matter.md @@@ -1,430 -1,0 +1,430 @@@ +--- +title: Front matter +description: Use front matter to add metadata to your content. +categories: [content management] +keywords: [front matter,yaml,toml,json,metadata,archetypes] +menu: + docs: + parent: content-management + weight: 60 +weight: 60 +toc: true +aliases: [/content/front-matter/] +--- + +## Overview + +The front matter at the top of each content file is metadata that: + +- Describes the content +- Augments the content +- Establishes relationships with other content +- Controls the published structure of your site +- Determines template selection + +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. + +[json]: https://www.json.org/ +[toml]: https://toml.io/ +[yaml]: https://yaml.org/ + +See examples of front matter delimiters by toggling between the serialization formats below. + +{{< 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 >}} + +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. + +[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 + +## Fields + +The most common front matter fields are `date`, `draft`, `title`, and `weight`, but you can specify metadata using any of fields below. + +{{% 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. + +[parameters]: #parameters +{{% /note %}} + +###### aliases + +(`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. + +[`aliases`]: /methods/page/aliases/ +[aliases]: /content-management/urls/#aliases + +###### build + +(`map`) A map of [build options]. + +[build options]: /content-management/build-options/ + +###### cascade {#cascade-field} + +(`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. + +[cascade]: #cascade + +###### date + +(`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. + +[`date`]: /methods/page/date/ + +###### description + +(`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. + +[`description`]: /methods/page/description/ + +###### draft + +(`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. + +[`draft`]: /methods/page/draft/ + +###### expiryDate + +(`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. + +[`expirydate`]: /methods/page/expirydate/ + +###### headless + +(`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]. + +[leaf bundles]: /content-management/page-bundles/#leaf-bundles +[page resources]: /content-management/page-resources/ + +###### isCJKLanguage + +(`bool`) Set to `true` if the content language is in the [CJK] family. This value determines how Hugo calculates word count, and affects the values returned by the [`WordCount`], [`FuzzyWordCount`], [`ReadingTime`], and [`Summary`] methods on a `Page` object. + +[`fuzzywordcount`]: /methods/page/wordcount/ +[`readingtime`]: /methods/page/readingtime/ +[`summary`]: /methods/page/summary/ +[`wordcount`]: /methods/page/wordcount/ +[cjk]: /getting-started/glossary/#cjk + +###### keywords + +(`string array`) An array of keywords, typically rendered within a `meta` element within the `head` element of the published HTML file, or used as a [taxonomy] to classify content. Access these values from a template using the [`Keywords`] method on a `Page` object. + +[`keywords`]: /methods/page/keywords/ +[taxonomy]: /getting-started/glossary/#taxonomy + + + + + + + +###### 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/ + + + + +###### 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 templates]: /templates/sitemap/ +[`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 + +(`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. + +[`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" }} +

Tags

+ +{{ 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 an array with an optional `_target` keyword, allowing you to target different page sets while cascading values. + +{{< code-toggle file=content/_index.md fm=true >}} +title ="Home" +[[cascade]] +[cascade.params] +background = "yosemite.jpg" +[cascade._target] +path="/articles/**" +lang="en" +kind="page" +[[cascade]] +[cascade.params] +background = "goldenbridge.jpg" +[cascade._target] +kind="section" +{{}} + +Use any combination of these keywords to target a set of pages: + +###### path {#cascade-path} + +(`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. + +###### kind {#cascade-kind} + +(`string`) A Glob pattern matching the Page's Kind(s), e.g. "{home,section}". + +###### lang {#cascade-lang} + +(`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 %}} +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. + +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 + +{{< 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' +{{}} + +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. + +## Emacs Org Mode + +If your [content format] is [Emacs Org Mode], you may provide front matter using Org Mode keywords. For example: + +{{< 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 >}} + +Note that you can also specify array elements on a single line: + +{{< code file=content/example.org lang=text >}} +#+TAGS[]: red blue +{{< /code >}} + +[content format]: /content-management/formats/ +[emacs org mode]: https://orgmode.org/ diff --cc docs/content/en/content-management/image-processing/index.md index 292aa8a4d,000000000..db786361c mode 100644,000000..100644 --- a/docs/content/en/content-management/image-processing/index.md +++ b/docs/content/en/content-management/image-processing/index.md @@@ -1,523 -1,0 +1,523 @@@ +--- +title: Image processing +description: Resize, crop, rotate, filter, and convert images. +categories: [content management,fundamentals] +keywords: [resources,images] +menu: + docs: + parent: content-management + weight: 90 +toc: true +weight: 90 +--- + +## Image resources + +To process an image you must access the file as a page resource, global resource, or remote resource. + +### Page resource + +A page resource is a file within a [page bundle]. A page bundle is a directory with an `index.md` or `_index.md` file at its root. + +```text +content/ +└── posts/ + └── post-1/ <-- page bundle + ├── index.md + └── sunset.jpg <-- page resource +``` + +To access an image as a page resource: + +```go-html-template +{{ $image := .Resources.Get "sunset.jpg" }} +``` + +### Global resource + +A global resource is a file within the `assets` directory, or within any directory [mounted] to the `assets` directory. + +```text +assets/ +└── images/ + └── sunset.jpg <-- global resource +``` + +To access an image as a global resource: + +```go-html-template +{{ $image := resources.Get "images/sunset.jpg" }} +``` + +### Remote resource + +A remote resource is a file on a remote server, accessible via HTTP or HTTPS. To access an image as a remote resource: + +```go-html-template +{{ $image := resources.GetRemote "https://gohugo.io/img/hugo-logo.png" }} +``` + +## Image rendering + - Once you have accessed an image as either a page resource or a global resource, render it in your templates using the `Permalink`, `RelPermalink`, `Width`, and `Height` properties. ++Once you have accessed an image as a resource, render it in your templates using the `Permalink`, `RelPermalink`, `Width`, and `Height` properties. + +Example 1: Throws an error if the resource is not found. + +```go-html-template +{{ $image := .Resources.GetMatch "sunset.jpg" }} + +``` + +Example 2: Skips image rendering if the resource is not found. + +```go-html-template +{{ $image := .Resources.GetMatch "sunset.jpg" }} +{{ with $image }} + +{{ end }} +``` + +Example 3: A more concise way to skip image rendering if the resource is not found. + +```go-html-template +{{ with .Resources.GetMatch "sunset.jpg" }} + +{{ end }} +``` + +Example 4: Skips rendering if there's problem accessing a remote resource. + +```go-html-template +{{ $u := "https://gohugo.io/img/hugo-logo.png" }} +{{ with resources.GetRemote $u }} + {{ with .Err }} + {{ errorf "%s" . }} + {{ else }} + + {{ end }} +{{ else }} + {{ errorf "Unable to get remote resource %q" $u }} +{{ end }} +``` + +## Image processing methods + +The `image` resource implements the [`Process`], [`Resize`], [`Fit`], [`Fill`], [`Crop`], [`Filter`], [`Colors`] and [`Exif`] methods. + +{{% note %}} - Metadata (EXIF, IPTC, XMP, etc.) is not preserved during image transformation. Use the `Exif` method with the _original_ image to extract EXIF metadata from JPEG or TIFF images. ++Metadata (EXIF, IPTC, XMP, etc.) is not preserved during image transformation. Use the `Exif` method with the _original_ image to extract EXIF metadata from JPEG, PNG, TIFF, and WebP images. +{{% /note %}} + +### Process + +{{< new-in 0.119.0 >}} + +{{% note %}} +The `Process` method is also available as a filter, which is more effective if you need to apply multiple filters to an image. See [Process filter](/functions/images/process). +{{% /note %}} + +Process processes the image with the given specification. The specification can contain an optional action, one of `resize`, `crop`, `fit` or `fill`. This means that you can use this method instead of [`Resize`], [`Fit`], [`Fill`], or [`Crop`]. + +See [Options](#image-processing-options) for available options. + +You can also use this method apply image processing that does not need any scaling, e.g. format conversions: + +```go-html-template +{{/* Convert the image from JPG to PNG. */}} +{{ $png := $jpg.Process "png" }} +``` + +Some more examples: + +```go-html-template +{{/* Rotate the image 90 degrees counter-clockwise. */}} +{{ $image := $image.Process "r90" }} + +{{/* Scaling actions. */}} +{{ $image := $image.Process "resize 600x" }} +{{ $image := $image.Process "crop 600x400" }} +{{ $image := $image.Process "fit 600x400" }} +{{ $image := $image.Process "fill 600x400" }} +``` + +### Resize + +Resize an image to the given width and/or height. + +If you specify both width and height, the resulting image will be disproportionally scaled unless the original image has the same aspect ratio. + +```go-html-template +{{/* Resize to a width of 600px and preserve aspect ratio */}} +{{ $image := $image.Resize "600x" }} + +{{/* Resize to a height of 400px and preserve aspect ratio */}} +{{ $image := $image.Resize "x400" }} + +{{/* Resize to a width of 600px and a height of 400px */}} +{{ $image := $image.Resize "600x400" }} +``` + +### Fit + +Downscale an image to fit the given dimensions while maintaining aspect ratio. You must provide both width and height. + +```go-html-template +{{ $image := $image.Fit "600x400" }} +``` + +### Fill + +Crop and resize an image to match the given dimensions. You must provide both width and height. Use the [`anchor`] option to change the crop box anchor point. + +```go-html-template +{{ $image := $image.Fill "600x400" }} +``` + +### Crop + +Crop an image to match the given dimensions without resizing. You must provide both width and height. Use the [`anchor`] option to change the crop box anchor point. + +```go-html-template +{{ $image := $image.Crop "600x400" }} +``` + +### Filter + +Apply one or more [filters] to an image. + +```go-html-template +{{ $image := $image.Filter (images.GaussianBlur 6) (images.Pixelate 8) }} +``` + +Write this in a more functional style using pipes. Hugo applies the filters in the order given. + +```go-html-template +{{ $image := $image | images.Filter (images.GaussianBlur 6) (images.Pixelate 8) }} +``` + +Sometimes it can be useful to create the filter chain once and then reuse it. + +```go-html-template +{{ $filters := slice (images.GaussianBlur 6) (images.Pixelate 8) }} +{{ $image1 := $image1.Filter $filters }} +{{ $image2 := $image2.Filter $filters }} +``` + +### Colors + +{{< new-in 0.104.0 >}} + +`.Colors` returns a slice of hex strings with the dominant colors in the image using a simple histogram method. + +```go-html-template +{{ $colors := $image.Colors }} +``` + +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 down image. + +### EXIF + +Provides an [EXIF] object containing image metadata. + - You may access EXIF data in JPEG and TIFF images. To prevent errors when processing images without EXIF data, wrap the access in a [`with`] statement. ++You may access EXIF data in JPEG, PNG, TIFF, and WebP images. To prevent errors when processing images without EXIF data, wrap the access in a [`with`] statement. + +```go-html-template +{{ with $image.Exif }} + Date: {{ .Date }} + Lat/Long: {{ .Lat }}/{{ .Long }} + Tags: + {{ range $k, $v := .Tags }} + TAG: {{ $k }}: {{ $v }} + {{ end }} +{{ end }} +``` + +You may also access EXIF fields individually, using the [`lang.FormatNumber`] function to format the fields as needed. + +```go-html-template +{{ with $image.Exif }} + +{{ end }} +``` + +#### EXIF methods + +Date +: (`time.Time`) Returns the image creation date/time. Format with the [`time.Format`]function. + +[time.Format]: /functions/time/format/ + +Lat +: (`float64`) Returns the GPS latitude in degrees. + +Long +: (`float64`) Returns the GPS longitude in degrees. + +Tags +: (`exif.Tags`) Returns a collection of the available EXIF tags for this image. You may include or exclude specific tags from this collection in the [site configuration]. + +## Image processing options + +The [`Resize`], [`Fit`], [`Fill`], and [`Crop`] methods accept a space-delimited, case-insensitive list of options. The order of the options within the list is irrelevant. + +### Dimensions + +With the [`Resize`] method you must specify width, height, or both. The [`Fit`], [`Fill`], and [`Crop`] methods require both width and height. All dimensions are in pixels. + +```go-html-template +{{ $image := $image.Resize "600x" }} +{{ $image := $image.Resize "x400" }} +{{ $image := $image.Resize "600x400" }} +{{ $image := $image.Fit "600x400" }} +{{ $image := $image.Fill "600x400" }} +{{ $image := $image.Crop "600x400" }} +``` + +### Rotation + +Rotates an image counter-clockwise by the given angle. Hugo performs rotation _before_ scaling. For example, if the original image is 600x400 and you wish to rotate the image 90 degrees counter-clockwise while scaling it by 50%: + +```go-html-template +{{ $image = $image.Resize "200x r90" }} +``` + +In the example above, the width represents the desired width _after_ rotation. + +To rotate an image without scaling, use the dimensions of the original image: + +```go-html-template +{{ with .Resources.GetMatch "sunset.jpg" }} + {{ with .Resize (printf "%dx%d r90" .Height .Width) }} + + {{ end }} +{{ end }} +``` + +In the example above, on the second line, we have reversed width and height to reflect the desired dimensions _after_ rotation. + +### Anchor + +When using the [`Crop`] or [`Fill`] method, the _anchor_ determines the placement of the crop box. You may specify `TopLeft`, `Top`, `TopRight`, `Left`, `Center`, `Right`, `BottomLeft`, `Bottom`, `BottomRight`, or `Smart`. + +The default value is `Smart`, which uses [Smartcrop] image analysis to determine the optimal placement of the crop box. You may override the default value in the [site configuration]. + +For example, if you have a 400x200 image with a bird in the upper left quadrant, you can create a 200x100 thumbnail containing the bird: + +```go-html-template +{{ $image.Crop "200x100 TopLeft" }} +``` + +If you apply [rotation](#rotation) when using the [`Crop`] or [`Fill`] method, specify the anchor relative to the rotated image. + +### Target format + +By default, Hugo encodes the image in the source format. You may convert the image to another format by specifying `bmp`, `gif`, `jpeg`, `jpg`, `png`, `tif`, `tiff`, or `webp`. + +```go-html-template +{{ $image.Resize "600x webp" }} +``` + +To convert an image without scaling, use the dimensions of the original image: + +```go-html-template +{{ with .Resources.GetMatch "sunset.jpg" }} + {{ with .Resize (printf "%dx%d webp" .Width .Height) }} + + {{ end }} +{{ end }} +``` + +### Quality + +Applicable to JPEG and WebP images, the `q` value determines the quality of the converted image. Higher values produce better quality images, while lower values produce smaller files. Set this value to a whole number between 1 and 100, inclusive. + +The default value is 75. You may override the default value in the [site configuration]. + +```go-html-template +{{ $image.Resize "600x webp q50" }} +``` + +### Hint + +Applicable to WebP images, this option corresponds to a set of predefined encoding parameters, and is equivalent to the `-preset` flag for the [`cwebp`] encoder. + +[`cwebp`]: https://developers.google.com/speed/webp/docs/cwebp + +Value|Example +:--|:-- +`drawing`|Hand or line drawing with high-contrast details +`icon`|Small colorful image +`photo`|Outdoor photograph with natural lighting +`picture`|Indoor photograph such as a portrait +`text`|Image that is primarily text + +The default value is `photo`. You may override the default value in the [site configuration]. + +```go-html-template +{{ $image.Resize "600x webp picture" }} +``` + +### Background color + +When converting an image from a format that supports transparency (e.g., PNG) to a format that does _not_ support transparency (e.g., JPEG), you may specify the background color of the resulting image. + +Use either a 3-digit or 6-digit hexadecimal color code (e.g., `#00f` or `#0000ff`). + +The default value is `#ffffff` (white). You may override the default value in the [site configuration]. + +```go-html-template +{{ $image.Resize "600x jpg #b31280" }} +``` + +### Resampling filter + +You may specify the resampling filter used when resizing an image. Commonly used resampling filters include: + +Filter|Description +:--|:-- +`Box`|Simple and fast averaging filter appropriate for downscaling +`Lanczos`|High-quality resampling filter for photographic images yielding sharp results +`CatmullRom`|Sharp cubic filter that is faster than the Lanczos filter while providing similar results +`MitchellNetravali`|Cubic filter that produces smoother results with less ringing artifacts than CatmullRom +`Linear`|Bilinear resampling filter, produces smooth output, faster than cubic filters +`NearestNeighbor`|Fastest resampling filter, no antialiasing + +The default value is `Box`. You may override the default value in the [site configuration]. + +```go-html-template +{{ $image.Resize "600x400 Lanczos" }} +``` + +See [github.com/disintegration/imaging] for the complete list of resampling filters. If you wish to improve image quality at the expense of performance, you may wish to experiment with the alternative filters. + +## Image processing examples + +_The photo of the sunset used in the examples below is Copyright [Bjørn Erik Pedersen](https://commons.wikimedia.org/wiki/User:Bep) (Creative Commons Attribution-Share Alike 4.0 International license)_ + +{{< imgproc "sunset.jpg" "resize 300x" />}} + +{{< imgproc "sunset.jpg" "fill 90x120 left" />}} + +{{< imgproc "sunset.jpg" "fill 90x120 right" />}} + +{{< imgproc "sunset.jpg" "fit 90x90" />}} + +{{< imgproc "sunset.jpg" "crop 250x250 center" />}} + +{{< imgproc "sunset.jpg" "resize 300x q10" />}} + +This is the shortcode used to generate the examples above: + +{{< readfile file=layouts/shortcodes/imgproc.html highlight=go-html-template >}} + +Call the shortcode from your Markdown like this: + +```go-html-template +{{}} +``` + +{{% note %}} +Note the self-closing shortcode syntax above. You may call the `imgproc` shortcode with or without **inner content**. +{{% /note %}} + +## Imaging configuration + +### Processing options + +Define an `imaging` section in your site configuration to set the default [image processing options](#image-processing-options). + +{{< code-toggle config=imaging />}} + +anchor +: See image processing options: [anchor](#anchor). + +bgColor +: See image processing options: [background color](#background-color). + +hint +: See image processing options: [hint](#hint). + +quality +: See image processing options: [quality](#quality). + +resampleFilter +: See image processing options: [resampling filter](#resampling-filter). + +### EXIF data + +Define an `imaging.exif` section in your site configuration to control the availability of EXIF data. + +{{< code-toggle file=hugo >}} +[imaging.exif] +includeFields = "" +excludeFields = "" +disableDate = false +disableLatLong = false +{{< /code-toggle >}} + +disableDate +: Hugo extracts the image creation date/time into `.Date`. Set this to `true` to disable. Default is `false`. + +disableLatLong +: Hugo extracts the GPS latitude and longitude into `.Lat` and `.Long`. Set this to `true` to disable. Default is `false`. + +excludeFields +: Regular expression matching the EXIF tags to exclude from the `.Tags` collection. Default is `""`. + +includeFields +: Regular expression matching the EXIF tags to include in the `.Tags` collection. Default is `""`. To include all available tags, set this value to `".*"`. + +{{% note %}} +To improve performance and decrease cache size, Hugo excludes the following tags: `ColorSpace`, `Contrast`, `Exif`, `Exposure[M|P|B]`, `Flash`, `GPS`, `JPEG`, `Metering`, `Resolution`, `Saturation`, `Sensing`, `Sharp`, and `WhiteBalance`. + +To control tag availability, change the `excludeFields` or `includeFields` settings as described above. +{{% /note %}} + +## Smart cropping of images + +By default, Hugo uses the [Smartcrop] library when cropping images with the `Crop` or`Fill` methods. You can set the anchor point manually, but in most cases the `Smart` option will make a good choice. + +Examples using the sunset image from above: + +{{< imgproc "sunset.jpg" "fill 200x200 smart" />}} + +{{< imgproc "sunset.jpg" "crop 200x200 smart" />}} + +## Image processing performance consideration + +Hugo caches processed images in the `resources` directory. If you include this directory in source control, Hugo will not have to regenerate the images in a CI/CD workflow (e.g., GitHub Pages, GitLab Pages, Netlify, etc.). This results in faster builds. + +If you change image processing methods or options, or if you rename or remove images, the `resources` directory will contain unused images. To remove the unused images, perform garbage collection with: + +```sh +hugo --gc +``` + + +[`anchor`]: /content-management/image-processing#anchor +[mounted]: /hugo-modules/configuration#module-configuration-mounts +[page bundle]: /content-management/page-bundles/ +[`lang.FormatNumber`]: /functions/lang/formatnumber/ +[filters]: /functions/images/filter/#image-filters +[github.com/disintegration/imaging]: +[Smartcrop]: +[Exif]: +[`Process`]: #process +[`Colors`]: #colors +[`Crop`]: #crop +[`Exif`]: #exif +[`Fill`]: #fill +[`Filter`]: #filter +[`Fit`]: #fit +[`Resize`]: #resize +[site configuration]: #processing-options +[`with`]: /functions/go-template/with/ diff --cc docs/content/en/content-management/menus.md index 1f8595816,000000000..169b6eb05 mode 100644,000000..100644 --- a/docs/content/en/content-management/menus.md +++ b/docs/content/en/content-management/menus.md @@@ -1,233 -1,0 +1,233 @@@ +--- +title: Menus +description: Create menus by defining entries, localizing each entry, and rendering the resulting data structure. +categories: [content management] +keywords: [menus] +menu: + docs: + parent: content-management + weight: 190 +weight: 190 +toc: true +aliases: [/extras/menus/] +--- + +## Overview + +To create a menu for your site: + +1. Define the menu entries +2. [Localize] each entry +3. Render the menu with a [template] + +Create multiple menus, either flat or nested. For example, create a main menu for the header, and a separate menu for the footer. + +There are three ways to define menu entries: + +1. Automatically +1. In front matter +1. In site configuration + +{{% note %}} +Although you can use these methods in combination when defining a menu, the menu will be easier to conceptualize and maintain if you use one method throughout the site. +{{% /note %}} + +## Define automatically + +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" +{{< /code-toggle >}} + +This creates a menu structure that you can access with `site.Menus.main` in your templates. See [menu templates] for details. + +## Define in front matter + +To add a page to the "main" menu: + +{{< code-toggle file=content/about.md fm=true >}} +title = 'About' +menus = 'main' +{{< /code-toggle >}} + +Access the entry with `site.Menus.main` in your templates. See [menu templates] for details. + +To add a page to the "main" and "footer" menus: + +{{< code-toggle file=content/contact.md fm=true >}} +title = 'Contact' +menus = ['main','footer'] +{{< /code-toggle >}} + +Access the entry with `site.Menus.main` and `site.Menus.footer` in your templates. See [menu templates] for details. + +{{% note %}} +The configuration key in the examples above is `menus`. The `menu` (singular) configuration key is an alias for `menus`. +{{% /note %}} + +### Properties {#properties-front-matter} + +Use these properties when defining menu entries in front matter: + +identifier +: (`string`) Required when two or more menu entries have the same `name`, or when localizing the `name` using translation tables. Must start with a letter, followed by letters, digits, or underscores. + +name +: (`string`) The text to display when rendering the menu entry. + +params +: (`map`) User-defined properties for the menu entry. + +parent +: (`string`) The `identifier` of the parent menu entry. If `identifier` is not defined, use `name`. Required for child entries in a nested menu. + +post +: (`string`) The HTML to append when rendering the menu entry. + +pre +: (`string`) The HTML to prepend when rendering the menu entry. + +title +: (`string`) The HTML `title` attribute of the rendered menu entry. + +weight +: (`int`) A non-zero integer indicating the entry's position relative the root of the menu, or to its parent for a child entry. Lighter entries float to the top, while heavier entries sink to the bottom. + +### Example {#example-front-matter} + +This front matter menu entry demonstrates some of the available properties: + +{{< code-toggle file=content/products/software.md fm=true >}} +title = 'Software' +[[menus.main]] +parent = 'Products' +weight = 20 +pre = '' +[menus.main.params] +class = 'center' +{{< /code-toggle >}} + +Access the entry with `site.Menus.main` in your templates. See [menu templates] for details. + +## Define in site configuration + +To define entries for the "main" menu: + +{{< code-toggle file=hugo >}} +[[menus.main]] +name = 'Home' +pageRef = '/' +weight = 10 + +[[menus.main]] +name = 'Products' +pageRef = '/products' +weight = 20 + +[[menus.main]] +name = 'Services' +pageRef = '/services' +weight = 30 +{{< /code-toggle >}} + +This creates a menu structure that you can access with `site.Menus.main` in your templates. See [menu templates] for details. + +To define entries for the "footer" menu: + +{{< code-toggle file=hugo >}} +[[menus.footer]] +name = 'Terms' +pageRef = '/terms' +weight = 10 + +[[menus.footer]] +name = 'Privacy' +pageRef = '/privacy' +weight = 20 +{{< /code-toggle >}} + +This creates a menu structure that you can access with `site.Menus.footer` in your templates. See [menu templates] for details. + +{{% note %}} +The configuration key in the examples above is `menus`. The `menu` (singular) configuration key is an alias for `menus`. +{{% /note %}} + +### Properties {#properties-site-configuration} + +{{% note %}} +The [properties available to entries defined in front matter] are also available to entries defined in site configuration. + +[properties available to entries defined in front matter]: /content-management/menus/#properties-front-matter +{{% /note %}} + +Each menu entry defined in site configuration requires two or more properties: + +- Specify `name` and `pageRef` for internal links +- Specify `name` and `url` for external links + +pageRef +: (`string`) The logical path of the target page, relative to the `content` directory. Omit language code and file extension. Required for *internal* links. + +Kind|pageRef +:--|:-- +home|`/` +page|`/books/book-1` +section|`/books` +taxonomy|`/tags` +term|`/tags/foo` + +url +: (`string`) Required for *external* links. + +### Example {#example-site-configuration} + +This nested menu demonstrates some of the available properties: + +{{< code-toggle file=hugo >}} +[[menus.main]] +name = 'Products' +pageRef = '/products' +weight = 10 + +[[menus.main]] +name = 'Hardware' +pageRef = '/products/hardware' +parent = 'Products' +weight = 1 + +[[menus.main]] +name = 'Software' +pageRef = '/products/software' +parent = 'Products' +weight = 2 + +[[menus.main]] +name = 'Services' +pageRef = '/services' +weight = 20 + +[[menus.main]] +name = 'Hugo' +pre = '' +url = 'https://gohugo.io/' +weight = 30 +[menus.main.params] +rel = 'external' +{{< /code-toggle >}} + +This creates a menu structure that you can access with `site.Menus.main` in your templates. See [menu templates] for details. + +## Localize + +Hugo provides two methods to localize your menu entries. See [multilingual]. + +## Render + +See [menu templates]. + +[localize]: /content-management/multilingual/#menus - [menu templates]: /templates/menu-templates/ ++[menu templates]: /templates/menu/ +[multilingual]: /content-management/multilingual/#menus +[section]: /getting-started/glossary/#section - [template]: /templates/menu-templates/ ++[template]: /templates/menu/ diff --cc docs/content/en/content-management/multilingual.md index 22e2c186a,000000000..4529eb1c4 mode 100644,000000..100644 --- a/docs/content/en/content-management/multilingual.md +++ b/docs/content/en/content-management/multilingual.md @@@ -1,634 -1,0 +1,631 @@@ +--- +title: Multilingual mode +linkTitle: Multilingual +description: Localize your project for each language and region, including translations, images, dates, currencies, numbers, percentages, and collation sequence. Hugo's multilingual framework supports single-host and multihost configurations. +categories: [content management] +keywords: [multilingual,i18n,internationalization] +menu: + docs: + parent: content-management + weight: 230 +weight: 230 +toc: true +aliases: [/content/multilingual/,/tutorials/create-a-multilingual-site/] +--- + +## 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 >}} +defaultContentLanguage = 'de' +defaultContentLanguageInSubdir = true + +[languages.de] +contentDir = 'content/de' +disabled = false +languageCode = 'de-DE' +languageDirection = 'ltr' +languageName = 'Deutsch' +title = 'Projekt Dokumentation' +weight = 1 + +[languages.de.params] +subtitle = 'Referenz, Tutorials und Erklärungen' + +[languages.en] +contentDir = 'content/en' +disabled = false +languageCode = 'en-US' +languageDirection = 'ltr' +languageName = 'English' +title = 'Project Documentation' +weight = 2 + +[languages.en.params] +subtitle = 'Reference, Tutorials, and Explanations' +{{< /code-toggle >}} + +defaultContentLanguage +: (`string`) The project's default language key, conforming to the syntax described in [RFC 5646]. This value must match one of the defined language keys. Examples: + +- `en` +- `en-GB` +- `pt-BR` + +defaultContentLanguageInSubdir +: (`bool`) If `true`, Hugo renders the default language site in a subdirectory matching the `defaultContentLanguage`. Default is `false`. + +contentDir +: (`string`) The content directory for this language. Omit if [translating by file name]. + +disabled +: (`bool`) If `true`, Hugo will not render content for this language. Default is `false`. + +languageCode +: (`string`) The language tag as described in [RFC 5646]. This value does not affect localization or URLs. Hugo uses this value to populate the `language` element in the [built-in RSS template], and the `lang` attribute of the `html` element in the [built-in alias template]. Examples: + +- `en` +- `en-GB` +- `pt-BR` + +languageDirection +: (`string`) The language direction, either left-to-right (`ltr`) or right-to-left (`rtl`). Use this value in your templates with the global [`dir`] HTML attribute. + +languageName +: (`string`) The language name, typically used when rendering a language switcher. + +title - : (`string`) The site title for this langauge (optional). ++: (`string`) The site title for this language (optional). + +weight +: (`int`) The language weight. When set to a non-zero value, this is the primary sort criteria for this language. + +[`dir`]: https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/dir +[built-in RSS template]: https://github.com/gohugoio/hugo/blob/master/tpl/tplimpl/embedded/templates/_default/rss.xml +[built-in alias template]: https://github.com/gohugoio/hugo/blob/master/tpl/tplimpl/embedded/templates/alias.html +[RFC 5646]: https://datatracker.ietf.org/doc/html/rfc5646#section-2.1 +[translating by file name]: #translation-by-file-name + +### Changes in Hugo 0.112.0 + +{{< new-in 0.112.0 >}} + +In Hugo `v0.112.0` we consolidated all configuration options, and improved how the languages and their parameters are merged with the main configuration. But while testing this on Hugo sites out there, we received some error reports and reverted some of the changes in favor of deprecation warnings: + +1. `site.Language.Params` is deprecated. Use `site.Params` directly. +1. Adding custom parameters to the top level language configuration is deprecated. Define custom parameters within `languages.xx.params`. See `color` in the example below. + +{{< code-toggle file=hugo >}} + +title = "My blog" +languageCode = "en-us" + +[languages] +[languages.sv] +title = "Min blogg" +languageCode = "sv" +[languages.en.params] +color = "blue" +{{< /code-toggle >}} + +In the example above, all settings except `color` below `params` map to predefined configuration options in Hugo for the site and its language, and should be accessed via the documented accessors: + +```go-html-template +{{ site.Title }} +{{ site.LanguageCode }} +{{ site.Params.color }} +``` + +### Disable a language + +To disable a language within a `languages` object in your site configuration: + +{{< code-toggle file=hugo >}} +[languages.es] +disabled = true +{{< /code-toggle >}} + +To disable one or more languages in the root of your site configuration: + +{{< code-toggle file=hugo >}} +disableLanguages = ["es", "fr"] +{{< /code-toggle >}} + +To disable one or more languages using an environment variable: + +```sh +HUGO_DISABLELANGUAGES="es fr" hugo +``` + +Note that you cannot disable the default content language. + +### Configure multilingual multihost + + +Hugo supports multiple languages in a multihost configuration. This means you can configure a `baseURL` per `language`. + +{{% note %}} +If a `baseURL` is set on the `language` level, then all languages must have one and they must all be different. +{{% /note %}} + +Example: + +{{< code-toggle file=hugo >}} +[languages] + [languages.en] + baseURL = 'https://en.example.org/' + languageName = 'English' + title = 'In English' + weight = 2 + [languages.fr] + baseURL = 'https://fr.example.org' + languageName = 'Français' + title = 'En Français' + weight = 1 +{{}} + +With the above, the two sites will be generated into `public` with their own root: + +```text +public +├── en +└── fr +``` + +**All URLs (i.e `.Permalink` etc.) will be generated from that root. So the English home page above will have its `.Permalink` set to `https://example.org/`.** + +When you run `hugo server` we will start multiple HTTP servers. You will typically see something like this in the console: + +```text +Web Server is available at 127.0.0.1:1313 (bind address 127.0.0.1) fr +Web Server is available at 127.0.0.1:1314 (bind address 127.0.0.1) en +Press Ctrl+C to stop +``` + +Live reload and `--navigateToChanged` between the servers work as expected. + +## Translate your content + +There are two ways to manage your content translations. Both ensure each page is assigned a language and is linked to its counterpart translations. + +### Translation by file name + +Considering the following example: + +1. `/content/about.en.md` +2. `/content/about.fr.md` + +The first file is assigned the English language and is linked to the second. +The second file is assigned the French language and is linked to the first. + +Their language is __assigned__ according to the language code added as a __suffix to the file name__. + +By having the same **path and base file name**, the content pieces are __linked__ together as translated pages. + +{{% note %}} +If a file has no language code, it will be assigned the default language. +{{% /note %}} + +### Translation by content directory + +This system uses different content directories for each of the languages. Each language's content directory is set using the `contentDir` parameter. + +{{< code-toggle file=hugo >}} +languages: + en: + weight: 10 + languageName: "English" + contentDir: "content/english" + fr: + weight: 20 + languageName: "Français" + contentDir: "content/french" +{{< /code-toggle >}} + +The value of `contentDir` can be any valid path -- even absolute path references. The only restriction is that the content directories cannot overlap. + +Considering the following example in conjunction with the configuration above: + +1. `/content/english/about.md` +2. `/content/french/about.md` + +The first file is assigned the English language and is linked to the second. +The second file is assigned the French language and is linked to the first. + +Their language is __assigned__ according to the content directory they are __placed__ in. + +By having the same **path and basename** (relative to their language content directory), the content pieces are __linked__ together as translated pages. + +### Bypassing default linking + +Any pages sharing the same `translationKey` set in front matter will be linked as translated pages regardless of basename or location. + +Considering the following example: + +1. `/content/about-us.en.md` +2. `/content/om.nn.md` +3. `/content/presentation/a-propos.fr.md` + +{{< code-toggle >}} +translationKey: "about" +{{< /code-toggle >}} + +By setting the `translationKey` front matter parameter to `about` in all three pages, they will be __linked__ as translated pages. + +### Localizing permalinks + +Because paths and file names are used to handle linking, all translated pages will share the same URL (apart from the language subdirectory). + +To localize URLs: + +- For a regular page, set either [`slug`] or [`url`] in front matter +- For a section page, set [`url`] in front matter + +[`slug`]: /content-management/urls/#slug +[`url`]: /content-management/urls/#url + +For example, a French translation can have its own localized slug. + +{{< code-toggle file=content/about.fr.md fm=true >}} +title: A Propos +slug: "a-propos" +{{< /code-toggle >}} + +At render, Hugo will build both `/about/` and `/fr/a-propos/` without affecting the translation link. + +### Page bundles + +To avoid the burden of having to duplicate files, each Page Bundle inherits the resources of its linked translated pages' bundles except for the content files (Markdown files, HTML files etc...). + +Therefore, from within a template, the page will have access to the files from all linked pages' bundles. + +If, across the linked bundles, two or more files share the same basename, only one will be included and chosen as follows: + +* File from current language bundle, if present. +* First file found across bundles by order of language `Weight`. + +{{% note %}} +Page Bundle resources follow the same language assignment logic as content files, both by file name (`image.jpg`, `image.fr.jpg`) and by directory (`english/about/header.jpg`, `french/about/header.jpg`). +{{%/ note %}} + +## Reference translated content + +To create a list of links to translated content, use a template similar to the following: + +{{< code file=layouts/partials/i18nlist.html >}} +{{ if .IsTranslated }} +

{{ i18n "translations" }}

+ +{{ end }} +{{< /code >}} + - The above can be put in a `partial` (i.e., inside `layouts/partials/`) and included in any template, whether a [single content page][contenttemplate] or the [homepage]. It will not print anything if there are no translations for a given page. ++The above can be put in a `partial` (i.e., inside `layouts/partials/`) and included in any template. It will not print anything if there are no translations for a given page. + +The above also uses the [`i18n` function][i18func] described in the next section. + +### List all available languages + +`.AllTranslations` on a `Page` can be used to list all translations, including the page itself. On the home page it can be used to build a language navigator: + +{{< code file=layouts/partials/allLanguages.html >}} + +{{< /code >}} + +## Translation of strings + +See the [`lang.Translate`] template function. + +[`lang.Translate`]: /functions/lang/translate + +## Localization + +The following localization examples assume your site's primary language is English, with translations to French and German. + +{{< code-toggle file=hugo >}} +defaultContentLanguage = 'en' + +[languages] +[languages.en] +contentDir = 'content/en' +languageName = 'English' +weight = 1 +[languages.fr] +contentDir = 'content/fr' +languageName = 'Français' +weight = 2 +[languages.de] +contentDir = 'content/de' +languageName = 'Deutsch' +weight = 3 + +{{< /code-toggle >}} + +### Dates + +With this front matter: + +{{< code-toggle >}} +date = 2021-11-03T12:34:56+01:00 +{{< /code-toggle >}} + +And this template code: + +```go-html-template +{{ .Date | time.Format ":date_full" }} +``` + +The rendered page displays: + +Language|Value +:--|:-- +English|Wednesday, November 3, 2021 +Français|mercredi 3 novembre 2021 +Deutsch|Mittwoch, 3. November 2021 + +See [`time.Format`] for details. + +### Currency + +With this template code: + +```go-html-template +{{ 512.5032 | lang.FormatCurrency 2 "USD" }} +``` + +The rendered page displays: + +Language|Value +:--|:-- +English|$512.50 +Français|512,50 $US +Deutsch|512,50 $ + +See [lang.FormatCurrency] and [lang.FormatAccounting] for details. + +### Numbers + +With this template code: + +```go-html-template +{{ 512.5032 | lang.FormatNumber 2 }} +``` + +The rendered page displays: + +Language|Value +:--|:-- +English|512.50 +Français|512,50 +Deutsch|512,50 + +See [lang.FormatNumber] and [lang.FormatNumberCustom] for details. + +### Percentages + +With this template code: + +```go-html-template +{{ 512.5032 | lang.FormatPercent 2 }} +``` + +The rendered page displays: + +Language|Value +:--|:-- +English|512.50% +Français|512,50 % +Deutsch|512,50 % + +See [lang.FormatPercent] for details. + +## Menus + +Localization of menu entries depends on how you define them: + +- When you define menu entries [automatically] using the section pages menu, you must use translation tables to localize each entry. +- When you define menu entries [in front matter], they are already localized based on the front matter itself. If the front matter values are insufficient, use translation tables to localize each entry. +- When you define menu entries [in site configuration], you must create language-specific menu entries under each language key. If the names of the menu entries are insufficient, use translation tables to localize each entry. + +### Create language-specific menu entries + +#### Method 1 -- Use a single configuration file + +For a simple menu with a small number of entries, use a single configuration file. For example: + +{{< code-toggle file=hugo >}} +[languages.de] +languageCode = 'de-DE' +languageName = 'Deutsch' +weight = 1 + +[[languages.de.menus.main]] +name = 'Produkte' +pageRef = '/products' +weight = 10 + +[[languages.de.menus.main]] +name = 'Leistungen' +pageRef = '/services' +weight = 20 + +[languages.en] +languageCode = 'en-US' +languageName = 'English' +weight = 2 + +[[languages.en.menus.main]] +name = 'Products' +pageRef = '/products' +weight = 10 + +[[languages.en.menus.main]] +name = 'Services' +pageRef = '/services' +weight = 20 +{{< /code-toggle >}} + +#### Method 2 -- Use a configuration directory + +With a more complex menu structure, create a [configuration directory] and split the menu entries into multiple files, one file per language. For example: + +```text +config/ +└── _default/ + ├── menus.de.toml + ├── menus.en.toml + └── hugo.toml +``` + +{{< code-toggle file=config/_default/menus.de >}} +[[main]] +name = 'Produkte' +pageRef = '/products' +weight = 10 +[[main]] +name = 'Leistungen' +pageRef = '/services' +weight = 20 +{{< /code-toggle >}} + +{{< code-toggle file=config/_default/menus.en >}} +[[main]] +name = 'Products' +pageRef = '/products' +weight = 10 +[[main]] +name = 'Services' +pageRef = '/services' +weight = 20 +{{< /code-toggle >}} + +[configuration directory]: /getting-started/configuration/#configuration-directory + +### Use translation tables + +When rendering the text that appears in menu each entry, the [example menu template] does this: + +```go-html-template +{{ or (T .Identifier) .Name | safeHTML }} +``` + +It queries the translation table for the current language using the menu entry's `identifier` and returns the translated string. If the translation table does not exist, or if the `identifier` key is not present in the translation table, it falls back to `name`. + +The `identifier` depends on how you define menu entries: + +- If you define the menu entry [automatically] using the section pages menu, the `identifier` is the page's `.Section`. +- If you define the menu entry [in site configuration] or [in front matter], set the `identifier` property to the desired value. + +For example, if you define menu entries in site configuration: + +{{< code-toggle file=hugo >}} +[[menus.main]] + identifier = 'products' + name = 'Products' + pageRef = '/products' + weight = 10 +[[menus.main]] + identifier = 'services' + name = 'Services' + pageRef = '/services' + weight = 20 +{{< / code-toggle >}} + +Create corresponding entries in the translation tables: + +{{< code-toggle file=i18n/de >}} +products = 'Produkte' +services = 'Leistungen' +{{< / code-toggle >}} + - [example menu template]: /templates/menu-templates/#example ++[example menu template]: /templates/menu/#example +[automatically]: /content-management/menus/#define-automatically +[in front matter]: /content-management/menus/#define-in-front-matter +[in site configuration]: /content-management/menus/#define-in-site-configuration + +## Missing translations + +If a string does not have a translation for the current language, Hugo will use the value from the default language. If no default value is set, an empty string will be shown. + +While translating a Hugo website, it can be handy to have a visual indicator of missing translations. The [`enableMissingTranslationPlaceholders` configuration option][config] will flag all untranslated strings with the placeholder `[i18n] identifier`, where `identifier` is the id of the missing translation. + +{{% note %}} +Hugo will generate your website with these missing translation placeholders. It might not be suitable for production environments. +{{% /note %}} + +For merging of content from other languages (i.e. missing content translations), see [lang.Merge]. + +To track down missing translation strings, run Hugo with the `--printI18nWarnings` flag: + +```sh +hugo --printI18nWarnings | grep i18n +i18n|MISSING_TRANSLATION|en|wordCount +``` + +## Multilingual themes support + +To support Multilingual mode in your themes, some considerations must be taken for the URLs in the templates. If there is more than one language, URLs must meet the following criteria: + +* Come from the built-in `.Permalink` or `.RelPermalink` +* Be constructed with the [`relLangURL`] or [`absLangURL`] template function, or be prefixed with `{{ .LanguagePrefix }}` + +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` + +If you organize content with translations in the same directory: + +```sh +hugo new content post/test.en.md +hugo new content post/test.de.md +``` + +If you organize content with translations in different directories: + +```sh +hugo new content content/en/post/test.md +hugo new content content/de/post/test.md +``` + +[`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/ +[lang.Merge]: /functions/lang/merge/ +[menus]: /content-management/menus/ +[OS environment]: /getting-started/configuration/#configure-with-environment-variables +[`rellangurl`]: /functions/urls/rellangurl/ - [single page templates]: /templates/single-page-templates/ +[`time.Format`]: /functions/time/format/ diff --cc docs/content/en/content-management/organization/index.md index e286462d7,000000000..99a3224bf mode 100644,000000..100644 --- a/docs/content/en/content-management/organization/index.md +++ b/docs/content/en/content-management/organization/index.md @@@ -1,169 -1,0 +1,162 @@@ +--- +title: Content organization +linkTitle: Organization +description: Hugo assumes that the same structure that works to organize your source content is used to organize the rendered site. +categories: [content management,fundamentals] +keywords: [sections,content,organization,bundle,resources] +menu: + docs: + parent: content-management + weight: 20 +weight: 20 +toc: true +aliases: [/content/sections/] +--- + +## Page bundles + +Hugo `0.32` announced page-relative images and other resources packaged into `Page Bundles`. + +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. + +```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 +``` + +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 + +In Hugo, your content should be organized in a manner that reflects the rendered website. + +While Hugo supports content nested at any level, the top levels (i.e. `content/`) are special in Hugo and are considered the content type used to determine layouts etc. To read more about sections, including how to nest them, see [sections]. + +Without any additional configuration, the following will automatically work: + +```txt +. +└── content + └── about + | └── index.md // <- https://example.org/about/ + ├── posts + | ├── firstpost.md // <- https://example.org/posts/firstpost/ + | ├── happy + | | └── ness.md // <- https://example.org/posts/happy/ness/ + | └── secondpost.md // <- https://example.org/posts/secondpost/ + └── quote + ├── first.md // <- https://example.org/quote/first/ + └── second.md // <- https://example.org/quote/second/ +``` + +## 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]. + +### Index pages: `_index.md` + - `_index.md` has a special role in Hugo. It allows you to add front matter and content to your [list templates][lists]. These templates include those for [section templates], [taxonomy templates], [taxonomy terms templates], and your [homepage template]. ++`_index.md` has a special role in Hugo. It allows you to add front matter and content to `home`, `section`, `taxonomy`, and `term` pages. + +{{% note %}} +**Tip:** You can get a reference to the content and metadata in `_index.md` using the [`.Site.GetPage` function](/methods/page/getpage). +{{% /note %}} + - You can create one `_index.md` for your homepage and one in each of your content sections, taxonomies, and taxonomy terms. The following shows typical placement of an `_index.md` that would contain content and front matter for a `posts` section list page on a Hugo website: ++You can create one `_index.md` for your home page and one in each of your content sections, taxonomies, and terms. The following shows typical placement of an `_index.md` that would contain content and front matter for a `posts` section list page on a Hugo website: + +```txt +. url +. ⊢--^-⊣ +. path slug +. ⊢--^-⊣⊢---^---⊣ +. file path +. ⊢------^------⊣ +content/posts/_index.md +``` + +At build, this will output to the following destination with the associated values: + +```txt + + url ("/posts/") + ⊢-^-⊣ + baseurl section ("posts") +⊢--------^---------⊣⊢-^-⊣ + permalink +⊢----------^-------------⊣ +https://example.org/posts/index.html +``` + +The [sections] can be nested as deeply as you want. The important thing to understand is that to make the section tree fully navigational, at least the lower-most section must include a content file. (i.e. `_index.md`). + +### Single pages in sections + - Single content files in each of your sections will be rendered as [single page templates][singles]. Here is an example of a single `post` within `posts`: ++Single content files in each of your sections will be rendered by a [single template]. Here is an example of a single `post` within `posts`: + +```txt + path ("posts/my-first-hugo-post.md") +. ⊢-----------^------------⊣ +. section slug +. ⊢-^-⊣⊢--------^----------⊣ +content/posts/my-first-hugo-post.md +``` + +When Hugo builds your site, the content will be output to the following destination: + +```txt + + url ("/posts/my-first-hugo-post/") + ⊢------------^----------⊣ + baseurl section slug +⊢--------^--------⊣⊢-^--⊣⊢-------^---------⊣ + permalink +⊢--------------------^---------------------⊣ +https://example.org/posts/my-first-hugo-post/index.html +``` + +## Paths explained + +The following concepts provide more insight into the relationship between your project's organization and the default Hugo behavior when building output for the website. + +### `section` + +A default content type is determined by the section in which a content item is stored. `section` is determined by the location within the project's `content` directory. `section` *cannot* be specified or overridden in front matter. + +### `slug` + +The `slug` is the last segment of the URL path, defined by the file name and optionally overridden by a `slug` value in front matter. See [URL Management](/content-management/urls/#slug) for details. + +### `path` + +A content's `path` is determined by the section's path to the file. The file `path` + +* is based on the path to the content's location AND +* does not include the slug + +### `url` + +The `url` is the entire URL path, defined by the file path and optionally overridden by a `url` value in front matter. See [URL Management](/content-management/urls/#slug) for details. + +[config]: /getting-started/configuration/ +[formats]: /content-management/formats/ +[front matter]: /content-management/front-matter/ +[getpage]: /methods/page/getpage/ - [homepage template]: /templates/homepage/ - [homepage]: /templates/homepage/ - [lists]: /templates/lists/ +[pretty]: /content-management/urls/#appearance - [section templates]: /templates/section-templates/ +[sections]: /content-management/sections/ - [singles]: /templates/single-page-templates/ - [taxonomy templates]: /templates/taxonomy-templates/ - [taxonomy terms templates]: /templates/taxonomy-templates/ - [types]: /content-management/types/ ++[single template]: /templates/types/#single +[urls]: /content-management/urls/ diff --cc docs/content/en/content-management/page-bundles.md index af7c2ce14,000000000..b83bb0ba5 mode 100644,000000..100644 --- a/docs/content/en/content-management/page-bundles.md +++ b/docs/content/en/content-management/page-bundles.md @@@ -1,157 -1,0 +1,161 @@@ +--- +title: Page bundles +description: Use page bundles to logically associate one or more resources with content. +categories: [content management] +keywords: [page,bundle,leaf,branch] +menu : + docs: + parent: content-management + weight: 30 +weight: 30 +toc: true +--- + +## Introduction + +A page bundle is a directory that encapsulates both content and associated resources. + +By way of example, this site has an "about" page and a "privacy" page: + +```text +content/ +├── about/ +│ ├── index.md +│ └── welcome.jpg +└── privacy.md +``` + +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 %}} + +## Comparison + +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] | ++| Template types | [single] | [home], [section], [taxonomy], or [term] | +| 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` | + ++[single]: /templates/types/#single ++[home]: /templates/types/#home ++[section]: /templates/types/#section ++[taxonomy]: /templates/types/#taxonomy ++[term]: /templates/types/#term ++ +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 +├── posts +│ ├── my-post +│ │ ├── 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 +``` + +There are four leaf bundles in the example above: + +about +: This leaf bundle does not contain any page resources. + +my-post +: This leaf bundle contains an index file, two resources of [resource type] `page`, and two resources of resource type `image`. + +- content-1, content-2 + + These are resources of resource type `page`, accessible via the [`Resources`] method on the `Page` object. Hugo will not render these as individual pages. + +- 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 does not contain any page resources. + +another-leaf-bundle +: This leaf bundle does not contain any page resources. + +{{% note %}} +Create leaf bundles at any depth within the content directory, but a leaf bundle may not contain another bundle. Leaf bundles do not have descendants. +{{% /note %}} + +## Branch bundles + +A _branch bundle_ is a directory that contains an _index.md file and zero or more resources. Analogous to a physical branch, a branch bundle may have descendants including leaf bundles and other branch bundles. Top level directories with or without _index.md files are also branch bundles. This includes the home page. + +```text +content/ +├── 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 +└── _index.md +``` + +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 contains an index file, two resources of [resource type] `page`, and two resources of resource type `image`. + +branch-bundle-2 +: This branch bundle contains an index file and a leaf bundle. + +{{% note %}} +Create branch bundles at any depth within the content directory, but a leaf bundle may not contain another bundle. Leaf bundles do not have descendants. +{{% /note %}} + + +## 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 --cc docs/content/en/content-management/related.md index 478b55a99,000000000..0a97bd7cb mode 100644,000000..100644 --- a/docs/content/en/content-management/related.md +++ b/docs/content/en/content-management/related.md @@@ -1,178 -1,0 +1,178 @@@ +--- +title: Related content +description: List related content in "See Also" sections. +categories: [content management] +keywords: [content] +menu: + docs: + parent: content-management + weight: 110 +weight: 110 +toc: true +aliases: [/content/related/,/related/] +--- + +Hugo uses a set of factors to identify a page's related content based on front matter parameters. This can be tuned to the desired set of indices and parameters or left to Hugo's default [Related Content configuration](#configure-related-content). + +## List related content + - To list up to 5 related pages (which share the same _date_ or _keyword_ parameters) is as simple as including something similar to this partial in your single page template: ++To list up to 5 related pages (which share the same _date_ or _keyword_ parameters) is as simple as including something similar to this partial in your template: + +{{< code file=layouts/partials/related.html >}} +{{ $related := .Site.RegularPages.Related . | first 5 }} +{{ with $related }} +

See Also

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

See Also

+
    + {{ range $i, $p := . }} +
  • + {{ .LinkTitle }} + {{ with .HeadingsFiltered }} +
      + {{ range . }} + {{ $link := printf "%s#%s" $p.RelPermalink .ID | safeURL }} +
    • + {{ .Title }} +
      • + {{ end }} +
    + {{ end }} +
    • + {{ end }} +
+{{ end }} +``` + +## Configure related content + +Hugo provides a sensible default configuration of Related Content, but you can fine-tune this in your configuration, on the global or language level if needed. + +### Default configuration + +Without any `related` configuration set on the project, Hugo's Related Content methods will use the following. + +{{< code-toggle config=related />}} + +Custom configuration should be set using the same syntax. + +{{% note %}} +If you add a `related` configuration section, you need to add a complete configuration. It is not possible to just set, say, `includeNewer` and use the rest from the Hugo defaults. +{{% /note %}} + +### Top level configuration options + +threshold +: (`int`) A value between 0-100. Lower value will give more, but maybe not so relevant, matches. + +includeNewer +: (`bool`) Set to `true` to include **pages newer than the current page** in the related content listing. This will mean that the output for older posts may change as new related content gets added. + +toLower +: (`bool`) Set to `true` to lower case keywords in both the indexes and the queries. This may give more accurate results at a slight performance penalty. Note that this can also be set per index. + +### Configuration options per index + +name +: (`string`) The index name. This value maps directly to a page parameter. Hugo supports string values (`author` in the example) and lists (`tags`, `keywords` etc.) and time and date objects. + +type {{< new-in 0.111.0 >}} +: (`string`) One of `basic`(default) or `fragments`. + +applyFilter {{< new-in 0.111.0 >}} +: (`string`) Apply a `type` specific filter to the result of a search. This is currently only used for the `fragments` type. + +weight +: (`int`) An integer weight that indicates _how important_ this parameter is relative to the other parameters. It can be `0`, which has the effect of turning this index off, or even negative. Test with different values to see what fits your content best. + +cardinalityThreshold {{< new-in 0.111.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. + +toLower +: (`bool`) See above. + +## Performance considerations + +**Fast is Hugo's middle name** and we would not have released this feature had it not been blistering fast. + +This feature has been in the back log and requested by many for a long time. The development got this recent kick start from this Twitter thread: + +{{< tweet user="scott_lowe" id="898398437527363585" >}} + +Scott S. Lowe removed the "Related Content" section built using the `intersect` template function on tags, and the build time dropped from 30 seconds to less than 2 seconds on his 1700 content page sized blog. + +He should now be able to add an improved version of that "Related Content" section without giving up the fast live-reloads. But it's worth noting that: + +* If you don't use any of the `Related` methods, you will not use the Relate Content feature, and performance will be the same as before. +* Calling `.RegularPages.Related` etc. will create one inverted index, also sometimes named posting list, that will be reused for any lookups in that same page collection. Doing that in addition to, as an example, calling `.Pages.Related` will work as expected, but will create one additional inverted index. This should still be very fast, but worth having in mind, especially for bigger sites. + +{{% note %}} +We currently do not index **Page content**. We thought we would release something that will make most people happy before we start solving [Sherlock's last case](https://github.com/joearms/sherlock). +{{% /note %}} diff --cc docs/content/en/content-management/sections.md index 0c2f8f0e2,000000000..03655c90a mode 100644,000000..100644 --- a/docs/content/en/content-management/sections.md +++ b/docs/content/en/content-management/sections.md @@@ -1,164 -1,0 +1,164 @@@ +--- +title: Sections +description: Organize content into sections. + +categories: [content management] +keywords: [lists,sections,content types,organization] +menu: + docs: + parent: content-management + weight: 120 +weight: 120 +toc: true +aliases: [/content/sections/] +--- + +## Overview + +A section is a top-level content directory, or any content directory with an _index.md file. A content directory with an _index.md file is also known as a [branch bundle](/getting-started/glossary/#branch-bundle). Section templates receive one or more page [collections](/getting-started/glossary/#collection) in [context](/getting-started/glossary/#context). + +{{% note %}} +Although top-level directories without _index.md files are sections, we recommend creating _index.md files in _all_ sections. +{{% /note %}} + +A typical site consists of one or more sections. For example: + +```text +content/ +├── articles/ <-- section (top-level directory) +│ ├── 2022/ +│ │ ├── article-1/ +│ │ │ ├── cover.jpg +│ │ │ └── index.md +│ │ └── article-2.md +│ └── 2023/ +│ ├── article-3.md +│ └── article-4.md +├── products/ <-- section (top-level directory) +│ ├── product-1/ <-- section (has _index.md file) +│ │ ├── benefits/ <-- section (has _index.md file) +│ │ │ ├── _index.md +│ │ │ ├── benefit-1.md +│ │ │ └── benefit-2.md +│ │ ├── features/ <-- section (has _index.md file) +│ │ │ ├── _index.md +│ │ │ ├── feature-1.md +│ │ │ └── feature-2.md +│ │ └── _index.md +│ └── product-2/ <-- section (has _index.md file) +│ ├── benefits/ <-- section (has _index.md file) +│ │ ├── _index.md +│ │ ├── benefit-1.md +│ │ └── benefit-2.md +│ ├── features/ <-- section (has _index.md file) +│ │ ├── _index.md +│ │ ├── feature-1.md +│ │ └── feature-2.md +│ └── _index.md +├── _index.md +└── about.md +``` + +The example above has two top-level sections: articles and products. None of the directories under articles are sections, while all of the directories under products are sections. A section within a section is a known as a nested section or subsection. + +## Explanation + +Sections and non-sections behave differently. + +||Sections|Non-sections +:--|:-:|:-: +Directory names become URL segments|:heavy_check_mark:|:heavy_check_mark: +Have logical ancestors and descendants|:heavy_check_mark:|:x: +Have list pages|:heavy_check_mark:|:x: + +With the file structure from the [example above](#overview): + +1. The list page for the articles section includes all articles, regardless of directory structure; none of the subdirectories are sections. + +1. The articles/2022 and articles/2023 directories do not have list pages; they are not sections. + +1. The list page for the products section, by default, includes product-1 and product-2, but not their descendant pages. To include descendant pages, use the `RegularPagesRecursive` method instead of the `Pages` method in the list template. + +[`Pages`]: /methods/page/pages/ +[`RegularPagesRecursive`]: /methods/page/regularpagesrecursive/ + +1. All directories in the products section have list pages; each directory is a section. + +## Template selection + +Hugo has a defined [lookup order] to determine which template to use when rendering a page. The [lookup rules] consider the top-level section name; subsection names are not considered when selecting a template. + +With the file structure from the [example above](#overview): + - Content directory|List page template ++Content directory|Section template +:--|:-- +content/products|layouts/products/list.html +content/products/product-1|layouts/products/list.html +content/products/product-1/benefits|layouts/products/list.html + - Content directory|Single page template ++Content directory|Single template +:--|:-- +content/products|layouts/products/single.html +content/products/product-1|layouts/products/single.html +content/products/product-1/benefits|layouts/products/single.html + +If you need to use a different template for a subsection, specify `type` and/or `layout` in front matter. + +[lookup rules]: /templates/lookup-order/#lookup-rules +[lookup order]: /templates/lookup-order/ + +## Ancestors and descendants + +A section has one or more ancestors (including the home page), and zero or more descendants. With the file structure from the [example above](#overview): + +```text +content/products/product-1/benefits/benefit-1.md +``` + +The content file (benefit-1.md) has four ancestors: benefits, product-1, products, and the home page. This logical relationship allows us to use the `.Parent` and `.Ancestors` methods to traverse the site structure. + +For example, use the `.Ancestors` method to render breadcrumb navigation. + +{{< code file=layouts/partials/breadcrumb.html >}} + +{{< /code >}} + +With this CSS: + +```css +.breadcrumb ol { + padding-left: 0; +} + +.breadcrumb li { + display: inline; +} + +.breadcrumb li:not(:last-child)::after { + content: "»"; +} +``` + +Hugo renders this, where each breadcrumb is a link to the corresponding page: + +```text +Home » Products » Product 1 » Benefits » Benefit 1 +``` + +[archetype]: /content-management/archetypes/ +[content type]: /content-management/types/ +[directory structure]: /getting-started/directory-structure/ - [section templates]: /templates/section-templates/ ++[section templates]: /templates/types/#section +[leaf bundles]: /content-management/page-bundles/#leaf-bundles +[branch bundles]: /content-management/page-bundles/#branch-bundles diff --cc docs/content/en/content-management/shortcodes.md index 87c9f0825,000000000..847ba2bbb mode 100644,000000..100644 --- a/docs/content/en/content-management/shortcodes.md +++ b/docs/content/en/content-management/shortcodes.md @@@ -1,477 -1,0 +1,477 @@@ +--- +title: Shortcodes +description: Shortcodes are simple snippets inside your content files calling built-in or custom templates. +categories: [content management] +keywords: [markdown,content,shortcodes] +menu: + docs: + parent: content-management + weight: 100 +weight: 100 +toc: true +aliases: [/extras/shortcodes/] +testparam: "Hugo Rocks!" +--- + +## What a shortcode is + +Hugo loves Markdown because of its simple content format, but there are times when Markdown falls short. Often, content authors are forced to add raw HTML (e.g., video ` ++ ++{{< /code >}} ++ ++{{< code file=youtube-embed.html >}} ++
++ ++
++{{< /code >}} ++ ++### Single named example: `image` ++ ++Let's say you want to create your own `img` shortcode rather than use Hugo's built-in [`figure` shortcode][figure]. Your goal is to be able to call the shortcode as follows in your content files: ++ ++{{< code file=content-image.md >}} ++{{}} ++{{< /code >}} ++ ++You have created the shortcode at `/layouts/shortcodes/img.html`, which loads the following shortcode template: ++ ++{{< code file=layouts/shortcodes/img.html >}} ++ ++
++ {{ with .Get "link" }}{{ end }} ++ ++ {{ if .Get "link" }}{{ end }} ++ {{ if or (or (.Get "title") (.Get "caption")) (.Get "attr") }} ++
{{ if isset .Params "title" }} ++

{{ .Get "title" }}

{{ end }} ++ {{ if or (.Get "caption") (.Get "attr") }}

++ {{ .Get "caption" }} ++ {{ with .Get "attrlink" }} {{ end }} ++ {{ .Get "attr" }} ++ {{ if .Get "attrlink" }} {{ end }} ++

{{ end }} ++
++ {{ end }} ++
++ ++{{< /code >}} ++ ++Would be rendered as: ++ ++{{< code file=img-output.html >}} ++
++ ++
++

Steve Francia

++
++
++{{< /code >}} ++ ++### Single flexible example: `vimeo` ++ ++```go-html-template ++{{}} ++{{}} ++``` ++ ++Would load the template found at `/layouts/shortcodes/vimeo.html`: ++ ++{{< code file=layouts/shortcodes/vimeo.html >}} ++{{ if .IsNamedParams }} ++
++ ++
++{{ else }} ++
++ ++
++{{ end }} ++{{< /code >}} ++ ++Would be rendered as: ++ ++{{< code file=vimeo-iframes.html >}} ++
++ ++
++
++ ++
++{{< /code >}} ++ ++### Paired example: `highlight` ++ ++The following is taken from `highlight`, which is a [built-in shortcode] that ships with Hugo. ++ ++{{< code file=highlight-example.md >}} ++{{}} ++ ++ This HTML ++ ++{{}} ++{{< /code >}} ++ ++The template for the `highlight` shortcode uses the following code, which is already included in Hugo: ++ ++```go-html-template ++{{ .Get 0 | highlight .Inner }} ++``` ++ ++The rendered output of the HTML example code block will be as follows: ++ ++{{< code file=syntax-highlighted.html >}} ++
<html>
++    <body> This HTML </body>
++</html>
++
++{{< /code >}} ++ ++### 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. ++ ++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 >}} ++
++ {{ .Inner }} ++
++{{< /code >}} ++ ++You also have an `img` shortcode with a single named `src` argument that you want to call inside of `gallery` and other shortcodes, so that the parent defines the context of each `img`: ++ ++{{< code file=layouts/shortcodes/img.html >}} ++{{- $src := .Get "src" -}} ++{{- with .Parent -}} ++ ++{{- else -}} ++ ++{{- end -}} ++{{< /code >}} ++ ++You can then call your shortcode in your content as follows: ++ ++```go-html-template ++{{}} ++ {{}} ++ {{}} ++{{}} ++{{}} ++``` ++ ++This will output the following HTML. Note how the first two `img` shortcodes inherit the `class` value of `content-gallery` set with the call to the parent `gallery`, whereas the third `img` only uses `src`: ++ ++```html ++
++ ++ ++
++ ++``` ++ ++## Error handling in shortcodes ++ ++Use the [`errorf`] template function with the [`Name`] and [`Position`] shortcode methods to generate useful error messages: ++ ++{{< code file=layouts/shortcodes/greeting.html >}} ++{{ with .Get "name" }} ++

Hello, my name is {{ . }}.

++{{ else }} ++ {{ errorf "The %q shortcode requires a 'name' argument. See %s" .Name .Position }} ++{{ end }} ++{{< /code >}} ++ ++When the above fails, you will see an `ERROR` message such as: ++ ++```sh ++ERROR The "greeting" shortcode requires a 'name' argument. See "/home/user/project/content/_index.md:12:1" ++``` ++ ++## Inline shortcodes ++ ++You can also implement your shortcodes inline -- e.g. where you use them in the content file. This can be useful for scripting that you only need in one place. ++ ++This feature is disabled by default, but can be enabled in your site configuration: ++ ++{{< code-toggle file=hugo >}} ++[security] ++enableInlineShortcodes = true ++{{< /code-toggle >}} ++ ++It is disabled by default for security reasons. The security model used by Hugo's template handling assumes that template authors are trusted, but that the content files are not, so the templates are injection-safe from malformed input data. But in most situations you have full control over the content, too, and then `enableInlineShortcodes = true` would be considered safe. But it's something to be aware of: It allows ad-hoc [Go Text templates](https://golang.org/pkg/text/template/) to be executed from the content files. ++ ++And once enabled, you can do this in your content files: ++ ++ ```go-html-template ++ {{}}{{ now }}{{}} ++ ``` ++ ++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. ++ ++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 arguments if needed, using the self-closing syntax: ++ ++ ```go-html-template ++{{}} ++``` ++ ++[`.Parent`]: /methods/shortcode/parent/ ++[`errorf`]: /functions/fmt/errorf/ ++[`Name`]: /methods/shortcode/name/ ++[`Position`]: /methods/shortcode/position/ ++[built-in shortcode]: /content-management/shortcodes/ ++[figure]: /content-management/shortcodes/#figure ++[lookup order]: /templates/lookup-order/ ++[source organization]: /getting-started/directory-structure/ ++[vimeoexample]: #single-flexible-example-vimeo ++[youtubeshortcode]: /content-management/shortcodes/#youtube diff --cc docs/content/en/templates/single.md index 000000000,000000000..f6292ca03 new file mode 100644 --- /dev/null +++ b/docs/content/en/templates/single.md @@@ -1,0 -1,0 +1,56 @@@ ++--- ++title: Single templates ++description: Create a single template to render a single page. ++categories: [templates] ++keywords: [] ++menu: ++ docs: ++ parent: templates ++ weight: 70 ++weight: 70 ++toc: true ++aliases: [/layout/content/,/templates/single-page-templates/] ++--- ++ ++The single template below inherits the site's shell from the [base template]. ++ ++[base template]: /templates/types/ ++ ++{{< code file=layouts/_default/single.html >}} ++{{ define "main" }} ++

{{ .Title }}

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

{{ .Title }}

++ {{ with .Date }} ++ {{ $dateMachine := . | time.Format "2006-01-02T15:04:05-07:00" }} ++ {{ $dateHuman := . | time.Format ":date_long" }} ++ ++ {{ end }} ++
++ {{ .Content }} ++
++ ++
++{{ end }} ++{{< /code >}} diff --cc docs/content/en/templates/sitemap.md index 000000000,000000000..9fc152210 new file mode 100644 --- /dev/null +++ b/docs/content/en/templates/sitemap.md @@@ -1,0 -1,0 +1,82 @@@ ++--- ++title: Sitemap templates ++description: Hugo provides built-in sitemap templates. ++categories: [templates] ++keywords: [] ++menu: ++ docs: ++ parent: templates ++ weight: 140 ++weight: 140 ++toc: true ++aliases: [/layout/sitemap/,/templates/sitemap-template/] ++--- ++ ++## Overview ++ ++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 [embedded sitemap template]. ++ ++With a multilingual project, Hugo generates: ++ ++- A sitemap.xml file in the root of each site (language) using the [embedded sitemap template] ++- A sitemap.xml file in the root of the [`publishDir`] using the [embedded sitemapindex template] ++ ++[embedded sitemap template]: {{% eturl sitemap %}} ++[embedded sitemapindex template]: {{% eturl sitemapindex %}} ++ ++## Configuration ++ ++These are the default sitemap configuration values. They apply to all pages unless overridden in front matter. ++ ++{{< code-toggle config=sitemap />}} ++ ++changefreq ++: (`string`) How frequently a page is likely to change. Valid values are `always`, `hourly`, `daily`, `weekly`, `monthly`, `yearly`, and `never`. With the default value of `""` Hugo will omit this field from the sitemap. See [details](https://www.sitemaps.org/protocol.html#changefreqdef). ++ ++disable {{< new-in 0.125.0 >}} ++: (`bool`) Whether to disable page inclusion. Default is `false`. Set to `true` in front matter to exclude the page. ++ ++filename ++: (`string`) The name of the generated file. Default is `sitemap.xml`. ++ ++priority ++: (`float`) The priority of a page relative to any other page on the site. Valid values range from 0.0 to 1.0. With the default value of `-1` Hugo will omit this field from the sitemap. See [details](https://www.sitemaps.org/protocol.html#priority). ++ ++## Override default values ++ ++Override the default values for a given page in front matter. ++ ++{{< code-toggle file=news.md fm=true >}} ++title = 'News' ++[sitemap] ++ changefreq = 'weekly' ++ disable = true ++ priority = 0.8 ++{{}} ++ ++## Override built-in templates ++ ++To override the built-in sitemap.xml template, create a new file in either of these locations: ++ ++- layouts/sitemap.xml ++- layouts/_default/sitemap.xml ++ ++When ranging through the page collection, access the _change frequency_ and _priority_ with `.Sitemap.ChangeFreq` and `.Sitemap.Priority` respectively. ++ ++To override the built-in sitemapindex.xml template, create a new file in either of these locations: ++ ++- layouts/sitemapindex.xml ++- layouts/_default/sitemapindex.xml ++ ++## Disable sitemap generation ++ ++You may disable sitemap generation in your site configuration: ++ ++{{< code-toggle file=hugo >}} ++disableKinds = ['sitemap'] ++{{}} ++ ++[`publishDir`]: /getting-started/configuration#publishdir ++[sitemap protocol]: diff --cc docs/content/en/templates/taxonomy.md index 000000000,000000000..d0f24b1b2 new file mode 100644 --- /dev/null +++ b/docs/content/en/templates/taxonomy.md @@@ -1,0 -1,0 +1,176 @@@ ++--- ++title: Taxonomy templates ++description: Create a taxonomy template to render a list of terms. ++categories: [templates] ++keywords: [] ++menu: ++ docs: ++ parent: templates ++ weight: 90 ++weight: 90 ++toc: true ++aliases: [/taxonomies/displaying/,/templates/terms/,/indexes/displaying/,/taxonomies/templates/,/indexes/ordering/, /templates/taxonomies/, /templates/taxonomy-templates/] ++--- ++ ++The [taxonomy] template below inherits the site's shell from the [base template], and renders a list of [terms] in the current taxonomy. ++ ++[taxonomy]: /getting-started/glossary/#taxonomy ++[terms]: /getting-started/glossary/#term ++[base template]: /templates/types/ ++ ++{{< code file=layouts/_default/taxonomy.html >}} ++{{ define "main" }} ++

{{ .Title }}

++ {{ .Content }} ++ {{ range .Pages }} ++

{{ .LinkTitle }}

++ {{ end }} ++{{ end }} ++{{< /code >}} ++ ++Review the [template lookup order] to select a template path that provides the desired level of specificity. ++ ++[template lookup order]: /templates/lookup-order/#taxonomy-templates ++ ++In the example above, the taxonomy and term will be capitalized if their respective pages are not backed by files. You can disable this in your site configuration: ++ ++{{< code-toggle file=hugo >}} ++capitalizeListTitles = false ++{{< /code-toggle >}} ++ ++## Data object ++ ++Use these methods on the `Data` object within a taxonomy template. ++ ++Singular ++: (`string`) Returns the singular name of the taxonomy. ++ ++```go-html-template ++{{ .Data.Singular }} → tag ++``` ++ ++Plural ++: (`string`) Returns the plural name of the taxonomy. ++ ++```go-html-template ++{{ .Data.Plural }} → tags ++``` ++ ++Terms ++: (`page.Taxonomy`) Returns the `Taxonomy` object, consisting of a map of terms and the [weighted pages] associated with each term. ++ ++[weighted pages]: /getting-started/glossary/#weighted-page ++ ++```go-html-template ++{{ $taxonomyObject := .Data.Terms }} ++``` ++ ++Once we have the `Taxonomy` object, we can call any of its [methods], allowing us to sort alphabetically or by term count. ++ ++[methods]: /methods/taxonomy/ ++ ++## Sort alphabetically ++ ++The taxonomy template below inherits the site's shell from the base template, and renders a list of terms in the current taxonomy. Hugo sorts the list alphabetically by term, and displays the number of pages associated with each term. ++ ++{{< code file=layouts/_default/taxonomy.html >}} ++{{ define "main" }} ++

{{ .Title }}

++ {{ .Content }} ++ {{ range .Data.Terms.Alphabetical }} ++

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

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

{{ .Title }}

++ {{ .Content }} ++ {{ range .Data.Terms.ByCount }} ++

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

++ {{ end }} ++{{ end }} ++{{< /code >}} ++ ++## Include content links ++ ++The [`Alphabetical`] and [`ByCount`] methods used in the previous examples return an [ordered taxonomy], so we can also list the content to which each term is assigned. ++ ++[ordered taxonomy]: /getting-started/glossary/#ordered-taxonomy ++[`Alphabetical`]: /methods/taxonomy/alphabetical/ ++[`ByCount`]: /methods/taxonomy/bycount/ ++ ++The taxonomy template below inherits the site's shell from the base template, and renders a list of terms in the current taxonomy. Hugo sorts the list by the number of pages associated with each term, displays the number of pages associated with each term, then lists the content to which each term is assigned. ++ ++{{< code file=layouts/_default/taxonomy.html >}} ++{{ define "main" }} ++

{{ .Title }}

++ {{ .Content }} ++ {{ range .Data.Terms.ByCount }} ++

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

++ ++ {{ end }} ++{{ end }} ++{{< /code >}} ++ ++## Display metadata ++ ++Display metadata about each term by creating a corresponding branch bundle in the content directory. ++ ++For example, create an "authors" taxonomy: ++ ++{{< code-toggle file=hugo >}} ++[taxonomies] ++author = 'authors' ++{{< /code-toggle >}} ++ ++Then create content with one [branch bundle] for each term: ++ ++[branch bundle]: /getting-started/glossary/#branch-bundle ++ ++```text ++content/ ++└── authors/ ++ ├── jsmith/ ++ │ ├── _index.md ++ │ └── portrait.jpg ++ └── rjones/ ++ ├── _index.md ++ └── portrait.jpg ++``` ++ ++Then add front matter to each term page: ++ ++{{< code-toggle file=content/authors/jsmith/_index.md fm=true >}} ++title = "John Smith" ++affiliation = "University of Chicago" ++{{< /code-toggle >}} ++ ++Then create a taxonomy template specific to the "authors" taxonomy: ++ ++{{< code file=layouts/authors/taxonomy.html >}} ++{{ define "main" }} ++

{{ .Title }}

++ {{ .Content }} ++ {{ range .Data.Terms.Alphabetical }} ++

{{ .Page.LinkTitle }}

++

Affiliation: {{ .Page.Params.Affiliation }}

++ {{ with .Page.Resources.Get "portrait.jpg" }} ++ {{ with .Fill "100x100" }} ++ portrait ++ {{ end }} ++ {{ end }} ++ {{ end }} ++{{ end }} ++{{< /code >}} ++ ++In the example above we list each author including their affiliation and portrait. diff --cc docs/content/en/templates/term.md index 000000000,000000000..5becd0aa0 new file mode 100644 --- /dev/null +++ b/docs/content/en/templates/term.md @@@ -1,0 -1,0 +1,115 @@@ ++--- ++title: Term templates ++description: Create a term template to render a list of pages associated with the current term. ++categories: [templates] ++keywords: [] ++menu: ++ docs: ++ parent: templates ++ weight: 100 ++weight: 100 ++toc: true ++--- ++ ++The [term] template below inherits the site's shell from the [base template], and renders a list of pages associated with the current term. ++ ++[term]: /getting-started/glossary/#term ++[base template]: /templates/types/ ++ ++{{< code file=layouts/_default/term.html >}} ++{{ define "main" }} ++

{{ .Title }}

++ {{ .Content }} ++ {{ range .Pages }} ++

{{ .LinkTitle }}

++ {{ end }} ++{{ end }} ++{{< /code >}} ++ ++Review the [template lookup order] to select a template path that provides the desired level of specificity. ++ ++[template lookup order]: /templates/lookup-order/#taxonomy-templates ++ ++In the example above, the term will be capitalized if its respective page is not backed by a file. You can disable this in your site configuration: ++ ++{{< code-toggle file=hugo >}} ++capitalizeListTitles = false ++{{< /code-toggle >}} ++ ++## Data object ++ ++Use these methods on the `Data` object within a term template. ++ ++Singular ++: (`string`) Returns the singular name of the taxonomy. ++ ++```go-html-template ++{{ .Data.Singular }} → tag ++``` ++ ++Plural ++: (`string`) Returns the plural name of the taxonomy. ++ ++```go-html-template ++{{ .Data.Plural }} → tags ++``` ++ ++Term ++: (`string`) Returns the name of the term. ++ ++```go-html-template ++{{ .Data.Term }} → fiction ++``` ++ ++## Display metadata ++ ++Display metadata about each term by creating a corresponding branch bundle in the content directory. ++ ++For example, create an "authors" taxonomy: ++ ++{{< code-toggle file=hugo >}} ++[taxonomies] ++author = 'authors' ++{{< /code-toggle >}} ++ ++Then create content with one [branch bundle] for each term: ++ ++[branch bundle]: /getting-started/glossary/#branch-bundle ++ ++```text ++content/ ++└── authors/ ++ ├── jsmith/ ++ │ ├── _index.md ++ │ └── portrait.jpg ++ └── rjones/ ++ ├── _index.md ++ └── portrait.jpg ++``` ++ ++Then add front matter to each term page: ++ ++{{< code-toggle file=content/authors/jsmith/_index.md fm=true >}} ++title = "John Smith" ++affiliation = "University of Chicago" ++{{< /code-toggle >}} ++ ++Then create a term template specific to the "authors" taxonomy: ++ ++{{< code file=layouts/authors/term.html >}} ++{{ define "main" }} ++

{{ .Title }}

++

Affiliation: {{ .Params.affiliation }}

++ {{ with .Resources.Get "portrait.jpg" }} ++ {{ with .Fill "100x100" }} ++ portrait ++ {{ end }} ++ {{ end }} ++ {{ .Content }} ++ {{ range .Pages }} ++

{{ .LinkTitle }}

++ {{ end }} ++{{ end }} ++{{< /code >}} ++ ++In the example above we display the author with their affiliation and portrait, then a list of associated content. diff --cc docs/content/en/templates/types/index.md index 000000000,000000000..934105d88 new file mode 100644 --- /dev/null +++ b/docs/content/en/templates/types/index.md @@@ -1,0 -1,0 +1,284 @@@ ++--- ++title: Template types ++linkTitle: Template types ++description: Create templates of different types to render your content, resources, and data. ++categories: [templates] ++keywords: [] ++menu: ++ docs: ++ parent: templates ++ weight: 30 ++weight: 30 ++toc: true ++aliases: ['/templates/lists/'] ++--- ++ ++[![structural diagram of a website](site-hierarchy.svg)](site-hierarchy.svg) ++ ++## Structure ++ ++Create templates in the layouts directory in the root of your project. ++ ++Although your site may not require each of these templates, the example below is typical for a site of medium complexity. ++ ++```text ++layouts/ ++├── _default/ ++│ ├── _markup/ ++│ │ ├── render-image.html <-- render hook ++│ │ └── render-link.html <-- render hook ++│ ├── baseof.html ++│ ├── home.html ++│ ├── section.html ++│ ├── single.html ++│ ├── taxonomy.html ++│ └── term.html ++├── articles/ ++│ └── card.html <-- content view ++├── partials/ ++│ ├── footer.html ++│ └── header.html ++└── shortcodes/ ++ ├── audio.html ++ └── video.html ++``` ++ ++Hugo's [template lookup order] determines the template path, allowing you to create unique templates for any page. ++ ++[template lookup order]: /templates/lookup-order/ ++ ++{{% note %}} ++You must have thorough understanding of the [template lookup order] when creating templates. Template selection is based on template type, page kind, content type, section, language, and output format. ++ ++[template lookup order]: /templates/lookup-order/ ++{{% /note %}} ++ ++The purpose of each template type is described below. ++ ++## Base ++ ++Base templates reduce duplicate code by wrapping other templates within a shell. ++ ++For example, the base template below calls the [partial] function to include partial templates for the `head`, `header`, and `footer` elements of each page, and it uses the [block] function to include `home`, `single`, `section`, `taxonomy`, and `term` templates within the `main` element of each page. ++ ++[block]: /functions/go-template/block/ ++[partial]: /functions/partials/include/ ++ ++{{< code file=layouts/_default/baseof.html >}} ++ ++ ++ ++ {{ partial "head.html" . }} ++ ++ ++
++ {{ partial "header.html" . }} ++
++
++ {{ block "main" . }}{{ end }} ++
++
++ {{ partial "footer.html" . }} ++
++ ++ ++{{< /code >}} ++ ++Learn more about [base templates](/templates/base/). ++ ++## Home ++ ++A home template renders your site's home page. For a single page site this is the only required template. ++ ++For example, the home template below inherits the site's shell from the base template, and renders the home page content with a list of pages. ++ ++{{< code file=layouts/_default/home.html >}} ++{{ define "main" }} ++ {{ .Content }} ++ {{ range site.RegularPages }} ++

{{ .LinkTitle }}

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

{{ .Title }}

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

{{ .Title }}

++ {{ .Content }} ++ {{ range .Pages }} ++

{{ .LinkTitle }}

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

{{ .Title }}

++ {{ .Content }} ++ {{ range .Pages }} ++

{{ .LinkTitle }}

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

{{ .Title }}

++ {{ .Content }} ++ {{ range .Pages }} ++

{{ .LinkTitle }}

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

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

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

{{ .LinkTitle }}

++ {{ .Summary }} ++
++{{< /code >}} ++ ++Learn more about [content view templates](/templates/content-view/). ++ ++## Render hook ++ ++A render hook template overrides the conversion of Markdown to HTML. ++ ++For example, the render hook template below adds a `rel` attribute to external links. ++ ++{{< code file=layouts/_default/_markup/render-link.html >}} ++{{- $u := urls.Parse .Destination -}} ++ ++ {{- with .Text | safeHTML }}{{ . }}{{ end -}} ++ ++{{- /* chomp trailing newline */ -}} ++{{< /code >}} ++ ++Learn more about [render hook templates](/render-hooks/). ++ ++## Shortcode ++ ++A shortcode template is used to render a component of your site. Unlike partial templates, shortcode templates are called from content pages. ++ ++For example, the shortcode template below renders an audio element from a [global resource]. ++ ++[global resource]: /getting-started/glossary/#global-resource ++ ++{{< code file=layouts/shortcodes/audio.html >}} ++{{ with resources.Get (.Get "src") }} ++ ++{{ end }} ++{{< /code >}} ++ ++Call the shortcode from your content page: ++ ++{{< code file=content/example.md >}} ++{{}} ++{{< /code >}} ++ ++Learn more about [shortcode templates](/templates/shortcode/). ++ ++## Other ++ ++Use other specialized templates to create: ++ ++- [Sitemaps](/templates/sitemap) ++- [RSS feeds](/templates/rss/) ++- [404 error pages](/templates/404/) ++- [robots.txt files](/templates/robots/) diff --cc docs/content/en/templates/types/site-hierarchy.svg index 000000000,000000000..3c744871b new file mode 100644 --- /dev/null +++ b/docs/content/en/templates/types/site-hierarchy.svg @@@ -1,0 -1,0 +1,1 @@@ ++ diff --cc docs/content/en/troubleshooting/faq.md index f8106a7db,000000000..0fd67264c mode 100644,000000..100644 --- a/docs/content/en/troubleshooting/faq.md +++ b/docs/content/en/troubleshooting/faq.md @@@ -1,143 -1,0 +1,143 @@@ +--- +title: Frequently asked questions +linkTitle: FAQs +description: These questions are frequently asked by new users. +categories: [troubleshooting] +keywords: [faq] +menu: + docs: + parent: troubleshooting + weight: 70 +weight: 70 +# Use level 6 headings for each question. +--- + +Hugo’s [forum] is an active community of users and developers who answer questions, share knowledge, and provide examples. A quick search of over 20,000 topics will often answer your question. Please be sure to read about [requesting help] before asking your first question. + +These are just a few of the questions most frequently asked by new users. + +###### An error message indicates that a feature is not available. Why? + +Hugo is available in two editions: standard and extended. With the extended edition you can (a) encode to the WebP format when processing images, and (b) transpile Sass to CSS using the embedded LibSass transpiler. The extended edition is not required to use the Dart Sass transpiler. + +When you attempt to perform either of the operations above with the standard edition, Hugo throws this error: + +```go-html-template +Error: this feature is not available in your current Hugo version +``` + +To resolve, uninstall the standard edition, then install the extended edition. See the [installation] section for details. + +###### Why do I see "Page Not Found" when visiting the home page? + +In the content/_index.md file: + + - Is `draft` set to `true`? + - Is the `date` in the future? + - Is the `publishDate` in the future? + - Is the `expiryDate` in the past? + +If the answer to any of these questions is yes, either change the field values, or use one of these command line flags: `--buildDrafts`, `--buildFuture`, or `--buildExpired`. + +###### Why is a given page not published? + +In the content/section/page.md file, or in the content/section/page/index.md file: + + - Is `draft` set to `true`? + - Is the `date` in the future? + - Is the `publishDate` in the future? + - Is the `expiryDate` in the past? + +If the answer to any of these questions is yes, either change the field values, or use one of these command line flags: `--buildDrafts`, `--buildFuture`, or `--buildExpired`. + +###### Why can't I see any of a page's descendants? + +You may have an index.md file instead of an _index.md file. See [details](/content-management/page-bundles/). + +###### What is the difference between an index.md file and an _index.md file? + +A directory with an index.md file is a [leaf bundle]. A directory with an _index.md file is a [branch bundle]. See [details](/content-management/page-bundles/). + +[branch bundle]: /getting-started/glossary/#branch-bundle +[leaf bundle]: /getting-started/glossary/#leaf-bundle + +###### Why is my partial template not rendered as expected? {#foo} + +You may have neglected to pass the required [context] when calling the partial. For example: + +```go-html-template +{{/* incorrect */}} +{{ partial "_internal/pagination.html" }} + +{{/* correct */}} +{{ partial "_internal/pagination.html" . }} +``` + +###### In a template, what's the difference between `:=` and `=` when assigning values to variables? + +Use `:=` to initialize a variable, and use `=` to assign a value to a variable that has been previously initialized. See [details](https://pkg.go.dev/text/template#hdr-Variables). + +###### When I paginate a list page, why is the page collection not filtered as specified? + - You are probably invoking the [`Paginate`] or [`Paginator`] method more than once on the same page. See [details](/templates/pagination/#list-paginator-pages). ++You are probably invoking the [`Paginate`] or [`Paginator`] method more than once on the same page. See [details](/templates/pagination/). + +###### Why are there two ways to call a shortcode? + +Use the `{{%/* shortcode */%}}` notation if the shortcode template, or the content between the opening and closing shortcode tags, contains Markdown. Otherwise use the\ +`{{}}` notation. See [details](/content-management/shortcodes/). + +###### Can I use environment variables to control configuration? + +Yes. See [details](/getting-started/configuration/#configure-with-environment-variables). + +###### Why am I seeing inconsistent output from one build to the next? + +The most common causes are page collisions (publishing two pages to the same path) and the effects of concurrency. Use the `--printPathWarnings` command line flag to check for page collisions, and create a topic on the [forum] if you suspect concurrency problems. + +###### 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`. + +{{% note %}} +For other questions please visit the [forum]. A quick search of over 20,000 topics will often answer your question. Please be sure to read about [requesting help] before asking your first question. + +[forum]: https://discourse.gohugo.io +[requesting help]: https://discourse.gohugo.io/t/requesting-help/9132 +{{% /note %}} + +[`Paginate`]: /methods/page/paginate/ +[`Paginator`]: /methods/page/paginator/ +[context]: /getting-started/glossary/#context +[forum]: https://discourse.gohugo.io +[installation]: /installation/ +[requesting help]: https://discourse.gohugo.io/t/requesting-help/9132 diff --cc docs/go.mod index ca0acd79f,000000000..51d5f3a43 mode 100644,000000..100644 --- a/docs/go.mod +++ b/docs/go.mod @@@ -1,5 -1,0 +1,5 @@@ +module github.com/gohugoio/hugoDocs + +go 1.16 + - require github.com/gohugoio/gohugoioTheme v0.0.0-20240619093131-b595d5fb8c52 // indirect ++require github.com/gohugoio/gohugoioTheme v0.0.0-20240728210410-d42c342ce472 // indirect diff --cc docs/go.sum index a1664d320,000000000..633446af0 mode 100644,000000..100644 --- a/docs/go.sum +++ b/docs/go.sum @@@ -1,6 -1,0 +1,12 @@@ +github.com/gohugoio/gohugoioTheme v0.0.0-20240426212330-f38e99e0d88d h1:EaFz80Aqh3Ej20VmUSNe3K+F0NbT8UueXLP/VqkK9Dw= +github.com/gohugoio/gohugoioTheme v0.0.0-20240426212330-f38e99e0d88d/go.mod h1:GOYeAPQJ/ok8z7oz1cjfcSlsFpXrmx6VkzQ5RpnyhZM= +github.com/gohugoio/gohugoioTheme v0.0.0-20240508091825-b23e8e2d2419 h1:cQ/44eDHK0tVImTtSx/9sWWZv+RynH/oB4R7ASbQNAE= +github.com/gohugoio/gohugoioTheme v0.0.0-20240508091825-b23e8e2d2419/go.mod h1:GOYeAPQJ/ok8z7oz1cjfcSlsFpXrmx6VkzQ5RpnyhZM= +github.com/gohugoio/gohugoioTheme v0.0.0-20240619093131-b595d5fb8c52 h1:dPJxUU4SevIZ7OS1DIVOrJ7p8I/QM00pXGRfAtKgQmU= +github.com/gohugoio/gohugoioTheme v0.0.0-20240619093131-b595d5fb8c52/go.mod h1:GOYeAPQJ/ok8z7oz1cjfcSlsFpXrmx6VkzQ5RpnyhZM= ++github.com/gohugoio/gohugoioTheme v0.0.0-20240622143740-53a4bdb8c0fb h1:gOIE1eFXILxCio/QOm3oLYcYmsis2CD099dXbXpjprA= ++github.com/gohugoio/gohugoioTheme v0.0.0-20240622143740-53a4bdb8c0fb/go.mod h1:GOYeAPQJ/ok8z7oz1cjfcSlsFpXrmx6VkzQ5RpnyhZM= ++github.com/gohugoio/gohugoioTheme v0.0.0-20240623150114-cc7096eab3fd h1:I8X7c0oBRWXy83BL2ODSk7v0xPXDnp2hcFWpCcN+Kyc= ++github.com/gohugoio/gohugoioTheme v0.0.0-20240623150114-cc7096eab3fd/go.mod h1:GOYeAPQJ/ok8z7oz1cjfcSlsFpXrmx6VkzQ5RpnyhZM= ++github.com/gohugoio/gohugoioTheme v0.0.0-20240728210410-d42c342ce472 h1:AYZUibKKFRBp2VCQpDHW+JmQKvCvyhX7z7/SOLUSCcw= ++github.com/gohugoio/gohugoioTheme v0.0.0-20240728210410-d42c342ce472/go.mod h1:GOYeAPQJ/ok8z7oz1cjfcSlsFpXrmx6VkzQ5RpnyhZM= diff --cc docs/netlify.toml index 54f157413,000000000..f7f1a5f04 mode 100644,000000..100644 --- a/docs/netlify.toml +++ b/docs/netlify.toml @@@ -1,30 -1,0 +1,30 @@@ +[build] + publish = "public" + command = "hugo --gc --minify" + + [build.environment] - HUGO_VERSION = "0.127.0" ++ HUGO_VERSION = "0.131.0" + +[context.production.environment] + HUGO_ENV = "production" + HUGO_ENABLEGITINFO = "true" + +[context.split1] + command = "hugo --gc --minify --enableGitInfo" + + [context.split1.environment] + HUGO_ENV = "production" + +[context.deploy-preview] + command = "hugo --gc --minify --buildFuture -b $DEPLOY_PRIME_URL" + +[context.branch-deploy] + command = "hugo --gc --minify -b $DEPLOY_PRIME_URL" + +[context.next.environment] + HUGO_ENABLEGITINFO = "true" + +[[redirects]] + from = "/npmjs/*" + to = "/npmjs/" + status = 200