Content Authoring

This page covers the Markdown, front matter, and shortcode syntax you'll use when writing content.

Content Structure Link to this heading

A content directory looks like this:

content
├── _index.md              # 1. Home
├── docs
│   ├── _index.md          # 2. Section: List Page for Articles
│   ├── p1.md              # 3-1. Page: Filename Only
│   ├── p2                 # 3-2. Page: Using index.md
│   │   ├── foo.jpg
│   │   └── index.md
│   └── bar
│       ├── _index.md      # Section: Nested Section
│       ├── post-1.md
│       └── post-2.md
│
│
├── tags                   # Optional: Taxonomy and Term
│   ├── _index.md          # 4. Taxonomy: List Page for Tags
│   └── my-tag.md          # 5. Term: Single Tag Page (my-tag)
│
└── categories             # Optional: Another Taxonomy
    ├── _index.md          # Taxonomy: List Page for Categories
    └── tutorials.md       # Term: Single Category Page (tutorials)

Home Link to this heading

Place the home page at _index.md in the top-level content directory.

Section Link to this heading

Use _index.md to create a list page. docs/_index.md lists every article under docs. docs/bar/_index.md lists every article in the nested bar section.

Page Link to this heading

Create a post with either filename.md or filename/index.md. Posts can't have child pages.

Taxonomy Link to this heading

Use tags/ and categories/ to group articles into taxonomies. Just like a section, each taxonomy has its own _index.md as a list page. For example, tags/_index.md lists every tag.

Optional. Even without the actual file, Hugo still generates the corresponding HTML.

Term Link to this heading

Each remaining file under a taxonomy directory is a single term page. tags/my-tag.md is the page for the my-tag tag. categories/tutorials.md is the page for the tutorials category.

Optional. Even without the actual file, Hugo still generates the corresponding HTML.

p1.md or p1/index.md? Link to this heading

Only p1/index.md can own page resources, such as images. Use the p1/index.md format everywhere to keep your project structure consistent, unless one of these two cases applies:

1. Your site has almost no images or other resources.
2. Your site keeps all resources in a single assets directory.

Neither case needs page resources, so the plain p1.md format is simpler and cleaner.

Front Matter Link to this heading

Front matter is the block at the start of every content file that records that content's metadata. It supports three formats, yaml, YAML, and JSON, distinguished purely by delimiter:

• yaml: wrapped in +++
• YAML: wrapped in ---
• JSON: wrapped directly in { }

The three formats are functionally identical, so pick one. YAML is recommended, since most tools default to supporting YAML, and some support only YAML.

A YAML-format Markdown front matter block looks like this:

---
title: 'My First Post'
date: '2026-08-15T10:00:00+08:00'
lastmod: '2026-08-15T10:00:00+08:00'
draft: false
tags: ['hugo', 'notes']
params:
  showToc: true
---

The body of the post starts here.

Common fields:

Front matter settings override the settings in hugo.yaml. params holds theme-specific settings. Hugo can still read theme settings that aren't placed under params, but it's recommended to always nest them there, since this keeps things clearer and more intuitive when migrating themes or managing the site.

HTML in Markdown Link to this heading

Hugo parses Markdown according to the CommonMark (external link) spec. If you're not familiar with Markdown syntax, see Learn Markdown in Y Minutes (external link), or test rendering live in the Playground (external link).

You can also write raw HTML directly inside Markdown content, but it's stripped out by default. To allow it, enable this in hugo.yaml:

markup:
  goldmark:
    renderer:
      unsafe: true

When this isn't enabled, HTML tags are removed.

Also, there must be a blank line between HTML and the surrounding Markdown content. Otherwise Goldmark treats that block as plain HTML and won't parse the Markdown syntax inside it:

<div>

The **bold text** here will render correctly.

</div>

<div>
The **bold text** here will not render, the asterisks will be output literally.
</div>

Referencing Images Link to this heading

Where you store an image determines how you reference it. Hugo has three common locations: the assets/ directory, page resources in the content/ directory, and the static/ directory. Later chapters cover the full directory structure. This section only covers how to reference images from each of the three locations:

• assets/

  Place images in assets/img/ and reference them after processing through Hugo Pipes:

  ![Alt text](/img/photo.png)

• Page resource

  Place both the image and the content file in the same directory under content, and reference the image with a relative path:

  ![Alt text](foo.png)

• static/

  Place images at static/foo.png. These are copied to the output directory unchanged and must be referenced with an absolute path:

  ![Alt text](/foo.png)

hugo-community-docs recommends placing images in assets/:

• Hugo can't process files in static/. It copies them to your site as they are, even if unused.
• static/ relies on absolute paths (/foo.png). If you deploy your site to a subdirectory (such as example.com/blog/), you need to adjust every link. Links that Hugo generates from assets/ automatically point to the correct path.
• Page resources are meant for a page to use its own resources. It's hard for other pages to use the page resources of a different page.

Referencing Posts Link to this heading

hugo-community-docs recommends always linking with the file extension included, for example [link](../post-1/index.md), since this allows your IDE to autocomplete, navigate, and catch broken links.

Shortcodes Link to this heading

Shortcodes are a way to insert template logic into Markdown content, used to handle things Markdown syntax alone can't, such as embedding videos, building tabs, or calling components provided by a theme.

For example, embedding a YouTube video:

{{< youtube id="dQw4w9WgXcQ" >}}

Shortcodes have two syntax forms: {{< >}} and {{% %}}. Most cases use {{< >}}, but which syntax a specific shortcode requires depends on how that shortcode is implemented internally. Refer to the documentation provided by the theme or the shortcode's author to be sure.

To display shortcode syntax itself in your content without executing it, wrap it in {{</* */>}}:

{{</* youtube id="dQw4w9WgXcQ" */>}}