Complete Hugo Features Reference Guide

Introduction

This comprehensive guide demonstrates all major Hugo features and serves as a reference when creating blog posts. Whether you’re new to Hugo or need a quick syntax reminder, you’ll find examples of markdown formatting, front matter configuration, shortcodes, and best practices all in one place.

Quick Navigation

Use the table of contents above to jump to specific sections. This guide covers everything from basic markdown syntax to advanced Hugo features like shortcodes and front matter configuration.

Markdown Basics

Text Formatting

• Bold text using **bold**
• Italic text using *italic*
• Bold and italic using ***bold and italic***
• Strikethrough using ~~strikethrough~~
• Inline code using backticks
• Links using [text](url)

Lists

Unordered Lists

• Item 1
• Item 2
  • Nested item 2.1
  • Nested item 2.2
    • Deep nested item
• Item 3

Ordered Lists

1. First item
2. Second item
   1. Nested ordered item
   2. Another nested item
3. Third item

Task Lists

• Completed task
• Incomplete task
• Another task to do

Blockquotes

This is a blockquote. It can span multiple lines.

Nested blockquotes are also possible.

Or with attribution:

“The only way to do great work is to love what you do.” — Steve Jobs

You can also use blockquotes as callout boxes:

Note: This is a note-style callout box for informational content.

Warning: This is a warning callout box for important cautions.

Tip: This is a tip callout box for helpful suggestions.

Code Blocks

Inline Code

Use var example = "inline code" within text.

Fenced Code Blocks with Syntax Highlighting

// JavaScript example
function greet(name) {
    console.log(`Hello, ${name}!`);
    return true;
}

greet("Hugo");

# Python example
def fibonacci(n):
    """Generate fibonacci sequence"""
    a, b = 0, 1
    for _ in range(n):
        yield a
        a, b = b, a + b

print(list(fibonacci(10)))

// Go example
package main

import "fmt"

func main() {
    fmt.Println("Hello from Hugo!")
}

# Bash example
#!/bin/bash
echo "Building Hugo site..."
hugo --minify

{
  "name": "example",
  "version": "1.0.0",
  "description": "JSON example"
}

# YAML example
title: My Hugo Site
baseURL: https://example.com
languageCode: en-us

Images

Markdown Image Syntax

Hugo Figure Shortcode

The figure shortcode provides more control over images with captions, alt text, and sizing options:

{{< figure src="/images/sample.jpg" title="Image Title" alt="Alt text" caption="Caption text" >}}

Tables

Basic Table

Aligned Tables

Links and References

Internal Links

Hugo provides special shortcodes for internal linking (Note: Replace paths with actual content in your site):

[Link to another post]({{< ref "/posts/another-post.md" >}})
[Link to about page]({{< ref "/about.md" >}})
[Link with anchor]({{< relref "/posts/another-post.md#section" >}})

External Links

• Hugo Documentation
• Hugo Community
• Hugo Themes

Footnotes

Here’s a sentence with a footnote.¹

Here’s another with a longer footnote.²

Hugo Built-in Shortcodes

Hugo includes several built-in shortcodes for embedding content:

YouTube Video

{{< youtube w7Ft2ymGmfc >}}

Vimeo Video

{{< vimeo 146022717 >}}

GitHub Gist

{{< gist spf13 7896402 >}}

Tweet Embed

{{< tweet user="GoHugoIO" id="877500564405444608" >}}

Highlight with Line Numbers

{{< highlight python "linenos=table,hl_lines=2 4-6" >}}
def example():
    # This line will be highlighted
    data = [1, 2, 3]
    # These lines too
    result = sum(data)
    return result
{{< /highlight >}}

Parameters from Config

You can reference site parameters:

Site title: {{< param "title" >}}

Horizontal Rules

Use three or more hyphens:

HTML in Markdown

Hugo allows raw HTML in markdown (if enabled in config):

Definition Lists

Term 1

Definition for term 1

Term 2

First definition for term 2

Second definition for term 2

Emojis

You can use emojis in your posts! 😊 🚀 ❤️ 🎉

• 💻 Technology
• 📚 Learning
• 💡 Ideas
• ⭐ Favorites

Advanced Markdown Features

Nested Lists with Multiple Levels

1. First level
   • Second level bullet
   • Another second level
     1. Third level number
     2. Another third level
        • Fourth level bullet
2. Back to first level

Complex Tables

Front Matter Features Demonstrated

This post demonstrates the following front matter options:

Metadata

• Title: Custom title for the post.
• Date: Publication date.
• LastMod: Last modification date.
• Draft: Controls publication status (false = published, true = draft).
• Description: Meta description for SEO.
• Keywords: SEO keywords array.

Taxonomies

• Tags: hugo, markdown, tutorial, sample.
• Categories: Technology, Blogging.
• Series: Hugo Guide (groups related posts).

Display Options

• showToc: Show table of contents.
• TocOpen: Auto-expand TOC.
• ShowReadingTime: Display estimated reading time.
• ShowBreadCrumbs: Navigation breadcrumbs.
• ShowPostNavLinks: Previous/Next post links.
• ShowWordCount: Display word count.

Author & Social

• Author: Single or multiple authors.
• Comments: Enable/disable comments.
• disableShare: Control social sharing buttons.

Cover Image

• image: Path to cover image.
• alt: Alt text for accessibility.
• caption: Display caption.
• relative: Use relative path for page bundles.
• hidden: Hide on single page view.

Other Options

• weight: Control sorting order.
• aliases: URL redirects from old paths.
• canonicalURL: Specify canonical URL.
• editPost: GitHub edit link configuration.

Page Organization Tips

Using Page Bundles

Organize related content together. Page bundles are useful when you have multiple assets (images, data files) that belong to a single post:

content/posts/my-post/
├── index.md          # Main content
├── image1.jpg        # Images
├── image2.png
└── data.json         # Data files

Reference with relative paths: ![Image](image1.jpg)

When to use page bundles: Use them when your post has multiple images or related files. For simple posts with no assets, a single .md file in the posts directory is sufficient.

Content Organization Best Practices

1. Use descriptive titles for better SEO and user experience.
2. Add relevant tags and categories for content discovery.
3. Include a cover image for visual appeal in listings.
4. Write a custom summary to control what appears in previews.
5. Use headings hierarchically (h2 → h3 → h4, don’t skip levels).
6. Add internal links to keep readers engaged.
7. Enable table of contents for longer articles.
8. Set lastmod date when updating old posts.
9. Use aliases to maintain old URLs when restructuring.
10. Add edit links for open-source or collaborative blogs.

SEO Optimization

Key Elements for SEO

• ✅ Descriptive, keyword-rich title.
• ✅ Meta description (150-160 characters).
• ✅ Keywords array in front matter.
• ✅ Canonical URL to avoid duplicate content.
• ✅ Alt text for all images.
• ✅ Proper heading hierarchy.
• ✅ Internal linking structure.
• ✅ External links to authoritative sources.
• ✅ Updated lastmod date.
• ✅ Custom summary for search snippets.

Content Types

Hugo supports different content types with custom layouts:

• Posts: Blog articles (this file).
• Pages: Static pages (about, contact).
• Docs: Documentation sections.
• Projects: Portfolio items.
• Custom: Any custom type you define.

Additional Resources

• Hugo Documentation
• Markdown Guide
• Hugo Themes Gallery
• Hugo Community Forum
• CommonMark Specification