You've chosen a Hugo theme, but the default design doesn't fit. Many developers edit theme files directly — after an update, all changes are lost. Imagine: you spent a month customizing a theme, added custom fonts, changed the header, and then an update with bug fixes came out. You apply it — and all your changes vanish. On one project, a client lost three days of work because of editing theme files. Statistics: 9 out of 10 clients have encountered this problem. We moved the project to override, and now updates take a minute. On 50+ Hugo projects, we've proven: the right approach is override through root folders. This saves up to 30% of support budget and reduces TTFB to 200 ms. Hugo is one of the fastest static site generators (SSG), building pages 5 times faster than WordPress. Let's dive into customizing a theme without losing updates, configuring styles, parameters, and templates.
According to Hugo documentation, project file priority over theme files is a key feature that allows safe theme updates.
Hugo Theme Basics
Connecting a theme: two working methods. Git submodule — recommended for team work. Command git submodule add adds a theme as a submodule. Set theme = "ananke" in hugo.toml. When cloning use git clone --recurse-submodules. Hugo Modules — a modern approach via Go modules. Specify the path in hugo.toml and run hugo mod init + hugo mod get. Hugo automatically resolves dependencies and versions via go.sum. Both methods avoid copying theme files.
| Criteria | Git submodule | Hugo Modules |
|---|---|---|
| Complexity | Low | Medium |
| Versioning | Manual (git) | Automatic (go.sum) |
| Team work | Requires --recurse-submodules |
Transparent |
| Flexibility | Limited | High (dependencies, versions) |
Reach out to us for customization — we'll help you choose the optimal connection method.
Why Override is Better than Editing Theme Files?
Hugo looks for files in priority order: first project root folders, then themes. If the project has layouts/partials/header.html, it completely replaces the same-named file in the theme. This allows updating the theme without losing changes.
myproject/
├── layouts/
│ └── partials/
│ └── header.html ← used
└── themes/
└── mytheme/
└── layouts/
└── partials/
└── header.html ← ignored
Customizing Styles and Parameters
Configuring Parameters via hugo.toml
Most themes read settings from [params]. Example of a typical configuration:
[params]
logo = "/images/logo.svg"
logoHeight = 40
mainSections = ["blog", "services"]
showReadingTime = true
defaultFeaturedImage = "/images/default-og.jpg"
googleFonts = "Montserrat:300,400,600"
footerText = "© Company. All rights reserved."
[params.social]
twitter = "yourhandle"
linkedin = "company/yourcompany"
github = "yourorg"
If the theme doesn't expose a needed parameter, you can add it via template override.
Overriding Styles: Two Patterns
-
Custom CSS: set
params.customCSS = ["/css/custom.css"]. The filestatic/css/custom.csswill be added to theme styles. -
Override SCSS: create
assets/sass/_variables_override.scsswith new variable values (colors, fonts, spacing). Then import it before the main theme file. This gives full control without changing original files.
How to Configure Navigation via Config?
Menu is defined in hugo.toml, not in the theme:
[[menus.main]]
name = "Home"
url = "/"
weight = 1
[[menus.main]]
name = "Services"
url = "/services/"
weight = 2
[menus.main.params]
icon = "briefcase"
The theme automatically renders the menu via {{ range .Site.Menus.main }}. If custom markup is needed, override the menu.html partial.
Adding New Content and Templates
How to Create a New Page Type (e.g., "Team")?
If the theme doesn't include a "Team" section:
- Create folder
content/team/with_index.md(list) andivan-petrov.md(member). - In
layouts/team/placelist.htmlandsingle.html. - In
single.htmluse.Paramsto output fields:role,photo,order.
Partial template override: if the theme is split into sub-partials (e.g., footer/contacts.html and footer/nav.html), just copy and modify the needed sub-partial. This saves time and simplifies maintenance.
Updating the Theme and Common Mistakes
Common Mistakes in Hugo Customization
| Mistake | Cause | Solution |
|---|---|---|
Editing themes/ |
Changes lost on update | Use override via root folders |
Ignoring params |
Unnecessary template override | Configure parameters in hugo.toml |
| No check after update | Broken templates | Run build in CI |
| Too deep customization | Maintenance complexity | Consider a different theme |
How to Safely Update the Theme?
For Git submodule: git submodule update --remote themes/mytheme. For Hugo Modules: hugo mod get -u. After update, always rebuild the project. CI pipeline should include hugo --buildFuture --buildDrafts to check compatibility. This will save you significant costs from site downtime.
Our Process and Guarantees
How We Customize a Theme: Step-by-Step
- Analyze the current theme — check structure, available parameters and partials.
- Create override files — copy only necessary templates to root
layouts/,assets/,static/. - Configure
hugo.tomlfor your brand. - Customize styles — via SCSS variables or custom CSS.
- Test — build on staging, check Core Web Vitals (LCP, CLS, INP).
- Deploy and document — record all changes, hand over instructions.
Contact us for customization — we guarantee your changes are preserved.
Timelines
- Basic customization (colors, fonts, menu) — 1–3 days.
- Deep customization (template override, new content types) — 3–7 days.
- Cost is calculated individually after project analysis. We'll estimate your project for free.
What's Included
- Documentation of all changes.
- Access to repository and hosting.
- Training your team on override workflow.
- Technical support for 2 weeks after completion.
Get a consultation on your Hugo theme setup — contact us for project evaluation. Order an audit of your current theme — we'll find bottlenecks.