Skip to main content
Blog posts in your Hugo site are stored in the content/posts/ directory. Each post lives in its own subdirectory with an index.md file.

​
Post structure

Hugo uses a specific directory structure for blog posts. Each post should be created as a subdirectory within content/posts/ containing an index.md file: 
content/
└── posts/
    └── on-the-proliferation-of-artifical-intelligence/
        └── index.md
This structure allows you to keep related assets (images, files, etc.) alongside your post content.

​
Creating a new post

1
Create the post directory
2
Navigate to your Hugo site’s root directory and create a new subdirectory in content/posts/:
3
mkdir -p content/posts/your-post-slug
4
Use a descriptive, URL-friendly slug for your directory name (lowercase, hyphens instead of spaces).
5
Create the index.md file
6
Create an index.md file inside your new directory:
7
touch content/posts/your-post-slug/index.md
8
Add front matter
9
Open the index.md file and add front matter at the top. Front matter uses TOML syntax enclosed in +++ markers:
10
+++
title = 'Your Post Title'
date = 2026-03-03T10:00:00-08:00
draft = false
+++
11
Write your content
12
Below the closing +++, write your post content using Markdown syntax.

​
Example post

Here’s a real example from the benson.vc site: 
+++
title = 'On the Proliferation of Artificial Intelligence'
date = 2018-07-28T18:02:45-08:00
draft = false
+++
> **Q: Do the benefits of artificial intelligence outweigh the risks?**

*The late physicist Stephen Hawking warned that artificial intelligence (AI) was "either the best or the worst thing ever to happen to humanity"...*

While Artificial Intelligence (AI) promises unprecedented advances in healthcare, transportation, logistics...
This post is located at: 
content/posts/on-the-proliferation-of-artifical-intelligence/index.md

​
Draft vs. published posts

Control whether a post appears on your live site using the draft field in front matter:
  • draft = false - Post is published and visible
  • draft = true - Post is hidden from production builds
When running Hugo locally with hugo server -D, draft posts will be visible for preview.

​
Post URLs

Hugo generates URLs based on your directory structure. A post at: 
content/posts/my-awesome-post/index.md
Will be accessible at: 
https://yourdomain.com/posts/my-awesome-post/

​
Including assets

Since each post has its own directory, you can include images and other files alongside your content: 
content/posts/my-awesome-post/
├── index.md
├── header-image.jpg
└── diagram.png
Reference these assets in your Markdown using relative paths: 
![My header image](header-image.jpg)

​
Common questions

Yes, you can create subdirectories within content/posts/ to organize your content. However, the standard Congo theme structure uses a flat posts/ directory with each post in its own subdirectory. For taxonomies like categories and tags, use front matter fields instead of directory structure.
While you can create posts as single .md files directly in content/posts/, using subdirectories with index.md is the recommended approach. This is called a “page bundle” in Hugo and provides better organization and asset management.
The date in front matter must follow RFC 3339 format with timezone information. Hugo will parse this date and you can format it in your templates using Hugo’s date formatting functions. The Congo theme handles date display automatically.
Hugo supports multiple content formats including Markdown, HTML, and AsciiDoc. However, Markdown is the recommended and most widely supported format for the Congo theme.

Build docs developers (and LLMs) love

Get started for freeTalk to us