Directory Structure and Assets

Understanding Hugo's directory structure is essential for managing content and assets effectively.

Directory Structure

A typical Hugo project follows this structure:

.
├── archetypes/      # Templates for new Markdown files
├── assets/          # Processed assets (images, CSS, JS)
├── content/         # Markdown files and page bundles
├── data/            # Custom configuration data
├── i18n/            # Translation files
├── layouts/         # Custom layout files
├── static/          # Raw static files (favicons, robots.txt)
├── themes/          # Theme files
└── hugo.yaml        # Site configuration

This guide focuses on three key directories: assets/, static/, and content/, as these are the ones you'll work with most frequently.

Page Bundles

Hugo supports two content structures for Markdown files in the content/ directory.

A standalone page is stored as name.md. This structure cannot associate images or other resources with the page, making it unsuitable for thumbnails or bundled assets.

A leaf bundle is created by placing content in an index.md file within a directory. Any images in the same directory (or subdirectories) become page resources that the theme can automatically discover and use.

Convert this structure:

content/
└── awesome_article.md

into this:

content/
└── awesome_article/
    ├── index.md
    └── feature.png

Create a new article using: hugo new content posts/first/index.md

Asset Placement: Assets vs. Static

1. assets/ (Processable)

Hugo has the ability to process files here (resize images, convert to WebP, minify CSS/JS). All images and stylesheets go here.

2. static/ (Raw Files)

Hugo cannot process files here, they are copied directly to the build directory. Use for raw files such as favicons and robots.txt.

Referencing Assets in Markdown

Global Resources

To reference an image in assets/img/example.webp, use a leading slash:

![alt text](/img/logo.svg "image description")

Local Resources

For leaf bundles (directories containing index.md), place images directly within the bundle's folder:

content/
└── posts/
    └── my-article/
        ├── index.md
        └── local-image.png

Reference them locally within index.md:

![alt text](./local-image.png "image description")