From 39121de4d991bdcf5f202da4d8d81a8ac6c149fc Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bj=C3=B8rn=20Erik=20Pedersen?= Date: Mon, 21 Oct 2019 10:21:37 +0200 Subject: docs: Replace /docs --- docs/content/en/templates/404.md | 64 -- docs/content/en/templates/_index.md | 19 - docs/content/en/templates/alternatives.md | 77 --- docs/content/en/templates/base.md | 132 ---- docs/content/en/templates/data-templates.md | 259 -------- docs/content/en/templates/files.md | 115 ---- docs/content/en/templates/homepage.md | 76 --- docs/content/en/templates/internal.md | 212 ------- docs/content/en/templates/introduction.md | 664 --------------------- docs/content/en/templates/lists.md | 558 ----------------- docs/content/en/templates/lookup-order.md | 85 --- docs/content/en/templates/menu-templates.md | 162 ----- docs/content/en/templates/ordering-and-grouping.md | 344 ----------- docs/content/en/templates/output-formats.md | 253 -------- docs/content/en/templates/pagination.md | 155 ----- docs/content/en/templates/partials.md | 209 ------- docs/content/en/templates/robots.md | 54 -- docs/content/en/templates/rss.md | 120 ---- docs/content/en/templates/section-templates.md | 122 ---- docs/content/en/templates/shortcode-templates.md | 418 ------------- docs/content/en/templates/single-page-templates.md | 92 --- docs/content/en/templates/sitemap-template.md | 106 ---- docs/content/en/templates/taxonomy-templates.md | 375 ------------ docs/content/en/templates/template-debugging.md | 81 --- docs/content/en/templates/views.md | 121 ---- 25 files changed, 4873 deletions(-) delete mode 100644 docs/content/en/templates/404.md delete mode 100644 docs/content/en/templates/_index.md delete mode 100644 docs/content/en/templates/alternatives.md delete mode 100644 docs/content/en/templates/base.md delete mode 100644 docs/content/en/templates/data-templates.md delete mode 100644 docs/content/en/templates/files.md delete mode 100644 docs/content/en/templates/homepage.md delete mode 100644 docs/content/en/templates/internal.md delete mode 100644 docs/content/en/templates/introduction.md delete mode 100644 docs/content/en/templates/lists.md delete mode 100644 docs/content/en/templates/lookup-order.md delete mode 100644 docs/content/en/templates/menu-templates.md delete mode 100644 docs/content/en/templates/ordering-and-grouping.md delete mode 100644 docs/content/en/templates/output-formats.md delete mode 100644 docs/content/en/templates/pagination.md delete mode 100644 docs/content/en/templates/partials.md delete mode 100644 docs/content/en/templates/robots.md delete mode 100644 docs/content/en/templates/rss.md delete mode 100644 docs/content/en/templates/section-templates.md delete mode 100644 docs/content/en/templates/shortcode-templates.md delete mode 100644 docs/content/en/templates/single-page-templates.md delete mode 100644 docs/content/en/templates/sitemap-template.md delete mode 100644 docs/content/en/templates/taxonomy-templates.md delete mode 100644 docs/content/en/templates/template-debugging.md delete mode 100644 docs/content/en/templates/views.md (limited to 'docs/content/en/templates') 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"}} -
-
-

Go Home

