From: Bjørn Erik Pedersen Date: Sat, 1 May 2021 09:45:45 +0000 (+0200) Subject: Merge commit 'c239c643fee10bfa217cb108755b798f8f5f3b10' X-Git-Tag: v0.83.0~8 X-Git-Url: http://git.maquefel.me/?a=commitdiff_plain;h=d7b22aee463d4178c1fb4594054c9b1493b9c571;p=brevno-suite%2Fhugo Merge commit 'c239c643fee10bfa217cb108755b798f8f5f3b10' --- d7b22aee463d4178c1fb4594054c9b1493b9c571 diff --cc docs/_vendor/github.com/gohugoio/gohugoioTheme/layouts/partials/site-search.html index d8c4b97b,00000000..b6c521dc mode 100644,000000..100644 --- a/docs/_vendor/github.com/gohugoio/gohugoioTheme/layouts/partials/site-search.html +++ b/docs/_vendor/github.com/gohugoio/gohugoioTheme/layouts/partials/site-search.html @@@ -1,6 -1,0 +1,6 @@@ + ++ diff --cc docs/content/en/about/benefits.md index 020e5898,00000000..d5c13a9c mode 100644,000000..100644 --- a/docs/content/en/about/benefits.md +++ b/docs/content/en/about/benefits.md @@@ -1,43 -1,0 +1,43 @@@ +--- +title: The Benefits of Static Site Generators +linktitle: The Benefits of Static +description: Improved performance, security and ease of use are just a few of the reasons static site generators are so appealing. +date: 2017-02-01 +publishdate: 2017-02-01 +lastmod: 2017-02-01 +keywords: [ssg,static,performance,security] +menu: + docs: + parent: "about" + weight: 30 +weight: 30 +sections_weight: 30 +draft: false +aliases: [] +toc: false +--- + +The purpose of website generators is to render content into HTML files. Most are "dynamic site generators." That means the HTTP server---i.e., the program that sends files to the browser to be viewed---runs the generator to create a new HTML file every time an end user requests a page. + +Over time, dynamic site generators were programmed to cache their HTML files to prevent unnecessary delays in delivering pages to end users. A cached page is a static version of a web page. + +Hugo takes caching a step further and all HTML files are rendered on your computer. You can review the files locally before copying them to the computer hosting the HTTP server. Since the HTML files aren't generated dynamically, we say that Hugo is a *static site generator*. + +This has many benefits. The most noticeable is performance. HTTP servers are *very* good at sending files---so good, in fact, that you can effectively serve the same number of pages with a fraction of the memory and CPU needed for a dynamic site. + +## More on Static Site Generators + +* ["An Introduction to Static Site Generators", David Walsh][] +* ["Hugo vs. WordPress page load speed comparison: Hugo leaves WordPress in its dust", GettingThingsTech][hugovwordpress] +* ["Static Site Generators", O'Reilly][] +* [StaticGen: Top Open-Source Static Site Generators (GitHub Stars)][] +* ["Top 10 Static Website Generators", Netlify blog][] +* ["The Resurgence of Static", dotCMS][dotcms] + + +["An Introduction to Static Site Generators", David Walsh]: https://davidwalsh.name/introduction-static-site-generators - ["Static Site Generators", O'Reilly]: https://www.oreilly.com/web-platform/free/files/static-site-generators.pdf ++["Static Site Generators", O'Reilly]: https://github.com/gohugoio/hugoDocs/files/1242701/static-site-generators.pdf +["Top 10 Static Website Generators", Netlify blog]: https://www.netlify.com/blog/2016/05/02/top-ten-static-website-generators/ +[hugovwordpress]: https://gettingthingstech.com/hugo-vs.-wordpress-page-load-speed-comparison-hugo-leaves-wordpress-in-its-dust/ +[StaticGen: Top Open-Source Static Site Generators (GitHub Stars)]: https://www.staticgen.com/ +[dotcms]: https://dotcms.com/blog/post/the-resurgence-of-static diff --cc docs/content/en/content-management/related.md index ec3c3dd6,00000000..c0728fe9 mode 100644,000000..100644 --- a/docs/content/en/content-management/related.md +++ b/docs/content/en/content-management/related.md @@@ -1,137 -1,0 +1,137 @@@ +--- +title: Related Content +description: List related content in "See Also" sections. +date: 2017-09-05 +categories: [content management] +keywords: [content] +menu: + docs: + parent: "content-management" + weight: 40 +weight: 30 +draft: false +aliases: [/content/related/,/related/] +toc: true +--- + + +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: + +{{< code file="layouts/partials/related.html" >}} +{{ $related := .Site.RegularPages.Related . | first 5 }} +{{ with $related }} +

