Basic Configuration

This page describes the basic configuration you should prepare after installing the Neso theme.
October 10, 2025 Translations: 
Table of Contents

If your Hugo project is brand new (just created with hugo new site), the initial site config hugo.toml only contains:

baseURL = 'https://example.org/'
languageCode = 'en-us'
title = 'My New Hugo Site'

If your project has been in use for a while, it may already include other custom settings.

In all cases, several settings are required by the Neso theme. Please read the notes below and add or adjust these parameters in your hugo.toml accordingly.

The following settings ensure the theme works correctly (some may have been added during installation).

# General
# --------------------------------

# Required: your site’s base URL
baseURL = "https://example.org/"
# Required: your site’s primary language code
languageCode = "en-us"
# Required: your site title
title = "My New Hugo Site"

# Required: select the theme
# If you installed the theme via Hugo Modules, you may remove this key
theme = "hugo-neso"


# Build
# --------------------------------

[minify]
  # Recommended: minify the generated output to improve page load time
  minifyOutput = true

# Required: Tailwind integration — start
[build]
  [build.buildStats]
    enable = true
  [[build.cachebusters]]
    source = 'assets/notwatching/hugo_stats\.json'
    target = 'css'
  [[build.cachebusters]]
    source = '(postcss|tailwind)\.config\.js'
    target = 'css'
[module]
  [[module.mounts]]
    source = 'assets'
    target = 'assets'
  [[module.mounts]]
    disableWatch = true
    source = 'hugo_stats.json'
    target = 'assets/notwatching/hugo_stats.json'
# Required: Tailwind integration — end
  
  # Required (when installing the theme via Hugo Modules): import the theme
  # If you installed the theme by other means, remove this block
  [[module.imports]]
    path = "github.com/babeneso/hugo-neso"


# Markdown
# --------------------------------

[markup]
  [markup.goldmark]
    [markup.goldmark.parser]
      # Recommended: do not wrap <img> in <p> (the theme provides proper spacing)
      wrapStandAloneImageWithinParagraph = false

      [markup.goldmark.parser.attribute]
        # Required: enable attributes on block elements
        block = true

    [markup.goldmark.renderer]
      # Recommended: allow raw HTML in Markdown
      unsafe = true

  [markup.highlight]
    # Required: use CSS classes for code blocks so syntax highlighting works
    noClasses = false

  # Recommended: table of contents levels
  [markup.tableOfContents]
    startLevel = 2
    endLevel = 3

Other important settings

Below are settings you will encounter as you further customize the theme. You do not need to configure them immediately; this section provides context for when you get there.

Favicon

Place your favicon in the following locations (provide both ICO and SVG):

  • static/favicon.ico (recommended 64×64)
  • assets/favicon.svg

If you use these exact paths and filenames, the icons will take effect immediately and will be automatically injected into the page <head> element.

If you prefer other filenames or locations, that is also fine; see the branding settings.

Outputs

If you plan to provide RSS for readers (Hugo enables it by default; see setting 1 and setting 2), or use the built‑in site search, you need to adjust the following:

# Outputs
# --------------------------------

[outputs]
  home = ["html", "rss", "json"]
  # other outputs...

When configuring your site’s navigation main menu, you will encounter settings like:

# Main menu
# --------------------------------

[menus]
  [[menus.main]]
    identifier = 'posts'
    name       = 'Posts'   # text shown in the menu
    pageRef    = '/posts'  # your content section
    weight     = 10        # smaller appears earlier
  [[menus.main]]
    identifier = 'tags'
    name       = 'Tags'
    pageRef    = '/tags'
    weight     = 20
  # other main menu items...

Other theme options

The Neso theme provides many additional options. They live under the [params.neso] table:

# Parameters
# --------------------------------

[params]
  [params.neso]
  # Neso theme options...