Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/zirconium-dev/zirconium/llms.txt

Use this file to discover all available pages before exploring further.

​
Overview

Zirconium provides extensive customization options while maintaining a consistent and polished experience. The system uses chezmoi to manage dotfiles, matugen for color scheme generation, and various tools for theming and appearance.

​
Dotfiles with zdots

Zirconium uses zdots - a curated collection of dotfiles managed by chezmoi.

​
How zdots works

1

System installation

zdots are cloned to /usr/share/zirconium/zdots during the image build:
git clone "https://github.com/zirconium-dev/zdots.git" /usr/share/zirconium/zdots
2

First login

On your first graphical login, chezmoi-init.service applies the default configuration:
chezmoi apply -S /usr/share/zirconium/zdots \
  --config ~/.config/zirconium/chezmoi/chezmoi.toml
3

Automatic updates

The chezmoi-update.timer periodically syncs your dotfiles with zdots, prompting to skip conflicts.

​
What zdots manages

zdots provides configuration for:
  • Niri: Window manager configuration (~/.config/niri/)
  • DankMaterialShell: UI shell and panels (~/.config/DankMaterialShell/)
  • Shell: bash, fish, and other shell configurations
  • Terminal: foot terminal emulator settings
  • Color schemes: Generated by matugen
  • Application settings: Various application defaults

​
Chezmoi configuration

User config location: ~/.config/zirconium/chezmoi/chezmoi.toml System source: /usr/share/zirconium/zdots
The justfile defines zdots path as:
zdots_path := "/usr/share/zirconium/zdots"

​
OS update behavior with dotfiles

Understanding how Zirconium handles dotfiles during updates is crucial for maintaining your customizations.

​
Automatic update behavior

By default, Zirconium automatically updates your dotfiles:
1

On OS update

When you update Zirconium (rpm-ostree upgrade or bootc upgrade), the zdots in /usr/share/zirconium/zdots are updated to the latest version.
2

On next login

The chezmoi-update.timer runs and attempts to apply the new zdots configuration.
3

Conflict handling

If you’ve modified configuration files, chezmoi will prompt:
yes s | chezmoi apply --no-tty --keep-going -S /usr/share/zirconium/zdots --verbose
The yes s automatically skips conflicts, preserving your changes.
While yes s skips conflicting files, you may miss important upstream improvements. Review changes periodically.

​
Managing dotfile updates

You have several options for controlling dotfile updates:

​
1. Accept all updates (default)

Let zdots manage everything automatically: 
# This is the default behavior
systemctl --user is-enabled chezmoi-update.timer

​
2. Disable automatic updates

Maintain full control over your dotfiles: 
# Disable automatic dotfile updates
zjust toggle-automatic-dotfiles

# Or manually
systemctl --user disable --now chezmoi-update.timer
systemctl --user mask chezmoi-update.timer
systemctl --user disable chezmoi-init.service
systemctl --user mask chezmoi-init.service
When disabled, your dotfiles remain frozen at their current state. You can manually update when ready.

​
3. Manual selective updates

Update dotfiles on your own schedule: 
# Update all dotfiles (with conflict prompts)
zjust zdots-update

# Reset specific file to zdots default
zjust zdots-reset ~/.config/niri/config.kdl

# Reset everything (requires confirmation)
zjust zdots-override-all

​
Chezmoi systemd services

# /usr/lib/systemd/user/chezmoi-init.service
[Unit]
Description=Initializes Chezmoi if directory is missing
ConditionPathExists=!%h/.config/zirconium/chezmoi

[Service]
ExecStart=mkdir -p %h/.config/zirconium/chezmoi
ExecStart=touch %h/.config/zirconium/chezmoi/chezmoi.toml
ExecStart=chezmoi apply -S /usr/share/zirconium/zdots --config %h/.config/zirconium/chezmoi/chezmoi.toml
Type=oneshot

[Install]
WantedBy=graphical-session-pre.target

​
Theming and appearance

Zirconium provides comprehensive theming through multiple coordinated systems.

​
Color scheme generation with matugen

matugen generates Material Design 3 color schemes from wallpapers or colors. Installed from: zirconium/packages COPR repository matugen creates:
  • DMS color schemes (~/.cache/DankMaterialShell/dms-colors.json)
  • GTK/Qt theme colors
  • Terminal color schemes
  • Coordinated system-wide palette

​
Setting accent colors

Change your system accent color: 
# Interactive color picker
zjust set-accent-color
# Options: blue, teal, green, yellow, orange, red, pink, purple, slate

# Or set directly
gsettings set org.gnome.desktop.interface accent-color "teal"
Accent color changes automatically update DMS theme and panel colors.

​
Qt theming

