From: Bjørn Erik Pedersen Date: Fri, 27 Oct 2023 08:06:44 +0000 (+0200) Subject: Merge commit '3710a5ec7efe6baca6e452f43632c05d22bab3c4' X-Git-Url: http://git.maquefel.me/?a=commitdiff_plain;h=705e3cd5f;p=brevno-suite%2Fhugo Merge commit '3710a5ec7efe6baca6e452f43632c05d22bab3c4' --- 705e3cd5f558fb506f25c4255968bfdc907adb29 diff --cc docs/config/_default/params.toml index 7103394a6,000000000..3fddf9dbc mode 100644,000000..100644 --- a/docs/config/_default/params.toml +++ b/docs/config/_default/params.toml @@@ -1,21 -1,0 +1,24 @@@ + +description = "The world’s fastest framework for building websites" +## Setting this to true will add a "noindex" to *EVERY* page on the site.. +removefromexternalsearch = false +## Gh repo for site footer (include trailing slash) +ghrepo = "https://github.com/gohugoio/hugoDocs/" +## GH Repo for filing a new issue +github_repo = "https://github.com/gohugoio/hugo/issues/new" +### Edit content repo (set to automatically enter "edit" mode; this is good for "improve this page" links) +ghdocsrepo = "https://github.com/gohugoio/hugoDocs/tree/master/docs" +## Discuss Forum URL +forum = "https://discourse.gohugo.io/" +## Google Tag Manager +gtmid = "" + +# First one is picked as the Twitter card image if not set on page. +images = ["images/gohugoio-card.png"] + +flex_box_interior_classes = "flex-auto w-100 w-40-l mr3 mb3 bg-white ba b--moon-gray nested-copy-line-height" + +#sidebar_direction = "sidebar_left" ++ ++[social] ++twitter = "GoHugoIO" diff --cc docs/content/en/getting-started/glossary.md index c15af5170,000000000..759cb1cd1 mode 100644,000000..100644 --- a/docs/content/en/getting-started/glossary.md +++ b/docs/content/en/getting-started/glossary.md @@@ -1,270 -1,0 +1,274 @@@ +--- +title: Glossary of terms +description: Terms commonly used throughout the documentation. +keywords: [glossary] +menu: + docs: + parent: getting-started + weight: 60 +weight: 60 +type: glossary +--- + + + +### action + +See [template action](#template-action). + +### archetype + +A template for new content. See [details](/content-management/archetypes/). + +### argument + +A [scalar](#scalar), [array](#array), [slice](#slice), [map](#map), or [object](#object) passed to a [function](#function), [method](#method), or [shortcode](#shortcode). + +### array + +A numbered sequence of elements. Unlike Go's [slice](#slice) data type, an array has a fixed length. See the [Go documentation](https://go.dev/ref/spec#Array_types) for details. + +### bool + +See [boolean](#boolean). + +### boolean + +A data type with two possible values, either `true` or `false`. + +### branch bundle + +A [page bundle](#page-bundle) with an _index.md file and zero or more [resources](#resource). Analogous to a physical branch, a branch bundle may have descendants including regular pages, [leaf bundles](/getting-started/glossary/#leaf-bundle), and other branch bundles. See [details](/content-management/page-bundles/). + +### build + +To generate a static site that includes HTML files and assets such as images, CSS, and JavaScript. The build process includes rendering and resource transformations. + +### bundle + +See [page bundle](#page-bundle). + +### cache + +A software component that stores data so that future requests for the same data are faster. + +### collection + +Typically, a collection of pages, but may also refer to an [array](#array), [slice](#slice), or [map](#map). For example, the pages within a site's "articles" section are a page collection. + +### content format + +A markup language for creating content. Typically markdown, but may also be HTML, AsciiDoc, Org, Pandoc, or reStructuredText. See [details](/content-management/formats/). + +### content type + +A classification of content inferred from the top-level directory name or the `type` set in [front matter](#front-matter). Pages in the root of the content directory, including the home page, are of type "page". Accessed via `.Page.Type` in [templates](#template). See [details](/content-management/types/). + +### content view + +A template called with the `.Page.Render` method. See [details](/templates/views/). + +### context + +Represented by a period "." within a [template action](#template-action), context is the current location in a data structure. For example, while iterating over a [collection](#collection) of pages, the context within each iteration is the page's data structure. The context received by each template depends on template type and/or how it was called. See [details](/templates/introduction/#the-dot). + +### flag + +An option passed to a command-line program, beginning with one or two hyphens. See [details](/commands/hugo/). + +### float + +See [floating point](#floating-point). + +### floating point + +A numeric data type with a fractional component. For example, `3.14159`. + +### function + +Used within a [template action](#template-action), a function takes one or more [arguments](#argument) and returns a value. Unlike [methods](#method), functions are not associated with an [object](#object). See [details](/functions/). + +### front matter + +Metadata at the beginning of each content page, separated from the content by format-specific delimiters. See [details](/content-management/front-matter/). + ++### identifier ++ ++A string that represents a variable, method, object, or field. It must conform to Go's [language specification](https://go.dev/ref/spec#Identifiers), beginning with a letter or underscore, followed by zero or more letters, digits, or underscores. ++ +### int + +See [integer](#integer). + +### integer + +A numeric data type without a fractional component. For example, `42`. + +### internationalization + +Software design and development efforts that enable [localization](#localization). See the [W3C definition](https://www.w3.org/International/questions/qa-i18n). Abbreviated i18n. + +### kind + +See [page kind](#page-kind). + +### layout + +See [template](#template). + +### leaf bundle + +A [page bundle](#page-bundle) with an index.md file and zero or more [resources](#resource). Analogous to a physical leaf, a leaf bundle is at the end of a branch. Hugo ignores content (but not resources) beneath the leaf bundle. See [details](/content-management/page-bundles/). + +### list page + +Any [page kind](#page-kind) that receives a page [collection](#collection) in [context](#context). This includes the home page, [section pages](#section-page), [taxonomy pages](#taxonomy-page), and [term pages](#term-page). + +### localization + +Adaptation of a site to meet language and regional requirements. This includes translations, language-specific media, date and currency formats, etc. See [details](/content-management/multilingual/) and the [W3C definition](https://www.w3.org/International/questions/qa-i18n). Abbreviated l10n. + +### map + +An unordered group of elements, each indexed by a unique key. See the [Go documentation](https://go.dev/ref/spec#Map_types) for details. + +### method + +Used within a [template action](#template-action) and associated with an [object](#object), a method takes zero or more [arguments](#argument) and either returns a value or performs an action. For example, `.IsHome` is a method on the `.Page` object which returns `true` if the current page is the home page. See also [function](#function). + +### module + +Like a [theme](#theme), a module is a packaged combination of [archetypes](#archetype), assets, content, data, [templates](#template), translation tables, static files, or configuration settings. A module may serve as the basis for a new site, or to augment an existing site. See [details](/hugo-modules/). + +### object + +A data structure with or without associated [methods](#method). + +### page bundle + +A directory that encapsulates both content and associated [resources](#resource). There are two types of page bundles: [leaf bundles](/getting-started/glossary/#leaf-bundle) and [branch bundles](/getting-started/glossary/#branch-bundle). See [details](/content-management/page-bundles/). + +### page kind + +A classification of rendered pages, one of "home", "page", "section", "taxonomy", or "term". Accessed via `.Page.Kind` in [templates](#template). See [details](/templates/section-templates/#page-kinds). + +### pager + +Created during [pagination](#pagination), a pager contains a subset of a section list, and navigation links to other pagers. + +### paginate + +To split a [section](#section) list into two or more [pagers](#pager) See [details](/templates/pagination/). + +### pagination + +The process of [paginating](#paginate) a [section](#section) list. + +### parameter + +Typically, a user-defined key/value pair at the site or page level, but may also refer to a configuration setting or an [argument](#argument). + +### partial + +A [template](#template) called from any other template including [shortcodes](#shortcode), [render hooks](#render-hook), and other partials. A partial either renders something or returns something. A partial can also call itself, for example, to [walk](#walk) a data structure. + +### permalink + +The absolute URL of a rendered page, including scheme and host. + +### pipe + +See [pipeline](#pipeline). + +### pipeline + +Within a [template action](#template-action), a pipeline is a possibly chained sequence of values, [function](#function) calls, or [method](#method) calls. Functions and methods in the pipeline may take multiple [arguments](#argument). + +A pipeline may be *chained* by separating a sequence of commands with pipeline characters "|". In a chained pipeline, the result of each command is passed as the last argument to the following command. The output of the final command in the pipeline is the value of the pipeline. See the [Go documentation](https://pkg.go.dev/text/template#hdr-Pipelines) for details. + +### publish + +See [build](#build). + +### regular page + +Content with the "page" [page kind](#page-kind). See also [section page](#section-page). + +### render hook + +A [template](#template) that overrides standard markdown rendering. See [details](/templates/render-hooks/). + +### resource + +Any file consumed by the build process to augment or generate content, structure, behavior, or presentation. For example: images, videos, content snippets, CSS, Sass, JavaScript, and data. + +Hugo supports three types of resources: page resources (located in a [page bundle](/getting-started/glossary/#page-bundle)), global resources (located in the assets directory), and remote resources (typically accessed via HTTPS). + +### scalar + +A single value, one of [string](#string), [integer](#integer), [floating point](#floating-point), or [boolean](#boolean). + +### section + +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](#collection) in [context](#context). See [details](/content-management/sections/). + +### section page + +Content with the "section" [page kind](#page-kind). Typically a listing of [regular pages](#regular-page) and/or [section pages](#section-page) within the current [section](#section). See also [regular page](#regular-page). + +### shortcode + +A [template](#template) called from within markdown, taking zero or more [arguments](#argument). See [details](/content-management/shortcodes/). + +### slice + +A numbered sequence of elements. Unlike Go's [array](#array) data type, slices are dynamically sized. See the [Go documentation](https://go.dev/ref/spec#Slice_types) for details. + +### string + +A sequence of bytes. For example, `"What is 6 times 7?"` . + +### taxonomy + +A group of related [terms](#term) used to classify content. For example, a "colors" taxonomy might include the terms "red", "green", and "blue". See [details](/content-management/taxonomies/). + +### taxonomy page + +Content with the "taxonomy" [page kind](#page-kind). Typically a listing of [terms](#term) within a given [taxonomy](#taxonomy). + +### template + +A file with [template actions](#template-action), located within the layouts directory of a project, theme, or module. See [details](/templates/). + +### template action + +A data evaluation or control structure within a [template](#template), delimited by "{{" and "}}". See the [Go documentation](https://pkg.go.dev/text/template#hdr-Actions) for details. + +### term + +A member of a [taxonomy](#taxonomy), used to classify content. See [details](/content-management/taxonomies/). + +### term page + +Content with the "term" [page kind](#page-kind). Typically a listing of [regular pages](#regular-page) and [section pages](#section-page) with a given [term](#term). + +### theme + +A packaged combination of [archetypes](#archetype), assets, content, data, [templates](#template), translation tables, static files, or configuration settings. A theme may serve as the basis for a new site, or to augment an existing site. See also [module](#module). + +### token + +An identifier within a format string, beginning with a colon and replaced with a value when rendered. For example, use tokens in format strings for both [permalinks](/content-management/urls/#permalinks) and [dates](/functions/time/format/#localization). + + +### type + +See [content type](#content-type). + +### variable + +A variable initialized within a [template action](#template-action). + +### walk + +To recursively traverse a nested data structure. For example, rendering a multilevel menu. diff --cc docs/content/en/templates/internal.md index 9118184e8,000000000..a73ecde4c mode 100644,000000..100644 --- a/docs/content/en/templates/internal.md +++ b/docs/content/en/templates/internal.md @@@ -1,226 -1,0 +1,226 @@@ +--- +title: Internal templates +description: Hugo ships with a group of boilerplate templates that cover the most common use cases for static websites. +categories: [templates] +keywords: [internal, analytics,] +menu: + docs: + parent: templates + weight: 190 +weight: 190 +toc: true +--- + + +{{% note %}} +While the following internal templates are called similar to partials, they do *not* observe the partial template lookup order. +{{% /note %}} + +## Google Analytics + +Hugo ships with an internal template supporting [Google Analytics 4][GA4] (GA4). + +**Note:** Universal Analytics are [deprecated]. + +[GA4]: https://support.google.com/analytics/answer/10089681 +[deprecated]: https://support.google.com/analytics/answer/11583528 + +### Configure Google Analytics + +Provide your tracking ID in your configuration file: + +**Google Analytics 4 (gtag.js)** +{{< code-toggle file="hugo" >}} +[services.googleAnalytics] +ID = "G-MEASUREMENT_ID" +{{}} + +### Use the Google Analytics template + +Include the Google Analytics internal template in your templates where you want the code to appear: + +```go-html-template +{{ template "_internal/google_analytics.html" . }} +``` + +To create your own template, access the configured ID with `{{ site.Config.Services.GoogleAnalytics.ID }}`. + +## Disqus + +Hugo also ships with an internal template for [Disqus comments][disqus], a popular commenting system for both static and dynamic websites. To effectively use Disqus, secure a Disqus "shortname" by [signing up for the free service][disqussignup]. + +### Configure Disqus + +To use Hugo's Disqus template, first set up a single configuration value: + +{{< code-toggle file="hugo" >}} +[services.disqus] +shortname = 'your-disqus-shortname' +{{}} + +Hugo's Disqus template accesses this value with: + +```go-html-template +{{ .Site.Config.Services.Disqus.Shortname }} +``` + +You can also set the following in the front matter for a given piece of content: + +* `disqus_identifier` +* `disqus_title` +* `disqus_url` + +### Use the Disqus template + +To add Disqus, include the following line in the templates where you want your comments to appear: + +```go-html-template +{{ template "_internal/disqus.html" . }} +``` + +### Conditional loading of Disqus comments + +Users have noticed that enabling Disqus comments when running the Hugo web server on `localhost` (i.e. via `hugo server`) causes the creation of unwanted discussions on the associated Disqus account. + +You can create the following `layouts/partials/disqus.html`: + +{{< code file="layouts/partials/disqus.html" >}} +
+ + +comments powered by Disqus +{{< /code >}} + +The `if` statement skips the initialization of the Disqus comment injection when you are running on `localhost`. + +You can then render your custom Disqus partial template as follows: + +```go-html-template +{{ partial "disqus.html" . }} +``` + +## Open Graph + +An internal template for the [Open Graph protocol](https://ogp.me/), metadata that enables a page to become a rich object in a social graph. +This format is used for Facebook and some other sites. + +### Configure Open Graph + +Hugo's Open Graph template is configured using a mix of configuration variables and [front-matter](/content-management/front-matter/) on individual pages. + +{{< code-toggle file="hugo" >}} +[params] + title = "My cool site" + images = ["site-feature-image.jpg"] + description = "Text about my cool site" +[taxonomies] + series = "series" +{{}} + +{{< code-toggle file="content/blog/my-post" >}} +title = "Post title" +description = "Text about this post" +date = "2006-01-02" +images = ["post-cover.png"] +audio = [] +videos = [] +series = [] +tags = [] +{{}} + +Hugo uses the page title and description for the title and description metadata. +The first 6 URLs from the `images` array are used for image metadata. +If [page bundles](/content-management/page-bundles/) are used and the `images` array is empty or undefined, images with file names matching `*feature*` or `*cover*,*thumbnail*` are used for image metadata. + +Various optional metadata can also be set: + +- Date, published date, and last modified data are used to set the published time metadata if specified. +- `audio` and `videos` are URL arrays like `images` for the audio and video metadata tags, respectively. +- The first 6 `tags` on the page are used for the tags metadata. +- The `series` taxonomy is used to specify related "see also" pages by placing them in the same series. + +If using YouTube this will produce a og:video tag like ``. Use the `https://youtu.be/` format with YouTube videos (example: `https://youtu.be/qtIqKaDlqXo`). + +### Use the Open Graph template + +To add Open Graph metadata, include the following line between the `` tags in your templates: + +```go-html-template +{{ template "_internal/opengraph.html" . }} +``` + +## Twitter Cards + - An internal template for [Twitter Cards](https://developer.twitter.com/en/docs/tweets/optimize-with-cards/overview/abouts-cards), ++An internal template for [Twitter Cards](https://developer.twitter.com/en/docs/twitter-for-websites/cards/overview/abouts-cards), +metadata used to attach rich media to Tweets linking to your site. + +### Configure Twitter Cards + +Hugo's Twitter Card template is configured using a mix of configuration variables and [front-matter](/content-management/front-matter/) on individual pages. + +{{< code-toggle file="hugo" >}} +[params] + images = ["site-feature-image.jpg"] + description = "Text about my cool site" +{{}} + +{{< code-toggle file="content/blog/my-post" >}} +title = "Post title" +description = "Text about this post" +images = ["post-cover.png"] +{{}} + +If `images` aren't specified in the page front-matter, then hugo searches for [image page resources](/content-management/image-processing/) with `feature`, `cover`, or `thumbnail` in their name. +If no image resources with those names are found, the images defined in the [site config](/getting-started/configuration/) are used instead. +If no images are found at all, then an image-less Twitter `summary` card is used instead of `summary_large_image`. + +Hugo uses the page title and description for the card's title and description fields. The page summary is used if no description is given. + +Set the value of `twitter:site` in your site configuration: + +{{< code-toggle file="hugo" copy=false >}} +[params.social] +twitter = "GoHugoIO" +{{}} + +NOTE: The `@` will be added for you + +```html + +``` + +### Use the Twitter Cards template + +To add Twitter card metadata, include the following line immediately after the `` element in your templates: + +```go-html-template +{{ template "_internal/twitter_cards.html" . }} +``` + +## The internal templates + +The code for these templates is located [here](https://github.com/gohugoio/hugo/tree/master/tpl/tplimpl/embedded/templates). + +* `_internal/disqus.html` +* `_internal/google_analytics.html` +* `_internal/opengraph.html` +* `_internal/pagination.html` +* `_internal/schema.html` +* `_internal/twitter_cards.html` + +[disqus]: https://disqus.com +[disqussignup]: https://disqus.com/profile/signup/ diff --cc docs/content/en/templates/introduction.md index 93666de28,000000000..2eb436f82 mode 100644,000000..100644 --- a/docs/content/en/templates/introduction.md +++ b/docs/content/en/templates/introduction.md @@@ -1,672 -1,0 +1,675 @@@ +--- +title: Templating +linkTitle: Templating +description: Hugo uses Go's `html/template` and `text/template` libraries as the basis for the templating. +categories: [fundamentals,templates] +keywords: [go] +menu: + docs: + parent: templates + weight: 20 +weight: 20 +aliases: [/layouts/introduction/,/layout/introduction/, /templates/go-templates/] +toc: true +--- + +{{% note %}} +The following is only a primer on Go Templates. For an in-depth look into Go Templates, check the official [Go docs](https://golang.org/pkg/text/template/). +{{% /note %}} + +Go Templates provide an extremely simple template language that adheres to the belief that only the most basic of logic belongs in the template or view layer. + +## Basic syntax + +Go Templates are HTML files with the addition of [variables][variables] and [functions][functions]. Go Template variables and functions are accessible within `{{ }}`. + +### Access a predefined variable + +A _predefined variable_ could be a variable already existing in the +current scope (like the `.Title` example in the [Variables](#variables) section below) or a custom variable (like the +`$address` example in that same section). + + +```go-html-template +{{ .Title }} +{{ $address }} +``` + +Parameters for functions are separated using spaces. The general syntax is: + +```go-html-template +{{ FUNCTION ARG1 ARG2 .. }} +``` + +The following example calls the `add` function with inputs of `1` and `2`: + +```go-html-template +{{ add 1 2 }} +``` + +#### Methods and fields are accessed via dot notation + +Accessing the Page Parameter `bar` defined in a piece of content's [front matter]. + +```go-html-template +{{ .Params.bar }} +``` + +#### Parentheses can be used to group items together + +```go-html-template +{{ if or (isset .Params "alt") (isset .Params "caption") }} Caption {{ end }} +``` + +#### A single statement can be split over multiple lines + +```go-html-template +{{ if or + (isset .Params "alt") + (isset .Params "caption") +}} +``` + +#### Raw string literals can include newlines + +```go-html-template +{{ $msg := `Line one. +Line two.` }} +``` + +## Variables + +Each Go Template gets a data object. In Hugo, each template is passed +a `Page`. In the below example, `.Title` is one of the elements +accessible in that [`Page` variable][pagevars]. + +With the `Page` being the default scope of a template, the `Title` +element in current scope (`.` -- "the **dot**") is accessible simply +by the dot-prefix (`.Title`): + +```go-html-template +{{ .Title }} +``` + +Values can also be stored in custom variables and referenced later: + +{{% note %}} +The custom variables need to be prefixed with `$`. +{{% /note %}} + +```go-html-template +{{ $address := "123 Main St." }} +{{ $address }} +``` + +Variables can be re-defined using the `=` operator. The example below +prints "Var is Hugo Home" on the home page, and "Var is Hugo Page" on +all other pages: + +```go-html-template +{{ $var := "Hugo Page" }} +{{ if .IsHome }} + {{ $var = "Hugo Home" }} +{{ end }} +Var is {{ $var }} +``` + ++Variable names must conform to Go's naming rules for [identifiers][identifier]. ++ +## Functions + +Go Templates only ship with a few basic functions but also provide a mechanism for applications to extend the original set. + +[Hugo template functions][functions] provide additional functionality specific to building websites. Functions are called by using their name followed by the required parameters separated by spaces. Template functions cannot be added without recompiling Hugo. + +### Example 1: adding numbers + +```go-html-template +{{ add 1 2 }} + +``` + +### Example 2: comparing numbers + +```go-html-template +{{ lt 1 2 }} + +``` + +Note that both examples make use of Go Template's [math][math] functions. + +{{% note %}} +There are more boolean operators than those listed in the Hugo docs in the [Go Template documentation](https://golang.org/pkg/text/template/#hdr-Functions). +{{% /note %}} + +## Includes + +When including another template, you will need to pass it the data that it would +need to access. + +{{% note %}} +To pass along the current context, please remember to include a trailing **dot**. +{{% /note %}} + +The templates location will always be starting at the `layouts/` directory +within Hugo. + +### Partial + +The [`partial`][partials] function is used to include _partial_ templates using +the syntax `{{ partial "/." . }}`. + +Example of including a `layouts/partials/header.html` partial: + +```go-html-template +{{ partial "header.html" . }} +``` + +### Template + +The `template` function was used to include _partial_ templates +in much older Hugo versions. Now it's useful only for calling +[_internal_ templates][internal templates]. The syntax is `{{ template +"_internal/