See Also

+ +{{ end }} +{{< /code >}} + +### Methods + +Here is the list of "Related" methods available on a page collection such `.RegularPages`. + +#### .Related PAGE +Returns a collection of pages related the given one. + +``` +{{ $related := .Site.RegularPages.Related . }} +``` + +#### .RelatedIndices PAGE INDICE1 [INDICE2 ...] +Returns a collection of pages related to a given one restricted to a list of indices. + +``` +{{ $related := .Site.RegularPages.RelatedIndices . "tags" "date" }} +``` + +#### .RelatedTo KEYVALS [KEYVALS2 ...] +Returns a collection of pages related together by a set of indices and their match. + +In order to build those set and pass them as argument, one must use the `keyVals` function where the first argument would be the `indice` and the consecutive ones its potential `matches`. + +``` +{{ $related := .Site.RegularPages.RelatedTo ( keyVals "tags" "hugo" "rocks") ( keyVals "date" .Date ) }} +``` + +{{% note %}} +Read [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 %}} + +## 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 file="config" >}} +related: + threshold: 80 + includeNewer: false + toLower: false + indices: + - name: keywords + weight: 100 + - name: date + weight: 10 +{{< /code-toggle >}} + - Note that if you have configured `tags` as a taxonomy, `tags` will also be added to the default configuration abve with the weight of `80`. ++Note that if you have configured `tags` as a taxonomy, `tags` will also be added to the default configuration above with the weight of `80`. + +Custom configuration should be set using the same syntax. + +{{% note %}} +If you add a `related` config 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 Config Options + +threshold +: A value between 0-100. Lower value will give more, but maybe not so relevant, matches. + +includeNewer +: 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 +: 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. + +### Config Options per Index + +name +: The index name. This value maps directly to a page param. Hugo supports string values (`author` in the example) and lists (`tags`, `keywords` etc.) and time and date objects. + +weight +: 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. + +pattern +: 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 +: 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 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/getting-started/configuration-markup.md index 14a23b73,00000000..e19bbe47 mode 100644,000000..100644 --- a/docs/content/en/getting-started/configuration-markup.md +++ b/docs/content/en/getting-started/configuration-markup.md @@@ -1,237 -1,0 +1,237 @@@ +--- +title: Configure Markup +description: How to handle Markdown and other markup related configuration. +date: 2019-11-15 +categories: [getting started,fundamentals] +keywords: [configuration,highlighting] +weight: 65 +sections_weight: 65 +slug: configuration-markup +toc: true +--- + +## Configure Markup + +{{< new-in "0.60.0" >}} + +See [Goldmark](#goldmark) for settings related to the default Markdown handler in Hugo. + +Below are all markup related configuration in Hugo with their default settings: + +{{< code-toggle config="markup" />}} + +**See each section below for details.** + +### Goldmark + +[Goldmark](https://github.com/yuin/goldmark/) is from Hugo 0.60 the default library used for Markdown. It's fast, it's [CommonMark](https://spec.commonmark.org/0.29/) compliant and it's very flexible. Note that the feature set of Goldmark vs Blackfriday isn't the same; you gain a lot but also lose some, but we will work to bridge any gap in the upcoming Hugo versions. + +This is the default configuration: + +{{< code-toggle config="markup.goldmark" />}} + +For details on the extensions, refer to [this section](https://github.com/yuin/goldmark/#built-in-extensions) of the Goldmark documentation + +Some settings explained: + +unsafe +: By default, Goldmark does not render raw HTMLs and potentially dangerous links. If you have lots of inline HTML and/or JavaScript, you may need to turn this on. + +typographer +: This extension substitutes punctuations with typographic entities like [smartypants](https://daringfireball.net/projects/smartypants/). + +attribute +: Enable custom attribute support for titles and blocks by adding attribute lists inside single curly brackets (`{.myclass class="class1 class2" }`) and placing it _after the Markdown element it decorates_, on the same line for titles and on a new line directly below for blocks. + - {{< new-in "0.81" >}} In Hugo 0.81.0 we added support for adding attributes (e.g. CSS classes) to Markdown blocks, e.g. tables, lists, paragraphs etc. ++{{< new-in "0.81.0" >}} In Hugo 0.81.0 we added support for adding attributes (e.g. CSS classes) to Markdown blocks, e.g. tables, lists, paragraphs etc. + +A blockquote with a CSS class: + +```md +> foo +> bar +{.myclass} +``` + +There are some current limitations: For tables you can currently only apply it to the full table, and for lists the `ul`/`ol`-nodes only, e.g.: + +```md +* Fruit + * Apple + * Orange + * Banana + {.fruits} +* Dairy + * Milk + * Cheese + {.dairies} +{.list} +``` + +Note that attributes in [code fences](/content-management/syntax-highlighting/#highlighting-in-code-fences) must come after the opening tag, with any other highlighting processing instruction, e.g.: + +```` +```go {.myclass linenos=table,hl_lines=[8,"15-17"],linenostart=199} +// ... code +``` +```` + +autoHeadingIDType ("github") {{< new-in "0.62.2" >}} +: The strategy used for creating auto IDs (anchor names). Available types are `github`, `github-ascii` and `blackfriday`. `github` produces GitHub-compatible IDs, `github-ascii` will drop any non-Ascii characters after accent normalization, and `blackfriday` will make the IDs work as with [Blackfriday](#blackfriday), the default Markdown engine before Hugo 0.60. Note that if Goldmark is your default Markdown engine, this is also the strategy used in the [anchorize](/functions/anchorize/) template func. + +### Blackfriday + + +[Blackfriday](https://github.com/russross/blackfriday) was Hugo's default Markdown rendering engine, now replaced with Goldmark. But you can still use it: Just set `defaultMarkdownHandler` to `blackfriday` in your top level `markup` config. + +This is the default config: + +{{< code-toggle config="markup.blackFriday" />}} + +### Highlight + +This is the default `highlight` configuration. Note that some of these settings can be set per code block, see [Syntax Highlighting](/content-management/syntax-highlighting/). + +{{< code-toggle config="markup.highlight" />}} + +For `style`, see these galleries: + +* [Short snippets](https://xyproto.github.io/splash/docs/all.html) +* [Long snippets](https://xyproto.github.io/splash/docs/longer/all.html) + +For CSS, see [Generate Syntax Highlighter CSS](/content-management/syntax-highlighting/#generate-syntax-highlighter-css). + +### Table Of Contents + +{{< code-toggle config="markup.tableOfContents" />}} + +These settings only works for the Goldmark renderer: + +startLevel +: The heading level, values starting at 1 (`h1`), to start render the table of contents. + +endLevel +: The heading level, inclusive, to stop render the table of contents. + +ordered +: Whether or not to generate an ordered list instead of an unordered list. + + +## Markdown Render Hooks + +{{< new-in "0.62.0" >}} + +Note that this is only supported with the [Goldmark](#goldmark) renderer. + +Render Hooks allow custom templates to override markdown rendering functionality. You can do this by creating templates with base names `render-{feature}` in `layouts/_default/_markup`. + +You can also create type/section specific hooks in `layouts/[type/section]/_markup`, e.g.: `layouts/blog/_markup`.{{< new-in "0.71.0" >}} + +The features currently supported are: + +* `image` +* `link` +* `heading` {{< new-in "0.71.0" >}} + +You can define [Output-Format-](/templates/output-formats) and [language-](/content-management/multilingual/)specific templates if needed. Your `layouts` folder may look like this: + +```bash +layouts +└── _default + └── _markup + ├── render-image.html + ├── render-image.rss.xml + └── render-link.html +``` + +Some use cases for the above: + +* Resolve link references using `.GetPage`. This would make links portable as you could translate `./my-post.md` (and similar constructs that would work on GitHub) into `/blog/2019/01/01/my-post/` etc. +* Add `target=_blank` to external links. +* Resolve and [process](/content-management/image-processing/) images. +* Add [header links](https://remysharp.com/2014/08/08/automatic-permalinks-for-blog-posts). + +### Render Hook Templates + +The `render-link` and `render-image` templates will receive this context: + +Page +: The [Page](/variables/page/) being rendered. + +Destination +: The URL. + +Title +: The title attribute. + +Text +: The rendered (HTML) link text. + +PlainText +: The plain variant of the above. + +The `render-heading` template will receive this context: + +Page +: The [Page](/variables/page/) being rendered. + +Level +: The header level (1--6) + +Anchor +: An auto-generated html id unique to the header within the page + +Text +: The rendered (HTML) text. + +PlainText +: The plain variant of the above. + +Attributes (map) {{< new-in "0.82.0" >}} +: A map of attributes (e.g. `id`, `class`) + +#### Link with title Markdown example: + +```md +[Text](https://www.gohugo.io "Title") +``` + +Here is a code example for how the render-link.html template could look: + +{{< code file="layouts/_default/_markup/render-link.html" >}} +{{ .Text | safeHTML }} +{{< /code >}} + +#### Image Markdown example: + +```md +![Text](https://d33wubrfki0l68.cloudfront.net/c38c7334cc3f23585738e40334284fddcaf03d5e/2e17c/images/hugo-logo-wide.svg "Title") +``` + +Here is a code example for how the render-image.html template could look: + +{{< code file="layouts/_default/_markup/render-image.html" >}} +