Zirconium uses qt6ct for Qt application theming: 
# /etc/profile.d/zirconium-qt-override.sh
export QT_QPA_PLATFORMTHEME=qt6ct
Installed Qt components:
  • qt6ct - Qt6 Configuration Tool
  • plasma-breeze - Breeze theme for Qt
  • kf6-qqc2-desktop-style - QtQuickControls2 desktop style
  • kf6-kirigami - Kirigami UI framework

​
Fonts

Zirconium includes carefully selected fonts:
  • Maple fonts: Installed from Terra repository
  • Noto Emoji: Google Noto Color Emoji fonts
  • System fonts: default-fonts and default-fonts-core-emoji

​
Font rendering

Optimized font rendering settings: 
# /etc/profile.d/zirconium-font-settings.sh
export FREETYPE_PROPERTIES="cff:no-stem-darkening=0 autofitter:no-stem-darkening=0"
Font cache is regenerated during build: 
fc-cache --force --really-force --system-only --verbose

​
Wallpapers

Default wallpapers are provided in: 
/usr/share/zirconium/skel/Pictures/Wallpapers/
These are installed during the image build from /ctx/assets/wallpapers/.

​
Additional customization tools

Zirconium includes several tools for advanced customization:

​
chezmoi

Powerful dotfile manager with templating support. 
# View managed files
chezmoi managed

# Check for differences
chezmoi diff

# Apply specific source
chezmoi apply -S /usr/share/zirconium/zdots

# Edit a file with chezmoi
chezmoi edit ~/.config/niri/config.kdl
You can use chezmoi’s templating to create conditional configurations:
# In your zdots fork, use templates like:
{{ if eq .hostname "laptop" }}
# Laptop-specific config
{{ else }}
# Desktop config
{{ end }}

​
fastfetch and hyfetch

System information display tools: 
# Display system info
fastfetch

# Display with pride flags
hyfetch
Configuration: /usr/share/zirconium/fastfetch.jsonc

​
just (zjust)

Task runner for common Zirconium operations: 
# Interactive menu
zjust
# Equivalent to: zjust --choose

# List all available recipes
zjust --list
Justfile location: /usr/share/zirconium/just/00-start.just Includes Universal Blue recipes: 
import "/usr/share/ublue-os/just/update.just"
import "/usr/share/ublue-os/just/shared.just"
import "/usr/share/ublue-os/just/default.just"

​
MOTD (Message of the Day)

Custom MOTD is displayed on login: 
# Toggle MOTD display
zjust toggle-user-motd

# Manual display
zmotd
Scripts:
  • /usr/bin/zmotd - MOTD generator
  • /usr/bin/zfetch - System info for MOTD
  • /usr/bin/glorpfetch - Alternative fetch tool

​
Advanced customization

​
Forking zdots

For deep customization, fork the zdots repository:
1

Fork zdots

Fork zirconium-dev/zdots on GitHub.
2

Clone your fork

git clone https://github.com/YOUR_USERNAME/zdots ~/my-zdots
3

Point chezmoi to your fork

chezmoi init --apply --source ~/my-zdots
4

Disable automatic updates

zjust toggle-automatic-dotfiles
5

Make changes

Edit files in ~/my-zdots and apply:
chezmoi apply

​
Creating a custom image

For the ultimate customization, build your own Zirconium variant:
  1. Fork the zirconium repository
  2. Modify build scripts in build_files/
  3. Customize system files in system_files/
  4. Build and host your custom image
  5. Rebase to your custom image: 
    sudo bootc switch ghcr.io/YOUR_USERNAME/zirconium:latest

​
Customization reference

​
Key files and directories

PathPurpose
/usr/share/zirconium/zdots/System zdots source
~/.config/zirconium/chezmoi/User chezmoi config
~/.config/niri/Niri window manager config
~/.config/DankMaterialShell/DMS shell config
/usr/share/zirconium/just/Justfile recipes
/etc/profile.d/System environment variables

​
Common customization tasks

Edit shell configuration in zdots:
  • bash: ~/.bashrc (sources /usr/share/zirconium/shell/pure.bash)
  • fish: ~/.config/fish/config.fish
Or disable zdots updates and edit directly.
Edit DMS settings:
$EDITOR ~/.config/DankMaterialShell/settings.json
systemctl restart --user dms.service
Edit Niri config:
$EDITOR ~/.config/niri/config.kdl
niri msg action reload-config

# User fonts
mkdir -p ~/.local/share/fonts
cp your-font.ttf ~/.local/share/fonts/
fc-cache -f -v

​
Next steps

Niri configuration

Deep dive into Niri window manager

DMS configuration

Customize DankMaterialShell components

Build docs developers (and LLMs) love

Get started for freeTalk to us