Hugo Configuration Guide (`hugo.toml`)#

A concise reference for the most useful configuration options in Hugo, especially for blog setups and themes like Terminal.

🧭 Basic Site Configuration#

1
2
3
4
5
baseURL = "https://yourusername.github.io/your-repo/"
languageCode = "en-us"
title = "My Blog"
theme = "terminal"
paginate = 5

Options#

baseURL → Full URL of your deployed site
languageCode → Default language
title → Site title
theme → Theme name (folder inside /themes)
paginate → Number of posts per page

🧠 Content Behavior#

1
2
summaryLength = 30
enableRobotsTXT = true

summaryLength → Number of words in summaries
enableRobotsTXT → Auto-generate robots.txt

🗂 URLs & Structure#

1
2
[permalinks]
  posts = "/posts/:year/:month/:title/"

Customize how URLs are generated
Common variables:
- :year
- :month
- :title
- :slug

✍️ Markdown & Code Highlighting#

Check Hugo doc for more details

1
2
3
4
5
6
7
[markup]
  [markup.highlight]
    codeFences = true
    guessSyntax = true
    lineNos = false
    style = "monokai"
    noClasses = false

Highlight options#

codeFences → Enable ``` blocks
guessSyntax → Auto-detect language
lineNos → Show line numbers
style → Color theme
noClasses → Inline styles vs CSS classes

📐 Goldmark (Markdown engine)#

1
2
[markup.goldmark.renderer]
  unsafe = true

Allows raw HTML inside Markdown

🧩 Params (Theme-specific)#

1
2
3
4
5
6
[params]
  contentTypeName = "posts"
  themeColor = "orange"
  showMenuItems = 2
  fullWidthTheme = false
  centerTheme = true

⚠️ These depend on the theme. For Terminal:

contentTypeName → Which folder is treated as posts
themeColor → Accent color
showMenuItems → Items in navbar
fullWidthTheme → Stretch layout
centerTheme → Center content

🌍 Languages & Menus#

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
[languages]
  [languages.en]
    title = "My Blog"

    [languages.en.menu]

      [[languages.en.menu.main]]
        identifier = "about"
        name = "About"
        url = "/about"

      [[languages.en.menu.main]]
        identifier = "posts"
        name = "Posts"
        url = "/posts"

Imaging#

Check Hugo doc

🖼 Static Files#

Hugo automatically maps:

1
/static → /

Example:

1
static/images/test.png

Becomes:

1
/images/test.png

⚡ Performance & Build#

1
2
3
4
5
[minify]
  disableXML = true

[build]
  writeStats = true

minify → Compress output
writeStats → Useful for analyzing assets

🔍 Taxonomies (Tags & Categories)#

1
2
3
[taxonomies]
  tag = "tags"
  category = "categories"

Use in posts:

1
tags: ["physics", "ml"]

📡 Outputs#

1
2
[outputs]
  home = ["HTML", "RSS"]

Enable RSS feeds or JSON output

🧪 Development vs Production#

Local preview:

1
hugo serve

Production build:

1
hugo --minify

🧠 Best Practices#

Always set draft = false before publishing
Use page bundles for posts with images
Avoid hardcoding /your-repo/ in Markdown → use relative paths
Keep baseURL correct for GitHub Pages

🚀 Example Minimal Config#

1
2
3
4
5
6
7
8
9
baseURL = "https://yourusername.github.io/your-repo/"
languageCode = "en-us"
title = "My Blog"
theme = "terminal"

[markup]
  [markup.highlight]
    codeFences = true
    guessSyntax = true

✨ Advanced (Optional)#

1
2
3
[params]
  customCSS = ["css/custom.css"]
  customJS = ["js/custom.js"]

Add custom styles or scripts

🧭 Final Note#

Hugo’s power comes from:

Markdown + configuration
Templates (themes)
Static asset pipeline

Most behavior is controlled either by:

hugo.toml
Theme params
Layout overrides

Happy writing ✨

Hugo Config Guide

Hugo Configuration Guide (hugo.toml)#