diff --git a/content/templates/404.md b/content/templates/404.md index 71e46fa4b..c99140c39 100644 --- a/content/templates/404.md +++ b/content/templates/404.md @@ -11,7 +11,6 @@ weight: 120 draft: false aliases: [/templates/404/] toc: false -wip: true --- 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. @@ -29,18 +28,15 @@ In addition to the standard page variables, the 404 page has access to all site This is a basic example of a 404.html template: -{{% code file="404.html"%}} +{{% code file="layouts/404.html" download="404.html" %}} ```html -{{ partial "header.html" . }} -{{ partial "subheader.html" . }} - -
-
-

{{ .Title }}

-
-
- -{{ partial "footer.html" . }} +{{ define "main"}} +
+
+

Go Home

+
+
+{{ end }} ``` {{% /code %}} @@ -48,10 +44,10 @@ This is a basic example of a 404.html template: 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_ - it's automatic. -* _Apache_ - one way is to 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. -* _Caddy Server_ - using `errors { 404 /404.html }`. [Details here](https://caddyserver.com/docs/errors) +* [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. +* Caddy Server. Using `errors { 404 /404.html }`. [Details here](https://caddyserver.com/docs/errors) [pagevars]: /variables/page/ \ No newline at end of file diff --git a/content/templates/data-templates.md b/content/templates/data-templates.md index 2d6846095..e1140f6d9 100644 --- a/content/templates/data-templates.md +++ b/content/templates/data-templates.md @@ -4,14 +4,13 @@ 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-02-01 +lastmod: 2017-03-12 categories: [templates] tags: [data,dynamic,csv,json,toml,yaml] weight: 80 draft: false aliases: [/extras/datafiles/,/extras/datadrivencontent/,/doc/datafiles/] toc: true -wip: true --- @@ -20,20 +19,19 @@ In addition to the [built-in variables][vars] available from Hugo, you can speci Hugo supports loading data from YAML, JSON, and TOML files located in the `data` directory in the root of your Hugo project. - ## 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 supplemental to the content files. This feature can extend the content in case your front matter would grow immensely. Or perhaps your 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 file. +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 either the `.yml`, `.yaml`, `.json` or `toml` extension). The data will be accessible as a `map` in the `.Site.Data` variable. +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., give 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). +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. +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 this map will be a dot chained set of _path_, _filename_ and _key_ in file (if applicable).** +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: @@ -41,14 +39,12 @@ This is best explained with an example: [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 constructed, but it illustrates the flexibility of Data Files. It uses TOML as file format. - -Given the files: +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: +`jacopastorius.toml` contains the content below. `johnpatitucci.toml` contains a similar list: ``` discography = [ @@ -74,13 +70,13 @@ The list of bass players can be accessed via `.Site.Data.jazz.bass`, a single ba You can now render the list of recordings for all the bass players in a template: -``` +```html {{ range $.Site.Data.jazz.bass }} {{ partial "artist.html" . }} {{ end }} ``` -And then in `partial/artist.html`: +And then in the `partial/artist.html`: ```
    @@ -90,11 +86,11 @@ And then in `partial/artist.html`:
