{{ .WordCount }} Words

- {{ with .GetTerms "topics" }} -

{{ .LinkTitle }}

- {{ end }} - {{ with .GetTerms "tags" }} -

{{ .LinkTitle }}

- {{ end }} -

- {{ with .PrevInSection }} - {{.Title}} ++

{{ .WordCount }} Words

++ {{ with .GetTerms "topics" }} ++

{{ .LinkTitle }}

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

{{ .LinkTitle }}

++ ++ {{ end }} ++

++ {{ with .PrevInSection }} ++ {{ .Title }} ++ {{ end }} ++ {{ with .NextInSection }} ++ {{ .Title }} ++ {{ end }} ++

+{{ end }} +{{< /code >}} + +To easily generate new instances of a content type (e.g., new `.md` files in a section like `project/`) with preconfigured front matter, use [content archetypes][archetypes]. + +[archetypes]: /content-management/archetypes/ +[base templates]: /templates/base/ +[config]: /getting-started/configuration/ +[content type]: /content-management/types/ +[directory structure]: /getting-started/directory-structure/ +[dry]: https://en.wikipedia.org/wiki/Don%27t_repeat_yourself +[`.format` function]: /functions/format/ +[front matter]: /content-management/front-matter/ +[pagetaxonomy]: /templates/taxonomy-templates/#display-a-single-piece-of-contents-taxonomies +[pagevars]: /variables/page/ +[partials]: /templates/partials/ +[section]: /content-management/sections/ +[site variables]: /variables/site/ +[spf13]: https://spf13.com/ +[`with`]: /functions/with/ diff --cc docs/content/en/templates/sitemap-template.md index 9fc817020,000000000..d0738a362 mode 100644,000000..100644 --- a/docs/content/en/templates/sitemap-template.md +++ b/docs/content/en/templates/sitemap-template.md @@@ -1,87 -1,0 +1,84 @@@ +--- +title: Sitemap Templates +description: Hugo provides built-in sitemap templates. - date: 2017-02-01 +categories: [templates] +keywords: [sitemap, xml, templates] +menu: + docs: - parent: "templates" ++ parent: templates + weight: 160 +weight: 160 - sections_weight: 160 - draft: false +aliases: [/layout/sitemap/,/templates/sitemap/] +toc: true +--- + +## Overview + +Hugo's built-in sitemap templates conform to v0.9 of the [sitemap protocol]. + +With a monolingual project, Hugo generates a sitemap.xml file in the root of the [`publishDir`] using the built-in [sitemap.xml] template. + +With a multilingual project, Hugo generates: + +- A sitemap.xml file in the root of each site (language) using the built-in [sitemap.xml] template +- A sitemap.xml file in the root of the [`publishDir`] using the built-in [sitemapindex.xml] template + +## Configuration + +Set the default values for [change frequency] and [priority], and the name of the generated file, in your site configuration. + +{{< code-toggle file="config" >}} +[sitemap] + changefreq = 'monthly' + filename = 'sitemap.xml' + priority = 0.5 +{{}} + +changefreq +: How frequently a page is likely to change. Valid values are `always`, `hourly`, `daily`, `weekly`, `monthly`, `yearly`, and `never`. Default is `""` (change frequency omitted from rendered sitemap). + +filename +: The name of the generated file. Default is `sitemap.xml`. + +priority +: The priority of a page relative to any other page on the site. Valid values range from 0.0 to 1.0. Default is `-1` (priority omitted from rendered sitemap). + +## 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' + 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="config" >}} +disableKinds = ['sitemap'] +{{}} + - [`publishDir`]: {{< relref "getting-started/configuration#publishdir" >}} ++[`publishDir`]: /getting-started/configuration#publishdir +[change frequency]: +[priority]: +[sitemap protocol]: +[sitemap.xml]: +[sitemapindex.xml]: diff --cc docs/content/en/templates/taxonomy-templates.md index e9fc80525,000000000..e343df471 mode 100644,000000..100644 --- a/docs/content/en/templates/taxonomy-templates.md +++ b/docs/content/en/templates/taxonomy-templates.md @@@ -1,341 -1,0 +1,333 @@@ +--- +title: Taxonomy Templates - # linktitle: +description: Taxonomy templating includes taxonomy list pages, taxonomy terms pages, and using taxonomies in your single page templates. - date: 2017-02-01 - publishdate: 2017-02-01 - lastmod: 2017-02-01 +categories: [templates] +keywords: [taxonomies,metadata,front matter,terms,templates] +menu: + docs: - parent: "templates" ++ parent: templates + weight: 50 +weight: 50 - sections_weight: 50 - draft: false +aliases: [/taxonomies/displaying/,/templates/terms/,/indexes/displaying/,/taxonomies/templates/,/indexes/ordering/, /templates/taxonomies/, /templates/taxonomy/] +toc: true +--- + + + +Hugo includes support for user-defined groupings of content called **taxonomies**. Taxonomies are classifications that demonstrate logical relationships between content. See [Taxonomies under Content Management](/content-management/taxonomies) if you are unfamiliar with how Hugo leverages this powerful feature. + +Hugo provides multiple ways to use taxonomies throughout your project templates: + +* Order the way content associated with a taxonomy term is displayed in a [taxonomy list template](#taxonomy-list-templates) +* Order the way the terms for a taxonomy are displayed in a [taxonomy terms template](#taxonomy-terms-templates) +* List a single content's taxonomy terms within a [single page template] + +## Taxonomy List Templates + +Taxonomy list page templates are lists and therefore have all the variables and methods available to [list pages][lists]. + +### Taxonomy List Template Lookup Order + +See [Template Lookup](/templates/lookup-order/). + +## Taxonomy Terms Templates + +### Taxonomy Terms Templates Lookup Order + +See [Template Lookup](/templates/lookup-order/). + +### Taxonomy Methods + +A Taxonomy is a `map[string]WeightedPages`. + +.Get(term) +: Returns the WeightedPages for a term. + +.Count(term) +: The number of pieces of content assigned to this term. + +.Alphabetical +: Returns an OrderedTaxonomy (slice) ordered by Term. + +.ByCount +: Returns an OrderedTaxonomy (slice) ordered by number of entries. + +.Reverse +: Returns an OrderedTaxonomy (slice) in reverse order. Must be used with an OrderedTaxonomy. + +### OrderedTaxonomy + +Since Maps are unordered, an OrderedTaxonomy is a special structure that has a defined order. + +```go +[]struct { + Name string + WeightedPages WeightedPages +} +``` + +Each element of the slice has: + +.Term +: The Term used. + +.WeightedPages +: A slice of Weighted Pages. + +.Count +: The number of pieces of content assigned to this term. + +.Pages +: All Pages assigned to this term. All [list methods][renderlists] are available to this. + +## WeightedPages + +WeightedPages is simply a slice of WeightedPage. + +```go +type WeightedPages []WeightedPage +``` + +.Count(term) +: The number of pieces of content assigned to this term. + +.Pages +: Returns a slice of pages, which then can be ordered using any of the [list methods][renderlists]. + +## Displaying custom metadata in Taxonomy Terms Templates + +If you need to display custom metadata for each taxonomy term, you will need to create a page for that term at `/content///_index.md` and add your metadata in its front matter, [as explained in the taxonomies documentation](/content-management/taxonomies/#add-custom-metadata-to-a-taxonomy-or-term). Based on the Actors taxonomy example shown there, within your taxonomy terms template, you may access your custom fields by iterating through the variable `.Pages` as such: + +```go-html-template +

+ {{ .Title }} + {{ .Params.wikipedia }} +

+``` + + + +## Order Taxonomies + +Taxonomies can be ordered by either alphabetical key or by the number of content pieces assigned to that key. + +### Order Alphabetically Example + +```go-html-template +

{{ .Page.Title }} {{ .Count }}

+``` + + + +## Order Content within Taxonomies + +Hugo uses both `date` and `weight` to order content within taxonomies. + +Each piece of content in Hugo can optionally be assigned a date. It can also be assigned a weight for each taxonomy it is assigned to. + +When iterating over content within taxonomies, the default sort is the same as that used for section and list pages: first by weight, then by date. This means that if the weights for two pieces of content are the same, then the more recent content will be displayed first. + +The default weight for any piece of content is 0. Zero means "does not have a weight", not "has a weight of numerical value zero". + +Weights of zero are thus treated specially: if two pages have unequal weights, and one of them is zero, then the zero-weighted page will always appear after the other one, regardless of the other's weight. Zero weights should thus be used with care: for example, if both positive and negative weights are used to extend a sequence in both directions, a zero-weighted page will appear not in the middle of the list, but at the end. + +### Assign Weight + +Content can be assigned weight for each taxonomy that it's assigned to. + - ```txt - +++ ++ ++{{< code-toggle file="content/example.md" fm=true copy=false >}} +tags = [ "a", "b", "c" ] +tags_weight = 22 +categories = ["d"] - title = "foo" ++title = "Example" +categories_weight = 44 - +++ - Front Matter with weighted tags and categories - ``` ++{{< /code-toggle >}} + +The convention is `taxonomyname_weight`. + +In the above example, this piece of content has a weight of 22 which applies to the sorting when rendering the pages assigned to the "a", "b" and "c" values of the 'tag' taxonomy. + +It has also been assigned the weight of 44 when rendering the 'd' category. + +With this the same piece of content can appear in different positions in different taxonomies. + +Currently taxonomies only support the default ordering of content which is weight -> date. + + + +There are two different templates that the use of taxonomies will require you to provide. + +Both templates are covered in detail in the templates section. + - A [list template](/templates/list/) is any template that will be used to render multiple pieces of content in a single html page. This template will be used to generate all the automatically created taxonomy pages. ++A [list template](/templates/lists/) is any template that will be used to render multiple pieces of content in a single html page. This template will be used to generate all the automatically created taxonomy pages. + - A [taxonomy terms template](/templates/terms/) is a template used to ++A [taxonomy template](/templates/taxonomy-templates/) is a template used to +generate the list of terms for a given template. + + + +There are four common ways you can display the data in your +taxonomies in addition to the automatic taxonomy pages created by hugo - using the [list templates](/templates/list/): ++using the [list templates](/templates/lists/): + +1. For a given piece of content, you can list the terms attached +2. For a given piece of content, you can list other content with the same + term +3. You can list all terms for a taxonomy +4. You can list all taxonomies (with their terms) + +## Display a Single Piece of Content's Taxonomies + +Within your content templates, you may wish to display the taxonomies that piece of content is assigned to. + +Because we are leveraging the front matter system to define taxonomies for content, the taxonomies assigned to each content piece are located in the usual place (i.e., `.Params.`). + +### Example: List Tags in a Single Page Template + +```go-html-template +

{{ .LinkTitle }}

+``` + +If you want to list taxonomies inline, you will have to take care of optional plural endings in the title (if multiple taxonomies), as well as commas. Let's say we have a taxonomy "directors" such as `directors: [ "Joel Coen", "Ethan Coen" ]` in the TOML-format front matter. + +To list such taxonomies, use the following: + +### Example: Comma-delimit Tags in a Single Page Template + +```go-html-template +{{ $taxo := "directors" }} +{{ with .Param $taxo }} + Director{{ if gt (len .) 1 }}s{{ end }}: + {{ range $index, $director := . }} + {{- if gt $index 0 }}, {{ end -}} + {{ with $.Site.GetPage (printf "/%s/%s" $taxo $director) -}} + {{ $director }} + {{- end -}} + {{- end -}} +{{ end }} +``` + +Alternatively, you may use the [delimit template function][delimit] as a shortcut if the taxonomies should just be listed with a separator. See {{< gh 2143 >}} on GitHub for discussion. + +## List Content with the Same Taxonomy Term + +If you are using a taxonomy for something like a series of posts, you can list individual pages associated with the same taxonomy. This is also a quick and dirty method for showing related content: + +### Example: Showing Content in Same Series + +```go-html-template +

{{ .Page.Title }}

+``` + +## List All content in a Given taxonomy + +This would be very useful in a sidebar as âfeatured contentâ. You could even have different sections of âfeatured contentâ by assigning different terms to the content. + +### Example: Grouping "Featured" Content + +```go-html-template + +``` + +## Render a Site's Taxonomies + +If you wish to display the list of all keys for your site's taxonomy, you can retrieve them from the [`.Site` variable][sitevars] available on every page. + +This may take the form of a tag cloud, a menu, or simply a list. + +The following example displays all terms in a site's tags taxonomy: + +### Example: List All Site Tags {#example-list-all-site-tags} + +```go-html-template +

{{ .Page.Title }} {{ .Count }}

