How to Add a New Template File to the Omarchy Theming System

Adding a new template file to the Omarchy theming system requires creating a *.tpl file in default/themed/ with Jinja-style placeholders, then running the omarchy-theme-set-templates command to render the output into your ~/.config/ directory.

Omarchy, maintained by omacom, is an open-source Linux configuration framework that manages application theming through a declarative template architecture. When adding a new template file to the Omarchy theming system, you insert variable placeholders—such as {{ accent }} or {{ background }}—that automatically populate with values from your active theme’s colors.toml, ensuring consistent color propagation across all supported applications.

Understanding the Omarchy Template Architecture

Omarchy stores source templates in the default/themed/ directory of the repository. Each file uses the .tpl extension and contains plain text configuration mixed with variable placeholders. These placeholders map directly to keys defined in the active theme’s colors.toml file, located at themes/<theme_name>/colors.toml.

The rendering logic resides in bin/omarchy-theme-set-templates. This script reads the active theme variables, substitutes all placeholders using Jinja-style syntax, and writes the final, concrete configuration files into your user’s ~/.config/ directory while preserving the original subdirectory layout. This separation of template source and rendered output allows dynamic theme switching without manually editing static configuration files.

Creating a New Template File

To add support for a new application, create a .tpl file containing the target program’s standard configuration syntax with Omarchy placeholder variables.

First, navigate to the template source directory:

cd "$OMARCHY_PATH/default/themed"

Create a new template with appropriate placeholders. For example, to template a configuration file for a hypothetical application named myapp, create myapp.conf.tpl:

cat > myapp.conf.tpl <<'EOF'

# MyApp configuration generated from the active Omarchy theme

background = "{{ background }}"
foreground = "{{ foreground }}"
accent     = "{{ accent }}"
EOF

Standard placeholders like {{ background }}, {{ foreground }}, and {{ accent }} are universally available across Omarchy themes, though you can reference any custom key defined in the theme’s colors.toml. Existing templates such as default/themed/hyprland.lua.tpl and default/themed/alacritty.toml.tpl demonstrate advanced usage of nested placeholders and conditional logic.

Rendering and Deploying Templates

After creating or modifying a template, execute the rendering command to generate the actual configuration files in ~/.config/:

omarchy-theme-set-templates

This command processes every .tpl file in default/themed/, substitutes variables from the active theme’s colors.toml, and mirrors the directory structure in your configuration folder. Omarchy triggers this rendering automatically when switching themes, but manual execution is required after adding new template files to ensure immediate deployment.

To render a specific template rather than the entire set, use the --only flag followed by the target base filename:

omarchy-theme-set-templates --only hyprland.lua

Key Files in the Omarchy Theming System

Reference these source files when extending the theming system according to the omacom/omarchy codebase:

• default/themed/ – The root directory containing all *.tpl source files
• default/themed/hyprland.lua.tpl – A fully-featured example demonstrating complex placeholder usage for window manager configuration
• default/themed/alacritty.toml.tpl – Shows terminal emulator templating with color variable substitution
• bin/omarchy-theme-set-templates – The CLI entry point that orchestrates template rendering and deployment
• docs/theming.md – Official documentation covering the template workflow and variable naming conventions
• themes/<theme_name>/colors.toml – The source of truth for all color values consumed by templates during rendering

Summary

• Place new templates in default/themed/ using the *.tpl extension so Omarchy recognizes them as theme sources during the rendering cycle
• Use Jinja-style syntax ({{ variable }}) to mark values that should be substituted from the active theme’s colors.toml
• Run omarchy-theme-set-templates to render all templates and write them to ~/.config/ whenever you add or modify template files
• Use the --only flag to render a specific template by name when you want to avoid regenerating the entire configuration directory
• Reference existing templates like hyprland.lua.tpl for implementation patterns and standard placeholder naming conventions

Frequently Asked Questions

Where should I place new template files in the Omarchy repository?

Place new template files in the default/themed/ directory at the root of the repository. According to the omacom/omarchy source code, the omarchy-theme-set-templates command recursively scans this location for *.tpl files during the rendering process.

What placeholder syntax does Omarchy use for theme variables?

Omarchy uses double curly brace syntax ({{ variable_name }}) for placeholders, compatible with Jinja2-style templating. Variables reference keys defined in your active theme’s colors.toml file, such as {{ background }}, {{ foreground }}, or {{ accent }}.

How do I apply theme changes after editing a template file?

Run the omarchy-theme-set-templates command located at bin/omarchy-theme-set-templates to immediately render all templates and deploy them to ~/.config/. This command is automatically invoked when switching themes via Omarchy's theme management utilities, but must be run manually after adding new template files.

Can I render only a specific template instead of regenerating everything?

Yes. Pass the --only flag followed by the base filename (without the .tpl extension) to omarchy-theme-set-templates to process a single template. For example, omarchy-theme-set-templates --only hyprland.lua renders only the Hyprland configuration while leaving other files untouched.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}