Theme Customization

Thanks to Hugo’s override mechanism, customizing is straightforward and clean. The Neso theme also exposes multiple entry points for your edits. This page walks from simple to advanced ways to customize the theme.
October 9, 2025 Translations: 
Table of Contents

Override CSS Directly

Create an empty file at the following path in your Hugo project (the filename must be exactly custom.css):

assets/css/custom.css

If the directories do not exist, please create them.

Then write your own CSS there. Although this is not always the best approach, it is simple and effective. Neso’s CSS is intentionally written with low specificity so your rules can override it.

You may also follow Tailwind’s recommendation to place styles in appropriate layers and define your own utility classes. If you prefer this method, I have prepared a small cheat sheet you can start from.

Note

Because this theme primarily uses Tailwind utility classes, there may be fewer static class names for you to target in the HTML. I will add reasonable hooks in future updates where appropriate.

Customize Syntax Highlighting

See the instructions here.

Tailwind CSS

Download palette.css from the Neso GitHub repo: palette.css.

Inside that CSS you will find the color variables used by the theme. Customize them according to Tailwind’s guidance on theme customization.

After editing, place the file under your project at: assets/css/palette.css.

If the directories do not exist, please create them.

Insert Custom Snippets

Download any of these four partials from the Neso GitHub repo (link). You do not need all of them – pick what you need:

head_start.html
HTML, CSS, JavaScript, or Go html/template written here will be inserted at the very beginning of the <head> element on every page.
Good for: Google Tag Manager container code; JavaScript that avoids FOUC.
head_end.html
Code here is inserted at the very end of the <head> element on every page.
Good for: custom CSS.
body_start.html
Code here is inserted at the very beginning of the <body> element on every page.
Good for: Google Tag Manager container code.
body_end.html
Code here is inserted at the very end of the <body> element on every page.
Good for: JavaScript.

After editing these files, place them under your project at: layouts/_partials/include/<here>.

If the directories do not exist, please create them.

Tip

The Neso theme ships with a Tailwind CSS pipeline enabled, so you can freely use utility classes inside your HTML templates.

Override Templates (Advanced)

Examine the Neso theme’s directory structure (GitHub repo):

hugo-neso/
├── assets
├── i18n
└── layouts

You should see similar directories (and names) in your own Hugo project. Refer to the Hugo documentation for each directory’s purpose.

In short, you can copy a source file from the theme (download it from the Neso theme’s GitHub repo), make your changes, and place it under the corresponding folder in your own project. During build, Hugo will prefer your version.

Tip

The Neso theme ships with a Tailwind CSS pipeline enabled, so you can freely use utility classes inside your HTML templates.

Warning

If your installation method placed a copy of the theme under themes/ as hugo-neso/, do not modify files inside that copy directly. Use the override approach described above. Otherwise, when the theme updates, you will have to manually track and merge your changes.