--- /dev/null
- [json]: /documents/ecma-404-json-spec.pdf "Specification for JSON, JavaScript Object Notation"
+---
+title: Front Matter
+linktitle:
+description: Hugo allows you to add front matter in yaml, toml, or json to your content files.
+date: 2017-01-09
+publishdate: 2017-01-09
+lastmod: 2017-02-24
+categories: [content management]
+#tags: ["front matter", "yaml", "toml", "json", "metadata", "archetypes"]
+menu:
+ docs:
+ parent: "content-management"
+ weight: 30
+weight: 30 #rem
+draft: false
+aliases: [/content/front-matter/]
+toc: true
+---
+
+**Front matter** allows you to keep metadata attached to an instance of a [content type][]---i.e., embedded inside a content file---and is one of the many features that gives Hugo its strength.
+
+## Front Matter Formats
+
+Hugo supports three formats for front matter, each with their own identifying tokens.
+
+TOML
+: identified by opening and closing `+++`.
+
+YAML
+: identified by opening and closing `---`.
+
+JSON
+: a single JSON object surrounded by '`{`' and '`}`', followed by a new line.
+
+### TOML Example
+
+```
++++
+title = "spf13-vim 3.0 release and new website"
+description = "spf13-vim is a cross platform distribution of vim plugins and resources for Vim."
+tags = [ ".vimrc", "plugins", "spf13-vim", "vim" ]
+date = "2012-04-06"
+categories = [
+ "Development",
+ "VIM"
+]
+slug = "spf13-vim-3-0-release-and-new-website"
++++
+```
+
+### YAML Example
+
+```
+---
+title: "spf13-vim 3.0 release and new website"
+description: "spf13-vim is a cross platform distribution of vim plugins and resources for Vim."
+tags: [ ".vimrc", "plugins", "spf13-vim", "vim" ]
+lastmod: 2015-12-23
+date: "2012-04-06"
+categories:
+ - "Development"
+ - "VIM"
+slug: "spf13-vim-3-0-release-and-new-website"
+---
+```
+
+### JSON Example
+
+```
+{
+ "title": "spf13-vim 3.0 release and new website",
+ "description": "spf13-vim is a cross platform distribution of vim plugins and resources for Vim.",
+ "tags": [ ".vimrc", "plugins", "spf13-vim", "vim" ],
+ "date": "2012-04-06",
+ "categories": [
+ "Development",
+ "VIM"
+ ],
+ "slug": "spf13-vim-3-0-release-and-new-website"
+}
+```
+
+## Front Matter Variables
+
+### Predefined
+
+There are a few predefined variables that Hugo is aware of. See [Page Variables][pagevars] for how to call many of these predefined variables in your templates.
+
+`aliases`
+: an array of one or more aliases (e.g., old published paths of renamed content) that will be created in the output directory structure . See [Aliases][aliases] for details.
+
+`date`
+: the datetime at which the content was created; note this value is auto-populated according to Hugo's built-in [archetype][].
+
+`description`
+: the description for the content.
+
+`draft`
+: if `true`, the content will not be rendered unless the `--buildDrafts` flag is passed to the `hugo` command.
+
+`expiryDate`
+: the datetime at which the content should no longer be published by Hugo; expired content will not be rendered unless the `--buildExpired` flag is passed to the `hugo` command.
+
+`isCJKLanguage`
+: if `true`, Hugo will explicitly treat the content as a CJK language; both `.Summary` and `.WordCount` work properly in CJK languages.
+
+`keywords`
+: the meta keywords for the content.
+
+`layout`
+: the layout Hugo should select from the [lookup order][lookup] when rendering the content. If a `type` is not specified in the front matter, Hugo will look for the layout of the same name in the layout directory that corresponds with a content's section. See ["Defining a Content Type"][definetype]
+
+`lastmod`
+: the datetime at which the content was last modified.
+
+`linkTitle`
+: used for creating links to content; if set, Hugo defaults to using the `linktitle` before the `title`. Hugo can also [order lists of content by `linktitle`][bylinktitle].
+
+`markup`
+: **experimental**; specify `"rst"` for reStructuredText (requires`rst2html`) or `"md"` (default) for Markdown.
+
+`outputs`
+: allows you to specify output formats specific to the content. See [output formats][outputs].
+
+`publishDate`
+: if in the future, content will not be rendered unless the `--buildFuture` flag is passed to `hugo`.
+
+`slug`
+: appears as the tail of the output URL. A value specified in front matter will override the segment of the URL based on the filename.
+
+`taxonomies`
+: these will use the field name of the plural form of the index; see the `tags` and `categories` in the above front matter examples.
+
+`title`
+: the title for the content.
+
+`type`
+: the type of the content; this value will be automatically derived from the directory (i.e., the [section][]) if not specified in front matter.
+
+`url`
+: the full path to the content from the web root. It makes no assumptions about the path of the content file. It also ignores any language prefixes of
+the multilingual feature.
+
+`weight`
+: used for [ordering your content in lists][ordering].
+
+{{% note "Hugo's Default URL Destinations" %}}
+If neither `slug` nor `url` is present and [permalinks are not configured otherwise in your site `config` file](/content-management/urls/#permalinks), Hugo will use the filename of your content to create the output URL. See [Content Organization](/content-management/organization) for an explanation of paths in Hugo and [URL Management](/content-management/urls/) for ways to customize Hugo's default behaviors.
+{{% /note %}}
+
+### User-Defined
+
+You can add fields to your front matter arbitrarily to meet your needs. These user-defined key-values are placed into a single `.Params` variable for use in your templates.
+
+The following fields can be accessed via `.Params.include_toc` and `.Params.show_comments`, respectively. The [Variables][] section provides more information on using Hugo's page- and site-level variables in your templates.
+
+```
+include_toc: true
+show_comments: false
+```
+
+These two user-defined fields can then be accessed via `.Params.include_toc` and `.Params.show_comments`, respectively. The [Variables][variables] section provides more information on using Hugo's page- and site-level variables in your templates.
+
+
+## Order Content Through Front Matter
+
+You can assign content-specific `weight` in the front matter of your content. These values are especially useful for [ordering][ordering] in list views. You can use `weight` for ordering of content and the convention of [`<TAXONOMY>_weight`][taxweight] for ordering content within a taxonomy. See [Ordering and Grouping Hugo Lists][lists] to see how `weight` can be used to organize your content in list views.
+
+## Override Global Markdown Configuration
+
+It's possible to set some options for Markdown rendering in a content's front matter as an override to the [BlackFriday rendering options set in your project configuration][config].
+
+## Front Matter Format Specs
+
+* [TOML Spec][toml]
+* [YAML Spec][yaml]
+* [JSON Spec][json]
+
+[variables]: /variables/
+[aliases]: /content-management/urls/#aliases/
+[archetype]: /content-management/archetypes/
+[bylinktitle]: /templates/lists/#by-link-title
+[config]: /getting-started/configuration/ "Hugo documentation for site configuration"
+[content type]: /content-management/types/
+[contentorg]: /content-management/organization/
+[definetype]: /content-management/types/#defining-a-content-type "Learn how to specify a type and a layout in a content's front matter"
++[json]: https://www.ecma-international.org/publications/files/ECMA-ST/ECMA-404.pdf "Specification for JSON, JavaScript Object Notation"
+[lists]: /templates/lists/#ordering-content "See how to order content in list pages; for example, templates that look to specific _index.md for content and front matter."
+[lookup]: /templates/lookup-order/ "Hugo traverses your templates in a specific order when rendering content to allow for DRYer templating."
+[ordering]: /templates/lists/ "Hugo provides multiple ways to sort and order your content in list templates"
+[outputs]: /templates/output-formats/ "With the release of v22, you can output your content to any text format using Hugo's familiar templating"
+[pagevars]: /variables/page/
+[section]: /content-management/sections/
+[taxweight]: /content-management/taxonomies/
+[toml]: https://github.com/toml-lang/toml "Specification for TOML, Tom's Obvious Minimal Language"
+[urls]: /content-management/urls/
+[variables]: /variables/
+[yaml]: http://yaml.org/spec/ "Specification for YAML, YAML Ain't Markup Language"
--- /dev/null
- [json]: /documents/ecma-404-json-spec.pdf
+---
+title: Configure Hugo
+linktitle: Configuration
+description: Often the default settings are good enough, but the config file can provide highly granular control over how your site is rendered.
+date: 2013-07-01
+publishdate: 2017-01-02
+lastmod: 2017-03-05
+categories: [getting started,fundamentals]
+#tags: [configuration,toml,yaml,json]
+menu:
+ docs:
+ parent: "getting-started"
+ weight: 60
+weight: 60
+sections_weight: 60
+draft: false
+aliases: [/overview/source-directory/,/overview/configuration/]
+toc: true
+---
+
+The [directory structure][] of a Hugo website—or more precisely, the source organization of files containing the website's content and templates—provides most of the configuration information that Hugo needs in order to generate a finished website.
+
+Because of Hugo's sensible defaults, many websites may not need a configuration file. Hugo is designed to recognize certain typical usage patterns.
+
+## Configuration Lookup Order
+
+Similar to the template [lookup order][], Hugo has a default set of rules for searching for a configuration file in the root of your website's source directory as a default behavior:
+
+1. `./config.toml`
+2. `./config.yaml`
+3. `./config.json`
+
+In your `config` file, you can direct Hugo as to how you want your website rendered, control your website's menus, and arbitrarily define site-wide parameters specific to your project.
+
+## YAML Configuration
+
+The following is a typical example of a YAML configuration file. Note the document opens with 3 hyphens and closes with 3 periods. The values nested under `params:` will populate the [`.Site.Params`][] variable for use in [templates][]:
+
+{{< code file="config.yml">}}
+---
+baseURL: "https://yoursite.example.com/"
+title: "My Hugo Site"
+footnoteReturnLinkContents: "↩"
+permalinks:
+ post: /:year/:month/:title/
+params:
+ Subtitle: "Hugo is Absurdly Fast!"
+ AuthorName: "Jon Doe"
+ GitHubUser: "spf13"
+ ListOfFoo:
+ - "foo1"
+ - "foo2"
+ SidebarRecentLimit: 5
+...
+{{< /code >}}
+
+### All Variables, YAML
+
+The following is the full list of Hugo-defined variables in an example YAML file. The values provided in this example represent the default values used by Hugo.
+
+{{< code file="config.yml" download="config.yml" >}}
+---
+archetypeDir: "archetypes"
+# hostname (and path) to the root, e.g. http://spf13.com/
+baseURL: ""
+# include content marked as draft
+buildDrafts: false
+# include content with publishdate in the future
+buildFuture: false
+# include content already expired
+buildExpired: false
+# enable this to make all relative URLs relative to content root. Note that this does not affect absolute URLs. See the "URL Management" page
+relativeURLs: false
+canonifyURLs: false
+# config file (default is path/config.yaml|json|toml)
+config: "config.toml"
+contentDir: "content"
+dataDir: "data"
+defaultExtension: "html"
+defaultLayout: "post"
+# Missing translations will default to this content language
+defaultContentLanguage: "en"
+# Renders the default content language in subdir, e.g. /en/. The root directory / will redirect to /en/
+defaultContentLanguageInSubdir: false
+disableLiveReload: false
+# Do not build RSS files
+disableRSS: false
+# Do not build Sitemap file
+disableSitemap: false
+# Enable GitInfo feature
+enableGitInfo: false
+# Build robots.txt file
+enableRobotsTXT: false
+# Do not render 404 page
+disable404: false
+# Do not inject generator meta tag on homepage
+disableHugoGeneratorInject: false
+# Allows you to disable all page types and will render nothing related to 'kind';
+# values = "page", "home", "section", "taxonomy", "taxonomyTerm", "RSS", "sitemap", "robotsTXT", "404"
+disableKinds: []
+# Do not make the url/path to lowercase
+disablePathToLower: false ""
+# Enable Emoji emoticons support for page content; see emoji-cheat-sheet.com
+enableEmoji: false
+# Show a placeholder instead of the default value or an empty string if a translation is missing
+enableMissingTranslationPlaceholders: false
+footnoteAnchorPrefix: ""
+footnoteReturnLinkContents: ""
+# google analytics tracking id
+googleAnalytics: ""
+# if true, auto-detect Chinese/Japanese/Korean Languages in the content. (.Summary and .WordCount can work properly in CJKLanguage)
+hasCJKLanguage: false
+languageCode: ""
+layoutDir: "layouts"
+# Enable Logging
+log: false
+# Log File path (if set, logging enabled automatically)
+logFile: ""
+# "toml","yaml", or "json"
+metaDataFormat: "toml"
+newContentEditor: ""
+# Don't sync permission mode of files
+noChmod: false
+# Don't sync modification time of files
+noTimes: false
+# Pagination
+paginate: 10
+paginatePath: "page"
+# See "content-management/permalinks"
+permalinks:
+# Pluralize titles in lists using inflect
+pluralizeListTitles: true
+# Preserve special characters in taxonomy names ("Gérard Depardieu" vs "Gerard Depardieu")
+preserveTaxonomyNames: false
+# filesystem path to write files to
+publishDir: "public"
+# enables syntax guessing for code fences without specified language
+pygmentsCodeFencesGuessSyntax: false
+# color-codes for highlighting derived from this style
+pygmentsStyle: "monokai"
+# true use pygments-css or false will color code directly
+pygmentsUseClasses: false
+# maximum number of items in the RSS feed
+rssLimit: 15
+# see "Section Menu for Lazy Bloggers", /templates/menu-templates for more info
+SectionPagesMenu: ""
+# default sitemap configuration map
+sitemap:
+# filesystem path to read files relative from
+source: ""
+staticDir: "static"
+# display memory and timing of different steps of the program
+stepAnalysis: false
+# theme to use (located by default in /themes/THEMENAME/)
+themesDir: "themes"
+theme: ""
+title: ""
+# Title Case style guide for the title func and other automatic title casing in Hugo.
+// Valid values are "AP" (default), "Chicago" and "Go" (which was what you had in Hugo <= 0.25.1).
+// See https://www.apstylebook.com/ and http://www.chicagomanualofstyle.org/home.html
+titleCaseStyle: "AP"
+# if true, use /filename.html instead of /filename/
+uglyURLs: false
+# verbose output
+verbose: false
+# verbose logging
+verboseLog: false
+# watch filesystem for changes and recreate as needed
+watch: true
+taxonomies:
+ - category: "categories"
+ - tag: "tags"
+---
+{{< /code >}}
+
+## TOML Configuration
+
+The following is an example of a TOML configuration file. The values under `[params]` will populate the `.Site.Params` variable for use in [templates][]:
+
+```
+contentDir = "content"
+layoutDir = "layouts"
+publishDir = "public"
+buildDrafts = false
+baseURL = "https://yoursite.example.com/"
+canonifyURLs = true
+title = "My Hugo Site"
+
+[taxonomies]
+ category = "categories"
+ tag = "tags"
+
+[params]
+ subtitle = "Hugo is Absurdly Fast!"
+ author = "John Doe"
+```
+
+### All Variables, TOML
+
+The following is the full list of Hugo-defined variables in an example TOML file. The values provided in this example represent the default values used by Hugo.
+
+{{< code file="config.toml" download="config.toml">}}
++++
+archetypeDir = "archetypes"
+# hostname (and path) to the root, e.g. http://spf13.com/
+baseURL = ""
+# include content marked as draft
+buildDrafts = false
+# include content with publishdate in the future
+buildFuture = false
+# include content already expired
+buildExpired = false
+# enable this to make all relative URLs relative to content root. Note that this does not affect absolute URLs.
+relativeURLs = false
+canonifyURLs = false
+# config file (default is path/config.yaml|json|toml)
+config = "config.toml"
+contentDir = "content"
+dataDir = "data"
+defaultExtension = "html"
+defaultLayout = "post"
+# Missing translations will default to this content language
+defaultContentLanguage = "en"
+# Renders the default content language in subdir, e.g. /en/. The root directory / will redirect to /en/
+defaultContentLanguageInSubdir = false
+disableLiveReload = false
+# Do not build RSS files
+disableRSS = false
+# Do not build Sitemap file
+disableSitemap = false
+# Enable GitInfo feature
+enableGitInfo = false
+# Build robots.txt file
+enableRobotsTXT = false
+# Do not render 404 page
+disable404 = false
+# Do not inject generator meta tag on homepage
+disableHugoGeneratorInject = false
+# Allows you to disable all page types and will render nothing related to 'kind';
+# values = "page", "home", "section", "taxonomy", "taxonomyTerm", "RSS", "sitemap", "robotsTXT", "404"
+disableKinds = []
+# Do not make the url/path to lowercase
+disablePathToLower = false
+# Enable Emoji emoticons support for page content; see emoji-cheat-sheet.com
+enableEmoji = false
+# Show a placeholder instead of the default value or an empty string if a translation is missing
+enableMissingTranslationPlaceholders = false
+footnoteAnchorPrefix = ""
+footnoteReturnLinkContents = ""
+# google analytics tracking id
+googleAnalytics = ""
+# if true, auto-detect Chinese/Japanese/Korean Languages in the content. (.Summary and .WordCount can work properly in CJKLanguage)
+hasCJKLanguage = false
+languageCode = ""
+layoutDir = "layouts"
+# Enable Logging
+log = false
+# Log File path (if set, logging enabled automatically)
+logFile =
+# maximum number of items in the RSS feed
+rssLimit = 15
+# "toml","yaml", or "json"
+metaDataFormat = "toml"
+newContentEditor = ""
+# Don't sync permission mode of files
+noChmod = false
+# Don't sync modification time of files
+noTimes = false
+# Pagination
+paginate = 10
+paginatePath = "page"
+# See "content-management/permalinks"
+permalinks =
+# Pluralize titles in lists using inflect
+pluralizeListTitles = true
+# Preserve special characters in taxonomy names ("Gérard Depardieu" vs "Gerard Depardieu")
+preserveTaxonomyNames = false
+# filesystem path to write files to
+publishDir = "public"
+# enables syntax guessing for code fences without specified language
+pygmentsCodeFencesGuessSyntax = false
+# color-codes for highlighting derived from this style
+pygmentsStyle = "monokai"
+# true: use pygments-css or false: color-codes directly
+pygmentsUseClasses = false
+# see "Section Menu for Lazy Bloggers", /templates/menu-templates for more info
+SectionPagesMenu =
+# default sitemap configuration map
+sitemap =
+# filesystem path to read files relative from
+source = ""
+staticDir = "static"
+# display memory and timing of different steps of the program
+stepAnalysis = false
+# theme to use (located by default in /themes/THEMENAME/)
+themesDir = "themes"
+theme = ""
+title = ""
+# if true, use /filename.html instead of /filename/
+uglyURLs = false
+# verbose output
+verbose = false
+# verbose logging
+verboseLog = false
+# watch filesystem for changes and recreate as needed
+watch = true
+[taxonomies]
+ category = "categories"
+ tag = "tags"
++++
+{{< /code >}}
+
+{{% note %}}
+If you are developing your site on a \*nix machine, here is a handy shortcut for finding a configuration option from the command line:
+```
+~/sites/yourhugosite
+hugo config | grep emoji
+enableemoji: true
+```
+{{% /note %}}
+
+## Environmental Variables
+
+In addition to the 3 config options already mentioned, configuration key-values can be defined through operating system environment variables.
+
+For example, the following command will effectively set a website's title on Unix-like systems:
+
+```
+$ env HUGO_TITLE="Some Title" hugo
+```
+
+{{% note "Setting Environment Variables" %}}
+Names must be prefixed with `HUGO_` and the configuration key must be set in uppercase when setting operating system environment variables.
+{{% /note %}}
+
+## Ignore Files When Rendering
+
+The following statement inside `./config.toml` will cause Hugo to ignore files ending with `.foo` and `.boo` when rendering:
+
+```
+ignoreFiles = [ "\\.foo$", "\\.boo$" ]
+```
+
+The above is a list of regular expressions. Note that the backslash (`\`) character is escaped in this example to keep TOML happy.
+
+## Configure Blackfriday
+
+[Blackfriday](https://github.com/russross/blackfriday) is Hugo's built-in Markdown rendering engine.
+
+Hugo typically configures Blackfriday with sane default values that should fit most use cases reasonably well.
+
+However, if you have specific needs with respect to Markdown, Hugo exposes some of its Blackfriday behavior options for you to alter. The following table lists these Hugo options, paired with the corresponding flags from Blackfriday's source code ( [html.go](https://github.com/russross/blackfriday/blob/master/html.go) and [markdown.go](https://github.com/russross/blackfriday/blob/master/markdown.go)).
+
+{{< readfile file="/content/readfiles/bfconfig.md" markdown="true" >}}
+
+{{% note %}}
+1. Blackfriday flags are *case sensitive* as of Hugo v0.15.
+2. Blackfriday flags must be grouped under the `blackfriday` key and can be set on both the site level *and* the page level. Any setting on a page will override its respective site setting.
+{{% /note %}}
+
+{{< code file="bf-config.toml" >}}
+[blackfriday]
+ angledQuotes = true
+ fractions = false
+ plainIDAnchors = true
+ extensions = ["hardLineBreak"]
+{{< /code >}}
+
+{{< code file="bf-config.yml" >}}
+blackfriday:
+ angledQuotes: true
+ fractions: false
+ plainIDAnchors: true
+ extensions:
+ - hardLineBreak
+{{< /code >}}
+
+## Configure Additional Output Formats
+
+Hugo v0.20 introduced the ability to render your content to multiple output formats (e.g., to JSON, AMP html, or CSV). See [Output Formats][] for information on how to add these values to your Hugo project's configuration file.
+
+## Configuration Format Specs
+
+* [TOML Spec][toml]
+* [YAML Spec][yaml]
+* [JSON Spec][json]
+
+[`.Site.Params`]: /variables/site/
+[directory structure]: /getting-started/directory-structure
++[json]: https://www.ecma-international.org/publications/files/ECMA-ST/ECMA-404.pdf "Specification for JSON, JavaScript Object Notation"
+[lookup order]: /templates/lookup-order/
+[Output Formats]: /templates/output-formats/
+[templates]: /templates/
+[toml]: https://github.com/toml-lang/toml
+[yaml]: http://yaml.org/spec/
--- /dev/null
- [json]: /documents/ecma-404-json-spec.pdf
+---
+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]
+#tags: [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.
+
+## 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 `partial/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 YAML structure in your `User0123.yml` data file located directly in `data/`:
+
+```
+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::
+
+```
+<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 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 := "http://a-big-corp.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).
+
+## 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/
projects / brevno-suite / hugo / commitdiff