+``` + +### Example: List All Taxonomies, Terms, and Assigned Content + +This example will list all taxonomies and their terms, as well as all the content assigned to each of the terms. + - {{< code file="layouts/partials/all-taxonomies.html" download="all-taxonomies.html" download="all-taxonomies.html" >}} ++{{< code file="layouts/partials/all-taxonomies.html" >}} +

{{ $taxonomy_term }} +
- {{ $key }}
+

+{{< /code >}} + +## `.Site.GetPage` for Taxonomies + - Because taxonomies are lists, the [`.GetPage` function][getpage] can be used to get all the pages associated with a particular taxonomy term using a terse syntax. The following ranges over the full list of tags on your site and links to each of the individual taxonomy pages for each term without having to use the more fragile URL construction of the ["List All Site Tags" example above]({{< relref "#example-list-all-site-tags" >}}): ++Because taxonomies are lists, the [`.GetPage` function][getpage] can be used to get all the pages associated with a particular taxonomy term using a terse syntax. The following ranges over the full list of tags on your site and links to each of the individual taxonomy pages for each term without having to use the more fragile URL construction of the ["List All Site Tags" example above](#example-list-all-site-tags): + +{{< code file="links-to-all-tags.html" >}} +{{ $taxo := "tags" }} +

{{ .Title}}
{{ .Title }}

+{{< /code >}} + + + + + + +[delimit]: /functions/delimit/ +[getpage]: /functions/getpage/ +[lists]: /templates/lists/ +[renderlists]: /templates/lists/ +[single page template]: /templates/single-page-templates/ +[sitevars]: /variables/site/ diff --cc docs/content/en/templates/template-debugging.md index b8938890f,000000000..0f32fa732 mode 100644,000000..100644 --- a/docs/content/en/templates/template-debugging.md +++ b/docs/content/en/templates/template-debugging.md @@@ -1,69 -1,0 +1,64 @@@ +--- +title: Template Debugging +description: You can use Go templates' `printf` function to debug your Hugo templates. These snippets provide a quick and easy visualization of the variables available to you in different contexts. - date: 2017-02-01 - publishdate: 2017-02-01 +categories: [templates] +keywords: [debugging,troubleshooting] +menu: + docs: - parent: "templates" ++ parent: templates + weight: 180 +weight: 180 - sections_weight: 180 - aliases: [] - toc: false +--- + +Here are some snippets you can add to your template to answer some common questions. + +These snippets use the `printf` function available in all Go templates. This function is an alias to the Go function, [fmt.Printf](https://pkg.go.dev/fmt). + +## What Variables are Available in this Context? + +You can use the template syntax, `$.`, to get the top-level template context from anywhere in your template. This will print out all the values under, `.Site`. + +```go-html-template +{{ printf "%#v" $.Site }} +``` + +This will print out the value of `.Permalink`: + +```go-html-template +{{ printf "%#v" .Permalink }} +``` + +This will print out a list of all the variables scoped to the current context +(`.`, aka ["the dot"][tempintro]). + +```go-html-template +{{ printf "%#v" . }} +``` + +When developing a [homepage], what does one of the pages you're looping through look like? + +```go-html-template +{{ range .Pages }} + {{/* The context, ".", is now each one of the pages as it goes through the loop */}} + {{ printf "%#v" . }} +{{ end }} +``` + +## Why Am I Showing No Defined Variables? + +Check that you are passing variables in the `partial` function: + +```go-html-template +{{ partial "header.html" }} +``` + +This example will render the header partial, but the header partial will not have access to any contextual variables. You need to pass variables explicitly. For example, note the addition of ["the dot"][tempintro]. + +```go-html-template +{{ partial "header.html" . }} +``` + +The dot (`.`) is considered fundamental to understanding Hugo templating. For more information, see [Introduction to Hugo Templating][tempintro]. + +[homepage]: /templates/homepage/ +[tempintro]: /templates/introduction/ diff --cc docs/content/en/templates/views.md index 495f701bd,000000000..24ff61150 mode 100644,000000..100644 --- a/docs/content/en/templates/views.md +++ b/docs/content/en/templates/views.md @@@ -1,121 -1,0 +1,114 @@@ +--- +title: Content View Templates - # linktitle: Content Views +description: Hugo can render alternative views of your content, which is especially useful in list and summary views. - date: 2017-02-01 - publishdate: 2017-02-01 - lastmod: 2017-02-01 +categories: [templates] +keywords: [views] +menu: + docs: - parent: "templates" ++ parent: templates + weight: 70 +weight: 70 - sections_weight: 70 - draft: false - aliases: [] +toc: true +--- + +These alternative **content views** are especially useful in [list templates][lists]. + +The following are common use cases for content views: + +* You want content of every type to be shown on the homepage but only with limited [summary views][summaries]. +* You only want a bulleted list of your content on a [taxonomy list page][taxonomylists]. Views make this very straightforward by delegating the rendering of each different type of content to the content itself. + +## Create a Content View + +To create a new view, create a template in each of your different content type directories with the view name. The following example contains an "li" view and a "summary" view for the `posts` and `project` content types. As you can see, these sit next to the [single content view][single] template, `single.html`. You can even provide a specific view for a given type and continue to use the `_default/single.html` for the primary view. + +```txt + â¾ layouts/ + â¾ posts/ + li.html + single.html + summary.html + â¾ project/ + li.html + single.html + summary.html +``` + +Hugo also has support for a default content template to be used in the event that a specific content view template has not been provided for that type. Content views can also be defined in the `_default` directory and will work the same as list and single templates who eventually trickle down to the `_default` directory as a matter of the lookup order. + + +```txt +â¾ layouts/ + â¾ _default/ + li.html + single.html + summary.html +``` + +## Which Template Will be Rendered? + +The following is the [lookup order][lookup] for content views: + +1. `/layouts//.html` +2. `/layouts/_default/.html` +3. `/themes//layouts//.html` +4. `/themes//layouts/_default/.html` + +## Example: Content View Inside a List + +The following example demonstrates how to use content views inside your [list templates][lists]. + +### `list.html` + +In this example, `.Render` is passed into the template to call the [render function][render]. `.Render` is a special function that instructs content to render itself with the view template provided as the first argument. In this case, the template is going to render the `summary.html` view that follows: + - {{< code file="layouts/_default/list.html" download="list.html" >}} ++{{< code file="layouts/_default/list.html" >}} +

- {{ range .Pages }} - {{ .Render "summary"}} - {{ end }} ++

++ {{ range .Pages }} ++ {{ .Render "summary" }} ++ {{ end }} +

+{{< /code >}} + +### `summary.html` + +Hugo will pass the entire page object to the following `summary.html` view template. (See [Page Variables][pagevars] for a complete list.) + - {{< code file="layouts/_default/summary.html" download="summary.html" >}} ++{{< code file="layouts/_default/summary.html" >}} +

{{ .Date.Format "Mon, Jan 2, 2006" }} - {{ .FuzzyWordCount }} Words

+ {{ .Summary }} + +

+{{< /code >}} + +### `li.html` + +Continuing on the previous example, we can change our render function to use a smaller `li.html` view by changing the argument in the call to the `.Render` function (i.e., `{{ .Render "li" }}`). + - {{< code file="layouts/_default/li.html" download="li.html" >}} ++{{< code file="layouts/_default/li.html" >}} +

+ {{ .Title }} +

