Hugo Content Types vs Kinds vs Archetypes: The Complete Guide

Hugo page kinds determine runtime rendering behavior (home, section, taxonomy), archetypes are scaffolding templates used when creating new content via hugo new, and content types define logical content classification based on section names or archetype usage.

When building static sites with gohugoio/hugo, developers often confuse three fundamental classification systems that operate at different stages of the content lifecycle. While these terms sound interchangeable, they serve distinct purposes—ranging from file creation scaffolding to runtime rendering logic and template selection.

What Are Hugo Page Kinds?

Page kinds are Hugo's internal classification system defined in resources/kinds/kinds.go that determines how a piece of content is processed and rendered at build time. Unlike content types, kinds are automatically assigned by Hugo based on a page's URL structure and location in the content/ directory.

The built-in page kinds include:

• home — The site homepage
• section — List pages for content sections
• page — Individual content pages
• taxonomy — Taxonomy list pages (e.g., /tags/)
• taxonomyTerm — Individual taxonomy term pages (e.g., /tags/hugo/)

Templates access the current kind via the .Kind variable, enabling conditional rendering logic:

{{ if eq .Kind "home" }}
  {{/* render homepage layout */}}
{{ else if eq .Kind "section" }}
  {{/* render section list */}}
{{ end }}

What Are Hugo Archetypes?

Archetypes are content scaffolding templates stored in the archetypes/ directory. When you run hugo new <path>, Hugo searches for an archetype matching the content's section name, falls back to default.md, processes front-matter placeholders using Go template syntax, and writes the result to content/.

Unlike kinds, archetypes operate at content creation time, not render time. They ensure consistent front-matter structure across new posts, pages, or custom content types but have no impact on how Hugo renders the final HTML.

Example archetype file (archetypes/post.md):

---
title: "{{ replace .Name "-" " " | title }}"
date: {{ .Date }}
draft: true
tags: []
---

Running hugo new posts/my-article.md generates content/posts/my-article.md with the above front-matter pre-populated.

What Are Hugo Content Types?

Content types represent the logical classification of content based on its purpose or structure. In Hugo, content types are implicitly determined by the archetype used to create them or the section name where they reside.

When you create content using hugo new posts/hello.md, Hugo assigns the content type posts (matching the section). This classification determines:

• Which archetype was used (archetypes/posts.md)
• Which layout templates are searched (layouts/posts/single.html)
• Which content view templates are available

Content types bridge archetypes (creation) and kinds (rendering), defining what a piece of content is while kinds define how it is rendered.

Comparing the Three Concepts

Concept	Purpose	When Applied	Source Location
Content Types	Logical classification (post, project, recipe)	Content creation and layout resolution	Implicit via section name or archetype
Page Kinds	Rendering behavior (home, section, taxonomy)	Build/render time	resources/kinds/kinds.go
Archetypes	Front-matter scaffolding	Content creation (hugo new)	archetypes/ directory

Practical Usage Examples

Conditional Rendering Based on Kind

Access the .Kind variable in templates to apply specific layouts:

{{/* layouts/_default/baseof.html */}}
{{ if eq .Kind "home" }}
  <main class="homepage">
{{ else if eq .Kind "section" }}
  <main class="section-list">
{{ else }}
  <main class="content-page">
{{ end }}
  {{ block "main" . }}{{ end }}
</main>

Creating a Custom Event Archetype

Define a specialized archetype for event content:

File: archetypes/event.md

---
title: "{{ replace .Name "-" " " | title }}"
date: {{ .Date }}
draft: true
eventDate: {{ .Date }}
location: ""
categories: ["events"]
---

Generate new event content:

hugo new events/annual-conference-2025.md

This creates content/events/annual-conference-2025.md with the pre-defined structure, which Hugo will render as a page kind with the events content type.

Summary

• Page kinds are internal Hugo classifications defined in resources/kinds/kinds.go that determine rendering behavior and template selection at build time.
• Archetypes are scaffolding templates in the archetypes/ directory used by the hugo new command to generate consistent front-matter for new content files.
• Content types are logical classifications derived from section names or archetypes that influence which templates and organization rules apply to content.
• Use .Kind in templates to branch logic based on page classification, and use archetypes to standardize content creation workflows.

Frequently Asked Questions

How do I check what kind a specific page is?

Access the .Kind variable in your templates. For debugging, temporarily add {{ printf "%#v" .Kind }} to your layout to see the string value (e.g., "home", "section", "page") rendered on the page. The available kinds are defined in the Hugo source at resources/kinds/kinds.go.

Can I create custom page kinds?

No, page kinds are hardcoded in Hugo's core (resources/kinds/kinds.go) and represent fundamental rendering classifications. However, you can achieve similar custom classification using content types (via sections or front matter) and conditional template logic. For custom output formats (like JSON or AMP), use Hugo's output format configuration rather than custom kinds.

Why is my archetype not being used when I run hugo new?

Hugo selects archetypes based on the content's section name. If you run hugo new posts/my-article.md, Hugo looks for archetypes/posts.md. If that doesn't exist, it falls back to archetypes/default.md. Ensure your archetype filename matches your content section exactly, and verify the file is in the project root's archetypes/ directory (or the theme's archetypes directory if using a theme).

Do content types affect page kinds?

No, content types and page kinds operate independently. A content type (like post or event) determines which archetype was used and which layout templates Hugo searches for (e.g., layouts/post/single.html). The page kind (like page or section) determines the rendering behavior and internal classification. A single content file has one content type and one page kind simultaneously, but these classifications serve different purposes in the build pipeline.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}