hugo/docs/content/en/content-management/types.md

100 lines
5.1 KiB
Markdown
Raw Normal View History

---
title: Content Types
linktitle: Types
description: Hugo supports sites with multiple content types and assumes your site will be organized into sections, where each section represents the corresponding type.
date: 2017-02-01
publishdate: 2017-02-01
lastmod: 2017-02-01
categories: [content management]
keywords: [lists,sections,content types,types,organization]
menu:
docs:
parent: "content-management"
weight: 60
weight: 60 #rem
draft: false
aliases: [/content/types]
toc: true
---
A **content type** can have a unique set of metadata (i.e., [front matter][]) or customized [template][] and can be created by the `hugo new` command via [archetypes][].
## What is a Content Type
[Tumblr][] is a good example of a website with multiple content types. A piece of "content" could be a photo, quote, or a post, each with different sets of metadata and different visual rendering.
## Assign a Content Type
Hugo assumes that your site will be organized into [sections][] and each section represents a corresponding type. This is to reduce the amount of configuration necessary for new Hugo projects.
If you are taking advantage of this default behavior, each new piece of content you place into a section will automatically inherit the type. Therefore a new file created at `content/posts/new-post.md` will automatically be assigned the type `posts`. Alternatively, you can set the content type in a content file's [front matter][] in the field "`type`".
## Create New Content of a Specific Type
You can manually add files to your content directories, but Hugo can create and populate a new content file with preconfigured front matter via [archetypes][].
## Define a Content Type
Creating a new content type is easy. You simply define the templates and archetype unique to your new content type, or Hugo will use defaults.
{{% note "Declaring Content Types" %}}
Remember, all of the following are *optional*. If you do not specifically declare content types in your front matter or develop specific layouts for content types, Hugo is smart enough to assume the content type from the file path and section. (See [Content Sections](/content-management/sections/) for more information.)
{{% /note %}}
The following examples take you stepwise through creating a new type layout for a content file that contains the following front matter:
{{< code file="content/events/my-first-event.md" copy="false" >}}
+++
title = My First Event
date = "2016-06-24T19:20:04-07:00"
description = "Today is my 36th birthday. How time flies."
type = "event"
layout = "birthday"
+++
{{< /code >}}
Squashed 'docs/' changes from 715741f73..4e7e1815b 4e7e1815b Fix some typos d23d8f5c4 Remove 'fundamentals' category from function pages 52fa65e15 Mention Chroma as the preferred syntax highlighter 64ca535db Merge commit '8762aee8afe30bec6f1fbc9560749983dc44d60b' 8762aee8a Squashed 'themes/gohugoioTheme/' changes from 396b859f..6f3a8bf5 03f0673a9 Move the gopher to the theme 320e268cd Spelling e45b640f7 More layout lookup work fe0ad9d9d Sync the YAML config menu example with TOML's b9505fc70 Remove template reference to ordinal numbers 0fa2532d3 Remove deprecated Hugoidx, add native hugo solution 2152b907c Fix a link in the last commit 47614f416 Manually specifying heading anchors in Markdown content 9d6770d2a Release notes 0.37.1 e1eed8b27 Remove some unused images e960046f5 releaser: Prepare repository for 0.38-DEV 4fa83a4ee releaser: Add release notes to /docs for release of 0.37.1 46c879995 releaser: Bump versions for release of 0.37.1 fb3ac5a3e releaser: Prepare repository for 0.38-DEV 4870c8e7b Update archetypes.md 232c0b578 Merge commit '2b18014fd0aa99e9f1a5610ba875101351a90de3' 2b18014fd Squashed 'themes/gohugoioTheme/' changes from fe71e360..396b859f 62567e9aa Add some "writing guidelines" 7cfd530d2 Revise the archetype docs 5d4c3c03c Update data-templates.md e5fee3099 Update page-bundles.md ca7f03c8d Update page-bundles.md 2a7fdc269 Fix typo 'vailable' to 'available' line 53 999b75201 LastMod should be Lastmod? 099f46ca5 Fix spacing in content-management/types.md 6bcdc58ef Word choice improvements 20e8a21f6 update rss linking docs 7ef44d262 Add some missing configuration entries f1c7aa568 Sort config list 5cb8ceade Create a proper definition list for the configuration settings 25dffe4ac Send custom dimensions in GA 55df01a34 Fix broken gtag 6c8772aad Add site to GA config e63acb894 Remove conflicting release note for 0.35 f30083a23 Add branch to GA config 99caedb96 Set the small-multiples to draft 4a33c70ab Polish the Small Multiples showcase 7b2f1ea2e Add small multiples showcase e78e96bae Add new sponsor c42943041 updated to new Forestry logo e07eda273 Add OS env to faq 414f0dbc6 Release Hugo 0.37 85f0cc324 Merge branch 'temp37' 1e6da9497 Rebuild images 75e97adfc releaser: Add release notes to /docs for release of 0.37 50b887cb0 releaser: Bump versions for release of 0.37 7acf73ba3 Merge commit '900b5f6cfe5a377ef369d26cd700201be4cf6b06' 819d02c30 Merge commit '374d184e6747678364fd61f5faf328ec9205eb6b' c7eacf018 Fix typos in development contribution doc git-subtree-dir: docs git-subtree-split: 4e7e1815b742659dec1c8f59a1896a3396c7b6e9
2018-03-11 19:39:20 +00:00
By default, Hugo assumes `*.md` under `events` is of the `events` content type. However, we have specified that this particular file at `content/events/my-first-event.md` is of type `event` and should render using the `birthday` layout.
### Create a Type Layout Directory
Create a directory with the name of the type in `/layouts`. For creating these custom layouts, **type is always singular**; e.g., `events => event` and `posts => post`.
For this example, you need to create `layouts/event/birthday.html`.
{{% note %}}
If you have multiple content files in your `events` directory that are of the `special` type and you don't want to define the `layout` specifically for each piece of content, you can create a layout at `layouts/special/single.html` to observe the [single page template lookup order](/templates/single-page-templates/).
{{% /note %}}
{{% warning %}}
With the "everything is a page" data model introduced in v0.18 (see [Content Organization](/content-management/organization/)), you can use `_index.md` in content directories to add both content and front matter to [list pages](/templates/lists/). However, `type` and `layout` declared in the front matter of `_index.md` are *not* currently respected at build time as of v0.19. This is a known issue [(#3005)](https://github.com/gohugoio/hugo/issues/3005).
{{% /warning %}}
### Create Views
Many sites support rendering content in a few different ways; e.g., a single page view and a summary view to be used when displaying a [list of section contents][sectiontemplates].
Hugo limits assumptions about how you want to display your content to an intuitive set of sane defaults and will support as many different views of a content type as your site requires. All that is required for these additional views is that a template exists in each `/layouts/<TYPE>` directory with the same name.
### Custom Content Type Template Lookup Order
The lookup order for the `content/events/my-first-event.md` templates would be as follows:
* `layouts/event/birthday.html`
* `layouts/event/single.html`
* `layouts/events/single.html`
* `layouts/_default/single.html`
### Create a Corresponding Archetype
We can then create a custom archetype with preconfigured front matter at `event.md` in the `/archetypes` directory; i.e. `archetypes/event.md`.
Read [Archetypes][archetypes] for more information on archetype usage with `hugo new`.
[archetypes]: /content-management/archetypes/
[front matter]: /content-management/front-matter/
[sectiontemplates]: /templates/section-templates/
[sections]: /content-management/sections/
[template]: /templates/
Squashed 'docs/' changes from 715741f73..4e7e1815b 4e7e1815b Fix some typos d23d8f5c4 Remove 'fundamentals' category from function pages 52fa65e15 Mention Chroma as the preferred syntax highlighter 64ca535db Merge commit '8762aee8afe30bec6f1fbc9560749983dc44d60b' 8762aee8a Squashed 'themes/gohugoioTheme/' changes from 396b859f..6f3a8bf5 03f0673a9 Move the gopher to the theme 320e268cd Spelling e45b640f7 More layout lookup work fe0ad9d9d Sync the YAML config menu example with TOML's b9505fc70 Remove template reference to ordinal numbers 0fa2532d3 Remove deprecated Hugoidx, add native hugo solution 2152b907c Fix a link in the last commit 47614f416 Manually specifying heading anchors in Markdown content 9d6770d2a Release notes 0.37.1 e1eed8b27 Remove some unused images e960046f5 releaser: Prepare repository for 0.38-DEV 4fa83a4ee releaser: Add release notes to /docs for release of 0.37.1 46c879995 releaser: Bump versions for release of 0.37.1 fb3ac5a3e releaser: Prepare repository for 0.38-DEV 4870c8e7b Update archetypes.md 232c0b578 Merge commit '2b18014fd0aa99e9f1a5610ba875101351a90de3' 2b18014fd Squashed 'themes/gohugoioTheme/' changes from fe71e360..396b859f 62567e9aa Add some "writing guidelines" 7cfd530d2 Revise the archetype docs 5d4c3c03c Update data-templates.md e5fee3099 Update page-bundles.md ca7f03c8d Update page-bundles.md 2a7fdc269 Fix typo 'vailable' to 'available' line 53 999b75201 LastMod should be Lastmod? 099f46ca5 Fix spacing in content-management/types.md 6bcdc58ef Word choice improvements 20e8a21f6 update rss linking docs 7ef44d262 Add some missing configuration entries f1c7aa568 Sort config list 5cb8ceade Create a proper definition list for the configuration settings 25dffe4ac Send custom dimensions in GA 55df01a34 Fix broken gtag 6c8772aad Add site to GA config e63acb894 Remove conflicting release note for 0.35 f30083a23 Add branch to GA config 99caedb96 Set the small-multiples to draft 4a33c70ab Polish the Small Multiples showcase 7b2f1ea2e Add small multiples showcase e78e96bae Add new sponsor c42943041 updated to new Forestry logo e07eda273 Add OS env to faq 414f0dbc6 Release Hugo 0.37 85f0cc324 Merge branch 'temp37' 1e6da9497 Rebuild images 75e97adfc releaser: Add release notes to /docs for release of 0.37 50b887cb0 releaser: Bump versions for release of 0.37 7acf73ba3 Merge commit '900b5f6cfe5a377ef369d26cd700201be4cf6b06' 819d02c30 Merge commit '374d184e6747678364fd61f5faf328ec9205eb6b' c7eacf018 Fix typos in development contribution doc git-subtree-dir: docs git-subtree-split: 4e7e1815b742659dec1c8f59a1896a3396c7b6e9
2018-03-11 19:39:20 +00:00
[Tumblr]: https://www.tumblr.com/