``` -Discover a new favourite bass player? Just add another TOML-file. +Discover a new favorite bass player? Just add another `.toml` file in the same directory. -## Example: Accessing named values in a Data File +## Example: Accessing Named Values in a Data File -Assuming you have the following YAML structure to your `User0123.yml` Data File located directly in `data/` +Assume you have the following YAML structure in your `User0123.yml` data file located directly in `data/`: ``` Name: User0123 @@ -105,75 +101,73 @@ Achievements: - "Reads documentation" ``` -To render the `Short Description` in your `layout` File following code is required. +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. This will send the description through the Blackfriday Markdown rendering engine. +Note the use of the [`markdownify` template function][markdownify]. This will send the description through the Blackfriday Markdown rendering engine. ## Data-Driven Content -Data-driven content with a static site generator? Yes, it is possible! +In addition to the [data files](/extras/datafiles/) feature, Hugo also 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. -In addition to the [data files](/extras/datafiles/) feature, we have also -implemented the feature "Data-driven Content", 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**. +Data-driven content currently consists of two functions, `getJSON` and `getCSV`, which are available in all template files. ## Implementation details ### Calling the Functions with a URL -In any HTML template or Markdown document, call the functions like this: +In your template, call the functions like this: ```golang {{ $dataJ := getJSON "url" }} {{ $dataC := getCSV "separator" "url" }} ``` -If you use a prefix or postfix for the URL, the functions -accept [variadic arguments][variadic]: +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" }} +``` +{{ $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. +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; for example: +All passed arguments will be joined to the final URL: - {{ $urlPre := "https://api.github.com" }} - {{ $gistJ := getJSON $urlPre "/users/GITHUB_USERNAME/gists" }} +```html +{{ $urlPre := "https://api.github.com" }} +{{ $gistJ := getJSON $urlPre "/users/GITHUB_USERNAME/gists" }} +``` -will resolve internally to: +This will resolve internally to the following: - {{ $gistJ := getJSON "https://api.github.com/users/GITHUB_USERNAME/gists" }} +```html +{{ $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 }} -
+```html +
    + {{ $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: +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" %}} ```html @@ -200,8 +194,7 @@ first position followed by the URL. The following is an example of creating an H ``` {{% /code %}} -The expression `{{index $r number}}` must be used to output the nth-column from -the current row. +The expression `{{index $r number}}` must be used to output the nth-column from the current row. ### Caching of URLs @@ -209,7 +202,7 @@ Each downloaded URL will be cached in the default folder `$TMPDIR/hugo_cache/`. 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. +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`. @@ -231,11 +224,10 @@ There is no chance to trigger a [LiveReload][] when the content of a URL changes 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 +## 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 posts](https://github.com/SchumacherFM/blog-cs/blob/master/content%2Fposts%2Fgithub-starred.md) with the related [short code](https://github.com/SchumacherFM/blog-cs/blob/master/layouts%2Fshortcodes%2FghStarred.html). -- More? Please tell us! +- 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 @@ -244,15 +236,17 @@ If you change any local file and the LiveReload is triggered, Hugo will read the * [JSON Spec][json] * [CSV Spec][csv] +[config]: /getting-started/configuration/ [csv]: https://tools.ietf.org/html/rfc4180 [customize]: /themes/customizing/ -[lookup]: /templates/lookup-order/ [json]: /documents/ecma-404-json-spec.pdf [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 -[yaml]: http://yaml.org/spec/ [variadic]: http://en.wikipedia.org/wiki/Variadic_function -[vars]: /variables/ \ No newline at end of file +[vars]: /variables/ +[yaml]: http://yaml.org/spec/ \ No newline at end of file diff --git a/content/templates/files.md b/content/templates/files.md index 02c66de1d..08461fb0b 100644 --- a/content/templates/files.md +++ b/content/templates/files.md @@ -79,7 +79,7 @@ Here is the templating for our new `readfile` shortcode: ``` {{% /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: +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: ``` {{}} diff --git a/content/templates/menu-templates.md b/content/templates/menu-templates.md index a433c13d8..c2e058b4d 100644 --- a/content/templates/menu-templates.md +++ b/content/templates/menu-templates.md @@ -10,8 +10,7 @@ tags: [lists,sections,menus] weight: 130 draft: false aliases: [/templates/menus/] -toc: true -wip: true +toc: false --- Hugo makes no assumptions about how your rendered HTML will be @@ -20,8 +19,9 @@ able to build your menu however you want. The following is an example: +{{% code file="layouts/partials/sidebar.html" download="sidebar.html" %}} ```html - + ``` +{{% /code %}} {{% note "`absLangURL` and `relLangURL`" %}} -Use the `absLangURL` or `relLangURL` 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. Read more on the [`absLangUrl`](/functions/abslangurl) and [`relLangUrl`](/functions/rellangurl) functions. +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 @@ -96,4 +97,6 @@ The above is all that's needed. But if you want custom menu items, e.g. changing url = "/blog/" ``` -**Note** that the `identifier` must match the section name. \ No newline at end of file +{{% note %}} +The `identifier` *must* match the section name. +{{% /note %}} \ No newline at end of file diff --git a/content/templates/pagination.md b/content/templates/pagination.md index 22c02128c..742b5750a 100644 --- a/content/templates/pagination.md +++ b/content/templates/pagination.md @@ -11,10 +11,9 @@ weight: 140 draft: false aliases: [/extras/pagination,/doc/pagination/] toc: true -wip: true --- -Hugo supports pagination for your homepage, section pages, and taxonomies. Hugo's pagination features were designed with ease of use and flexibility in mind. The real power of Hugo pagination shines when combine 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. +Hugo supports pagination for your homepage, section pages, and taxonomies. Hugo's pagination features were designed with ease of use and flexibility in mind. 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. ## Configuring Pagination @@ -60,7 +59,7 @@ 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): -``` +```html {{ template "_internal/pagination.html" . }} ``` @@ -70,7 +69,7 @@ If you use any filters or ordering functions to create your `.Paginator` *and* y The following example shows how to create `.Paginator` before its used: -```golang +```html {{ $paginator := .Paginate (where .Data.Pages "Type" "post") }} {{ template "_internal/pagination.html" . }} {{ range $paginator.Pages }} @@ -80,7 +79,7 @@ The following example shows how to create `.Paginator` before its used: Without the `where` filter, the above example is even simpler: -```golang +```html {{ template "_internal/pagination.html" . }} {{ range .Paginator.Pages }} {{ .Title }} diff --git a/content/templates/partials.md b/content/templates/partials.md index d4e3d8f88..1d96a9c91 100644 --- a/content/templates/partials.md +++ b/content/templates/partials.md @@ -11,7 +11,6 @@ weight: 90 draft: false aliases: [/templates/partial/,/layout/chrome/,/extras/analytics/] toc: true -wip: true --- In practice, splitting out reusable template portions into **partial templates** to be included anywhere help keep your templating DRY. @@ -53,7 +52,7 @@ All partials are called within your templates using the following pattern: ``` {{% 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 [templating introduction](/templates/introduction/). +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 %}} 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: diff --git a/content/templates/robots.md b/content/templates/robots.md index 7f63e4c73..b32e4aec2 100644 --- a/content/templates/robots.md +++ b/content/templates/robots.md @@ -11,7 +11,6 @@ weight: 165 draft: false aliases: [/extras/robots-txt/] toc: false -wip: true --- Hugo can generate a customized [robots.txt][robots] in the same way as any other template. diff --git a/content/templates/rss.md b/content/templates/rss.md index 1d2c419ec..10e5f0121 100644 --- a/content/templates/rss.md +++ b/content/templates/rss.md @@ -11,7 +11,6 @@ weight: 150 draft: false aliases: [/templates/rss/] toc: true -wip: true --- ## RSS Template Lookup Order @@ -40,28 +39,28 @@ Hugo provides the ability for you to define any RSS type you wish and can have d ### Main RSS 1. `/layouts/rss.xml` -2. `/layouts/\_default/rss.xml` +2. `/layouts/_default/rss.xml` 3. Embedded rss.xml ### Section RSS 1. `/layouts/section/
.rss.xml` -2. `/layouts/\_default/rss.xml` +2. `/layouts/_default/rss.xml` 3. `/themes//layouts/section/
.rss.xml` -4. `/themes//layouts/\_default/rss.xml` +4. `/themes//layouts/_default/rss.xml` 5. Embedded rss.xml ### Taxonomy RSS 1. `/layouts/taxonomy/.rss.xml` -2. `/layouts/\_default/rss.xml` +2. `/layouts/_default/rss.xml` 3. `/themes//layouts/taxonomy/.rss.xml` -4. `/themes//layouts/\_default/rss.xml` +4. `/themes//layouts/_default/rss.xml` 5. Embedded rss.xml ## Configuring RSS -By default, Hugo will create an unlimited number of RSS entries. You can limit this number via the `rssLimit:` field in your [`config` file](/getting-started/configuration). +By default, Hugo will create an unlimited number of RSS entries. You can limit this number via the `rssLimit:` field in your [`config` file](/getting-started/configuration/). The following values will also be included in the RSS output if specified in your site’s configuration: @@ -105,7 +104,7 @@ This is the default RSS template that ships with Hugo. It adheres to the [RSS 2. ``` {{% warning "XML Header" %}} -Hugo will automatically add the following header line to this file on render…please don't include this in the template as it's not valid HTML. +Hugo will automatically add the following header line to this file on render. Please do *not* include this in the template as it's not valid HTML. ```xml ``` @@ -122,13 +121,11 @@ In your `header.html` template, you can specify your RSS feed in your `{{ .SomeText }} diff --git a/content/templates/sitemap-template.md b/content/templates/sitemap-template.md index 56e2c2adc..dc69d2b9c 100644 --- a/content/templates/sitemap-template.md +++ b/content/templates/sitemap-template.md @@ -11,12 +11,11 @@ weight: 160 draft: false aliases: [/layout/sitemap/,/templates/sitemap/] toc: false -wip: true --- 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`.** +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: @@ -29,7 +28,7 @@ A sitemap is a `Page` and therefore has all the [page variables][pagevars] avail `.Sitemap.Filename` : The sitemap filename -If provided, Hugo will use `/layouts/sitemap.xml` instead of the internal `sitemap.xml` template that ships with Hugo.. +If provided, Hugo will use `/layouts/sitemap.xml` instead of the internal `sitemap.xml` template that ships with Hugo. ## Hugo’s sitemap.xml diff --git a/content/templates/taxonomy-templates.md b/content/templates/taxonomy-templates.md index 5218a4f77..34876848a 100644 --- a/content/templates/taxonomy-templates.md +++ b/content/templates/taxonomy-templates.md @@ -279,7 +279,7 @@ The following example displays all terms in a site's tags taxonomy: 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" %}} +{{% code file="layouts/partials/all-taxonomies.html" download="all-taxonomies.html" download="all-taxonomies.html" %}} ```html