-
-
-{{ 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/-baseof.html` -2. `/themes//layouts/section/-baseof.html` -3. `/layouts//baseof.html` -4. `/themes//layouts//baseof.html` -5. `/layouts/section/baseof.html` -6. `/themes//layouts/section/baseof.html` -7. `/layouts/_default/-baseof.html` -8. `/themes//layouts/_default/-baseof.html` -9. `/layouts/_default/baseof.html` -10. `/themes//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" >}} - - - - - {{ block "title" . }} - <!-- Blocks may include default content. --> - {{ .Site.Title }} - {{ end }} - - - - {{ block "main" . }} - - {{ end }} - {{ block "footer" . }} - - {{ end }} - - -{{< /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" }} -

Posts

- {{ range .Pages }} -
-

{{ .Title }}

- {{ .Content }} -
- {{ 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: - -``` - -{{ 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" }} - - {{ .Title }} – {{ .Site.Title }} -{{ end }} -{{ define "main" }} -

{{ .Title }}

- {{ .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 ---- - - - -Hugo supports loading data from YAML, JSON, and TOML files located in the `data` directory in the root of your Hugo project. - -{{< youtube FyPgSuwIMWQ >}} - -## The Data Folder - -The `data` folder is where you can store additional data for Hugo to use when generating your site. Data files aren't used to generate standalone pages; rather, they're meant to be supplemental to content files. This feature can extend the content in case your front matter fields grow out of control. Or perhaps you want to show a larger dataset in a template (see example below). In both cases, it's a good idea to outsource the data in their own files. - -These files must be YAML, JSON, or TOML files (using the `.yml`, `.yaml`, `.json`, or `.toml` extension). The data will be accessible as a `map` in the `.Site.Data` variable. - -## Data Files in Themes - -Data Files can also be used in [Hugo themes][themes] but note that theme data files follow the same logic as other template files in the [Hugo lookup order][lookup] (i.e., given two files with the same name and relative path, the file in the root project `data` directory will override the file in the `themes//data` directory). - -Therefore, theme authors should take care to not include data files that could be easily overwritten by a user who decides to [customize a theme][customize]. For theme-specific data items that shouldn't be overridden, it can be wise to prefix the folder structure with a namespace; e.g. `mytheme/data//somekey/...`. To check if any such duplicate exists, run hugo with the `-v` flag. - -The keys in the map created with data templates from data files will be a dot-chained set of `path`, `filename`, and `key` in file (if applicable). - -This is best explained with an example: - -## Example: Jaco Pastorius' Solo Discography - -[Jaco Pastorius](http://en.wikipedia.org/wiki/Jaco_Pastorius_discography) was a great bass player, but his solo discography is short enough to use as an example. [John Patitucci](http://en.wikipedia.org/wiki/John_Patitucci) is another bass giant. - -The example below is a bit contrived, but it illustrates the flexibility of data Files. This example uses TOML as its file format with the two following data files: - -* `data/jazz/bass/jacopastorius.toml` -* `data/jazz/bass/johnpatitucci.toml` - -`jacopastorius.toml` contains the content below. `johnpatitucci.toml` contains a similar list: - -``` -discography = [ -"1974 – Modern American Music … Period! The Criteria Sessions", -"1974 – Jaco", -"1976 - Jaco Pastorius", -"1981 - Word of Mouth", -"1981 - The Birthday Concert (released in 1995)", -"1982 - Twins I & II (released in 1999)", -"1983 - Invitation", -"1986 - Broadway Blues (released in 1998)", -"1986 - Honestly Solo Live (released in 1990)", -"1986 - Live In Italy (released in 1991)", -"1986 - Heavy'n Jazz (released in 1992)", -"1991 - Live In New York City, Volumes 1-7.", -"1999 - Rare Collection (compilation)", -"2003 - Punk Jazz: The Jaco Pastorius Anthology (compilation)", -"2007 - The Essential Jaco Pastorius (compilation)" -] -``` - -The list of bass players can be accessed via `.Site.Data.jazz.bass`, a single bass player by adding the filename without the suffix, e.g. `.Site.Data.jazz.bass.jacopastorius`. - -You can now render the list of recordings for all the bass players in a template: - -``` -{{ range $.Site.Data.jazz.bass }} - {{ partial "artist.html" . }} -{{ end }} -``` - -And then in the `partials/artist.html`: - -``` -
    -{{ range .discography }} -
  • {{ . }}
    • -{{ end }} -
-``` - -Discover a new favorite bass player? Just add another `.toml` file in the same directory. - -## Example: Accessing Named Values in a Data File - -Assume you have the following data structure in your `User0123.[yml|toml|json]` data file located directly in `data/`: - -{{< code-toggle file="User0123" >}} -Name: User0123 -"Short Description": "He is a **jolly good** fellow." -Achievements: - - "Can create a Key, Value list from Data File" - - "Learns Hugo" - - "Reads documentation" -{{}} - -You can use the following code to render the `Short Description` in your layout:: - -``` -
Short Description of {{.Site.Data.User0123.Name}}:

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

-``` - -Note the use of the [`markdownify` template function][markdownify]. This will send the description through the Blackfriday Markdown rendering engine. - - - -## Data-Driven Content - -In addition to the [data files](/extras/datafiles/) feature, Hugo also has a "data-driven content" feature, which lets you load any [JSON](http://www.json.org/) or [CSV](http://en.wikipedia.org/wiki/Comma-separated_values) file from nearly any resource. - -Data-driven content currently consists of two functions, `getJSON` and `getCSV`, which are available in all template files. - -## Implementation details - -### Call the Functions with a URL - -In your template, call the functions like this: - -``` -{{ $dataJ := getJSON "url" }} -{{ $dataC := getCSV "separator" "url" }} -``` - -If you use a prefix or postfix for the URL, the functions accept [variadic arguments][variadic]: - -``` -{{ $dataJ := getJSON "url prefix" "arg1" "arg2" "arg n" }} -{{ $dataC := getCSV "separator" "url prefix" "arg1" "arg2" "arg n" }} -``` - -The separator for `getCSV` must be put in the first position and can only be one character long. - -All passed arguments will be joined to the final URL: - -``` -{{ $urlPre := "https://api.github.com" }} -{{ $gistJ := getJSON $urlPre "/users/GITHUB_USERNAME/gists" }} -``` - -This will resolve internally to the following: - -``` -{{ $gistJ := getJSON "https://api.github.com/users/GITHUB_USERNAME/gists" }} -``` - -Finally, you can range over an array. This example will output the -first 5 gists for a GitHub user: - -``` -
    - {{ $urlPre := "https://api.github.com" }} - {{ $gistJ := getJSON $urlPre "/users/GITHUB_USERNAME/gists" }} - {{ range first 5 $gistJ }} - {{ if .public }} -
  • {{ .description }}
    • - {{ end }} - {{ end }} -
-``` - -### Example for CSV files - -For `getCSV`, the one-character-long separator must be placed in the first position followed by the URL. The following is an example of creating an HTML table in a [partial template][partials] from a published CSV: - -{{< code file="layouts/partials/get-csv.html" >}} - - - - - - - - - - {{ $url := "https://example.com/finance/employee-salaries.csv" }} - {{ $sep := "," }} - {{ range $i, $r := getCSV $sep $url }} - - - - - - {{ end }} - -
NamePositionSalary
{{ index $r 0 }}{{ index $r 1 }}{{ index $r 2 }}
-{{< /code >}} - -The expression `{{index $r number}}` must be used to output the nth-column from the current row. - -### Cache URLs - -Each downloaded URL will be cached in the default folder `$TMPDIR/hugo_cache/`. The variable `$TMPDIR` will be resolved to your system-dependent temporary directory. - -With the command-line flag `--cacheDir`, you can specify any folder on your system as a caching directory. - -You can also set `cacheDir` in the [main configuration file][config]. - -If you don't like caching at all, you can fully disable caching with the command line flag `--ignoreCache`. - -### Authentication When Using REST URLs - -Currently, you can only use those authentication methods that can be put into an URL. [OAuth][] and other authentication methods are not implemented. - -## Load Local files - -To load local files with `getJSON` and `getCSV`, the source files must reside within Hugo's working directory. The file extension does not matter, but the content does. - -It applies the same output logic as above in [Calling the Functions with a URL](#calling-the-functions-with-a-url). - -{{% note %}} -The local CSV files to be loaded using `getCSV` must be located **outside** of the `data` directory. -{{% /note %}} - -## LiveReload with Data Files - -There is no chance to trigger a [LiveReload][] when the content of a URL changes. However, when a *local* file changes (i.e., `data/*` and `themes//data/*`), a LiveReload will be triggered. Symlinks are not supported. Note too that because downloading of data takes a while, Hugo stops processing your Markdown files until the data download has completed. - -{{% warning "URL Data and LiveReload" %}} -If you change any local file and the LiveReload is triggered, Hugo will read the data-driven (URL) content from the cache. If you have disabled the cache (i.e., by running the server with `hugo server --ignoreCache`), Hugo will re-download the content every time LiveReload triggers. This can create *huge* traffic. You may reach API limits quickly. -{{% /warning %}} - -## Examples of Data-driven Content - -- Photo gallery JSON powered: [https://github.com/pcdummy/hugo-lightslider-example](https://github.com/pcdummy/hugo-lightslider-example) -- GitHub Starred Repositories [in a post](https://github.com/SchumacherFM/blog-cs/blob/master/content%2Fposts%2Fgithub-starred.md) using data-driven content in a [custom short code](https://github.com/SchumacherFM/blog-cs/blob/master/layouts%2Fshortcodes%2FghStarred.html). - -## Specs for Data Formats - -* [TOML Spec][toml] -* [YAML Spec][yaml] -* [JSON Spec][json] -* [CSV Spec][csv] - -[config]: /getting-started/configuration/ -[csv]: https://tools.ietf.org/html/rfc4180 -[customize]: /themes/customizing/ -[json]: https://www.ecma-international.org/publications/files/ECMA-ST/ECMA-404.pdf "Specification for JSON, JavaScript Object Notation" -[LiveReload]: /getting-started/usage/#livereload -[lookup]: /templates/lookup-order/ -[markdownify]: /functions/markdownify/ -[OAuth]: http://en.wikipedia.org/wiki/OAuth -[partials]: /templates/partials/ -[themes]: /themes/ -[toml]: https://github.com/toml-lang/toml -[variadic]: http://en.wikipedia.org/wiki/Variadic_function -[vars]: /variables/ -[yaml]: http://yaml.org/spec/ diff --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: - -``` -{{}} -``` - -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: - -``` -{{}} -``` - -{{% 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: - -``` -{{}} -``` - -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: - -``` -{{}} -``` - -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" }} -
-
-

{{.Title}}

- {{ with .Params.subtitle }} - {{.}} - {{ end }} -
-
- - {{.Content}} -
-
- - {{ range first 10 .Pages }} - {{ .Render "summary"}} - {{ end }} -
-
-{{ 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 ---- - - -{{% 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" -{{}} - -### 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" -{{}} - -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" >}} -
- - -comments powered by Disqus -{{< /code >}} - -The `if` statement skips the initialization of the Disqus comment injection when you are running on `localhost`. - -You can then render your custom Disqus partial template as follows: - -``` -{{ partial "disqus.html" . }} -``` - -## 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 file="content/blog/my-post" >}} -title = "Post title" -description = "Text about this post" -date = "2006-01-02" -images = ["post-cover.png"] -audio = [] -videos = [] -series = [] -tags = [] -{{}} - -Hugo uses the page title and description for the title and description metadata. -The first 6 URLs from the `images` array are used for image metadata. - -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 ``. 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 `` 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 file="content/blog/my-post" >}} -title = "Post title" -description = "Text about this post" -images = ["post-cover.png"] -{{}} - -If `images` aren't specified in the page front-matter, then hugo searches for [image page resources](/content-management/image-processing/) with `feature`, `cover`, or `thumbnail` in their name. -If no image resources with those names are found, the images defined in the [site config](getting-started/configuration/) are used instead. -If no images are found at all, then an image-less Twitter `summary` card is used instead of `summary_large_image`. - -Hugo uses the page title and description for the card's title and description fields. The page summary is used if no description is given. - -### Use the Twitter Cards Template - -To add Twitter card metadata, include the following line between the `` 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 }} -``` - -Values can also be stored in custom variables and referenced later: - -{{% note %}} -The custom variables need to be prefixed with `$`. -{{% /note %}} - -```go-html-template -{{ $address := "123 Main St." }} -{{ $address }} -``` - -{{% warning %}} -For Hugo v0.47 and older versions, variables defined inside `if` -conditionals and similar are not visible on the outside. -See [https://github.com/golang/go/issues/10608](https://github.com/golang/go/issues/10608). - -Hugo has created a workaround for this issue in [Scratch](/functions/scratch). -{{% /warning %}} - -For **Hugo v0.48** and newer, variables can be re-defined using the -new `=` operator (new in Go 1.11). - -Below example will work only in these newer Hugo versions. The example -prints "Var is Hugo Home" on the home page, and "Var is Hugo Page" on -all other pages: - -```go-html-template -{{ $var := "Hugo Page" }} -{{ if .IsHome }} - {{ $var = "Hugo Home" }} -{{ end }} -Var is {{ $var }} -``` - -## Functions - -Go Templates only ship with a few basic functions but also provide a mechanism for applications to extend the original set. - -[Hugo template functions][functions] provide additional functionality specific to building websites. Functions are called by using their name followed by the required parameters separated by spaces. Template functions cannot be added without recompiling Hugo. - -### Example 1: Adding Numbers - -```go-html-template -{{ add 1 2 }} - -``` - -### Example 2: Comparing Numbers - -```go-html-template -{{ lt 1 2 }} - -``` - -Note that both examples make use of Go Template's [math functions][]. - -{{% note "Additional Boolean Operators" %}} -There are more boolean operators than those listed in the Hugo docs in the [Go Template documentation](http://golang.org/pkg/text/template/#hdr-Functions). -{{% /note %}} - -## Includes - -When including another template, you will need to pass it the data that it would -need to access. - -{{% note %}} -To pass along the current context, please remember to include a trailing **dot**. -{{% /note %}} - -The templates location will always be starting at the `layouts/` directory -within Hugo. - -### Partial - -The [`partial`][partials] function is used to include *partial* templates using -the syntax `{{ partial "/." . }}`. - -Example 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/