diff options
| author | Bjørn Erik Pedersen <bjorn.erik.pedersen@gmail.com> | 2019-10-21 11:21:37 +0300 |
|---|---|---|
| committer | Bjørn Erik Pedersen <bjorn.erik.pedersen@gmail.com> | 2019-10-21 11:21:51 +0300 |
| commit | 39121de4d991bdcf5f202da4d8d81a8ac6c149fc (patch) | |
| tree | 97e0b638fea1d898de9e297732d1044b49bfba8e /docs/content/en/templates | |
| parent | 180195aa342777fece1b29a08ec89456d7996c61 (diff) | |
docs: Replace /docs
Diffstat (limited to 'docs/content/en/templates')
25 files changed, 0 insertions, 4873 deletions
diff --git a/docs/content/en/templates/404.md b/docs/content/en/templates/404.md deleted file mode 100644 index add040175..000000000 --- a/docs/content/en/templates/404.md +++ /dev/null @@ -1,64 +0,0 @@ ---- -title: Custom 404 Page -linktitle: 404 Page -description: If you know how to create a single page template, you have unlimited options for creating a custom 404. -date: 2017-02-01 -publishdate: 2017-02-01 -lastmod: 2017-03-31 -categories: [templates] -keywords: [404, page not found] -menu: - docs: - parent: "templates" - weight: 120 -weight: 120 #rem -draft: false -aliases: [] -toc: false ---- - -When using Hugo with [GitHub Pages](http://pages.github.com/), you can provide your own template for a [custom 404 error page](https://help.github.com/articles/custom-404-pages/) by creating a 404.html template file in your `/layouts` folder. When Hugo generates your site, the `404.html` file will be placed in the root. - -404 pages will have all the regular [page variables][pagevars] available to use in the templates. - -In addition to the standard page variables, the 404 page has access to all site content accessible from `.Pages`. - -``` -▾ layouts/ - 404.html -``` - -## 404.html - -This is a basic example of a 404.html template: - -{{< code file="layouts/404.html" download="404.html" >}} -{{ define "main"}} - <main id="main"> - <div> - <h1 id="title"><a href="{{ "/" | relURL }}">Go Home</a></h1> - </div> - </main> -{{ end }} -{{< /code >}} - -## Automatic Loading - -Your 404.html file can be set to load automatically when a visitor enters a mistaken URL path, dependent upon the web serving environment you are using. For example: - -* [GitHub Pages](/hosting-and-deployment/hosting-on-github/). The 404 page is automatic. -* Apache. You can specify `ErrorDocument 404 /404.html` in an `.htaccess` file in the root of your site. -* Nginx. You might specify `error_page 404 /404.html;` in your `nginx.conf` file. -* Amazon AWS S3. When setting a bucket up for static web serving, you can specify the error file from within the S3 GUI. -* Amazon CloudFont. You can specify the page in the Error Pages section in the CloudFont Console. [Details here](https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/custom-error-pages.html) -* Caddy Server. Using `errors { 404 /404.html }`. [Details here](https://caddyserver.com/docs/errors) -* Netlify. Add `/* /404.html 404` to `content/_redirects`. [Details Here](https://www.netlify.com/docs/redirects/#custom-404) -* Azure Static website. You can specify the `Error document path` in the Static website configuration page of the Azure portal. [More details are available in the Static website documentation](https://docs.microsoft.com/en-us/azure/storage/blobs/storage-blob-static-website). - -{{% note %}} -`hugo server` will not automatically load your custom `404.html` file, but you -can test the appearance of your custom "not found" page by navigating your -browser to `/404.html`. -{{% /note %}} - -[pagevars]: /variables/page/ diff --git a/docs/content/en/templates/_index.md b/docs/content/en/templates/_index.md deleted file mode 100644 index 18ae40eac..000000000 --- a/docs/content/en/templates/_index.md +++ /dev/null @@ -1,19 +0,0 @@ ---- -title: Templates -linktitle: Templates Overview -description: Go templating, template types and lookup order, shortcodes, and data. -date: 2017-02-01 -publishdate: 2017-02-01 -lastmod: 2017-02-01 -menu: - docs: - parent: "templates" - weight: 01 -weight: 01 #rem -categories: [templates] -keywords: [] -draft: false -aliases: [/templates/overview/,/templates/content] -toc: false -notesforauthors: ---- diff --git a/docs/content/en/templates/alternatives.md b/docs/content/en/templates/alternatives.md deleted file mode 100644 index 91de38488..000000000 --- a/docs/content/en/templates/alternatives.md +++ /dev/null @@ -1,77 +0,0 @@ ---- -title: Alternative Templating Languages -linktitle: Alternative Templating -description: In addition to Go templates, Hugo supports the powerful Ace templating from @yosssi and Amber templating from @eknkc. -godocref: -date: 2017-02-01 -publishdate: 2017-02-01 -lastmod: 2017-02-20 -categories: [templates] -keywords: [amber,ace,templating languages] -menu: - docs: - parent: "templates" - weight: 170 -weight: 170 -sections_weight: 170 -draft: false -aliases: [/templates/ace/,/templates/amber/] -toc: true ---- - -## Ace Templates - -For template documentation, follow the links from the [Ace project](https://github.com/yosssi/ace). - -* Ace templates must be named with the ace-suffix; e.g., `list.ace` -* It's possible to use both Go templates and Ace templates side by side and even include one into the other -* Full Go template syntax support, including all the useful helper [template functions][] -* Partials can be included both with the Ace and the Go template syntax. For example, the following two will have the same output in Ace: - * `= include partials/foo.html .` - * `{{ partial "foo" . }}` - -One noticeable difference between Ace and the other templating engines in Hugo is [Ace's inheritance support through base and inner templates][aceinheritance]. - -In Hugo, the Ace base template will be chosen with the same rule set as for [Go base templates][]. - -``` -.: -index.ace - -./blog: -single.ace -baseof.ace - -./_default: -baseof.ace list.ace single.ace single-baseof.ace -``` - -{{% note %}} -Note that the `html` suffix is needed even if the filename is suffixed `ace`. This does not work from inside a theme ([issue #763](https://github.com/gohugoio/hugo/issues/763)). -{{% /note %}} - -Some examples for the layout files above: - -* Home page: `./index.ace` + `./_default/baseof.ace` -* Single page in the `blog` section: `./blog/single.ace` + `./blog/baseof.ace` -* Single page in another section: `./_default/single.ace` + `./_default/single-baseof.ace` -* Taxonomy page in any section: `./_default/list.ace` + `./_default/baseof.ace` - -{{% note %}} -In most cases, one `baseof.ace` in `_default` will suffice. An Ace template without a reference to a base section (e.g., `= content`) will be handled as a standalone template. -{{% /note %}} - -## Amber Templates - -For Amber template documentation, follow the links from the [Amber project][]. - -* Amber templates must be named with the Amber suffix; e.g., `list.amber` -* Partials in Amber or HTML can be included with the Amber template syntax: - * `import ../partials/test.html ` - * `import ../partials/test_a.amber ` - -[aceinheritance]: https://github.com/yosssi/ace/tree/master/examples/base_inner_template -[Amber Project]: https://github.com/eknkc/amber -[template functions]: /functions/ -[Go templates]: /templates/introduction/ -[Go base templates]: /templates/base/
\ No newline at end of file diff --git a/docs/content/en/templates/base.md b/docs/content/en/templates/base.md deleted file mode 100644 index 5643f8d4b..000000000 --- a/docs/content/en/templates/base.md +++ /dev/null @@ -1,132 +0,0 @@ ---- -title: Base Templates and Blocks -linktitle: -description: The base and block constructs allow you to define the outer shell of your master templates (i.e., the chrome of the page). -godocref: https://golang.org/pkg/text/template/#example_Template_block -date: 2017-02-01 -publishdate: 2017-02-01 -lastmod: 2017-02-01 -categories: [templates,fundamentals] -keywords: [blocks,base] -menu: - docs: - parent: "templates" - weight: 20 -weight: 20 -sections_weight: 20 -draft: false -aliases: [/templates/blocks/,/templates/base-templates-and-blocks/] -toc: true ---- - -The `block` keyword allows you to define the outer shell of your pages' one or more master template(s) and then fill in or override portions as necessary. - -{{< youtube QVOMCYitLEc >}} - -## Base Template Lookup Order - -The [lookup order][lookup] for base templates is as follows: - -1. `/layouts/section/<TYPE>-baseof.html` -2. `/themes/<THEME>/layouts/section/<TYPE>-baseof.html` -3. `/layouts/<TYPE>/baseof.html` -4. `/themes/<THEME>/layouts/<TYPE>/baseof.html` -5. `/layouts/section/baseof.html` -6. `/themes/<THEME>/layouts/section/baseof.html` -7. `/layouts/_default/<TYPE>-baseof.html` -8. `/themes/<THEME>/layouts/_default/<TYPE>-baseof.html` -9. `/layouts/_default/baseof.html` -10. `/themes/<THEME>/layouts/_default/baseof.html` - -Variables are denoted by capitalized text set within `<>`. Note that Hugo's default behavior is for `type` to inherit from `section` unless otherwise specified. - -### Example Base Template Lookup Order - -As an example, let's assume your site is using a theme called "mytheme" when rendering the section list for a `posts` section. Hugo picks `layout/section/posts.html` as the template for [rendering the section][]. The `{{define}}` block in this template tells Hugo that the template is an extension of a base template. - -Here is the lookup order for the `posts` base template: - -1. `/layouts/section/posts-baseof.html` -2. `/themes/mytheme/layouts/section/posts-baseof.html` -3. `/layouts/posts/baseof.html` -4. `/themes/mytheme/layouts/posts/baseof.html` -5. `/layouts/section/baseof.html` -6. `/themes/mytheme/layouts/section/baseof.html` -7. `/layouts/_default/posts-baseof.html` -8. `/themes/mytheme/layouts/_default/posts-baseof.html` -9. `/layouts/_default/baseof.html` -10. `/themes/mytheme/layouts/_default/baseof.html` - -## Define the Base Template - -The following defines a simple base template at `_default/baseof.html`. As a default template, it is the shell from which all your pages will be rendered unless you specify another `*baseof.html` closer to the beginning of the lookup order. - -{{< code file="layouts/_default/baseof.html" download="baseof.html" >}} -<!DOCTYPE html> -<html> - <head> - <meta charset="utf-8"> - <title>{{ block "title" . }} - <!-- Blocks may include default content. --> - {{ .Site.Title }} - {{ end }}</title> - </head> - <body> - <!-- Code that all your templates share, like a header --> - {{ block "main" . }} - <!-- The part of the page that begins to differ between templates --> - {{ end }} - {{ block "footer" . }} - <!-- More shared code, perhaps a footer but that can be overridden if need be in --> - {{ end }} - </body> -</html> -{{< /code >}} - -## Override the Base Template - -From the above base template, you can define a [default list template][hugolists]. The default list template will inherit all of the code defined above and can then implement its own `"main"` block from: - -{{< code file="layouts/_default/list.html" download="list.html" >}} -{{ define "main" }} - <h1>Posts</h1> - {{ range .Pages }} - <article> - <h2>{{ .Title }}</h2> - {{ .Content }} - </article> - {{ end }} -{{ end }} -{{< /code >}} - -This replaces the contents of our (basically empty) "main" block with something useful for the list template. In this case, we didn't define a `"title"` block, so the contents from our base template remain unchanged in lists. - -{{% warning %}} -Code that you put outside the block definitions *can* break your layout. This even includes HTML comments. For example: - -``` -<!-- Seemingly harmless HTML comment..that will break your layout at build --> -{{ define "main" }} -...your code here -{{ end }} -``` -[See this thread from the Hugo discussion forums.](https://discourse.gohugo.io/t/baseof-html-block-templates-and-list-types-results-in-empty-pages/5612/6) -{{% /warning %}} - -The following shows how you can override both the `"main"` and `"title"` block areas from the base template with code unique to your [default single page template][singletemplate]: - -{{< code file="layouts/_default/single.html" download="single.html" >}} -{{ define "title" }} - <!-- This will override the default value set in baseof.html; i.e., "{{.Site.Title}}" in the original example--> - {{ .Title }} – {{ .Site.Title }} -{{ end }} -{{ define "main" }} - <h1>{{ .Title }}</h1> - {{ .Content }} -{{ end }} -{{< /code >}} - -[hugolists]: /templates/lists -[lookup]: /templates/lookup-order/ -[rendering the section]: /templates/section-templates/ -[singletemplate]: /templates/single-page-templates/ diff --git a/docs/content/en/templates/data-templates.md b/docs/content/en/templates/data-templates.md deleted file mode 100644 index e70840b7d..000000000 --- a/docs/content/en/templates/data-templates.md +++ /dev/null @@ -1,259 +0,0 @@ ---- -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 ---- - -<!-- begin data files --> - -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/<THEME>/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/<THEME>/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`: - -``` -<ul> -{{ range .discography }} - <li>{{ . }}</li> -{{ end }} -</ul> -``` - -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 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" -{{</ code-toggle >}} - -You can use the following code to render the `Short Description` in your layout:: - -``` -<div>Short Description of {{.Site.Data.User0123.Name}}: <p>{{ index .Site.Data.User0123 "Short Description" | markdownify }}</p></div> -``` - -Note the use of the [`markdownify` template function][markdownify]. This will send the description through the Blackfriday Markdown rendering engine. - -<!-- begin "Data-drive Content" page --> - -## 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: - -``` -<ul> - {{ $urlPre := "https://api.github.com" }} - {{ $gistJ := getJSON $urlPre "/users/GITHUB_USERNAME/gists" }} - {{ range first 5 $gistJ }} - {{ if .public }} - <li><a href="{{ .html_url }}" target="_blank">{{ .description }}</a></li> - {{ end }} - {{ end }} -</ul> -``` - -### 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" >}} - <table> - <thead> - <tr> - <th>Name</th> - <th>Position</th> - <th>Salary</th> - </tr> - </thead> - <tbody> - {{ $url := "https://example.com/finance/employee-salaries.csv" }} - {{ $sep := "," }} - {{ range $i, $r := getCSV $sep $url }} - <tr> - <td>{{ index $r 0 }}</td> - <td>{{ index $r 1 }}</td> - <td>{{ index $r 2 }}</td> - </tr> - {{ end }} - </tbody> - </table> -{{< /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 - -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/<THEME>/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 --git a/docs/content/en/templates/files.md b/docs/content/en/templates/files.md deleted file mode 100644 index 6b898fe73..000000000 --- a/docs/content/en/templates/files.md +++ /dev/null @@ -1,115 +0,0 @@ ---- -title: Local File Templates -linktitle: Local File Templates -description: Hugo's `readDir` and `readFile` functions make it easy to traverse your project's directory structure and write file contents to your templates. -godocref: https://golang.org/pkg/os/#FileInfo -date: 2017-02-01 -publishdate: 2017-02-01 -lastmod: 2017-02-01 -categories: [templates] -keywords: [files,directories] -menu: - docs: - parent: "templates" - weight: 110 -weight: 110 -sections_weight: 110 -draft: false -aliases: [/extras/localfiles/,/templates/local-files/] -toc: true ---- - -## Traverse Local Files - -With Hugo's [`readDir`][readDir] and [`readFile`][readFile] template functions, you can traverse your website's files on your server. - -## Use `readDir` - -The [`readDir` function][readDir] returns an array of [`os.FileInfo`][osfileinfo]. It takes the file's `path` as a single string argument. This path can be to any directory of your website (i.e., as found on your server's file system). - -Whether the path is absolute or relative does not matter because---at least for `readDir`---the root of your website (typically `./public/`) in effect becomes both: - -1. The file system root -2. The current working directory - -### `readDir` Example: List Directory Files - -This shortcode creates a link to each of the files in a directory---display as the file's basename---along with the file's size in bytes. - -{{< code file="layouts/shortcodes/directoryindex.html" download="directoryindex.html" >}} -{{< readfile file="/themes/gohugoioTheme/layouts/shortcodes/directoryindex.html" >}} -{{< /code >}} - -You can then call the shortcode as follows inside of your content's markup: - -``` -{{</* directoryindex path="/static/css" pathURL="/css" */>}} -``` - -The above shortcode [is part of the code for the Hugo docs][dirindex]. Here it lists this site's CSS files: - -{{< directoryindex path="/themes/gohugoioTheme/static" pathURL="/css" >}} - -{{% note "Slashes are Important" %}} -The initial slash `/` in `pathURL` is important in the `directoryindex` shortcode. Otherwise, `pathURL` becomes relative to the current web page. -{{% /note %}} - -## Use `readFile` - -The [`readfile` function][readFile] reads a file from disk and converts it into a string to be manipulated by other Hugo functions or added as-is. `readFile` takes the file, including path, as an argument passed to the function. - -To use the `readFile` function in your templates, make sure the path is relative to your *Hugo project's root directory*: - -``` -{{ readFile "/content/templates/local-file-templates" }} -``` - -### `readFile` Example: Add a Project File to Content - -As `readFile` is a function, it is only available to you in your templates and not your content. However, we can create a simple [shortcode template][sct] that calls `readFile`, passes the first argument through the function, and then allows an optional second argument to send the file through the Blackfriday markdown processor. The pattern for adding this shortcode to your content will be as follows: - -``` -{{</* readfile file="/path/to/local/file.txt" markdown="true" */>}} -``` - -{{% warning %}} -If you are going to create [custom shortcodes](/templates/shortcode-templates/) with `readFile` for a theme, note that usage of the shortcode will refer to the project root and *not* your `themes` directory. -{{% /warning %}} - -Here is the templating for our new `readfile` shortcode: - -{{< code file="layouts/shortcodes/readfile.html" download="readfile.html" >}} -{{< readfile file="/themes/gohugoioTheme/layouts/shortcodes/readfile.html">}} -{{< /code >}} - -This `readfile` shortcode is [also part of the Hugo docs][readfilesource]. So is [`testing.txt`][testfile], which we will call in this example by passing it into our new `readfile` shortcode as follows: - -``` -{{</* readfile file="/content/en/readfiles/testing.txt" */>}} -``` - -The output "string" for this shortcode declaration will be the following: - -``` -{{< readfile file="/content/en/readfiles/testing.txt" >}} -``` - -However, if we want Hugo to pass this string through Blackfriday, we should add the `markdown="true"` optional parameter: - -``` -{{</* readfile file="/content/en/readfiles/testing.txt" markdown="true" */>}} -``` - -And here is the result as [called directly in the Hugo docs][] and rendered for display: - -{{< readfile file="/content/en/readfiles/testing.txt" markdown="true">}} - -[called directly in the Hugo docs]: https://github.com/gohugoio/hugoDocs/blob/master/content/en/templates/files.md -[dirindex]: https://github.com/gohugoio/hugo/blob/master/docs/layouts/shortcodes/directoryindex.html -[osfileinfo]: https://golang.org/pkg/os/#FileInfo -[readDir]: /functions/readdir/ -[readFile]: /functions/readfile/ -[sc]: /content-management/shortcodes/ -[sct]: /templates/shortcode-templates/ -[readfilesource]: https://github.com/gohugoio/hugoDocs/blob/master/layouts/shortcodes/readfile.html -[testfile]: https://github.com/gohugoio/hugoDocs/blob/master/content/en/readfiles/testing.txt diff --git a/docs/content/en/templates/homepage.md b/docs/content/en/templates/homepage.md deleted file mode 100644 index 48130c39b..000000000 --- a/docs/content/en/templates/homepage.md +++ /dev/null @@ -1,76 +0,0 @@ ---- -title: Homepage Template -linktitle: Homepage Template -description: The homepage of a website is often formatted differently than the other pages. For this reason, Hugo makes it easy for you to define your new site's homepage as a unique template. -date: 2017-02-01 -publishdate: 2017-02-01 -lastmod: 2017-02-01 -categories: [templates] -keywords: [homepage] -menu: - docs: - parent: "templates" - weight: 30 -weight: 30 -sections_weight: 30 -draft: false -aliases: [/layout/homepage/,/templates/homepage-template/] -toc: true ---- - -Homepage is a `Page` and therefore has all the [page variables][pagevars] and [site variables][sitevars] available for use. - -{{% note "The Only Required Template" %}} -The homepage template is the *only* required template for building a site and therefore useful when bootstrapping a new site and template. It is also the only required template if you are developing a single-page website. -{{% /note %}} - -{{< youtube ut1xtRZ1QOA >}} - -## Homepage Template Lookup Order - -See [Template Lookup](/templates/lookup-order/). - -## Add Content and Front Matter to the Homepage - -The homepage, similar to other [list pages in Hugo][lists], accepts content and front matter from an `_index.md` file. This file should live at the root of your `content` folder (i.e., `content/_index.md`). You can then add body copy and metadata to your homepage the way you would any other content file. - -See the homepage template below or [Content Organization][contentorg] for more information on the role of `_index.md` in adding content and front matter to list pages. - -## `.Pages` on the Homepage - -In addition to the standard [page variables][pagevars], the homepage template has access to *all* site content via `.Pages`. - -## Example Homepage Template - -The following is an example of a homepage template that uses [partial][partials], [base][] templates, and a content file at `content/_index.md` to populate the `{{.Title}}` and `{{.Content}}` [page variables][pagevars]. - -{{< code file="layouts/index.html" download="index.html" >}} -{{ define "main" }} - <main aria-role="main"> - <header class="homepage-header"> - <h1>{{.Title}}</h1> - {{ with .Params.subtitle }} - <span class="subtitle">{{.}}</span> - {{ end }} - </header> - <div class="homepage-content"> - <!-- Note that the content for index.html, as a sort of list page, will pull from content/_index.md --> - {{.Content}} - </div> - <div> - <!-- Note that .Pages is the same as .Site.RegularPages on the homepage template. --> - {{ range first 10 .Pages }} - {{ .Render "summary"}} - {{ end }} - </div> - </main> -{{ end }} -{{< /code >}} - -[base]: /templates/base/ -[contentorg]: /content-management/organization/ -[lists]: /templates/lists/ -[lookup]: /templates/lookup-order/ -[pagevars]: /variables/page/ -[partials]: /templates/partials/ -[sitevars]: /variables/site/ diff --git a/docs/content/en/templates/internal.md b/docs/content/en/templates/internal.md deleted file mode 100644 index 19ef4db82..000000000 --- a/docs/content/en/templates/internal.md +++ /dev/null @@ -1,212 +0,0 @@ ---- -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 ---- -<!-- reference: https://discourse.gohugo.io/t/lookup-order-for-partials/5705/6 -code: https://github.com/gohugoio/hugo/blob/e445c35d6a0c7f5fc2f90f31226cd1d46e048bbc/tpl/template_embedded.go#L147 --> - -{{% 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" -{{</ code-toggle >}} - -### 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" . }} -``` - -A `.Site.GoogleAnalytics` variable is also exposed from the config. - -## 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" -{{</ code-toggle >}} - -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" . }} -``` - -A `.Site.DisqusShortname` variable is also exposed from the config. - -### 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" >}} -<div id="disqus_thread"></div> -<script type="text/javascript"> - -(function() { - // Don't ever inject Disqus on localhost--it creates unwanted - // discussions from 'localhost:1313' on your Disqus account... - if (window.location.hostname == "localhost") - return; - - var dsq = document.createElement('script'); dsq.type = 'text/javascript'; dsq.async = true; - var disqus_shortname = '{{ .Site.DisqusShortname }}'; - dsq.src = '//' + disqus_shortname + '.disqus.com/embed.js'; - (document.getElementsByTagName('head')[0] || document.getElementsByTagName('body')[0]).appendChild(dsq); -})(); -</script> -<noscript>Please enable JavaScript to view the <a href="http://disqus.com/?ref_noscript">comments powered by Disqus.</a></noscript> -<a href="http://disqus.com/" class="dsq-brlink">comments powered by <span class="logo-disqus">Disqus</span></a> -{{< /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" . }} -``` - -## Open Graph -An internal template for the [Open Graph protocol](http://ogp.me/), metadata that enables a page to become a rich object in a social graph. -This format is used for Facebook and some other sites. - -### Configure Open Graph - -Hugo's Open Graph template is configured using a mix of configuration variables and [front-matter](/content-management/front-matter/) on individual pages. - -{{< code-toggle file="config" >}} -[params] - title = "My cool site" - images = ["site-feature-image.jpg"] - description = "Text about my cool site" -[taxonomies] - series = "series" -{{</ code-toggle >}} - -{{< code-toggle file="content/blog/my-post" >}} -title = "Post title" -description = "Text about this post" -date = "2006-01-02" -images = ["post-cover.png"] -audio = [] -videos = [] -series = [] -tags = [] -{{</ code-toggle >}} - -Hugo uses the page title and description for the title and description metadata. -The first 6 URLs from the `images` array are used for image metadata. - -Various optional metadata can also be set: - -- Date, published date, and last modified data are used to set the published time metadata if specified. -- `audio` and `videos` are URL arrays like `images` for the audio and video metadata tags, respectively. -- The first 6 `tags` on the page are used for the tags metadata. -- The `series` taxonomy is used to specify related "see also" pages by placing them in the same series. - -If using YouTube this will produce a og:video tag like `<meta property="og:video" content="url">`. If using a YouTube link make sure this is in **https://www.youtube.com/v/NlXVWtgLNjY** not __https://www.youtube.com/watch?v=NlXVWtgLNjY__ - -### Use the Open Graph Template - -To add Open Graph metadata, include the following line between the `<head>` tags in your templates: - -``` -{{ template "_internal/opengraph.html" . }} -``` - -## Twitter Cards - -An internal template for [Twitter Cards](https://developer.twitter.com/en/docs/tweets/optimize-with-cards/overview/abouts-cards), -metadata used to attach rich media to Tweets linking to your site. - -### Configure Twitter Cards - -Hugo's Twitter Card template is configured using a mix of configuration variables and [front-matter](/content-management/front-matter/) on individual pages. - -{{< code-toggle file="config" >}} -[params] - images = ["site-feature-image.jpg"] - description = "Text about my cool site" -{{</ code-toggle >}} - -{{< code-toggle file="content/blog/my-post" >}} -title = "Post title" -description = "Text about this post" -images = ["post-cover.png"] -{{</ code-toggle >}} - -If `images` aren't specified in the page front-matter, then hugo searches for [image page resources](/content-management/image-processing/) with `feature`, `cover`, or `thumbnail` in their name. -If no image resources with those names are found, the images defined in the [site config](getting-started/configuration/) are used instead. -If no images are found at all, then an image-less Twitter `summary` card is used instead of `summary_large_image`. - -Hugo uses the page title and description for the card's title and description fields. The page summary is used if no description is given. - -### Use the Twitter Cards Template - -To add Twitter card metadata, include the following line between the `<head>` tags in your templates: - -``` -{{ template "_internal/twitter_cards.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 --git a/docs/content/en/templates/introduction.md b/docs/content/en/templates/introduction.md deleted file mode 100644 index a2b91ba1d..000000000 --- a/docs/content/en/templates/introduction.md +++ /dev/null @@ -1,664 +0,0 @@ ---- -title: Introduction to Hugo Templating -linktitle: Introduction -description: Hugo uses Go's `html/template` and `text/template` libraries as the basis for the templating. -godocref: https://golang.org/pkg/html/template/ -date: 2017-02-01 -publishdate: 2017-02-01 -lastmod: 2017-02-25 -categories: [templates,fundamentals] -keywords: [go] -menu: - docs: - parent: "templates" - weight: 10 -weight: 10 -sections_weight: 10 -draft: false -aliases: [/layouts/introduction/,/layout/introduction/, /templates/go-templates/] -toc: true ---- - -{{% note %}} -The following is only a primer on Go Templates. For an in-depth look into Go Templates, check the official [Go docs](https://golang.org/pkg/text/template/). -{{% /note %}} - -Go Templates provide an extremely simple template language that adheres to the belief that only the most basic of logic belongs in the template or view layer. - -{{< youtube gnJbPO-GFIw >}} - -## Basic Syntax - -Go Templates are HTML files with the addition of [variables][variables] and [functions][functions]. Go Template variables and functions are accessible within `{{ }}`. - -### Access a Predefined Variable - -A _predefined variable_ could be a variable already existing in the -current scope (like the `.Title` example in the [Variables]({{< relref -"#variables" >}}) section below) or a custom variable (like the -`$address` example in that same section). - - -```go-html-template -{{ .Title }} -{{ $address }} -``` - -Parameters for functions are separated using spaces. The general syntax is: - -``` -{{ FUNCTION ARG1 ARG2 .. }} -``` - -The following example calls the `add` function with inputs of `1` and `2`: - -```go-html-template -{{ add 1 2 }} -``` - -#### Methods and Fields are Accessed via dot Notation - -Accessing the Page Parameter `bar` defined in a piece of content's [front matter][]. - -```go-html-template -{{ .Params.bar }} -``` - -#### Parentheses Can be Used to Group Items Together - -```go-html-template -{{ if or (isset .Params "alt") (isset .Params "caption") }} Caption {{ end }} -``` - -## Variables {#variables} - -Each Go Template gets a data object. In Hugo, each template is passed -a `Page`. In the below example, `.Title` is one of the elements -accessible in that [`Page` variable][pagevars]. - -With the `Page` being the default scope of a template, the `Title` -element in current scope (`.` -- "the **dot**") is accessible simply -by the dot-prefix (`.Title`): - -```go-html-template -<title>{{ .Title }}</title> -``` - -Values can also be stored in custom variables and referenced later: - -{{% note %}} -The custom variables need to be prefixed with `$`. -{{% /note %}} - -```go-html-template -{{ $address := "123 Main St." }} -{{ $address }} -``` - -{{% warning %}} -For Hugo v0.47 and older versions, variables defined inside `if` -conditionals and similar are not visible on the outside. -See [https://github.com/golang/go/issues/10608](https://github.com/golang/go/issues/10608). - -Hugo has created a workaround for this issue in [Scratch](/functions/scratch). -{{% /warning %}} - -For **Hugo v0.48** and newer, variables can be re-defined using the -new `=` operator (new in Go 1.11). - -Below example will work only in these newer Hugo versions. The example -prints "Var is Hugo Home" on the home page, and "Var is Hugo Page" on -all other pages: - -```go-html-template -{{ $var := "Hugo Page" }} -{{ if .IsHome }} - {{ $var = "Hugo Home" }} -{{ end }} -Var is {{ $var }} -``` - -## Functions - -Go Templates only ship with a few basic functions but also provide a mechanism for applications to extend the original set. - -[Hugo template functions][functions] provide additional functionality specific to building websites. Functions are called by using their name followed by the required parameters separated by spaces. Template functions cannot be added without recompiling Hugo. - -### Example 1: Adding Numbers - -```go-html-template -{{ add 1 2 }} -<!-- prints 3 --> -``` - -### Example 2: Comparing Numbers - -```go-html-template -{{ lt 1 2 }} -<!-- prints 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 [Go 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 "<PATH>/<PARTIAL>.<EXTENSION>" . }}`. - -Example of including a `layouts/partials/header.html` partial: - -```go-html-template -{{ partial "header.html" . }} -``` - -### Template - -The `template` function was used to include *partial* templates -in much older Hugo versions. Now it's useful only for calling -[*internal* templates][internal_templates]. The syntax is `{{ template -"_internal/<TEMPLATE>.<EXTENSION>" . }}`. - -{{% note %}} -The available **internal** templates can be found -[here](https://github.com/gohugoio/hugo/tree/master/tpl/tplimpl/embedded/templates). -{{% /note %}} - -Example of including the internal `opengraph.html` template: - -```go-html-template -{{ template "_internal/opengraph.html" . }} -``` - -## Logic - -Go Templates provide the most basic iteration and conditional logic. - -### Iteration - -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 (`.`) - -```go-html-template -{{ range $array }} - {{ . }} <!-- The . represents an element in $array --> -{{ end }} -``` - -#### Example 2: Declaring a variable name for an array element's value - -```go-html-template -{{ range $elem_val := $array }} - {{ $elem_val }} -{{ end }} -``` - -#### Example 3: Declaring variable names for an array element's index _and_ value - -For an array or slice, the first declared variable will map to each -element's index. - -```go-html-template -{{ range $elem_index, $elem_val := $array }} - {{ $elem_index }} -- {{ $elem_val }} -{{ end }} -``` - -#### Example 4: Declaring variable names for a map element's key _and_ value - -For a map, the first declared variable will map to each map element's -key. - -```go-html-template -{{ range $elem_key, $elem_val := $map }} - {{ $elem_key }} -- {{ $elem_val }} -{{ end }} -``` - -#### Example 5: Conditional on empty _map_, _array_, or _slice_. - -If the _map_, _array_, or _slice_ passed into the range is zero-length then the else statement is evaluated. - -```go-html-template -{{ range $array }} - {{ . }} -{{else}} - <!-- This is only evaluated if $array is empty --> -{{ 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` (boolean) -- 0 (integer) -- any zero-length array, slice, map, or string - -#### Example 1: `with` - -It is common to write "if something exists, do this" kind of -statements using `with`. - -{{% note %}} -`with` rebinds the context `.` within its scope (just like in `range`). -{{% /note %}} - -It skips the block if the variable is absent, or if it evaluates to -"false" as explained above. - -```go-html-template -{{ with .Params.title }} - <h4>{{ . }}</h4> -{{ end }} -``` - -#### Example 2: `with` .. `else` - -Below snippet uses the "description" front-matter parameter's value if -set, else uses the default `.Summary` [Page variable][pagevars]: - - -```go-html-template -{{ with .Param "description" }} - {{ . }} -{{ else }} - {{ .Summary }} -{{ end }} -``` - -See the [`.Param` function][param]. - -#### Example 3: `if` - -An alternative (and a more verbose) way of writing `with` is using -`if`. Here, the `.` does not get rebinded. - -Below example is "Example 1" rewritten using `if`: - -```go-html-template -{{ if isset .Params "title" }} - <h4>{{ index .Params "title" }}</h4> -{{ end }} -``` - -#### Example 4: `if` .. `else` - -Below example is "Example 2" rewritten using `if` .. `else`, and using -[`isset` function][isset] + `.Params` variable (different from the -[`.Param` **function**][param]) instead: - -```go-html-template -{{ if (isset .Params "description") }} - {{ index .Params "description" }} -{{ else }} - {{ .Summary }} -{{ end }} -``` - -#### Example 5: `if` .. `else if` .. `else` - -Unlike `with`, `if` can contain `else if` clauses too. - -```go-html-template -{{ if (isset .Params "description") }} - {{ index .Params "description" }} -{{ else if (isset .Params "summary") }} - {{ index .Params "summary" }} -{{ else }} - {{ .Summary }} -{{ end }} -``` - -#### Example 6: `and` & `or` - -```go-html-template -{{ if (and (or (isset .Params "title") (isset .Params "caption")) (isset .Params "attr")) }} -``` - -## 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: - -```go-html-template -{{ shuffle (seq 1 5) }} -``` - - -```go-html-template -{{ (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: - -```go-html-template -{{ index .Params "disqus_url" | html }} -``` - -### Example 3: `or` with `isset` - -```go-html-template -{{ if or (or (isset .Params "title") (isset .Params "caption")) (isset .Params "attr") }} -Stuff Here -{{ end }} -``` - -Could be rewritten as - -```go-html-template -{{ 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: - -```go-html-template -{{ "<!--[if lt IE 9]>" | safeHTML }} - <script src="html5shiv.js"></script> -{{ "<![endif]-->" | 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: - -```go-html-template -{{ `<!--[if lt IE 7]><html class="no-js lt-ie9 lt-ie8 lt-ie7"><![endif]-->` | safeHTML }} -``` - -## Context (aka "the dot") {#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 }} -<ul> -{{ range .Params.tags }} - <li> - <a href="/tags/{{ . | urlize }}">{{ . }}</a> - - {{ $title }} - </li> -{{ end }} -</ul> -{{< /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" >}} -<ul> -{{ range .Params.tags }} - <li> - <a href="/tags/{{ . | urlize }}">{{ . }}</a> - - {{ $.Site.Title }} - </li> -{{ end }} -</ul> -{{< /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: - -```go-html-template -<div> - {{ .Title }} -</div> -``` - -Which will output: - -```html -<div> - Hello, World! -</div> -``` - -Leveraging the `-` in the following example will remove the extra white space surrounding the `.Title` variable and remove the newline: - -```go-html-template -<div> - {{- .Title -}} -</div> -``` - -Which then outputs: - -```html -<div>Hello, World!</div> -``` - -Go considers the following characters _whitespace_: - -* <kbd>space</kbd> -* horizontal <kbd>tab</kbd> -* carriage <kbd>return</kbd> -* 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: - -```go-html-template -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: - -```go-html-template -{{ printf "<!-- Our website is named: %s -->" .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 %}} - -```go-html-template -<!-- {{ $author := "Emma Goldman" }} was a great woman. --> -{{ $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 (YAML): - -``` ---- -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 }} -<aside> - <header> - <a href="#{{.Title | urlize}}"> - <h3>{{.Title}}</h3> - </a> - </header> - {{.TableOfContents}} -</aside> -<a href="#" id="toc-toggle"></a> -{{ 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-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 `<footer>` that is only rendered if the `copyrighthtml` parameter is provided. If it *is* provided, you will then need to declare the string is safe to use via the [`safeHTML` function][safehtml] so that the HTML entity is not escaped again. This would let you easily update just your top-level config file each January 1st, instead of hunting through your templates. - -```go-html-template -{{ if .Site.Params.copyrighthtml }} - <footer> - <div class="text-center">{{.Site.Params.CopyrightHTML | safeHTML}}</div> - </footer> -{{ end }} -``` - -An alternative way of writing the "`if`" and then referencing the same value is to use [`with`][with] instead. `with` rebinds the context (`.`) within its scope and skips the block if the variable is absent: - -{{< code file="layouts/partials/twitter.html" >}} -{{ with .Site.Params.twitteruser }} - <div> - <a href="https://twitter.com/{{.}}" rel="author"> - <img src="/images/twitter.png" width="48" height="48" title="Twitter: {{.}}" alt="Twitter"></a> - </div> -{{ end }} -{{< /code >}} - -Finally, you can pull "magic constants" out of your layouts as well. The following uses the [`first`][first] function, as well as the [`.RelPermalink`][relpermalink] page variable and the [`.Site.Pages`][sitevars] site variable. - -```go-html-template -<nav> - <h1>Recent Posts</h1> - <ul> - {{- range first .Site.Params.SidebarRecentLimit .Site.Pages -}} - <li><a href="{{.RelPermalink}}">{{.Title}}</a></li> - {{- end -}} - </ul> -</nav> -``` - -## Example: Show Only Upcoming Events - -Go allows you to do more than what's shown here. Using Hugo's [`where` function][where] and Go built-ins, we can list only the items from `content/events/` whose date (set in a content file's [front matter][]) is in the future. The following is an example [partial template][partials]: - -{{< code file="layouts/partials/upcoming-events.html" download="upcoming-events.html" >}} -<h4>Upcoming Events</h4> -<ul class="upcoming-events"> -{{ range where .Pages.ByDate "Section" "events" }} - {{ if ge .Date.Unix now.Unix }} - <li> - <!-- add span for event type --> - <span>{{ .Type | title }} —</span> - {{ .Title }} on - <!-- add span for event date --> - <span>{{ .Date.Format "2 January at 3:04pm" }}</span> - at {{ .Params.place }} - </li> - {{ end }} -{{ end }} -</ul> -{{< /code >}} - - -[`where` function]: /functions/where/ -[config]: /getting-started/configuration/ -[dotdoc]: http://golang.org/pkg/text/template/#hdr-Variables -[first]: /functions/first/ -[front matter]: /content-management/front-matter/ -[functions]: /functions/ "See the full list of Hugo's templating functions with a quick start reference guide and basic and advanced examples." -[Go html/template]: http://golang.org/pkg/html/template/ "Godocs references for Go's html templating" -[gohtmltemplate]: http://golang.org/pkg/html/template/ "Godocs references for Go's html templating" -[index]: /functions/index/ -[math functions]: /functions/math/ -[partials]: /templates/partials/ "Link to the partial templates page inside of the templating section of the Hugo docs" -[internal_templates]: /templates/internal/ -[relpermalink]: /variables/page/ -[safehtml]: /functions/safehtml/ -[sitevars]: /variables/site/ -[pagevars]: /variables/page/ -[variables]: /variables/ "See the full extent of page-, site-, and other variables that Hugo make available to you in your templates." -[where]: /functions/where/ -[with]: /functions/with/ -[godocsindex]: http://golang.org/pkg/text/template/ "Godocs page for index function" -[param]: /functions/param/ -[isset]: /functions/isset/ diff --git a/docs/content/en/templates/lists.md b/docs/content/en/templates/lists.md deleted file mode 100644 index 5d6948a1f..000000000 --- a/docs/content/en/templates/lists.md +++ /dev/null @@ -1,558 +0,0 @@ ---- -title: Lists of Content in Hugo -linktitle: List Page Templates -description: Lists have a specific meaning and usage in Hugo when it comes to rendering your site homepage, section page, taxonomy list, or taxonomy terms list. -date: 2017-02-01 -publishdate: 2017-02-01 -lastmod: 2017-02-01 -categories: [templates] -keywords: [lists,sections,rss,taxonomies,terms] -menu: - docs: - parent: "templates" - weight: 22 -weight: 22 -sections_weight: 22 -draft: false -aliases: [/templates/list/,/layout/indexes/] -toc: true ---- - -## What is a List Page Template? - -{{< youtube 8b2YTSMdMps >}} - -A list page template is a template used to render multiple pieces of content in a single HTML page. The exception to this rule is the homepage, which is still a list but has its own [dedicated template][homepage]. - -Hugo uses the term *list* in its truest sense; i.e. a sequential arrangement of material, especially in alphabetical or numerical order. Hugo uses list templates on any output HTML page where content is traditionally listed: - -* [Taxonomy terms pages][taxterms] -* [Taxonomy list pages][taxlists] -* [Section list pages][sectiontemps] -* [RSS][rss] - -For template lookup order, see [Template Lookup](/templates/lookup-order/). - -The idea of a list page comes from the [hierarchical mental model of the web][mentalmodel] and is best demonstrated visually: - -[](/images/site-hierarchy.svg) - -## List Defaults - -### Default Templates - -Since section lists and taxonomy lists (N.B., *not* [taxonomy terms lists][taxterms]) are both *lists* with regards to their templates, both have the same terminating default of `_default/list.html` or `themes/<THEME>/layouts/_default/list.html` in their lookup order. In addition, both [section lists][sectiontemps] and [taxonomy lists][taxlists] have their own default list templates in `_default`: - -See [Template Lookup Order](/templates/lookup-order/) for the complete reference. - -## Add Content and Front Matter to List Pages - -Since v0.18, [everything in Hugo is a `Page`][bepsays]. This means list pages and the homepage can have associated content files (i.e. `_index.md`) that contain page metadata (i.e., front matter) and content. - -This new model allows you to include list-specific front matter via `.Params` and also means that list templates (e.g., `layouts/_default/list.html`) have access to all [page variables][pagevars]. - -{{% note %}} -It is important to note that all `_index.md` content files will render according to a *list* template and not according to a [single page template](/templates/single-page-templates/). -{{% /note %}} - -### Example Project Directory - -The following is an example of a typical Hugo project directory's content: - -``` -. -... -├── content -| ├── posts -| | ├── _index.md -| | ├── post-01.md -| | └── post-02.md -| └── quote -| | ├── quote-01.md -| | └── quote-02.md -... -``` - -Using the above example, let's assume you have the following in `content/posts/_index.md`: - -{{< code file="content/posts/_index.md" >}} ---- -title: My Go Journey -date: 2017-03-23 -publishdate: 2017-03-24 ---- - -I decided to start learning Go in March 2017. - -Follow my journey through this new blog. -{{< /code >}} - -You can now access this `_index.md`'s' content in your list template: - -{{< code file="layouts/_default/list.html" download="list.html" >}} -{{ define "main" }} -<main> - <article> - <header> - <h1>{{.Title}}</h1> - </header> - <!-- "{{.Content}}" pulls from the markdown content of the corresponding _index.md --> - {{.Content}} - </article> - <ul> - <!-- Ranges through content/posts/*.md --> - {{ range .Pages }} - <li> - <a href="{{.Permalink}}">{{.Date.Format "2006-01-02"}} | {{.Title}}</a> - </li> - {{ end }} - </ul> -</main> -{{ end }} -{{< /code >}} - -This above will output the following HTML: - -{{< code file="example.com/posts/index.html" copy="false" >}} -<!--top of your baseof code--> -<main> - <article> - <header> - <h1>My Go Journey</h1> - </header> - <p>I decided to start learning Go in March 2017.</p> - <p>Follow my journey through this new blog.</p> - </article> - <ul> - <li><a href="/posts/post-01/">Post 1</a></li> - <li><a href="/posts/post-02/">Post 2</a></li> - </ul> -</main> -<!--bottom of your baseof--> -{{< /code >}} - -### List Pages Without `_index.md` - -You do *not* have to create an `_index.md` file for every list page (i.e. section, taxonomy, taxonomy terms, etc) or the homepage. If Hugo does not find an `_index.md` within the respective content section when rendering a list template, the page will be created but with no `{{.Content}}` and only the default values for `.Title` etc. - -Using this same `layouts/_default/list.html` template and applying it to the `quotes` section above will render the following output. Note that `quotes` does not have an `_index.md` file to pull from: - -{{< code file="example.com/quote/index.html" copy="false" >}} -<!--baseof--> -<main> - <article> - <header> - <!-- Hugo assumes that .Title is the name of the section since there is no _index.md content file from which to pull a "title:" field --> - <h1>Quotes</h1> - </header> - </article> - <ul> - <li><a href="https://example.com/quote/quotes-01/">Quote 1</a></li> - <li><a href="https://example.com/quote/quotes-02/">Quote 2</a></li> - </ul> -</main> -<!--baseof--> -{{< /code >}} - -{{% note %}} -The default behavior of Hugo is to pluralize list titles; hence the inflection of the `quote` section to "Quotes" when called with the `.Title` [page variable](/variables/page/). You can change this via the `pluralizeListTitles` directive in your [site configuration](/getting-started/configuration/). -{{% /note %}} - -## Example List Templates - -### Section Template - -This list template has been modified slightly from a template originally used in [spf13.com](http://spf13.com/). It makes use of [partial templates][partials] for the chrome of the rendered page rather than using a [base template][base]. The examples that follow also use the [content view templates][views] `li.html` or `summary.html`. - -{{< code file="layouts/section/posts.html" >}} -{{ partial "header.html" . }} -{{ partial "subheader.html" . }} -<main> - <div> - <h1>{{ .Title }}</h1> - <ul> - <!-- Renders the li.html content view for each content/posts/*.md --> - {{ range .Pages }} - {{ .Render "li"}} - {{ end }} - </ul> - </div> -</main> -{{ partial "footer.html" . }} -{{< /code >}} - -### Taxonomy Template - -{{< code file="layouts/_default/taxonomy.html" download="taxonomy.html" >}} -{{ define "main" }} -<main> - <div> - <h1>{{ .Title }}</h1> - <!-- ranges through each of the content files associated with a particular taxonomy term and renders the summary.html content view --> - {{ range .Pages }} - {{ .Render "summary"}} - {{ end }} - </div> -</main> -{{ end }} -{{< /code >}} - -## Order Content - -Hugo lists render the content based on metadata you provide in [front matter][]. In addition to sane defaults, Hugo also ships with multiple methods to make quick work of ordering content inside list templates: - -### Default: Weight > Date > LinkTitle > FilePath - -{{< code file="layouts/partials/default-order.html" >}} -<ul> - {{ range .Pages }} - <li> - <h1><a href="{{ .Permalink }}">{{ .Title }}</a></h1> - <time>{{ .Date.Format "Mon, Jan 2, 2006" }}</time> - </li> - {{ end }} -</ul> -{{< /code >}} - -### By Weight - -Lower weight gets higher precedence. So content with lower weight will come first. - -{{< code file="layouts/partials/by-weight.html" >}} -<ul> - {{ range .Pages.ByWeight }} - <li> - <h1><a href="{{ .Permalink }}">{{ .Title }}</a></h1> - <time>{{ .Date.Format "Mon, Jan 2, 2006" }}</time> - </li> - {{ end }} -</ul> -{{< /code >}} - -### By Date - -{{< code file="layouts/partials/by-date.html" >}} -<ul> - <!-- orders content according to the "date" field in front matter --> - {{ range .Pages.ByDate }} - <li> - <h1><a href="{{ .Permalink }}">{{ .Title }}</a></h1> - <time>{{ .Date.Format "Mon, Jan 2, 2006" }}</time> - </li> - {{ end }} -</ul> -{{< /code >}} - -### By Publish Date - -{{< code file="layouts/partials/by-publish-date.html" >}} -<ul> - <!-- orders content according to the "publishdate" field in front matter --> - {{ range .Pages.ByPublishDate }} - <li> - <h1><a href="{{ .Permalink }}">{{ .Title }}</a></h1> - <time>{{ .Date.Format "Mon, Jan 2, 2006" }}</time> - </li> - {{ end }} -</ul> -{{< /code >}} - -### By Expiration Date - -{{< code file="layouts/partials/by-expiry-date.html" >}} -<ul> - {{ range .Pages.ByExpiryDate }} - <li> - <h1><a href="{{ .Permalink }}">{{ .Title }}</a></h1> - <time>{{ .Date.Format "Mon, Jan 2, 2006" }}</time> - </li> - {{ end }} -</ul> -{{< /code >}} - -### By Last Modified Date - -{{< code file="layouts/partials/by-last-mod.html" >}} -<ul> - <!-- orders content according to the "lastmod" field in front matter --> - {{ range .Pages.ByLastmod }} - <li> - <h1><a href="{{ .Permalink }}">{{ .Title }}</a></h1> - <time>{{ .Date.Format "Mon, Jan 2, 2006" }}</time> - </li> - {{ end }} -</ul> -{{< /code >}} - -### By Length - -{{< code file="layouts/partials/by-length.html" >}} -<ul> - <!-- orders content according to content length in ascending order (i.e., the shortest content will be listed first) --> - {{ range .Pages.ByLength }} - <li> - <h1><a href="{{ .Permalink }}">{{ .Title }}</a></h1> - <time>{{ .Date.Format "Mon, Jan 2, 2006" }}</time> - </li> - {{ end }} -</ul> -{{< /code >}} - -### By Title - -{{< code file="layouts/partials/by-title.html" >}} -<ul> - <!-- ranges through content in ascending order according to the "title" field set in front matter --> - {{ range .Pages.ByTitle }} - <li> - <h1><a href="{{ .Permalink }}">{{ .Title }}</a></h1> - <time>{{ .Date.Format "Mon, Jan 2, 2006" }}</time> - </li> - {{ end }} -</ul> -{{< /code >}} - -### By Link Title - -{{< code file="layouts/partials/by-link-title.html" >}} -<ul> - <!-- ranges through content in ascending order according to the "linktitle" field in front matter. If a "linktitle" field is not set, the range will start with content that only has a "title" field and use that value for .LinkTitle --> - {{ range .Pages.ByLinkTitle }} - <li> - <h1><a href="{{ .Permalink }}">{{ .LinkTitle }}</a></h1> - <time>{{ .Date.Format "Mon, Jan 2, 2006" }}</time> - </li> - {{ end }} -</ul> -{{< /code >}} - -### By Parameter - -Order based on the specified front matter parameter. Content that does not have the specified front matter field will use the site's `.Site.Params` default. If the parameter is not found at all in some entries, those entries will appear together at the end of the ordering. - -{{< code file="layouts/partials/by-rating.html" >}} -<!-- Ranges through content according to the "rating" field set in front matter --> -{{ range (.Pages.ByParam "rating") }} - <!-- ... --> -{{ end }} -{{< /code >}} - -If the targeted front matter field is nested beneath another field, you can access the field using dot notation. - -{{< code file="layouts/partials/by-nested-param.html" >}} -{{ range (.Pages.ByParam "author.last_name") }} - <!-- ... --> -{{ end }} -{{< /code >}} - -### Reverse Order - -Reversing order can be applied to any of the above methods. The following uses `ByDate` as an example: - -{{< code file="layouts/partials/by-date-reverse.html" >}} -<ul> - {{ range .Pages.ByDate.Reverse }} - <li> - <h1><a href="{{ .Permalink }}">{{ .Title }}</a></h1> - <time>{{ .Date.Format "Mon, Jan 2, 2006" }}</time> - </li> - {{ end }} -</ul> -{{< /code >}} - -## Group Content - -Hugo provides some functions for grouping pages by Section, Type, Date, etc. - -### By Page Field - -{{< code file="layouts/partials/by-page-field.html" >}} -<!-- Groups content according to content section. The ".Key" in this instance will be the section's title. --> -{{ range .Pages.GroupBy "Section" }} -<h3>{{ .Key }}</h3> -<ul> - {{ range .Pages }} - <li> - <a href="{{ .Permalink }}">{{ .Title }}</a> - <div class="meta">{{ .Date.Format "Mon, Jan 2, 2006" }}</div> - </li> - {{ end }} -</ul> -{{ end }} -{{< /code >}} - -In the above example, you may want `{{.Title}}` to point the `title` field you have added to your `_index.md` file instead. You can access this value using the [`.GetPage` function][getpage]: - -{{< code file="layouts/partials/by-page-field.html" >}} -<!-- Groups content according to content section.--> -{{ range .Pages.GroupBy "Section" }} -<!-- Checks for existence of _index.md for a section; if available, pulls from "title" in front matter --> -{{ with $.Site.GetPage "section" .Key }} -<h3>{{.Title}}</h3> -{{ else }} -<!-- If no _index.md is available, ".Key" defaults to the section title and filters to title casing --> -<h3>{{ .Key | title }}</h3> -{{ end }} -<ul> - {{ range .Pages }} - <li> - <a href="{{ .Permalink }}">{{ .Title }}</a> - <div class="meta">{{ .Date.Format "Mon, Jan 2, 2006" }}</div> - </li> - {{ end }} -</ul> -{{ end }} -{{< /code >}} - -### By Date - -{{< code file="layouts/partials/by-page-date.html" >}} -<!-- Groups content by month according to the "date" field in front matter --> -{{ range .Pages.GroupByDate "2006-01" }} -<h3>{{ .Key }}</h3> -<ul> - {{ range .Pages }} - <li> - <a href="{{ .Permalink }}">{{ .Title }}</a> - <div class="meta">{{ .Date.Format "Mon, Jan 2, 2006" }}</div> - </li> - {{ end }} -</ul> -{{ end }} -{{< /code >}} - -### By Publish Date - -{{< code file="layouts/partials/by-page-publish-date.html" >}} -<!-- Groups content by month according to the "publishdate" field in front matter --> -{{ range .Pages.GroupByPublishDate "2006-01" }} -<h3>{{ .Key }}</h3> -<ul> - {{ range .Pages }} - <li> - <a href="{{ .Permalink }}">{{ .Title }}</a> - <div class="meta">{{ .PublishDate.Format "Mon, Jan 2, 2006" }}</div> - </li> - {{ end }} -</ul> -{{ end }} -{{< /code >}} - -### By Page Parameter - -{{< code file="layouts/partials/by-page-param.html" >}} -<!-- Groups content according to the "param_key" field in front matter --> -{{ range .Pages.GroupByParam "param_key" }} -<h3>{{ .Key }}</h3> -<ul> - {{ range .Pages }} - <li> - <a href="{{ .Permalink }}">{{ .Title }}</a> - <div class="meta">{{ .Date.Format "Mon, Jan 2, 2006" }}</div> - </li> - {{ end }} -</ul> -{{ end }} -{{< /code >}} - -### By Page Parameter in Date Format - -The following template takes grouping by `date` a step further and uses Go's layout string. See the [`Format` function][] for more examples of how to use Go's layout string to format dates in Hugo. - -{{< code file="layouts/partials/by-page-param-as-date.html" >}} -<!-- Groups content by month according to the "param_key" field in front matter --> -{{ range .Pages.GroupByParamDate "param_key" "2006-01" }} -<h3>{{ .Key }}</h3> -<ul> - {{ range .Pages }} - <li> - <a href="{{ .Permalink }}">{{ .Title }}</a> - <div class="meta">{{ .Date.Format "Mon, Jan 2, 2006" }}</div> - </li> - {{ end }} -</ul> -{{ end }} -{{< /code >}} - -### Reverse Key Order - -Ordering of groups is performed by keys in alphanumeric order (A–Z, 1–100) and in reverse chronological order (i.e., with the newest first) for dates. - -While these are logical defaults, they are not always the desired order. There are two different syntaxes to change Hugo's default ordering for groups, both of which work the same way. - -#### 1. Adding the Reverse Method - -``` -{{ range (.Pages.GroupBy "Section").Reverse }} -``` - -``` -{{ range (.Pages.GroupByDate "2006-01").Reverse }} -``` - -#### 2. Providing the Alternate Direction - -``` -{{ range .Pages.GroupByDate "2006-01" "asc" }} -``` - -``` -{{ range .Pages.GroupBy "Section" "desc" }} -``` - -### Order Within Groups - -Because Grouping returns a `{{.Key}}` and a slice of pages, all of the ordering methods listed above are available. - -Here is the ordering for the example that follows: - -1. Content is grouped by month according to the `date` field in front matter. -2. Groups are listed in ascending order (i.e., the oldest groups first) -3. Pages within each respective group are ordered alphabetically according to the `title`. - -{{< code file="layouts/partials/by-group-by-page.html" >}} -{{ range .Pages.GroupByDate "2006-01" "asc" }} -<h3>{{ .Key }}</h3> -<ul> - {{ range .Pages.ByTitle }} - <li> - <a href="{{ .Permalink }}">{{ .Title }}</a> - <div class="meta">{{ .Date.Format "Mon, Jan 2, 2006" }}</div> - </li> - {{ end }} -</ul> -{{ end }} -{{< /code >}} - -## Filtering and Limiting Lists {#filtering-and-limiting-lists} - -Sometimes you only want to list a subset of the available content. A -common is to only display posts from [**main sections**][mainsections] -on the blog's homepage. - -See the documentation on [`where` function][wherefunction] and -[`first` function][firstfunction] for further details. - -[base]: /templates/base/ -[bepsays]: http://bepsays.com/en/2016/12/19/hugo-018/ -[directorystructure]: /getting-started/directory-structure/ -[`Format` function]: /functions/format/ -[front matter]: /content-management/front-matter/ -[getpage]: /functions/getpage/ -[homepage]: /templates/homepage/ -[homepage]: /templates/homepage/ -[mentalmodel]: http://webstyleguide.com/wsg3/3-information-architecture/3-site-structure.html -[pagevars]: /variables/page/ -[partials]: /templates/partials/ -[RSS 2.0]: http://cyber.law.harvard.edu/rss/rss.html "RSS 2.0 Specification" -[rss]: /templates/rss/ -[sections]: /content-management/sections/ -[sectiontemps]: /templates/section-templates/ -[sitevars]: /variables/site/ -[taxlists]: /templates/taxonomy-templates/#taxonomy-list-templates/ -[taxterms]: /templates/taxonomy-templates/#taxonomy-terms-templates/ -[taxvars]: /variables/taxonomy/ -[views]: /templates/views/ -[wherefunction]: /functions/where/ -[firstfunction]: /functions/first/ -[mainsections]: /functions/where/#mainsections diff --git a/docs/content/en/templates/lookup-order.md b/docs/content/en/templates/lookup-order.md deleted file mode 100644 index 61ce35ef2..000000000 --- a/docs/content/en/templates/lookup-order.md +++ /dev/null @@ -1,85 +0,0 @@ ---- -title: Hugo's Lookup Order -linktitle: Template Lookup Order -description: Hugo searches for the layout to use for a given page in a well defined order, starting from the most specific. -godocref: -date: 2017-02-01 -publishdate: 2017-02-01 -lastmod: 2017-07-05 -categories: [templates,fundamentals] -keywords: [templates] -menu: - docs: - parent: "templates" - weight: 15 - quicklinks: -weight: 15 -sections_weight: 15 -draft: false -aliases: [/templates/lookup/] -toc: true ---- - -## Hugo Layouts Lookup Rules - -Hugo takes the parameters listed below into consideration when choosing a layout for a given page. They are listed in a priority order. This should feel natural, but look at the table below for concrete examples of the different parameter variations. - - -Kind -: The page `Kind` (the home page is one). See the example tables below per kind. This also determines if it is a **single page** (i.e. a regular content page. We then look for a template in `_default/single.html` for HTML) or a **list page** (section listings, home page, taxonomy lists, taxonomy terms. We then look for a template in `_default/list.html` for HTML). - -Output Format -: See [Custom Output Formats](/templates/output-formats). An output format has both a `name` (e.g. `rss`, `amp`, `html`) and a `suffix` (e.g. `xml`, `html`). We prefer matches with both (e.g. `index.amp.html`, but look for less specific templates. - -Language -: We will consider a language code in the template name. If the site language is `fr`, `index.fr.amp.html` will win over `index.amp.html`, but `index.amp.html` will be chosen before `index.fr.html`. - -Layout -: Can be set in page front matter. - -Type -: Is value of `type` if set in front matter, else it is the name of the root section (e.g. "blog"). It will always have a value, so if not set, the value is "page". - -Section -: Is relevant for `section`, `taxonomy` and `taxonomyTerm` types. - -{{% note %}} -**Tip:** The examples below looks long and complex. That is the flexibility talking. Most Hugo sites contain just a handful of templates: - -```bash -├── _default -│ ├── baseof.html -│ ├── list.html -│ └── single.html -└── index.html -``` -{{% /note %}} - - -## Hugo Layouts Lookup Rules With Theme - -In Hugo, layouts can live in either the project's or the themes' layout folders, and the most specific layout will be chosen. Hugo will interleave the lookups listed below, finding the most specific one either in the project or themes. - -## Examples: Layout Lookup for Regular Pages - -{{< datatable-filtered "output" "layouts" "Kind == page" "Example" "OutputFormat" "Suffix" "Template Lookup Order" >}} - -## Examples: Layout Lookup for Home Page - -{{< datatable-filtered "output" "layouts" "Kind == home" "Example" "OutputFormat" "Suffix" "Template Lookup Order" >}} - -## Examples: Layout Lookup for Section Pages - -{{< datatable-filtered "output" "layouts" "Kind == section" "Example" "OutputFormat" "Suffix" "Template Lookup Order" >}} - -## Examples: Layout Lookup for Taxonomy List Pages - -{{< datatable-filtered "output" "layouts" "Kind == taxonomy" "Example" "OutputFormat" "Suffix" "Template Lookup Order" >}} - -## Examples: Layout Lookup for Taxonomy Terms Pages - -{{< datatable-filtered "output" "layouts" "Kind == taxonomyTerm" "Example" "OutputFormat" "Suffix" "Template Lookup Order" >}} - - - - diff --git a/docs/content/en/templates/menu-templates.md b/docs/content/en/templates/menu-templates.md deleted file mode 100644 index b39fe42a9..000000000 --- a/docs/content/en/templates/menu-templates.md +++ /dev/null @@ -1,162 +0,0 @@ ---- -title: Menu Templates -linktitle: Menu Templates -description: Menus are a powerful but simple feature for content management but can be easily manipulated in your templates to meet your design needs. -date: 2017-02-01 -publishdate: 2017-02-01 -lastmod: 2017-02-01 -categories: [templates] -keywords: [lists,sections,menus] -menu: - docs: - title: "how to use menus in templates" - parent: "templates" - weight: 130 -weight: 130 -sections_weight: 130 -draft: false -aliases: [/templates/menus/] -toc: false ---- - -Hugo makes no assumptions about how your rendered HTML will be -structured. Instead, it provides all of the functions you will need to be -able to build your menu however you want. - -The following is an example: - -{{< code file="layouts/partials/sidebar.html" download="sidebar.html" >}} -<!-- sidebar start --> -<aside> - <ul> - {{ $currentPage := . }} - {{ range .Site.Menus.main }} - {{ if .HasChildren }} - <li class="{{ if $currentPage.HasMenuCurrent "main" . }}active{{ end }}"> - <a href="#"> - {{ .Pre }} - <span>{{ .Name }}</span> - </a> - </li> - <ul class="sub-menu"> - {{ range .Children }} - <li class="{{ if $currentPage.IsMenuCurrent "main" . }}active{{ end }}"> - <a href="{{ .URL }}">{{ .Name }}</a> - </li> - {{ end }} - </ul> - {{ else }} - <li> - <a href="{{ .URL }}"> - {{ .Pre }} - <span>{{ .Name }}</span> - </a> - </li> - {{ end }} - {{ end }} - <li> - <a href="#" target="_blank">Hardcoded Link 1</a> - </li> - <li> - <a href="#" target="_blank">Hardcoded Link 2</a> - </li> - </ul> -</aside> -{{< /code >}} - -{{% note "`absLangURL` and `relLangURL`" %}} -Use the [`absLangURL`](/functions/abslangurl) or [`relLangURL`](/functions/rellangurl) functions if your theme makes use of the [multilingual feature](/content-management/multilingual/). In contrast to `absURL` and `relURL`, these two functions add the correct language prefix to the url. -{{% /note %}} - -## Section Menu for Lazy Bloggers - -To enable this menu, configure `sectionPagesMenu` in your site `config`: - -``` -sectionPagesMenu = "main" -``` - -The menu name can be anything, but take a note of what it is. - -This will create a menu with all the sections as menu items and all the sections' pages as "shadow-members". The _shadow_ implies that the pages isn't represented by a menu-item themselves, but this enables you to create a top-level menu like this: - -``` -<nav class="sidebar-nav"> - {{ $currentPage := . }} - {{ range .Site.Menus.main }} - <a class="sidebar-nav-item{{if or ($currentPage.IsMenuCurrent "main" .) ($currentPage.HasMenuCurrent "main" .) }} active{{end}}" href="{{ .URL }}" title="{{ .Title }}">{{ .Name }}</a> - {{ end }} -</nav> -``` - -In the above, the menu item is marked as active if on the current section's list page or on a page in that section. - - -## Site Config menus - -The above is all that's needed. But if you want custom menu items, e.g. changing weight, name, or link title attribute, you can define them manually in the site config file: - -{{< code-toggle file="config" >}} -[[menu.main]] - name = "This is the blog section" - title = "blog section" - weight = -110 - identifier = "blog" - url = "/blog/" -{{</ code-toggle >}} - -{{% note %}} -The `identifier` *must* match the section name. -{{% /note %}} - -## Menu Entries from the Page's front matter - -It's also possible to create menu entries from the page (i.e. the `.md`-file). - -Here is a `yaml` example: - -``` ---- -title: Menu Templates -linktitle: Menu Templates -menu: - docs: - title: "how to use menus in templates" - parent: "templates" - weight: 130 ---- -... -``` - -{{% note %}} -You can define more than one menu. It also doesn't have to be a complex value, -`menu` can also be a string, an array of strings, or an array of complex values -like in the example above. -{{% /note %}} - -### Using .Page in Menus - -If you use the front matter method of defining menu entries, you'll get access to the `.Page` variable. -This allows to use every variable that's reachable from the [page variable](/variables/page/). - -This variable is only set when the menu entry is defined in the page's front matter. -Menu entries from the site config don't know anything about `.Page`. - -That's why you have to use the go template's `with` keyword or something similar in your templating language. - -Here's an example: - -``` -<nav class="sidebar-nav"> - {{ range .Site.Menus.main }} - <a href="{{ .URL }}" title="{{ .Title }}"> - {{- .Name -}} - {{- with .Page -}} - <span class="date"> - {{- dateFormat " (2006-01-02)" .Date -}} - </span> - {{- end -}} - </a> - {{ end }} -</nav> -``` diff --git a/docs/content/en/templates/ordering-and-grouping.md b/docs/content/en/templates/ordering-and-grouping.md deleted file mode 100644 index 078adab2c..000000000 --- a/docs/content/en/templates/ordering-and-grouping.md +++ /dev/null @@ -1,344 +0,0 @@ ---- -title: Ordere and Grouping Hugo Lists -linktitle: List Ordering and Grouping -description: You can group or order your content in both your templating and content front matter. -date: 2017-02-01 -publishdate: 2017-02-01 -lastmod: 2017-02-01 -categories: [templates] -keywords: [] -menu: - docs: - parent: "templates" - weight: 27 -weight: 27 -sections_weight: 27 -draft: true -aliases: [/templates/ordering/,/templates/grouping/] -toc: true -notes: This was originally going to be a separate page on the new docs site but it now makes more sense to keep everything within the templates/lists page. - rdwatters, 2017-03-12. ---- - -In Hugo, A list template is any template that will be used to render multiple pieces of content in a single HTML page. - -## Example List Templates - -### Section Template - -This list template is used for [spf13.com](http://spf13.com/). It makes use of [partial templates][partials]. All examples use a [view](/templates/views/) called either "li" or "summary." - -{{< code file="layouts/section/post.html" >}} -{{ partial "header.html" . }} -{{ partial "subheader.html" . }} - -<section id="main"> - <div> - <h1 id="title">{{ .Title }}</h1> - <ul id="list"> - {{ range .Pages }} - {{ .Render "li"}} - {{ end }} - </ul> - </div> -</section> -{{ partial "footer.html" . }} -{{< /code >}} - -### Taxonomy Template - -{{< code file="layouts/_default/taxonomies.html" download="taxonomies.html" >}} -{{ define "main" }} -<section id="main"> - <div> - <h1 id="title">{{ .Title }}</h1> - {{ range .Pages }} - {{ .Render "summary"}} - {{ end }} - </div> -</section> -{{ end }} -{{< /code >}} - -## Order Content - -Hugo lists render the content based on metadata provided in the [front matter](/content-management/front-matter/).. - -Here are a variety of different ways you can order the content items in -your list templates: - -### Default: Weight > Date - -{{< code file="layouts/partials/order-default.html" >}} -<ul class="pages"> - {{ range .Pages }} - <li> - <h1><a href="{{ .Permalink }}">{{ .Title }}</a></h1> - <time>{{ .Date.Format "Mon, Jan 2, 2006" }}</time> - </li> - {{ end }} -</ul> -{{< /code >}} - -### By Weight - -{{< code file="layouts/partials/by-weight.html" >}} -{{ range .Pages.ByWeight }} - <li> - <a href="{{ .Permalink }}">{{ .Title }}</a> - <div class="meta">{{ .Date.Format "Mon, Jan 2, 2006" }}</div> - </li> -{{ end }} -{{< /code >}} - -### By Date - -{{< code file="layouts/partials/by-date.html" >}} -{{ range .Pages.ByDate }} - <li> - <a href="{{ .Permalink }}">{{ .Title }}</a> - <div class="meta">{{ .Date.Format "Mon, Jan 2, 2006" }}</div> - </li> -{{ end }} -{{< /code >}} - -### By Publish Date - -{{< code file="layouts/partials/by-publish-date.html" >}} -{{ range .Pages.ByPublishDate }} - <li> - <a href="{{ .Permalink }}">{{ .Title }}</a> - <div class="meta">{{ .PublishDate.Format "Mon, Jan 2, 2006" }}</div> - </li> -{{ end }} -{{< /code >}} - -### By Expiration Date - -{{< code file="layouts/partials/by-expiry-date.html" >}} -{{ range .Pages.ByExpiryDate }} - <li> - <a href="{{ .Permalink }}">{{ .Title }}</a> - <div class="meta">{{ .ExpiryDate.Format "Mon, Jan 2, 2006" }}</div> - </li> -{{ end }} -{{< /code >}} - -### By Last Modified Date - -{{< code file="layouts/partials/by-last-mod.html" >}} -{{ range .Pages.ByLastmod }} - <li> - <a href="{{ .Permalink }}">{{ .Title }}</a> - <div class="meta">{{ .Date.Format "Mon, Jan 2, 2006" }}</div> - </li> -{{ end }} -{{< /code >}} - -### By Length - -{{< code file="layouts/partials/by-length.html" >}} -{{ range .Pages.ByLength }} - <li> - <a href="{{ .Permalink }}">{{ .Title }}</a> - <div class="meta">{{ .Date.Format "Mon, Jan 2, 2006" }}</div> - </li> -{{ end }} -{{< /code >}} - - -### By Title - -{{< code file="layouts/partials/by-title.html" >}} -{{ range .Pages.ByTitle }} - <li> - <a href="{{ .Permalink }}">{{ .Title }}</a> - <div class="meta">{{ .Date.Format "Mon, Jan 2, 2006" }}</div> - </li> -{{ end }} -{{< /code >}} - -### By Link Title - -{{< code file="layouts/partials/by-link-title.html" >}} -{{ range .Pages.ByLinkTitle }} - <li> - <a href="{{ .Permalink }}">{{ .LinkTitle }}</a> - <div class="meta">{{ .Date.Format "Mon, Jan 2, 2006" }}</div> - </li> -{{ end }} -{{< /code >}} - -### By Parameter - -Order based on the specified front matter parameter. Content that does not have the specified front matter field will use the site's `.Site.Params` default. If the parameter is not found at all in some entries, those entries will appear together at the end of the ordering. - -The below example sorts a list of posts by their rating. - -{{< code file="layouts/partials/by-rating.html" >}} -{{ range (.Pages.ByParam "rating") }} - <!-- ... --> -{{ end }} -{{< /code >}} - -If the front matter field of interest is nested beneath another field, you can -also get it: - -{{< code file="layouts/partials/by-nested-param.html" >}} -{{ range (.Pages.ByParam "author.last_name") }} - <!-- ... --> -{{ end }} -{{< /code >}} - -### Reverse Order - -Reversing order can be applied to any of the above methods. The following uses `ByDate` as an example: - -{{< code file="layouts/partials/by-date-reverse.html" >}} -{{ range .Pages.ByDate.Reverse }} -<li> -<a href="{{ .Permalink }}">{{ .Title }}</a> -<div class="meta">{{ .Date.Format "Mon, Jan 2, 2006" }}</div> -</li> -{{ end }} -{{< /code >}} - -## Group Content - -Hugo provides some functions for grouping pages by Section, Type, Date, etc. - -### By Page Field - -{{< code file="layouts/partials/by-page-field.html" >}} -{{ range .Pages.GroupBy "Section" }} -<h3>{{ .Key }}</h3> -<ul> - {{ range .Pages }} - <li> - <a href="{{ .Permalink }}">{{ .Title }}</a> - <div class="meta">{{ .Date.Format "Mon, Jan 2, 2006" }}</div> - </li> - {{ end }} -</ul> -{{ end }} -{{< /code >}} - -### By Page date - -{{< code file="layouts/partials/by-page-date.html" >}} -{{ range .Pages.GroupByDate "2006-01" }} -<h3>{{ .Key }}</h3> -<ul> - {{ range .Pages }} - <li> - <a href="{{ .Permalink }}">{{ .Title }}</a> - <div class="meta">{{ .Date.Format "Mon, Jan 2, 2006" }}</div> - </li> - {{ end }} -</ul> -{{ end }} -{{< /code >}} - -### By Page publish date - -{{< code file="layouts/partials/by-page-publish-date.html" >}} -{{ range .Pages.GroupByPublishDate "2006-01" }} -<h3>{{ .Key }}</h3> -<ul> - {{ range .Pages }} - <li> - <a href="{{ .Permalink }}">{{ .Title }}</a> - <div class="meta">{{ .PublishDate.Format "Mon, Jan 2, 2006" }}</div> - </li> - {{ end }} -</ul> -{{ end }} -{{< /code >}} - -### By Page Param - -{{< code file="layouts/partials/by-page-param.html" >}} -{{ range .Pages.GroupByParam "param_key" }} -<h3>{{ .Key }}</h3> -<ul> - {{ range .Pages }} - <li> - <a href="{{ .Permalink }}">{{ .Title }}</a> - <div class="meta">{{ .Date.Format "Mon, Jan 2, 2006" }}</div> - </li> - {{ end }} -</ul> -{{ end }} -{{< /code >}} - -### By Page Param in Date Format - -{{< code file="layouts/partials/by-page-param-as-date.html" >}} -{{ range .Pages.GroupByParamDate "param_key" "2006-01" }} -<h3>{{ .Key }}</h3> -<ul> - {{ range .Pages }} - <li> - <a href="{{ .Permalink }}">{{ .Title }}</a> - <div class="meta">{{ .Date.Format "Mon, Jan 2, 2006" }}</div> - </li> - {{ end }} -</ul> -{{ end }} -{{< /code >}} - -### Reverse Key Order - -The ordering of the groups is performed by keys in alphanumeric order (A–Z, 1–100) and in reverse chronological order (newest first) for dates. - -While these are logical defaults, they are not always the desired order. There are two different syntaxes to change the order, both of which work the same way. You can use your preferred syntax. - -#### Reverse Method - -``` -{{ range (.Pages.GroupBy "Section").Reverse }} -``` - -``` -{{ range (.Pages.GroupByDate "2006-01").Reverse }} -``` - - -#### Provide the Alternate Direction - -``` -{{ range .Pages.GroupByDate "2006-01" "asc" }} -``` - -``` -{{ range .Pages.GroupBy "Section" "desc" }} -``` - -### Order Within Groups - -Because Grouping returns a `{{.Key}}` and a slice of pages, all of the ordering methods listed above are available. - -In the following example, groups are ordered chronologically and then content -within each group is ordered alphabetically by title. - -{{< code file="layouts/partials/by-group-by-page.html" >}} -{{ range .Pages.GroupByDate "2006-01" "asc" }} -<h3>{{ .Key }}</h3> -<ul> - {{ range .Pages.ByTitle }} - <li> - <a href="{{ .Permalink }}">{{ .Title }}</a> - <div class="meta">{{ .Date.Format "Mon, Jan 2, 2006" }}</div> - </li> - {{ end }} -</ul> -{{ end }} -{{< /code >}} - -## Filter and Limiting Lists - -See the [_Lists/Filtering and Limiting Lists_ -section][filteringandlimitinglists] for details. - - -[views]: /templates/views/ -[filteringandlimitinglists]: /templates/lists/#filtering-and-limiting-lists diff --git a/docs/content/en/templates/output-formats.md b/docs/content/en/templates/output-formats.md deleted file mode 100644 index 487661f5a..000000000 --- a/docs/content/en/templates/output-formats.md +++ /dev/null @@ -1,253 +0,0 @@ ---- -title: Custom Output Formats -linktitle: Custom Output Formats -description: Hugo can output content in multiple formats, including calendar events, e-book formats, Google AMP, and JSON search indexes, or any custom text format. -date: 2017-03-22 -publishdate: 2017-03-22 -lastmod: 2017-03-22 -categories: [templates] -keywords: ["amp","outputs","rss"] -menu: - docs: - parent: "templates" - weight: 18 -weight: 18 -sections_weight: 18 -draft: false -aliases: [/templates/outputs/,/extras/output-formats/,/content-management/custom-outputs/] -toc: true ---- - -This page describes how to properly configure your site with the media types and output formats, as well as where to create your templates for your custom outputs. - -## Media Types - -A [media type][] (also known as *MIME type* and *content type*) is a two-part identifier for file formats and format contents transmitted on the Internet. - -This is the full set of built-in media types in Hugo: - -{{< datatable "media" "types" "type" "suffix" >}} - -**Note:** - -* It is possible to add custom media types or change the defaults; e.g., if you want to change the suffix for `text/html` to `asp`. -* The `Suffix` is the value that will be used for URLs and filenames for that media type in Hugo. -* The `Type` is the identifier that must be used when defining new/custom `Output Formats` (see below). -* The full set of media types will be registered in Hugo's built-in development server to make sure they are recognized by the browser. - -To add or modify a media type, define it in a `mediaTypes` section in your [site configuration][config], either for all sites or for a given language. - -{{< code-toggle file="config" >}} -[mediaTypes] - [mediaTypes."text/enriched"] - suffix = "enr" - [mediaTypes."text/html"] - suffix = "asp" -{{</ code-toggle >}} - -The above example adds one new media type, `text/enriched`, and changes the suffix for the built-in `text/html` media type. - -**Note:** these media types are configured for **your output formats**. If you want to redefine one of Hugo's default output formats (e.g. `HTML`), you also need to redefine the media type. So, if you want to change the suffix of the `HTML` output format from `html` (default) to `htm`: - -```toml -[mediaTypes] -[mediaTypes."text/html"] -suffix = "htm" - -# Redefine HTML to update its media type. -[outputFormats] -[outputFormats.HTML] -mediaType = "text/html" -``` - -**Note** that for the above to work, you also need to add an `outputs` definition in your site config. - -## Output Format Definitions - -Given a media type and some additional configuration, you get an **Output Format**. - -This is the full set of Hugo's built-in output formats: - -{{< datatable "output" "formats" "name" "mediaType" "path" "baseName" "rel" "protocol" "isPlainText" "isHTML" "noUgly" "permalinkable" >}} - -* A page can be output in as many output formats as you want, and you can have an infinite amount of output formats defined **as long as they resolve to a unique path on the file system**. In the above table, the best example of this is `AMP` vs. `HTML`. `AMP` has the value `amp` for `Path` so it doesn't overwrite the `HTML` version; e.g. we can now have both `/index.html` and `/amp/index.html`. -* The `MediaType` must match the `Type` of an already defined media type. -* You can define new output formats or redefine built-in output formats; e.g., if you want to put `AMP` pages in a different path. - -To add or modify an output format, define it in an `outputFormats` section in your site's [configuration file](/getting-started/configuration/), either for all sites or for a given language. - -{{< code-toggle file="config" >}} -[outputFormats.MyEnrichedFormat] -mediaType = "text/enriched" -baseName = "myindex" -isPlainText = true -protocol = "bep://" -{{</ code-toggle >}} - -The above example is fictional, but if used for the homepage on a site with `baseURL` `https://example.org`, it will produce a plain text homepage with the URL `bep://example.org/myindex.enr`. - -### Configure Output Formats - -The following is the full list of configuration options for output formats and their default values: - -`name` -: the output format identifier. This is used to define what output format(s) you want for your pages. - -`mediaType` -: this must match the `Type` of a defined media type. - -`path` -: sub path to save the output files. - -`baseName` -: the base filename for the list filenames (homepage, etc.). **Default:** `index`. - -`rel` -: can be used to create `rel` values in `link` tags. **Default:** `alternate`. - -`protocol` -: will replace the "http://" or "https://" in your `baseURL` for this output format. - -`isPlainText` -: use Go's plain text templates parser for the templates. **Default:** `false`. - -`isHTML` -: used in situations only relevant for `HTML`-type formats; e.g., page aliases. - -`noUgly` -: used to turn off ugly URLs If `uglyURLs` is set to `true` in your site. **Default:** `false`. - -`notAlternative` -: enable if it doesn't make sense to include this format in an `AlternativeOutputFormats` format listing on `Page` (e.g., with `CSS`). Note that we use the term *alternative* and not *alternate* here, as it does not necessarily replace the other format. **Default:** `false`. - -`permalinkable` -: make `.Permalink` and `.RelPermalink` return the rendering Output Format rather than main ([see below](#link-to-output-formats)). This is enabled by default for `HTML` and `AMP`. **Default:** `false`. - -## Output Formats for Pages - -A `Page` in Hugo can be rendered to multiple *output formats* on the file -system. - -### Default Output Formats -Every `Page` has a [`Kind`][page_kinds] attribute, and the default Output -Formats are set based on that. - -| Kind | Default Output Formats | -|--------------- |----------------------- | -| `page` | HTML | -| `home` | HTML, RSS | -| `section` | HTML, RSS | -| `taxonomyTerm` | HTML, RSS | -| `taxonomy` | HTML, RSS | - -### Customizing Output Formats - -This can be changed by defining an `outputs` list of output formats in either -the `Page` front matter or in the site configuration (either for all sites or -per language). - -Example from site config file: - -{{< code-toggle file="config" >}} -[outputs] - home = ["HTML", "AMP", "RSS"] - page = ["HTML"] -{{</ code-toggle >}} - - -Note that in the above examples, the *output formats* for `section`, -`taxonomyTerm` and `taxonomy` will stay at their default value `["HTML", -"RSS"]`. - -* The `outputs` definition is per [`Page` `Kind`][page_kinds] (`page`, `home`, `section`, `taxonomy`, or `taxonomyTerm`). -* The names (e.g. `HTML`, `AMP`) used must match the `Name` of a defined *Output Format*. - * These names are case insensitive. -* These can be overridden per `Page` in the front matter of content files. - -The following is an example of `YAML` front matter in a content file that defines output formats for the rendered `Page`: - -```yaml ---- -date: "2016-03-19" -outputs: -- html -- amp -- json ---- -``` - -## List Output formats - -Each `Page` has both an `.OutputFormats` (all formats, including the current) and an `.AlternativeOutputFormats` variable, the latter of which is useful for creating a `link rel` list in your site's `<head>`: - -```go-html-template -{{ range .AlternativeOutputFormats -}} -<link rel="{{ .Rel }}" type="{{ .MediaType.Type }}" href="{{ .Permalink | safeURL }}"> -{{ end -}} -``` - -## Link to Output Formats - -`.Permalink` and `.RelPermalink` on `Page` will return the first output format defined for that page (usually `HTML` if nothing else is defined). This is regardless of the template file they are being called from. - -__from `single.json.json`:__ -```go-html-template -{{ .RelPermalink }} > /that-page/ -{{ with .OutputFormats.Get "json" -}} -{{ .RelPermalink }} > /that-page/index.json -{{- end }} -``` - -In order for them to return the output format of the current template file instead, the given output format should have its `permalinkable` setting set to true. - -__Same template file as above with json output format's `permalinkable` set to true:__ - -```go-html-template -{{ .RelPermalink }} > /that-page/index.json -{{ with .OutputFormats.Get "html" -}} -{{ .RelPermalink }} > /that-page/ -{{- end }} -``` - -From content files, you can use the [`ref` or `relref` shortcodes](/content-management/shortcodes/#ref-and-relref): - -```go-html-template -[Neat]({{</* ref "blog/neat.md" "amp" */>}}) -[Who]({{</* relref "about.md#who" "amp" */>}}) -``` - -## Templates for Your Output Formats - -A new output format needs a corresponding template in order to render anything useful. - -{{% note %}} -The key distinction for Hugo versions 0.20 and newer is that Hugo looks at an output format's `Name` and MediaType's `Suffix` when choosing the template used to render a given `Page`. -{{% /note %}} - -The following table shows examples of different output formats, the suffix used, and Hugo's respective template [lookup order][]. All of the examples in the table can: - -* Use a [base template][base]. -* Include [partial templates][partials] - -{{< datatable "output" "layouts" "Example" "OutputFormat" "Suffix" "Template Lookup Order" >}} - -Hugo will now also detect the media type and output format of partials, if possible, and use that information to decide if the partial should be parsed as a plain text template or not. - -Hugo will look for the name given, so you can name it whatever you want. But if you want it treated as plain text, you should use the file suffix and, if needed, the name of the Output Format. The pattern is as follows: - -``` -[partial name].[OutputFormat].[suffix] -``` - -The partial below is a plain text template (Outpuf Format is `CSV`, and since this is the only output format with the suffix `csv`, we don't need to include the Output Format's `Name`): - -``` -{{ partial "mytextpartial.csv" . }} -``` - -[base]: /templates/base/ -[config]: /getting-started/configuration/ -[lookup order]: /templates/lookup/ -[media type]: https://en.wikipedia.org/wiki/Media_type -[partials]: /templates/partials/ -[page_kinds]: /templates/section-templates/#page-kinds diff --git a/docs/content/en/templates/pagination.md b/docs/content/en/templates/pagination.md deleted file mode 100644 index bd4176761..000000000 --- a/docs/content/en/templates/pagination.md +++ /dev/null @@ -1,155 +0,0 @@ ---- -title: Pagination -linktitle: Pagination -description: Hugo supports pagination for your homepage, section pages, and taxonomies. -date: 2017-02-01 -publishdate: 2017-02-01 -lastmod: 2017-02-01 -categories: [templates] -keywords: [lists,sections,pagination] -menu: - docs: - parent: "templates" - weight: 140 -weight: 140 -sections_weight: 140 -draft: false -aliases: [/extras/pagination,/doc/pagination/] -toc: true ---- - -The real power of Hugo pagination shines when combined with the [`where` function][where] and its SQL-like operators: [`first`][], [`last`][], and [`after`][]. You can even [order the content][lists] the way you've become used to with Hugo. - -## Configure Pagination - -Pagination can be configured in your [site configuration][configuration]: - -`Paginate` -: default = `10`. This setting can be overridden within the template. - -`PaginatePath` -: default = `page`. Allows you to set a different path for your pagination pages. - -Setting `Paginate` to a positive value will split the list pages for the homepage, sections and taxonomies into chunks of that size. But note that the generation of the pagination pages for sections, taxonomies and homepage is *lazy* --- the pages will not be created if not referenced by a `.Paginator` (see below). - -`PaginatePath` is used to adapt the `URL` to the pages in the paginator (the default setting will produce URLs on the form `/page/1/`. - -## List Paginator Pages - -{{% warning %}} -`.Paginator` is provided to help you build a pager menu. This feature is currently only supported on homepage and list pages (i.e., taxonomies and section lists). -{{% /warning %}} - -There are two ways to configure and use a `.Paginator`: - -1. The simplest way is just to call `.Paginator.Pages` from a template. It will contain the pages for *that page*. -2. Select a subset of the pages with the available template functions and ordering options, and pass the slice to `.Paginate`, e.g. `{{ range (.Paginate ( first 50 .Pages.ByTitle )).Pages }}`. - -For a given **Page**, it's one of the options above. The `.Paginator` is static and cannot change once created. - -The global page size setting (`Paginate`) can be overridden by providing a positive integer as the last argument. The examples below will give five items per page: - -* `{{ range (.Paginator 5).Pages }}` -* `{{ $paginator := .Paginate (where .Pages "Type" "posts") 5 }}` - -It is also possible to use the `GroupBy` functions in combination with pagination: - -``` -{{ range (.Paginate (.Pages.GroupByDate "2006")).PageGroups }} -``` - -## Build the navigation - -The `.Paginator` contains enough information to build a paginator interface. - -The easiest way to add this to your pages is to include the built-in template (with `Bootstrap`-compatible styles): - -``` -{{ template "_internal/pagination.html" . }} -``` - -{{% note "When to Create `.Paginator`" %}} -If you use any filters or ordering functions to create your `.Paginator` *and* you want the navigation buttons to be shown before the page listing, you must create the `.Paginator` before it's used. -{{% /note %}} - -The following example shows how to create `.Paginator` before its used: - -``` -{{ $paginator := .Paginate (where .Pages "Type" "posts") }} -{{ template "_internal/pagination.html" . }} -{{ range $paginator.Pages }} - {{ .Title }} -{{ end }} -``` - -Without the `where` filter, the above example is even simpler: - -``` -{{ template "_internal/pagination.html" . }} -{{ range .Paginator.Pages }} - {{ .Title }} -{{ end }} -``` - -If you want to build custom navigation, you can do so using the `.Paginator` object, which includes the following properties: - -`PageNumber` -: The current page's number in the pager sequence - -`URL` -: The relative URL to the current pager - -`Pages` -: The pages in the current pager - -`NumberOfElements` -: The number of elements on this page - -`HasPrev` -: Whether there are page(s) before the current - -`Prev` -: The pager for the previous page - -`HasNext` -: Whether there are page(s) after the current - -`Next` -: The pager for the next page - -`First` -: The pager for the first page - -`Last` -: The pager for the last page - -`Pagers` -: A list of pagers that can be used to build a pagination menu - -`PageSize` -: Size of each pager - -`TotalPages` -: The number of pages in the paginator - -`TotalNumberOfElements` -: The number of elements on all pages in this paginator - -## Additional information - -The pages are built on the following form (`BLANK` means no value): - -``` -[SECTION/TAXONOMY/BLANK]/index.html -[SECTION/TAXONOMY/BLANK]/page/1/index.html => redirect to [SECTION/TAXONOMY/BLANK]/index.html -[SECTION/TAXONOMY/BLANK]/page/2/index.html -.... -``` - - -[`first`]: /functions/first/ -[`last`]: /functions/last/ -[`after`]: /functions/after/ -[configuration]: /getting-started/configuration/ -[lists]: /templates/lists/ -[where]: /functions/where/ diff --git a/docs/content/en/templates/partials.md b/docs/content/en/templates/partials.md deleted file mode 100644 index 725e946fb..000000000 --- a/docs/content/en/templates/partials.md +++ /dev/null @@ -1,209 +0,0 @@ ---- -title: Partial Templates -linktitle: Partial Templates -description: Partials are smaller, context-aware components in your list and page templates that can be used economically to keep your templating DRY. -date: 2017-02-01 -publishdate: 2017-02-01 -lastmod: 2017-02-01 -categories: [templates] -keywords: [lists,sections,partials] -menu: - docs: - parent: "templates" - weight: 90 -weight: 90 -sections_weight: 90 -draft: false -aliases: [/templates/partial/,/layout/chrome/,/extras/analytics/] -toc: true ---- - -{{< youtube pjS4pOLyB7c >}} - -## Partial Template Lookup Order - -Partial templates---like [single page templates][singletemps] and [list page templates][listtemps]---have a specific [lookup order][]. However, partials are simpler in that Hugo will only check in two places: - -1. `layouts/partials/*<PARTIALNAME>.html` -2. `themes/<THEME>/layouts/partials/*<PARTIALNAME>.html` - -This allows a theme's end user to copy a partial's contents into a file of the same name for [further customization][customize]. - -## Use Partials in your Templates - -All partials for your Hugo project are located in a single `layouts/partials` directory. For better organization, you can create multiple subdirectories within `partials` as well: - -``` -. -└── layouts - └── partials - ├── footer - │ ├── scripts.html - │ └── site-footer.html - ├── head - │ ├── favicons.html - │ ├── metadata.html - │ ├── prerender.html - │ └── twitter.html - └── header - ├── site-header.html - └── site-nav.html -``` - -All partials are called within your templates using the following pattern: - -``` -{{ partial "<PATH>/<PARTIAL>.html" . }} -``` - -{{% note %}} -One of the most common mistakes with new Hugo users is failing to pass a context to the partial call. In the pattern above, note how "the dot" (`.`) is required as the second argument to give the partial context. You can read more about "the dot" in the [Hugo templating introduction](/templates/introduction/). -{{% /note %}} - -{{% note %}} -`<PARTIAL>` including `baseof` is reserved. ([#5373](https://github.com/gohugoio/hugo/issues/5373)) -{{% /note %}} - -As shown in the above example directory structure, you can nest your directories within `partials` for better source organization. You only need to call the nested partial's path relative to the `partials` directory: - -``` -{{ partial "header/site-header.html" . }} -{{ partial "footer/scripts.html" . }} -``` - -### Variable Scoping - -The second argument in a partial call is the variable being passed down. The above examples are passing the `.`, which tells the template receiving the partial to apply the current [context][context]. - -This means the partial will *only* be able to access those variables. The partial is isolated and *has no access to the outer scope*. From within the partial, `$.Var` is equivalent to `.Var`. - -## Returning a value from a Partial - -In addition to outputting markup, partials can be used to return a value of any type. In order to return a value, a partial must include a lone `return` statement. - -### Example GetFeatured -```go-html-template -{{/* layouts/partials/GetFeatured.html */}} -{{ return first . (where site.RegularPages ".Params.featured" true) }} -``` - -```go-html-template -{{/* layouts/index.html */}} -{{ range partial "GetFeatured.html" 5 }} - [...] -{{ end }} -``` -### Example GetImage -```go-html-template -{{/* layouts/partials/GetImage.html */}} -{{ $image := false }} -{{ with .Params.gallery }} - {{ $image = index . 0 }} -{{ end }} -{{ with .Params.image }} - {{ $image = . }} -{{ end }} -{{ return $image }} -``` - -```go-html-template -{{/* layouts/_default/single.html */}} -{{ with partial "GetImage.html" . }} - [...] -{{ end }} -``` - -{{% note %}} -Only one `return` statement is allowed per partial file. -{{% /note %}} - -## Cached Partials - -The [`partialCached` template function][partialcached] can offer significant performance gains for complex templates that don't need to be re-rendered on every invocation. The simplest usage is as follows: - -``` -{{ partialCached "footer.html" . }} -``` - -You can also pass additional parameters to `partialCached` to create *variants* of the cached partial. - -For example, you can tell Hugo to only render the partial `footer.html` once per section: - -``` -{{ partialCached "footer.html" . .Section }} -``` - -If you need to pass additional parameters to create unique variants, you can pass as many variant parameters as you need: - -``` -{{ partialCached "footer.html" . .Params.country .Params.province }} -``` - -Note that the variant parameters are not made available to the underlying partial template. They are only use to create a unique cache key. - -### Example `header.html` - -The following `header.html` partial template is used for [spf13.com](http://spf13.com/): - -{{< code file="layouts/partials/header.html" download="header.html" >}} -<!DOCTYPE html> -<html class="no-js" lang="en-US" prefix="og: http://ogp.me/ns# fb: http://ogp.me/ns/fb#"> -<head> - <meta charset="utf-8"> - - {{ partial "meta.html" . }} - - <base href="{{ .Site.BaseURL }}"> - <title> {{ .Title }} : spf13.com </title> - <link rel="canonical" href="{{ .Permalink }}"> - {{ if .RSSLink }}<link href="{{ .RSSLink }}" rel="alternate" type="application/rss+xml" title="{{ .Title }}" />{{ end }} - - {{ partial "head_includes.html" . }} -</head> -<body lang="en"> -{{< /code >}} - -{{% note %}} -The `header.html` example partial was built before the introduction of block templates to Hugo. Read more on [base templates and blocks](/templates/base/) for defining the outer chrome or shell of your master templates (i.e., your site's head, header, and footer). You can even combine blocks and partials for added flexibility. -{{% /note %}} - -### Example `footer.html` - -The following `footer.html` partial template is used for [spf13.com](http://spf13.com/): - -{{< code file="layouts/partials/footer.html" download="footer.html" >}} -<footer> - <div> - <p> - © 2013-14 Steve Francia. - <a href="http://creativecommons.org/licenses/by/3.0/" title="Creative Commons Attribution">Some rights reserved</a>; - please attribute properly and link back. Hosted by <a href="http://servergrove.com">ServerGrove</a>. - </p> - </div> -</footer> -<script type="text/javascript"> - - var _gaq = _gaq || []; - _gaq.push(['_setAccount', 'UA-XYSYXYSY-X']); - _gaq.push(['_trackPageview']); - - (function() { - var ga = document.createElement('script'); - ga.src = ('https:' == document.location.protocol ? 'https://ssl' : - 'http://www') + '.google-analytics.com/ga.js'; - ga.setAttribute('async', 'true'); - document.documentElement.firstChild.appendChild(ga); - })(); - -</script> -</body> -</html> -{{< /code >}} - -[context]: /templates/introduction/ "The most easily overlooked concept to understand about Go templating is how the dot always refers to the current context." -[customize]: /themes/customizing/ "Hugo provides easy means to customize themes as long as users are familiar with Hugo's template lookup order." -[listtemps]: /templates/lists/ "To effectively leverage Hugo's system, see how Hugo handles list pages, where content for sections, taxonomies, and the homepage are listed and ordered." -[lookup order]: /templates/lookup-order/ "To keep your templating dry, read the documentation on Hugo's lookup order." -[partialcached]: /functions/partialcached/ "Use the partial cached function to improve build times in cases where Hugo can cache partials that don't need to be rendered with every page." -[singletemps]: /templates/single-page-templates/ "The most common form of template in Hugo is the single content template. Read the docs on how to create templates for individual pages." -[themes]: /themes/ diff --git a/docs/content/en/templates/robots.md b/docs/content/en/templates/robots.md deleted file mode 100644 index cfb077e30..000000000 --- a/docs/content/en/templates/robots.md +++ /dev/null @@ -1,54 +0,0 @@ ---- -title: Robots.txt File -linktitle: Robots.txt -description: Hugo can generate a customized robots.txt in the same way as any other template. -date: 2017-02-01 -publishdate: 2017-02-01 -lastmod: 2017-02-01 -categories: [templates] -keywords: [robots,search engines] -menu: - docs: - parent: "templates" - weight: 165 -weight: 165 -sections_weight: 165 -draft: false -aliases: [/extras/robots-txt/] -toc: false ---- - -To create your robots.txt as a template, first set the `enableRobotsTXT` value to `true` in your [configuration file][config]. By default, this option generates a robots.txt with the following content, which tells search engines that they are allowed to crawl everything: - -``` -User-agent: * -``` - -## Robots.txt Template Lookup Order - -The [lookup order][lookup] for the `robots.txt` template is as follows: - -* `/layouts/robots.txt` -* `/themes/<THEME>/layouts/robots.txt` - -{{% note %}} -If you do not want Hugo to create a default `robots.txt` or leverage the `robots.txt` template, you can hand code your own and place the file in `static`. Remember that everything in the [static directory](/getting-started/directory-structure/) is copied over as-is when Hugo builds your site. -{{% /note %}} - -## Robots.txt Template Example - -The following is an example `robots.txt` layout: - -{{< code file="layouts/robots.txt" download="robots.txt" >}} -User-agent: * - -{{range .Pages}} -Disallow: {{.RelPermalink}} -{{end}} -{{< /code >}} - -This template disallows all the pages of the site by creating one `Disallow` entry for each page. - -[config]: /getting-started/configuration/ -[lookup]: /templates/lookup-order/ -[robots]: http://www.robotstxt.org/ diff --git a/docs/content/en/templates/rss.md b/docs/content/en/templates/rss.md deleted file mode 100644 index 08049bfbd..000000000 --- a/docs/content/en/templates/rss.md +++ /dev/null @@ -1,120 +0,0 @@ ---- -title: RSS Templates -linktitle: RSS Templates -description: Hugo ships with its own RSS 2.0 template that requires almost no configuration, or you can create your own RSS templates. -date: 2017-02-01 -publishdate: 2017-02-01 -lastmod: 2017-02-01 -keywords: [rss, xml, templates] -categories: [templates] -menu: - docs: - parent: "templates" - weight: 150 -weight: 150 -sections_weight: 150 -draft: false -toc: true ---- - -## RSS Template Lookup Order - -See [Template Lookup Order](/templates/lookup-order/) for the complete reference. - -{{% note "Hugo Ships with an RSS Template" %}} -Hugo ships with its own [RSS 2.0 template](#the-embedded-rss-xml). The embedded template will be sufficient for most use cases. -{{% /note %}} - -RSS pages are of the type `Page` and have all the [page variables](/variables/page/) available to use in the templates. - -### Section RSS - -A [section’s][section] RSS will be rendered at `/<SECTION>/index.xml` (e.g., http://spf13.com/project/index.xml). - -Hugo provides the ability for you to define any RSS type you wish and can have different RSS files for each section and taxonomy. - -## Lookup Order for RSS Templates - -The table below shows the RSS template lookup order for the different page kinds. The first listing shows the lookup order when running with a theme (`demoTheme`). - -{{< datatable-filtered "output" "layouts" "OutputFormat == RSS" "Example" "OutputFormat" "Suffix" "Template Lookup Order" >}} - -## Configure RSS - -By default, Hugo will create an unlimited number of RSS entries. You can limit the number of articles included in the built-in RSS templates by assigning a numeric value to `rssLimit:` field in your project's [`config` file][config]. - -The following values will also be included in the RSS output if specified in your site’s configuration: - -```toml -languageCode = "en-us" -copyright = "This work is licensed under a Creative Commons Attribution-ShareAlike 4.0 International License." - -[author] - name = "My Name Here" -``` - -## The Embedded rss.xml - -This is the default RSS template that ships with Hugo. It adheres to the [RSS 2.0 Specification][RSS 2.0]. - -```xml -{{ printf "<?xml version=\"1.0\" encoding=\"utf-8\" standalone=\"yes\" ?>" | safeHTML }} -<rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom"> - <channel> - <title>{{ if eq .Title .Site.Title }}{{ .Site.Title }}{{ else }}{{ with .Title }}{{.}} on {{ end }}{{ .Site.Title }}{{ end }}</title> - <link>{{ .Permalink }}</link> - <description>Recent content {{ if ne .Title .Site.Title }}{{ with .Title }}in {{.}} {{ end }}{{ end }}on {{ .Site.Title }}</description> - <generator>Hugo -- gohugo.io</generator>{{ with .Site.LanguageCode }} - <language>{{.}}</language>{{end}}{{ with .Site.Author.email }} - <managingEditor>{{.}}{{ with $.Site.Author.name }} ({{.}}){{end}}</managingEditor>{{end}}{{ with .Site.Author.email }} - <webMaster>{{.}}{{ with $.Site.Author.name }} ({{.}}){{end}}</webMaster>{{end}}{{ with .Site.Copyright }} - <copyright>{{.}}</copyright>{{end}}{{ if not .Date.IsZero }} - <lastBuildDate>{{ .Date.Format "Mon, 02 Jan 2006 15:04:05 -0700" | safeHTML }}</lastBuildDate>{{ end }} - {{ with .OutputFormats.Get "RSS" }} - {{ printf "<atom:link href=%q rel=\"self\" type=%q />" .Permalink .MediaType | safeHTML }} - {{ end }} - {{ range .Pages }} - <item> - <title>{{ .Title }}</title> - <link>{{ .Permalink }}</link> - <pubDate>{{ .Date.Format "Mon, 02 Jan 2006 15:04:05 -0700" | safeHTML }}</pubDate> - {{ with .Site.Author.email }}<author>{{.}}{{ with $.Site.Author.name }} ({{.}}){{end}}</author>{{end}} - <guid>{{ .Permalink }}</guid> - <description>{{ .Summary | html }}</description> - </item> - {{ end }} - </channel> -</rss> -``` - -## Reference your RSS Feed in `<head>` - -In your `header.html` template, you can specify your RSS feed in your `<head></head>` tag using Hugo's [Output Formats][Output Formats] like this: - -```go-html-template -{{ range .AlternativeOutputFormats -}} - {{ printf `<link rel="%s" type="%s" href="%s" title="%s" />` .Rel .MediaType.Type .Permalink $.Site.Title | safeHTML }} -{{ end -}} -``` - -If you only want the RSS link, you can query the formats: - -```go-html-template -{{ with .OutputFormats.Get "rss" -}} - {{ printf `<link rel="%s" type="%s" href="%s" title="%s" />` .Rel .MediaType.Type .Permalink $.Site.Title | safeHTML }} -{{ end -}} -``` - -Either of the two snippets above will generate the below `link` tag on the site homepage for RSS output: - -```html -<link rel="alternate" type="application/rss+xml" href="https://example.com/index.xml" title="Site Title"> -``` - -_We are assuming `BaseURL` to be `https://example.com/` and `$.Site.Title` to be `"Site Title"` in this example._ - -[config]: /getting-started/configuration/ -[embedded]: #the-embedded-rss-xml -[RSS 2.0]: http://cyber.law.harvard.edu/rss/rss.html "RSS 2.0 Specification" -[section]: /content-management/sections/ -[Output Formats]: /templates/output-formats/#link-to-output-formats diff --git a/docs/content/en/templates/section-templates.md b/docs/content/en/templates/section-templates.md deleted file mode 100644 index 577529e3f..000000000 --- a/docs/content/en/templates/section-templates.md +++ /dev/null @@ -1,122 +0,0 @@ ---- -title: Section Page Templates -linktitle: Section Templates -description: Templates used for section pages are **lists** and therefore have all the variables and methods available to list pages. -date: 2017-02-01 -publishdate: 2017-02-01 -lastmod: 2017-02-01 -categories: [templates] -keywords: [lists,sections,templates] -menu: - docs: - parent: "templates" - weight: 40 -weight: 40 -sections_weight: 40 -draft: false -aliases: [/templates/sections/] -toc: true ---- - -## Add Content and Front Matter to Section Templates - -To effectively leverage section page templates, you should first understand Hugo's [content organization](/content-management/organization/) and, specifically, the purpose of `_index.md` for adding content and front matter to section and other list pages. - -## Section Template Lookup Order - -See [Template Lookup](/templates/lookup-order/). - -## Page Kinds - -Every `Page` in Hugo has a `.Kind` attribute. - -| Kind | Description | Example | -|----------------|--------------------------------------------------------------------|-------------------------------------------------------------------------------| -| `home` | The home page | `/index.html` | -| `page` | A page showing a _regular page_ | `my-post` page (`/posts/my-post/index.html`) | -| `section` | A page listing _regular pages_ from a given [_section_][sections] | `posts` section (`/posts/index.html`) | -| `taxonomy` | A page listing _regular pages_ from a given _taxonomy term_ | page for the term `awesome` from `tags` taxonomy (`/tags/awesome/index.html`) | -| `taxonomyTerm` | A page listing terms from a given _taxonomy_ | page for the `tags` taxonomy (`/tags/index.html`) | - -## `.Site.GetPage` with Sections - -`Kind` can easily be combined with the [`where` function][where] in your templates to create kind-specific lists of content. This method is ideal for creating lists, but there are times where you may want to fetch just the index page of a single section via the section's path. - -The [`.GetPage` function][getpage] looks up an index page of a given `Kind` and `path`. - -You can call `.Site.GetPage` with two arguments: `kind` (one of the valid values -of `Kind` from above) and `kind value`. - -Examples: - -- `{{ .Site.GetPage "section" "posts" }}` -- `{{ .Site.GetPage "page" "search" }}` - -## Example: Creating a Default Section Template - -{{< code file="layouts/_default/section.html" download="section.html" >}} -{{ define "main" }} - <main> - {{ .Content }} - <ul class="contents"> - {{ range .Paginator.Pages }} - <li>{{.Title}} - <div> - {{ partial "summary.html" . }} - </div> - </li> - {{ end }} - </ul> - {{ partial "pagination.html" . }} - </main> -{{ end }} -{{< /code >}} - -### Example: Using `.Site.GetPage` - -The `.Site.GetPage` example that follows assumes the following project directory structure: - -``` -. -└── content - ├── blog - │ ├── _index.md # "title: My Hugo Blog" in the front matter - │ ├── post-1.md - │ ├── post-2.md - │ └── post-3.md - └── events #Note there is no _index.md file in "events" - ├── event-1.md - └── event-2.md -``` - -`.Site.GetPage` will return `nil` if no `_index.md` page is found. Therefore, if `content/blog/_index.md` does not exist, the template will output the section name: - -``` -<h1>{{ with .Site.GetPage "section" "blog" }}{{ .Title }}{{ end }}</h1> -``` - -Since `blog` has a section index page with front matter at `content/blog/_index.md`, the above code will return the following result: - -``` -<h1>My Hugo Blog</h1> -``` - -If we try the same code with the `events` section, however, Hugo will default to the section title because there is no `content/events/_index.md` from which to pull content and front matter: - -``` -<h1>{{ with .Site.GetPage "section" "events" }}{{ .Title }}{{ end }}</h1> -``` - -Which then returns the following: - -``` -<h1>Events</h1> -``` - - -[contentorg]: /content-management/organization/ -[getpage]: /functions/getpage/ -[lists]: /templates/lists/ -[lookup]: /templates/lookup-order/ -[where]: /functions/where/ -[sections]: /content-management/sections/ diff --git a/docs/content/en/templates/shortcode-templates.md b/docs/content/en/templates/shortcode-templates.md deleted file mode 100644 index cfe0d316b..000000000 --- a/docs/content/en/templates/shortcode-templates.md +++ /dev/null @@ -1,418 +0,0 @@ ---- -title: Create Your Own Shortcodes -linktitle: Shortcode Templates -description: You can extend Hugo's built-in shortcodes by creating your own using the same templating syntax as that for single and list pages. -date: 2017-02-01 -publishdate: 2017-02-01 -lastmod: 2017-02-01 -categories: [templates] -keywords: [shortcodes,templates] -menu: - docs: - parent: "templates" - weight: 100 -weight: 100 -sections_weight: 100 -draft: false -aliases: [] -toc: true ---- - -Shortcodes are a means to consolidate templating into small, reusable snippets that you can embed directly inside of your content. In this sense, you can think of shortcodes as the intermediary between [page and list templates][templates] and [basic content files][]. - -{{% note %}} -Hugo also ships with built-in shortcodes for common use cases. (See [Content Management: Shortcodes](/content-management/shortcodes/).) -{{% /note %}} - -## Create Custom Shortcodes - -Hugo's built-in shortcodes cover many common, but not all, use cases. Luckily, Hugo provides the ability to easily create custom shortcodes to meet your website's needs. - -{{< youtube Eu4zSaKOY4A >}} - -### File Location - -To create a shortcode, place an HTML template in the `layouts/shortcodes` directory of your [source organization][]. Consider the file name carefully since the shortcode name will mirror that of the file but without the `.html` extension. For example, `layouts/shortcodes/myshortcode.html` will be called with either `{{</* myshortcode /*/>}}` or `{{%/* myshortcode /*/%}}` depending on the type of parameters you choose. - -You can organize your shortcodes in subfolders, e.g. in `layouts/shortcodes/boxes`. These shortcodes would then be accessible with their relative path, e.g: - -``` -{{</* boxes/square */>}} -``` - -Note the forward slash. - -### Shortcode Template Lookup Order - -Shortcode templates have a simple [lookup order][]: - -1. `/layouts/shortcodes/<SHORTCODE>.html` -2. `/themes/<THEME>/layouts/shortcodes/<SHORTCODE>.html` - -### Positional vs Named Parameters - -You can create shortcodes using the following types of parameters: - -* Positional parameters -* Named parameters -* Positional *or* named parameters (i.e, "flexible") - -In shortcodes with positional parameters, the order of the parameters is important. If a shortcode has a single required value (e.g., the `youtube` shortcode below), positional parameters work very well and require less typing from content authors. - -For more complex layouts with multiple or optional parameters, named parameters work best. While less terse, named parameters require less memorization from a content author and can be added in a shortcode declaration in any order. - -Allowing both types of parameters (i.e., a "flexible" shortcode) is useful for complex layouts where you want to set default values that can be easily overridden by users. - -### Access Parameters - -All shortcode parameters can be accessed via the `.Get` method. Whether you pass a key (i.e., string) or a number to the `.Get` method depends on whether you are accessing a named or positional parameter, respectively. - -To access a parameter by name, use the `.Get` method followed by the named parameter as a quoted string: - -``` -{{ .Get "class" }} -``` - -To access a parameter by position, use the `.Get` followed by a numeric position, keeping in mind that positional parameters are zero-indexed: - -``` -{{ .Get 0 }} -``` - -For the second position, you would just use: - -``` -{{ .Get 1 }} -``` - -`with` is great when the output depends on a parameter being set: - -``` -{{ with .Get "class"}} class="{{.}}"{{ end }} -``` - -`.Get` can also be used to check if a parameter has been provided. This is -most helpful when the condition depends on either of the values, or both: - -``` -{{ or .Get "title" | .Get "alt" | if }} alt="{{ with .Get "alt"}}{{.}}{{else}}{{.Get "title"}}{{end}}"{{ end }} -``` - -#### `.Inner` - -If a closing shortcode is used, the `.Inner` variable will be populated with all of the content between the opening and closing shortcodes. If a closing shortcode is required, you can check the length of `.Inner` as an indicator of its existence. - -A shortcode with content declared via the `.Inner` variable can also be declared without the inline content and without the closing shortcode by using the self-closing syntax: - -``` -{{</* innershortcode /*/>}} -``` - -#### `.Params` - -The `.Params` variable in shortcodes contains the list parameters passed to shortcode for more complicated use cases. You can also access higher-scoped parameters with the following logic: - -`$.Params` -: these are the parameters passed directly into the shortcode declaration (e.g., a YouTube video ID) - -`$.Page.Params` -: refers to the page's params; the "page" in this case refers to the content file in which the shortcode is declared (e.g., a `shortcode_color` field in a content's front matter could be accessed via `$.Page.Params.shortcode_color`). - -`$.Page.Site.Params` -: refers to global variables as defined in your [site's configuration file][config]. - -#### `.IsNamedParams` - -The `.IsNamedParams` variable checks whether the shortcode declaration uses named parameters and returns a boolean value. - -For example, you could create an `image` shortcode that can take either a `src` named parameter or the first positional parameter, depending on the preference of the content's author. Let's assume the `image` shortcode is called as follows: - -``` -{{</* image src="images/my-image.jpg"*/>}} -``` - -You could then include the following as part of your shortcode templating: - -``` -{{ if .IsNamedParams }} -<img src="{{.Get "src" }}" alt=""> -{{ else }} -<img src="{{.Get 0}}" alt=""> -{{ end }} -``` - -See the [example Vimeo shortcode][vimeoexample] below for `.IsNamedParams` in action. - -{{% warning %}} -While you can create shortcode templates that accept both positional and named parameters, you *cannot* declare shortcodes in content with a mix of parameter types. Therefore, a shortcode declared like `{{</* image src="images/my-image.jpg" "This is my alt text" */>}}` will return an error. -{{% /warning %}} - -You can also use the variable `.Page` to access all the normal [page variables][pagevars]. - -A shortcodes can also be nested. In a nested shortcode, you can access the parent shortcode context with [`.Parent` variable][shortcodesvars]. This can be very useful for inheritance of common shortcode parameters from the root. - -### Checking for Existence - -You can check if a specific shortcode is used on a page by calling `.HasShortcode` in that page template, providing the name of the shortcode. This is sometimes useful when you want to include specific scripts or styles in the header that are only used by that shortcode. - -## Custom Shortcode Examples - -The following are examples of the different types of shortcodes you can create via shortcode template files in `/layouts/shortcodes`. - -### Single-word Example: `year` - -Let's assume you would like to keep mentions of your copyright year current in your content files without having to continually review your markdown. Your goal is to be able to call the shortcode as follows: - -``` -{{</* year */>}} -``` - -{{< code file="/layouts/shortcodes/year.html" >}} -{{ now.Format "2006" }} -{{< /code >}} - -### Single Positional Example: `youtube` - -Embedded videos are a common addition to markdown content that can quickly become unsightly. The following is the code used by [Hugo's built-in YouTube shortcode][youtubeshortcode]: - -``` -{{</* youtube 09jf3ow9jfw */>}} -``` - -Would load the template at `/layouts/shortcodes/youtube.html`: - -{{< code file="/layouts/shortcodes/youtube.html" >}} -<div class="embed video-player"> -<iframe class="youtube-player" type="text/html" width="640" height="385" src="http://www.youtube.com/embed/{{ index .Params 0 }}" allowfullscreen frameborder="0"> -</iframe> -</div> -{{< /code >}} - -{{< code file="youtube-embed.html" copy="false" >}} -<div class="embed video-player"> - <iframe class="youtube-player" type="text/html" - width="640" height="385" - src="http://www.youtube.com/embed/09jf3ow9jfw" - allowfullscreen frameborder="0"> - </iframe> -</div> -{{< /code >}} - -### Single Named Example: `image` - -Let's say you want to create your own `img` shortcode rather than use Hugo's built-in [`figure` shortcode][figure]. Your goal is to be able to call the shortcode as follows in your content files: - -{{< code file="content-image.md" >}} -{{</* img src="/media/spf13.jpg" title="Steve Francia" */>}} -{{< /code >}} - -You have created the shortcode at `/layouts/shortcodes/img.html`, which loads the following shortcode template: - -{{< code file="/layouts/shortcodes/img.html" >}} -<!-- image --> -<figure {{ with .Get "class" }}class="{{.}}"{{ end }}> - {{ with .Get "link"}}<a href="{{.}}">{{ end }} - <img src="{{ .Get "src" }}" {{ if or (.Get "alt") (.Get "caption") }}alt="{{ with .Get "alt"}}{{.}}{{else}}{{ .Get "caption" }}{{ end }}"{{ end }} /> - {{ if .Get "link"}}</a>{{ end }} - {{ if or (or (.Get "title") (.Get "caption")) (.Get "attr")}} - <figcaption>{{ if isset .Params "title" }} - <h4>{{ .Get "title" }}</h4>{{ end }} - {{ if or (.Get "caption") (.Get "attr")}}<p> - {{ .Get "caption" }} - {{ with .Get "attrlink"}}<a href="{{.}}"> {{ end }} - {{ .Get "attr" }} - {{ if .Get "attrlink"}}</a> {{ end }} - </p> {{ end }} - </figcaption> - {{ end }} -</figure> -<!-- image --> -{{< /code >}} - -Would be rendered as: - -{{< code file="img-output.html" copy="false" >}} -<figure> - <img src="/media/spf13.jpg" /> - <figcaption> - <h4>Steve Francia</h4> - </figcaption> -</figure> -{{< /code >}} - -### Single Flexible Example: `vimeo` - -``` -{{</* vimeo 49718712 */>}} -{{</* vimeo id="49718712" class="flex-video" */>}} -``` - -Would load the template found at `/layouts/shortcodes/vimeo.html`: - -{{< code file="/layouts/shortcodes/vimeo.html" >}} -{{ if .IsNamedParams }} - <div class="{{ if .Get "class" }}{{ .Get "class" }}{{ else }}vimeo-container{{ end }}"> - <iframe src="//player.vimeo.com/video/{{ .Get "id" }}" allowfullscreen></iframe> - </div> -{{ else }} - <div class="{{ if len .Params | eq 2 }}{{ .Get 1 }}{{ else }}vimeo-container{{ end }}"> - <iframe src="//player.vimeo.com/video/{{ .Get 0 }}" allowfullscreen></iframe> - </div> -{{ end }} -{{< /code >}} - -Would be rendered as: - -{{< code file="vimeo-iframes.html" copy="false" >}} -<div class="vimeo-container"> - <iframe src="//player.vimeo.com/video/49718712" allowfullscreen></iframe> -</div> -<div class="flex-video"> - <iframe src="//player.vimeo.com/video/49718712" allowfullscreen></iframe> -</div> -{{< /code >}} - -### Paired Example: `highlight` - -The following is taken from `highlight`, which is a [built-in shortcode][] that ships with Hugo. - -{{< code file="highlight-example.md" >}} -{{</* highlight html */>}} - <html> - <body> This HTML </body> - </html> -{{</* /highlight */>}} -{{< /code >}} - -The template for the `highlight` shortcode uses the following code, which is already included in Hugo: - -``` -{{ .Get 0 | highlight .Inner }} -``` - -The rendered output of the HTML example code block will be as follows: - -{{< code file="syntax-highlighted.html" copy="false" >}} -<div class="highlight" style="background: #272822"><pre style="line-height: 125%"><span style="color: #f92672"><html></span> - <span style="color: #f92672"><body></span> This HTML <span style="color: #f92672"></body></span> -<span style="color: #f92672"></html></span> -</pre></div> -{{< /code >}} - -{{% note %}} -The preceding shortcode makes use of a Hugo-specific template function called `highlight`, which uses [Pygments](http://pygments.org) to add syntax highlighting to the example HTML code block. See the [developer tools page on syntax highlighting](/tools/syntax-highlighting/) for more information. -{{% /note %}} - -### Nested Shortcode: Image Gallery - -Hugo's [`.Parent` shortcode variable][parent] returns a boolean value depending on whether the shortcode in question is called within the context of a *parent* shortcode. This provides an inheritance model for common shortcode parameters. - -The following example is contrived but demonstrates the concept. Assume you have a `gallery` shortcode that expects one named `class` parameter: - -{{< code file="layouts/shortcodes/gallery.html" >}} -<div class="{{.Get "class"}}"> - {{.Inner}} -</div> -{{< /code >}} - -You also have an `img` shortcode with a single named `src` parameter that you want to call inside of `gallery` and other shortcodes, so that the parent defines the context of each `img`: - -{{< code file="layouts/shortcodes/img.html" >}} -{{- $src := .Get "src" -}} -{{- with .Parent -}} - <img src="{{$src}}" class="{{.Get "class"}}-image"> -{{- else -}} - <img src="{{$src}}"> -{{- end }} -{{< /code >}} - -You can then call your shortcode in your content as follows: - -``` -{{</* gallery class="content-gallery" */>}} - {{</* img src="/images/one.jpg" */>}} - {{</* img src="/images/two.jpg" */>}} -{{</* /gallery */>}} -{{</* img src="/images/three.jpg" */>}} -``` - -This will output the following HTML. Note how the first two `img` shortcodes inherit the `class` value of `content-gallery` set with the call to the parent `gallery`, whereas the third `img` only uses `src`: - -``` -<div class="content-gallery"> - <img src="/images/one.jpg" class="content-gallery-image"> - <img src="/images/two.jpg" class="content-gallery-image"> -</div> -<img src="/images/three.jpg"> -``` - - -## Error Handling in Shortcodes - -Use the [errorf](/functions/errorf) template func and [.Position](/variables/shortcodes/) variable to get useful error messages in shortcodes: - -```bash -{{ with .Get "name" }} -{{ else }} -{{ errorf "missing value for param 'name': %s" .Position }} -{{ end }} -``` - -When the above fails, you will see an `ERROR` log similar to the below: - -```bash -ERROR 2018/11/07 10:05:55 missing value for param name: "/Users/bep/dev/go/gohugoio/hugo/docs/content/en/variables/shortcodes.md:32:1" -``` - -## More Shortcode Examples - -More shortcode examples can be found in the [shortcodes directory for spf13.com][spfscs] and the [shortcodes directory for the Hugo docs][docsshortcodes]. - - -## Inline Shortcodes - -Since Hugo 0.52, you can implement your shortcodes inline -- e.g. where you use them in the content file. This can be useful for scripting that you only need in one place. - -This feature is disabled by default, but can be enabled in your site config: - -{{< code-toggle file="config">}} -enableInlineShortcodes = true -{{< /code-toggle >}} - -It is disabled by default for security reasons. The security model used by Hugo's template handling assumes that template authors are trusted, but that the content files are not, so the templates are injection-safe from malformed input data. But in most situations you have full control over the content, too, and then `enableInlineShortcodes = true` would be considered safe. But it's something to be aware of: It allows ad-hoc [Go Text templates](https://golang.org/pkg/text/template/) to be executed from the content files. - -And once enabled, you can do this in your content files: - - ```go-text-template - {{</* time.inline */>}}{{ now }}{{</* /time.inline */>}} - ``` - -The above will print the current date and time. - - Note that an inline shortcode's inner content is parsed and executed as a Go text template with the same context as a regular shortcode template. - -This means that the current page can be accessed via `.Page.Title` etc. This also means that there are no concept of "nested inline shortcodes". - -The same inline shortcode can be reused later in the same content file, with different params if needed, using the self-closing syntax: - - ```go-text-template -{{</* time.inline /*/>}} -``` - - -[basic content files]: /content-management/formats/ "See how Hugo leverages markdown--and other supported formats--to create content for your website." -[built-in shortcode]: /content-management/shortcodes/ -[config]: /getting-started/configuration/ "Learn more about Hugo's built-in configuration variables as well as how to us your site's configuration file to include global key-values that can be used throughout your rendered website." -[Content Management: Shortcodes]: /content-management/shortcodes/#using-hugo-s-built-in-shortcodes "Check this section if you are not familiar with the definition of what a shortcode is or if you are unfamiliar with how to use Hugo's built-in shortcodes in your content files." -[source organization]: /getting-started/directory-structure/#directory-structure-explained "Learn how Hugo scaffolds new sites and what it expects to find in each of your directories." -[docsshortcodes]: https://github.com/gohugoio/hugo/tree/master/docs/layouts/shortcodes "See the shortcode source directory for the documentation site you're currently reading." -[figure]: /content-management/shortcodes/#figure -[hugosc]: /content-management/shortcodes/#using-hugo-s-built-in-shortcodes -[lookup order]: /templates/lookup-order/ "See the order in which Hugo traverses your template files to decide where and how to render your content at build time" -[pagevars]: /variables/page/ "See which variables you can leverage in your templating for page vs list templates." -[parent]: /variables/shortcodes/ -[shortcodesvars]: /variables/shortcodes/ "Certain variables are specific to shortcodes, although most .Page variables can be accessed within your shortcode template." -[spfscs]: https://github.com/spf13/spf13.com/tree/master/layouts/shortcodes "See more examples of shortcodes by visiting the shortcode directory of the source for spf13.com, the blog of Hugo's creator, Steve Francia." -[templates]: /templates/ "The templates section of the Hugo docs." -[vimeoexample]: #single-flexible-example-vimeo -[youtubeshortcode]: /content-management/shortcodes/#youtube "See how to use Hugo's built-in YouTube shortcode." diff --git a/docs/content/en/templates/single-page-templates.md b/docs/content/en/templates/single-page-templates.md deleted file mode 100644 index e8b72e598..000000000 --- a/docs/content/en/templates/single-page-templates.md +++ /dev/null @@ -1,92 +0,0 @@ ---- -title: Single Page Templates -linktitle: -description: The primary view of content in Hugo is the single view. Hugo will render every Markdown file provided with a corresponding single template. -date: 2017-02-01 -publishdate: 2017-02-01 -lastmod: 2017-04-06 -categories: [templates] -keywords: [page,templates] -menu: - docs: - parent: "templates" - weight: 60 -weight: 60 -sections_weight: 60 -draft: false -aliases: [/layout/content/] -toc: true ---- - -## Single Page Template Lookup Order - -See [Template Lookup](/templates/lookup-order/). - -## Example Single Page Templates - -Content pages are of the type `page` and will therefore have all the [page variables][pagevars] and [site variables][] available to use in their templates. - -### `posts/single.html` - -This single page template makes use of Hugo [base templates][], the [`.Format` function][] for dates, the [`.WordCount` page variable][pagevars], and ranges through the single content's specific [taxonomies][pagetaxonomy]. [`with`][] is also used to check whether the taxonomies are set in the front matter. - -{{< code file="layouts/posts/single.html" download="single.html" >}} -{{ define "main" }} -<section id="main"> - <h1 id="title">{{ .Title }}</h1> - <div> - <article id="content"> - {{ .Content }} - </article> - </div> -</section> -<aside id="meta"> - <div> - <section> - <h4 id="date"> {{ .Date.Format "Mon Jan 2, 2006" }} </h4> - <h5 id="wordcount"> {{ .WordCount }} Words </h5> - </section> - {{ with .Params.topics }} - <ul id="topics"> - {{ range . }} - <li><a href="{{ "topics" | absURL}}{{ . | urlize }}">{{ . }}</a> </li> - {{ end }} - </ul> - {{ end }} - {{ with .Params.tags }} - <ul id="tags"> - {{ range . }} - <li> <a href="{{ "tags" | absURL }}{{ . | urlize }}">{{ . }}</a> </li> - {{ end }} - </ul> - {{ end }} - </div> - <div> - {{ with .PrevInSection }} - <a class="previous" href="{{.Permalink}}"> {{.Title}}</a> - {{ end }} - {{ with .NextInSection }} - <a class="next" href="{{.Permalink}}"> {{.Title}}</a> - {{ end }} - </div> -</aside> -{{ end }} -{{< /code >}} - -To easily generate new instances of a content type (e.g., new `.md` files in a section like `project/`) with preconfigured front matter, use [content archetypes][archetypes]. - -[archetypes]: /content-management/archetypes/ -[base templates]: /templates/base/ -[config]: /getting-started/configuration/ -[content type]: /content-management/types/ -[directory structure]: /getting-started/directory-structure/ -[dry]: https://en.wikipedia.org/wiki/Don%27t_repeat_yourself -[`.Format` function]: /functions/format/ -[front matter]: /content-management/front-matter/ -[pagetaxonomy]: /templates/taxonomy-templates/#displaying-a-single-piece-of-content-s-taxonomies -[pagevars]: /variables/page/ -[partials]: /templates/partials/ -[section]: /content-management/sections/ -[site variables]: /variables/site/ -[spf13]: http://spf13.com/ -[`with`]: /functions/with/ diff --git a/docs/content/en/templates/sitemap-template.md b/docs/content/en/templates/sitemap-template.md deleted file mode 100644 index 9afc0d389..000000000 --- a/docs/content/en/templates/sitemap-template.md +++ /dev/null @@ -1,106 +0,0 @@ ---- -title: Sitemap Template -# linktitle: Sitemap -description: Hugo ships with a built-in template file observing the v0.9 of the Sitemap Protocol, but you can override this template if needed. -date: 2017-02-01 -publishdate: 2017-02-01 -lastmod: 2017-02-01 -categories: [templates] -keywords: [sitemap, xml, templates] -menu: - docs: - parent: "templates" - weight: 160 -weight: 160 -sections_weight: 160 -draft: false -aliases: [/layout/sitemap/,/templates/sitemap/] -toc: false ---- - -A single Sitemap template is used to generate the `sitemap.xml` file. -Hugo automatically comes with this template file. *No work is needed on -the users' part unless they want to customize `sitemap.xml`.* - -A sitemap is a `Page` and therefore has all the [page variables][pagevars] available to use in this template along with Sitemap-specific ones: - -`.Sitemap.ChangeFreq` -: The page change frequency - -`.Sitemap.Priority` -: The priority of the page - -`.Sitemap.Filename` -: The sitemap filename - -If provided, Hugo will use `/layouts/sitemap.xml` instead of the internal `sitemap.xml` template that ships with Hugo. - -## Sitemap Templates - -Hugo has built-on Sitemap templates, but you can provide your own if needed, in either `layouts/sitemap.xml` or `layouts/_default/sitemap.xml`. - -For multilingual sites, we also create a Sitemap index. You can provide a custom layout for that in either `layouts/sitemapindex.xml` or `layouts/_default/sitemapindex.xml`. - -## Hugo’s sitemap.xml - -This template respects the version 0.9 of the [Sitemap Protocol](http://www.sitemaps.org/protocol.html). - -```xml -{{ printf "<?xml version=\"1.0\" encoding=\"utf-8\" standalone=\"yes\" ?>" | safeHTML }} -<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9" - xmlns:xhtml="http://www.w3.org/1999/xhtml"> - {{ range .Data.Pages }} - <url> - <loc>{{ .Permalink }}</loc>{{ if not .Lastmod.IsZero }} - <lastmod>{{ safeHTML ( .Lastmod.Format "2006-01-02T15:04:05-07:00" ) }}</lastmod>{{ end }}{{ with .Sitemap.ChangeFreq }} - <changefreq>{{ . }}</changefreq>{{ end }}{{ if ge .Sitemap.Priority 0.0 }} - <priority>{{ .Sitemap.Priority }}</priority>{{ end }}{{ if .IsTranslated }}{{ range .Translations }} - <xhtml:link - rel="alternate" - hreflang="{{ .Lang }}" - href="{{ .Permalink }}" - />{{ end }} - <xhtml:link - rel="alternate" - hreflang="{{ .Lang }}" - href="{{ .Permalink }}" - />{{ end }} - </url> - {{ end }} -</urlset> -``` - -## Hugo's sitemapindex.xml - -This is used to create a Sitemap index in multilingual mode: - -```xml -{{ printf "<?xml version=\"1.0\" encoding=\"utf-8\" standalone=\"yes\" ?>" | safeHTML }} -<sitemapindex xmlns="http://www.sitemaps.org/schemas/sitemap/0.9"> - {{ range . }} - <sitemap> - <loc>{{ .SitemapAbsURL }}</loc> - {{ if not .LastChange.IsZero }} - <lastmod>{{ .LastChange.Format "2006-01-02T15:04:05-07:00" | safeHTML }}</lastmod> - {{ end }} - </sitemap> - {{ end }} -</sitemapindex> -``` - -## Configure `sitemap.xml` - -Defaults for `<changefreq>`, `<priority>` and `filename` values can be set in the site's config file, e.g.: - -{{< code-toggle file="config" >}} -[sitemap] - changefreq = "monthly" - priority = 0.5 - filename = "sitemap.xml" -{{</ code-toggle >}} - -The same fields can be specified in an individual content file's front matter in order to override the value assigned to that piece of content at render time. - - - -[pagevars]: /variables/page/ diff --git a/docs/content/en/templates/taxonomy-templates.md b/docs/content/en/templates/taxonomy-templates.md deleted file mode 100644 index b82a5175c..000000000 --- a/docs/content/en/templates/taxonomy-templates.md +++ /dev/null @@ -1,375 +0,0 @@ ---- -title: Taxonomy Templates -# linktitle: -description: Taxonomy templating includes taxonomy list pages, taxonomy terms pages, and using taxonomies in your single page templates. -date: 2017-02-01 -publishdate: 2017-02-01 -lastmod: 2017-02-01 -categories: [templates] -keywords: [taxonomies,metadata,front matter,terms,templates] -menu: - docs: - parent: "templates" - weight: 50 -weight: 50 -sections_weight: 50 -draft: false -aliases: [/taxonomies/displaying/,/templates/terms/,/indexes/displaying/,/taxonomies/templates/,/indexes/ordering/, /templates/taxonomies/, /templates/taxonomy/] -toc: true ---- - -<!-- NOTE! Check on https://github.com/gohugoio/hugo/issues/2826 for shifting of terms' pages to .Data.Pages AND -https://discourse.gohugo.io/t/how-to-specify-category-slug/4856/15 for original discussion.--> - -Hugo includes support for user-defined groupings of content called **taxonomies**. Taxonomies are classifications that demonstrate logical relationships between content. See [Taxonomies under Content Management](/content-management/taxonomies) if you are unfamiliar with how Hugo leverages this powerful feature. - -Hugo provides multiple ways to use taxonomies throughout your project templates: - -* Order the way content associated with a taxonomy term is displayed in a [taxonomy list template](#taxonomy-list-template) -* Order the way the terms for a taxonomy are displayed in a [taxonomy terms template](#taxonomy-terms-template) -* List a single content's taxonomy terms within a [single page template][] - -## Taxonomy List Templates - -Taxonomy list page templates are lists and therefore have all the variables and methods available to [list pages][lists]. - -### Taxonomy List Template Lookup Order - -See [Template Lookup](/templates/lookup-order/). - -## Taxonomy Terms Template - -### Taxonomy Terms Templates Lookup Order - -See [Template Lookup](/templates/lookup-order/). - -### Taxonomy Methods - -A Taxonomy is a `map[string]WeightedPages`. - -.Get(term) -: Returns the WeightedPages for a term. - -.Count(term) -: The number of pieces of content assigned to this term. - -.Alphabetical -: Returns an OrderedTaxonomy (slice) ordered by Term. - -.ByCount -: Returns an OrderedTaxonomy (slice) ordered by number of entries. - -.Reverse -: Returns an OrderedTaxonomy (slice) in reverse order. Must be used with an OrderedTaxonomy. - -### OrderedTaxonomy - -Since Maps are unordered, an OrderedTaxonomy is a special structure that has a defined order. - -```go -[]struct { - Name string - WeightedPages WeightedPages -} -``` - -Each element of the slice has: - -.Term -: The Term used. - -.WeightedPages -: A slice of Weighted Pages. - -.Count -: The number of pieces of content assigned to this term. - -.Pages -: All Pages assigned to this term. All [list methods][renderlists] are available to this. - -## WeightedPages - -WeightedPages is simply a slice of WeightedPage. - -```go -type WeightedPages []WeightedPage -``` - -.Count(term) -: The number of pieces of content assigned to this term. - -.Pages -: Returns a slice of pages, which then can be ordered using any of the [list methods][renderlists]. - -## Displaying custom metadata in Taxonomy Terms Templates - -If you need to display custom metadata for each taxonomy term, you will need to create a page for that term at `/content/<TAXONOMY>/<TERM>/_index.md` and add your metadata in its front matter, [as explained in the taxonomies documentation](/content-management/taxonomies/#add-custom-meta-data-to-a-taxonomy-term). Based on the Actors taxonomy example shown there, within your taxonomy terms template, you may access your custom fields by iterating through the variable `.Pages` as such: - -```go-html-template -<ul> - {{ range .Pages }} - <li> - <a href="{{ .Permalink }}">{{ .Title }}</a> - {{ .Params.wikipedia }} - </li> - {{ end }} -</ul> -``` - -<!-- Begin /taxonomies/ordering/ --> - -## Order Taxonomies - -Taxonomies can be ordered by either alphabetical key or by the number of content pieces assigned to that key. - -### Order Alphabetically Example - -In Hugo 0.55 and later you can do: - -```go-html-template -<ul> - {{ range .Data.Terms.Alphabetical }} - <li><a href="{{ .Page.Permalink }}">{{ .Page.Title }}</a> {{ .Count }}</li> - {{ end }} -</ul> -``` - -Before that you would have to do something like: - -```go-html-template -<ul> - {{ $type := .Type }} - {{ range $key, $value := .Data.Terms.Alphabetical }} - {{ $name := .Name }} - {{ $count := .Count }} - {{ with $.Site.GetPage (printf "/%s/%s" $type $name) }} - <li><a href="{{ .Permalink }}">{{ $name }}</a> {{ $count }}</li> - {{ end }} - {{ end }} -</ul> -``` - - -<!-- [See Also Taxonomy Lists](/templates/list/) --> - -## Order Content within Taxonomies - -Hugo uses both `date` and `weight` to order content within taxonomies. - -Each piece of content in Hugo can optionally be assigned a date. It can also be assigned a weight for each taxonomy it is assigned to. - -When iterating over content within taxonomies, the default sort is the same as that used for [section and list pages]() first by weight then by date. This means that if the weights for two pieces of content are the same, than the more recent content will be displayed first. The default weight for any piece of content is 0. - -### Assign Weight - -Content can be assigned weight for each taxonomy that it's assigned to. - -``` -+++ -tags = [ "a", "b", "c" ] -tags_weight = 22 -categories = ["d"] -title = "foo" -categories_weight = 44 -+++ -Front Matter with weighted tags and categories -``` - -The convention is `taxonomyname_weight`. - -In the above example, this piece of content has a weight of 22 which applies to the sorting when rendering the pages assigned to the "a", "b" and "c" values of the 'tag' taxonomy. - -It has also been assigned the weight of 44 when rendering the 'd' category. - -With this the same piece of content can appear in different positions in different taxonomies. - -Currently taxonomies only support the default ordering of content which is weight -> date. - -<!-- Begin /taxonomies/templates/ --> - -There are two different templates that the use of taxonomies will require you to provide. - -Both templates are covered in detail in the templates section. - -A [list template](/templates/list/) is any template that will be used to render multiple pieces of content in a single html page. This template will be used to generate all the automatically created taxonomy pages. - -A [taxonomy terms template](/templates/terms/) is a template used to -generate the list of terms for a given template. - -<!-- Begin /taxonomies/displaying/ --> - -There are four common ways you can display the data in your -taxonomies in addition to the automatic taxonomy pages created by hugo -using the [list templates](/templates/list/): - -1. For a given piece of content, you can list the terms attached -2. For a given piece of content, you can list other content with the same - term -3. You can list all terms for a taxonomy -4. You can list all taxonomies (with their terms) - -## Display a Single Piece of Content's Taxonomies - -Within your content templates, you may wish to display the taxonomies that piece of content is assigned to. - -Because we are leveraging the front matter system to define taxonomies for content, the taxonomies assigned to each content piece are located in the usual place (i.e., `.Params.<TAXONOMYPLURAL>`). - -### Example: List Tags in a Single Page Template - -```go-html-template -{{ $taxo := "tags" }} <!-- Use the plural form here --> -<ul id="{{ $taxo }}"> - {{ range .Param $taxo }} - {{ $name := . }} - {{ with $.Site.GetPage (printf "/%s/%s" $taxo ($name | urlize)) }} - <li><a href="{{ .Permalink }}">{{ $name }}</a></li> - {{ end }} - {{ end }} -</ul> -``` - -If you want to list taxonomies inline, you will have to take care of optional plural endings in the title (if multiple taxonomies), as well as commas. Let's say we have a taxonomy "directors" such as `directors: [ "Joel Coen", "Ethan Coen" ]` in the TOML-format front matter. - -To list such taxonomies, use the following: - -### Example: Comma-delimit Tags in a Single Page Template - -```go-html-template -{{ $taxo := "directors" }} <!-- Use the plural form here --> -{{ with .Param $taxo }} - <strong>Director{{ if gt (len .) 1 }}s{{ end }}:</strong> - {{ range $index, $director := . }} - {{- if gt $index 0 }}, {{ end -}} - {{ with $.Site.GetPage (printf "/%s/%s" $taxo $director) -}} - <a href="{{ .Permalink }}">{{ $director }}</a> - {{- end -}} - {{- end -}} -{{ end }} -``` - -Alternatively, you may use the [delimit template function][delimit] as a shortcut if the taxonomies should just be listed with a separator. See {{< gh 2143 >}} on GitHub for discussion. - -## List Content with the Same Taxonomy Term - -If you are using a taxonomy for something like a series of posts, you can list individual pages associated with the same taxonomy. This is also a quick and dirty method for showing related content: - -### Example: Showing Content in Same Series - -```go-html-template -<ul> - {{ range .Site.Taxonomies.series.golang }} - <li><a href="{{ .Page.RelPermalink }}">{{ .Page.Title }}</a></li> - {{ end }} -</ul> -``` - -## List All content in a Given taxonomy - -This would be very useful in a sidebar as “featured content”. You could even have different sections of “featured content” by assigning different terms to the content. - -### Example: Grouping "Featured" Content - -```go-html-template -<section id="menu"> - <ul> - {{ range $key, $taxonomy := .Site.Taxonomies.featured }} - <li>{{ $key }}</li> - <ul> - {{ range $taxonomy.Pages }} - <li hugo-nav="{{ .RelPermalink}}"><a href="{{ .Permalink}}">{{ .LinkTitle }}</a></li> - {{ end }} - </ul> - {{ end }} - </ul> -</section> -``` - -## Render a Site's Taxonomies - -If you wish to display the list of all keys for your site's taxonomy, you can retrieve them from the [`.Site` variable][sitevars] available on every page. - -This may take the form of a tag cloud, a menu, or simply a list. - -The following example displays all terms in a site's tags taxonomy: - -### Example: List All Site Tags {#example-list-all-site-tags} - -In Hugo 0.55 and later you can simply do: - -```go-html-template -<ul> - {{ range .Site.Taxonomies.tags }} - <li><a href="{{ .Page.Permalink }}">{{ .Page.Title }}</a> {{ .Count }}</li> - {{ end }} -</ul> -``` - -Before that you would do something like this: - -{{< todo >}}Clean up rest of the taxonomy examples re Hugo 0.55.{{< /todo >}} - -```go-html-template -<ul id="all-tags"> - {{ range $name, $taxonomy := .Site.Taxonomies.tags }} - {{ with $.Site.GetPage (printf "/tags/%s" $name) }} - <li><a href="{{ .Permalink }}">{{ $name }}</a></li> - {{ end }} - {{ end }} -</ul> -``` - -### Example: List All Taxonomies, Terms, and Assigned Content - -This example will list all taxonomies and their terms, as well as all the content assigned to each of the terms. - -{{< code file="layouts/partials/all-taxonomies.html" download="all-taxonomies.html" download="all-taxonomies.html" >}} -<section> - <ul id="all-taxonomies"> - {{ range $taxonomy_term, $taxonomy := .Site.Taxonomies }} - {{ with $.Site.GetPage (printf "/%s" $taxonomy_term) }} - <li><a href="{{ .Permalink }}">{{ $taxonomy_term }}</a> - <ul> - {{ range $key, $value := $taxonomy }} - <li>{{ $key }}</li> - <ul> - {{ range $value.Pages }} - <li hugo-nav="{{ .RelPermalink}}"> - <a href="{{ .Permalink}}">{{ .LinkTitle }}</a> - </li> - {{ end }} - </ul> - {{ end }} - </ul> - </li> - {{ end }} - {{ end }} - </ul> -</section> -{{< /code >}} - -## `.Site.GetPage` for Taxonomies - -Because taxonomies are lists, the [`.GetPage` function][getpage] can be used to get all the pages associated with a particular taxonomy term using a terse syntax. The following ranges over the full list of tags on your site and links to each of the individual taxonomy pages for each term without having to use the more fragile URL construction of the ["List All Site Tags" example above]({{< relref "#example-list-all-site-tags" >}}): - -{{< code file="links-to-all-tags.html" >}} -{{ $taxo := "tags" }} -<ul class="{{ $taxo }}"> - {{ with ($.Site.GetPage (printf "/%s" $taxo)) }} - {{ range .Pages }} - <li><a href="{{ .Permalink }}">{{ .Title}}</a></li> - {{ end }} - {{ end }} -</ul> -{{< /code >}} - -<!-- TODO: ### `.Site.GetPage` Taxonomy List Example --> - -<!-- TODO: ### `.Site.GetPage` Taxonomy Terms Example --> - - -[delimit]: /functions/delimit/ -[getpage]: /functions/getpage/ -[lists]: /templates/lists/ -[renderlists]: /templates/lists/ -[single page template]: /templates/single-page-templates/ -[sitevars]: /variables/site/ diff --git a/docs/content/en/templates/template-debugging.md b/docs/content/en/templates/template-debugging.md deleted file mode 100644 index bba84b9fe..000000000 --- a/docs/content/en/templates/template-debugging.md +++ /dev/null @@ -1,81 +0,0 @@ ---- -title: Template Debugging -# linktitle: Template Debugging -description: You can use Go templates' `printf` function to debug your Hugo templates. These snippets provide a quick and easy visualization of the variables available to you in different contexts. -godocref: http://golang.org/pkg/fmt/ -date: 2017-02-01 -publishdate: 2017-02-01 -lastmod: 2017-02-01 -categories: [templates] -keywords: [debugging,troubleshooting] -menu: - docs: - parent: "templates" - weight: 180 -weight: 180 -sections_weight: 180 -draft: false -aliases: [] -toc: false ---- - -Here are some snippets you can add to your template to answer some common questions. - -These snippets use the `printf` function available in all Go templates. This function is an alias to the Go function, [fmt.Printf](http://golang.org/pkg/fmt/). - -## What Variables are Available in this Context? - -You can use the template syntax, `$.`, to get the top-level template context from anywhere in your template. This will print out all the values under, `.Site`. - -``` -{{ printf "%#v" $.Site }} -``` - -This will print out the value of `.Permalink`: - - -``` -{{ printf "%#v" .Permalink }} -``` - - -This will print out a list of all the variables scoped to the current context -(`.`, aka ["the dot"][tempintro]). - - -``` -{{ printf "%#v" . }} -``` - - -When developing a [homepage][], what does one of the pages you're looping through look like? - -``` -{{ range .Pages }} - {{/* The context, ".", is now each one of the pages as it goes through the loop */}} - {{ printf "%#v" . }} -{{ end }} -``` - -{{% note "`.Pages` on the Homepage" %}} -`.Pages` on the homepage is equivalent to `.Site.RegularPages`. -{{% /note %}} - -## Why Am I Showing No Defined Variables? - -Check that you are passing variables in the `partial` function: - -``` -{{ partial "header" }} -``` - -This example will render the header partial, but the header partial will not have access to any contextual variables. You need to pass variables explicitly. For example, note the addition of ["the dot"][tempintro]. - -``` -{{ partial "header" . }} -``` - -The dot (`.`) is considered fundamental to understanding Hugo templating. For more information, see [Introduction to Hugo Templating][tempintro]. - -[homepage]: /templates/homepage/ -[tempintro]: /templates/introduction/ diff --git a/docs/content/en/templates/views.md b/docs/content/en/templates/views.md deleted file mode 100644 index eb158eed0..000000000 --- a/docs/content/en/templates/views.md +++ /dev/null @@ -1,121 +0,0 @@ ---- -title: Content View Templates -# linktitle: Content Views -description: Hugo can render alternative views of your content, which is especially useful in list and summary views. -date: 2017-02-01 -publishdate: 2017-02-01 -lastmod: 2017-02-01 -categories: [templates] -keywords: [views] -menu: - docs: - parent: "templates" - weight: 70 -weight: 70 -sections_weight: 70 -draft: false -aliases: [] -toc: true ---- - -These alternative **content views** are especially useful in [list templates][lists]. - -The following are common use cases for content views: - -* You want content of every type to be shown on the homepage but only with limited [summary views][summaries]. -* You only want a bulleted list of your content on a [taxonomy list page][taxonomylists]. Views make this very straightforward by delegating the rendering of each different type of content to the content itself. - -## Create a Content View - -To create a new view, create a template in each of your different content type directories with the view name. The following example contains an "li" view and a "summary" view for the `posts` and `project` content types. As you can see, these sit next to the [single content view][single] template, `single.html`. You can even provide a specific view for a given type and continue to use the `_default/single.html` for the primary view. - -``` - ▾ layouts/ - ▾ posts/ - li.html - single.html - summary.html - ▾ project/ - li.html - single.html - summary.html -``` - -Hugo also has support for a default content template to be used in the event that a specific content view template has not been provided for that type. Content views can also be defined in the `_default` directory and will work the same as list and single templates who eventually trickle down to the `_default` directory as a matter of the lookup order. - - -``` -▾ layouts/ - ▾ _default/ - li.html - single.html - summary.html -``` - -## Which Template Will be Rendered? - -The following is the [lookup order][lookup] for content views: - -1. `/layouts/<TYPE>/<VIEW>.html` -2. `/layouts/_default/<VIEW>.html` -3. `/themes/<THEME>/layouts/<TYPE>/<VIEW>.html` -4. `/themes/<THEME>/layouts/_default/<VIEW>.html` - -## Example: Content View Inside a List - -The following example demonstrates how to use content views inside of your [list templates][lists]. - -### `list.html` - -In this example, `.Render` is passed into the template to call the [render function][render]. `.Render` is a special function that instructs content to render itself with the view template provided as the first argument. In this case, the template is going to render the `summary.html` view that follows: - -{{< code file="layouts/_default/list.html" download="list.html" >}} -<main id="main"> - <div> - <h1 id="title">{{ .Title }}</h1> - {{ range .Pages }} - {{ .Render "summary"}} - {{ end }} - </div> -</main> -{{< /code >}} - -### `summary.html` - -Hugo will pass the entire page object to the following `summary.html` view template. (See [Page Variables][pagevars] for a complete list.) - -{{< code file="layouts/_default/summary.html" download="summary.html" >}} -<article class="post"> - <header> - <h2><a href='{{ .Permalink }}'> {{ .Title }}</a> </h2> - <div class="post-meta">{{ .Date.Format "Mon, Jan 2, 2006" }} - {{ .FuzzyWordCount }} Words </div> - </header> - {{ .Summary }} - <footer> - <a href='{{ .Permalink }}'><nobr>Read more →</nobr></a> - </footer> -</article> -{{< /code >}} - -### `li.html` - -Continuing on the previous example, we can change our render function to use a smaller `li.html` view by changing the argument in the call to the `.Render` function (i.e., `{{ .Render "li" }}`). - -{{< code file="layouts/_default/li.html" download="li.html" >}} -<li> - <a href="{{ .Permalink }}">{{ .Title }}</a> - <div class="meta">{{ .Date.Format "Mon, Jan 2, 2006" }}</div> -</li> -{{< /code >}} - -[lists]: /templates/lists/ -[lookup]: /templates/lookup-order/ -[pagevars]: /variables/page/ -[render]: /functions/render/ -[single]: /templates/single-page-templates/ -[spf]: http://spf13.com -[spfsourceli]: https://github.com/spf13/spf13.com/blob/master/layouts/_default/li.html -[spfsourcesection]: https://github.com/spf13/spf13.com/blob/master/layouts/_default/section.html -[spfsourcesummary]: https://github.com/spf13/spf13.com/blob/master/layouts/_default/summary.html -[summaries]: /content-management/summaries/ -[taxonomylists]: /templates/taxonomy-templates/ |