Advanced Usage

Discover advanced usage of the Hugo - FixIt theme.

Style Customization

FixIt theme provides a flexible SCSS customization system. Create assets/scss/custom.scss in your project root to customize styles.

The theme exposes SCSS mixins, functions, and CSS custom properties for customization. See the SCSS API Reference for the full API.

Theme Adaptation

You can configure appearance via [params.appearance] in hugo.toml. This is the recommended way to customize colors, fonts, and sizes.

1
2
3
4

[params.appearance]
global_font_size = "16px"
global_font_color = "#1f2328"
global_link_color = "#161209"

All appearance variables are defined in scss-vars.html.

Fonts Style

Customizing fonts requires two steps: import the font CSS, then configure the font family.

To customize the global font, take the open-source font LXGW WenKai as an example:

Import the font in assets/scss/custom.scss, then configure the font family via [params.appearance]:

1

@import url('https://chinese-fonts-cdn.deno.dev/packages/lxgwwenkai/dist/LXGWWenKai-Regular/result.css');

1
2

[params.appearance]
global_font_family = "LXGW WenKai, system-ui, sans-serif"

To customize the code font, take the open-source font Fira Mono as an example:

1

@import url('https://fonts.googleapis.com/css?family=Fira+Mono:400,700&display=swap&subset=latin-ext');

1
2

[params.appearance]
code_font_family = "Fira Mono, Menlo, Consolas, monospace"

If you want to customize a font that does not have a public CDN, you can manually or online split it and publish it to NPM. Take the MMT typeface as an example:

1

@import url('https://cdn.jsdelivr.net/npm/mmt-webfont/dist/result.css');

1
2

[params.appearance]
global_font_family = "MMT, system-ui, sans-serif"

Page Style

The FixIt theme provides built-in page width options via page_style:

• narrow — Narrow page/toc width ratio
• normal — Default page/toc width ratio
• wide — Larger page/toc width ratio

For a custom page width, use the page-style mixin in assets/scss/custom.scss:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

@include page-style('custom') {
  @include media('xl') {
    width: ROUND(70%, 2px);
    max-width: 1600px;
  }
  @include media('lg') {
    width: ROUND(60%, 2px);
  }
  @include media('md') {
    width: ROUND(56%, 2px);
  }
}

Then set page_style = "custom" in your site configuration.

Responsive Media Queries

The FixIt theme provides a media mixin for responsive breakpoints:

Usage in assets/scss/custom.scss:

1
2
3
4
5
6
7
8

.my-element {
  @include media('xl') {
    width: 1200px;
  }
  @include media('sm') {
    width: 100%;
  }
}

Print Style

FixIt theme provides UnoCSS utility classes for print view:

• break-before-page — Insert page break before element
• break-after-page — Insert page break after element
• print:hidden — Hide elements in print view

1
2
3
4
5

<div class="break-before-page"></div>
<div class="break-after-page"></div>
<div class="print:hidden">
  Something you want to hide in the print view is written here.
</div>

If goldmark.parser.attribute.block is set to true:

1
2
3
4
5

{.break-before-page}
{.break-after-page}

Something you want to hide in the print view is written here.
{.print:hidden}

Script Customization

Create assets/js/custom.ts (or custom.js) in your project root. It will be executed at the end of each page.

Access the FixIt public API via window.fixit. See the JavaScript API Reference for the full API.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20

const { fixit } = window as any

class CustomScript {
  constructor() {
    this.init()
  }

  init() {
    console.log('FixIt version:', fixit.version)

    // Listen to theme changes
    fixit.eventBus.on('fixit:switch-theme', ({ detail }: any) => {
      console.log('Theme switched:', detail.mode)
    })
  }
}

document.addEventListener('DOMContentLoaded', () => {
  void new CustomScript()
})

Templates Customization

Hugo allows you to modify the theme by overriding theme templates, for example: you can create layouts/404.html to override themes/FixIt/layouts/404.html.

However, for most templates, FixIt theme generally doesn’t recommend this, as it may make theme upgrades difficult.

To avoid upgrade conflicts, FixIt theme opens a unified custom template entry file and configuration. See Open Custom Blocks.

Custom Admonitions

You can define custom admonitions using the admonition mixin.

First, add the icon in hugo.toml:

1
2

[params.admonition]
ban = "fa-solid fa-ban"

Then add the style in assets/scss/custom.scss:

1
2
3

.admonition {
  @include admonition(ban, #ff3d00, rgba(255, 61, 0, 0.1));
}

To customize the default title, add to the language file:

1
2

[admonition]
ban = "Forbidden"

Then use it in content:

{{< admonition ban >}}
This is a custom admonition type with a ban icon.
{{< /admonition >}}

> [!ban]
> This is a custom admonition type with a ban icon.

Custom Task Lists

You can define custom task lists using the task-icon and task-text mixins.

First, add the icon in hugo.toml:

1
2

[params.taskList]
tip = "fa-regular fa-lightbulb"

To customize the default title:

1
2

[task-list]
tip = "Tip"

Then use it in content:

1

- [tip] This is a custom task list type with a tip icon.

The rendered output:

• This is a custom task list type with a tip icon.

To customize the style, add in assets/scss/custom.scss:

1
2
3
4

li[data-task='tip'] {
  @include task-icon(#EA9E36);
  @include task-text(#9974F7);
}

Above example will change the color of the task list:

• This is a custom task list type with a tip icon.

Import Theme Components

Why do others have certain features on their blogs based on the FixIt theme, but I don’t?

Before this, you might have had similar questions. Actually, it is very likely that they have introduced additional theme components.

Next, taking the component-projects component as an example, we will introduce how to import a theme component. Most components are imported in a similar way.

1. First, install the component

   The installation method is the same as installing the theme. There are several ways to install, choose one, Here are two mainstream ways.

   • Install as a Hugo module

     First, make sure your project itself is a Hugo module.

     Then add this theme component to your hugo.toml configuration file:

     [module]
     
     [[module.imports]]
     path = "github.com/hugo-fixit/FixIt"
     
     [[module.imports]]
     path = "github.com/hugo-fixit/component-projects"

     On the first start of Hugo it will download the required files.

   • Install as a Git submodule

     Clone FixIt and this git repository into your theme folder and add it as a submodule to the site directory.

     git submodule add https://github.com/hugo-fixit/component-projects.git themes/component-projects

     Next edit hugo.toml of your project and add this theme component to your themes:

     theme = [
       "FixIt",
       "component-projects",
     ]

2. Inject Partial

   Theme components usually require some third-party resources, such as CSS or JavaScript. Generally, each component will provide an initialization file in the layouts/_partials directory, such as: inject/component-projects.html.

   Through the custom blocks opened by the FixIt theme, we can easily inject the initialization file of the component through configuration:

   [params]
   
   [params.custom_partials]
   # ... other partials
   assets = [ "inject/component-projects.html" ]
   # ... other partials

3. Theme component import completed, use the component features according to different component documents.

This section does not elaborate on the concept or development of theme components. If you are interested, you can check Contributing - Develop Theme Components.

PWA Support

This part is shown in the pwa support page.