diff options
author | Bjørn Erik Pedersen <bjorn.erik.pedersen@gmail.com> | 2024-01-27 10:47:28 +0100 |
---|---|---|
committer | Bjørn Erik Pedersen <bjorn.erik.pedersen@gmail.com> | 2024-01-27 10:47:28 +0100 |
commit | fc7de7136acbcf0aef54ae8460c7702bc83709be (patch) | |
tree | c109bb4dd1f1b054db476e7e4117f79bdd62ec9e /docs/content/en/content-management/front-matter.md | |
parent | 1083bf7c08e6f35826279065b8a09a16cc991c7f (diff) |
docs: Prepare for new sub tree
See #11925
Diffstat (limited to 'docs/content/en/content-management/front-matter.md')
-rw-r--r-- | docs/content/en/content-management/front-matter.md | 244 |
1 files changed, 0 insertions, 244 deletions
diff --git a/docs/content/en/content-management/front-matter.md b/docs/content/en/content-management/front-matter.md deleted file mode 100644 index 7593fb759..000000000 --- a/docs/content/en/content-management/front-matter.md +++ /dev/null @@ -1,244 +0,0 @@ ---- -title: Front matter -description: Hugo allows you to add front matter in yaml, toml, or json to your content files. -categories: [content management] -keywords: [front matter,yaml,toml,json,metadata,archetypes] -menu: - docs: - parent: content-management - weight: 60 -weight: 60 -toc: true -aliases: [/content/front-matter/] ---- - -**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. - -{{< youtube Yh2xKRJGff4 >}} - -## Front matter formats - -Hugo supports four 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. - -ORG -: a group of Org mode keywords in the format '`#+KEY: VALUE`'. Any line that does not start with `#+` ends the front matter section. - Array values can either be separated into multiple lines (`#+KEY: VALUE_1` and `#+KEY: VALUE_2`) or a whitespace separated list of strings (`#+KEY[]: VALUE_1 VALUE_2`). - -### Example - -{{< code-toggle >}} -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" -{{< /code-toggle >}} - -## 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. - -audio -: An array of paths to audio files related to the page; used by the `opengraph` [internal template](/templates/internal) to populate `og:audio`. - -cascade -: A map of front matter keys whose values are passed down to the page's descendants unless overwritten by self or a closer ancestor's cascade. See [Front Matter Cascade](#front-matter-cascade) for details. - -date -: The datetime assigned to this page. This is usually fetched from the `date` field in front matter, but this behavior is configurable. - -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. - -headless -: If `true`, sets a leaf bundle to be [headless][headless-bundle]. - -images -: An array of paths to images related to the page; used by [internal templates](/templates/internal) such as `_internal/twitter_cards.html`. - -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 [Content Types][content type]. - -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`. - -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`. - -resources -: Used for configuring page bundle resources. See [Page Resources][page-resources]. - -series -: An array of series this page belongs to, as a subset of the `series` [taxonomy](/content-management/taxonomies/); used by the `opengraph` [internal template](/templates/internal) to populate `og:see_also`. - -slug -: Overrides the last segment of the URL path. Not applicable to section pages. See [URL Management](/content-management/urls/#slug) for details. - -summary -: Text used when providing a summary of the article in the `.Summary` page variable; details available in the [content-summaries](/content-management/summaries/) section. - -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 -: Overrides the entire URL path. Applicable to regular pages and section pages. See [URL Management](/content-management/urls/#url) for details. - -videos -: An array of paths to videos related to the page; used by the `opengraph` [internal template](/templates/internal) to populate `og:video`. - -weight -: used for [ordering your content in lists][ordering]. Lower weight gets higher precedence. So content with lower weight will come first. If set, weights should be non-zero, as 0 is interpreted as an *unset* weight. - -taxonomies -: Field name of the *plural* form of the index. See `tags` and `categories` in the above front matter examples. *Note that the plural form of user-defined taxonomies cannot be the same as any of the predefined front matter variables.* - -{{% note %}} -If neither `slug` nor `url` is present and [permalinks are not configured otherwise in your site configuration file](/content-management/urls/#permalinks), Hugo will use the file name 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. - -{{< code-toggle >}} -include_toc: true -show_comments: false -{{</ code-toggle >}} - -## Front matter cascade - -Any node or section can pass down to descendants a set of front matter values as long as defined underneath the reserved `cascade` front matter key. - -### Target specific pages - -The `cascade` block can be a slice with a optional `_target` keyword, allowing for multiple `cascade` values targeting different page sets. - -{{< code-toggle >}} -title ="Blog" -[[cascade]] -background = "yosemite.jpg" -[cascade._target] -path="/blog/**" -lang="en" -kind="page" -[[cascade]] -background = "goldenbridge.jpg" -[cascade._target] -kind="section" -{{</ code-toggle >}} - -Keywords available for `_target`: - -path -: A [Glob](https://github.com/gobwas/glob) pattern matching the content path below /content. Expects Unix-styled slashes. Note that this is the virtual path, so it starts at the mount root. The matching supports double-asterisks so you can match for patterns like `/blog/*/**` to match anything from the third level and down. - -kind -: A Glob pattern matching the Page's Kind(s), e.g. "{home,section}". - -lang -: A Glob pattern matching the Page's language, e.g. "{en,sv}". - -environment -: A Glob pattern matching the build environment, e.g. "{production,development}" - -Any of the above can be omitted. - -{{% note %}} -When making a site that supports multiple languages, defining a `[[cascade]]` is recommended to be done in [Site Config](../../getting-started/configuration/#cascade) to prevent duplication. - -If you instea define a `[[cascade]]` in front matter for multiple languages, an `content/XX/foo/_index.md` file needs to be made on a per-language basis, with `XX` the glob pattern matching the Page's language. In this case, the **lang** keyword is ignored. -{{% /note %}} - -### Example - -In `content/blog/_index.md` - -{{< code-toggle >}} -title: Blog -cascade: - banner: images/typewriter.jpg -{{</ code-toggle >}} - -With the above example the Blog section page and its descendants will return `images/typewriter.jpg` when `.Params.banner` is invoked unless: - -- Said descendant has its own `banner` value set -- Or a closer ancestor node has its own `cascade.banner` value set. - -## 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 [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/ -[config]: /getting-started/configuration/ -[content type]: /content-management/types/ -[contentorg]: /content-management/organization/ -[headless-bundle]: /content-management/page-bundles/#headless-bundle -[json]: https://www.ecma-international.org/publications/files/ECMA-ST/ECMA-404.pdf -[lists]: /templates/lists/#sort-content -[lookup]: /templates/lookup-order/ -[ordering]: /templates/lists/ -[outputs]: /templates/output-formats/ -[page-resources]: /content-management/page-resources/ -[pagevars]: /variables/page/ -[section]: /content-management/sections/ -[taxweight]: /content-management/taxonomies/ -[toml]: https://toml.io/ -[urls]: /content-management/urls/ -[variables]: /variables/ -[yaml]: https://yaml.org/spec/ |