+{{< /code >}} + +[lists]: /templates/lists/ +[lookup]: /templates/lookup-order/ +[pagevars]: /variables/page/ +[render]: /functions/render/ +[single]: /templates/single-page-templates/ +[spf]: https://spf13.com +[spfsourceli]: https://github.com/spf13/spf13.com/blob/master/layouts/_default/li.html +[spfsourcesection]: https://github.com/spf13/spf13.com/blob/master/layouts/_default/section.html +[spfsourcesummary]: https://github.com/spf13/spf13.com/blob/master/layouts/_default/summary.html +[summaries]: /content-management/summaries/ +[taxonomylists]: /templates/taxonomy-templates/ diff --cc docs/content/en/tools/_index.md index a63041819,000000000..b553dac9c mode 100644,000000..100644 --- a/docs/content/en/tools/_index.md +++ b/docs/content/en/tools/_index.md @@@ -1,23 -1,0 +1,19 @@@ +--- +title: Developer Tools +linktitle: Developer Tools Overview +description: In addition to Hugo's powerful CLI, there is a large number of community-developed tool chains for Hugo developers. - date: 2016-12-05 - publishdate: 2016-12-05 - lastmod: 2017-02-26 +categories: [developer tools] +keywords: [] +menu: + docs: - parent: "tools" ++ parent: tools + weight: 01 +weight: 01 - sections_weight: 01 +--- + +One of Hugo's greatest strengths is its passionate---and always evolving---developer community. With the exception of the `highlight` shortcode mentioned in [Syntax Highlighting][syntax], the tools and other projects featured in this section are offerings from both commercial services and open-source projects, many of which are developed by Hugo developers just like you. + +[See the popularity of Hugo compared with other static site generators.][staticgen] + +[staticgen]: https://staticgen.com - [syntax]: /tools/syntax-highlighting/ ++[syntax]: /content-management/syntax-highlighting/ diff --cc docs/content/en/tools/editors.md index ed67885fc,000000000..55ab47090 mode 100644,000000..100644 --- a/docs/content/en/tools/editors.md +++ b/docs/content/en/tools/editors.md @@@ -1,50 -1,0 +1,44 @@@ +--- +title: Editor Plug-ins for Hugo +linktitle: Editor Plug-ins +description: The Hugo community uses a wide range of preferred tools and has developed plug-ins for some of the most popular text editors to help automate parts of your workflow. - date: 2017-02-01 - publishdate: 2017-02-01 +categories: [developer tools] +keywords: [editor, plug-ins] +menu: + docs: - parent: "tools" ++ parent: tools + weight: 50 +weight: 50 - sections_weight: 50 - draft: false - aliases: [] - toc: false +--- + +The Hugo community uses a wide range of preferred tools and has developed plug-ins for some of the most popular text editors to help automate parts of your workflow. + +## Sublime Text + +* [Hugofy](https://github.com/akmittal/Hugofy). Hugofy is a plugin for Sublime Text 3 to make life easier to use Hugo static site generator. +* [Hugo Snippets](https://packagecontrol.io/packages/Hugo%20Snippets). Hugo Snippets is a useful plugin for adding automatic snippets to Sublime Text 3. + +## Visual Studio Code + +* [Hugofy](https://marketplace.visualstudio.com/items?itemName=akmittal.hugofy). Hugofy is a plugin for Visual Studio Code to "make life easier" when developing with Hugo. The source code can be found [here](https://github.com/akmittal/hugofy-vscode). +* [Hugo Helper](https://marketplace.visualstudio.com/items?itemName=rusnasonov.vscode-hugo). Hugo Helper is a plugin for Visual Studio Code that has some useful commands for Hugo. The source code can be found [here](https://github.com/rusnasonov/vscode-hugo). +* [Hugo Language and Syntax Support](https://marketplace.visualstudio.com/items?itemName=budparr.language-hugo-vscode). Hugo Language and Syntax Support is a Visual Studio Code plugin for Hugo syntax highlighting and snippets. The source code can be found [here](https://github.com/budparr/language-hugo-vscode). +* [Hugo Themer](https://marketplace.visualstudio.com/items?itemName=eliostruyf.vscode-hugo-themer). Hugo Themer is an extension to help you while developing themes. It allows you to easily navigate through your theme files. +* [Front Matter](https://marketplace.visualstudio.com/items?itemName=eliostruyf.vscode-front-matter). Once you go for a static site, you need to think about how you are going to manage your articles. Front matter is a tool that helps you maintain the metadata/front matter of your articles like: creation date, modified date, slug, tile, SEO check, and many more... +* [Syntax Highlighting for Hugo Shortcodes](https://marketplace.visualstudio.com/items?itemName=kaellarkin.hugo-shortcode-syntax). This extension add some syntax highlighting for Shortcodes, making visual identification of individual pieces easier. + +## Emacs + +* [emacs-easy-hugo](https://github.com/masasam/emacs-easy-hugo). Emacs major mode for managing hugo blogs. Note that Hugo also supports [Org-mode][formats]. +* [ox-hugo.el](https://ox-hugo.scripter.co). Native Org-mode exporter that exports to Blackfriday Markdown with Hugo front-matter. `ox-hugo` supports two common Org blogging flows --- exporting multiple Org subtrees in a single file to multiple Hugo posts, and exporting a single Org file to a single Hugo post. It also leverages the Org tag and property inheritance features. See [*Why ox-hugo?*](https://ox-hugo.scripter.co/doc/why-ox-hugo/) for more. + +## Vim + +* [Vim Hugo Helper](https://github.com/robertbasic/vim-hugo-helper). A small Vim plugin to help me with writing posts with Hugo. + +## Atom + +* [Hugofy](https://atom.io/packages/hugofy). A Hugo Static Website Generator package for Atom. +* [language-hugo](https://atom.io/packages/language-hugo). Adds syntax highlighting to Hugo files. + +[formats]: /content-management/formats/ diff --cc docs/content/en/tools/frontends.md index 7ad44df53,000000000..1bfaf0995 mode 100644,000000..100644 --- a/docs/content/en/tools/frontends.md +++ b/docs/content/en/tools/frontends.md @@@ -1,29 -1,0 +1,22 @@@ +--- +title: Frontend Interfaces with Hugo +linktitle: Frontends +description: Do you prefer a graphical user interface over a text editor? Give these frontends a try. - date: 2017-02-01 - publishdate: 2017-02-01 - lastmod: 2017-02-01 +categories: [developer tools] +keywords: [frontend, gui] +menu: + docs: - parent: "tools" ++ parent: tools + weight: 40 +weight: 40 - sections_weight: 40 - draft: false - aliases: [] - toc: false +--- + +- [enwrite](https://github.com/zzamboni/enwrite). Enwrite enables evernote-powered, statically generated blogs and websites. Now posting to your blog or updating your website is as easy as writing a new note in Evernote! +- [Lipi](https://github.com/SohanChy/Lipi). Lipi is a native GUI frontend written in Java to manage your Hugo websites. +- [Netlify CMS](https://netlifycms.org). Netlify CMS is an open source, serverless solution for managing Git based content in static sites, and it works on any platform that can host static sites. A [Hugo/Netlify CMS starter](https://github.com/netlify-templates/one-click-hugo-cms) is available to get new projects running quickly. +- [Hokus CMS](https://github.com/julianoappelklein/hokus). Hokus CMS is an open source, multi-platform, easy to use, desktop application for Hugo. Build from simple to complex user interfaces for Hugo websites by choosing from a dozen ready-to-use components â all for free, with no vendor lock-in. + +## Commercial Services + +- [DATOCMS](https://www.datocms.com) DatoCMS is a fully customizable administrative area for your static websites. Use your favorite website generator, let your clients publish new content independently, and the host the site anywhere you like. +- [CloudCannon](https://cloudcannon.com/hugo-cms/). The intuitive Git-based CMS for your Hugo website. CloudCannon syncs changes from your Git repository and pushes content changes back, so your development and content teams are always in sync. Edit all of your content on the page with visual editing, build entire pages with reusable custom components and then publish confidently. diff --cc docs/content/en/tools/migrations.md index d6ca14ab5,000000000..0156c46db mode 100644,000000..100644 --- a/docs/content/en/tools/migrations.md +++ b/docs/content/en/tools/migrations.md @@@ -1,85 -1,0 +1,80 @@@ +--- +title: Migrate to Hugo +linktitle: Migrations +description: A list of community-developed tools for migrating from your existing static site generator or content management system to Hugo. - date: 2017-02-01 - publishdate: 2017-02-01 - lastmod: 2022-03-26 +keywords: [migrations, jekyll, wordpress, drupal, ghost, contentful] +menu: + docs: - parent: "tools" ++ parent: tools + weight: 10 +weight: 10 - sections_weight: 10 - draft: false +aliases: [/developer-tools/migrations/, /developer-tools/migrated/] +toc: true +--- + +This section highlights some projects around Hugo that are independently developed. These tools try to extend the functionality of our static site generator or help you to get started. + +{{% note %}} +Do you know or maintain a similar project around Hugo? Feel free to open a [pull request](https://github.com/gohugoio/hugoDocs/pulls) on GitHub if you think it should be added. +{{% /note %}} + +Take a look at this list of migration tools if you currently use other blogging tools like Jekyll or WordPress but intend to switch to Hugo instead. They'll take care to export your content into Hugo-friendly formats. + +## Jekyll + +Alternatively, you can use the new [Jekyll import command](/commands/hugo_import_jekyll/). + +- [JekyllToHugo](https://github.com/fredrikloch/JekyllToHugo) - A Small script for converting Jekyll blog posts to a Hugo site. +- [ConvertToHugo](https://github.com/coderzh/ConvertToHugo) - Convert your blog from Jekyll to Hugo. + +## Ghost + +- [ghostToHugo](https://github.com/jbarone/ghostToHugo) - Convert Ghost blog posts and export them to Hugo. + +## Octopress + +- [octohug](https://github.com/codebrane/octohug) - Octopress to Hugo migrator. + +## DokuWiki + +- [dokuwiki-to-hugo](https://github.com/wgroeneveld/dokuwiki-to-hugo) - Migrates your DokuWiki source pages from [DokuWiki syntax](https://www.dokuwiki.org/wiki:syntax) to Hugo Markdown syntax. Includes extra's like the TODO plugin. Written with extensibility in mind using python 3. Also generates a TOML header for each page. Designed to copypaste the wiki directory into your /content directory. + +## WordPress + +- [wordpress-to-hugo-exporter](https://github.com/SchumacherFM/wordpress-to-hugo-exporter) - A one-click WordPress plugin that converts all posts, pages, taxonomies, metadata, and settings to Markdown and YAML which can be dropped into Hugo. (Note: If you have trouble using this plugin, you can [export your site for Jekyll](https://wordpress.org/plugins/jekyll-exporter/) and use Hugo's built in Jekyll converter listed above.) +- [blog2md](https://github.com/palaniraja/blog2md) - Works with [exported xml](https://en.support.wordpress.com/export/) file of your free YOUR-TLD.wordpress.com website. It also saves approved comments to `YOUR-POST-NAME-comments.md` file along with posts. +- [wordhugopress](https://github.com/nantipov/wordhugopress) - A small utility written in Java, exports the entire WordPress site from the database and resource (e.g. images) files stored locally or remotely. Therefore, migration from the backup files is possible. Supports merging of the multiple WordPress sites into a single Hugo one. + +## Medium + +- [medium2md](https://github.com/gautamdhameja/medium-2-md) - A simple Medium to Hugo exporter able to import stories in one command, including Front Matter. +- [medium-to-hugo](https://github.com/bgadrian/medium-to-hugo) - CLI tool written in Go to export medium posts into a Hugo compatible Markdown format. Tags and images are included. All images will be downloaded locally and linked appropriately. + +## Tumblr + +- [tumblr-importr](https://github.com/carlmjohnson/tumblr-importr) - An importer that uses the Tumblr API to create a Hugo static site. +- [tumblr2hugomarkdown](https://github.com/Wysie/tumblr2hugomarkdown) - Export all your Tumblr content to Hugo Markdown files with preserved original formatting. +- [Tumblr to Hugo](https://github.com/jipiboily/tumblr-to-hugo) - A migration tool that converts each of your Tumblr posts to a content file with a proper title and path. Furthermore, "Tumblr to Hugo" creates a CSV file with the original URL and the new path on Hugo, to help you setup the redirections. + +## Drupal + +- [drupal2hugo](https://github.com/danapsimer/drupal2hugo) - Convert a Drupal site to Hugo. + +## Joomla + +- [hugojoomla](https://github.com/davetcc/hugojoomla) - This utility written in Java takes a Joomla database and converts all the content into Markdown files. It changes any URLs that are in Joomla's internal format and converts them to a suitable form. + +## Blogger + +- [blogimport](https://github.com/natefinch/blogimport) - A tool to import from Blogger posts to Hugo. +- [blogger-to-hugo](https://pypi.org/project/blogger-to-hugo/) - Another tool to import Blogger posts to Hugo. It also downloads embedded images so they will be stored locally. +- [blog2md](https://github.com/palaniraja/blog2md) - Works with [exported xml](https://support.google.com/blogger/answer/41387?hl=en) file of your YOUR-TLD.blogspot.com website. It also saves comments to `YOUR-POST-NAME-comments.md` file along with posts. +- [BloggerToHugo](https://github.com/huanlin/blogger-to-hugo) - Yet another tool to import Blogger posts to Hugo. For Windows platform only, and .NET Framework 4.5 is required. See README.md before using this tool. + +## Contentful + - - [contentful2hugo](https://github.com/ArnoNuyts/contentful2hugo) - A tool to create content-files for Hugo from content on [Contentful](https://www.contentful.com/). ++- [contentful-hugo](https://github.com/ModiiMedia/contentful-hugo) - A tool to create content-files for Hugo from content on [Contentful](https://www.contentful.com/). + +## BlogML + +- [BlogML2Hugo](https://github.com/jijiechen/BlogML2Hugo) - A tool that helps you convert BlogML xml file to Hugo Markdown files. Users need to take care of links to attachments and images by themselves. This helps the blogs that export BlogML files (e.g. BlogEngine.NET) transform to hugo sites easily. diff --cc docs/content/en/tools/other.md index ed7c530d0,000000000..3f8aeebbb mode 100644,000000..100644 --- a/docs/content/en/tools/other.md +++ b/docs/content/en/tools/other.md @@@ -1,28 -1,0 +1,23 @@@ +--- +title: Other Hugo Community Projects +linktitle: Other Projects +description: Some interesting projects developed by the Hugo community that don't quite fit into our other developer tool categories. - date: 2017-02-01 - publishdate: 2017-02-01 +categories: [developer tools] +keywords: [frontend, gui] +menu: + docs: - parent: "tools" ++ parent: tools + weight: 70 +weight: 70 - sections_weight: 70 - aliases: [] - toc: false +--- + +And for all the other small things around Hugo: + +- [hugo-gallery](https://github.com/icecreammatt/hugo-gallery) lets you create an image gallery for Hugo sites. +- [flickr-hugo-embed](https://github.com/nikhilm/flickr-hugo-embed) prints shortcodes to embed a set of images from an album on Flickr into Hugo. +- [hugo-openapispec-shortcode](https://github.com/tenfourty/hugo-openapispec-shortcode) A shortcode that allows you to include [Open API Spec](https://openapis.org) (formerly known as Swagger Spec) in a page. +- [HugoPhotoSwipe](https://github.com/GjjvdBurg/HugoPhotoSwipe) makes it easy to create image galleries using PhotoSwipe. +- [Hugo SFTP Upload](https://github.com/thomasmey/HugoSftpUpload) Syncs the local build of your Hugo website with your remote webserver via SFTP. +- [Emacs Easy Hugo](https://github.com/masasam/emacs-easy-hugo) Emacs package for writing blog posts in markdown or org-mode and building your site with Hugo. +- [JAMStack Themes](https://jamstackthemes.dev/ssg/hugo/). JAMStack themes is a collection of site themes filterable by static site generator and supported CMS to help build CMS-connected sites using Hugo (linking to Hugo-specific themes). +- [plausible-hugo](https://github.com/divinerites/plausible-hugo). Easy Hugo integration for Plausible Analytics, a simple, open-source, lightweight and privacy-friendly web analytics alternative to Google Analytics. diff --cc docs/content/en/tools/search.md index 464aa9107,000000000..030e9f2c7 mode 100644,000000..100644 --- a/docs/content/en/tools/search.md +++ b/docs/content/en/tools/search.md @@@ -1,36 -1,0 +1,30 @@@ +--- +title: Search for your Hugo Website +linktitle: Search +description: See some of the open-source and commercial search options for your newly created Hugo website. - date: 2017-02-01 - publishdate: 2017-02-01 - categories: [developer tools] - keywords: [search,tools] +menu: + docs: - parent: "tools" ++ parent: tools + weight: 60 +weight: 60 - sections_weight: 60 - aliases: [] +toc: true +--- + +A static website with a dynamic search function? Yes, Hugo provides an alternative to embeddable scripts from Google or other search engines for static websites. Hugo allows you to provide your visitors with a custom search function by indexing your content files directly. + +* [GitHub Gist for Hugo Workflow](https://gist.github.com/sebz/efddfc8fdcb6b480f567). This gist contains a simple workflow to create a search index for your static website. It uses a simple Grunt script to index all your content files and [lunr.js](https://lunrjs.com/) to serve the search results. + +* [hugo-lunr](https://www.npmjs.com/package/hugo-lunr). A simple way to add site search to your static Hugo site using [lunr.js](https://lunrjs.com/). Hugo-lunr will create an index file of any HTML and Markdown documents in your Hugo project. +* [hugo-lunr-zh](https://www.npmjs.com/package/hugo-lunr-zh). A bit like Hugo-lunr, but Hugo-lunr-zh can help you separate the Chinese keywords. +* [GitHub Gist for Fuse.js integration](https://gist.github.com/eddiewebb/735feb48f50f0ddd65ae5606a1cb41ae). This gist demonstrates how to leverage Hugo's existing build time processing to generate a searchable JSON index used by [Fuse.js](https://fusejs.io/) on the client-side. Although this gist uses Fuse.js for fuzzy matching, any client-side search tool capable of reading JSON indexes will work. Does not require npm, grunt or other build-time tools except Hugo! +* [hugo-search-index](https://www.npmjs.com/package/hugo-search-index). A library containing Gulp tasks and a prebuilt browser script that implements search. Gulp generates a search index from project markdown files. +* [hugofastsearch](https://gist.github.com/cmod/5410eae147e4318164258742dd053993). A usability and speed update to "GitHub Gist for Fuse.js integration" âÂ global, keyboard-optimized search. +* [JS & Fuse.js tutorial](https://makewithhugo.com/add-search-to-a-hugo-site/) A simple client-side search solution, using FuseJS (does not require jQuery). +* [Pagefind](https://github.com/cloudcannon/pagefind). A fully static search library that aims to perform well on large sites, while using as little of your users' bandwidth as possible. +* [Hugo Lyra](https://github.com/paolomainardi/hugo-lyra). Hugo-Lyra is a JavaScript module to integrate [Lyra](https://github.com/LyraSearch/lyra) into a Hugo website. It contains the server-side part to generate the index and the client-side library (optional) to bootstrap the search engine easily. + +## Commercial Search Services + +* [Algolia](https://www.algolia.com/)'s Search API makes it easy to deliver a great search experience in your apps and websites. Algolia Search provides hosted full-text, numerical, faceted, and geolocalized search. - * [Bonsai](https://www.bonsai.io) is a fully-managed hosted Elasticsearch service that is fast, reliable, and simple to set up. Easily ingest your docs from Hugo into Elasticsearch following [this guide from the docs](https://docs.bonsai.io/docs/hugo). ++* [Bonsai](https://www.bonsai.io) is a fully-managed hosted Elasticsearch service that is fast, reliable, and simple to set up. Easily ingest your docs from Hugo into Elasticsearch following [this guide from the docs](https://docs.bonsai.io/hc/en-us/articles/13929190788756-Hugo). +* [ExpertRec](https://www.expertrec.com/) is a hosted search-as-a-service solution that is fast and scalable. Set-up and integration is extremely easy and takes only a few minutes. The search settings can be modified without coding using a dashboard. diff --cc docs/content/en/tools/starter-kits.md index 8399e99df,000000000..69c8f3e0b mode 100644,000000..100644 --- a/docs/content/en/tools/starter-kits.md +++ b/docs/content/en/tools/starter-kits.md @@@ -1,38 -1,0 +1,31 @@@ +--- +title: Starter Kits - linktitle: Starter Kits +description: A list of community-developed projects designed to help you get up and running with Hugo. - date: 2017-02-22 - publishdate: 2017-02-01 - lastmod: 2018-08-11 +keywords: [starters,assets,pipeline] +menu: + docs: - parent: "tools" ++ parent: tools + weight: 30 +weight: 30 - sections_weight: 30 - draft: false +aliases: [/developer-tools/migrations/,/developer-tools/migrated/] - toc: false +--- + +Know of a Hugo-related starter kit that isn't mentioned here? [Please add it to the list.][addkit] + - {{% note "Starter Kits are Not Maintained by the Hugo Team"%}} ++{{% note %}} +The following starter kits are developed by active members of the Hugo community. If you find yourself having issues with any of the projects, it's best to file an issue directly with the project's maintainer(s). +{{% /note %}} + +* [Wowchemy]. Wowchemy is the 5,500+ star open source Hugo starter kit and website builder trusted by 750,000+ sites since 2016. Create _any_ kind of site with [50+ templates, widgets, and extensions](https://wowchemy.com/). Translated into 35+ languages and backed by a large, active community of 150+ contributors. +* [Hugo Wrapper][hugow]. Hugo Wrapper is a POSIX-style shell script which acts as a wrapper to download and run Hugo binary for your platform. It can be executed in variety of [Operating Systems][hugow-test] and [Command Shells][hugow-test]. +* [GOHUGO AMP]. GoHugo AMP is a starter theme that aims to make it easy to adopt [Google's AMP Project][amp]. The starter kit comes with 40+ shortcodes and partials plus automatic structured data. The project also includes a [separate site with extensive documentation][gohugodocs]. +* [Hyas]. Hyas is a Hugo starter helping you build modern websites that are secure, fast, and SEO-ready â by default. It is Netlify-ready (functions, redirects, headers) and comes with [documentation](https://gethyas.com/) to easily make it your own. + +[Wowchemy]: https://github.com/wowchemy/wowchemy-hugo-modules +[addkit]: https://github.com/gohugoio/hugo/edit/master/docs/content/en/tools/starter-kits.md +[amp]: https://amp.dev +[GOHUGO AMP]: https://github.com/wildhaber/gohugo-amp - [gohugodocs]: https://gohugo-amp.gohugohq.com/ ++[gohugodocs]: https://github.com/wildhaber/gohugo-amp.gohugohq.com +[hugow]: https://github.com/khos2ow/hugo-wrapper +[hugow-test]: https://github.com/khos2ow/hugo-wrapper#tested-on +[Hyas]: https://github.com/h-enk/hyas diff --cc docs/content/en/troubleshooting/_index.md index 3170dc7d8,000000000..51f1791a3 mode 100644,000000..100644 --- a/docs/content/en/troubleshooting/_index.md +++ b/docs/content/en/troubleshooting/_index.md @@@ -1,23 -1,0 +1,14 @@@ +--- +title: Troubleshoot - linktitle: Troubleshoot +description: Frequently asked questions and known issues pulled from the Hugo Discuss forum. - date: 2017-02-01 - publishdate: 2017-02-01 - lastmod: 2017-02-01 +menu: + docs: - parent: "troubleshooting" ++ parent: troubleshooting + weight: 1 +weight: 1 - draft: false - hidesectioncontents: false - slug: +aliases: [/troubleshooting/faqs/,/faqs/] - toc: false - notesforauthors: +--- + +The Troubleshooting section includes known issues, recent workarounds, and FAQs pulled from the [Hugo Discussion Forum][forum]. + +[forum]: https://discourse.gohugo.io diff --cc docs/content/en/troubleshooting/build-performance.md index ea31ef84b,000000000..b58cdc11f mode 100644,000000..100644 --- a/docs/content/en/troubleshooting/build-performance.md +++ b/docs/content/en/troubleshooting/build-performance.md @@@ -1,94 -1,0 +1,87 @@@ +--- +title: Build Performance - linktitle: Build Performance +description: An overview of features used for diagnosing and improving performance issues in site builds. - date: 2017-03-12 - publishdate: 2017-03-12 - keywords: [performance, build] - categories: [troubleshooting] +menu: + docs: - parent: "troubleshooting" ++ parent: troubleshooting +weight: 3 - slug: - aliases: [] +toc: true +--- + +## Template Metrics + +Hugo is a very fast static site generator, but it is possible to write +inefficient templates. Hugo's _template metrics_ feature is extremely helpful +in pinpointing which templates are executed most often and how long those +executions take **in terms of CPU time**. + +| Metric Name | Description | +| ------------------- | -------------------------------------------------------------- | +| cumulative duration | The cumulative time spent executing a given template. | +| average duration | The average time spent executing a given template. | +| maximum duration | The maximum time a single execution took for a given template. | +| count | The number of times a template was executed. | +| template | The template name. | + +```txt +â¶ hugo --templateMetrics +Started building sites ... + +Built site for language en: +0 draft content +0 future content +0 expired content +2 regular pages created +22 other pages created +0 non-page files copied +0 paginator pages created +4 tags created +3 categories created +total in 18 ms + +Template Metrics: + + cumulative average maximum + duration duration duration count template + ---------- -------- -------- ----- -------- + 6.419663ms 583.605Âµs 994.374Âµs 11 _internal/_default/rss.xml + 4.718511ms 1.572837ms 3.880742ms 3 indexes/category.html + 4.642666ms 2.321333ms 3.282842ms 2 posts/single.html + 4.364445ms 396.767Âµs 2.451372ms 11 partials/header.html + 2.346069ms 586.517Âµs 903.343Âµs 4 indexes/tag.html + 2.330919ms 211.901Âµs 2.281342ms 11 partials/header.includes.html + 1.238976ms 103.248Âµs 446.084Âµs 12 posts/li.html + 972.16Âµs 972.16Âµs 972.16Âµs 1 _internal/_default/sitemap.xml + 953.597Âµs 953.597Âµs 953.597Âµs 1 index.html + 822.263Âµs 822.263Âµs 822.263Âµs 1 indexes/post.html + 567.498Âµs 51.59Âµs 112.205Âµs 11 partials/navbar.html + 348.22Âµs 31.656Âµs 88.249Âµs 11 partials/meta.html + 346.782Âµs 173.391Âµs 276.176Âµs 2 posts/summary.html + 235.184Âµs 21.38Âµs 124.383Âµs 11 partials/footer.copyright.html + 132.003Âµs 12Âµs 117.999Âµs 11 partials/menu.html + 72.547Âµs 6.595Âµs 63.764Âµs 11 partials/footer.html +``` + +{{% note %}} +**A Note About Parallelism** + +Hugo builds pages in parallel where multiple pages are generated +simultaneously. Because of this parallelism, the sum of "cumulative duration" +values is usually greater than the actual time it takes to build a site. +{{% /note %}} + +## Cached Partials + +Some `partial` templates such as sidebars or menus are executed many times +during a site build. Depending on the content within the `partial` template and +the desired output, the template may benefit from caching to reduce the number +of executions. The [`partialCached`][partialcached] template function provides +caching capabilities for `partial` templates. + - {{% tip %}} ++{{% note %}} +Note that you can create cached variants of each `partial` by passing additional +parameters to `partialCached` beyond the initial context. See the +`partialCached` documentation for more details. - {{% /tip %}} ++{{% /note %}} + - [partialCached]:{{< ref "/functions/partialCached.md" >}} ++[partialCached]: /functions/partialcached diff --cc docs/content/en/troubleshooting/faq.md index 998f9bbbe,000000000..04e857acb mode 100644,000000..100644 --- a/docs/content/en/troubleshooting/faq.md +++ b/docs/content/en/troubleshooting/faq.md @@@ -1,62 -1,0 +1,61 @@@ +--- +title: Frequently Asked Questions +linktitle: FAQ +description: Solutions to some common Hugo problems. - date: 2018-02-10 +categories: [troubleshooting] +menu: + docs: - parent: "troubleshooting" ++ parent: troubleshooting +keywords: [faqs] +weight: 2 +toc: true +aliases: [/faq/] +--- + +{{% note %}} +**Note:** The answers/solutions presented below are short, and may not be enough to solve your problem. Visit [Hugo Discourse](https://discourse.gohugo.io/) and use the search. It that does not help, start a new topic and ask your questions. +{{% /note %}} + +## I can't see my content! + +Is your Markdown file [in draft mode](https://gohugo.io/content-management/front-matter/#front-matter-variables)? When testing, run `hugo server` with the `-D` or `--buildDrafts` [switch](https://gohugo.io/getting-started/usage/#draft-future-and-expired-content). + +Is your Markdown file part of a [leaf bundle](/content-management/page-bundles/)? If there is an `index.md` file in the same or any parent directory then other Markdown files will not be rendered as individual pages. + +## Can I set configuration variables via OS environment? + +Yes you can! See [Configure with Environment Variables](/getting-started/configuration/#configure-with-environment-variables). + +## How do I schedule posts? + +1. Set `publishDate` in the page [Front Matter](/content-management/front-matter/) to a datetime in the future. If you want the creation and publication datetime to be the same, it's also sufficient to only set `date`[^date-hierarchy]. +2. Build and publish at intervals. + +How to automate the "publish at intervals" part depends on your situation: + +* If you deploy from your own PC/server, you can automate with [Cron](https://en.wikipedia.org/wiki/Cron) or similar. +* If your site is hosted on a service similar to [Netlify](https://www.netlify.com/) you can: + * Use a service such as [ifttt](https://ifttt.com/date_and_time) to schedule the updates + * Set up a deploy hook which you can run with a cron service to deploy your site at intervals, such as [cron-job.org](https://cron-job.org/) (both Netlify and Cloudflare Pages support deploy hooks) + +Also see this Twitter thread: + +{{< tweet user="ChrisShort" id="962380712027590657" >}} + +[^date-hierarchy]: See [Configure Dates](https://gohugo.io/getting-started/configuration/#configure-dates) for the order in which the different date variables are complemented by each other when not explicitly set. + +## Can I use the latest Hugo version on Netlify? + +Yes you can! Read [this](/hosting-and-deployment/hosting-on-netlify/#configure-hugo-version-in-netlify). + +## I get "... this feature is not available in your current Hugo version" + +If you process `SCSS` or `Sass` to `CSS` in your Hugo project with `libsass` as the transpiler or if you convert images to the `webp` format, you need the Hugo `extended` version, or else you may see an error message similar to the below: + +```bash +error: failed to transform resource: TOCSS: failed to transform "scss/main.scss" (text/x-scss): this feature is not available in your current Hugo version +``` + +We release two set of binaries for technical reasons. The extended version is not what you get by default for some installation methods. On the [release page](https://github.com/gohugoio/hugo/releases), look for archives with `extended` in the name. To build `hugo-extended`, use `go install --tags extended` + +To confirm, run `hugo version` and look for the word `extended`. diff --cc docs/content/en/variables/_index.md index 382ee25d4,000000000..9b5289573 mode 100644,000000..100644 --- a/docs/content/en/variables/_index.md +++ b/docs/content/en/variables/_index.md @@@ -1,23 -1,0 +1,17 @@@ +--- +title: Variables and Params +linktitle: Variables Overview +description: Page-, file-, taxonomy-, and site-level variables and parameters available in templates. - date: 2017-02-01 - publishdate: 2017-02-01 - lastmod: 2017-02-01 +categories: [variables and params] +keywords: [variables,params,values,globals] - draft: false +menu: + docs: - parent: "variables" ++ parent: variables + weight: 1 - weight: 01 #rem - sections_weight: 01 ++weight: 01 +aliases: [/templates/variables/] - toc: false +--- + +Hugo's templates are context aware and make a large number of values available to you as you're creating views for your website. + +[Go templates]: /templates/introduction/ "Understand context in Go templates by learning the language's fundamental templating functions." diff --cc docs/content/en/variables/files.md index 4e6c0632f,000000000..784ab7c64 mode 100644,000000..100644 --- a/docs/content/en/variables/files.md +++ b/docs/content/en/variables/files.md @@@ -1,54 -1,0 +1,102 @@@ +--- +title: File Variables - linktitle: - description: "You can access filesystem-related data for a content file in the `.File` variable." - date: 2017-02-01 - publishdate: 2017-02-01 - lastmod: 2017-02-01 ++description: "Use File variables to access file-related values for each page that is backed by a file." +categories: [variables and params] +keywords: [files] - draft: false +menu: + docs: - parent: "variables" ++ parent: variables + weight: 40 ++toc: true +weight: 40 - sections_weight: 40 +aliases: [/variables/file-variables/] - toc: false +--- ++## Variables + - {{% note "Rendering Local Files" %}} - For information on creating shortcodes and templates that tap into Hugo's file-related feature set, see [Local File Templates](/templates/files/). ++{{% note %}} ++The path separators (slash or backslash) in `.File.Path`, `.File.Dir`, and `.File.Filename` depend on the operating system. +{{% /note %}} + - The `.File` object contains the following fields: - +.File.Path - : the original relative path of the page, relative to the content dir (e.g., `posts/foo.en.md`) - - .File.LogicalName - : the name of the content file that represents a page (e.g., `foo.en.md`) ++: (`string`) The file path, relative to the `content` directory. + - .File.TranslationBaseName - : the filename without extension or optional language identifier (e.g., `foo`) ++.File.Dir ++: (`string`) The file path, excluding the file name, relative to the `content` directory. + - .File.ContentBaseName - : is either a TranslationBaseName or name of containing folder if file is a leaf bundle. ++.File.LogicalName ++: (`string`) The file name. + +.File.BaseFileName - : the filename without extension (e.g., `foo.en`) ++: (`string`) The file name, excluding the extension. ++ ++.File.TranslationBaseName ++: (`string`) The file name, excluding the extension and language identifier. + +.File.Ext - : the file extension of the content file (e.g., `md`). ++: (`string`) The file extension. + +.File.Lang - : the language associated with the given file if Hugo's [Multilingual features][multilingual] are enabled (e.g., `en`) ++: (`string`) The language associated with the given file. + - .File.Dir - : given the path `content/posts/dir1/dir2/`, the relative directory path of the content file will be returned (e.g., `posts/dir1/dir2/`). Note that the path separator (`\` or `/`) could be dependent on the operating system. ++ ++.File.ContentBaseName ++: (`string`) If the page is a branch or leaf bundle, the name of the containing directory, else the `.TranslationBaseName`. ++ ++.File.Filename ++: (`string`) The absolute file path. + +.File.UniqueID - : the MD5-checksum of the content file's path. ++: (`string`) The MD5 hash of `.File.Path`. ++ ++## Examples ++ ++```text ++content/ ++âââ news/ ++âÂ Â âââ b/ ++âÂ Â âÂ Â âââ index.de.md <-- leaf bundle ++âÂ Â âÂ Â âââ index.en.md <-- leaf bundle ++âÂ Â âââ a.de.md <-- regular content ++âÂ Â âââ a.en.md <-- regular content ++âÂ Â âââ _index.de.md <-- branch bundle ++âÂ Â âââ _index.en.md <-- branch bundle ++âââ _index.de.md ++âââ _index.en.md ++``` ++ ++With the content structure above, the `.File` objects for the English pages contain the following properties: ++ ++ |regular content|leaf bundle|branch bundle ++:--|:--|:--|:-- ++Path|news/a.en.md|news/b/index.en.md|news/_index.en.md ++Dir|news/|news/b/|news/ ++LogicalName|a.en.md|index.en.md|_index.en.md ++BaseFileName|a.en|index.en|_index.en ++TranslationBaseName|a|index|_index ++Ext|md|md|md ++Lang|en|en|en ++ContentBaseName|a|b|news ++Filename|/home/user/...|/home/user/...|/home/user/... ++UniqueID|15be14b...|186868f...|7d9159d... ++ ++## Defensive coding ++ ++Some of the pages on a site may not be backed by a file. For example: ++ ++- Top level section pages ++- Taxonomy pages ++- Term pages ++ ++Without a backing file, Hugo will throw a warning if you attempt to access a `.File` property. For example: ++ ++```text ++WARN .File.ContentBaseName on zero object. Wrap it in if or with... ++``` ++ ++To code defensively: + - [Multilingual]: /content-management/multilingual/ ++```go-html-template ++{{ with .File }} ++ {{ .ContentBaseName }} ++{{ end }} ++``` diff --cc docs/content/en/variables/git.md index 24878e350,000000000..dfd6e5407 mode 100644,000000..100644 --- a/docs/content/en/variables/git.md +++ b/docs/content/en/variables/git.md @@@ -1,58 -1,0 +1,51 @@@ +--- +title: Git Info Variables +linktitle: Git Variables +description: Get the last Git revision information for every content file. - date: 2017-03-12 - publishdate: 2017-03-12 - lastmod: 2017-03-12 +categories: [variables and params] +keywords: [git] - draft: false +menu: + docs: - parent: "variables" ++ parent: variables + weight: 70 +weight: 70 - sections_weight: 70 +aliases: [/extras/gitinfo/] - toc: false - wip: false +--- + - {{% note "`.GitInfo` Performance Considerations" %}} ++{{% note %}} +Hugo's Git integrations should be fairly performant but *can* increase your build time. This will depend on the size of your Git history. +{{% /note %}} + +## `.GitInfo` Prerequisites + +1. The Hugo site must be in a Git-enabled directory. +2. The Git executable must be installed and in your system `PATH`. +3. The `.GitInfo` feature must be enabled in your Hugo project by passing `--enableGitInfo` flag on the command line or by setting `enableGitInfo` to `true` in your [site's configuration file][configuration]. + +## The `.GitInfo` Object + +The `GitInfo` object contains the following fields: + +.AbbreviatedHash +: the abbreviated commit hash (e.g., `866cbcc`) + +.AuthorName +: the author's name, respecting [`.mailmap`](https://git-scm.com/docs/gitmailmap) + +.AuthorEmail +: the author's email address, respecting [`.mailmap`](https://git-scm.com/docs/gitmailmap) + +.AuthorDate +: the author date + +.Hash +: the commit hash (e.g., `866cbccdab588b9908887ffd3b4f2667e94090c3`) + +.Subject +: commit message subject (e.g., `tpl: Add custom index function`) + +## `.Lastmod` + +If the `.GitInfo` feature is enabled, `.Lastmod` (on `Page`) is fetched from Git i.e. `.GitInfo.AuthorDate`. This behavior can be changed by adding your own [front matter configuration for dates](/getting-started/configuration/#configure-front-matter). + +[configuration]: /getting-started/configuration/ diff --cc docs/content/en/variables/menus.md index a59560729,000000000..b88514803 mode 100644,000000..100644 --- a/docs/content/en/variables/menus.md +++ b/docs/content/en/variables/menus.md @@@ -1,127 -1,0 +1,92 @@@ +--- - title: Menu Entry Properties - linktitle: Menu Entry Properties - description: A menu entry in a menu-template has specific variables and functions to make menu management easier. - date: 2017-03-12 - publishdate: 2017-03-12 - lastmod: 2017-03-12 ++title: Menu Variables ++description: Use these variables and methods in your menu templates. +categories: [variables and params] +keywords: [menus] - draft: false +menu: + docs: - title: "variables defined by a menu entry" - parent: "variables" ++ parent: variables + weight: 50 +weight: 50 - sections_weight: 50 +aliases: [/variables/menu/] - toc: false +--- + - A **menu entry** has the following properties available that can be used in a - [menu template][menu-template]. ++## Variables + - ## Menu Entry Variables ++After [defining menu entries], access their properties in [menu templates] with these variables. ++ ++.Children ++: (`menu`) A collection of child menu entries, if any, under the current menu entry. ++ ++.Identifier ++: (`string`) The `identifier` property of the menu entry. If you define the menu entry [automatically], the page's `.Section`. ++ ++.KeyName ++: (`string`) The `identifier` property of the menu entry, else the `name` property. + +.Menu - : _string_
- Name of the **menu** that contains this **menu entry**. ++: (`string`) The identifier of the menu that contains the menu entry. + - .URL - : _string_
- URL that the menu entry points to. The `url` key, if set for the menu entry, - sets this value. If that key is not set, and if the menu entry is set in a page - front-matter, this value defaults to the page's `.RelPermalink`. ++.Name ++: (`string`) The `name` property of the menu entry. ++ ++- If you define the menu entry [automatically], the page's `.LinkTitle`, else the page's `.Title`. ++- If you define the menu [in front matter] or [in site configuration], falls back to the page's `.LinkTitle`, then to the page's `.Title`. + +.Page - : _\*Page_
- Reference to the [page object][page-object] associated with the menu entry. This - will be non-nil if the menu entry is set via a page's front-matter and not via - the site config. ++: (`page`) A reference to the page associated with the menu entry. + ++ + - .Name - : _string_
- Name of the menu entry. The `name` key, if set for the menu entry, sets - this value. If that key is not set, and if the menu entry is set in a page - front-matter, this value defaults to the page's `.LinkTitle`. ++.Params ++: (`map`) The `params` property of the menu entry. + - .Identifier - : _string_
- Value of the `identifier` key if set for the menu entry. This value must be - unique for each menu entry. **It is necessary to set a unique identifier - manually if two or more menu entries have the same `.Name`.** ++.Parent ++: (`string`) The `parent` property of the menu entry. ++ ++.Post ++: (`template.HTML`) The `post` property of the menu entry. + +.Pre - : _template.HTML_
- Value of the `pre` key if set for the menu entry. This value typically contains - a string representing HTML. ++: (`template.HTML`) The `pre` property of the menu entry. + - .Post - : _template.HTML_
- Value of the `post` key if set for the menu entry. This value typically contains - a string representing HTML. ++.Title ++: (`string`) The `title` property of the menu entry. + - .Weight - : _int_
- Value of the `weight` key if set for the menu entry. By default the entries in - a menu are sorted ascending by their `weight`. If that key is not set, and if - the menu entry is set in a page front-matter, this value defaults to the page's - `.Weight`. ++- If you define the menu entry [automatically], the page's `.LinkTitle`, else the page's `.Title`. ++- If you define the menu [in front matter] or [in site configuration], falls back to the page's `.LinkTitle`, then to the page's `.Title`. + - .Parent - : _string_
- Name (or Identifier if present) of this menu entry's parent **menu entry**. The - `parent` key, if set for the menu entry, sets this value. If this key is set, - this menu entry nests under that parent entry, else it nests directly under the - `.Menu`. ++.URL ++: (`string`) The `.RelPermalink` of the page associated with the menu entry. For menu entries pointing to external resources, the `url` property of the menu entry. + - .Children - : _Menu_
- This value is auto-populated by Hugo. It is a collection of children menu - entries, if any, under the current menu entry. ++.Weight ++: (`int`) The `weight` property of the menu entry. + - ## Menu Entry Functions ++- If you define the menu entry [automatically], the page's `.Weight`. ++- If you define the menu [in front matter] or [in site configuration], falls back to the page's `.Weight`. + - Menus also have the following functions available: ++## Methods + +.HasChildren - : _boolean_
- Returns `true` if `.Children` is non-nil. - - .KeyName - : _string_
- Returns the `.Identifier` if present, else returns the `.Name`. ++: (`bool`) Returns `true` if `.Children` is non-nil. + +.IsEqual - : _boolean_
- Returns `true` if the two compared menu entries represent the same menu entry. ++: (`bool`) Returns `true` if the compared menu entries represent the same menu entry. + +.IsSameResource - : _boolean_
- Returns `true` if the two compared menu entries have the same `.URL`. - - .Title - : _string_
- Link title, meant to be used in the `title` attribute of a menu entry's - ``-tags. Returns the menu entry's `title` key if set. Else, if the menu - entry was created through a page's front-matter, it returns the page's - `.LinkTitle`. Else, it just returns an empty string. - - ## Other Menu-related Functions - - Additionally, here are some relevant methods available to menus on a page: ++: (`bool`) Returns `true` if the compared menu entries point to the same resource. + - .IsMenuCurrent - : _(menu string, menuEntry *MenuEntry ) boolean_
- See [`.IsMenuCurrent` method](/functions/ismenucurrent/). ++.Page.HasMenuCurrent ++: (`bool`) Use this method to determine ancestors of the active menu entry. See [details](/functions/hasmenucurrent/). + - .HasMenuCurrent - : _(menu string, menuEntry *MenuEntry) boolean_
- See [`.HasMenuCurrent` method](/functions/hasmenucurrent/). ++.Page.IsMenuCurrent ++: (`bool`) Use this method to determine the active menu entry. See [details](/functions/ismenucurrent/). + - [menu-template]: /templates/menu-templates/ - [page-object]: /variables/page/ ++[automatically]: /content-management/menus/#define-automatically ++[defining menu entries]: /content-management/menus/#overview ++[in front matter]: /content-management/menus/#define-in-front-matter ++[in site configuration]: /content-management/menus/#define-in-site-configuration ++[menu templates]: /templates/menu-templates/ diff --cc docs/content/en/variables/page.md index 2de54ff8b,000000000..f8266965e mode 100644,000000..100644 --- a/docs/content/en/variables/page.md +++ b/docs/content/en/variables/page.md @@@ -1,301 -1,0 +1,325 @@@ +--- +title: Page Variables - linktitle: +description: Page-level variables are defined in a content file's front matter, derived from the content's file location, or extracted from the content body itself. - date: 2017-02-01 - publishdate: 2017-02-01 +categories: [variables and params] +keywords: [pages] - draft: false +menu: + docs: - title: "variables defined by a page" - parent: "variables" ++ parent: variables + weight: 20 +weight: 20 - sections_weight: 20 - aliases: [] +toc: true +--- + +The following is a list of page-level variables. Many of these will be defined in the front matter, derived from file location, or extracted from the content itself. + - {{% note "`.Scratch`" %}} - See [`.Scratch`](/functions/scratch/) for page-scoped, writable variables. - {{% /note %}} - +## Page Variables + +.AlternativeOutputFormats +: contains all alternative formats for a given page; this variable is especially useful `link rel` list in your site's ``. (See [Output Formats](/templates/output-formats/).) + +.Aliases +: aliases of this page + +.Ancestors - : get the ancestors of each page, simplify [breadcrumb navigation]({{< relref "content-management/sections#example-breadcrumb-navigation" >}}) implementation complexity ++: get the ancestors of each page, simplify [breadcrumb navigation](/content-management/sections#example-breadcrumb-navigation) implementation complexity + +.BundleType +: the [bundle] type: `leaf`, `branch`, or an empty string if the page is not a bundle. + +.Content +: the content itself, defined below the front matter. + +.Data +: the data specific to this type of page. + +.Date +: the date associated with the page; `.Date` pulls from the `date` field in a content's front matter. See also `.ExpiryDate`, `.PublishDate`, and `.Lastmod`. + +.Description +: the description for the page. + +.Draft +: a boolean, `true` if the content is marked as a draft in the front matter. + +.ExpiryDate +: the date on which the content is scheduled to expire; `.ExpiryDate` pulls from the `expirydate` field in a content's front matter. See also `.PublishDate`, `.Date`, and `.Lastmod`. + +.File +: filesystem-related data for this content file. See also [File Variables]. + ++.Fragments ++: Fragments returns the fragments for this page. See [Page Fragments](#page-fragments). ++ +.FuzzyWordCount +: the approximate number of words in the content. + +.IsHome +: `true` in the context of the [homepage](/templates/homepage/). + +.IsNode +: always `false` for regular content pages. + +.IsPage +: always `true` for regular content pages. + +.IsSection +: `true` if [`.Kind`](/templates/section-templates/#page-kinds) is `section`. + +.IsTranslated +: `true` if there are translations to display. + +.Keywords +: the meta keywords for the content. + +.Kind +: the page's *kind*. Possible return values are `page`, `home`, `section`, `taxonomy`, or `term`. Note that there are also `RSS`, `sitemap`, `robotsTXT`, and `404` kinds, but these are only available during the rendering of each of these respective page's kind and therefore *not* available in any of the `Pages` collections. + +.Language +: a language object that points to the language's definition in the site `config`. `.Language.Lang` gives you the language code. + +.Lastmod +: the date the content was last modified. `.Lastmod` pulls from the `lastmod` field in a content's front matter. + + - If `lastmod` is not set, and `.GitInfo` feature is disabled, the front matter `date` field will be used. + - If `lastmod` is not set, and `.GitInfo` feature is enabled, `.GitInfo.AuthorDate` will be used instead. + +See also `.ExpiryDate`, `.Date`, `.PublishDate`, and [`.GitInfo`][gitinfo]. + +.LinkTitle +: access when creating links to the content. If set, Hugo will use the `linktitle` from the front matter before `title`. + +.Next - : Points up to the next [regular page](/variables/site/#site-pages) (sorted by Hugo's [default sort](/templates/lists#default-weight--date--linktitle--filepath)). Example: `{{with .Next}}{{.Permalink}}{{end}}`. Calling `.Next` from the first page returns `nil`. ++: Points up to the next [regular page](/variables/site/#site-pages) (sorted by Hugo's [default sort](/templates/lists#default-weight--date--linktitle--filepath)). Example: `{{ with .Next }}{{ .Permalink }}{{ end }}`. Calling `.Next` from the first page returns `nil`. + +.NextInSection - : Points up to the next [regular page](/variables/site/#site-pages) below the same top level section (e.g. in `/blog`)). Pages are sorted by Hugo's [default sort](/templates/lists#default-weight--date--linktitle--filepath). Example: `{{with .NextInSection}}{{.Permalink}}{{end}}`. Calling `.NextInSection` from the first page returns `nil`. ++: Points up to the next [regular page](/variables/site/#site-pages) below the same top level section (e.g. in `/blog`)). Pages are sorted by Hugo's [default sort](/templates/lists#default-weight--date--linktitle--filepath). Example: `{{ with .NextInSection }}{{ .Permalink }}{{ end }}`. Calling `.NextInSection` from the first page returns `nil`. + +.OutputFormats +: contains all formats, including the current format, for a given page. Can be combined the with [`.Get` function](/functions/get/) to grab a specific format. (See [Output Formats](/templates/output-formats/).) + +.Pages +: a collection of associated pages. This value will be `nil` within - the context of regular content pages. See [`.Pages`]({{< relref "page.md#pages" >}}). ++ the context of regular content pages. See [`.Pages`](#pages). + +.Permalink +: the Permanent link for this page; see [Permalinks](/content-management/urls/) + +.Plain +: the Page content stripped of HTML tags and presented as a string. You may need to pipe the result through the [`htmlUnescape`](/functions/htmlunescape/) function when rendering this value with the HTML [output format](/templates/output-formats#output-format-definitions). + +.PlainWords +: the slice of strings that results from splitting .Plain into words, as defined in Go's [strings.Fields](https://pkg.go.dev/strings#Fields). + +.Prev - : Points down to the previous [regular page](/variables/site/#site-pages) (sorted by Hugo's [default sort](/templates/lists#default-weight--date--linktitle--filepath)). Example: `{{if .Prev}}{{.Prev.Permalink}}{{end}}`. Calling `.Prev` from the last page returns `nil`. ++: Points down to the previous [regular page](/variables/site/#site-pages) (sorted by Hugo's [default sort](/templates/lists#default-weight--date--linktitle--filepath)). Example: `{{ if .Prev }}{{ .Prev.Permalink }}{{ end }}`. Calling `.Prev` from the last page returns `nil`. + +.PrevInSection - : Points down to the previous [regular page](/variables/site/#site-pages) below the same top level section (e.g. `/blog`). Pages are sorted by Hugo's [default sort](/templates/lists#default-weight--date--linktitle--filepath). Example: `{{if .PrevInSection}}{{.PrevInSection.Permalink}}{{end}}`. Calling `.PrevInSection` from the last page returns `nil`. ++: Points down to the previous [regular page](/variables/site/#site-pages) below the same top level section (e.g. `/blog`). Pages are sorted by Hugo's [default sort](/templates/lists#default-weight--date--linktitle--filepath). Example: `{{ if .PrevInSection }}{{ .PrevInSection.Permalink }}{{ end }}`. Calling `.PrevInSection` from the last page returns `nil`. + +.PublishDate +: the date on which the content was or will be published; `.Publishdate` pulls from the `publishdate` field in a content's front matter. See also `.ExpiryDate`, `.Date`, and `.Lastmod`. + +.RawContent +: raw markdown content without the front matter. Useful with [remarkjs.com]( +https://remarkjs.com) + +.ReadingTime +: the estimated time, in minutes, it takes to read the content. + +.Resources +: resources such as images and CSS that are associated with this page + +.Ref +: returns the permalink for a given reference (e.g., `.Ref "sample.md"`). `.Ref` does *not* handle in-page fragments correctly. See [Cross References](/content-management/cross-references/). + +.RelPermalink +: the relative permanent link for this page. + +.RelRef +: returns the relative permalink for a given reference (e.g., `RelRef +"sample.md"`). `.RelRef` does *not* handle in-page fragments correctly. See [Cross References](/content-management/cross-references/). + +.Site +: see [Site Variables](/variables/site/). + +.Sites +: returns all sites (languages). A typical use case would be to link back to the main language: `...`. + +.Sites.First +: returns the site for the first language. If this is not a multilingual setup, it will return itself. + +.Summary +: a generated summary of the content for easily showing a snippet in a summary view. The breakpoint can be set manually by inserting  at the appropriate place in the content page, or the summary can be written independent of the page text. See [Content Summaries](/content-management/summaries/) for more details. + +.TableOfContents +: the rendered [table of contents](/content-management/toc/) for the page. + +.Title +: the title for this page. + +.Translations +: a list of translated versions of the current page. See [Multilingual Mode](/content-management/multilingual/) for more information. + +.TranslationKey +: the key used to map language translations of the current page. See [Multilingual Mode](/content-management/multilingual/) for more information. + +.Truncated +: a boolean, `true` if the `.Summary` is truncated. Useful for showing a "Read more..." link only when necessary. See [Summaries](/content-management/summaries/) for more information. + +.Type +: the [content type](/content-management/types/) of the content (e.g., `posts`). + +.Weight +: assigned weight (in the front matter) to this content, used in sorting. + +.WordCount +: the number of words in the content. + ++## Writable Page-scoped Variables ++ ++[.Scratch][scratch] ++: returns a Scratch to store and manipulate data. In contrast to the [`.Store`][store] method, this scratch is reset on server rebuilds. ++ ++[.Store][store] ++: returns a Scratch to store and manipulate data. In contrast to the [`.Scratch`][scratch] method, this scratch is not reset on server rebuilds. ++ +## Section Variables and Methods + +Also see [Sections](/content-management/sections/). + +{{< readfile file="/content/en/readfiles/sectionvars.md" markdown="true" >}} + +## The `.Pages` Variable {#pages} + +`.Pages` is an alias to `.Data.Pages`. It is conventional to use the +aliased form `.Pages`. + +### `.Pages` compared to `.Site.Pages` + +{{< getcontent path="readfiles/pages-vs-site-pages.md" >}} + ++## Page Fragments ++ ++{{< new-in "0.111.0" >}} ++ ++The `.Fragments` method returns a list of fragments for the current page. ++ ++.Headings ++: A recursive list of headings for the current page. Can be used to generate a table of contents. ++ ++{{< todo >}}add .Headings toc example{{< /todo >}} ++ ++.Identifiers ++: A sorted list of identifiers for the current page. Can be used to check if a page contains a specific identifier or if a page contains duplicate identifiers: ++ ++```go-html-template ++{{ if .Fragments.Identifiers.Contains "my-identifier" }} ++

