Skip to content
Noctalia Noctalia Docs

Create a Matugen template

This guide walks you through adding a new Matugen template to Noctalia.

Overview

Section titled “Overview”

Adding a new template is straightforward once you know the flow.
You’ll go through five steps:

  1. Create the template file
  2. Add a settings toggle
  3. Wire the template into the config generator
  4. Show the toggle only if the program exists
  5. Add the UI toggle

Let’s break it down step by step.

Step 1: Create the Template File

Section titled “Step 1: Create the Template File”

First, create your template file in the Matugen templates directory.
For example, if you’re making one for kitty, create:

Assets/Matugen/templates/kitty.conf

# Generated by Matugen via Noctalia
color0 {{colors.surface.default.hex}}
color1 {{colors.error.default.hex}}
color2 {{colors.tertiary.default.hex}}
color3 {{colors.secondary.default.hex}}
color4 {{colors.primary.default.hex}}
color5 {{colors.primary.default.hex}}
color6 {{colors.secondary.default.hex}}
color7 {{colors.on_background.default.hex}}
color8 {{colors.outline.default.hex}}
color9 {{colors.secondary_fixed_dim.default.hex}}
color10 {{colors.tertiary_container.default.hex}}
color11 {{colors.surface_container.default.hex}}
color12 {{colors.primary_container.default.hex}}
color13 {{colors.on_primary_container.default.hex}}
color14 {{colors.surface_variant.default.hex}}
color15 {{colors.on_background.default.hex}}


cursor {{colors.primary.default.hex}}
cursor_text_color {{colors.on_surface.default.hex}}


foreground            {{colors.on_surface.default.hex}}
background            {{colors.surface.default.hex}}
selection_foreground  {{colors.on_secondary.default.hex}}
selection_background  {{colors.secondary_fixed_dim.default.hex}}
url_color             {{colors.primary.default.hex}}

Matugen uses template variables to map Material Design 3 colors to different app formats.
You can find all the available variables and their Material 3 mappings in the Matugen wiki.

Step 2: Add a Settings Toggle

Section titled “Step 2: Add a Settings Toggle”

Next, create a setting to control whether this template is generated.
Open Commons/Settings.qml, find the matugen JsonObject, and add a new property:

property JsonObject matugen: JsonObject {
    // ... existing properties ...
    property bool kitty: false
}

This adds a persistent toggle that defaults to false.

Step 3: Wire It Into the Config Generator

Section titled “Step 3: Wire It Into the Config Generator”

Now tell Matugen when to use the new template.
Open Assets/Matugen/Matugen.qml and find the buildConfigToml() function.
Add your template config alongside the existing ones:

if (Settings.data.matugen.kitty) {
    lines.push("\n[templates.kitty]")
    lines.push('input_path = "' + Quickshell.shellDir + '/Assets/Matugen/templates/kitty.conf"')
    lines.push('output_path = "~/.config/kitty/noctalia.conf"')
    // Optional: Enable hot-reload (this depends on the program)
    // lines.push("post_hook = 'kitty +kitten themes --reload-in=all noctalia'")
}

That last line (commented out) is optional but handy - it tells Matugen to do something after generating the colors.

Step 4: Show the Toggle Only if the Program Exists

Section titled “Step 4: Show the Toggle Only if the Program Exists”

We don’t want to display the toggle if kitty isn’t installed.
Open Services/ProgramCheckerService.qml and:

  1. Add a property to track availability:
property bool kittyAvailable: false
  1. Add an entry to the programsToCheck object:
programsToCheck: {
    // ... existing entries ...
    "kittyAvailable": ["which", "kitty"],
}

This automatically updates kittyAvailable when the program is detected.

Step 5: Add the UI Toggle

Section titled “Step 5: Add the UI Toggle”

Finally, add the toggle to the settings panel.
Open Modules/SettingsPanel/Tabs/ColorSchemeTab.qml, find the “Terminal” section (or make one), and insert:

NCheckbox {
    label: "kitty"
    description: ProgramCheckerService.kittyAvailable
        ? "Write ~/.config/kitty/colors-noctalia.yml and reload"
        : "Requires kitty to be installed"
    checked: Settings.data.matugen.kitty
    enabled: ProgramCheckerService.kittyAvailable
    opacity: ProgramCheckerService.kittyAvailable ? 1.0 : 0.6
    onToggled: checked => {
        if (ProgramCheckerService.kittyAvailable) {
            Settings.data.matugen.kitty = checked
            if (Settings.data.colorSchemes.useWallpaperColors)
                MatugenService.generateFromWallpaper()
        }
    }
}

This checkbox:

  • Shows a helpful description based on whether kitty is installed
  • Disables itself automatically if the program isn’t available
  • Regenerates colors right away when toggled (if wallpaper colors are enabled)