shithub: hugo

Info  •  Files  •  Log  •  Branches

Doc Data Files: Add section about themes and expanded the example a bit

--- a/docs/content/extras/datafiles.md

+++ b/docs/content/extras/datafiles.md

@@ -17,6 +17,8 @@

 **It even works with [LiveReload](/extras/livereload/).**

+Data Files can also be used in [themes](/themes/overview/), but note: If the same `key` is used in both the main data folder and in the theme's data folder, the main one will win. So, for theme authors,  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/mytheme/somekey/...`. To check if any such duplicate exists, run hugo with the `-v` flag, e.g. `hugo -v`.

+

 ## The Data Folder

 As explained in [Source Organization](/overview/source-directory/), the `data` folder is where you can store additional data for Hugo to use when generating your site. These files must be YAML, JSON or TOML files (using either the `.yml`, `.yaml`, `.json` or `toml` extension) and the data will be accessible as a `map` in `.Site.Data`.

@@ -27,12 +29,17 @@

 ## 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.

+[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 uses TOML as file format.

+The example below is a bit constructed, but it illustrates the flexibility of Data Files. It uses TOML as file format.

-Given the file `data/jazz/bass/jacopastorius.toml` with the content below:

+Given the 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",

@@ -53,16 +60,24 @@

 ]

 ```

-This list can be accessed via `.Site.Data.jazz.bass.jacopastorius.discography`.

+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 in a template:

+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 `partial/artist.html`:

+

+```

 <ul>

-{{ range $.Site.Data.jazz.bass.jacopastorius.discography }}

+{{ range .discography }}

   <li>{{ . }}</li>

 {{ end }}

 </ul>

 ```

-

+Discover a new favourite bass player? Just add another TOML-file.