Understanding Hugo Page Structure

Hugo uses a file-system-based content model: your folder structure directly becomes your website structure.

Sections vs Pages

Section

• Created with _index.md
• Contains multiple pages
• Has its own URL
• Can be nested
• Example: content/docs/guide/_index.md → /docs/guide/

Page

• Created with any .md file (except _index.md)
• Single piece of content
• Leaf in the content tree
• Example: content/docs/guide/install.md → /docs/guide/install/

Key rule: _index.md makes a folder navigable. Without it, the folder is just organization.

The Weight System

Hugo sorts pages by weight:

Why weights instead of alphabetical?

• Semantic ordering (Installation before Advanced Topics)
• Easy reordering
• Leave gaps (1, 5, 10) to insert pages later

URLs Mirror File Paths

Predictable: File path = URL path

Organized: Related content grouped together

Frontmatter

Metadata between --- markers tells Hugo how to handle your content:

Required:

Common optional:

Sidebar Behavior

As documentation grows, collapsed sections keep navigation clean.

Navigation

Automatic (default):

• Hugo generates prev/next based on weight
• No maintenance needed

Manual:

• Use for linear tutorials
• Custom learning paths

Drafts

• Visible in local development
• Hidden in production builds
• Work on content without publishing it

Nesting

Hugo supports unlimited nesting, but keep it simple:

Good (3 levels):

Over-nested (avoid):