💥 Upgrading to FixIt V1

This guide walks you through upgrading from FixIt v0.x to v1.0. The v1 release introduces significant breaking changes to configuration structure, custom assets, and more. Read on to ensure a smooth upgrade.

Prerequisites

Before upgrading, make sure your environment meets the following requirements:

Configuration: camelCase to snake_case

The most impactful change in v1 is that all keys under [params] have been renamed from camelCase to snake_case. Hugo’s own configuration keys (e.g. [menu], [markup], etc.) are not affected.

1
2
3
4

[params]
defaultTheme = "auto"
dateFormat = "2006-01-02"
enablePWA = true

1
2
3

[params]
default_theme = "auto"
date_format = "2006-01-02"

Deprecation Detection

The theme includes a built-in deprecation detection system. When you build your site with old camelCase keys, Hugo will emit warnings like:

1
2

[FixIt] deprecation warnings (v1.0.0):
- params.defaultTheme is deprecated, use params.default_theme instead

These warnings point you directly to the new key names, making migration straightforward.

Common Top-Level Key Renames

Nested Key Renames

Sub-sections also follow the snake_case convention. For example:

1
2
3
4
5
6
7

[params.search]
contentLength = 200
absoluteUrl = true

[params.search.algolia]
appId = "xxx"
searchKey = "xxx"

1
2
3
4
5
6
7

[params.search]
content_length = 200
absolute_url = true

[params.search.algolia]
app_id = "xxx"
search_key = "xxx"

Other commonly affected nested sections:

Config Structure: [params.page] Eliminated

The entire [params.page] section has been flattened into [params]. All page-level parameters that were previously nested under [params.page] now live directly under [params]. They can still be overridden per-page via front matter.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

[params.page]
lightgallery = true
wordCount = true
readingTime = true

[params.page.toc]
enable = true

[params.page.comment]
# ...

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

[params]
lightgallery = true
word_count = true
reading_time = true

[params.toc]
enable = true

[params.comment]
# ...

Page-Level Key Migration

Sub-Sections Moved to [params] Level

linkTo* Consolidated into [params.post_link]

PWA Config Restructured

Other Structural Moves

• params.externalIcon has moved to [params.link] external_icon (now defaults to true)
• [params.link] is now a page-level section (can be overridden per-page via front matter)
• [params.image], [params.codeblock], [params.json_viewer], [params.filetree] are now page-level sections

Custom Styles and Scripts

The custom asset file paths have changed. Legacy paths are no longer loaded automatically.

SCSS Architecture Changes

The SCSS architecture has been restructured into per-layout bundles under assets/scss/:

• assets/scss/core/ — core styles (layouts, maps, mixins)
• assets/scss/pages/ — per-page-type styles
• assets/scss/widgets/ — widget styles

The SCSS function prefix has changed from fixit- to fi-. If you use any theme SCSS functions or mixins in your custom styles, update the references accordingly.

The new custom.scss uses @use instead of @import:

1

@use "core/mixins" as *;

[params.appearance] — Config-Driven Style Customization

The new [params.appearance] section allows you to customize SCSS variables directly in your Hugo config, replacing the old assets/css/_override.scss approach.

1
2
3
4
5

[params.appearance]
global_font_family = "Custom Font, sans-serif"
global_background_color = "#ffffff"
global_background_color_dark = "#1a1a1a"
code_font_family = "Fira Code, monospace"

Each variable supports light and dark mode variants using the _dark suffix. This covers colors, fonts, sizes, and more across the entire theme. See the default hugo.toml for the full list of available variables.

Front Matter Changes

The subtitle, featured_image, featured_image_preview, repost, weight, and message fields are now front-matter-only parameters (no longer configurable in hugo.toml).

Content Encryption

If you use the content encryption feature, the system has been completely rewritten:

• Removed legacy Base64 obfuscation layer
• New standalone package @hugo-fixit/encrypt with AES-256-GCM encryption
• Removed vendored crypto-js and xxhash-wasm dependencies

To use encryption in v1, add the encrypt command to your build pipeline:

1

npx @hugo-fixit/encrypt

Layout Partials Path Change

If you reference theme partials in custom code, update the paths:

For example, layouts/_partials/layouts/header.html is now layouts/_partials/base/header.html.

Hugo Config Updates

• languageCode in site config is deprecated; use locale instead (Hugo v0.158.0+)
• .Language.LanguageName is deprecated; use .Language.Label (Hugo v0.158.0+)
• [params.dev].debug has been removed; debug mode is now auto-detected from the Hugo environment

Quick Upgrade Checklist

• Update Hugo to >= 0.161.0 (Extended)
• Install Dart Sass >= 1.99.0
• Update FixIt theme and related theme components to the latest version
• Rename all camelCase config keys to snake_case
• Flatten [params.page] — move all keys and sub-sections up to [params]
• Consolidate linkTo* params into [params.post_link]
• Move enablePWA to [params.app].pwa and restructure [params.app]
• Move externalIcon to [params.link].external_icon
• Move assets/css/_custom.scss to assets/scss/custom.scss
• Replace assets/css/_override.scss with [params.appearance] config
• Move assets/css/_variables.scss to assets/scss/_variables.scss
• Move assets/js/_custom.js to assets/js/custom.ts or assets/js/custom.js
• Update front matter: link_guard to link.guard
• Update custom partials paths from layouts/_partials/layouts/ to layouts/_partials/base/
• If using encryption: add npx @hugo-fixit/encrypt to your build pipeline
• Update languageCode to locale in language config

If you run into issues during the upgrade, feel free to ask for help in the GitHub Discussions.