Page contains identifier "my-identifier"

++{{ end }} ++ ++{{ if gt (.Fragments.Identifiers.Count "my-identifier") 1 }} ++

Page contains duplicate "my-identifier" fragments

++{{ end }} ++``` ++ ++.HeadingsMap ++: Holds a map of headings for the current page. Can be used to start the table of contents from a specific heading. ++ ++Also see the [Go Doc](https://pkg.go.dev/github.com/gohugoio/hugo@v0.111.0/markup/tableofcontents#Fragments) for the return type. ++ ++### Fragments in hooks and shortcodes ++ ++`.Fragments` are safe to call from render hooks, even on the page you're on (`.Page.Fragments`). For shortcodes we recommend that all `.Fragments` usage is nested inside the `{{}}` shortcode delimiter (`{{%/**/%}}` takes part in the ToC creation so it's easy to end up in a situation where you bite yourself in the tail). ++ ++ ++## The global page function ++ ++{{< new-in "0.111.1" >}} ++ ++Hugo almost always passes a `Page` as the data context into the top level template (e.g. `single.html`) (the one exception is the multihost sitemap template). This means that you can access the current page with the `.` variable in the template. ++ ++But when you're deeply nested inside `.Render`, partial etc., accessing that `Page` object isn't always practical or possible. ++ ++For this reason, Hugo provides a global `page` function that you can use to access the current page from anywhere in any template. ++ ++```go-html-template ++{{ page.Title }} ++``` ++ ++There are one caveat with this, and this isn't new, but it's worth mentioning here: There are situations in Hugo where you may see a cached value, e.g. when using `partialCached` or in a shortcode. ++ +## Page-level Params + +Any other value defined in the front matter in a content file, including taxonomies, will be made available as part of the `.Params` variable. + - ```yml - --- - title: My First Post - date: 2017-02-20T15:26:23-06:00 ++{{< code-toggle file="content/example.md" fm=true copy=false >}} ++title: Example +categories: [one] +tags: [two,three,four] - ``` ++{{< /code-toggle >}} + +With the above front matter, the `tags` and `categories` taxonomies are accessible via the following: + +* `.Params.tags` +* `.Params.categories` + - {{% note "Casing of Params" %}} - Page-level `.Params` are *only* accessible in lowercase. - {{% /note %}} - - The `.Params` variable is particularly useful for the introduction of user-defined front matter fields in content files. For example, a Hugo website on book reviews could have the following front matter in `/content/review/book01.md`: ++The `.Params` variable is particularly useful for the introduction of user-defined front matter fields in content files. For example, a Hugo website on book reviews could have the following front matter: + - ```yml - --- - ... ++{{< code-toggle file="content/example.md" fm=true copy=false >}} ++title: Example +affiliatelink: "http://www.my-book-link.here" +recommendedby: "My Mother" - ... - --- - ``` ++{{< /code-toggle >}} + - These fields would then be accessible to the `/themes/yourtheme/layouts/review/single.html` template through `.Params.affiliatelink` and `.Params.recommendedby`, respectively. ++These fields would then be accessible to via `.Params.affiliatelink` and `.Params.recommendedby`. + - Two common situations where this type of front matter field could be introduced is as a value of a certain attribute like `href=""` or by itself to be displayed as text to the website's visitors. - - {{< code file="/themes/yourtheme/layouts/review/single.html" >}} -

Buy this book

++```go-html-template ++