+ {{ .Text }} +

+{{< /code >}} + +#### Heading link example + +Given this template file + +{{< code file="layouts/_default/_markup/render-heading.html" >}} +{{ .Text | safeHTML }} ¶ +{{< /code >}} + +And this markdown + +```md +### Section A +``` + +The rendered html will be + +```html +

Section A ¶

+``` diff --cc docs/content/en/hosting-and-deployment/hosting-on-netlify.md index 74c54b04,00000000..9dfc010a mode 100644,000000..100644 --- a/docs/content/en/hosting-and-deployment/hosting-on-netlify.md +++ b/docs/content/en/hosting-and-deployment/hosting-on-netlify.md @@@ -1,159 -1,0 +1,159 @@@ +--- +title: Host on Netlify +linktitle: Host on Netlify +description: Netlify can host your Hugo site with CDN, continuous deployment, 1-click HTTPS, an admin GUI, and its own CLI. +date: 2017-02-01 +publishdate: 2017-02-01 +lastmod: 2017-03-11 +categories: [hosting and deployment] +keywords: [netlify,hosting,deployment] +authors: [Ryan Watters, Seth MacLeod] +menu: + docs: + parent: "hosting-and-deployment" + weight: 10 +weight: 10 +sections_weight: 10 +draft: false +aliases: [] +toc: true +--- + +[Netlify][netlify] provides continuous deployment services, global CDN, ultra-fast DNS, atomic deploys, instant cache invalidation, one-click SSL, a browser-based interface, a CLI, and many other features for managing your Hugo website. + +## Assumptions + +* You have an account with GitHub, GitLab, or Bitbucket. +* You have completed the [Quick Start][] or have a Hugo website you are ready to deploy and share with the world. +* You do not already have a Netlify account. + +## Create a Netlify account + +Go to [app.netlify.com][] and select your preferred signup method. This will likely be a hosted Git provider, although you also have the option to sign up with an email address. + +The following examples use GitHub, but other git providers will follow a similar process. + +![Screenshot of the homepage for app.netlify.com, containing links to the most popular hosted git solutions.](/images/hosting-and-deployment/hosting-on-netlify/netlify-signup.jpg) + +Selecting GitHub will bring up an authorization modal for authentication. Select "Authorize application." + +![Screenshot of the authorization popup for Netlify and GitHub.](/images/hosting-and-deployment/hosting-on-netlify/netlify-first-authorize.jpg) + +## Create a New Site with Continuous Deployment + +You're now already a Netlify member and should be brought to your new dashboard. Select "New site from git." + +![Screenshot of the blank Netlify admin panel with no sites and highlighted 'add new site' button'](/images/hosting-and-deployment/hosting-on-netlify/netlify-add-new-site.jpg) + +Netlify will then start walking you through the steps necessary for continuous deployment. First, you'll need to select your git provider again, but this time you are giving Netlify added permissions to your repositories. + +![Screenshot of step 1 of create a new site for Netlify: selecting the git provider](/images/hosting-and-deployment/hosting-on-netlify/netlify-create-new-site-step-1.jpg) + +And then again with the GitHub authorization modal: + +![Screenshot of step 1 of create a new site for Netlify: selecting the git provider](/images/hosting-and-deployment/hosting-on-netlify/netlify-authorize-added-permissions.jpg) + +Select the repo you want to use for continuous deployment. If you have a large number of repositories, you can filter through them in real time using repo search: + +![Screenshot of step 1 of create a new site for Netlify: selecting the git provider](/images/hosting-and-deployment/hosting-on-netlify/netlify-create-new-site-step-2.jpg) + +Once selected, you'll be brought to a screen for basic setup. Here you can select the branch you wanted published, your [build command][], and your publish (i.e. deploy) directory. The publish directory should mirror that of what you've set in your [site configuration][config], the default of which is `public`. The following steps assume you are publishing from the `master` branch. + +## Configure Hugo Version in Netlify + +You can [set Hugo version](https://www.netlify.com/blog/2017/04/11/netlify-plus-hugo-0.20-and-beyond/) for your environments in `netlify.toml` file or set `HUGO_VERSION` as a build environment variable in the Netlify console. + +For production: + - {{< code-toggle file="netlify" >}} ++{{< code file="netlify.toml" codeLang="toml" >}} +[context.production.environment] - HUGO_VERSION = "0.53" - {{< /code-toggle >}} ++ HUGO_VERSION = "0.82.1" ++{{< /code >}} + +For testing: + - ``` ++{{< code file="netlify.toml" codeLang="toml" >}} +[context.deploy-preview.environment] - HUGO_VERSION = "0.53" - ``` ++ HUGO_VERSION = "0.82.1" ++{{< /code >}} + +The Netlify configuration file can be a little hard to understand and get right for the different environment, and you may get some inspiration and tips from this site's `netlify.toml`: + +{{< code file="netlify.toml" nocode="true" >}} +{{< readfile file="netlify.toml" highlight="toml" >}} +{{< /code >}} + +## Build and Deploy Site + +In the Netlify console, selecting "Deploy site" will immediately take you to a terminal for your build:. + +![Animated gif of deploying a site to Netlify, including the terminal read out for the build.](/images/hosting-and-deployment/hosting-on-netlify/netlify-deploying-site.gif) + +Once the build is finished---this should only take a few seconds--you should now see a "Hero Card" at the top of your screen letting you know the deployment is successful. The Hero Card is the first element that you see in most pages. It allows you to see a quick summary of the page and gives access to the most common/pertinent actions and information. You'll see that the URL is automatically generated by Netlify. You can update the URL in "Settings." + +![Screenshot of successful deploy badge at the top of a deployments screen from within the Netlify admin.](/images/hosting-and-deployment/hosting-on-netlify/netlify-deploy-published.jpg) + +![Screenshot of homepage to https://hugo-netlify-example.netlify.com, which is mostly dummy text](/images/hosting-and-deployment/hosting-on-netlify/netlify-live-site.jpg) + +[Visit the live site][visit]. + +Now every time you push changes to your hosted git repository, Netlify will rebuild and redeploy your site. + +See [this blog post](https://www.netlify.com/blog/2017/04/11/netlify-plus-hugo-0.20-and-beyond/) for more details about how Netlify handles Hugo versions. + +## Use Hugo Themes with Netlify + +The [`git clone` method for installing themes][installthemes] is not supported by Netlify. If you were to use `git clone`, it would require you to recursively remove the `.git` subdirectory from the theme folder and would therefore prevent compatibility with future versions of the theme. + +A *better* approach is to install a theme as a proper git submodule. You can [read the GitHub documentation for submodules][ghsm] or those found on [Git's website][gitsm] for more information, but the command is similar to that of `git clone`: + +``` +cd themes +git submodule add https://github.com// +``` + +It is recommended to only use stable versions of a theme (if it’s versioned) and always check the changelog. This can be done by checking out a specific release within the theme's directory. + +Switch to the theme's directory and list all available versions: + +``` +cd themes/ +git tag +# exit with q +``` + +You can checkout a specific version as follows: + +``` +git checkout tags/ +``` + +You can update a theme to the latest version by executing the following command in the *root* directory of your project: + +``` +git submodule update --rebase --remote +``` + +## Next Steps + +You now have a live website served over https, distributed through CDN, and configured for continuous deployment. Dig deeper into the Netlify documentation: + +1. [Using a Custom Domain][] +2. [Setting up HTTPS on Custom Domains][httpscustom] +3. [Redirects and Rewrite Rules][] + + +[app.netlify.com]: https://app.netlify.com +[build command]: /getting-started/usage/#the-hugo-command +[config]: /getting-started/configuration/ +[ghsm]: https://github.com/blog/2104-working-with-submodules +[gitsm]: https://git-scm.com/book/en/v2/Git-Tools-Submodules +[httpscustom]: https://www.netlify.com/docs/ssl/ +[hugoversions]: https://github.com/netlify/build-image/blob/master/Dockerfile#L216 +[installthemes]: /themes/installing/ +[netlify]: https://www.netlify.com/ +[netlifysignup]: https://app.netlify.com/signup +[Quick Start]: /getting-started/quick-start/ +[Redirects and Rewrite Rules]: https://www.netlify.com/docs/redirects/ +[Using a Custom Domain]: https://www.netlify.com/docs/custom-domains/ +[visit]: https://hugo-netlify-example.netlify.com diff --cc docs/content/en/templates/introduction.md index 43f88f14,00000000..17fa5475 mode 100644,000000..100644 --- a/docs/content/en/templates/introduction.md +++ b/docs/content/en/templates/introduction.md @@@ -1,662 -1,0 +1,662 @@@ +--- +title: Introduction to Hugo Templating +linktitle: Introduction +description: Hugo uses Go's `html/template` and `text/template` libraries as the basis for the templating. +godocref: https://golang.org/pkg/html/template/ +date: 2017-02-01 +publishdate: 2017-02-01 +lastmod: 2017-02-25 +categories: [templates,fundamentals] +keywords: [go] +menu: + docs: + parent: "templates" + weight: 10 +weight: 10 +sections_weight: 10 +draft: false +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]({{< relref +"#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: + +``` +{{ 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 }} +``` + +## Variables {#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 }} +``` + +{{% warning %}} +For Hugo v0.47 and older versions, variables defined inside `if` +conditionals and similar are not visible on the outside. +See [https://github.com/golang/go/issues/10608](https://github.com/golang/go/issues/10608). + +Hugo has created a workaround for this issue in [Scratch](/functions/scratch). +{{% /warning %}} + +For **Hugo v0.48** and newer, variables can be re-defined using the +new `=` operator (new in Go 1.11). + +Below example will work only in these newer Hugo versions. The example +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 }} +``` + +## 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 functions][]. + +{{% note "Additional Boolean Operators" %}} +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/