From: Bjørn Erik Pedersen Date: Mon, 16 Apr 2018 05:45:38 +0000 (+0200) Subject: Merge commit '047c4188dfc854f658d16f1e4a9501f9c97a31c7' X-Git-Tag: v0.39~6 X-Git-Url: http://git.maquefel.me/?a=commitdiff_plain;h=7c597c7d7;p=brevno-suite%2Fhugo Merge commit '047c4188dfc854f658d16f1e4a9501f9c97a31c7' --- 7c597c7d756652c3cd50f3b538559ef505d817b9 diff --cc docs/content/about/new-in-032/index.md index 41bd5893,00000000..b8ca6430 mode 100644,000000..100644 --- a/docs/content/about/new-in-032/index.md +++ b/docs/content/about/new-in-032/index.md @@@ -1,209 -1,0 +1,209 @@@ +--- +title: Hugo 0.32 HOWTO +description: About page bundles, image processing and more. +date: 2017-12-28 +keywords: [ssg,static,performance,security] +menu: + docs: + parent: "about" + weight: 10 +weight: 10 +sections_weight: 10 +draft: false +aliases: [] +toc: true +images: +- images/blog/sunset.jpg +--- + + +{{% note %}} +This documentation belongs in other places in this documentation site, but is put here first ... to get something up and running fast. +{{% /note %}} + + +Also see this demo project from [bep](https://github.com/bep/), the clever Norwegian behind these new features: + +* http://hugotest.bep.is/ +* https://github.com/bep/hugotest (source) + +## Page Resources + +### Organize Your Content + +{{< figure src="/images/hugo-content-bundles.png" title="Pages with image resources" >}} + +The content folder above shows a mix of content pages (`md` (i.e. markdown) files) and image resources. + +{{% note %}} +You can use any file type as a content resource as long as it is a MIME type recognized by Hugo (`json` files will, as one example, work fine). If you want to get exotic, you can define your [own media type](/templates/output-formats/#media-types). +{{% /note %}} + +The 3 page bundles marked in red explained from top to bottom: + +1. The home page with one image resource (`1-logo.png`) +2. The blog section with two images resources and two pages resources (`content1.md`, `content2.md`). Note that the `_index.md` represents the URL for this section. +3. An article (`hugo-is-cool`) with a folder with some images and one content resource (`cats-info.md`). Note that the `index.md` represents the URL for this article. + +The content files below `blog/posts` are just regular standalone pages. + +{{% note %}} +Note that changes to any resource inside the `content` folder will trigger a reload when running in watch (aka server or live reload mode), it will even work with `--navigateToChanged`. +{{% /note %}} + +#### Sort Order + +* Pages are sorted according to standard Hugo page sorting rules. +* Images and other resources are sorted in lexicographical order. + +### Handle Page Resources in Templates + + +#### List all Resources + - ```html ++```go-html-template +{{ range .Resources }} +
  • {{ .ResourceType | title }}
    • +{{ end }} +``` + +For an absolute URL, use `.Permalink`. + +**Note:** The permalink will be relative to the content page, respecting permalink settings. Also, included page resources will not have a value for `RelPermalink`. + +#### List All Resources by Type + - ```html ++```go-html-template +{{ with .Resources.ByType "image" }} +{{ end }} + +``` + +Type here is `page` for pages, else the main type in the MIME type, so `image`, `json` etc. + +#### Get a Specific Resource + - ```html ++```go-html-template +{{ $logo := .Resources.GetByPrefix "logo" }} +{{ with $logo }} +{{ end }} +``` + +#### Include Page Resource Content + - ```html ++```go-html-template +{{ with .Resources.ByType "page" }} +{{ range . }} +

    {{ .Title }}

    +{{ .Content }} +{{ end }} +{{ end }} + +``` + + +## Image Processing + +The `image` resource implements the methods `Resize`, `Fit` and `Fill`: + +Resize +: Resize to the given dimension, `{{ $logo.Resize "200x" }}` will resize to 200 pixels wide and preserve the aspect ratio. Use `{{ $logo.Resize "200x100" }}` to control both height and width. + +Fit +: Scale down the image to fit the given dimensions, e.g. `{{ $logo.Fit "200x100" }}` will fit the image inside a box that is 200 pixels wide and 100 pixels high. + +Fill +: Resize and crop the image given dimensions, e.g. `{{ $logo.Fill "200x100" }}` will resize and crop to width 200 and height 100 + + +{{% note %}} +Image operations in Hugo currently **do not preserve EXIF data** as this is not supported by Go's [image package](https://github.com/golang/go/search?q=exif&type=Issues&utf8=%E2%9C%93). This will be improved on in the future. +{{% /note %}} + + +### Image Processing Examples + +_The photo of the sunset used in the examples below is Copyright [Bjørn Erik Pedersen](https://commons.wikimedia.org/wiki/User:Bep) (Creative Commons Attribution-Share Alike 4.0 International license)_ + + +{{< imgproc sunset Resize "300x" />}} + +{{< imgproc sunset Fill "90x120 left" />}} + +{{< imgproc sunset Fill "90x120 right" />}} + +{{< imgproc sunset Fit "90x90" />}} + +{{< imgproc sunset Resize "300x q10" />}} + + +This is the shortcode used in the examples above: + + +{{< code file="layouts/shortcodes/imgproc.html" >}} +{{< readfile file="layouts/shortcodes/imgproc.html" >}} +{{< /code >}} + +And it is used like this: + - ```html ++```go-html-template +{{}} +``` + +### Image Processing Options + +In addition to the dimensions (e.g. `200x100`) where either height or width can be omitted, Hugo supports a set of additional image options: + +Anchor +: Only relevant for `Fill`. This is useful for thumbnail generation where the main motive is located in, say, the left corner. Valid are `Center`, `TopLeft`, `Top`, `TopRight`, `Left`, `Right`, `BottomLeft`, `Bottom`, `BottomRight`. Example: `{{ $logo.Fill "200x100 BottomLeft" }}` + +JPEG Quality +: Only relevant for JPEG images, values 1 to 100 inclusive, higher is better. Default is 75. `{{ $logo.Resize "200x q50" }}` + +Rotate +: Rotates an image by the given angle counter-clockwise. The rotation will be performed first to get the dimensions correct. `{{ $logo.Resize "200x r90" }}`. The main use of this is to be able to manually correct for [EXIF orientation](https://github.com/golang/go/issues/4341) of JPEG images. + +Resample Filter +: Filter used in resizing. Default is `Box`, a simple and fast resampling filter appropriate for downscaling. See https://github.com/disintegration/imaging for more. If you want to trade quality for faster processing, this may be a option to test. + + + +### Performance + +Processed images are stored below `/resources` (can be set with `resourceDir` config setting). This folder is deliberately placed in the project, as it is recommended to check these into source control as part of the project. These images are not "Hugo fast" to generate, but once generated they can be reused. + +If you change your image settings (e.g. size), remove or rename images etc., you will end up with unused images taking up space and cluttering your project. + +To clean up, run: + +```bash +hugo --gc +``` + + +{{% note %}} +**GC** is short for **Garbage Collection**. +{{% /note %}} + + +## Configuration + +### Default Image Processing Config + +You can configure an `imaging` section in `config.toml` with default image processing options: + +```toml +[imaging] +# Default resample filter used for resizing. Default is Box, +# a simple and fast averaging filter appropriate for downscaling. +# See https://github.com/disintegration/imaging +resampleFilter = "box" + +# Defatult JPEG quality setting. Default is 75. +quality = 68 +``` + + + + + diff --cc docs/content/content-management/comments.md index 355bf004,00000000..20932a82 mode 100644,000000..100644 --- a/docs/content/content-management/comments.md +++ b/docs/content/content-management/comments.md @@@ -1,84 -1,0 +1,80 @@@ +--- +title: Comments +linktitle: Comments +description: Hugo ships with an internal Disqus template, but this isn't the only commenting system that will work with your new Hugo website. +date: 2017-02-01 +publishdate: 2017-02-01 +lastmod: 2017-03-09 +keywords: [sections,content,organization] +categories: [project organization, fundamentals] +menu: + docs: + parent: "content-management" + weight: 140 +weight: 140 #rem +draft: false +aliases: [/extras/comments/] +toc: true +--- + +Hugo ships with support for [Disqus](https://disqus.com/), a third-party service that provides comment and community capabilities to websites via JavaScript. + +Your theme may already support Disqus, but if not, it is easy to add to your templates via [Hugo's built-in Disqus partial][disquspartial]. + +## Add Disqus + +Hugo comes with all the code you need to load Disqus into your templates. Before adding Disqus to your site, you'll need to [set up an account][disqussetup]. + +### Configure Disqus + - Disqus comments require you set a single value in your [site's configuration file][configuration]. The following show the configuration variable in a `config.toml` and `config.yml`, respectively: ++Disqus comments require you set a single value in your [site's configuration file][configuration] like so: + - ``` ++{{< code-toggle copy="false" >}} +disqusShortname = "yourdiscussshortname" - ``` - - ``` - disqusShortname: "yourdiscussshortname" - ``` ++{{}} + +For many websites, this is enough configuration. However, you also have the option to set the following in the [front matter][] of a single content file: + +* `disqus_identifier` +* `disqus_title` +* `disqus_url` + +### Render Hugo's Built-in Disqus Partial Template + +See [Partial Templates][partials] to learn how to add the Disqus partial to your Hugo website's templates. + +## Comments Alternatives + +There are a few alternatives to commenting on static sites for those who do not want to use Disqus: + +* [Static Man](https://staticman.net/) +* [txtpen](https://txtpen.com) +* [IntenseDebate](http://intensedebate.com/) +* [Graph Comment][] +* [Muut](http://muut.com/) +* [isso](http://posativ.org/isso/) (Self-hosted, Python) + * [Tutorial on Implementing Isso with Hugo][issotutorial] + + + + + + + +[configuration]: /getting-started/configuration/ +[disquspartial]: /templates/partials/#disqus +[disqussetup]: https://disqus.com/profile/signup/ +[forum]: https://discourse.gohugo.io +[front matter]: /content-management/front-matter/ +[Graph Comment]: https://graphcomment.com/ +[kaijuissue]: https://github.com/spf13/kaiju/issues/new +[issotutorial]: https://stiobhart.net/2017-02-24-isso-comments/ +[partials]: /templates/partials/ +[MongoDB]: https://www.mongodb.com/ +[tweet]: https://twitter.com/spf13 diff --cc docs/content/content-management/front-matter.md index a6a3f240,00000000..2fc18ee3 mode 100644,000000..100644 --- a/docs/content/content-management/front-matter.md +++ b/docs/content/content-management/front-matter.md @@@ -1,206 -1,0 +1,174 @@@ +--- +title: Front Matter +linktitle: +description: Hugo allows you to add front matter in yaml, toml, or json to your content files. +date: 2017-01-09 +publishdate: 2017-01-09 +lastmod: 2017-02-24 +categories: [content management] +keywords: ["front matter", "yaml", "toml", "json", "metadata", "archetypes"] +menu: + docs: + parent: "content-management" + weight: 30 +weight: 30 #rem +draft: false +aliases: [/content/front-matter/] +toc: true +--- + +**Front matter** allows you to keep metadata attached to an instance of a [content type][]---i.e., embedded inside a content file---and is one of the many features that gives Hugo its strength. + +{{< youtube Yh2xKRJGff4 >}} + +## Front Matter Formats + +Hugo supports three formats for front matter, each with their own identifying tokens. + +TOML +: identified by opening and closing `+++`. + +YAML +: identified by opening and closing `---`. + +JSON +: a single JSON object surrounded by '`{`' and '`}`', followed by a new line. + - ### TOML Example ++### Example + - ``` ++{{< code-toggle >}} ++++ +title = "spf13-vim 3.0 release and new website" +description = "spf13-vim is a cross platform distribution of vim plugins and resources for Vim." +tags = [ ".vimrc", "plugins", "spf13-vim", "vim" ] +date = "2012-04-06" +categories = [ + "Development", + "VIM" +] +slug = "spf13-vim-3-0-release-and-new-website" ++++ - ``` - - ### YAML Example - - ``` - --- - title: "spf13-vim 3.0 release and new website" - description: "spf13-vim is a cross platform distribution of vim plugins and resources for Vim." - tags: [ ".vimrc", "plugins", "spf13-vim", "vim" ] - lastmod: 2015-12-23 - date: "2012-04-06" - categories: - - "Development" - - "VIM" - slug: "spf13-vim-3-0-release-and-new-website" - --- - ``` - - ### JSON Example - - ``` - { - "title": "spf13-vim 3.0 release and new website", - "description": "spf13-vim is a cross platform distribution of vim plugins and resources for Vim.", - "tags": [ ".vimrc", "plugins", "spf13-vim", "vim" ], - "date": "2012-04-06", - "categories": [ - "Development", - "VIM" - ], - "slug": "spf13-vim-3-0-release-and-new-website" - } - ``` ++{{}} + +## Front Matter Variables + +### Predefined + +There are a few predefined variables that Hugo is aware of. See [Page Variables][pagevars] for how to call many of these predefined variables in your templates. + +`aliases` +: an array of one or more aliases (e.g., old published paths of renamed content) that will be created in the output directory structure . See [Aliases][aliases] for details. + +`date` +: the datetime at which the content was created; note this value is auto-populated according to Hugo's built-in [archetype][]. + +`description` +: the description for the content. + +`draft` +: if `true`, the content will not be rendered unless the `--buildDrafts` flag is passed to the `hugo` command. + +`expiryDate` +: the datetime at which the content should no longer be published by Hugo; expired content will not be rendered unless the `--buildExpired` flag is passed to the `hugo` command. + +`headless` +: if `true`, sets a leaf bundle to be [headless][headless-bundle]. + +`isCJKLanguage` +: if `true`, Hugo will explicitly treat the content as a CJK language; both `.Summary` and `.WordCount` work properly in CJK languages. + +`keywords` +: the meta keywords for the content. + +`layout` +: the layout Hugo should select from the [lookup order][lookup] when rendering the content. If a `type` is not specified in the front matter, Hugo will look for the layout of the same name in the layout directory that corresponds with a content's section. See ["Defining a Content Type"][definetype] + +`lastmod` +: the datetime at which the content was last modified. + +`linkTitle` +: used for creating links to content; if set, Hugo defaults to using the `linktitle` before the `title`. Hugo can also [order lists of content by `linktitle`][bylinktitle]. + +`markup` +: **experimental**; specify `"rst"` for reStructuredText (requires`rst2html`) or `"md"` (default) for Markdown. + +`outputs` +: allows you to specify output formats specific to the content. See [output formats][outputs]. + +`publishDate` +: if in the future, content will not be rendered unless the `--buildFuture` flag is passed to `hugo`. + +`resources` +: used for configuring page bundle resources. See [Page Resources][page-resources]. + +`slug` +: appears as the tail of the output URL. A value specified in front matter will override the segment of the URL based on the filename. + +`taxonomies` +: these will use the field name of the plural form of the index; see the `tags` and `categories` in the above front matter examples. + +`title` +: the title for the content. + +`type` +: the type of the content; this value will be automatically derived from the directory (i.e., the [section][]) if not specified in front matter. + +`url` +: the full path to the content from the web root. It makes no assumptions about the path of the content file. It also ignores any language prefixes of +the multilingual feature. + +`weight` +: used for [ordering your content in lists][ordering]. + +{{% note "Hugo's Default URL Destinations" %}} +If neither `slug` nor `url` is present and [permalinks are not configured otherwise in your site `config` file](/content-management/urls/#permalinks), Hugo will use the filename of your content to create the output URL. See [Content Organization](/content-management/organization) for an explanation of paths in Hugo and [URL Management](/content-management/urls/) for ways to customize Hugo's default behaviors. +{{% /note %}} + +### User-Defined + +You can add fields to your front matter arbitrarily to meet your needs. These user-defined key-values are placed into a single `.Params` variable for use in your templates. + +The following fields can be accessed via `.Params.include_toc` and `.Params.show_comments`, respectively. The [Variables][] section provides more information on using Hugo's page- and site-level variables in your templates. + +``` +include_toc: true +show_comments: false +``` + + +## Order Content Through Front Matter + +You can assign content-specific `weight` in the front matter of your content. These values are especially useful for [ordering][ordering] in list views. You can use `weight` for ordering of content and the convention of [`_weight`][taxweight] for ordering content within a taxonomy. See [Ordering and Grouping Hugo Lists][lists] to see how `weight` can be used to organize your content in list views. + +## Override Global Markdown Configuration + +It's possible to set some options for Markdown rendering in a content's front matter as an override to the [BlackFriday rendering options set in your project configuration][config]. + +## Front Matter Format Specs + +* [TOML Spec][toml] +* [YAML Spec][yaml] +* [JSON Spec][json] + +[variables]: /variables/ +[aliases]: /content-management/urls/#aliases/ +[archetype]: /content-management/archetypes/ +[bylinktitle]: /templates/lists/#by-link-title +[config]: /getting-started/configuration/ "Hugo documentation for site configuration" +[content type]: /content-management/types/ +[contentorg]: /content-management/organization/ +[definetype]: /content-management/types/#defining-a-content-type "Learn how to specify a type and a layout in a content's front matter" +[headless-bundle]: /content-management/page-bundles/#headless-bundle +[json]: https://www.ecma-international.org/publications/files/ECMA-ST/ECMA-404.pdf "Specification for JSON, JavaScript Object Notation" +[lists]: /templates/lists/#ordering-content "See how to order content in list pages; for example, templates that look to specific _index.md for content and front matter." +[lookup]: /templates/lookup-order/ "Hugo traverses your templates in a specific order when rendering content to allow for DRYer templating." +[ordering]: /templates/lists/ "Hugo provides multiple ways to sort and order your content in list templates" +[outputs]: /templates/output-formats/ "With the release of v22, you can output your content to any text format using Hugo's familiar templating" +[page-resources]: /content-management/page-resources/ +[pagevars]: /variables/page/ +[section]: /content-management/sections/ +[taxweight]: /content-management/taxonomies/ +[toml]: https://github.com/toml-lang/toml "Specification for TOML, Tom's Obvious Minimal Language" +[urls]: /content-management/urls/ +[variables]: /variables/ +[yaml]: http://yaml.org/spec/ "Specification for YAML, YAML Ain't Markup Language" diff --cc docs/content/content-management/image-processing/index.md index 1f84ba04,00000000..ecc85bb5 mode 100644,000000..100644 --- a/docs/content/content-management/image-processing/index.md +++ b/docs/content/content-management/image-processing/index.md @@@ -1,195 -1,0 +1,195 @@@ +--- +title: "Image Processing" +description: "Image Page resources can be resized and cropped." +date: 2018-01-24T13:10:00-05:00 +lastmod: 2018-01-26T15:59:07-05:00 +linktitle: "Image Processing" +categories: ["content management"] +keywords: [bundle,content,resources,images] +weight: 4004 +draft: false +toc: true +menu: + docs: + parent: "content-management" + weight: 32 +--- + +## The Image Page Resource + +The `image` is a [Page Resource]({{< relref "content-management/page-resources" >}}), and the processing methods listed below does not work on images inside your `/static` folder. + + +To get all images in a [Page Bundle]({{< relref "content-management/organization#page-bundles" >}}): + + - ```html ++```go-html-template +{{ with .Resources.ByType "image" }} +{{ end }} + +``` + +## Image Processing Methods + + +The `image` resource implements the methods `Resize`, `Fit` and `Fill`, each returning the transformed image using the specified dimensions and processing options. + +Resize +: Resizes the image to the specified width and height. + +```go +// Resize to a width of 600px and preserve ratio +{{ $image := $resource.Resize "600x" }} + +// Resize to a height of 400px and preserve ratio +{{ $image := $resource.Resize "x400" }} + +// Resize to a width 600px and a height of 400px +{{ $image := $resource.Resize "600x400" }} +``` + +Fit +: Scale down the image to fit the given dimensions while maintaining aspect ratio. Both height and width are required. + +```go +{{ $image := $resource.Fit "600x400" }} +``` + +Fill +: Resize and crop the image to match the given dimensions. Both height and width are required. + +```go +{{ $image := $resource.Fill "600x400" }} +``` + + +{{% note %}} +Image operations in Hugo currently **do not preserve EXIF data** as this is not supported by Go's [image package](https://github.com/golang/go/search?q=exif&type=Issues&utf8=%E2%9C%93). This will be improved on in the future. +{{% /note %}} + + +## Image Processing Options + +In addition to the dimensions (e.g. `600x400`), Hugo supports a set of additional image options. + + +JPEG Quality +: Only relevant for JPEG images, values 1 to 100 inclusive, higher is better. Default is 75. + +```go +{{ $image.Resize "600x q50" }} +``` + +Rotate +: Rotates an image by the given angle counter-clockwise. The rotation will be performed first to get the dimensions correct. The main use of this is to be able to manually correct for [EXIF orientation](https://github.com/golang/go/issues/4341) of JPEG images. + +```go +{{ $image.Resize "600x r90" }} +``` + +Anchor +: Only relevant for the `Fill` method. This is useful for thumbnail generation where the main motive is located in, say, the left corner. +Valid are `Center`, `TopLeft`, `Top`, `TopRight`, `Left`, `Right`, `BottomLeft`, `Bottom`, `BottomRight`. + +```go +{{ $image.Fill "300x200 BottomLeft" }} +``` + +Resample Filter +: Filter used in resizing. Default is `Box`, a simple and fast resampling filter appropriate for downscaling. + +Examples are: `Box`, `NearestNeighbor`, `Linear`, `Gaussian`. + +See https://github.com/disintegration/imaging for more. If you want to trade quality for faster processing, this may be a option to test. + +```go +{{ $image.Resize "600x400 Gaussian" }} +``` + +## Image Processing Examples + +_The photo of the sunset used in the examples below is Copyright [Bjørn Erik Pedersen](https://commons.wikimedia.org/wiki/User:Bep) (Creative Commons Attribution-Share Alike 4.0 International license)_ + + +{{< imgproc sunset Resize "300x" />}} + +{{< imgproc sunset Fill "90x120 left" />}} + +{{< imgproc sunset Fill "90x120 right" />}} + +{{< imgproc sunset Fit "90x90" />}} + +{{< imgproc sunset Resize "300x q10" />}} + + +This is the shortcode used in the examples above: + + +{{< code file="layouts/shortcodes/imgproc.html" >}} +{{< readfile file="layouts/shortcodes/imgproc.html" >}} +{{< /code >}} + +And it is used like this: + - ```html ++```go-html-template +{{}} +``` + + +{{% note %}} +**Tip:** Note the self-closing shortcode syntax above. The `imgproc` shortcode can be called both with and without **inner content**. +{{% /note %}} + +## Image Processing Config + +You can configure an `imaging` section in `config.toml` with default image processing options: + +```toml +[imaging] +# Default resample filter used for resizing. Default is Box, +# a simple and fast averaging filter appropriate for downscaling. +# See https://github.com/disintegration/imaging +resampleFilter = "box" + +# Defatult JPEG quality setting. Default is 75. +quality = 75 + +# Anchor used when cropping pictures. +# Default is "smart" which does Smart Cropping, using https://github.com/muesli/smartcrop +# Smart Cropping is content aware and tries to find the best crop for each image. +# Valid values are Smart, Center, TopLeft, Top, TopRight, Left, Right, BottomLeft, Bottom, BottomRight +anchor = "smart" + +``` + +All of the above settings can also be set per image procecssing. + +## Smart Cropping of Images + +By default, Hugo will use the [Smartcrop](https://github.com/muesli/smartcrop), a library created by [muesli](https://github.com/muesli), when cropping images with `.Fill`. You can set the anchor point manually, but in most cases the smart option will make a good choice. And we will work with the libray author to improve this in the future. + +An example using the sunset image from above: + + +{{< imgproc sunset Fill "200x200 smart" />}} + + +## Image Processing Performance Consideration + +Processed images are stored below `/resources` (can be set with `resourceDir` config setting). This folder is deliberately placed in the project, as it is recommended to check these into source control as part of the project. These images are not "Hugo fast" to generate, but once generated they can be reused. + +If you change your image settings (e.g. size), remove or rename images etc., you will end up with unused images taking up space and cluttering your project. + +To clean up, run: + +```bash +hugo --gc +``` + + +{{% note %}} +**GC** is short for **Garbage Collection**. +{{% /note %}} + + + diff --cc docs/content/content-management/menus.md index 1353ce0e,00000000..c2eadf50 mode 100644,000000..100644 --- a/docs/content/content-management/menus.md +++ b/docs/content/content-management/menus.md @@@ -1,177 -1,0 +1,161 @@@ +--- +title: Menus +linktitle: Menus +description: Hugo has a simple yet powerful menu system. +date: 2017-02-01 +publishdate: 2017-02-01 +lastmod: 2017-03-31 +categories: [content management] +keywords: [menus] +draft: false +menu: + docs: + parent: "content-management" + weight: 120 +weight: 120 #rem +aliases: [/extras/menus/] +toc: true +--- + +{{% note "Lazy Blogger"%}} +If all you want is a simple menu for your sections, see the ["Section Menu for Lazy Bloggers" in Menu Templates](/templates/menu-templates/#section-menu-for-lazy-bloggers). +{{% /note %}} + +You can do this: + +* Place content in one or many menus +* Handle nested menus with unlimited depth +* Create menu entries without being attached to any content +* Distinguish active element (and active branch) + +## What is a Menu in Hugo? + +A **menu** is a named array of menu entries accessible by name via the [`.Site.Menus` site variable][sitevars]. For example, you can access your site's `main` menu via `.Site.Menus.main`. + +{{% note "Menus on Multilingual Sites" %}} +If you make use of the [multilingual feature](/content-management/multilingual/), you can define language-independent menus. +{{% /note %}} + +A menu entry has the following properties (i.e., variables) available to it: + +`.URL` +: string + +`.Name` +: string + +`.Menu` +: string + +`.Identifier` +: string + +`.Pre` +: template.HTML + +`.Post` +: template.HTML + +`.Weight` +: int + +`.Parent` +: string + +`.Children` +: Menu + +Note that menus also have the following functions available as well: + +`.HasChildren` +: boolean + +Additionally, there are some relevant functions available to menus on a page: + +`.IsMenuCurrent` +: (menu string, menuEntry *MenuEntry ) boolean + +`.HasMenuCurrent` +: (menu string, menuEntry *MenuEntry) boolean + +## Add content to menus + +Hugo allows you to add content to a menu via the content's [front matter](/content-management/front-matter/). + +### Simple + +If all you need to do is add an entry to a menu, the simple form works well. + +#### A Single Menu + +``` +--- +menu: "main" +--- +``` + +#### Multiple Menus + +``` +--- +menu: ["main", "footer"] +--- +``` + +#### Advanced + + +``` +--- +menu: + docs: + parent: 'extras' + weight: 20 +--- +``` + +## Add Non-content Entries to a Menu + +You can also add entries to menus that aren’t attached to a piece of content. This takes place in your Hugo project's [`config` file][config]. + - Here’s an example snippet pulled from a `config.toml`: ++Here’s an example snippet pulled from a configuration file: + - {{< code file="config.toml" >}} ++{{< code-toggle file="config.toml" >}} +[[menu.main]] + name = "about hugo" + pre = "" + weight = -110 + identifier = "about" + url = "/about/" +[[menu.main]] + name = "getting started" + pre = "" + weight = -100 + url = "/getting-started/" - {{< /code >}} - - Here's the equivalent snippet in a `config.yaml`: - - {{< code file="config.yml" >}} - menu: - main: - - name: "about hugo" - pre: "" - weight: -110 - identifier: "about" - url: "/about/" - - name: "getting started" - pre: "" - weight: -100 - url: "/getting-started/" - {{< /code >}} ++{{< /code-toggle >}} + +{{% note %}} +The URLs must be relative to the context root. If the `baseURL` is `https://example.com/mysite/`, then the URLs in the menu must not include the context root `mysite`. Using an absolute URL will override the baseURL. If the value used for `URL` in the above example is `https://subdomain.example.com/`, the output will be `https://subdomain.example.com`. +{{% /note %}} + +## Nesting + +All nesting of content is done via the `parent` field. + +The parent of an entry should be the identifier of another entry. The identifier should be unique (within a menu). + +The following order is used to determine an Identifier: + +`.Name > .LinkTitle > .Title` + +This means that `.Title` will be used unless `.LinkTitle` is present, etc. In practice, `.Name` and `.Identifier` are only used to structure relationships and therefore never displayed. + +In this example, the top level of the menu is defined in your [site `config` file][config]). All content entries are attached to one of these entries via the `.Parent` field. + +## Render Menus + +See [Menu Templates](/templates/menu-templates/) for information on how to render your site menus within your templates. + +[config]: /getting-started/configuration/ +[multilingual]: /content-management/multilingual/ +[sitevars]: /variables/ diff --cc docs/content/content-management/multilingual.md index d27195a9,00000000..28a6e4fe mode 100644,000000..100644 --- a/docs/content/content-management/multilingual.md +++ b/docs/content/content-management/multilingual.md @@@ -1,386 -1,0 +1,386 @@@ +--- +title: Multilingual Mode +linktitle: Multilingual and i18n +description: Hugo supports the creation of websites with multiple languages side by side. +date: 2017-01-10 +publishdate: 2017-01-10 +lastmod: 2017-01-10 +categories: [content management] +keywords: [multilingual,i18n, internationalization] +menu: + docs: + parent: "content-management" + weight: 150 +weight: 150 #rem +draft: false +aliases: [/content/multilingual/,/content-management/multilingual/,/tutorials/create-a-multilingual-site/] +toc: true +--- + +You should define the available languages in a `languages` section in your site configuration. + +## Configure Languages + - The following is an example of a TOML site configuration for a multilingual Hugo project: ++The following is an example of a site configuration for a multilingual Hugo project: + - {{< code file="config.toml" download="config.toml" >}} ++{{< code-toggle file="config" >}} +DefaultContentLanguage = "en" +copyright = "Everything is mine" + +[params.navigation] +help = "Help" + +[languages] +[languages.en] +title = "My blog" +weight = 1 +[languages.en.params] +linkedin = "english-link" + +[languages.fr] +copyright = "Tout est à moi" +title = "Mon blog" +weight = 2 +[languages.fr.params] +linkedin = "lien-francais" +[languages.fr.params.navigation] +help = "Aide" - {{< /code >}} ++{{< /code-toggle >}} + +Anything not defined in a `[languages]` block will fall back to the global +value for that key (e.g., `copyright` for the English [`en`] language). + +With the configuration above, all content, sitemap, RSS feeds, paginations, +and taxonomy pages will be rendered below `/` in English (your default content language) and then below `/fr` in French. + +When working with front matter `Params` in [single page templates][singles], omit the `params` in the key for the translation. + +If you want all of the languages to be put below their respective language code, enable `defaultContentLanguageInSubdir: true`. + +Only the obvious non-global options can be overridden per language. Examples of global options are `baseURL`, `buildDrafts`, etc. + +## Disable a Language + +You can disable one or more languages. This can be useful when working on a new translation. + +```toml +disableLanguages = ["fr", "jp"] +``` + +Note that you cannot disable the default content language. + +We kept this as a standalone setting to make it easier to set via [OS environment](/getting-started/configuration/#configure-with-environment-variables): + +```bash +HUGO_DISABLELANGUAGES="fr jp" hugo +``` +If you have already a list of disabled languages in `config.toml`, you can enable them in development like this: + +```bash +HUGO_DISABLELANGUAGES=" " hugo server +``` + + +## Configure Multilingual Multihost + +From **Hugo 0.31** we support multiple languages in a multihost configuration. See [this issue](https://github.com/gohugoio/hugo/issues/4027) for details. + +This means that you can now configure a `baseURL` per `language`: + + +> If a `baseURL` is set on the `language` level, then all languages must have one and they must all be different. + +Example: + - ```bash ++{{< code-toggle file="config" >}} +[languages] +[languages.no] +baseURL = "https://example.no" +languageName = "Norsk" +weight = 1 +title = "På norsk" + +[languages.en] +baseURL = "https://example.com" +languageName = "English" +weight = 2 +title = "In English" - ``` ++{{}} + +With the above, the two sites will be generated into `public` with their own root: + +```bash +public +├── en +└── no +``` + +**All URLs (i.e `.Permalink` etc.) will be generated from that root. So the English home page above will have its `.Permalink` set to `https://example.com/`.** + +When you run `hugo server` we will start multiple HTTP servers. You will typlically see something like this in the console: + +```bash +Web Server is available at 127.0.0.1:1313 (bind address 127.0.0.1) +Web Server is available at 127.0.0.1:1314 (bind address 127.0.0.1) +Press Ctrl+C to stop +``` + +Live reload and `--navigateToChanged` between the servers work as expected. + +## Taxonomies and Blackfriday + +Taxonomies and [Blackfriday configuration][config] can also be set per language: + + - {{< code file="bf-config.toml" >}} ++{{< code-toggle file="config" >}} +[Taxonomies] +tag = "tags" + +[blackfriday] +angledQuotes = true +hrefTargetBlank = true + +[languages] +[languages.en] +weight = 1 +title = "English" +[languages.en.blackfriday] +angledQuotes = false + +[languages.fr] +weight = 2 +title = "Français" +[languages.fr.Taxonomies] +plaque = "plaques" - {{< /code >}} ++{{}} + +## Translate Your Content + +Translated articles are identified by the name of the content file. + +### Examples of Translated Articles + +1. `/content/about.en.md` +2. `/content/about.fr.md` + +In this example, the `about.md` will be assigned the configured `defaultContentLanguage`. + +1. `/content/about.md` +2. `/content/about.fr.md` + +This way, you can slowly start to translate your current content without having to rename everything. If left unspecified, the default value for `defaultContentLanguage` is `en`. + +By having the same **directory and base filename**, the content pieces are linked together as translated pieces. + +You can also set the key used to link the translations explicitly in front matter: + +```yaml +translationKey: "my-story" +``` + +If you need distinct URLs per language, you can set the slug in the non-default language file. For example, you can define a custom slug for a French translation in the front matter of `content/about.fr.md` as follows: + +```yaml +slug: "a-propos" + +``` + +At render, Hugo will build both `/about/` and `/a-propos/` as properly linked translated pages. + +For merging of content from other languages (i.e. missing content translations), see [lang.Merge](/functions/lang.merge/). + +## Link to Translated Content + +To create a list of links to translated content, use a template similar to the following: + +{{< code file="layouts/partials/i18nlist.html" >}} +{{ if .IsTranslated }} +

    {{ i18n "translations" }}

    + +{{ end }} +{{< /code >}} + +The above can be put in a `partial` (i.e., inside `layouts/partials/`) and included in any template, be it for a [single content page][contenttemplate] or the [homepage][]. It will not print anything if there are no translations for a given page. + +The above also uses the [`i18n` function][i18func] described in the next section. + +## List All Available Languages + +`.AllTranslations` on a `Page` can be used to list all translations, including itself. Called on the home page it can be used to build a language navigator: + + +{{< code file="layouts/partials/allLanguages.html" >}} + +{{< /code >}} + +## Translation of Strings + +Hugo uses [go-i18n][] to support string translations. [See the project's source repository][go-i18n-source] to find tools that will help you manage your translation workflows. + +Translations are collected from the `themes//i18n/` folder (built into the theme), as well as translations present in `i18n/` at the root of your project. In the `i18n`, the translations will be merged and take precedence over what is in the theme folder. Language files should be named according to [RFC 5646][] with names such as `en-US.toml`, `fr.toml`, etc. + +{{% note %}} +From **Hugo 0.31** you no longer need to use a valid language code. It _can be_ anything. + +See https://github.com/gohugoio/hugo/issues/3564 + +{{% /note %}} + +From within your templates, use the `i18n` function like this: + +``` +{{ i18n "home" }} +``` + +This uses a definition like this one in `i18n/en-US.toml`: + +``` +[home] +other = "Home" +``` + +Often you will want to use to the page variables in the translations strings. To do that, pass on the "." context when calling `i18n`: + +``` +{{ i18n "wordCount" . }} +``` + +This uses a definition like this one in `i18n/en-US.toml`: + +``` +[wordCount] +other = "This article has {{ .WordCount }} words." +``` +An example of singular and plural form: + +``` +[readingTime] +one = "One minute read" +other = "{{.Count}} minutes read" +``` +And then in the template: + +``` +{{ i18n "readingTime" .ReadingTime }} +``` +To track down missing translation strings, run Hugo with the `--i18n-warnings` flag: + +``` + hugo --i18n-warnings | grep i18n +i18n|MISSING_TRANSLATION|en|wordCount +``` + +## Customize Dates + +At the time of this writing, Golang does not yet have support for internationalized locales, but if you do some work, you can simulate it. For example, if you want to use French month names, you can add a data file like ``data/mois.yaml`` with this content: + +~~~yaml +1: "janvier" +2: "février" +3: "mars" +4: "avril" +5: "mai" +6: "juin" +7: "juillet" +8: "août" +9: "septembre" +10: "octobre" +11: "novembre" +12: "décembre" +~~~ + +... then index the non-English date names in your templates like so: + +~~~html + +~~~ + +This technique extracts the day, month and year by specifying ``.Date.Day``, ``.Date.Month``, and ``.Date.Year``, and uses the month number as a key, when indexing the month name data file. + +## Menus + +You can define your menus for each language independently. The [creation of a menu][menus] works analogous to earlier versions of Hugo, except that they have to be defined in their language-specific block in the configuration file: + +``` +defaultContentLanguage = "en" + +[languages.en] +weight = 0 +languageName = "English" + +[[languages.en.menu.main]] +url = "/" +name = "Home" +weight = 0 + + +[languages.de] +weight = 10 +languageName = "Deutsch" + +[[languages.de.menu.main]] +url = "/" +name = "Startseite" +weight = 0 +``` + +The rendering of the main navigation works as usual. `.Site.Menus` will just contain the menu of the current language. Pay attention to the generation of the menu links. `absLangURL` takes care that you link to the correct locale of your website. Otherwise, both menu entries would link to the English version as the default content language that resides in the root directory. + +``` +
      + {{- $currentPage := . -}} + {{ range .Site.Menus.main -}} +
    • + {{ .Name }} +
      • + {{- end }} +
    + +``` + +## Missing Translations + +If a string does not have a translation for the current language, Hugo will use the value from the default language. If no default value is set, an empty string will be shown. + +While translating a Hugo website, it can be handy to have a visual indicator of missing translations. The [`enableMissingTranslationPlaceholders` configuration option][config] will flag all untranslated strings with the placeholder `[i18n] identifier`, where `identifier` is the id of the missing translation. + +{{% note %}} +Hugo will generate your website with these missing translation placeholders. It might not be suited for production environments. +{{% /note %}} + +For merging of content from other languages (i.e. missing content translations), see [lang.Merge](/functions/lang.merge/). + +## Multilingual Themes support + +To support Multilingual mode in your themes, some considerations must be taken for the URLs in the templates. If there is more than one language, URLs must meet the following criteria: + +* Come from the built-in `.Permalink` or `.URL` +* Be constructed with + * The [`relLangURL` template function][rellangurl] or the [`absLangURL` template function][abslangurl] **OR** + * Prefixed with `{{ .LanguagePrefix }}` + +If there is more than one language defined, the `LanguagePrefix` variable will equal `/en` (or whatever your `CurrentLanguage` is). If not enabled, it will be an empty string and is therefore harmless for single-language Hugo websites. + +[abslangurl]: /functions/abslangurl +[config]: /getting-started/configuration/ +[contenttemplate]: /templates/single-page-templates/ +[go-i18n-source]: https://github.com/nicksnyder/go-i18n +[go-i18n]: https://github.com/nicksnyder/go-i18n +[homepage]: /templates/homepage/ +[i18func]: /functions/i18n/ +[menus]: /content-management/menus/ +[rellangurl]: /functions/rellangurl +[RFC 5646]: https://tools.ietf.org/html/rfc5646 +[singles]: /templates/single-page-templates/ diff --cc docs/content/content-management/page-bundles.md index 09aeae8e,00000000..34620a5e mode 100644,000000..100644 --- a/docs/content/content-management/page-bundles.md +++ b/docs/content/content-management/page-bundles.md @@@ -1,182 -1,0 +1,182 @@@ +--- +title : "Page Bundles" +description : "Content organization using Page Bundles" +date : 2018-01-24T13:09:00-05:00 +lastmod : 2018-01-28T22:26:40-05:00 +linktitle : "Page Bundles" +keywords : ["page", "bundle", "leaf", "branch"] +categories : ["content management"] +toc : true +menu : + docs: + identifier : "page-bundles" + parent : "content-management" + weight : 11 +--- + +Page Bundles are a way to group [Page Resources](/content-management/page-resources/). + +A Page Bundle can be one of: + +- Leaf Bundle (leaf means it has no children) +- Branch Bundle (home page, section, taxonomy terms, taxonomy list) + +| | Leaf Bundle | Branch Bundle | +|-----------------|--------------------------------------------------------|---------------------------------------------------------| +| Usage           | Collection of resources (pages, images etc.) for single pages | Collection of non-page resources (images etc.)for list pages | +| Index file name | `index.md` [^fn:1] | `_index.md` [^fn:1] | +| Layout type | `single` | `list` | +| Nesting | Doesn't allow nesting of more bundles under it | Allows nesting of leaf/branch bundles under it | +| Example | `content/posts/my-post/index.md` | `content/posts/_index.md` | + + +## Leaf Bundles {#leaf-bundles} + +A _Leaf Bundle_ is a directory at any hierarchy within the `content/` +directory, that contains an **`index.md`** file. + +### Examples of Leaf Bundle organization {#examples-of-leaf-bundle-organization} + +```text +content/ +├── about +│ ├── index.md +├── posts +│ ├── my-post +│ │ ├── content1.md +│ │ ├── content2.md +│ │ ├── image1.jpg +│ │ ├── image2.png +│ │ └── index.md +│ └── my-another-post +│    └── index.md +│ +└── another-section + ├── .. +    └── not-a-leaf-bundle + ├── .. +    └── another-leaf-bundle +    └── index.md +``` + +In the above example `content/` directory, there are four leaf +bundles: + +about +: This leaf bundle is at the root level (directly under + `content` directory) and has only the `index.md`. + +my-post +: This leaf bundle has the `index.md`, two other content + Markdown files and two image files. + +my-another-post +: This leaf bundle has only the `index.md`. + +another-leaf-bundle +: This leaf bundle is nested under couple of + directories. This bundle also has only the `index.md`. + +{{% note %}} +The hierarchy depth at which a leaf bundle is created does not matter, +as long as it is not inside another **leaf** bundle. +{{% /note %}} + + +### Headless Bundle {#headless-bundle} + +A headless bundle is a bundle that is configured to not get published +anywhere: + +- It will have no `Permalink` and no rendered HTML in `public/`. +- It will not be part of `.Site.RegularPages`, etc. + +But you can get it by `.Site.GetPage`. Here is an example: + - ```html ++```go-html-template +{{ $headless := .Site.GetPage "page" "some-headless-bundle" }} +{{ $reusablePages := $headless.Resources.Match "author*" }} +

    Authors

    +{{ range $reusablePages }} +

    {{ .Title }}

    + {{ .Content }} +{{ end }} +``` + +_In this example, we are assuming the `some-headless-bundle` to be a headless + bundle containing one or more **page** resources whose `.Name` matches + `"author*"`._ + +Explanation of the above example: + +1. Get the `some-headless-bundle` Page "object". +2. Collect a *slice* of resources in this *Page Bundle* that matches + `"author*"` using `.Resources.Match`. +3. Loop through that *slice* of nested pages, and output their `.Title` and + `.Content`. + +--- + +A leaf bundle can be made headless by adding below in the Front Matter +(in the `index.md`): + +```toml +headless = true +``` + +{{% note %}} +Only leaf bundles can be made headless. +{{% /note %}} + +There are many use cases of such headless page bundles: + +- Shared media galleries +- Reusable page content "snippets" + + +## Branch Bundles {#branch-bundles} + +A _Branch Bundle_ is any directory at any hierarchy within the +`content/` directory, that contains at least an **`_index.md`** file. + +This `_index.md` can also be directly under the `content/` directory. + +{{% note %}} +Here `md` (markdown) is used just as an example. You can use any file +type as a content resource as long as it is a content type recognized by Hugo. +{{% /note %}} + + +### Examples of Branch Bundle organization {#examples-of-branch-bundle-organization} + +```text +content/ +├── branch-bundle-1 +│   ├── branch-content1.md +│   ├── branch-content2.md +│   ├── image1.jpg +│   ├── image2.png +│   └── _index.md +└── branch-bundle-2 + ├── _index.md + └── a-leaf-bundle + └── index.md +``` + +In the above example `content/` directory, there are two branch +bundles (and a leaf bundle): + +`branch-bundle-1` +: This branch bundle has the `_index.md`, two + other content Markdown files and two image files. + +`branch-bundle-2` +: This branch bundle has the `_index.md` and a + nested leaf bundle. + +{{% note %}} +The hierarchy depth at which a branch bundle is created does not +matter. +{{% /note %}} + +[^fn:1]: The `.md` extension is just an example. The extension can be `.html`, `.json` or any of any valid MIME type. diff --cc docs/content/content-management/page-resources.md index f3b12d8c,00000000..cefb1cd4 mode 100644,000000..100644 --- a/docs/content/content-management/page-resources.md +++ b/docs/content/content-management/page-resources.md @@@ -1,184 -1,0 +1,150 @@@ +--- +title : "Page Resources" +description : "Page Resources -- images, other pages, documents etc. -- have page-relative URLs and their own metadata." +date: 2018-01-24 +categories: ["content management"] +keywords: [bundle,content,resources] +weight: 4003 +draft: false +toc: true +linktitle: "Page Resources" +menu: + docs: + parent: "content-management" + weight: 31 +--- + +## Properties + +ResourceType +: The main type of the resource. For example, a file of MIME type `image/jpg` has for ResourceType `image`. + +Name +: Default value is the filename (relative to the owning page). Can be set in front matter. + +Title +: Default blank. Can be set in front matter. + +Permalink +: The absolute URL to the resource. Resources of type `page` will have no value. + +RelPermalink +: The relative URL to the resource. Resources of type `page` will have no value. + +## Methods +ByType +: Returns the page resources of the given type. + +```go +{{ .Resources.ByType "image" }} +``` +Match +: Returns all the page resources (as a slice) whose `Name` matches the given Glob pattern ([examples](https://github.com/gobwas/glob/blob/master/readme.md)). The matching is case-insensitive. + +```go +{{ .Resources.Match "images/*" }} +``` + +GetMatch +: Same as `Match` but will return the first match. + +### Pattern Matching +```go +// Using Match/GetMatch to find this images/sunset.jpg ? +.Resources.Match "images/sun*" ✅ +.Resources.Match "**/Sunset.jpg" ✅ +.Resources.Match "images/*.jpg" ✅ +.Resources.Match "**.jpg" ✅ +.Resources.Match "*" 🚫 +.Resources.Match "sunset.jpg" 🚫 +.Resources.Match "*sunset.jpg" 🚫 + +``` + +## Page Resources Metadata + +Page Resources' metadata is managed from their page's front matter with an array/table parameter named `resources`. You can batch assign values using a [wildcards](http://tldp.org/LDP/GNU-Linux-Tools-Summary/html/x11655.htm). + +{{% note %}} +Resources of type `page` get `Title` etc. from their own front matter. +{{% /note %}} + +name +: Sets the value returned in `Name`. + +{{% warning %}} +The methods `Match` and `GetMatch` use `Name` to match the resources. +{{%/ warning %}} + +title +: Sets the value returned in `Title` + +params +: A map of custom key/values. + + - ### Resources metadata: YAML Example ++### Resources metadata example + - ~~~yaml ++{{< code-toggle copy="false">}} +title: Application +date : 2018-01-25 +resources : +- src : "images/sunset.jpg" + name : "header" +- src : "documents/photo_specs.pdf" + title : "Photo Specifications" + params: + icon : "photo" +- src : "documents/guide.pdf" + title : "Instruction Guide" +- src : "documents/checklist.pdf" + title : "Document Checklist" +- src : "documents/payment.docx" + title : "Proof of Payment" +- src : "**.pdf" + name : "pdf-file-:counter" + params : + icon : "pdf" +- src : "**.docx" + params : + icon : "word" - ~~~ - - ### Resources metadata: TOML Example - - ~~~toml - title = Application - date : 2018-01-25 - [[resources]] - src = "images/sunset.jpg" - name = "header" - [[resources]] - src = "documents/photo_specs.pdf" - title = "Photo Specifications" - [resources.params] - icon = "photo" - [[resources]] - src = "documents/guide.pdf" - title = "Instruction Guide" - [[resources]] - src = "documents/checklist.pdf" - title = "Document Checklist" - [[resources]] - src = "documents/payment.docx" - title = "Proof of Payment" - [[resources]] - src = "**.pdf" - name = "pdf-file-:counter" - [resources.params] - icon = "pdf" - [[resources]] - src = "**.docx" - [resources.params] - icon = "word" - ~~~ - ++{{}} + +From the example above: + +- `sunset.jpg` will receive a new `Name` and can now be found with `.GetMatch "header"`. +- `documents/photo_specs.pdf` will get the `photo` icon. +- `documents/checklist.pdf`, `documents/guide.pdf` and `documents/payment.docx` will get `Title` as set by `title`. +- Every `PDF` in the bundle except `documents/photo_specs.pdf` will get the `pdf` icon. +- All `PDF` files will get a new `Name`. The `name` parameter contains a special placeholder [`:counter`](#counter), so the `Name` will be `pdf-file-1`, `pdf-file-2`, `pdf-file-3`. +- Every docx in the bundle will receive the `word` icon. + +{{% warning %}} +The __order matters__ --- Only the **first set** values of the `title`, `name` and `params`-**keys** will be used. Consecutive parameters will be set only for the ones not already set. For example, in the above example, `.Params.icon` is already first set to `"photo"` in `src = "documents/photo_specs.pdf"`. So that would not get overridden to `"pdf"` by the later set `src = "**.pdf"` rule. +{{%/ warning %}} + +### The `:counter` placeholder in `name` and `title` + +The `:counter` is a special placeholder recognized in `name` and `title` parameters `resources`. + +The counter starts at 1 the first time they are used in either `name` or `title`. + +For example, if a bundle has the resources `photo_specs.pdf`, `other_specs.pdf`, `guide.pdf` and `checklist.pdf`, and the front matter has specified the `resources` as: + - ~~~toml ++{{< code-toggle copy="false">}} +[[resources]] + src = "*specs.pdf" + title = "Specification #:counter" +[[resources]] + src = "**.pdf" + name = "pdf-file-:counter" - ~~~ ++{{}} + +the `Name` and `Title` will be assigned to the resource files as follows: + +| Resource file | `Name` | `Title` | +|-------------------|-------------------|-----------------------| +| checklist.pdf | `"pdf-file-1.pdf` | `"checklist.pdf"` | +| guide.pdf | `"pdf-file-2.pdf` | `"guide.pdf"` | +| other\_specs.pdf | `"pdf-file-3.pdf` | `"Specification #1"` | +| photo\_specs.pdf | `"pdf-file-4.pdf` | `"Specification #2"` | diff --cc docs/content/content-management/related.md index 8ae6e79c,00000000..6f66e446 mode 100644,000000..100644 --- a/docs/content/content-management/related.md +++ b/docs/content/content-management/related.md @@@ -1,138 -1,0 +1,143 @@@ +--- +title: Related Content +description: List related content in "See Also" sections. +date: 2017-09-05 +categories: [content management] +keywords: [content] +menu: + docs: + parent: "content-management" + weight: 40 +weight: 30 +draft: false +aliases: [/content/related/,/related/] +toc: true +--- + +{{% note %}} +We currently do not index **Page content**. We thought we would release something that will make most people happy before we start solving [Sherlock's last case](https://github.com/joearms/sherlock). +{{% /note %}} + +## List Related Content + +To list up to 5 related pages is as simple as including something similar to this partial in your single page template: + +{{< code file="layouts/partials/related.html" >}} +{{ $related := .Site.RegularPages.Related . | first 5 }} +{{ with $related }} +

    See Also

    + +{{ end }} +{{< /code >}} + ++ ++{{% note %}} ++Read [this blog article](https://regisphilibert.com/blog/2018/04/hugo-optmized-relashionships-with-related-content/) for a great explanation more advanced usage of this feature. ++{{% /note %}} ++ +The full set of methods available on the page lists can bee seen in this Go interface: + +```go +// A PageGenealogist finds related pages in a page collection. This interface is implemented +// by Pages and PageGroup, which makes it available as `{{ .RegularPages.Related . }}` etc. +type PageGenealogist interface { + + // Template example: + // {{ $related := .RegularPages.Related . }} + Related(doc related.Document) (Pages, error) + + // Template example: + // {{ $related := .RegularPages.RelatedIndices . "tags" "date" }} + RelatedIndices(doc related.Document, indices ...interface{}) (Pages, error) + + // Template example: + // {{ $related := .RegularPages.RelatedTo ( keyVals "tags" "hugo" "rocks") ( keyVals "date" .Date ) }} + RelatedTo(args ...types.KeyValues) (Pages, error) +} +``` +## Configure Related Content +Hugo provides a sensible default configuration of Related Content, but you can fine-tune this in your configuration, on the global or language level if needed. + +{{% note %}} +If you add a `related` config section, you need to add a complete configuration. It is not possible to just set, say, `includeNewer` and use the rest from the Hugo defaults. +{{% /note %}} + +Below is a sample `config.toml` section: + +``` +[related] + +# Only include matches with rank >= threshold. This is a normalized rank between 0 and 100. +threshold = 80 + +# To get stable "See also" sections we, by default, exclude newer related pages. +includeNewer = false + +# Will lower case keywords in both queries and in the indexes. +toLower = false + +[[related.indices]] +name = "keywords" +weight = 150 +[[related.indices]] +name = "author" +toLower = true +weight = 30 +[[related.indices]] +name = "tags" +weight = 100 +[[related.indices]] +name = "date" +weight = 10 +pattern = "2006" +``` +### Top Level Config Options + +threshold +: A value between 0-100. Lower value will give more, but maybe not so relevant, matches. + +includeNewer +: Set to true to include **pages newer than the current page** in the related content listing. This will mean that the output for older posts may change as new related content gets added. + +toLower +: Set to true to lower case keywords in both the indexes and the queries. This may give more accurate results at a slight performance penalty. Note that this can also be set per index. + +### Config Options per Index + +name +: The index name. This value maps directly to a page param. Hugo supports string values (`author` in the example) and lists (`tags`, `keywords` etc.) and time and date objects. + +weight +: An integer weight that indicates _how important_ this parameter is relative to the other parameters. It can be 0, which has the effect of turning this index off, or even negative. Test with different values to see what fits your content best. + +pattern +: This is currently only relevant for dates. When listing related content, we may want to list content that is also close in time. Setting "2006" (default value for date indexes) as the pattern for a date index will add weight to pages published in the same year. For busier blogs, "200601" (year and month) may be a better default. + +toLower +: See above. + +## Performance Considerations + +**Fast is Hugo's middle name** and we would not have released this feature had it not been blistering fast. + +This feature has been in the back log and requested by many for a long time. The development got this recent kick start from this Twitter thread: + +{{< tweet 898398437527363585 >}} + +Scott S. Lowe removed the "Related Content" section built using the `intersect` template function on tags, and the build time dropped from 30 seconds to less than 2 seconds on his 1700 content page sized blog. + +He should now be able to add an improved version of that "Related Content" section without giving up the fast live-reloads. But it's worth noting that: + +* If you don't use any of the `Related` methods, you will not use the Relate Content feature, and performance will be the same as before. +* Calling `.RegularPages.Related` etc. will create one inverted index, also sometimes named posting list, that will be reused for any lookups in that same page collection. Doing that in addition to, as an example, calling `.Pages.Related` will work as expected, but will create one additional inverted index. This should still be very fast, but worth having in mind, especially for bigger sites. + + + + + + + diff --cc docs/content/content-management/static-files.md index 12d27ccf,00000000..fe5ea77e mode 100644,000000..100644 --- a/docs/content/content-management/static-files.md +++ b/docs/content/content-management/static-files.md @@@ -1,48 -1,0 +1,48 @@@ +--- +title: Static Files +description: "The `static` folder is where you place all your **static files**." +date: 2017-11-18 +categories: [content management] +keywords: [source, directories] +menu: + docs: + parent: "content-management" + weight: 130 +weight: 130 #rem +aliases: [/static-files] +toc: true +--- + +The `static` folder is where you place all your **static files**, e.g. stylesheets, JavaScript, images etc. + - You can set the name of the static folder to use in your configuration file, for example `config.toml`. From **Hugo 0.31** you can configure as many static directories as you need. All the files in all the static directories will form a union filesystem. ++You can set the name of the static folder to use in your configuration file. From **Hugo 0.31** you can configure as many static directories as you need. All the files in all the static directories will form a union filesystem. + +Example: + - ```toml ++{{< code-toggle copy="false" file="config" >}} +staticDir = ["static1", "static2"] +[languages] +[languages.no] +staticDir = ["staticDir_override", "static_no"] +baseURL = "https://example.no" +languageName = "Norsk" +weight = 1 +title = "PÃ¥ norsk" + +[languages.en] +staticDir2 = "static_en" +baseURL = "https://example.com" +languageName = "English" +weight = 2 +title = "In English" - ``` ++{{}} + +In the above, with no theme used: + +* The English site will get its static files as a union of "static1", "static2" and "static_en". On file duplicates, the right-most version will win. +* The Norwegian site will get its static files as a union of "staticDir_override" and "static_no". + +**Note:** The `2` `static2` (can be a number between 0 and 10) is added to tell Hugo that you want to **add** this directory to the global set of static directories. Using `staticDir` on the language level would replace the global value. + + +**Note:** The example above is a [multihost setup](/content-management/multilingual/#configure-multilingual-multihost). In a regular setup, all the static directories will be available to all sites. diff --cc docs/content/content-management/syntax-highlighting.md index 67d443fd,00000000..e7eb011c mode 100644,000000..100644 --- a/docs/content/content-management/syntax-highlighting.md +++ b/docs/content/content-management/syntax-highlighting.md @@@ -1,188 -1,0 +1,193 @@@ +--- +title: Syntax Highlighting +description: Hugo comes with reallly fast syntax highlighting from Chroma. +date: 2017-02-01 +publishdate: 2017-02-01 +keywords: [highlighting,pygments,chroma,code blocks,syntax] +categories: [content management] +menu: + docs: + parent: "content-management" + weight: 300 +weight: 20 +sections_weight: 20 +draft: false +aliases: [/extras/highlighting/,/extras/highlight/,/tools/syntax-highlighting/] +toc: true +--- + +From Hugo 0.28, the default syntax hightlighter in Hugo is [Chroma](https://github.com/alecthomas/chroma); it is built in Go and is really, really fast -- and for the most important parts compatible with Pygments. + +If you want to continue to use Pygments (see below), set `pygmentsUseClassic=true` in your site config. + +The example below shows a simple code snippet from the Hugo source highlighted with the `highlight` shortcode. Note that the gohugo.io site is generated with `pygmentsUseClasses=true` (see [Generate Syntax Highlighter CSS](#generate-syntax-highlighter-css)). + +* `linenos=inline` or `linenos=table` (`table` will give copy-and-paste friendly code blocks) turns on line numbers. +* `hl_lines` lists a set of line numbers or line number ranges to be highlighted. Note that the hyphen range syntax is only supported for Chroma. +* `linenostart=199` starts the line number count from 199. + +With that, this: + +``` +{{}} +// ... code +{{}} +``` + +Gives this: + +{{< highlight go "linenos=table,hl_lines=8 15-17,linenostart=199" >}} +// GetTitleFunc returns a func that can be used to transform a string to +// title case. +// +// The supported styles are +// +// - "Go" (strings.Title) +// - "AP" (see https://www.apstylebook.com/) +// - "Chicago" (see http://www.chicagomanualofstyle.org/home.html) +// +// If an unknown or empty style is provided, AP style is what you get. +func GetTitleFunc(style string) func(s string) string { + switch strings.ToLower(style) { + case "go": + return strings.Title + case "chicago": + tc := transform.NewTitleConverter(transform.ChicagoStyle) + return tc.Title + default: + tc := transform.NewTitleConverter(transform.APStyle) + return tc.Title + } +} +{{< / highlight >}} + + +## Configure Syntax Highlighter +To make the transition from Pygments to Chroma seamless, they share a common set of configuration options: + +pygmentsOptions +: A comma separated list of options. See below for a full list. + +pygmentsCodefences +: Set to true to enable syntax highlighting in code fences with a language tag in markdown (see below for an example). + +pygmentsStyle +: The style of code highlighting. See https://help.farbox.com/pygments.html for a gallery. Note that this option is not relevant when `pygmentsUseClasses` is set. + +pygmentsUseClasses +: Set to `true` to use CSS classes to format your highlighted code. See [Generate Syntax Highlighter CSS](#generate-syntax-highlighter-css). + +pygmentsCodefencesGuessSyntax +: Set to `true` to try to do syntax highlighting on code fenced blocks in markdown without a language tag. + +pygmentsUseClassic +: Set to true to use Pygments instead of the much faster Chroma. + +### Options + +`pygmentsOptions` can be set either in site config or overridden per code block in the Highlight shortcode or template func. + +noclasses +: Use inline style. + +linenos +: For Chroma, any value in this setting will print line numbers. Pygments has some more fine grained control. + +linenostart +: Start the line numbers from this value (default is 1). + + +hl_lines +: Highlight a space separated list of line numbers. For Chroma, you can provide a list of ranges, i.e. "3-8 10-20". + + +The full set of supported options for Pygments is: `encoding`, `outencoding`, `nowrap`, `full`, `title`, `style`, `noclasses`, `classprefix`, `cssclass`, `cssstyles`, `prestyles`, `linenos`, `hl_lines`, `linenostart`, `linenostep`, `linenospecial`, `nobackground`, `lineseparator`, `lineanchors`, `linespans`, `anchorlinenos`, `startinline`. See the [Pygments HTML Formatter Documentation](http://pygments.org/docs/formatters/#HtmlFormatter) for details. + + +## Generate Syntax Highlighter CSS + +If you run with `pygmentsUseClasses=true` in your site config, you need a style sheet. + +You can generate one with Hugo: + +```bash +hugo gen chromastyles --style=monokai > syntax.css +``` + +Run `hugo gen chromastyles -h` for more options. See https://help.farbox.com/pygments.html for a gallery of available styles. + + +## Highlight Shortcode + +Highlighting is carried out via the [built-in shortcode](/content-management/shortcodes/) `highlight`. `highlight` takes exactly one required parameter for the programming language to be highlighted and requires a closing shortcode. Note that `highlight` is *not* used for client-side javascript highlighting. + +### Example `highlight` Shortcode + +{{< code file="example-highlight-shortcode-input.md" >}} +{{}} +
    +
    +

    {{ .Title }}

    + {{ range .Data.Pages }} + {{ .Render "summary"}} + {{ end }} +
    +
    +{{}} +{{< /code >}} + + + +## Highlight Template Func + +See [Highlight](/functions/highlight/). + +## Highlight in Code Fences + +It is also possible to add syntax highlighting with GitHub flavored code fences. To enable this, set the `pygmentsCodeFences` to `true` in Hugo's [configuration file](/getting-started/configuration/); + +```` - ```html ++```go-html-template +
    +
    +

    {{ .Title }}

    + {{ range .Data.Pages }} + {{ .Render "summary"}} + {{ end }} +
    +
    +``` +```` + ++## List of Chroma Highlighting Languages ++ ++The full list of Chroma lexers and their aliases (which is the identifier used in the `hightlight` template func or when doing highlighting in code fences): ++ ++{{< chroma-lexers >}} + +## Highlight with Pygments Classic + +If you for some reason don't want to use the built-in Chroma highlighter, you can set `pygmentsUseClassic=true` in your config and add Pygments to your path. + +{{% note "Disclaimers on Pygments" %}} +* Pygments is relatively slow and _causes a performance hit when building your site_, but Hugo has been designed to cache the results to disk. +* The caching can be turned off by setting the `--ignoreCache` flag to `true`. +* The languages available for highlighting depend on your Pygments installation. +{{% /note %}} + +If you have never worked with Pygments before, here is a brief primer: + ++ Install Python from [python.org](https://www.python.org/downloads/). Version 2.7.x is already sufficient. ++ Run `pip install Pygments` in order to install Pygments. Once installed, Pygments gives you a command `pygmentize`. Make sure it sits in your PATH; otherwise, Hugo will not be able to find and use it. + +On Debian and Ubuntu systems, you may also install Pygments by running `sudo apt-get install python3-pygments`. + + + +[Prism]: http://prismjs.com +[prismdownload]: http://prismjs.com/download.html +[Highlight.js]: http://highlightjs.org/ +[Rainbow]: http://craig.is/making/rainbows +[Syntax Highlighter]: http://alexgorbatchev.com/SyntaxHighlighter/ +[Google Prettify]: https://github.com/google/code-prettify +[Yandex]: http://yandex.ru/ diff --cc docs/content/content-management/taxonomies.md index 1a59ebe3,00000000..287c6f89 mode 100644,000000..100644 --- a/docs/content/content-management/taxonomies.md +++ b/docs/content/content-management/taxonomies.md @@@ -1,253 -1,0 +1,193 @@@ +--- +title: Taxonomies +linktitle: +description: Hugo includes support for user-defined taxonomies to help you demonstrate logical relationships between content for the end users of your website. +date: 2017-02-01 +publishdate: 2017-02-01 +lastmod: 2017-02-01 +keywords: [taxonomies,metadata,front matter,terms] +categories: [content management] +menu: + docs: + parent: "content-management" + weight: 80 +weight: 80 #rem +draft: false +aliases: [/taxonomies/overview/,/taxonomies/usage/,/indexes/overview/,/doc/indexes/,/extras/indexes] +toc: true +--- + +## What is a Taxonomy? + +Hugo includes support for user-defined groupings of content called **taxonomies**. Taxonomies are classifications of logical relationships between content. + +### Definitions + +Taxonomy +: a categorization that can be used to classify content + +Term +: a key within the taxonomy + +Value +: a piece of content assigned to a term + +{{< youtube pCPCQgqC8RA >}} + +## Example Taxonomy: Movie Website + +Let's assume you are making a website about movies. You may want to include the following taxonomies: + +* Actors +* Directors +* Studios +* Genre +* Year +* Awards + +Then, in each of the movies, you would specify terms for each of these taxonomies (i.e., in the [front matter][] of each of your movie content files). From these terms, Hugo would automatically create pages for each Actor, Director, Studio, Genre, Year, and Award, with each listing all of the Movies that matched that specific Actor, Director, Studio, Genre, Year, and Award. + +### Movie Taxonomy Organization + +To continue with the example of a movie site, the following demonstrates content relationships from the perspective of the taxonomy: + +``` +Actor <- Taxonomy + Bruce Willis <- Term + The Sixth Sense <- Value + Unbreakable <- Value + Moonrise Kingdom <- Value + Samuel L. Jackson <- Term + Unbreakable <- Value + The Avengers <- Value + xXx <- Value +``` + +From the perspective of the content, the relationships would appear differently, although the data and labels used are the same: + +``` +Unbreakable <- Value + Actors <- Taxonomy + Bruce Willis <- Term + Samuel L. Jackson <- Term + Director <- Taxonomy + M. Night Shyamalan <- Term + ... +Moonrise Kingdom <- Value + Actors <- Taxonomy + Bruce Willis <- Term + Bill Murray <- Term + Director <- Taxonomy + Wes Anderson <- Term + ... +``` + +## Hugo Taxonomy Defaults + +Hugo natively supports taxonomies. + +Without adding a single line to your site's configuration file, Hugo will automatically create taxonomies for `tags` and `categories`. If you do not want Hugo to create any taxonomies, set `disableKinds` in your site's configuration to the following: + +``` +disableKinds = ["taxonomy","taxonomyTerm"] +``` + +### Default Destinations + +When taxonomies are used---and [taxonomy templates][] are provided---Hugo will automatically create both a page listing all the taxonomy's terms and individual pages with lists of content associated with each term. For example, a `categories` taxonomy declared in your configuration and used in your content front matter will create the following pages: + +* A single page at `example.com/categories/` that lists all the [terms within the taxonomy][] +* [Individual taxonomy list pages][taxonomy templates] (e.g., `/categories/development/`) for each of the terms that shows a listing of all pages marked as part of that taxonomy within any content file's [front matter][] + +## Configure Taxonomies + +Taxonomies must be defined in your [website configuration][config] before they can be used throughout the site. You need to provide both the plural and singular labels for each taxonomy. For example, `singular key = "plural value"` for TOML and `singular key: "plural value"` for YAML. + - ### Example: TOML Taxonomy Configuration ++### Example: Taxonomy Configuration + - ``` ++{{< code-toggle copy="false" >}} +[taxonomies] + tag = "tags" + category = "categories" + series = "series" - ``` - - ### Example: YAML Taxonomy Configuration - - ``` - taxonomies: - tag: "tags" - category: "categories" - series: "series" - ``` ++{{}} + +### Preserve Taxonomy Values + +By default, taxonomy names are normalized. + +Therefore, if you want to have a taxonomy term with special characters such as `Gérard Depardieu` instead of `Gerard Depardieu`, set the value for `preserveTaxonomyNames` to `true` in your [site configuration][config]. Hugo will then preserve special characters in taxonomy values but will still title-ize the values for titles and normalize them in URLs. + +Note that if you use `preserveTaxonomyNames` and intend to manually construct URLs to the archive pages, you will need to pass the taxonomy values through the [`urlize` template function][]. + +{{% note %}} +You can add content and front matter to your taxonomy list and taxonomy terms pages. See [Content Organization](/content-management/organization/) for more information on how to add an `_index.md` for this purpose. + +Much like regular pages, taxonomy list [permalinks](/content-management/urls/) are configurable, but taxonomy term page permalinks are not. +{{% /note %}} + +## Add Taxonomies to Content + +Once a taxonomy is defined at the site level, any piece of content can be assigned to it, regardless of [content type][] or [content section][]. + +Assigning content to a taxonomy is done in the [front matter][]. Simply create a variable with the *plural* name of the taxonomy and assign all terms you want to apply to the instance of the content type. + +{{% note %}} +If you would like the ability to quickly generate content files with preconfigured taxonomies or terms, read the docs on [Hugo archetypes](/content-management/archetypes/). +{{% /note %}} + - ### Example: TOML Front Matter with Taxonomies ++### Example: Front Matter with Taxonomies + - ``` - +++ ++{{< code-toggle copy="false">}} +title = "Hugo: A fast and flexible static site generator" +tags = [ "Development", "Go", "fast", "Blogging" ] +categories = [ "Development" ] +series = [ "Go Web Dev" ] +slug = "hugo" +project_url = "https://github.com/gohugoio/hugo" - +++ - ``` - - ### Example: YAML Front Matter with Taxonomies - - ``` - --- - title: "Hugo: A fast and flexible static site generator" - tags: ["Development", "Go", "fast", "Blogging"] - categories: ["Development"] - series: ["Go Web Dev"] - slug: "hugo" - project_url: "https://github.com/gohugoio/hugo" - --- - ``` - - ### Example: JSON Front Matter with Taxonomies - - ``` - { - "title": "Hugo: A fast and flexible static site generator", - "tags": [ - "Development", - "Go", - "fast", - "Blogging" - ], - "categories" : [ - "Development" - ], - "series" : [ - "Go Web Dev" - ], - "slug": "hugo", - "project_url": "https://github.com/gohugoio/hugo" - } - ``` ++{{}} + +## Order Taxonomies + +A content file can assign weight for each of its associate taxonomies. Taxonomic weight can be used for sorting or ordering content in [taxonomy list templates][] and is declared in a content file's [front matter][]. The convention for declaring taxonomic weight is `taxonomyname_weight`. + +The following TOML and YAML examples show a piece of content that has a weight of 22, which can be used for ordering purposes when rendering the pages assigned to the "a", "b" and "c" values of the `tags` taxonomy. It has also been assigned the weight of 44 when rendering the "d" category page. + - ### Example: TOML Taxonomic `weight` ++### Example: Taxonomic `weight` + - ``` - +++ ++{{< code-toggle copy="false" >}} +title = "foo" +tags = [ "a", "b", "c" ] +tags_weight = 22 +categories = ["d"] +categories_weight = 44 - +++ - ``` - - ### Example: YAML Taxonomic `weight` - - ``` - --- - title: foo - tags: [ "a", "b", "c" ] - tags_weight: 22 - categories: ["d"] - categories_weight: 44 - --- - ``` ++{{}} + +By using taxonomic weight, the same piece of content can appear in different positions in different taxonomies. + +{{% note "Limits to Ordering Taxonomies" %}} +Currently taxonomies only support the [default `weight => date` ordering of list content](/templates/lists/#default-weight-date). For more information, see the documentation on [taxonomy templates](/templates/taxonomy-templates/). +{{% /note %}} + +## Add custom metadata to a Taxonomy Term + +If you need to add custom metadata to your taxonomy terms, you will need to create a page for that term at `/content///_index.md` and add your metadata in it's front matter. Continuing with our 'Actors' example, let's say you want to add a wikipedia page link to each actor. Your terms pages would be something like this: + +{{< code file="/content/actors/bruce-willis/_index.md" >}} + --- + title: "Bruce Willis" + wikipedia: "https://en.wikipedia.org/wiki/Bruce_Willis" + --- +{{< /code >}} + +You can later use your custom metadata as shown in the [Taxonomy Terms Templates documentation](/templates/taxonomy-templates/#displaying-custom-metadata-in-taxonomy-terms-templates). + +[`urlize` template function]: /functions/urlize/ +[content section]: /content-management/sections/ +[content type]: /content-management/types/ +[documentation on archetypes]: /content-management/archetypes/ +[front matter]: /content-management/front-matter/ +[taxonomy list templates]: /templates/taxonomy-templates/#taxonomy-page-templates +[taxonomy templates]: /templates/taxonomy-templates/ +[terms within the taxonomy]: /templates/taxonomy-templates/#taxonomy-terms-templates "See how to order terms associated with a taxonomy" +[config]: /getting-started/configuration/ diff --cc docs/content/content-management/urls.md index dd91fbce,00000000..d33725b7 mode 100644,000000..100644 --- a/docs/content/content-management/urls.md +++ b/docs/content/content-management/urls.md @@@ -1,282 -1,0 +1,275 @@@ +--- +title: URL Management +linktitle: URL Management +description: Hugo supports permalinks, aliases, link canonicalization, and multiple options for handling relative vs absolute URLs. +date: 2017-02-01 +publishdate: 2017-02-01 +lastmod: 2017-03-09 +keywords: [aliases,redirects,permalinks,urls] +categories: [content management] +menu: + docs: + parent: "content-management" + weight: 110 +weight: 110 #rem +draft: false +aliases: [/extras/permalinks/,/extras/aliases/,/extras/urls/,/doc/redirects/,/doc/alias/,/doc/aliases/] +toc: true +--- + +## Permalinks + +The default Hugo target directory for your built website is `public/`. However, you can change this value by specifying a different `publishDir` in your [site configuration][config]. The directories created at build time for a section reflect the position of the content's directory within the `content` folder and namespace matching its layout within the `contentdir` hierarchy. + +The `permalinks` option in your [site configuration][config] allows you to adjust the directory paths (i.e., the URLs) on a per-section basis. This will change where the files are written to and will change the page's internal "canonical" location, such that template references to `.RelPermalink` will honor the adjustments made as a result of the mappings in this option. + +{{% note "Default Publish and Content Folders" %}} +These examples use the default values for `publishDir` and `contentDir`; i.e., `public` and `content`, respectively. You can override the default values in your [site's `config` file](/getting-started/configuration/). +{{% /note %}} + +For example, if one of your [sections][] is called `post` and you want to adjust the canonical path to be hierarchical based on the year, month, and post title, you could set up the following configurations in YAML and TOML, respectively. + - ### YAML Permalinks Configuration Example ++### Permalinks Configuration Example + - {{< code file="config.yml" copy="false" >}} ++{{< code-toggle file="config" copy="false" >}} +permalinks: + post: /:year/:month/:title/ - {{< /code >}} - - ### TOML Permalinks Configuration Example - - {{< code file="config.toml" copy="false" >}} - [permalinks] - post = "/:year/:month/:title/" - {{< /code >}} ++{{< /code-toggle >}} + +Only the content under `post/` will have the new URL structure. For example, the file `content/post/sample-entry.md` with `date: 2017-02-27T19:20:00-05:00` in its front matter will render to `public/2017/02/sample-entry/index.html` at build time and therefore be reachable at `https://example.com/2017/02/sample-entry/`. + +You can also configure permalinks of taxonomies with the same syntax, by using the plural form of the taxonomy instead of the section. You will probably only want to use the configuration values `:slug` or `:title`. + +### Permalink Configuration Values + +The following is a list of values that can be used in a `permalink` definition in your site `config` file. All references to time are dependent on the content's date. + +`:year` +: the 4-digit year + +`:month` +: the 2-digit month + +`:monthname` +: the name of the month + +`:day` +: the 2-digit day + +`:weekday` +: the 1-digit day of the week (Sunday = 0) + +`:weekdayname` +: the name of the day of the week + +`:yearday` +: the 1- to 3-digit day of the year + +`:section` +: the content's section + +`:sections` +: the content's sections hierarchy + +`:title` +: the content's title + +`:slug` +: the content's slug (or title if no slug is provided in the front matter) + +`:filename` +: the content's filename (without extension) + +## Aliases + +For people migrating existing published content to Hugo, there's a good chance you need a mechanism to handle redirecting old URLs. + +Luckily, redirects can be handled easily with **aliases** in Hugo. + +### Example: Aliases + +Let's assume you create a new piece of content at `content/posts/my-awesome-blog-post.md`. The content is a revision of your previous post at `content/posts/my-original-url.md`. You can create an `aliases` field in the front matter of your new `my-awesome-blog-post.md` where you can add previous paths. The following examples show how to create this filed in TOML and YAML front matter, respectively. + +#### TOML Front Matter + +{{< code file="content/posts/my-awesome-post.md" copy="false" >}} ++++ +aliases = [ + "/posts/my-original-url/", + "/2010/01/01/even-earlier-url.html" +] ++++ +{{< /code >}} + +#### YAML Front Matter + +{{< code file="content/posts/my-awesome-post.md" copy="false" >}} +--- +aliases: + - /posts/my-original-url/ + - /2010/01/01/even-earlier-url.html +--- +{{< /code >}} + +Now when you visit any of the locations specified in aliases---i.e., *assuming the same site domain*---you'll be redirected to the page they are specified on. For example, a visitor to `example.com/posts/my-original-url/` will be immediately redirected to `example.com/posts/my-awesome-post/`. + +### Example: Aliases in Multilingual + +On [multilingual sites][multilingual], each translation of a post can have unique aliases. To use the same alias across multiple languages, prefix it with the language code. + +In `/posts/my-new-post.es.md`: + +``` +--- +aliases: + - /es/posts/my-original-post/ +--- +``` + +### How Hugo Aliases Work + +When aliases are specified, Hugo creates a directory to match the alias entry. Inside the directory, Hugo creates an `.html` file specifying the canonical URL for the page and the new redirect target. + +For example, a content file at `posts/my-intended-url.md` with the following in the front matter: + +``` +--- +title: My New post +aliases: [/posts/my-old-url/] +--- +``` + +Assuming a `baseURL` of `example.com`, the contents of the auto-generated alias `.html` found at `https://example.com/posts/my-old-url/` will contain the following: + +``` + + + + https://example.com/posts/my-intended-url + + + + + + +``` + +The `http-equiv="refresh"` line is what performs the redirect, in 0 seconds in this case. If an end user of your website goes to `https://example.com/posts/my-old-url`, they will now be automatically redirected to the newer, correct URL. The addition of `` lets search engine bots know that they should not crawl and index your new alias page. + +### Customize +You may customize this alias page by creating an `alias.html` template in the +layouts folder of your site (i.e., `layouts/alias.html`). In this case, the data passed to the template is + +`Permalink` +: the link to the page being aliased + +`Page` +: the Page data for the page being aliased + +### Important Behaviors of Aliases + +1. Hugo makes no assumptions about aliases. They also do not change based +on your UglyURLs setting. You need to provide absolute paths to your web root +and the complete filename or directory. +2. Aliases are rendered *before* any content are rendered and therefore will be overwritten by any content with the same location. + +## Pretty URLs + +Hugo's default behavior is to render your content with "pretty" URLs. No non-standard server-side configuration is required for these pretty URLs to work. + +The following demonstrates the concept: + +``` +content/posts/_index.md +=> example.com/posts/index.html +content/posts/post-1.md +=> example.com/posts/post-1/ +``` + +## Ugly URLs + +If you would like to have what are often referred to as "ugly URLs" (e.g., example.com/urls.html), set `uglyurls = true` or `uglyurls: true` in your site's `config.toml` or `config.yaml`, respectively. You can also use the `--uglyURLs=true` [flag from the command line][usage] with `hugo` or `hugo server`.. + +If you want a specific piece of content to have an exact URL, you can specify this in the [front matter][] under the `url` key. The following are examples of the same content directory and what the eventual URL structure will be when Hugo runs with its default behavior. + +See [Content Organization][contentorg] for more details on paths. + +``` +. +└── content + └── about + | └── _index.md // <- https://example.com/about/ + ├── post + | ├── firstpost.md // <- https://example.com/post/firstpost/ + | ├── happy + | | └── ness.md // <- https://example.com/post/happy/ness/ + | └── secondpost.md // <- https://example.com/post/secondpost/ + └── quote + ├── first.md // <- https://example.com/quote/first/ + └── second.md // <- https://example.com/quote/second/ +``` + +Here's the same organization run with `hugo --uglyURLs`: + +``` +. +└── content + └── about + | └── _index.md // <- https://example.com/about.html + ├── post + | ├── firstpost.md // <- https://example.com/post/firstpost.html + | ├── happy + | | └── ness.md // <- https://example.com/post/happy/ness.html + | └── secondpost.md // <- https://example.com/post/secondpost.html + └── quote + ├── first.md // <- https://example.com/quote/first.html + └── second.md // <- https://example.com/quote/second.html +``` + + +## Canonicalization + +By default, all relative URLs encountered in the input are left unmodified, e.g. `/css/foo.css` would stay as `/css/foo.css`. The `canonifyURLs` field in your site `config` has a default value of `false`. + +By setting `canonifyURLs` to `true`, all relative URLs would instead be *canonicalized* using `baseURL`. For example, assuming you have `baseURL = https://example.com/`, the relative URL `/css/foo.css` would be turned into the absolute URL `https://example.com/css/foo.css`. + +Benefits of canonicalization include fixing all URLs to be absolute, which may aid with some parsing tasks. Note, however, that all modern browsers handle this on the client without issue. + +Benefits of non-canonicalization include being able to have scheme-relative resource inclusion; e.g., so that `http` vs `https` can be decided according to how the page was retrieved. + +{{% note "`canonifyURLs` default change" %}} +In the May 2014 release of Hugo v0.11, the default value of `canonifyURLs` was switched from `true` to `false`, which we think is the better default and should continue to be the case going forward. Please verify and adjust your website accordingly if you are upgrading from v0.10 or older versions. +{{% /note %}} + +To find out the current value of `canonifyURLs` for your website, you may use the handy `hugo config` command added in v0.13. + +``` +hugo config | grep -i canon +``` + +Or, if you are on Windows and do not have `grep` installed: + +``` +hugo config | FINDSTR /I canon +``` + +## Override URLS with Front Matter + +In addition to specifying permalink values in your site configuration for different content sections, Hugo provides even more granular control for individual pieces of content. + +Both `slug` and `url` can be defined in individual front matter. For more information on content destinations at build time, see [Content Organization][contentorg]. + +## Relative URLs + +By default, all relative URLs are left unchanged by Hugo, which can be problematic when you want to make your site browsable from a local file system. + +Setting `relativeURLs` to `true` in your [site configuration][config] will cause Hugo to rewrite all relative URLs to be relative to the current content. + +For example, if your `/post/first/` page contains a link to `/about/`, Hugo will rewrite the URL to `../../about/`. + +[config]: /getting-started/configuration/ +[contentorg]: /content-management/organization/ +[front matter]: /content-management/front-matter/ +[multilingual]: /content-management/multilingual/ +[sections]: /content-management/sections/ +[usage]: /getting-started/usage/ diff --cc docs/content/functions/where.md index 3aa03296,00000000..eb311121 mode 100644,000000..100644 --- a/docs/content/functions/where.md +++ b/docs/content/functions/where.md @@@ -1,154 -1,0 +1,154 @@@ +--- +title: where +# linktitle: where +description: Filters an array to only the elements containing a matching value for a given field. +godocref: +date: 2017-02-01 +publishdate: 2017-02-01 +lastmod: 2017-02-01 +categories: [functions] +menu: + docs: + parent: "functions" +keywords: [filtering] +signature: ["where COLLECTION KEY [OPERATOR] MATCH"] +workson: [lists,taxonomies,terms,groups] +hugoversion: +relatedfuncs: [intersect,first,after,last] +deprecated: false +toc: true +needsexample: true +--- + +`where` filters an array to only the elements containing a matching value for a given field. + - ``` ++```go-html-template +{{ range where .Data.Pages "Section" "post" }} + {{ .Content }} +{{ end }} +``` + +It can be used by dot-chaining the second argument to refer to a nested element of a value. + +``` ++++ +series: golang ++++ +``` + - ``` ++```go-html-template +{{ range where .Site.Pages "Params.series" "golang" }} + {{ .Content }} +{{ end }} +``` + +It can also be used with the logical operators `!=`, `>=`, `in`, etc. Without an operator, `where` compares a given field with a matching value equivalent to `=`. + - ``` ++```go-html-template +{{ range where .Data.Pages "Section" "!=" "post" }} + {{ .Content }} +{{ end }} +``` + +The following logical operators are available with `where`: + +`=`, `==`, `eq` +: `true` if a given field value equals a matching value + +`!=`, `<>`, `ne` +: `true` if a given field value doesn't equal a matching value + +`>=`, `ge` +: `true` if a given field value is greater than or equal to a matching value + +`>`, `gt` +: `true` if a given field value is greater than a matching value + +`<=`, `le` +: `true` if a given field value is lesser than or equal to a matching value + +`<`, `lt` +: `true` if a given field value is lesser than a matching value + +`in` +: `true` if a given field value is included in a matching value; a matching value must be an array or a slice + +`not in` +: `true` if a given field value isn't included in a matching value; a matching value must be an array or a slice + +`intersect` +: `true` if a given field value that is a slice/array of strings or integers contains elements in common with the matching value; it follows the same rules as the [`intersect` function][intersect]. + +## Use `where` with `intersect` + - ``` ++```go-html-template +{{ range where .Site.Pages ".Params.tags" "intersect" .Params.tags }} + {{ if ne .Permalink $.Permalink }} + {{ .Render "summary" }} + {{ end }} +{{ end }} +``` + +You can also put the returned value of the `where` clauses into a variable: + +{{< code file="where-intersect-variables.html" >}} +{{ $v1 := where .Site.Pages "Params.a" "v1" }} +{{ $v2 := where .Site.Pages "Params.b" "v2" }} +{{ $filtered := $v1 | intersect $v2 }} +{{ range $filtered }} +{{ end }} +{{< /code >}} + +## Use `where` with `first` + +The following grabs the first five content files in `post` using the [default ordering](/templates/lists/) for lists (i.e., `weight => date`): + +{{< code file="where-with-first.html" >}} +{{ range first 5 (where .Data.Pages "Section" "post") }} + {{ .Content }} +{{ end }} +{{< /code >}} + +## Nest `where` Clauses + +You can also nest `where` clauses to drill down on lists of content by more than one parameter. The following first grabs all pages in the "blog" section and then ranges through the result of the first `where` clause and finds all pages that are *not* featured: + - ``` ++```go-html-template +{{ range where (where .Data.Pages "Section" "blog" ) ".Params.featured" "!=" "true" }} +``` + +## Unset Fields + +Filtering only works for set fields. To check whether a field is set or exists, you can use the operand `nil`. + +This can be useful to filter a small amount of pages from a large pool. Instead of set field on all pages, you can set field on required pages only. + +Only the following operators are available for `nil` + +* `=`, `==`, `eq`: True if the given field is not set. +* `!=`, `<>`, `ne`: True if the given field is set. + - ``` ++```go-html-template +{{ range where .Data.Pages ".Params.specialpost" "!=" nil }} + {{ .Content }} +{{ end }} +``` + +## Portable `where` filters + +This is especially important for themes, but to list the most relevant pages on the front page or similar, you can use `.Site.Params.mainSections` list. + +This will, by default, list pages from the _section with the most pages_. + - ```html ++```go-html-template +{{ $pages := where .Site.RegularPages "Type" "in" .Site.Params.mainSections }} +``` + +The user can override the default in `config.toml`: + +```toml +[params] +mainSections = ["blog", "docs"] +``` + +[intersect]: /functions/intersect/ diff --cc docs/content/getting-started/code-toggle.md index ae3e3e84,00000000..3e6b7da0 mode 100644,000000..100644 --- a/docs/content/getting-started/code-toggle.md +++ b/docs/content/getting-started/code-toggle.md @@@ -1,75 -1,0 +1,75 @@@ +--- +title: Code Toggle +description: Code Toggle tryout and showcase. +date: 2018-03-16 +categories: [getting started,fundamentals] +keywords: [configuration,toml,yaml,json] +weight: 60 +sections_weight: 60 +draft: false +toc: true +--- + +## The Config Toggler! + +This is an exemple for the Config Toggle shortcode. +Its purpose is to let users choose a Config language by clicking on its corresponding tab. Upon doing so, every Code toggler on the page will be switched to the target language. Also, target language will be saved in user's `localStorage` so when they go to a different pages, Code Toggler display their last "toggled" config language. + - ## That Congig Toggler ++## That Config Toggler + +{{< code-toggle file="config">}} + +baseURL: "https://yoursite.example.com/" +title: "My Hugo Site" +footnoteReturnLinkContents: "↩" +permalinks: + post: /:year/:month/:title/ +params: + Subtitle: "Hugo is Absurdly Fast!" + AuthorName: "Jon Doe" + GitHubUser: "spf13" + ListOfFoo: + - "foo1" + - "foo2" + SidebarRecentLimit: 5 +{{< /code-toggle >}} + +## Another Config Toggler! + +{{< code-toggle file="theme">}} + +# theme.toml template for a Hugo theme + +name = "Hugo Theme" +license = "MIT" +licenselink = "https://github.com/budparr/gohugo.io/blob/master/LICENSE.md" +description = "" +homepage = "https://github.com/budparr/gohugo.io" +tags = ["website"] +features = ["", ""] +min_version = 0.18 + +[author] + name = "Bud Parr" + homepage = "https://github.com/budparr" + +{{< /code-toggle >}} + +## Two regular code blocks + +{{< code file="bf-config.toml" >}} +[blackfriday] + angledQuotes = true + fractions = false + plainIDAnchors = true + extensions = ["hardLineBreak"] +{{< /code >}} + +{{< code file="bf-config.yml" >}} +blackfriday: + angledQuotes: true + fractions: false + plainIDAnchors: true + extensions: + - hardLineBreak - {{< /code >}} ++{{< /code >}} diff --cc docs/content/getting-started/configuration.md index ba2c87e8,00000000..8da25fd5 mode 100644,000000..100644 --- a/docs/content/getting-started/configuration.md +++ b/docs/content/getting-started/configuration.md @@@ -1,453 -1,0 +1,404 @@@ +--- +title: Configure Hugo +linktitle: Configuration +description: How to configure your Hugo site. +date: 2013-07-01 +publishdate: 2017-01-02 +lastmod: 2017-03-05 +categories: [getting started,fundamentals] +keywords: [configuration,toml,yaml,json] +menu: + docs: + parent: "getting-started" + weight: 60 +weight: 60 +sections_weight: 60 +draft: false +aliases: [/overview/source-directory/,/overview/configuration/] +toc: true +--- + +Hugo uses the `config.toml`, `config.yaml`, or `config.json` (if found in the +site root) as the default site config file. + +The user can choose to override that default with one or more site config files +using the command line `--config` switch. + +Examples: + +``` +hugo --config debugconfig.toml +hugo --config a.toml,b.toml,c.toml +``` + +{{% note %}} +Multiple site config files can be specified as a comma-separated string to the `--config` switch. +{{% /note %}} + +## All Configuration Settings + +The following is the full list of Hugo-defined variables with their default +value in parentheses. Users may choose to override those values in their site +config file(s). + +archetypeDir ("archetypes") +: The directory where Hugo finds archetype files (content templates). + +baseURL +: Hostname (and path) to the root, e.g. http://bep.is/ + +blackfriday +: See [Configure Blackfriday](/getting-started/configuration/#configure-blackfriday) + +buildDrafts (false) +: Include drafts when building. + +buildExpired (false) +: Include content already expired. + +buildFuture (false) +: Include content with publishdate in the future. + +canonifyURLs (false) +: Enable to turn relative URLs into absolute. + +contentDir ("content") +: The directory from where Hugo reads content files. + +dataDir ("data") +: The directory from where Hugo reads data files. + +defaultContentLanguage ("en") +: Content without language indicator will default to this language. + +defaultContentLanguageInSubdir (false) +: Render the default content language in subdir, e.g. `content/en/`. The site root `/` will then redirect to `/en/`. + +disableHugoGeneratorInject (false) +: Hugo will, by default, inject a generator meta tag in the HTML head on the _home page only_. You can turn it off, but we would really appreciate if you don't, as this is a good way to watch Hugo's popularity on the rise. + +disableKinds ([]) +: Enable disabling of all pages of the specified *Kinds*. Allowed values in this list: `"page"`, `"home"`, `"section"`, `"taxonomy"`, `"taxonomyTerm"`, `"RSS"`, `"sitemap"`, `"robotsTXT"`, `"404"`. + +disableLiveReload (false) +: Disable automatic live reloading of browser window. + +disablePathToLower (false) +: Do not convert the url/path to lowercase. + +enableEmoji (false) +: Enable Emoji emoticons support for page content; see the [Emoji Cheat Sheet](https://www.webpagefx.com/tools/emoji-cheat-sheet/). + +enableGitInfo (false) +: Enable `.GitInfo` object for each page (if the Hugo site is versioned by Git). This will then update the `Lastmod` parameter for each page using the last git commit date for that content file. + +enableMissingTranslationPlaceholders (false) +: Show a placeholder instead of the default value or an empty string if a translation is missing. + +enableRobotsTXT (false) +: Enable generation of `robots.txt` file. + +frontmatter + +: See [Front matter Configuration](#configure-front-matter). + +footnoteAnchorPrefix ("") +: Prefix for footnote anchors. + +footnoteReturnLinkContents ("") +: Text to display for footnote return links. + +googleAnalytics ("") +: Google Analytics tracking ID. + +hasCJKLanguage (false) +: If true, auto-detect Chinese/Japanese/Korean Languages in the content. This will make `.Summary` and `.WordCount` behave correctly for CJK languages. + +imaging +: See [Image Processing Config](/content-management/image-processing/#image-processing-config). + +languages +: See [Configure Languages](/content-management/multilingual/#configure-languages). + +languageCode ("") +: The site's language code. + +disableLanguages +: See [Disable a Language](/content-management/multilingual/#disable-a-language) + +layoutDir ("layouts") +: The directory from where Hugo reads layouts (templates). + +log (false) +: Enable logging. + +logFile ("") +: Log File path (if set, logging enabled automatically). + +menu +: See [Add Non-content Entries to a Menu](/content-management/menus/#add-non-content-entries-to-a-menu). + +metaDataFormat ("toml") +: Front matter meta-data format. Valid values: `"toml"`, `"yaml"`, or `"json"`. + +newContentEditor ("") +: The editor to use when creating new content. + +noChmod (false) +: Don't sync permission mode of files. + +noTimes (false) +: Don't sync modification time of files. + +paginate (10) +: Default number of pages per page in [pagination](/templates/pagination/). + +paginatePath ("page") +: The path element used during pagination (https://example.com/page/2). + +permalinks +: See [Content Management](/content-management/urls/#permalinks). + +pluralizeListTitles (true) +: Pluralize titles in lists. + +preserveTaxonomyNames (false) +: Preserve special characters in taxonomy names ("Gérard Depardieu" vs "Gerard Depardieu"). + +publishDir ("public") +: The directory to where Hugo will write the final static site (the HTML files etc.). + +pygmentsCodeFencesGuessSyntax (false) +: Enable syntax guessing for code fences without specified language. + +pygmentsStyle ("monokai") +: Color-theme or style for syntax highlighting. See [Pygments Color Themes](https://help.farbox.com/pygments.html). + +pygmentsUseClasses (false) +: Enable using external CSS for syntax highlighting. + +related +: See [Related Content](/content-management/related/#configure-related-content). + +relativeURLs (false) +: Enable this to make all relative URLs relative to content root. Note that this does not affect absolute URLs. + +rssLimit (unlimited) +: Maximum number of items in the RSS feed. + +sectionPagesMenu ("") +: See ["Section Menu for Lazy Bloggers"](/templates/menu-templates/#section-menu-for-lazy-bloggers). + +sitemap +: Default [sitemap configuration](/templates/sitemap-template/#configure-sitemap-xml). + +staticDir ("static") +: Relative directory from where Hugo reads static files. + +stepAnalysis (false) +: Display memory and timing of different steps of the program. + +summaryLength (70) +: The length of text to show in a [`.Summary`](/content-management/summaries/#hugo-defined-automatic-summary-splitting). + +taxonomies +: See [Configure Taxonomies](/content-management/taxonomies#configure-taxonomies). + +theme ("") +: Theme to use (located by default in `/themes/THEMENAME/`). + +themesDir ("themes") +: The directory where Hugo reads the themes from. + +title ("") +: Site title. + +uglyURLs (false) +: When enabled, creates URL of the form `/filename.html` instead of `/filename/`. + +verbose (false) +: Enable verbose output. + +verboseLog (false) +: Enable verbose logging. + +watch (false) +: Watch filesystem for changes and recreate as needed. + +{{% note %}} +If you are developing your site on a \*nix machine, here is a handy shortcut for finding a configuration option from the command line: +``` +cd ~/sites/yourhugosite +hugo config | grep emoji +``` + +which shows output like + +``` +enableemoji: true +``` +{{% /note %}} + +## Configuration Lookup Order + +Similar to the template [lookup order][], Hugo has a default set of rules for searching for a configuration file in the root of your website's source directory as a default behavior: + +1. `./config.toml` +2. `./config.yaml` +3. `./config.json` + +In your `config` file, you can direct Hugo as to how you want your website rendered, control your website's menus, and arbitrarily define site-wide parameters specific to your project. + + - ## YAML Configuration ++## Example Configuration + - {{< code file="config.yml">}} - baseURL: "https://yoursite.example.com/" - title: "My Hugo Site" - footnoteReturnLinkContents: "↩" - permalinks: - post: /:year/:month/:title/ - params: - Subtitle: "Hugo is Absurdly Fast!" - AuthorName: "Jon Doe" - GitHubUser: "spf13" - ListOfFoo: - - "foo1" - - "foo2" - SidebarRecentLimit: 5 - {{< /code >}} - - The following is a typical example of a YAML configuration file. The values nested under `params:` will populate the [`.Site.Params`][] variable for use in [templates][]: ++The following is a typical example of a configuration file. The values nested under `params:` will populate the [`.Site.Params`][] variable for use in [templates][]: + - {{< code file="config.yml">}} ++{{< code-toggle file="config">}} +baseURL: "https://yoursite.example.com/" +title: "My Hugo Site" +footnoteReturnLinkContents: "↩" +permalinks: + post: /:year/:month/:title/ +params: + Subtitle: "Hugo is Absurdly Fast!" + AuthorName: "Jon Doe" + GitHubUser: "spf13" + ListOfFoo: + - "foo1" + - "foo2" + SidebarRecentLimit: 5 - {{< /code >}} - - ## TOML Configuration - - The following is an example of a TOML configuration file. The values under `[params]` will populate the `.Site.Params` variable for use in [templates][]: - - {{< code file="config.toml">}} - contentDir = "content" - layoutDir = "layouts" - publishDir = "public" - buildDrafts = false - baseURL = "https://yoursite.example.com/" - canonifyURLs = true - title = "My Hugo Site" - - [taxonomies] - category = "categories" - tag = "tags" - - [params] - subtitle = "Hugo is Absurdly Fast!" - author = "John Doe" - {{< /code >}} - - ++{{< /code-toggle >}} + +## Configure with Environment Variables + +In addition to the 3 config options already mentioned, configuration key-values can be defined through operating system environment variables. + +For example, the following command will effectively set a website's title on Unix-like systems: + +``` +$ env HUGO_TITLE="Some Title" hugo +``` + +This is really useful if you use a service such as Netlify to deploy your site. Look at the Hugo docs [Netlify configuration file](https://github.com/gohugoio/hugoDocs/blob/master/netlify.toml) for an example. + +{{% note "Setting Environment Variables" %}} +Names must be prefixed with `HUGO_` and the configuration key must be set in uppercase when setting operating system environment variables. +{{% /note %}} + +{{< todo >}} +Test and document setting params via JSON env var. +{{< /todo >}} + +## Ignore Files When Rendering + +The following statement inside `./config.toml` will cause Hugo to ignore files ending with `.foo` and `.boo` when rendering: + +``` +ignoreFiles = [ "\\.foo$", "\\.boo$" ] +``` + +The above is a list of regular expressions. Note that the backslash (`\`) character is escaped in this example to keep TOML happy. + +## Configure Front Matter + +### Configure Dates + +Dates are important in Hugo, and you can configure how Hugo assigns dates to your content pages. You do this by adding a `frontmatter` section to your `config.toml`. + + +The default configuration is: + +```toml +[frontmatter] +date = ["date","publishDate", "lastmod"] +lastmod = [":git" "lastmod", "date","publishDate"] +publishDate = ["publishDate", "date"] +expiryDate = ["expiryDate"] +``` + +If you, as an example, have a non-standard date parameter in some of your content, you can override the setting for `date`: + + ```toml +[frontmatter] +date = [ "myDate", ":default"] +``` + +The `:default` is a shortcut to the default settings. The above will set `.Date` to the date value in `myDate` if present, if not we will look in `date`,`publishDate`, `lastmod` and pick the first valid date. + +In the list to the right, values starting with ":" are date handlers with a special meaning (see below). The others are just names of date parameters (case insensitive) in your front matter configuration. Also note that Hugo have some built-in aliases to the above: `lastmod` => `modified`, `publishDate` => `pubdate`, `published` and `expiryDate` => `unpublishdate`. With that, as an example, using `pubDate` as a date in front matter, will, by default, be assigned to `.PublishDate`. + +The special date handlers are: + + +`:fileModTime` +: Fetches the date from the content file's last modification timestamp. + +An example: + + ```toml +[frontmatter] +lastmod = ["lastmod" ,":fileModTime", ":default"] +``` + + +The above will try first to extract the value for `.Lastmod` starting with the `lastmod` front matter parameter, then the content file's modification timestamp. The last, `:default` should not be needed here, but Hugo will finally look for a valid date in `:git`, `date` and then `publishDate`. + + +`:filename` +: Fetches the date from the content file's filename. For example, `218-02-22-mypage.md` will extract the date `218-02-22`. Also, if `slug is not set, `mypage` will be used as the value for `.Slug`. + +An example: + +```toml +[frontmatter] +date = [":filename", ":default"] +``` + +The above will try first to extract the value for `.Date` from the filename, then it will look in front matter parameters `date`, `publishDate` and lastly `lastmod`. + + +`:git` +: This is the Git author date for the last revision of this content file. This will only be set if `--enableGitInfo` is set or `enableGitInfo = true` is set in site config. + +## Configure Blackfriday + +[Blackfriday](https://github.com/russross/blackfriday) is Hugo's built-in Markdown rendering engine. + +Hugo typically configures Blackfriday with sane default values that should fit most use cases reasonably well. + +However, if you have specific needs with respect to Markdown, Hugo exposes some of its Blackfriday behavior options for you to alter. The following table lists these Hugo options, paired with the corresponding flags from Blackfriday's source code ( [html.go](https://github.com/russross/blackfriday/blob/master/html.go) and [markdown.go](https://github.com/russross/blackfriday/blob/master/markdown.go)). + +{{< readfile file="/content/readfiles/bfconfig.md" markdown="true" >}} + +{{% note %}} +1. Blackfriday flags are *case sensitive* as of Hugo v0.15. +2. Blackfriday flags must be grouped under the `blackfriday` key and can be set on both the site level *and* the page level. Any setting on a page will override its respective site setting. +{{% /note %}} + - {{< code file="bf-config.toml" >}} ++{{< code-toggle file="config" >}} +[blackfriday] + angledQuotes = true + fractions = false + plainIDAnchors = true + extensions = ["hardLineBreak"] - {{< /code >}} - - {{< code file="bf-config.yml" >}} - blackfriday: - angledQuotes: true - fractions: false - plainIDAnchors: true - extensions: - - hardLineBreak - {{< /code >}} ++{{< /code-toggle >}} + +## Configure Additional Output Formats + +Hugo v0.20 introduced the ability to render your content to multiple output formats (e.g., to JSON, AMP html, or CSV). See [Output Formats][] for information on how to add these values to your Hugo project's configuration file. + +## Configuration Format Specs + +* [TOML Spec][toml] +* [YAML Spec][yaml] +* [JSON Spec][json] + +[`.Site.Params`]: /variables/site/ +[directory structure]: /getting-started/directory-structure +[json]: https://www.ecma-international.org/publications/files/ECMA-ST/ECMA-404.pdf "Specification for JSON, JavaScript Object Notation" +[lookup order]: /templates/lookup-order/ +[Output Formats]: /templates/output-formats/ +[templates]: /templates/ +[toml]: https://github.com/toml-lang/toml +[yaml]: http://yaml.org/spec/ diff --cc docs/content/news/0.27-relnotes-ready.md index 3dd02d45,00000000..9251c376 mode 100644,000000..100644 --- a/docs/content/news/0.27-relnotes-ready.md +++ b/docs/content/news/0.27-relnotes-ready.md @@@ -1,93 -1,0 +1,93 @@@ + +--- +date: 2017-09-11 +title: "0.27" +description: "0.27" +categories: ["Releases"] +--- + + +Hugo `0.27`comes with fast and flexible **Related Content** ([3b4f17bb](https://github.com/gohugoio/hugo/commit/3b4f17bbc9ff789faa581ac278ad109d1ac5b816) [@bep](https://github.com/bep) [#98](https://github.com/gohugoio/hugo/issues/98)). To add this to your site, put something like this in your single page template: + - ```html ++```go-html-template +{{ $related := .Site.RegularPages.Related . | first 5 }} +{{ with $related }} +

    See Also

    + +{{ end }} +``` + +The above translates to _list the five regular pages mostly related to the current page_. See the [Related Content Documentation](https://gohugo.io/content-management/related/) for details and configuration options. + +This release represents **37 contributions by 9 contributors** to the main Hugo code base. + +[@bep](https://github.com/bep) leads the Hugo development with a significant amount of contributions, but also a big shoutout to [@moorereason](https://github.com/moorereason), [@yihui](https://github.com/yihui), and [@oneleaftea](https://github.com/oneleaftea) for their ongoing contributions. + +And as always a big thanks to [@digitalcraftsman](https://github.com/digitalcraftsman) for his relentless work on keeping the documentation and the themes site in pristine condition. + +Many have also been busy writing and fixing the documentation in [hugoDocs](https://github.com/gohugoio/hugoDocs), +which has received **44 contributions by 30 contributors**. A special thanks to [@bep](https://github.com/bep), [@sdomino](https://github.com/sdomino), [@gotgenes](https://github.com/gotgenes), and [@digitalcraftsman](https://github.com/digitalcraftsman) for their work on the documentation site. + + +Hugo now has: + +* 19464+ [stars](https://github.com/gohugoio/hugo/stargazers) +* 455+ [contributors](https://github.com/gohugoio/hugo/graphs/contributors) +* 178+ [themes](http://themes.gohugo.io/) + +## Notes + +* We now only strip p tag in `markdownify` if there is only one paragraph. This allows blocks of paragraphs to be "markdownified" [33ae10b6](https://github.com/gohugoio/hugo/commit/33ae10b6ade67cd9618970121d7de5fd2ce7d781) [@bep](https://github.com/bep) [#3040](https://github.com/gohugoio/hugo/issues/3040) + +## Enhancements + +### Templates + +* Add `time.Duration` and `time.ParseDuration` template funcs [f4bf2141](https://github.com/gohugoio/hugo/commit/f4bf214137ebd24a0d12f16d3a98d9038e6eabd3) [@bep](https://github.com/bep) [#3828](https://github.com/gohugoio/hugo/issues/3828) +* Add `cond` (ternary) template func [0462c96a](https://github.com/gohugoio/hugo/commit/0462c96a5a9da3e8adc78d96acd39575a8b46c40) [@bep](https://github.com/bep) [#3860](https://github.com/gohugoio/hugo/issues/3860) +* Prepare for template metrics [d000cf60](https://github.com/gohugoio/hugo/commit/d000cf605091c6999b72d6c632752289bc680223) [@bep](https://github.com/bep) +* Add `strings.TrimLeft` and `TrimRight` [7674ad73](https://github.com/gohugoio/hugo/commit/7674ad73825c61eecc4003475fe0577f225fe579) [@moorereason](https://github.com/moorereason) +* compare, hugolib, tpl: Add `Eqer` interface [08f48b91](https://github.com/gohugoio/hugo/commit/08f48b91d68d3002b887ddf737456ff0cc4e786d) [@bep](https://github.com/bep) [#3807](https://github.com/gohugoio/hugo/issues/3807) +* Only strip p tag in `markdownify` if only one paragraph [33ae10b6](https://github.com/gohugoio/hugo/commit/33ae10b6ade67cd9618970121d7de5fd2ce7d781) [@bep](https://github.com/bep) [#3040](https://github.com/gohugoio/hugo/issues/3040) +* Cleanup `strings.TrimPrefix` and `TrimSuffix` [29a2da05](https://github.com/gohugoio/hugo/commit/29a2da0593b081cdd61b93c6328af2c9ea4eb20f) [@moorereason](https://github.com/moorereason) + +### Output + +* Improve the base template (aka `baseof.html`) identification [0019ce00](https://github.com/gohugoio/hugo/commit/0019ce002449d671a20a69406da37b10977f9493) [@bep](https://github.com/bep) + +### Core + +* Implement "related content" [3b4f17bb](https://github.com/gohugoio/hugo/commit/3b4f17bbc9ff789faa581ac278ad109d1ac5b816) [@bep](https://github.com/bep) [#98](https://github.com/gohugoio/hugo/issues/98) +* Add `Page.Equals` [f0f49ed9](https://github.com/gohugoio/hugo/commit/f0f49ed9b0c9b4545a45c95d56340fcbf4aafbef) [@bep](https://github.com/bep) +* Rewrite `replaceDivider` to reduce memory allocation [71ae9b45](https://github.com/gohugoio/hugo/commit/71ae9b4533083be185c5314c9c5b273cc3bd07bd) [@bep](https://github.com/bep) + + +### Other + +* Set up Hugo release flow on `CircleCI` [d2249c50](https://github.com/gohugoio/hugo/commit/d2249c50991ba7b00b092aca6e315ca1a4de75a1) [@bep](https://github.com/bep) [#3779](https://github.com/gohugoio/hugo/issues/3779) +* Maintain the scroll position if possible [7231d5a8](https://github.com/gohugoio/hugo/commit/7231d5a829f8d97336a2120afde1260db6ee6541) [@yihui](https://github.com/yihui) [#3824](https://github.com/gohugoio/hugo/issues/3824) +* Add an `iFrame` title to the `YouTube` shortcode [919bc921](https://github.com/gohugoio/hugo/commit/919bc9210a69c801c7304c0b529df93d1dca27aa) [@nraboy](https://github.com/nraboy) +* Remove the theme submodule from /docs [ea2cc26b](https://github.com/gohugoio/hugo/commit/ea2cc26b390476f1c605405604f8c92afd09b6ee) [@bep](https://github.com/bep) [#3791](https://github.com/gohugoio/hugo/issues/3791) +* Add support for multiple config files via `--config a.toml,b.toml,c.toml` [0f9f73cc](https://github.com/gohugoio/hugo/commit/0f9f73cce5c3f1f05be20bcf1d23b2332623d7f9) [@jgielstra](https://github.com/jgielstra) +* Render task list item inside `label` for correct accessibility [c8257f8b](https://github.com/gohugoio/hugo/commit/c8257f8b726478ca70dc8984cdcc17b31e4bdc0c) [@danieka](https://github.com/danieka) [#3303](https://github.com/gohugoio/hugo/issues/3303) +* Normalize `UniqueID` between Windows & Linux [0abdeeef](https://github.com/gohugoio/hugo/commit/0abdeeef6740a3cbba0db95374853d040f2022b8) [@Shywim](https://github.com/Shywim) + + +## Fixes + +### Output + +* Fix taxonomy term base template lookup [f88fe312](https://github.com/gohugoio/hugo/commit/f88fe312cb35f7de1615c095edd2f898303dd23b) [@bep](https://github.com/bep) [#3856](https://github.com/gohugoio/hugo/issues/3856) +* Fix `published` front matter handling [202510fd](https://github.com/gohugoio/hugo/commit/202510fdc92d52a20baeaa7edb1091f6882bd95f) [@bep](https://github.com/bep) [#3867](https://github.com/gohugoio/hugo/issues/3867) + + + + + + + + diff --cc docs/content/news/0.27-relnotes.md index a4ead081,00000000..92fc3a7b mode 100644,000000..100644 --- a/docs/content/news/0.27-relnotes.md +++ b/docs/content/news/0.27-relnotes.md @@@ -1,95 -1,0 +1,95 @@@ + +--- +date: 2017-09-11 +title: "Hugo 0.27: Fast and Flexible Related Content!" +description: "Makes it easy to add \"See Also\" sections etc. to your site." +categories: ["Releases"] +images: +- images/blog/hugo-27-poster.png +--- + + +Hugo `0.27`comes with fast and flexible **Related Content** ([3b4f17bb](https://github.com/gohugoio/hugo/commit/3b4f17bbc9ff789faa581ac278ad109d1ac5b816) [@bep](https://github.com/bep) [#98](https://github.com/gohugoio/hugo/issues/98)). To add this to your site, put something like this in your single page template: + - ```html ++```go-html-template +{{ $related := .Site.RegularPages.Related . | first 5 }} +{{ with $related }} +

    See Also

    + +{{ end }} +``` + +The above translates to _list the five regular pages mostly related to the current page_. See the [Related Content Documentation](https://gohugo.io/content-management/related/) for details and configuration options. + +This release represents **37 contributions by 9 contributors** to the main Hugo code base. + +[@bep](https://github.com/bep) leads the Hugo development with a significant amount of contributions, but also a big shoutout to [@moorereason](https://github.com/moorereason), [@yihui](https://github.com/yihui), and [@oneleaftea](https://github.com/oneleaftea) for their ongoing contributions. + +And as always a big thanks to [@digitalcraftsman](https://github.com/digitalcraftsman) for his relentless work on keeping the documentation and the themes site in pristine condition. + +Many have also been busy writing and fixing the documentation in [hugoDocs](https://github.com/gohugoio/hugoDocs), +which has received **44 contributions by 30 contributors**. A special thanks to [@bep](https://github.com/bep), [@sdomino](https://github.com/sdomino), [@gotgenes](https://github.com/gotgenes), and [@digitalcraftsman](https://github.com/digitalcraftsman) for their work on the documentation site. + + +Hugo now has: + +* 19464+ [stars](https://github.com/gohugoio/hugo/stargazers) +* 455+ [contributors](https://github.com/gohugoio/hugo/graphs/contributors) +* 178+ [themes](http://themes.gohugo.io/) + +## Notes + +* We now only strip p tag in `markdownify` if there is only one paragraph. This allows blocks of paragraphs to be "markdownified" [33ae10b6](https://github.com/gohugoio/hugo/commit/33ae10b6ade67cd9618970121d7de5fd2ce7d781) [@bep](https://github.com/bep) [#3040](https://github.com/gohugoio/hugo/issues/3040) + +## Enhancements + +### Templates + +* Add `time.Duration` and `time.ParseDuration` template funcs [f4bf2141](https://github.com/gohugoio/hugo/commit/f4bf214137ebd24a0d12f16d3a98d9038e6eabd3) [@bep](https://github.com/bep) [#3828](https://github.com/gohugoio/hugo/issues/3828) +* Add `cond` (ternary) template func [0462c96a](https://github.com/gohugoio/hugo/commit/0462c96a5a9da3e8adc78d96acd39575a8b46c40) [@bep](https://github.com/bep) [#3860](https://github.com/gohugoio/hugo/issues/3860) +* Prepare for template metrics [d000cf60](https://github.com/gohugoio/hugo/commit/d000cf605091c6999b72d6c632752289bc680223) [@bep](https://github.com/bep) +* Add `strings.TrimLeft` and `TrimRight` [7674ad73](https://github.com/gohugoio/hugo/commit/7674ad73825c61eecc4003475fe0577f225fe579) [@moorereason](https://github.com/moorereason) +* compare, hugolib, tpl: Add `Eqer` interface [08f48b91](https://github.com/gohugoio/hugo/commit/08f48b91d68d3002b887ddf737456ff0cc4e786d) [@bep](https://github.com/bep) [#3807](https://github.com/gohugoio/hugo/issues/3807) +* Only strip p tag in `markdownify` if only one paragraph [33ae10b6](https://github.com/gohugoio/hugo/commit/33ae10b6ade67cd9618970121d7de5fd2ce7d781) [@bep](https://github.com/bep) [#3040](https://github.com/gohugoio/hugo/issues/3040) +* Cleanup `strings.TrimPrefix` and `TrimSuffix` [29a2da05](https://github.com/gohugoio/hugo/commit/29a2da0593b081cdd61b93c6328af2c9ea4eb20f) [@moorereason](https://github.com/moorereason) + +### Output + +* Improve the base template (aka `baseof.html`) identification [0019ce00](https://github.com/gohugoio/hugo/commit/0019ce002449d671a20a69406da37b10977f9493) [@bep](https://github.com/bep) + +### Core + +* Implement "related content" [3b4f17bb](https://github.com/gohugoio/hugo/commit/3b4f17bbc9ff789faa581ac278ad109d1ac5b816) [@bep](https://github.com/bep) [#98](https://github.com/gohugoio/hugo/issues/98) +* Add `Page.Equals` [f0f49ed9](https://github.com/gohugoio/hugo/commit/f0f49ed9b0c9b4545a45c95d56340fcbf4aafbef) [@bep](https://github.com/bep) +* Rewrite `replaceDivider` to reduce memory allocation [71ae9b45](https://github.com/gohugoio/hugo/commit/71ae9b4533083be185c5314c9c5b273cc3bd07bd) [@bep](https://github.com/bep) + + +### Other + +* Set up Hugo release flow on `CircleCI` [d2249c50](https://github.com/gohugoio/hugo/commit/d2249c50991ba7b00b092aca6e315ca1a4de75a1) [@bep](https://github.com/bep) [#3779](https://github.com/gohugoio/hugo/issues/3779) +* Maintain the scroll position if possible [7231d5a8](https://github.com/gohugoio/hugo/commit/7231d5a829f8d97336a2120afde1260db6ee6541) [@yihui](https://github.com/yihui) [#3824](https://github.com/gohugoio/hugo/issues/3824) +* Add an `iFrame` title to the `YouTube` shortcode [919bc921](https://github.com/gohugoio/hugo/commit/919bc9210a69c801c7304c0b529df93d1dca27aa) [@nraboy](https://github.com/nraboy) +* Remove the theme submodule from /docs [ea2cc26b](https://github.com/gohugoio/hugo/commit/ea2cc26b390476f1c605405604f8c92afd09b6ee) [@bep](https://github.com/bep) [#3791](https://github.com/gohugoio/hugo/issues/3791) +* Add support for multiple config files via `--config a.toml,b.toml,c.toml` [0f9f73cc](https://github.com/gohugoio/hugo/commit/0f9f73cce5c3f1f05be20bcf1d23b2332623d7f9) [@jgielstra](https://github.com/jgielstra) +* Render task list item inside `label` for correct accessibility [c8257f8b](https://github.com/gohugoio/hugo/commit/c8257f8b726478ca70dc8984cdcc17b31e4bdc0c) [@danieka](https://github.com/danieka) [#3303](https://github.com/gohugoio/hugo/issues/3303) +* Normalize `UniqueID` between Windows & Linux [0abdeeef](https://github.com/gohugoio/hugo/commit/0abdeeef6740a3cbba0db95374853d040f2022b8) [@Shywim](https://github.com/Shywim) + + +## Fixes + +### Output + +* Fix taxonomy term base template lookup [f88fe312](https://github.com/gohugoio/hugo/commit/f88fe312cb35f7de1615c095edd2f898303dd23b) [@bep](https://github.com/bep) [#3856](https://github.com/gohugoio/hugo/issues/3856) +* Fix `published` front matter handling [202510fd](https://github.com/gohugoio/hugo/commit/202510fdc92d52a20baeaa7edb1091f6882bd95f) [@bep](https://github.com/bep) [#3867](https://github.com/gohugoio/hugo/issues/3867) + + + + + + + + diff --cc docs/content/news/0.35-relnotes/index.md index 6ce614df,00000000..80b4afd7 mode 100644,000000..100644 --- a/docs/content/news/0.35-relnotes/index.md +++ b/docs/content/news/0.35-relnotes/index.md @@@ -1,102 -1,0 +1,102 @@@ + +--- +date: 2018-01-31 +title: "Hugo 0.35: Headless Bundles!" +description: "Headless Bundles, disable languages, improves fast render mode, and much more." +categories: ["Releases"] +--- + +The most notable new feature in Hugo `0.35` is perhaps **Headless Bundles**. + +This means that you in your `index.md` front matter can say: + +```yaml +headless: true +``` +And + +* it will have no `Permalink` and no rendered HTML in `/public` +* it will not be part of `.Site.RegularPages` etc. + +But you can get it by: + +* `.Site.GetPage ...` + +The use cases are many: + +* Shared media libraries +* Reusable page content "snippets" +* ... + +But this release contains more goodies than possible to sum up in one paragraph, so study the release notes carefully. It represents **42 contributions by 8 contributors** to the main Hugo code base. + +[@bep](https://github.com/bep) leads the Hugo development with a significant amount of contributions, but also a big shoutout to [@vassudanagunta](https://github.com/vassudanagunta), [@yanzay](https://github.com/yanzay), and [@robertbasic](https://github.com/robertbasic) for their ongoing contributions. + +And as always a big thanks to [@digitalcraftsman](https://github.com/digitalcraftsman) for his relentless work on keeping the documentation and the themes site in pristine condition. + +Many have also been busy writing and fixing the documentation in [hugoDocs](https://github.com/gohugoio/hugoDocs), +which has received **28 contributions by 5 contributors**. A special thanks to [@bep](https://github.com/bep), [@kaushalmodi](https://github.com/kaushalmodi), [@regisphilibert](https://github.com/regisphilibert), and [@salim-b](https://github.com/salim-b) for their work on the documentation site. + + +Hugo now has: + +* 22967+ [stars](https://github.com/gohugoio/hugo/stargazers) +* 448+ [contributors](https://github.com/gohugoio/hugo/graphs/contributors) +* 197+ [themes](http://themes.gohugo.io/) + + +## Notes + +* Deprecate `useModTimeAsFallback` [adfd4370](https://github.com/gohugoio/hugo/commit/adfd4370b67fd7181178bd6b3b1d07356beaac71) [@bep](https://github.com/bep) [#4351](https://github.com/gohugoio/hugo/issues/4351) +* Deprecate CLI flags `canonifyURLs`, `pluralizeListTitles`, `preserveTaxonomyNames`, `uglyURLs` [f08ea02d](https://github.com/gohugoio/hugo/commit/f08ea02d24d42929676756950f3affaca7fd8c01) [@bep](https://github.com/bep) [#4347](https://github.com/gohugoio/hugo/issues/4347) +* Remove undraft command [2fa70c93](https://github.com/gohugoio/hugo/commit/2fa70c9344b231c9d999bbafdfa4acbf27ed9f6e) [@robertbasic](https://github.com/robertbasic) [#4353](https://github.com/gohugoio/hugo/issues/4353) + +## Enhancements + +### Templates + +* Update Twitter card to also consider images in `.Resources` [25d691da](https://github.com/gohugoio/hugo/commit/25d691daff57d7c6d7d0f63af3991d22e3f788fe) [@bep](https://github.com/bep) [#4349](https://github.com/gohugoio/hugo/issues/4349) +* Seed random on init only [83c761b7](https://github.com/gohugoio/hugo/commit/83c761b71a980aee6331179b271c7e24e999e8eb) [@liguoqinjim](https://github.com/liguoqinjim) +* Remove duplicate layout lookup layouts [b2fcbb1f](https://github.com/gohugoio/hugo/commit/b2fcbb1f9774aa1e929b8575c0e1ac366ab2fb73) [@bep](https://github.com/bep) [#4319](https://github.com/gohugoio/hugo/issues/4319) +* Add "removable-media" interface to `snapcraft.yaml` [f0c0ece4](https://github.com/gohugoio/hugo/commit/f0c0ece44d55b6c2997cbd106d1bc099ea1a2fa7) [@anthonyfok](https://github.com/anthonyfok) [#3837](https://github.com/gohugoio/hugo/issues/3837) + +### Other + +* Add a way to disable one or more languages [6413559f](https://github.com/gohugoio/hugo/commit/6413559f7575e2653d76227a8037a7edbaae82aa) [@bep](https://github.com/bep) [#4297](https://github.com/gohugoio/hugo/issues/4297)[#4329](https://github.com/gohugoio/hugo/issues/4329) +* Handle newly created files in Fast Render Mode [1707dae8](https://github.com/gohugoio/hugo/commit/1707dae8d3634006017eb6d040df4dbafc53d92f) [@yanzay](https://github.com/yanzay) [#4339](https://github.com/gohugoio/hugo/issues/4339) +* Extract the Fast Render Mode logic into a method [94e736c5](https://github.com/gohugoio/hugo/commit/94e736c5e167a0ee70a528e1c19d64a47e7929c2) [@bep](https://github.com/bep) [#4339](https://github.com/gohugoio/hugo/issues/4339) +* Remove unused code [ae5a45be](https://github.com/gohugoio/hugo/commit/ae5a45be6f0ee4d5c52b38fd28b22b55d9cd7b2d) [@bep](https://github.com/bep) +* Add the last lookup variant for the `GetPage` index [3446fe9b](https://github.com/gohugoio/hugo/commit/3446fe9b8937610b8b628b2c212eb25888a7c1bb) [@bep](https://github.com/bep) [#4312](https://github.com/gohugoio/hugo/issues/4312) +* Simplify bundle lookup via `.Site.GetPage`, `ref`, `relref` [517b6b62](https://github.com/gohugoio/hugo/commit/517b6b62389d23bfe41fe3ae551a691b11bdcaa7) [@bep](https://github.com/bep) [#4312](https://github.com/gohugoio/hugo/issues/4312) +* Remove some now superflous Fast Render Mode code [feeed073](https://github.com/gohugoio/hugo/commit/feeed073c3320b09fb38168ce272ac88b987f1d2) [@bep](https://github.com/bep) [#4339](https://github.com/gohugoio/hugo/issues/4339) +* Make resource counters for `name` and `title` independent [df20b054](https://github.com/gohugoio/hugo/commit/df20b05463fef42aba93d5208e410a7ecc56da5d) [@bep](https://github.com/bep) [#4335](https://github.com/gohugoio/hugo/issues/4335) +* Provide .Name to the archetype templates [863a812e](https://github.com/gohugoio/hugo/commit/863a812e07193541b42732b0e227f3d320433f01) [@bep](https://github.com/bep) [#4348](https://github.com/gohugoio/hugo/issues/4348) +* Only set `url` if permalink in metadata and remove duplicate confirm msg [3752348e](https://github.com/gohugoio/hugo/commit/3752348ef13ced8f6f528b42ee7d76a12a97ae5c) [@lildude](https://github.com/lildude) [#1887](https://github.com/gohugoio/hugo/issues/1887) +* Start Resources :counter first time they're used [7b472e46](https://github.com/gohugoio/hugo/commit/7b472e46084b603045b87cea870ffc73ac1cf7e7) [@bep](https://github.com/bep) [#4335](https://github.com/gohugoio/hugo/issues/4335) +* Update to Go 1.9.3 [a91aba1c](https://github.com/gohugoio/hugo/commit/a91aba1c1562259dffd321a608f38c38dd4d5aeb) [@bep](https://github.com/bep) [#4328](https://github.com/gohugoio/hugo/issues/4328) - * Support pages without front matter [91bb774a](https://github.com/gohugoio/hugo/commit/91bb774ae4e129f7ed0624754b31479c960ef774) [@vassudanagunta](https://github.com/vassudanagunta) [#4320](https://github.com/gohugoio/hugo/issues/4320)[#4320](https://github.com/gohugoio/hugo/issues/4320) ++* Support pages without front matter [91bb774a](https://github.com/gohugoio/hugo/commit/91bb774ae4e129f7ed0624754b31479c960ef774) [@vassudanagunta](https://github.com/vassudanagunta) [#4320](https://github.com/gohugoio/hugo/issues/4320) +* Add page metadata dates tests [3f0379ad](https://github.com/gohugoio/hugo/commit/3f0379adb72389954ca2be6a9f2ebfcd65c6c440) [@vassudanagunta](https://github.com/vassudanagunta) +* Re-generate CLI docs [1e27d058](https://github.com/gohugoio/hugo/commit/1e27d0589118a114e49c032e4bd68b4798e44a5b) [@bep](https://github.com/bep) +* Remove and update deprecation status [d418c2c2](https://github.com/gohugoio/hugo/commit/d418c2c2eacdc1dc6fffe839e0a90600867878ca) [@bep](https://github.com/bep) +* Shorten the stale setup [4a7c2b36](https://github.com/gohugoio/hugo/commit/4a7c2b3695fe7b88861f2155ea7ef635fe425cd4) [@bep](https://github.com/bep) +* Add a `GetPage` to the site benchmarks [a1956391](https://github.com/gohugoio/hugo/commit/a19563910eec5fed08f3b02563b9a7b38026183d) [@bep](https://github.com/bep) +* Add headless bundle support [0432c64d](https://github.com/gohugoio/hugo/commit/0432c64dd22e4610302162678bb93661ba68d758) [@bep](https://github.com/bep) [#4311](https://github.com/gohugoio/hugo/issues/4311) +* Merge matching resources params maps [5a0819b9](https://github.com/gohugoio/hugo/commit/5a0819b9b5eb9e79826cfa0a65f235d9821b1ac4) [@bep](https://github.com/bep) [#4315](https://github.com/gohugoio/hugo/issues/4315) +* Add some general code contribution criterias [78c86330](https://github.com/gohugoio/hugo/commit/78c863305f337ed4faf3cf0a23675f28b0ae5641) [@bep](https://github.com/bep) +* Tighten page kind logic, introduce tests [8125b4b0](https://github.com/gohugoio/hugo/commit/8125b4b03d10eb73f8aea3f9ea41172aba8df082) [@vassudanagunta](https://github.com/vassudanagunta) + +## Fixes +* Fix `robots.txt` in multihost mode [4d912e2a](https://github.com/gohugoio/hugo/commit/4d912e2aad39bfe8d76672cf53b01317792e02c5) [@bep](https://github.com/bep) [#4193](https://github.com/gohugoio/hugo/issues/4193) +* Fix `--uglyURLs` from comand line regression [016398ff](https://github.com/gohugoio/hugo/commit/016398ffe2e0a073453cf46a9d6bf72d693c11e5) [@bep](https://github.com/bep) [#4343](https://github.com/gohugoio/hugo/issues/4343) +* Avoid unescape in `highlight` [ebdd8cba](https://github.com/gohugoio/hugo/commit/ebdd8cba3f5965a8ac897833f313d772271de649) [@bep](https://github.com/bep) [#4219](https://github.com/gohugoio/hugo/issues/4219) +* Fix Docker build [a34213f0](https://github.com/gohugoio/hugo/commit/a34213f0b5624de101272aab469ca9b6fe0c273f) [@skoblenick](https://github.com/skoblenick) [#4076](https://github.com/gohugoio/hugo/issues/4076)[#4077](https://github.com/gohugoio/hugo/issues/4077) +* Fix language params handling [ae742cb1](https://github.com/gohugoio/hugo/commit/ae742cb1bdf35b81aa0ede5453da6b0c4a4fccf2) [@bep](https://github.com/bep) [#4356](https://github.com/gohugoio/hugo/issues/4356)[#4352](https://github.com/gohugoio/hugo/issues/4352) +* Fix handling of top-level page bundles [4eb2fec6](https://github.com/gohugoio/hugo/commit/4eb2fec67c3a72a3ac98aa834dc56fd4504626d8) [@bep](https://github.com/bep) [#4332](https://github.com/gohugoio/hugo/issues/4332) +* Fix `baseURL` server regression for multilingual sites [ed4a00e4](https://github.com/gohugoio/hugo/commit/ed4a00e46f2344320a22f07febe5aec4075cb3fb) [@bep](https://github.com/bep) [#4333](https://github.com/gohugoio/hugo/issues/4333) +* Fix "date" page param [322c5672](https://github.com/gohugoio/hugo/commit/322c567220aa4123a5d707629c1bebd375599912) [@vassudanagunta](https://github.com/vassudanagunta) [#4323](https://github.com/gohugoio/hugo/issues/4323) +* Fix typo in comment [912147ab](https://github.com/gohugoio/hugo/commit/912147ab896e69a450b7100c3d6bf81a7bf78b5a) [@yanzay](https://github.com/yanzay) + + + + + diff --cc docs/content/news/0.38-relnotes/featured-poster.png index 00000000,00000000..1e7988c8 new file mode 100644 Binary files differ diff --cc docs/content/news/0.38-relnotes/index.md index 1bfa7e14,00000000..88ef8887 mode 100644,000000..100644 --- a/docs/content/news/0.38-relnotes/index.md +++ b/docs/content/news/0.38-relnotes/index.md @@@ -1,67 -1,0 +1,66 @@@ + +--- +date: 2018-04-02 - title: "0.38" - description: "0.38" ++title: "The Easter Egg Edition" ++description: "Hugo 0.38: Date and slug from filenames, multiple content dirs, config from themes, language merge func …" +categories: ["Releases"] +--- + - - - +Hugo `0.38` is an **Easter egg** filled with good stuff. We now support fetching **date and slug from the content filename**, making the move from Jekyll even easier. And you can now set `contentDir` per language with intelligent merging, and themes can now provide configuration ... Also worth mentioning is several improvements in the [Chroma](https://github.com/alecthomas/chroma) highlighter, most notable support for Go templates. + ++We are working hard to get the documentation up-to-date with the new features, but you can also see them in action with the full source at [hugotest.bep.is](http://hugotest.bep.is/). ++ +This release represents **39 contributions by 4 contributors** to the main Hugo code base. +[@bep](https://github.com/bep) leads the Hugo development with a significant amount of contributions, but also a big shoutout to [@anthonyfok](https://github.com/anthonyfok), [@felicianotech](https://github.com/felicianotech), and [@paulcmal](https://github.com/paulcmal) for their ongoing contributions. + +And a big thanks to [@digitalcraftsman](https://github.com/digitalcraftsman) for his relentless work on keeping the themes site in pristine condition and to [@kaushalmodi](https://github.com/kaushalmodi) for his great work on the documentation site. + +Also, a shoutout to [@regisphilibert](https://github.com/regisphilibert) for his work on the new [Code Toggle Shortcode](https://gohugo.io/getting-started/code-toggle/) on the Hugo docs site, which we will put to good use to improve all the configuration samples. + +Many have also been busy writing and fixing the documentation in [hugoDocs](https://github.com/gohugoio/hugoDocs), +which has received **55 contributions by 18 contributors**. A special thanks to [@kaushalmodi](https://github.com/kaushalmodi), [@bep](https://github.com/bep), [@xa0082249956](https://github.com/xa0082249956), and [@paulcmal](https://github.com/paulcmal) for their work on the documentation site. + + +Hugo now has: + +* 24547+ [stars](https://github.com/gohugoio/hugo/stargazers) +* 447+ [contributors](https://github.com/gohugoio/hugo/graphs/contributors) +* 213+ [themes](http://themes.gohugo.io/) + +## Notes + +* Hugo now allows partial redefinition `outputs` in your site configuration. This is what most people would expect, but it is still a change in behaviour. For details, see [#4487](https://github.com/gohugoio/hugo/issues/4487) +* Before this release, Hugo flattened URLs of processed images in sub-folders. This worked fine but was not intentional. See [#4502](https://github.com/gohugoio/hugo/issues/4502). + +## Enhancements + +* Allow themes to define output formats, media types and params [e9c7b620](https://github.com/gohugoio/hugo/commit/e9c7b6205f94a7edac0e0df2cd18d1456cb26a06) [@bep](https://github.com/bep) [#4490](https://github.com/gohugoio/hugo/issues/4490) +* Allow partial redefinition of the `ouputs` config [f8dc47ee](https://github.com/gohugoio/hugo/commit/f8dc47eeffa847fd0b51e376da355e3d957848a6) [@bep](https://github.com/bep) [#4487](https://github.com/gohugoio/hugo/issues/4487) +* Add a way to merge pages by language [ffaec4ca](https://github.com/gohugoio/hugo/commit/ffaec4ca8c4c6fd05b195879ccd65acf2fd5a6ac) [@bep](https://github.com/bep) [#4463](https://github.com/gohugoio/hugo/issues/4463) +* Extract `date` and `slug` from filename [68bf1511](https://github.com/gohugoio/hugo/commit/68bf1511f2be39b6576d882d071196e477c72c9f) [@bep](https://github.com/bep) [#285](https://github.com/gohugoio/hugo/issues/285)[#3310](https://github.com/gohugoio/hugo/issues/3310)[#3762](https://github.com/gohugoio/hugo/issues/3762)[#4340](https://github.com/gohugoio/hugo/issues/4340) +* Add `Delete` method to delete key from `Scratch` [e46ab29b](https://github.com/gohugoio/hugo/commit/e46ab29bd24caa9e2cfa51f24ba15037750850d6) [@paulcmal](https://github.com/paulcmal) +* Simplify Prev/Next [79dd7cb3](https://github.com/gohugoio/hugo/commit/79dd7cb31a941d7545df33b938ca3ed46593ddfd) [@bep](https://github.com/bep) +* List Chroma lexers [2c54f1ad](https://github.com/gohugoio/hugo/commit/2c54f1ad48fe2a2f7504117d351d45abc89dcb1f) [@bep](https://github.com/bep) [#4554](https://github.com/gohugoio/hugo/issues/4554) +* Add support for a `contentDir` set per language [eb42774e](https://github.com/gohugoio/hugo/commit/eb42774e587816b1fbcafbcea59ed65df703882a) [@bep](https://github.com/bep) [#4523](https://github.com/gohugoio/hugo/issues/4523)[#4552](https://github.com/gohugoio/hugo/issues/4552)[#4553](https://github.com/gohugoio/hugo/issues/4553) +* Update Chroma [7a634898](https://github.com/gohugoio/hugo/commit/7a634898c359a6af0da52be17df07cae97c7937c) [@bep](https://github.com/bep) [#4549](https://github.com/gohugoio/hugo/issues/4549) +* Add `.Site.IsServer` [1823c053](https://github.com/gohugoio/hugo/commit/1823c053c8900cb6ee53b8e5c02939c7398e34dd) [@felicianotech](https://github.com/felicianotech) [#4478](https://github.com/gohugoio/hugo/issues/4478) +* Move to Ubuntu Trusty image [511d5d3b](https://github.com/gohugoio/hugo/commit/511d5d3b7681cb76822098f430ed6862232ca529) [@anthonyfok](https://github.com/anthonyfok) +* Bump some deprecations [b6798ee8](https://github.com/gohugoio/hugo/commit/b6798ee8676c48f86b0bd8581ea244f4be4ef3fa) [@bep](https://github.com/bep) +* Update Chroma to get `Go template support` [904a3d9d](https://github.com/gohugoio/hugo/commit/904a3d9ddf523d452d04d0b5814503e0ff17bd2e) [@bep](https://github.com/bep) [#4515](https://github.com/gohugoio/hugo/issues/4515) +* Recover from error in server [f0052b6d](https://github.com/gohugoio/hugo/commit/f0052b6d0f8e113a50aeb6cd7bd34555dbf34a00) [@bep](https://github.com/bep) [#4516](https://github.com/gohugoio/hugo/issues/4516) +* Spring test cleaning, take 2 [da880157](https://github.com/gohugoio/hugo/commit/da88015776645cc68b96e8b94030c95905df53ae) [@bep](https://github.com/bep) +* Add docs for `lang.Merge` [70005364](https://github.com/gohugoio/hugo/commit/70005364a245ea3bc59c74192e1f4c56cb6879cf) [@bep](https://github.com/bep) +* Remove archetype title/date warning [ac12d51e](https://github.com/gohugoio/hugo/commit/ac12d51e7ea3a0ffb7d8053a10b6bf6acf1235ae) [@bep](https://github.com/bep) [#4504](https://github.com/gohugoio/hugo/issues/4504) +* Add docs on the new front matter configuration [0dbf79c2](https://github.com/gohugoio/hugo/commit/0dbf79c2f8cd5b1a5c91c04a8d677f956b0b8fe8) [@bep](https://github.com/bep) [#4495](https://github.com/gohugoio/hugo/issues/4495) +* Refactor the GitInfo into the date handlers [ce6e4310](https://github.com/gohugoio/hugo/commit/ce6e4310febf5659392a41b543594382441f3681) [@bep](https://github.com/bep) [#4495](https://github.com/gohugoio/hugo/issues/4495) +* Do not print build total when `--quiet` is set [50a03a5a](https://github.com/gohugoio/hugo/commit/50a03a5acc7c200c795590c3f4b964fdc56085f2) [@bep](https://github.com/bep) [#4456](https://github.com/gohugoio/hugo/issues/4456) + +## Fixes + +* Fix freeze in invalid front matter error case [93e24a03](https://github.com/gohugoio/hugo/commit/93e24a03ce98d3212a2d49ad04739141229d0809) [@bep](https://github.com/bep) [#4526](https://github.com/gohugoio/hugo/issues/4526) +* Fix path duplication/flattening in processed images [3fbc7553](https://github.com/gohugoio/hugo/commit/3fbc75534d1acda2be1c597aa77c919d3a02659d) [@bep](https://github.com/bep) [#4502](https://github.com/gohugoio/hugo/issues/4502)[#4501](https://github.com/gohugoio/hugo/issues/4501) +* Fix SVG and similar resource handling [ba94abbf](https://github.com/gohugoio/hugo/commit/ba94abbf5dd90f989242af8a7027d67a572a6128) [@bep](https://github.com/bep) [#4455](https://github.com/gohugoio/hugo/issues/4455) + + + + diff --cc docs/content/news/0.38.1-relnotes/index.md index 73cdeb24,00000000..b900b6fb mode 100644,000000..100644 --- a/docs/content/news/0.38.1-relnotes/index.md +++ b/docs/content/news/0.38.1-relnotes/index.md @@@ -1,32 -1,0 +1,32 @@@ + +--- +date: 2018-04-05 - title: "0.38.1" - description: "0.38.1" ++title: "Some Live Reload Fixes" ++description: "Hugo 0.38.1 fixes some live reload issues introduced in 0.38." +categories: ["Releases"] +images: +- images/blog/hugo-bug-poster.png + +--- + + + +This is a bug-fix that is mainly motivated by some issues with server live reloading introduced in Hugo 0.38. + +* Fix livereload for the home page bundle [f87239e4](https://github.com/gohugoio/hugo/commit/f87239e4cab958bf59ecfb1beb8cac439441a553) [@bep](https://github.com/bep) [#4576](https://github.com/gohugoio/hugo/issues/4576) +* Fix empty BuildDate in "hugo version" [294c0f80](https://github.com/gohugoio/hugo/commit/294c0f8001fe598278c1eb8015deb6b98e8de686) [@anthonyfok](https://github.com/anthonyfok) +* Fix some livereload content regressions [a4deaeff](https://github.com/gohugoio/hugo/commit/a4deaeff0cfd70abfbefa6d40c0b86839a216f6d) [@bep](https://github.com/bep) [#4566](https://github.com/gohugoio/hugo/issues/4566) +* Update github.com/bep/gitmap to fix snap build [4d115c56](https://github.com/gohugoio/hugo/commit/4d115c56fac9060230fbac6181a05f7cc6d10b42) [@anthonyfok](https://github.com/anthonyfok) [#4538](https://github.com/gohugoio/hugo/issues/4538) +* Fix two tests that are broken on Windows [26f34fd5](https://github.com/gohugoio/hugo/commit/26f34fd59da1ce1885d4f2909c5d9ef9c1726944) [@neurocline](https://github.com/neurocline) + + +This release also contains some improvements: + +* Add bash completion [874159b5](https://github.com/gohugoio/hugo/commit/874159b5436bc9080aec71a9c26d35f8f62c9fd0) [@anthonyfok](https://github.com/anthonyfok) +* Handle mass content etc. edits in server mode [730b66b6](https://github.com/gohugoio/hugo/commit/730b66b6520f263af16f555d1d7be51205a8e51d) [@bep](https://github.com/bep) [#4563](https://github.com/gohugoio/hugo/issues/4563) + + + + + + diff --cc docs/content/news/0.38.2-relnotes/index.md index 33cae747,00000000..d69c5f5b mode 100644,000000..100644 --- a/docs/content/news/0.38.2-relnotes/index.md +++ b/docs/content/news/0.38.2-relnotes/index.md @@@ -1,26 -1,0 +1,26 @@@ + +--- +date: 2018-04-09 - title: "0.38.2" - description: "0.38.2" ++title: "Hugo 0.38.2: Two Bugfixes" ++description: "0.38.2 fixes --contentDir flag handling and \".\" in content filenames." +categories: ["Releases"] +images: +- images/blog/hugo-bug-poster.png + +--- + + + +This is a bug-fix release with a couple of important fixes: + + +* Fix handling of the `--contentDir` and possibly other related flags [080302eb](https://github.com/gohugoio/hugo/commit/080302eb8757fd94ccbd6bf99103432cd98e716c) [@bep](https://github.com/bep) [#4589](https://github.com/gohugoio/hugo/issues/4589) +* Fix handling of content files with "." in them [2817e842](https://github.com/gohugoio/hugo/commit/2817e842407c8dcbfc738297ab634392fcb41ce1) [@bep](https://github.com/bep) [#4559](https://github.com/gohugoio/hugo/issues/4559) + + +Also in this release: + +* Set .Parent in bundled pages to its owner [6792d86a](https://github.com/gohugoio/hugo/commit/6792d86ad028571c684a776c5f00e0107838c955) [@bep](https://github.com/bep) [#4582](https://github.com/gohugoio/hugo/issues/4582) + + + diff --cc docs/content/templates/data-templates.md index c0b2b514,00000000..460a657e mode 100644,000000..100644 --- a/docs/content/templates/data-templates.md +++ b/docs/content/templates/data-templates.md @@@ -1,255 -1,0 +1,259 @@@ +--- +title: Data Templates +linktitle: +description: In addition to Hugo's built-in variables, you can specify your own custom data in templates or shortcodes that pull from both local and dynamic sources. +date: 2017-02-01 +publishdate: 2017-02-01 +lastmod: 2017-03-12 +categories: [templates] +keywords: [data,dynamic,csv,json,toml,yaml] +menu: + docs: + parent: "templates" + weight: 80 +weight: 80 +sections_weight: 80 +draft: false +aliases: [/extras/datafiles/,/extras/datadrivencontent/,/doc/datafiles/] +toc: true +--- + + + +Hugo supports loading data from YAML, JSON, and TOML files located in the `data` directory in the root of your Hugo project. + +{{< youtube FyPgSuwIMWQ >}} + +## The Data Folder + +The `data` folder is where you can store additional data for Hugo to use when generating your site. Data files aren't used to generate standalone pages; rather, they're meant to be supplemental to content files. This feature can extend the content in case your front matter fields grow out of control. Or perhaps you want to show a larger dataset in a template (see example below). In both cases, it's a good idea to outsource the data in their own files. + +These files must be YAML, JSON, or TOML files (using the `.yml`, `.yaml`, `.json`, or `.toml` extension). The data will be accessible as a `map` in the `.Site.Data` variable. + +## Data Files in Themes + +Data Files can also be used in [Hugo themes][themes] but note that theme data files follow the same logic as other template files in the [Hugo lookup order][lookup] (i.e., given two files with the same name and relative path, the file in the root project `data` directory will override the file in the `themes//data` directory). + +Therefore, theme authors should take care to not include data files that could be easily overwritten by a user who decides to [customize a theme][customize]. For theme-specific data items that shouldn't be overridden, it can be wise to prefix the folder structure with a namespace; e.g. `mytheme/data//somekey/...`. To check if any such duplicate exists, run hugo with the `-v` flag. + +The keys in the map created with data templates from data files will be a dot-chained set of `path`, `filename`, and `key` in file (if applicable). + +This is best explained with an example: + +## Example: Jaco Pastorius' Solo Discography + +[Jaco Pastorius](http://en.wikipedia.org/wiki/Jaco_Pastorius_discography) was a great bass player, but his solo discography is short enough to use as an example. [John Patitucci](http://en.wikipedia.org/wiki/John_Patitucci) is another bass giant. + +The example below is a bit contrived, but it illustrates the flexibility of data Files. This example uses TOML as its file format with the two following data files: + +* `data/jazz/bass/jacopastorius.toml` +* `data/jazz/bass/johnpatitucci.toml` + +`jacopastorius.toml` contains the content below. `johnpatitucci.toml` contains a similar list: + +``` +discography = [ +"1974 – Modern American Music … Period! The Criteria Sessions", +"1974 – Jaco", +"1976 - Jaco Pastorius", +"1981 - Word of Mouth", +"1981 - The Birthday Concert (released in 1995)", +"1982 - Twins I & II (released in 1999)", +"1983 - Invitation", +"1986 - Broadway Blues (released in 1998)", +"1986 - Honestly Solo Live (released in 1990)", +"1986 - Live In Italy (released in 1991)", +"1986 - Heavy'n Jazz (released in 1992)", +"1991 - Live In New York City, Volumes 1-7.", +"1999 - Rare Collection (compilation)", +"2003 - Punk Jazz: The Jaco Pastorius Anthology (compilation)", +"2007 - The Essential Jaco Pastorius (compilation)" +] +``` + +The list of bass players can be accessed via `.Site.Data.jazz.bass`, a single bass player by adding the filename without the suffix, e.g. `.Site.Data.jazz.bass.jacopastorius`. + +You can now render the list of recordings for all the bass players in a template: + +``` +{{ range $.Site.Data.jazz.bass }} + {{ partial "artist.html" . }} +{{ end }} +``` + +And then in the `partials/artist.html`: + +``` +
      +{{ range .discography }} +
    • {{ . }}
      • +{{ end }} +
    +``` + +Discover a new favorite bass player? Just add another `.toml` file in the same directory. + +## Example: Accessing Named Values in a Data File + - Assume you have the following YAML structure in your `User0123.yml` data file located directly in `data/`: ++Assume you have the following data structure in your `User0123.[yml|toml|json]` data file located directly in `data/`: + - ``` ++{{< code-toggle file="User0123" >}} +Name: User0123 +"Short Description": "He is a **jolly good** fellow." +Achievements: + - "Can create a Key, Value list from Data File" + - "Learns Hugo" + - "Reads documentation" - ``` ++{{}} + +You can use the following code to render the `Short Description` in your layout:: + +``` +
    Short Description of {{.Site.Data.User0123.Name}}:

    {{ index .Site.Data.User0123 "Short Description" | markdownify }}

    +``` + +Note the use of the [`markdownify` template function][markdownify]. This will send the description through the Blackfriday Markdown rendering engine. + + + +## Data-Driven Content + +In addition to the [data files](/extras/datafiles/) feature, Hugo also has a "data-driven content" feature, which lets you load any [JSON](http://www.json.org/) or [CSV](http://en.wikipedia.org/wiki/Comma-separated_values) file from nearly any resource. + +Data-driven content currently consists of two functions, `getJSON` and `getCSV`, which are available in all template files. + +## Implementation details + +### Call the Functions with a URL + +In your template, call the functions like this: + +``` +{{ $dataJ := getJSON "url" }} +{{ $dataC := getCSV "separator" "url" }} +``` + +If you use a prefix or postfix for the URL, the functions accept [variadic arguments][variadic]: + +``` +{{ $dataJ := getJSON "url prefix" "arg1" "arg2" "arg n" }} +{{ $dataC := getCSV "separator" "url prefix" "arg1" "arg2" "arg n" }} +``` + +The separator for `getCSV` must be put in the first position and can only be one character long. + +All passed arguments will be joined to the final URL: + +``` +{{ $urlPre := "https://api.github.com" }} +{{ $gistJ := getJSON $urlPre "/users/GITHUB_USERNAME/gists" }} +``` + +This will resolve internally to the following: + +``` +{{ $gistJ := getJSON "https://api.github.com/users/GITHUB_USERNAME/gists" }} +``` + +Finally, you can range over an array. This example will output the +first 5 gists for a GitHub user: + +``` +
      + {{ $urlPre := "https://api.github.com" }} + {{ $gistJ := getJSON $urlPre "/users/GITHUB_USERNAME/gists" }} + {{ range first 5 $gistJ }} + {{ if .public }} +
    • {{ .description }}
      • + {{ end }} + {{ end }} +
    +``` + +### Example for CSV files + +For `getCSV`, the one-character-long separator must be placed in the first position followed by the URL. The following is an example of creating an HTML table in a [partial template][partials] from a published CSV: + +{{< code file="layouts/partials/get-csv.html" >}} + + + + + + + + + + {{ $url := "http://a-big-corp.com/finance/employee-salaries.csv" }} + {{ $sep := "," }} + {{ range $i, $r := getCSV $sep $url }} + + + + + + {{ end }} + +
    NamePositionSalary
    {{ index $r 0 }}{{ index $r 1 }}{{ index $r 2 }}
    +{{< /code >}} + +The expression `{{index $r number}}` must be used to output the nth-column from the current row. + +### Cache URLs + +Each downloaded URL will be cached in the default folder `$TMPDIR/hugo_cache/`. The variable `$TMPDIR` will be resolved to your system-dependent temporary directory. + +With the command-line flag `--cacheDir`, you can specify any folder on your system as a caching directory. + +You can also set `cacheDir` in the [main configuration file][config]. + +If you don't like caching at all, you can fully disable caching with the command line flag `--ignoreCache`. + +### Authentication When Using REST URLs + +Currently, you can only use those authentication methods that can be put into an URL. [OAuth][] and other authentication methods are not implemented. + - ### Load Local files ++## Load Local files + +To load local files with `getJSON` and `getCSV`, the source files must reside within Hugo's working directory. The file extension does not matter, but the content does. + +It applies the same output logic as above in [Calling the Functions with a URL](#calling-the-functions-with-a-url). + ++{{% note %}} ++The local CSV files to be loaded using `getCSV` must be located **outside** of the `data` directory. ++{{% /note %}} ++ +## LiveReload with Data Files + +There is no chance to trigger a [LiveReload][] when the content of a URL changes. However, when a *local* file changes (i.e., `data/*` and `themes//data/*`), a LiveReload will be triggered. Symlinks are not supported. Note too that because downloading of data takes a while, Hugo stops processing your Markdown files until the data download has completed. + +{{% warning "URL Data and LiveReload" %}} +If you change any local file and the LiveReload is triggered, Hugo will read the data-driven (URL) content from the cache. If you have disabled the cache (i.e., by running the server with `hugo server --ignoreCache`), Hugo will re-download the content every time LiveReload triggers. This can create *huge* traffic. You may reach API limits quickly. +{{% /warning %}} + +## Examples of Data-driven Content + +- Photo gallery JSON powered: [https://github.com/pcdummy/hugo-lightslider-example](https://github.com/pcdummy/hugo-lightslider-example) +- GitHub Starred Repositories [in a post](https://github.com/SchumacherFM/blog-cs/blob/master/content%2Fposts%2Fgithub-starred.md) using data-driven content in a [custom short code](https://github.com/SchumacherFM/blog-cs/blob/master/layouts%2Fshortcodes%2FghStarred.html). + +## Specs for Data Formats + +* [TOML Spec][toml] +* [YAML Spec][yaml] +* [JSON Spec][json] +* [CSV Spec][csv] + +[config]: /getting-started/configuration/ +[csv]: https://tools.ietf.org/html/rfc4180 +[customize]: /themes/customizing/ +[json]: https://www.ecma-international.org/publications/files/ECMA-ST/ECMA-404.pdf "Specification for JSON, JavaScript Object Notation" +[LiveReload]: /getting-started/usage/#livereload +[lookup]: /templates/lookup-order/ +[markdownify]: /functions/markdownify/ +[OAuth]: http://en.wikipedia.org/wiki/OAuth +[partials]: /templates/partials/ +[themes]: /themes/ +[toml]: https://github.com/toml-lang/toml +[variadic]: http://en.wikipedia.org/wiki/Variadic_function +[vars]: /variables/ +[yaml]: http://yaml.org/spec/ diff --cc docs/content/templates/internal.md index 6f8d4e86,00000000..7fbfec43 mode 100644,000000..100644 --- a/docs/content/templates/internal.md +++ b/docs/content/templates/internal.md @@@ -1,133 -1,0 +1,125 @@@ +--- +title: Internal Templates +linktitle: Internal Templates +description: Hugo ships with a group of boilerplate templates that cover the most common use cases for static websites. +date: 2017-03-06 +publishdate: 2017-03-06 +lastmod: 2017-03-06 +categories: [templates] +keywords: [internal, analytics,] +menu: + docs: + parent: "templates" + weight: 168 +weight: 168 +sections_weight: 168 +draft: false +aliases: [] +toc: true +wip: true +--- + + +{{% warning %}} +While the following internal templates are called similar to partials, they do *not* observe the partial template lookup order. +{{% /warning %}} + +## Google Analytics + +Hugo ships with internal templates for Google Analytics tracking, including both synchronous and asynchronous tracking codes. + +### Configure Google Analytics + +Provide your tracking id in your configuration file: + - ``` ++{{< code-toggle file="config" >}} +googleAnalytics = "UA-123-45" - ``` - - ``` - googleAnalytics: "UA-123-45" - ``` ++{{}} + +### Use the Google Analytics Template + +You can then include the Google Analytics internal template: + +``` +{{ template "_internal/google_analytics.html" . }} +``` + + +``` +{{ template "_internal/google_analytics_async.html" . }} +``` + +## Disqus + +Hugo also ships with an internal template for [Disqus comments][disqus], a popular commenting system for both static and dynamic websites. In order to effectively use Disqus, you will need to secure a Disqus "shortname" by [signing up for the free service][disqussignup]. + +### Configure Disqus + +To use Hugo's Disqus template, you first need to set a single value in your site's `config.toml` or `config.yml`: + - ``` ++{{< code-toggle file="config" >}} +disqusShortname = "yourdiscussshortname" - ``` - - ``` - disqusShortname: "yourdiscussshortname" - ``` ++{{}} + +You also have the option to set the following in the front matter for a given piece of content: + +* `disqus_identifier` +* `disqus_title` +* `disqus_url` + +### Use the Disqus Template + +To add Disqus, include the following line in templates where you want your comments to appear: + +``` +{{ template "_internal/disqus.html" . }} +``` + +### Conditional Loading of Disqus Comments + +Users have noticed that enabling Disqus comments when running the Hugo web server on `localhost` (i.e. via `hugo server`) causes the creation of unwanted discussions on the associated Disqus account. + +You can create the following `layouts/partials/disqus.html`: + +{{< code file="layouts/partials/disqus.html" download="disqus.html" >}} +
    + + +comments powered by Disqus +{{< /code >}} + +The `if` statement skips the initialization of the Disqus comment injection when you are running on `localhost`. + +You can then render your custom Disqus partial template as follows: + +``` +{{ partial "disqus.html" . }} +``` + +## The Internal Templates + +* `_internal/disqus.html` +* `_internal/google_news.html` +* `_internal/google_analytics.html` +* `_internal/google_analytics_async.html` +* `_internal/opengraph.html` +* `_internal/pagination.html` +* `_internal/schema.html` +* `_internal/twitter_cards.html` + +[disqus]: https://disqus.com +[disqussignup]: https://disqus.com/profile/signup/ diff --cc docs/content/templates/introduction.md index 95db7eab,00000000..32df1129 mode 100644,000000..100644 --- a/docs/content/templates/introduction.md +++ b/docs/content/templates/introduction.md @@@ -1,541 -1,0 +1,541 @@@ +--- +title: Introduction to Hugo Templating +linktitle: Introduction +description: Hugo uses Go's `html/template` and `text/template` libraries as the basis for the templating. +godocref: https://golang.org/pkg/html/template/ +date: 2017-02-01 +publishdate: 2017-02-01 +lastmod: 2017-02-25 +categories: [templates,fundamentals] +keywords: [go] +menu: + docs: + parent: "templates" + weight: 10 +weight: 10 +sections_weight: 10 +draft: false +aliases: [/templates/introduction/,/layouts/introduction/,/layout/introduction/, /templates/go-templates/] +toc: true +--- + +{{% note %}} +The following is only a primer on Go templates. For an in-depth look into Go templates, check the official [Go docs](http://golang.org/pkg/html/template/). +{{% /note %}} + +Go templates provide an extremely simple template language that adheres to the belief that only the most basic of logic belongs in the template or view layer. + +{{< youtube gnJbPO-GFIw >}} + +## Basic Syntax + +Golang templates are HTML files with the addition of [variables][variables] and [functions][functions]. Golang template variables and functions are accessible within `{{ }}`. + +### Access a Predefined Variable + +``` +{{ foo }} +``` + +Parameters for functions are separated using spaces. The following example calls the `add` function with inputs of `1` and `2`: + +``` +{{ add 1 2 }} +``` + +#### Methods and Fields are Accessed via dot Notation + +Accessing the Page Parameter `bar` defined in a piece of content's [front matter][]. + +``` +{{ .Params.bar }} +``` + +#### Parentheses Can be Used to Group Items Together + +``` +{{ if or (isset .Params "alt") (isset .Params "caption") }} Caption {{ end }} +``` + +## Variables + +Each Go template gets a data object. In Hugo, each template is passed a `Page`. See [variables][] for more information. + +This is how you access a `Page` variable from a template: + +``` +{{ .Title }} +``` + +Values can also be stored in custom variables and referenced later: + +``` +{{ $address := "123 Main St."}} +{{ $address }} +``` + +{{% warning %}} +Variables defined inside `if` conditionals and similar are not visible on the outside. See [https://github.com/golang/go/issues/10608](https://github.com/golang/go/issues/10608). + +Hugo has created a workaround for this issue in [Scratch](/functions/scratch). + +{{% /warning %}} + +## Functions + +Go templates only ship with a few basic functions but also provide a mechanism for applications to extend the original set. + +[Hugo template functions][functions] provide additional functionality specific to building websites. Functions are called by using their name followed by the required parameters separated by spaces. Template functions cannot be added without recompiling Hugo. + +### Example 1: Adding Numbers + +``` +{{ add 1 2 }} +=> 3 +``` + +### Example 2: Comparing Numbers + +``` +{{ lt 1 2 }} +=> true (i.e., since 1 is less than 2) +``` + +Note that both examples make use of Go template's [math functions][]. + +{{% note "Additional Boolean Operators" %}} +There are more boolean operators than those listed in the Hugo docs in the [Golang template documentation](http://golang.org/pkg/text/template/#hdr-Functions). +{{% /note %}} + +## Includes + +When including another template, you will need to pass it the data that it would +need to access. + +{{% note %}} +To pass along the current context, please remember to include a trailing **dot**. +{{% /note %}} + +The templates location will always be starting at the `layouts/` directory +within Hugo. + +### Partial + +The [`partial`][partials] function is used to include *partial* templates using +the syntax `{{ partial "/." . }}`. + +Example: + +``` +{{ partial "header.html" . }} +``` + +### Template + +The `template` function was used to include *partial* templates in much older +Hugo versions. Now it is still useful for calling [*internal* +templates][internal_templates]: + +``` +{{ template "_internal/opengraph.html" . }} +``` + +## Logic + +Go templates provide the most basic iteration and conditional logic. + +### Iteration + +Just like in Go, the Go templates make heavy use of `range` to iterate over +a map, array, or slice. The following are different examples of how to use +range. + +#### Example 1: Using Context + +``` +{{ range array }} + {{ . }} +{{ end }} +``` + +#### Example 2: Declaring Value => Variable name + +``` +{{range $element := array}} + {{ $element }} +{{ end }} +``` + +#### Example 3: Declaring Key-Value Variable Name + +``` +{{range $index, $element := array}} + {{ $index }} + {{ $element }} +{{ end }} +``` + +### Conditionals + +`if`, `else`, `with`, `or`, and `and` provide the framework for handling conditional logic in Go Templates. Like `range`, each statement is closed with an `{{end}}`. + +Go Templates treat the following values as false: + +* false +* 0 +* any zero-length array, slice, map, or string + +#### Example 1: `if` + +``` +{{ if isset .Params "title" }}

    {{ index .Params "title" }}

    {{ end }} +``` + +#### Example 2: `if` … `else` + +``` +{{ if isset .Params "alt" }} + {{ index .Params "alt" }} +{{else}} + {{ index .Params "caption" }} +{{ end }} +``` + +#### Example 3: `and` & `or` + +``` +{{ if and (or (isset .Params "title") (isset .Params "caption")) (isset .Params "attr")}} +``` + +#### Example 4: `with` + +An alternative way of writing "`if`" and then referencing the same value +is to use "`with`" instead. `with` rebinds the context `.` within its scope +and skips the block if the variable is absent. + +The first example above could be simplified as: + +``` +{{ with .Params.title }}

    {{ . }}

    {{ end }} +``` + +#### Example 5: `if` … `else if` + +``` +{{ if isset .Params "alt" }} + {{ index .Params "alt" }} +{{ else if isset .Params "caption" }} + {{ index .Params "caption" }} +{{ end }} +``` + +## Pipes + +One of the most powerful components of Go templates is the ability to stack actions one after another. This is done by using pipes. Borrowed from Unix pipes, the concept is simple: each pipeline's output becomes the input of the following pipe. + +Because of the very simple syntax of Go templates, the pipe is essential to being able to chain together function calls. One limitation of the pipes is that they can only work with a single value and that value becomes the last parameter of the next pipeline. + +A few simple examples should help convey how to use the pipe. + +### Example 1: `shuffle` + +The following two examples are functionally the same: + +``` +{{ shuffle (seq 1 5) }} +``` + + +``` +{{ (seq 1 5) | shuffle }} +``` + +### Example 2: `index` + +The following accesses the page parameter called "disqus_url" and escapes the HTML. This example also uses the [`index` function][index], which is built into Go templates: + +``` +{{ index .Params "disqus_url" | html }} +``` + +### Example 3: `or` with `isset` + +``` +{{ if or (or (isset .Params "title") (isset .Params "caption")) (isset .Params "attr") }} +Stuff Here +{{ end }} +``` + +Could be rewritten as + +``` +{{ if isset .Params "caption" | or isset .Params "title" | or isset .Params "attr" }} +Stuff Here +{{ end }} +``` + +### Example 4: Internet Explorer Conditional Comments {#ie-conditional-comments} + +By default, Go Templates remove HTML comments from output. This has the unfortunate side effect of removing Internet Explorer conditional comments. As a workaround, use something like this: + +``` +{{ "" | safeHTML }} +``` + +Alternatively, you can use the backtick (`` ` ``) to quote the IE conditional comments, avoiding the tedious task of escaping every double quotes (`"`) inside, as demonstrated in the [examples](http://golang.org/pkg/text/template/#hdr-Examples) in the Go text/template documentation: + +``` +{{ `` | safeHTML }} +``` + +## Context (aka "the dot") + +The most easily overlooked concept to understand about Go templates is that `{{ . }}` always refers to the current context. In the top level of your template, this will be the data set made available to it. Inside of an iteration, however, it will have the value of the current item in the loop; i.e., `{{ . }}` will no longer refer to the data available to the entire page. If you need to access page-level data (e.g., page params set in front matter) from within the loop, you will likely want to do one of the following: + +### 1. Define a Variable Independent of Context + +The following shows how to define a variable independent of the context. + +{{< code file="tags-range-with-page-variable.html" >}} +{{ $title := .Site.Title }} +
      +{{ range .Params.tags }} +
    • + {{ . }} + - {{ $title }} +
      • +{{ end }} +
    +{{< /code >}} + +{{% note %}} +Notice how once we have entered the loop (i.e. `range`), the value of `{{ . }}` has changed. We have defined a variable outside of the loop (`{{$title}}`) that we've assigned a value so that we have access to the value from within the loop as well. +{{% /note %}} + +### 2. Use `$.` to Access the Global Context + +`$` has special significance in your templates. `$` is set to the starting value of `.` ("the dot") by default. This is a [documented feature of Go text/template][dotdoc]. This means you have access to the global context from anywhere. Here is an equivalent example of the preceding code block but now using `$` to grab `.Site.Title` from the global context: + +{{< code file="range-through-tags-w-global.html" >}} +
      +{{ range .Params.tags }} +
    • + {{ . }} + - {{ $.Site.Title }} +
      • +{{ end }} +
    +{{< /code >}} + +{{% warning "Don't Redefine the Dot" %}} +The built-in magic of `$` would cease to work if someone were to mischievously redefine the special character; e.g. `{{ $ := .Site }}`. *Don't do it.* You may, of course, recover from this mischief by using `{{ $ := . }}` in a global context to reset `$` to its default value. +{{% /warning %}} + +## Whitespace + +Go 1.6 includes the ability to trim the whitespace from either side of a Go tag by including a hyphen (`-`) and space immediately beside the corresponding `{{` or `}}` delimiter. + +For instance, the following Go template will include the newlines and horizontal tab in its HTML output: + +``` +
    + {{ .Title }} +
    +``` + +Which will output: + +``` +
    + Hello, World! +
    +``` + +Leveraging the `-` in the following example will remove the extra white space surrounding the `.Title` variable and remove the newline: + +``` +
    + {{- .Title -}} +
    +``` + +Which then outputs: + +``` +
    Hello, World!
    +``` + +Go considers the following characters whitespace: + +* space +* horizontal tab +* carriage return +* newline + +## Comments + +In order to keep your templates organized and share information throughout your team, you may want to add comments to your templates. There are two ways to do that with Hugo. + +### Go templates comments + +Go templates support `{{/*` and `*/}}` to open and close a comment block. Nothing within that block will be rendered. + +For example: + +``` +Bonsoir, {{/* {{ add 0 + 2 }} */}}Eliott. +``` + +Will render `Bonsoir, Eliott.`, and not care about the syntax error (`add 0 + 2`) in the comment block. + +### HTML comments + +If you need to produce HTML comments from your templates, take a look at the [Internet Explorer conditional comments](#ie-conditional-comments) example. If you need variables to construct such HTML comments, just pipe `printf` to `safeHTML`. For example: + +``` +{{ printf "" .Site.Title | safeHTML }} +``` + +#### HTML comments containing Go templates + +HTML comments are by default stripped, but their content is still evaluated. That means that although the HTML comment will never render any content to the final HTML pages, code contained within the comment may fail the build process. + +{{% note %}} +Do **not** try to comment out Go template code using HTML comments. +{{% /note %}} + +``` + +{{ $author }} +``` + +The templating engine will strip the content within the HTML comment, but will first evaluate any Go template code if present within. So the above example will render `Emma Goldman`, as the `$author` variable got evaluated in the HTML comment. But the build would have failed if that code in the HTML comment had an error. + +## Hugo Parameters + +Hugo provides the option of passing values to your template layer through your [site configuration][config] (i.e. for site-wide values) or through the metadata of each specific piece of content (i.e. the [front matter][]). You can define any values of any type and use them however you want in your templates, as long as the values are supported by the front matter format specified via `metaDataFormat` in your configuration file. + +## Use Content (`Page`) Parameters + +You can provide variables to be used by templates in individual content's [front matter][]. + +An example of this is used in the Hugo docs. Most of the pages benefit from having the table of contents provided, but sometimes the table of contents doesn't make a lot of sense. We've defined a `notoc` variable in our front matter that will prevent a table of contents from rendering when specifically set to `true`. + +Here is the example front matter: + +``` +--- +title: Roadmap +lastmod: 2017-03-05 +date: 2013-11-18 +notoc: true +--- +``` + +Here is an example of corresponding code that could be used inside a `toc.html` [partial template][partials]: + +{{< code file="layouts/partials/toc.html" download="toc.html" >}} +{{ if not .Params.notoc }} + + +{{end}} +{{< /code >}} + +We want the *default* behavior to be for pages to include a TOC unless otherwise specified. This template checks to make sure that the `notoc:` field in this page's front matter is not `true`. + +## Use Site Configuration Parameters + +You can arbitrarily define as many site-level parameters as you want in your [site's configuration file][config]. These parameters are globally available in your templates. + +For instance, you might declare the following: + - {{< code file="config.yaml" >}} ++{{< code-toggle file="config" >}} +params: + copyrighthtml: "Copyright © 2017 John Doe. All Rights Reserved." + twitteruser: "spf13" + sidebarrecentlimit: 5 +{{< /code >}} + +Within a footer layout, you might then declare a `