diff options
Diffstat (limited to 'docs/content/en/templates/data-templates.md')
-rw-r--r-- | docs/content/en/templates/data-templates.md | 28 |
1 files changed, 19 insertions, 9 deletions
diff --git a/docs/content/en/templates/data-templates.md b/docs/content/en/templates/data-templates.md index 1be4e93eb..1586d3a54 100644 --- a/docs/content/en/templates/data-templates.md +++ b/docs/content/en/templates/data-templates.md @@ -18,23 +18,31 @@ toc: true <!-- begin data files --> -Hugo supports loading data from YAML, JSON, XML, and TOML files located in the `data` directory in the root of your Hugo project. +Hugo supports loading data from YAML, JSON, XML, and TOML files located in the `data` directory at 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. +The `data` folder should store additional data for Hugo to use when generating your site. + +Data files are not for generating standalone pages. They should supplement content files by: + +- extending the content when the front matter fields grow out of control, or +- showing a larger dataset in a template (see the example below). + +In both cases, it's a good idea to outsource the data in their (own) files. These files must be YAML, JSON, XML, or TOML files (using the `.yml`, `.yaml`, `.json`, `.xml`, or `.toml` extension). The data will be accessible as a `map` in the `.Site.Data` variable. -If you wish to access the data using the `.Site.Data.filename` notation, the filename must begin with an underscore or a Unicode letter, followed by zero or more underscores, Unicode letters, or Unicode digits. eg: +To access the data using the `site.Data.filename` notation, the filename must begin with an underscore or a Unicode letter, followed by zero or more underscores, Unicode letters, or Unicode digits. For example: - `123.json` - Invalid - `x123.json` - Valid - `_123.json` - Valid -If you wish to access the data using the [`index`](/functions/index-function/) function, the filename is irrelevant. For example: +To access the data using the [`index`](/functions/index-function/) function, the filename is irrelevant. For example: + Data file|Template code :--|:-- `123.json`|`{{ index .Site.Data "123" }}` @@ -44,11 +52,13 @@ Data file|Template code ## Data Files in Themes -Data Files can also be used in [Hugo themes][themes] but note that theme data files are merged with the project directory taking precedence (i.e., given two files with the same name and relative path, the data in the file in the root project `data` directory will override the data from the file in the `themes/<THEME>/data` directory *for keys that are duplicated*). +Data Files can also be used in [Hugo themes][themes]. + +However, note that the theme data files are merged with the project directory taking precedence. That is, Given two files with the same name and relative path, the data in the file in the root project `data` directory will override the data from the file in the `themes/<THEME>/data` directory *for keys that are duplicated*). -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. +Therefore, theme authors should be careful not to 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). +The keys in the map created with data templates from data files will be a dot-chained set of `path`, `filename`, and `key` in the file (if applicable). This is best explained with an example: @@ -213,7 +223,7 @@ If you don't like caching at all, you can fully disable caching with the command ### 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. +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 @@ -227,7 +237,7 @@ The local CSV files to be loaded using `getCSV` must be located **outside** the ## 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. +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 data takes a while, Hugo stops processing your Markdown files until the data download has been 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. |