Skip to main content
Back to path

Welcome to a Grasp lesson

Create a free account to keep studying and create your own study path.

Lesson 8

Content vs. Data: Choosing the Right Directory

Recommended resources

Hello again! Welcome to the third lesson in our module on content architecture.

In the last two lessons, we explored how to use Google Sheets as a content source for a Hugo site. We saw how to structure a sheet to generate individual pages (like blog posts) for the /content directory, and how to structure another sheet to provide data (like a list of features) for the /data directory.

Now it's time to connect these two concepts. Today's lesson focuses on a crucial architectural decision you'll make in every Hugo project: When should you store information in /content versus /data? Understanding this distinction is fundamental to building well-structured, scalable, and maintainable sites.

For someone with your deep experience in SEO and traditional CMS like WordPress, this lesson will clarify one of the core philosophical differences in how static site generators operate. Instead of a database where content types can sometimes be ambiguous, Hugo provides a very clear, file-system-based separation of concerns.

The Fundamental Difference: Pages vs. Data

Let's start with the single most important rule that separates the content and data directories:

  • The /content directory is for creating pages. Every Markdown file you place here (e.g., content/blog/my-first-post.md) will be processed by Hugo and turned into an HTML page with its own unique URL (e.g., yoursite.com/blog/my-first-post/).
  • The /data directory is for storing supplementary data. Files in this directory (e.g., data/testimonials.json) do not create pages. They are simply structured data (in JSON, YAML, or TOML format) that your templates can access and use anywhere on the site.
Hugo Project Directory Structure
As you can see in this typical Hugo project structure, `content` and `data` are sibling directories, but they serve distinct purposes. One holds page-generating content, the other holds reusable structured data.

To get a quick refresher on the roles of these directories, let's watch a brief segment from the Giraffe Academy tutorial we've seen before.

Creating a New Site / Directory Structure | Hugo - Static Site Generator | Tutorial 4

This video, 'Creating a New Site / Directory Structure', provides a concise overview of the purpose of both the content and data folders.

Watch from 3:34 to 4:44. Notice how the presenter describes the content folder as the place for 'web pages' and the data folder as a 'database for your website' that holds data files.

This distinction is a direct result of Hugo's static nature. Unlike a database-driven CMS that dynamically builds pages on every request, Hugo pre-builds all pages from files. The directory structure explicitly tells Hugo what to build.

A Detailed Comparison

To dig deeper into this, let's look at an article that provides a fantastic side-by-side comparison.

The complete guide to Hugo file structure and code organization

The article 'The complete guide to Hugo file structure and code organization' by jpdroege offers a clear breakdown of the two directories. The table in this section is particularly useful.

Read the section titled 'Data: structured content'. Pay close attention to the table comparing the content and data directories. This table perfectly summarizes the core differences.

Let's summarize and expand on the key points from that table:

Aspect /content /data
Primary Purpose To create individual web pages with unique URLs. To store structured data that can be used by templates.
Output Each file becomes an HTML page. Files do not become pages. The data is available via .Site.Data.
Format Primarily Markdown (.md), allowing for rich text and prose. Structured formats like JSON, YAML, or TOML (key-value pairs).
Typical Use Case Blog posts, service pages, case studies, privacy policy pages. Lists of team members, pricing plans, testimonials, social media links.
SEO Impact Direct. This is the content you want search engines to crawl and index as distinct pages. Indirect. This data enriches the pages made from /content, contributing to page quality, but isn't indexed on its own.

To understand the technical side of the /data directory better, the official Hugo documentation is the best source.

Data sources

Let's review the official Hugo documentation on 'Data sources'. This will reinforce the technical purpose and capabilities of the data directory.

Read the introduction and the section titled 'Data directory'. This explains how Hugo merges data files from your project, themes, and modules into a single data structure accessible in your templates.

A Mental Model: How to Choose

Now for the most important part: how do you decide where to put a piece of information? When you're architecting a new section of your site, ask yourself these questions:

  1. Does this content need its own dedicated page and URL?

    • Yes: It belongs in the /content directory. This is the clearest indicator. Think of a blog post, a product description, or an "About Us" page. From an SEO perspective, these are your indexable landing pages.
    • No: It is a strong candidate for the /data directory. For example, a list of testimonials to be displayed in a carousel on the homepage doesn't need its own URL.

  2. Is this content primarily prose (written text) or structured data?

    • Prose: The /content directory, using Markdown, is the ideal choice. It's designed for writing articles and pages.
    • Structured Data: The /data directory is perfect. A list of features, each with an icon, title, and description, is much cleaner to manage in a JSON file than in a Markdown file's front matter.

  3. Will this exact same data be used in multiple, different places across the site?

    • Yes: The /data directory is an excellent choice for this "Don't Repeat Yourself" (DRY) principle. For example, a list of company office locations could be stored in data/locations.json and then used to build a map on the contact page and list the addresses in the site's footer.

A WordPress Analogy

Given your expertise with WordPress, here's a helpful analogy:

  • Hugo's /content directory is like your Posts and Pages. Each entry is a discrete, viewable entity with a permalink.
  • Hugo's /data directory is like data you might manage via a Theme Options panel or a dedicated plugin (like a "Team Members" or "Testimonials" plugin). It's centralized data that doesn't have its own public-facing page but is pulled into various templates as needed.
Test your understanding!

You are building a corporate website. For each of the following pieces of information, decide whether it belongs in the /content or /data directory, and briefly explain why.

  1. A series of 20 in-depth case studies, each with a long description, images, and results.
  2. The company's three main office addresses (New York, London, Tokyo).
  3. The text for the website's "Privacy Policy" page.
  4. A list of partner company logos to be displayed in the website footer.
Show answer
  1. /content: Each case study needs its own dedicated page and URL to be shared and indexed by search engines. They are also prose-heavy, making Markdown the perfect format. You'd likely structure this as content/case-studies/study-a.md, content/case-studies/study-b.md, etc.
  2. /data: The office addresses are structured data (street, city, country) and will likely be used in multiple places (footer, contact page). They don't need their own individual pages. A file like data/offices.json would be perfect.
  3. /content: The privacy policy is a single, prose-heavy document that requires its own dedicated page and URL (/privacy-policy/). This is a classic use case for a file like content/privacy-policy.md.
  4. /data: This is a list of structured items (each with a name and logo_url). They don't need individual pages and are meant for reuse. data/partners.json is the ideal location.

Conclusion

You've now established a clear mental framework for organizing information in a Hugo project. This architectural decision is one of the first and most important you'll make, and getting it right sets you up for a scalable and intuitive "vibe coding" workflow.

Key Takeaways:

  • /content = Pages: Use for any content that needs its own URL. This is your primary, indexable content, best written in Markdown.
  • /data = Reusable Structured Data: Use for lists of items or key-value data that doesn't need a standalone page but enriches other pages. This is perfect for JSON, YAML, or TOML files.
  • Your decision framework: Ask yourself if the content needs a URL, if it's prose vs. structured data, and if it needs to be reused.

Preview of the next lesson:
Now that you have a firm grasp of when to use /content versus /data, the next logical step is to automate the process of getting your information from Google Sheets into these directories. In our next lesson, we will learn how to configure an AI tool to synchronize a Google Sheet with the Hugo project's content or data folders, bringing our full "Google Sheets as a CMS" workflow to life.