Theme Installation

This page shows how to install the Neso theme.
October 11, 2025 Translations: 
Table of Contents

Prepare Hugo

If you already have Hugo installed — and perhaps a site running — feel free to skip to Install the theme below.

If you have not used Hugo yet, the following is a brief walkthrough to get your first Hugo site ready.

Install Hugo

Follow the official installation guide to install Hugo.

Read this first

  1. Before installing Hugo, you must install the prerequisites listed on that page: Git and Go.
  2. Hugo ships in three variants (not operating systems): standard, extended, and extended/deploy. Please install the extended variant.
  3. Hugo offers multiple installation methods. On macOS, it is recommended to use Homebrew. (The author is not familiar with Windows; please consult the official docs.)
  4. The Neso theme requires Hugo v0.150.0 or newer.

After installing Git, Go, and Hugo (extended) in that order, verify in your terminal:

$

hugo version

If you see Hugo’s version information, your environment is good to go.

Create a Hugo site

Run the following commands in your terminal.

Move (cd) to your working directory, then run:

$

hugo new site mysite

This creates a folder named mysite (you can choose any name; we will call it the “Hugo project directory” below) and populates it with the basic files for a site.

Then cd into that directory:

$

cd mysite

Initialize a Git repository in the project directory:

$

git init

At this point, create a .gitignore at the project root. If you are unsure what to include, the following is a good starting point for Hugo projects:

# Hugo
/public/
/resources/_gen/
/assets/jsconfig.json
hugo_stats.json
/.hugo_build.lock

hugo.exe
hugo.darwin
hugo.linux

# Node modules
node_modules/

Prefer a GUI over the terminal for Git?

  1. If you are not comfortable with the terminal, install GitHub Desktop. Then add your working directory (which you already ran git init on) into GitHub Desktop and proceed with a visual workflow.
  2. In GitHub Desktop, confirm the repo from Current Repository at the top left of the window. Then choose Repository → Repository Settings… from the menu; you can edit .gitignore in the left sidebar of the dialog and paste the above rules.
  3. Using GitHub Desktop is fine for Git operations. However, some Hugo tasks still require the terminal.

Your Hugo project directory is now ready to install the theme.

Install the theme

There are multiple ways to install a Hugo theme. Because this theme integrates Tailwind CSS, please install Tailwind via npm first.

Note

The following steps come from Hugo’s official docs. If anything changes, the official docs take precedence.

  1. In your terminal, cd into the Hugo project directory and run:

    $

    npm install --save-dev tailwindcss @tailwindcss/cli

    This installs Tailwind packages inside your project directory.

  2. Open hugo.toml in your Hugo project directory and add the following:

    [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'

    This tells Hugo how to work with Tailwind.

Tailwind is now configured. Next, install the Neso theme itself using one of two methods: Hugo Modules (recommended) or Manual installation.

Install via Hugo Modules (recommended)

This approach keeps your project clean and makes updates easy: Hugo fetches the theme source directly from GitHub so you do not have to manage it yourself.

Important

The Neso theme requires Hugo v0.150.0 or newer.

  1. In your terminal, cd into the Hugo project directory and initialize your project as a Hugo module:

    $

    hugo mod init github.com/<your GitHub username>/<your repo name>

    For example, if your repo name is mysite and your GitHub username is ghuser-blah, you can run:

    $

    hugo mod init github.com/ghuser-blah/mysite

    This step is harmless and serves as preparation. If you prefer not to use your GitHub info yet, you can use any placeholder name (letters/digits, no spaces):

    $

    hugo mod init mysite

  2. Edit hugo.toml in your project directory:

    Under the [module] table you added for Tailwind, add a [[module.imports]] entry with the following path:

      # other settings...
  [[build.cachebusters]]
    source = '(postcss|tailwind)\.config\.js'
    target = 'css'
[module]
  [[module.imports]]
    path = "github.com/babeneso/hugo-neso" # must be this path
  [[module.mounts]]
    source = 'assets'
    # other settings...

  3. Run the following command in your project to fetch the latest theme sources from GitHub:

    $

    hugo mod get -u github.com/babeneso/hugo-neso

    (Use this same command later when you want to update.)

    If you prefer to pin or update to a specific release (example pins to v0.1.3):

    $

    hugo mod get github.com/babeneso/hugo-neso@v0.1.3

  4. It’s a good idea to run the next command to clean up unused entries in go.mod and go.sum:

    $

    hugo mod tidy

  5. Finally start the local server to preview your site:

    $

    hugo server

    If everything is correct, Hugo prints a http://localhost:xxxx/ URL. If you have not published any content yet, you will see an empty page, that means the setup succeeded.

Manual installation

Important

The Neso theme requires Hugo v0.150.0 or newer.

  1. Download the theme ZIP from here and extract it.

    Rename the folder containing the theme source to hugo-neso and place it under themes/ in your project:

    mysite/   <- your Hugo project directory
├── ...
├── themes/
│   └── hugo-neso/    <- the Neso theme
│       ├── assets/
│       ├── i18n/
│       ├── layouts/
│       ├── hugo.toml
│       └── ...
└── ...

  2. Edit the same hugo.toml where you configured Tailwind earlier (☝️ not the one inside hugo-neso/) and add theme = "hugo-neso":

    baseURL = 'https://example.org/'
languageCode = 'en-us'
title = 'My New Hugo Site'
# The above lines are generated by Hugo

# Safer to place it here—putting it lower can cause errors
theme = "hugo-neso"

# Tailwind settings from earlier
[build]
  [build.buildStats]
    enable = true
  [[build.cachebusters]]
    source = 'assets/notwatching/hugo_stats\.json'
    target = 'css'
    # other settings...

  3. Finally start the local server to preview your site:

    $

    hugo server

    If everything is correct, Hugo prints a http://localhost:xxxx/ URL. If you have not published any content yet, you will see an empty page, that means the setup succeeded.