Buy this book

It was recommended by {{ .Params.recommendedby }}.

- {{< /code >}} ++``` + - This template would render as follows, assuming you've set [`uglyURLs`](/content-management/urls/) to `false` in your [site `config`](/getting-started/configuration/): ++This template would render as follows: + - {{< output file="yourbaseurl/review/book01/index.html" >}} ++```html +

Buy this book

It was recommended by my Mother.

- {{< /output >}} ++``` + +{{% note %}} +See [Archetypes](/content-management/archetypes/) for consistency of `Params` across pieces of content. +{{% /note %}} + +### The `.Param` Method + +In Hugo, you can declare params in individual pages and globally for your entire website. A common use case is to have a general value for the site param and a more specific value for some of the pages (i.e., a header image): + +```go-html-template +{{ $.Param "header_image" }} +``` + +The `.Param` method provides a way to resolve a single value according to it's definition in a page parameter (i.e. in the content's front matter) or a site parameter (i.e., in your `config`). + +### Access Nested Fields in Front Matter + +When front matter contains nested fields like the following: + - ```yml - --- ++{{< code-toggle file="content/example.md" fm=true copy=false >}} ++title: Example +author: + given_name: John + family_name: Feminella + display_name: John Feminella - --- - ``` ++{{< /code-toggle >}} ++ +`.Param` can access these fields by concatenating the field names together with a dot: + +```go-html-template +{{ $.Param "author.display_name" }} +``` + - If your front matter contains a top-level key that is ambiguous with a nested key, as in the following case: - - ```yml - --- - favorites.flavor: vanilla - favorites: - flavor: chocolate - --- - ``` - - The top-level key will be preferred. Therefore, the following method, when applied to the previous example, will print `vanilla` and not `chocolate`: - - ```txt - {{ $.Param "favorites.flavor" }} - => vanilla - ``` - +[gitinfo]: /variables/git/ +[File Variables]: /variables/files/ - [bundle]: {{< relref "content-management/page-bundles" >}} ++[bundle]: /content-management/page-bundles ++[scratch]: /functions/scratch ++[store]: /functions/store diff --cc docs/content/en/variables/pages.md index 61036dd74,000000000..15904de95 mode 100644,000000..100644 --- a/docs/content/en/variables/pages.md +++ b/docs/content/en/variables/pages.md @@@ -1,30 -1,0 +1,25 @@@ +--- +title: Pages Methods - linktitle: +description: Pages is the core page collection in Hugo and has many useful methods. - date: 2019-10-20 +categories: [variables and params] +keywords: [pages] - draft: false +menu: + docs: - title: "methods defined on a page collection" - parent: "variables" ++ parent: variables + weight: 21 +weight: 21 - sections_weight: 20 +aliases: [/pages] +toc: true +--- + +Also see [List templates](/templates/lists) for an overview of sort methods. + +## .Next PAGE + +`.Next` and `.Prev` on `Pages` work similar to the methods with the same names on `.Page`, but are more flexible (and slightly slower) as they can be used on any page collection. + - `.Next` points **up** to the next page relative to the page sent in as the argument. Example: `{{with .Site.RegularPages.Next . }}{{.RelPermalink}}{{end}}`. Calling `.Next` with the first page in the collection returns `nil`. ++`.Next` points **up** to the next page relative to the page sent in as the argument. Example: `{{ with .Site.RegularPages.Next . }}{{ .RelPermalink }}{{ end }}`. Calling `.Next` with the first page in the collection returns `nil`. + +## .Prev PAGE + - `.Prev` points **down** to the previous page relative to the page sent in as the argument. Example: `{{with .Site.RegularPages.Prev . }}{{.RelPermalink}}{{end}}`. Calling `.Prev` with the last page in the collection returns `nil`. ++`.Prev` points **down** to the previous page relative to the page sent in as the argument. Example: `{{ with .Site.RegularPages.Prev . }}{{ .RelPermalink }}{{ end }}`. Calling `.Prev` with the last page in the collection returns `nil`. diff --cc docs/content/en/variables/shortcodes.md index a7c9e475b,000000000..3d4185b45 mode 100644,000000..100644 --- a/docs/content/en/variables/shortcodes.md +++ b/docs/content/en/variables/shortcodes.md @@@ -1,47 -1,0 +1,45 @@@ +--- +title: Shortcode Variables - linktitle: Shortcode Variables +description: Shortcodes can access page variables and also have their own specific built-in variables. - date: 2017-03-12 - publishdate: 2017-03-12 +categories: [variables and params] +keywords: [shortcodes] +menu: + docs: - parent: "variables" ++ parent: variables + weight: 20 +weight: 20 - sections_weight: 20 - aliases: [] - toc: false +--- + +[Shortcodes][shortcodes] have access to parameters delimited in the shortcode declaration via [`.Get`][getfunction], page- and site-level variables, and also the following shortcode-specific fields: + +.Name +: Shortcode name. + +.Ordinal +: Zero-based ordinal in relation to its parent. If the parent is the page itself, this ordinal will represent the position of this shortcode in the page content. + +.Page +: The owning Â´Page`. + +.Parent +: provides access to the parent shortcode context in nested shortcodes. This can be very useful for inheritance of common shortcode parameters from the root. + +.Position +: Contains [filename and position](https://godoc.org/github.com/gohugoio/hugo/common/text#Position) for the shortcode in a page. Note that this can be relatively expensive to calculate, and is meant for error reporting. See [Error Handling in Shortcodes](/templates/shortcode-templates/#error-handling-in-shortcodes). + +.IsNamedParams +: boolean that returns `true` when the shortcode in question uses [named rather than positional parameters][shortcodes] + +.Inner +: represents the content between the opening and closing shortcode tags when a [closing shortcode][markdownshortcode] is used + - [getfunction]: /functions/get/ - [markdownshortcode]: /content-management/shortcodes/#shortcodes-with-markdown - [shortcodes]: /templates/shortcode-templates/ ++.Scratch ++: returns a writable [`Scratch`][scratch] to store and manipulate data which will be attached to the shortcode context. This scratch is reset on server rebuilds. + +.InnerDeindent {{< new-in "0.100.0" >}} +: Gets the `.Inner` with any indentation removed. This is what's used in the built-in `{{}}` shortcode. ++ ++[getfunction]: /functions/get/ ++[markdownshortcode]: /content-management/shortcodes/#shortcodes-with-markdown ++[shortcodes]: /templates/shortcode-templates/ ++[scratch]: /functions/scratch diff --cc docs/content/en/variables/site.md index 34239ad44,000000000..71111eb83 mode 100644,000000..100644 --- a/docs/content/en/variables/site.md +++ b/docs/content/en/variables/site.md @@@ -1,129 -1,0 +1,123 @@@ +--- +title: Site Variables - linktitle: Site Variables +description: Many, but not all, site-wide variables are defined in your site's configuration. However, Hugo provides a number of built-in variables for convenient access to global values in your templates. - date: 2017-02-01 - publishdate: 2017-02-01 - lastmod: 2017-02-01 +categories: [variables and params] +keywords: [global,site] - draft: false +menu: + docs: - parent: "variables" ++ parent: variables + weight: 10 +weight: 10 - sections_weight: 10 +aliases: [/variables/site-variables/] +toc: true +--- + +The following is a list of site-level (aka "global") variables. Many of these variables are defined in your site's [configuration file][config], whereas others are built into Hugo's core for convenient usage in your templates. + +## Get the Site object from a partial + +All the methods below, e.g. `.Site.RegularPages` can also be reached via the global [`site`](/functions/site/) function, e.g. `site.RegularPages`, which can be handy in partials where the `Page` object isn't easily available. + +## Site Variables List + +.Site.AllPages +: array of all pages, regardless of their translation. + +.Site.BaseURL +: the base URL for the site as defined in the site configuration. + +.Site.BuildDrafts +: a boolean (default: `false`) to indicate whether to build drafts as defined in the site configuration. + +.Site.Copyright +: a string representing the copyright of your website as defined in the site configuration. + +.Site.Data +: custom data, see [Data Templates](/templates/data-templates/). + +.Site.DisqusShortname +: a string representing the shortname of the Disqus shortcode as defined in the site configuration. + +.Site.GoogleAnalytics +: a string representing your tracking code for Google Analytics as defined in the site configuration. + +.Site.Home +: reference to the homepage's [page object](https://gohugo.io/variables/page/) + +.Site.IsMultiLingual +: whether there are more than one language in this site. See [Multilingual](/content-management/multilingual/) for more information. + +.Site.IsServer +: a boolean to indicate if the site is being served with Hugo's built-in server. See [`hugo server`](/commands/hugo_server/) for more information. + +.Site.Language.Lang +: the language code of the current locale (e.g., `en`). + +.Site.Language.LanguageName +: the full language name (e.g. `English`). + +.Site.Language.Weight +: the weight that defines the order in the `.Site.Languages` list. + +.Site.Language +: indicates the language currently being used to render the website. This object's attributes are set in site configurations' language definition. + +.Site.LanguageCode +: a string representing the language tag as defined in the site configuration. + +.Site.LanguagePrefix +: this can be used to prefix URLs to point to the correct language. It will even work when only one defined language. See also the functions [absLangURL](/functions/abslangurl/) and [relLangURL](/functions/rellangurl). + +.Site.Languages +: an ordered list (ordered by defined weight) of languages. + +.Site.LastChange +: a string representing the date/time of the most recent change to your site. This string is based on the [`date` variable in the front matter](/content-management/front-matter) of your content pages. + +.Site.Menus +: all the menus in the site. + +.Site.Pages - : array of all content ordered by Date with the newest first. This array contains only the pages in the current language. See [`.Site.Pages`]({{< relref "site.md#site-pages" >}}). ++: array of all content ordered by Date with the newest first. This array contains only the pages in the current language. See [`.Site.Pages`](#site-pages). + +.Site.RegularPages - : a shortcut to the *regular* page collection. `.Site.RegularPages` is equivalent to `where .Site.Pages "Kind" "page"`. See [`.Site.Pages`]({{< relref "site.md#site-pages" >}}). ++: a shortcut to the *regular* page collection. `.Site.RegularPages` is equivalent to `where .Site.Pages "Kind" "page"`. See [`.Site.Pages`](#site-pages). + +.Site.Sections +: top-level directories of the site. + +.Site.Taxonomies - : the [taxonomies](/taxonomies/usage/) for the entire site. Also see section [Use `.Site.Taxonomies` Outside of Taxonomy Templates](/variables/taxonomy/#use-sitetaxonomies-outside-of-taxonomy-templates). ++: the [taxonomies](/content-management/taxonomies/) for the entire site. Also see section [Access taxonomy data from any template](/variables/taxonomy/#access-taxonomy-data-from-any-template). + +.Site.Title +: a string representing the title of the site. + +## The `.Site.Params` Variable + +`.Site.Params` is a container holding the values from the `params` section of your site configuration. + +### Example: `.Site.Params` + +The following `config.[yaml|toml|json]` defines a site-wide param for `description`: + +{{< code-toggle file="config" >}} +baseURL = "https://yoursite.example.com/" + +[params] + description = "Tesla's Awesome Hugo Site" + author = "Nikola Tesla" +{{}} + +You can use `.Site.Params` in a [partial template](/templates/partials/) to call the default site description: + +{{< code file="layouts/partials/head.html" >}} - ++ +{{< /code >}} + +## The `.Site.Pages` Variable {#site-pages} + +### `.Site.Pages` compared to `.Pages` + +{{< getcontent path="readfiles/pages-vs-site-pages.md" >}} + +[config]: /getting-started/configuration/ diff --cc docs/content/en/variables/sitemap.md index 24700182a,000000000..b0b080d00 mode 100644,000000..100644 --- a/docs/content/en/variables/sitemap.md +++ b/docs/content/en/variables/sitemap.md @@@ -1,31 -1,0 +1,25 @@@ +--- +title: Sitemap Variables +linktitle: Sitemap Variables +description: - date: 2017-03-12 - publishdate: 2017-03-12 +categories: [variables and params] +keywords: [sitemap] - draft: false +menu: + docs: - parent: "variables" ++ parent: variables + weight: 80 +weight: 80 - sections_weight: 80 - aliases: [] - toc: false +--- + +A sitemap is a `Page` and therefore has all the [page variables][pagevars] available to use sitemap templates. They also have the following sitemap-specific variables available to them: + +.Sitemap.ChangeFreq +: the page change frequency + +.Sitemap.Priority +: the priority of the page + +.Sitemap.Filename +: the sitemap filename + +[pagevars]: /variables/page/ diff --cc docs/content/en/variables/taxonomy.md index 901769b31,000000000..63b552328 mode 100644,000000..100644 --- a/docs/content/en/variables/taxonomy.md +++ b/docs/content/en/variables/taxonomy.md @@@ -1,140 -1,0 +1,138 @@@ +--- +title: Taxonomy Variables - linktitle: +description: Hugo's taxonomy system exposes variables to taxonomy and term templates. +categories: [variables and params] +keywords: [taxonomy,term] +menu: + docs: - parent: "variables" ++ parent: variables + weight: 30 +toc: true +weight: 30 - aliases: [] +--- + +## Taxonomy templates + +Pages rendered by taxonomy templates have `.Kind` set to `taxonomy` and `.Type` set to the taxonomy name. + +In taxonomy templates you may access `.Site`, `.Page`. `.Section`, and `.File` variables, as well as the following _taxonomy_ variables: + +.Data.Singular +: The singular name of the taxonomy (e.g., `tags => tag`). + +.Data.Plural +: The plural name of the taxonomy (e.g., `tags => tags`). + +.Data.Pages +: The collection of term pages related to this taxonomy. Aliased by `.Pages`. + +.Data.Terms +: A map of terms and weighted pages related to this taxonomy. + +.Data.Terms.Alphabetical +: A map of terms and weighted pages related to this taxonomy, sorted alphabetically in ascending order. Reverse the sort order with`.Data.Terms.Alphabetical.Reverse`. + +.Data.Terms.ByCount +: A map of terms and weighted pages related to this taxonomy, sorted by count in ascending order. Reverse the sort order with`.Data.Terms.ByCount.Reverse`. + +## Term templates + +Pages rendered by term templates have `.Kind` set to `term` and `.Type` set to the taxonomy name. + +In term templates you may access `.Site`, `.Page`. `.Section`, and `.File` variables, as well as the following _term_ variables: + +.Data.Singular +: The singular name of the taxonomy (e.g., `tags => tag`). + +.Data.Plural +: The plural name of the taxonomy (e.g., `tags => tags`). + +.Data.Pages +: The collection of content pages related to this taxonomy. Aliased by `.Pages`. + +.Data.Term +: The term itself (e.g., `tag-one`). + +## Access taxonomy data from any template + +Access the entire taxonomy data structure from any template with `site.Taxonomies`. This returns a map of taxonomies, terms, and a collection of weighted content pages related to each term. For example: + +```json +{ + "categories": { + "news": [ + { + "Weight": 0, + "Page": { + "Title": "Post 1", + "Date": "2022-12-18T15:13:35-08:00" + ... + } + }, + { + "Weight": 0, + "Page": { + "Title": "Post 2", + "Date": "2022-12-18T15:13:46-08:00", + ... + } + } + ] + }, + "tags": { + "international": [ + { + "Weight": 0, + "Page": { + "Title": "Post 1", + "Date": "2021-01-01T00:00:00Z" + ... + } + } + ] + } +} +``` + +Access a subset of the taxonomy data structure by chaining one or more identifiers, or by using the [`index`] function with one or more keys. For example, to access the collection of weighted content pages related to the news category, use either of the following: + +[`index`]: /functions/index-function/ + +```go-html-template +{{ $pages := site.Taxonomies.categories.news }} +{{ $pages := index site.Taxonomies "categories" "news" }} +``` + +For example, to render the entire taxonomy data structure as a nested unordered list: + +```go-html-template +

+ {{ with site.GetPage $taxonomy }} + {{ .LinkTitle }} + {{ end }} +
- + {{ with site.GetPage (path.Join $taxonomy $term) }} + {{ .LinkTitle }} + {{ end }} +
+

+``` + +See [Taxonomy Templates] for more examples. + +[Taxonomy Templates]: /templates/taxonomy-templates/ diff --cc docs/go.mod index 33f818ad6,000000000..07badfeaf 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-20230124135550-462d5fe4a87f // indirect ++require github.com/gohugoio/gohugoioTheme v0.0.0-20230418063032-99f9185b8e11 // indirect diff --cc docs/go.sum index ea0d2dcbe,000000000..6783cb92e mode 100644,000000..100644 --- a/docs/go.sum +++ b/docs/go.sum @@@ -1,61 -1,0 +1,65 @@@ +github.com/gohugoio/gohugoioTheme v0.0.0-20190808163145-07b3c0f73b02/go.mod h1:kpw3SS48xZvLQGEXKu8u5XHgXkPvL8DX3oGa07+z8Bs= +github.com/gohugoio/gohugoioTheme v0.0.0-20191014144142-1f3a01deed7b h1:PWNjl46fvtz54PKO0BdiXOF6/4L/uCP0F3gtcCxGrJs= +github.com/gohugoio/gohugoioTheme v0.0.0-20191014144142-1f3a01deed7b/go.mod h1:kpw3SS48xZvLQGEXKu8u5XHgXkPvL8DX3oGa07+z8Bs= +github.com/gohugoio/gohugoioTheme v0.0.0-20191021162625-2e7250ca437d h1:D3DcaYkuJbotdWNNAQpQl37txX4HQ6R5uMHoxVmTw0w= +github.com/gohugoio/gohugoioTheme v0.0.0-20191021162625-2e7250ca437d/go.mod h1:kpw3SS48xZvLQGEXKu8u5XHgXkPvL8DX3oGa07+z8Bs= +github.com/gohugoio/gohugoioTheme v0.0.0-20200123151337-9475fd449324 h1:UZwHDYtGY0uOKIvcm2LWd+xfFxD3X5L222LIJdI5RE4= +github.com/gohugoio/gohugoioTheme v0.0.0-20200123151337-9475fd449324/go.mod h1:kpw3SS48xZvLQGEXKu8u5XHgXkPvL8DX3oGa07+z8Bs= +github.com/gohugoio/gohugoioTheme v0.0.0-20200123204146-589b4c309025 h1:ScYFARz+bHX1rEr1donVknhRdxGY/cwqK1hHvWEfrlc= +github.com/gohugoio/gohugoioTheme v0.0.0-20200123204146-589b4c309025/go.mod h1:kpw3SS48xZvLQGEXKu8u5XHgXkPvL8DX3oGa07+z8Bs= +github.com/gohugoio/gohugoioTheme v0.0.0-20200123205007-5d6620a0db26 h1:acXfduibbWxji9tW0WkLHbjcXFsnd5uIwXe0WfwOazg= +github.com/gohugoio/gohugoioTheme v0.0.0-20200123205007-5d6620a0db26/go.mod h1:kpw3SS48xZvLQGEXKu8u5XHgXkPvL8DX3oGa07+z8Bs= +github.com/gohugoio/gohugoioTheme v0.0.0-20200128164921-1d0bc5482051 h1:cS14MnUGS6xwWYfPNshimm8HdMCZiYBxWkCD0VnvgVw= +github.com/gohugoio/gohugoioTheme v0.0.0-20200128164921-1d0bc5482051/go.mod h1:kpw3SS48xZvLQGEXKu8u5XHgXkPvL8DX3oGa07+z8Bs= +github.com/gohugoio/gohugoioTheme v0.0.0-20200327225449-368f4cbef8d7 h1:cZ+ahAjSetbFv3aDJ9ipDbKyqaVlmkbSZ5cULgBTh+w= +github.com/gohugoio/gohugoioTheme v0.0.0-20200327225449-368f4cbef8d7/go.mod h1:kpw3SS48xZvLQGEXKu8u5XHgXkPvL8DX3oGa07+z8Bs= +github.com/gohugoio/gohugoioTheme v0.0.0-20200327231942-7f80b3d02bfa h1:kG+O/wT9UXomzp5eQiUuFVZ0l7YylAW6EVPLyjMxi/c= +github.com/gohugoio/gohugoioTheme v0.0.0-20200327231942-7f80b3d02bfa/go.mod h1:kpw3SS48xZvLQGEXKu8u5XHgXkPvL8DX3oGa07+z8Bs= +github.com/gohugoio/gohugoioTheme v0.0.0-20200328100657-2bfd5f8c6aee h1:PJZhCwnuVLyafDWNPSHk9iJvk6gEIvPRnycy7Pq3peA= +github.com/gohugoio/gohugoioTheme v0.0.0-20200328100657-2bfd5f8c6aee/go.mod h1:kpw3SS48xZvLQGEXKu8u5XHgXkPvL8DX3oGa07+z8Bs= +github.com/gohugoio/gohugoioTheme v0.0.0-20200518164958-62cbad03c40f h1:Ge3JACszSUyJW2Az9cJzWdo4PUqdijJA1RxoQSVMBSI= +github.com/gohugoio/gohugoioTheme v0.0.0-20200518164958-62cbad03c40f/go.mod h1:kpw3SS48xZvLQGEXKu8u5XHgXkPvL8DX3oGa07+z8Bs= +github.com/gohugoio/gohugoioTheme v0.0.0-20200518165806-0095b7b902a7 h1:Sy0hlWyZmFtdSY0Cobvw1ZYm3G1aR5+4DuFNRbMkh48= +github.com/gohugoio/gohugoioTheme v0.0.0-20200518165806-0095b7b902a7/go.mod h1:kpw3SS48xZvLQGEXKu8u5XHgXkPvL8DX3oGa07+z8Bs= +github.com/gohugoio/gohugoioTheme v0.0.0-20200711112515-b0dfe471654f h1:BWJyycs4HD7tUbaU8RIGeMay84bIBWRVVLE3yajPas4= +github.com/gohugoio/gohugoioTheme v0.0.0-20200711112515-b0dfe471654f/go.mod h1:kpw3SS48xZvLQGEXKu8u5XHgXkPvL8DX3oGa07+z8Bs= +github.com/gohugoio/gohugoioTheme v0.0.0-20210301124928-2c15837dfec3 h1:ShqzOFeeg54FPSuS6q8HSeTVgj2xNZRe/YS0jNbi21g= +github.com/gohugoio/gohugoioTheme v0.0.0-20210301124928-2c15837dfec3/go.mod h1:kpw3SS48xZvLQGEXKu8u5XHgXkPvL8DX3oGa07+z8Bs= +github.com/gohugoio/gohugoioTheme v0.0.0-20210409065807-6383d8cbaf65 h1:EJzierSWKqwsrUXU6MaFe0J97c0e5pzl5dBNRRrV2Nc= +github.com/gohugoio/gohugoioTheme v0.0.0-20210409065807-6383d8cbaf65/go.mod h1:kpw3SS48xZvLQGEXKu8u5XHgXkPvL8DX3oGa07+z8Bs= +github.com/gohugoio/gohugoioTheme v0.0.0-20210409071416-c88da48134b7 h1:uRCgPslaBgLYy4ANXBoPbBQVM8aNiHoxIZTKUXpkuUA= +github.com/gohugoio/gohugoioTheme v0.0.0-20210409071416-c88da48134b7/go.mod h1:kpw3SS48xZvLQGEXKu8u5XHgXkPvL8DX3oGa07+z8Bs= +github.com/gohugoio/gohugoioTheme v0.0.0-20211211125852-b85e21c1f3d6 h1:lAgdWrn8VEg0PrNCPX4DflCg2msDKpSYV6E8RTNV3N0= +github.com/gohugoio/gohugoioTheme v0.0.0-20211211125852-b85e21c1f3d6/go.mod h1:kpw3SS48xZvLQGEXKu8u5XHgXkPvL8DX3oGa07+z8Bs= +github.com/gohugoio/gohugoioTheme v0.0.0-20220228085601-7cfbda06d135 h1:6hVzfE9YhSsZP5t6jWjvVp7MoPm7Y5fEhH/ls4ahhKk= +github.com/gohugoio/gohugoioTheme v0.0.0-20220228085601-7cfbda06d135/go.mod h1:kpw3SS48xZvLQGEXKu8u5XHgXkPvL8DX3oGa07+z8Bs= +github.com/gohugoio/gohugoioTheme v0.0.0-20220905093719-cb8b64046950 h1:Ovlh3nuy/aNptYZHmIra2MP+ZUEqiihY0HxvhdaMqGg= +github.com/gohugoio/gohugoioTheme v0.0.0-20220905093719-cb8b64046950/go.mod h1:kpw3SS48xZvLQGEXKu8u5XHgXkPvL8DX3oGa07+z8Bs= +github.com/gohugoio/gohugoioTheme v0.0.0-20220912070954-88dcaf003b4d h1:UYJL6RmEepprvlgHvDnFCWtPOvjmqzFCQ90cRDRBO7U= +github.com/gohugoio/gohugoioTheme v0.0.0-20220912070954-88dcaf003b4d/go.mod h1:kpw3SS48xZvLQGEXKu8u5XHgXkPvL8DX3oGa07+z8Bs= +github.com/gohugoio/gohugoioTheme v0.0.0-20220914071648-0ef1c51685bf h1:A8Ksnvp8reNt2Ap0mUK7gFkJkCjt9R60yopGsezcOBA= +github.com/gohugoio/gohugoioTheme v0.0.0-20220914071648-0ef1c51685bf/go.mod h1:kpw3SS48xZvLQGEXKu8u5XHgXkPvL8DX3oGa07+z8Bs= +github.com/gohugoio/gohugoioTheme v0.0.0-20221116211530-5ae8dcdd68d6 h1:eG53kL1LkQuKmrDdzbvvx6d60qM07zp2Wjo/tYxkDOY= +github.com/gohugoio/gohugoioTheme v0.0.0-20221116211530-5ae8dcdd68d6/go.mod h1:kpw3SS48xZvLQGEXKu8u5XHgXkPvL8DX3oGa07+z8Bs= +github.com/gohugoio/gohugoioTheme v0.0.0-20221118083537-967e29e21382 h1:e30rl1dxWkYOcgdl0omeOK0HBzgDLI/b9MfYHrINjzU= +github.com/gohugoio/gohugoioTheme v0.0.0-20221118083537-967e29e21382/go.mod h1:kpw3SS48xZvLQGEXKu8u5XHgXkPvL8DX3oGa07+z8Bs= +github.com/gohugoio/gohugoioTheme v0.0.0-20221124154621-1451a01f406b h1:TRrIisSY7ckt9FVHOOQtmKG4jsnORCYn72UMvMu+IQ0= +github.com/gohugoio/gohugoioTheme v0.0.0-20221124154621-1451a01f406b/go.mod h1:kpw3SS48xZvLQGEXKu8u5XHgXkPvL8DX3oGa07+z8Bs= +github.com/gohugoio/gohugoioTheme v0.0.0-20221206093948-1408550ab675 h1:wjpYa1cTELeceWndBDV7IG2vRxRWICBBO79HObOfTtk= +github.com/gohugoio/gohugoioTheme v0.0.0-20221206093948-1408550ab675/go.mod h1:kpw3SS48xZvLQGEXKu8u5XHgXkPvL8DX3oGa07+z8Bs= +github.com/gohugoio/gohugoioTheme v0.0.0-20221217122332-1c1752ad8f14 h1:K6tPFpi7W0zb89QIf+lNdgdTXfDFemU6NKk46MlX9lQ= +github.com/gohugoio/gohugoioTheme v0.0.0-20221217122332-1c1752ad8f14/go.mod h1:kpw3SS48xZvLQGEXKu8u5XHgXkPvL8DX3oGa07+z8Bs= +github.com/gohugoio/gohugoioTheme v0.0.0-20221220160735-8ffa1ef883b6 h1:yEoQecRBoLGfc7yTybMD3Mhm03bTScZFYPvwe0p75vA= +github.com/gohugoio/gohugoioTheme v0.0.0-20221220160735-8ffa1ef883b6/go.mod h1:GOYeAPQJ/ok8z7oz1cjfcSlsFpXrmx6VkzQ5RpnyhZM= +github.com/gohugoio/gohugoioTheme v0.0.0-20230109120406-12694c4a9456 h1:RSLItaapVjWkqSdQhumAmJkodFDbWMGNZmkVW/AFx0c= +github.com/gohugoio/gohugoioTheme v0.0.0-20230109120406-12694c4a9456/go.mod h1:GOYeAPQJ/ok8z7oz1cjfcSlsFpXrmx6VkzQ5RpnyhZM= +github.com/gohugoio/gohugoioTheme v0.0.0-20230119103504-3bcd960d6f1b h1:i/iaEOOuR1mKRR0qUOET587ooVhG8c2tllpA5HsrWNU= +github.com/gohugoio/gohugoioTheme v0.0.0-20230119103504-3bcd960d6f1b/go.mod h1:GOYeAPQJ/ok8z7oz1cjfcSlsFpXrmx6VkzQ5RpnyhZM= +github.com/gohugoio/gohugoioTheme v0.0.0-20230120185049-2c3c4d0ba232 h1:bEojKgKInbsLkID5Arh95vP4+0xydtn/+ayT6I8vkiU= +github.com/gohugoio/gohugoioTheme v0.0.0-20230120185049-2c3c4d0ba232/go.mod h1:GOYeAPQJ/ok8z7oz1cjfcSlsFpXrmx6VkzQ5RpnyhZM= +github.com/gohugoio/gohugoioTheme v0.0.0-20230124135550-462d5fe4a87f h1:8wI3zOTWQG15aKkbAZQaoGnUQff46hO95opQndBHRE4= +github.com/gohugoio/gohugoioTheme v0.0.0-20230124135550-462d5fe4a87f/go.mod h1:GOYeAPQJ/ok8z7oz1cjfcSlsFpXrmx6VkzQ5RpnyhZM= ++github.com/gohugoio/gohugoioTheme v0.0.0-20230330081257-7a8c9614432c h1:TyHgmowfiMyxKrqTdRxm/yWIFeN7XRh7Hm6/dOG6yDA= ++github.com/gohugoio/gohugoioTheme v0.0.0-20230330081257-7a8c9614432c/go.mod h1:GOYeAPQJ/ok8z7oz1cjfcSlsFpXrmx6VkzQ5RpnyhZM= ++github.com/gohugoio/gohugoioTheme v0.0.0-20230418063032-99f9185b8e11 h1:mDcricMewd66x8QjKqNun7Div7iYVLtl8s1dVs9VnB8= ++github.com/gohugoio/gohugoioTheme v0.0.0-20230418063032-99f9185b8e11/go.mod h1:GOYeAPQJ/ok8z7oz1cjfcSlsFpXrmx6VkzQ5RpnyhZM= diff --cc docs/hugo.toml index da6bd9534,000000000..5bed0ab2b mode 100644,000000..100644 --- a/docs/hugo.toml +++ b/docs/hugo.toml @@@ -1,87 -1,0 +1,97 @@@ +# This his the main configuration file. There are also environment specific configuration stored in the /config directory. + +baseURL = "https://gohugo.io/" +defaultContentLanguage = "en" +enableEmoji = true +googleAnalytics = "G-MBZGKNMDWC" +ignoreErrors = ["error-remote-getjson", "error-missing-instagram-accesstoken"] +languageCode = "en-us" +paginate = 100 +pluralizeListTitles = false +timeZone = "Europe/Oslo" +title = "Hugo" + +# We do redirects via Netlify's _redirects file, generated by Hugo (see "outputs" below). +disableAliases = true + +[minify] + [minify.tdewolff] + [minify.tdewolff.html] + keepWhitespace = true + +[module] + [module.hugoVersion] + min = "0.56.0" + [[module.imports]] + path = "github.com/gohugoio/gohugoioTheme" + +[outputs] + home = ["HTML", "RSS", "REDIR", "HEADERS"] + section = ["HTML", "RSS"] + +[mediaTypes] + [mediaTypes."text/netlify"] + delimiter = "" + +[outputFormats] + [outputFormats.REDIR] + mediatype = "text/netlify" + baseName = "_redirects" + isPlainText = true + notAlternative = true + [outputFormats.HEADERS] + mediatype = "text/netlify" + baseName = "_headers" + isPlainText = true + notAlternative = true + +[caches] + [caches.getjson] + dir = ":cacheDir/:project" + maxAge = -1 + [caches.getcsv] + dir = ":cacheDir/:project" + maxAge = -1 + [caches.images] + dir = ":cacheDir/images" + maxAge = "1440h" + [caches.assets] + dir = ":resourceDir/_gen" + maxAge = -1 + +[related] + threshold = 80 + includeNewer = true + toLower = false + [[related.indices]] + name = "keywords" - weight = 100 ++ weight = 60 ++ [[related.indices]] ++ # Can be used as a front matter slice to link to other page fragments (headings) using their ID. ++ # This isn't particular useful in the current docs, but we're planning on getting a auto generated ++ # reference section with a better ID setup. ++ # For now, we just use it to give pages with same headings some similarity score. ++ name = "fragmentrefs" ++ type = "fragments" ++ applyFilter = false ++ weight = 60 ++ cardinalityThreshold = 50 + [[related.indices]] + name = "date" + weight = 10 + pattern = "2006" + +[social] + twitter = "GoHugoIO" + +[imaging] + # See https://github.com/disintegration/imaging + # CatmullRom is a sharp bicubic filter which should fit the docs site well with its many screenshots. + # Note that you can also set this per image processing. + resampleFilter = "CatmullRom" + # Default JPEG quality setting. Default is 75. + quality = 75 + anchor = "smart" + +[taxonomies] + category = "categories" diff --cc docs/layouts/shortcodes/code-toggle.html index 113d85a1f,000000000..b4cfaaa20 mode 100644,000000..100644 --- a/docs/layouts/shortcodes/code-toggle.html +++ b/docs/layouts/shortcodes/code-toggle.html @@@ -1,108 -1,0 +1,87 @@@ +{{- /* +Renders syntax-highlighted configuration data in JSON, TOML, and YAML formats. + - @param {string} config - Section of site.Data.docs.config to render. - Example: markup.highlight - Default: "" - @param {bool} copy - Display a copy button. - Default: true - @param {string} file - File name to display above the rendered code. - Default: "" - @param {bool} fm - Does Inner represent front matter? - Default: false - @param {string} Inner - Content between opening and closing shortcode tags. - Default: "" - @param {bool} skipHeader - Omit top level key(s) when rendering a section of site.Data.docs.config. - Default: false ++@param {string} [config] The section of site.Data.docs.config to render. ++@param {bool} [copy=true] If true, display a copy to clipboard button. ++@param {string} [file] The file name to display above the rendered code. ++@param {bool} [fm=false] If true, render the code as front matter. ++@param {bool} [skipHeader=false] If false, omit top level key(s) when rendering a section of site.Data.docs.config. ++ +@returns {template.HTML} - */ -}} ++*/}} + - {{- /* Initialize. */ -}} - {{- $config := "" -}} - {{- $copy := true -}} - {{- $file := "" -}} - {{- $fm := false -}} - {{- $skipHeader := false -}} ++{{- /* Initialize. */}} ++{{- $config := "" }} ++{{- $copy := true }} ++{{- $file := "" }} ++{{- $fm := false }} ++{{- $skipHeader := false }} + - {{- /* Get parameters, defend against string booleans. */ -}} - {{- if .Params -}} - {{- $config = .Get "config" -}} - {{- $file = .Get "file" -}} - {{- if (isset .Params "copy") -}} - {{- if in (slice true "true") (.Get "copy") -}} - {{- $copy = true -}} - {{- else -}} - {{- $copy = false -}} - {{- end -}} - {{- end -}} - {{- if (isset .Params "fm") -}} - {{- if in (slice true "true") (.Get "fm") -}} - {{- $fm = true -}} - {{- else -}} - {{- $fm = false -}} - {{- end -}} - {{- end -}} - {{- if (isset .Params "skipHeader") -}} - {{- if in (slice true "true") (.Get "skipHeader") -}} - {{- $skipHeader = true -}} - {{- else -}} - {{- $skipHeader = false -}} - {{- end -}} - {{- end -}} - {{- end -}} ++{{- /* Get parameters. */}} ++{{- $config = .Get "config" }} ++{{- $file = .Get "file" }} ++{{- if in (slice "false" false 0) (.Get "copy") }} ++ {{- $copy = false }} ++{{- else if in (slice "true" true 1) (.Get "copy")}} ++ {{- $copy = true }} ++{{- end }} ++{{- if in (slice "false" false 0) (.Get "fm") }} ++ {{- $fm = false }} ++{{- else if in (slice "true" true 1) (.Get "fm")}} ++ {{- $fm = true }} ++{{- end }} ++{{- if in (slice "false" false 0) (.Get "skipHeader") }} ++ {{- $skipHeader = false }} ++{{- else if in (slice "true" true 1) (.Get "skipHeader")}} ++ {{- $skipHeader = true }} ++{{- end }} + - {{- /* Define constants. */ -}} - {{- $delimiters := dict "toml" "+++" "yaml" "---" -}} - {{- $langs := slice "yaml" "toml" "json" -}} - {{- $placeHolder := "#-hugo-placeholder-#" -}} ++{{- /* Define constants. */}} ++{{- $delimiters := dict "toml" "+++" "yaml" "---" }} ++{{- $langs := slice "yaml" "toml" "json" }} ++{{- $placeHolder := "#-hugo-placeholder-#" }} + - {{- /* Render. */ -}} - {{- $code := "" -}} - {{- with $config -}} - {{- $file = $file | default "config" -}} - {{- $sections := (split . ".") -}} - {{- $configSection := index $.Site.Data.docs.config $sections -}} - {{- $code = dict $sections $configSection -}} - {{- if $skipHeader -}} - {{- $code = $configSection -}} - {{- end -}} - {{- else -}} - {{- $code = $.Inner -}} ++{{- /* Render. */}} ++{{- $code := "" }} ++{{- with $config }} ++ {{- $file = $file | default "config" }} ++ {{- $sections := (split . ".") }} ++ {{- $configSection := index $.Site.Data.docs.config $sections }} ++ {{- $code = dict $sections $configSection }} ++ {{- if $skipHeader }} ++ {{- $code = $configSection }} ++ {{- end }} ++{{- else }} ++ {{- $code = $.Inner }} +{{- end }} +

+ {{- with $file }} +

- {{- . -}}{{- if not $fm -}}.{{- end -}} ++ {{ . }}{{ if not $fm }}.{{ end }} +

- {{- end -}} ++ {{- end }} + {{- range $langs }} + + + {{- end }} +

+ {{- range $langs }} +

- {{- $hCode := $code | transform.Remarshal . -}} - {{- if and $fm (in (slice "toml" "yaml") .) -}} - {{- $hCode = printf "%s\n%s\n%s" $placeHolder $hCode $placeHolder -}} - {{- end -}} ++ {{- $hCode := $code | transform.Remarshal . }} ++ {{- if and $fm (in (slice "toml" "yaml") .) }} ++ {{- $hCode = printf "%s\n%s\n%s" $placeHolder $hCode $placeHolder }} ++ {{- end }} + {{- $hCode = $hCode | replaceRE `\n+` "\n" }} + {{ highlight $hCode . "" | replaceRE $placeHolder (index $delimiters .) | safeHTML }} +

+ {{- if $copy }} + - {{- /* Functionality located within filesaver.js The copy here is located in the css with .copy class so it can be replaced with JS on success */ -}} - {{- end -}} ++ {{- /* Functionality located within filesaver.js The copy here is located in the css with .copy class so it can be replaced with JS on success */}} ++ {{- end }} + {{- end }} +

diff --cc docs/layouts/shortcodes/code.html index 0ee25149d,000000000..31ca27596 mode 100644,000000..100644 --- a/docs/layouts/shortcodes/code.html +++ b/docs/layouts/shortcodes/code.html @@@ -1,26 -1,0 +1,39 @@@ - {{ $file := .Get "file" }} - {{ $codeLang := "" }} - {{ $suffix := findRE "(\\.[^.]+)$" $file 1 }} - {{ with $suffix }} - {{ $codeLang = (index . 0 | strings.TrimPrefix ".") }} - {{ end }} - {{ with .Get "codeLang" }}{{ $codeLang = . }}{{ end }} - {{ if eq $codeLang "html" }} - {{ $codeLang = "go-html-template" }} - {{ end }} -

- {{- with $file -}} -

- {{- end -}} ++{{- /* ++Renders syntax highlighted code. ++ ++@param {bool} [copy=true] If true, display a copy to clipboard button. ++@param {string} [file] The file name to display above the rendered code. ++@param {string} [lang] The code language of the inner content. ++ ++@returns {template.HTML} ++*/}} + - {{ if ne (.Get "copy") "false" }} - - {{/* Functionality located within filesaver.js The copy here is located in the css with .copy class so it can be replaced with JS on success */}} - {{ end }} -

- {{ $inner := trim .Inner "\n" | safeHTML }} - {{ if .Get "nocode" }}{{ $inner }}{{ else }}{{ with $codeLang }}{{ highlight $inner . "" }}{{ else }}

{{ $inner }}

{{ end }}{{ end }} -

++{{- /* Initialize. */}} ++{{- $copy := true }} ++{{- $file := " " }} ++{{- $lang := "" }} + ++{{- /* Get parameters. */}} ++{{- $file = .Get "file" }} ++{{- $lang = or (.Get "lang") (path.Ext $file | strings.TrimPrefix ".") "text" }} ++{{- if in (slice "false" false 0) (.Get "copy") }} ++ {{- $copy = false }} ++{{- else if in (slice "true" true 1) (.Get "copy")}} ++ {{- $copy = true }} ++{{- end }} ++ ++{{- /* Use the go-html-template Chroma lexer for HTML. */}} ++{{- if eq $lang "html" }} ++ {{- $lang = "go-html-template" }} ++{{- end }} ++ ++{{- /* Render. */}} ++

++ {{- if $copy }} ++ ++ {{- end }} ++

++ {{- highlight (trim .Inner "\n\r") $lang }} ++

diff --cc docs/netlify.toml index d99f6d223,000000000..a07e29a94 mode 100644,000000..100644 --- a/docs/netlify.toml +++ b/docs/netlify.toml @@@ -1,35 -1,0 +1,35 @@@ +[build] +publish = "public" +command = "hugo --gc --minify" + +[context.production.environment] - HUGO_VERSION = "0.110.0" ++HUGO_VERSION = "0.111.3" +HUGO_ENV = "production" +HUGO_ENABLEGITINFO = "true" + +[context.split1] +command = "hugo --gc --minify --enableGitInfo" + +[context.split1.environment] - HUGO_VERSION = "0.110.0" ++HUGO_VERSION = "0.111.3" +HUGO_ENV = "production" + +[context.deploy-preview] +command = "hugo --gc --minify --buildFuture -b $DEPLOY_PRIME_URL" + +[context.deploy-preview.environment] - HUGO_VERSION = "0.110.0" ++HUGO_VERSION = "0.111.3" + +[context.branch-deploy] +command = "hugo --gc --minify -b $DEPLOY_PRIME_URL" + +[context.branch-deploy.environment] - HUGO_VERSION = "0.110.0" ++HUGO_VERSION = "0.111.3" + +[context.next.environment] +HUGO_ENABLEGITINFO = "true" + +[[redirects]] +from = "/npmjs/*" +to = "/npmjs/" +status = 200

Hugo Sponsors

{{ i18n "translations" }}

Authors

{{ .Title }}

See Also

See Also

{{ .Get "title" }}

Steve Francia

Steve Francia

{{ .Title }}

{{ .Title }}

{{ .Title }}

{{ .Title }}

Buy this book

Buy this book

Buy this book