Theme Engine for Obsidian

Customize Obsidian without touching CSS. Profiles, backgrounds, snippets, and themes - all from one place.

Theme Engine lets you customize 100+ Obsidian variables (plus your own custom ones) through a polished UI. Manage profiles, snippets, and even video backgrounds - no CSS knowledge required - yet powerful enough for advanced users.

Overview
Why Theme Engine?
Features
Screenshots / Demos
Included Profiles
Supported Languages
Usage Guide
Commands & Hotkeys
Tips & Performance
Variable Reference
Installation (End User)
Building from Source (Developer)
Project Structure
Contributing
Roadmap
Changelog (Summary)
Troubleshooting / FAQ
License
Trademark & Branding
Contact / Links

Overview

Theme Engine is an Obsidian plugin that allows you to edit and manage a large set of Obsidian’s core CSS color variables using an interactive UI. Create theme profiles (bundles of colors, snippets, notice rules, and settings), switch between them instantly, export/share them as JSON, or even import CSS from your installed themes to create new, editable profiles.

Designed for both:

Beginners - Simple color pickers, preset profiles, and a "Set Background" feature to get a polished look fast.
Power users / Developers - Full variable list, per-profile & global snippets, drag-and-drop reordering, regex notice rules, and exportable JSON.

Why Theme Engine?

Dynamic Theme Engine: Theme Engine acts as a smart layer on top of your existing theme. It dynamically captures your active theme's colors, allowing you to override only what you need.
Centralize Control: Unify theme tweaks into Profiles (collections of variables + snippets + backgrounds).
No More CSS Sprawl: Keep small CSS hacks tied to specific profiles instead of managing dozens of separate .css files.
Shareable Themes: Create shareable theme packages (profiles export to a single .json file).
Automate Your Workspace:
- Force Dark/Light mode automatically per profile.
- Apply custom video or image backgrounds per profile.
Intelligent & Dynamic:
- Style notice boxes by content (keyword / regex / keyword highlighting).
- Get warned if an external theme might be interfering with your profile.
Performance Tuned: Use the Live Preview FPS slider to balance visual feedback with CPU usage on your machine.

Features

1. Core Profile Management

Live Color Editor: An intuitive UI with color pickers and text inputs for over 100 core Obsidian color variables. It now provides instant visual feedback: variables matching your theme's default are dimmed (Pristine), while your customizations light up (Modified).
Full Profile Management: Create, delete, rename, and switch between multiple color profiles.
Import / Export:
- Export to JSON: Save your complete profile (colors, snippets, rules, background path) to a single .json file.
- Import from JSON: Import a profile JSON. The UI lets you choose a new name, preventing accidental overwrites.
Beautiful Default Themes: Comes with 3 stunning, ready-to-use profiles to get you started.

2. Advanced Customization

Per-Profile Backgrounds (Image & Video!):
- Set a custom image or video background for each profile.
- Built-in Background Browser to manage all your media: select, rename, and safely delete.
- Easily add new media via file upload, drag & drop, or pasting a URL.
- Automatically applies necessary transparency to UI elements for you.
- Dedicated settings for video (opacity, mute) and images (JPG conversion/quality).
Import from Installed Themes:
- Instantly create a new, editable CSS-based profile by importing the code from your already-installed community themes or snippets.
Advanced Notice Coloring:
- Control the background and text color of pop-up notices based on their content (keywords or Regex).
- New: "Highlight Only" mode to apply color only to specific keywords within a notice.
- Rules are saved per-profile and are included in exports.
CSS Snippets (Profile & Global):
- Per-Profile Snippets: Attach CSS snippets that are only active when their profile is active. Included in exports.
- Global Snippets: Create snippets that stay active across all of your profiles, perfect for a custom font or a small, universal UI tweak.
- Drag & Drop: Easily reorder your snippets with drag & drop to manage CSS priority (cascade).
- Lock Reordering: A lock button to prevent accidental reordering of snippets.

3. Workflow & UI

Complete i18n Overhaul (Translation System):
- Custom Languages Support: No longer limited to the 4 built-in languages. Add any language (e.g., Chinese, Spanish) directly from the settings.
- Tree-View Translation Editor: A powerful modal to edit translations in a nested tree, with deep search and highlighting.
- Management Tools: Import, Export, Copy, and Paste translations as JSON.
- Smart Fallback Engine: Gracefully falls back to English for any missing keys.
Quick Theme Toggle: Instantly cycle the active profile's theme setting between "Force Light," "Force Dark," and "Auto" with a new icon in the profile manager.
Ribbon Icon: Access the Theme Engine settings with a single click from the Obsidian ribbon.
Selective Data Reset: The "Reset Plugin" feature is now granular. You can choose to delete only specific categories of data (Profiles, Snippets, Backgrounds, Settings, or Languages).
Theme Interference Warning: A small icon appears if you have a community theme enabled, warning you that it might override your Theme Engine settings.
Add Custom CSS Variables:
- Add any CSS variable (e.g., from another plugin) to the UI.
- Define its type (color, size, text, number) for the correct UI controls.
- Custom variables are saved and exported with your profile.
Reliable Profile Snapshots: Use the Pin button to save a complete snapshot of your profile (colors, CSS, snippets, rules). Experiment freely and restore with one click.
Multi-Step Color Undo: The "Undo" icon (reset) remembers the last 5 changes you made to each specific color.
Plugin Integrations: Full color control for the Iconize plugin, with an automated cleanup system.

Screenshots / Demos

Default Themes

OLED Matrix (Dark)	Citrus Zest (Light)

Included Profiles

The plugin comes with these hand-crafted profiles by default:

Default: A dynamic profile that acts as a transparent layer, automatically capturing and adopting the colors of your currently active Obsidian theme.
OLED Matrix: A true-black, high-contrast theme with vibrant green accents.
Citrus Zest: A brilliant light theme with a clean design and stunning orange highlights.

Supported Languages

Theme Engine has a powerful, extensible translation system. It includes full support for 4 built-in languages and allows you to add your own Custom Languages via the settings menu.

Built-in Languages:

English (Default)
العربية (Arabic) - Full RTL Support
Français (French)
فارسی (Persian) - Full RTL Support

Usage Guide

Need help getting started?

See the complete usage guide:

Open Usage Guide →

Includes:

Creating profiles
Importing & exporting
Background setup
CSS snippets
Notice rules
Hotkeys

Commands & Hotkeys

Theme Engine includes built-in commands for:

Profile switching
Theme cycling
Settings access

View Full Command List →

Tips & Performance

Want better responsiveness and smoother behavior?

See the complete performance guide:

Open Tips & Performance Guide →

Includes:

Live Preview optimization
Background performance recommendations
Community theme conflict advice
Suggested workflows
Stability troubleshooting

Variable Reference

Theme Engine exposes more than 100+ core Obsidian variables covering:

Backgrounds
Text & Typography
Navigation
Links
Code Blocks
Tables
Callouts
Interactive Elements
Graph View
Canvas
Tabs
Scrollbars
Plugin integrations
Custom variables

[!TIP]

View the complete variable documentation here:

Variable Reference →

Installation (End User)

[!IMPORTANT] Requires Obsidian v1.11.0 or higher. Please ensure your Obsidian app is updated before installing.

Download the latest release from the GitHub Releases page.
Extract the plugin folder into your vault's plugins folder: <YourVault>/.obsidian/plugins/.
In Obsidian, go to Settings -> Community plugins.
Enable the "Theme Engine" plugin.
Open the plugin settings to start customizing!

Building from Source (Developer)

If you want to customize the plugin or contribute to its development, you can easily build it from the source code.

Clone the Repository:

git clone https://github.com/YazanAmmar/obsidian-theme-engine.git
cd obsidian-theme-engine

Install Dependencies:

Make sure you have Node.js installed. Then, run the following command.
```
npm install
```
Build the Plugin: To compile the TypeScript code and package the plugin for Obsidian:
- Standard Build: Use npm run build to compile the core files (main.js, styles.css, manifest.json) into the project root.
```
npm run build
```
- Lint the Code: Run the ESLint script to check for code style issues.
```
npm run lint
```
- Development Build (Advanced): Use npm run dev to compile AND automatically copy the resulting files to a local Obsidian vault.
```
npm run dev
```

[!NOTE]

The npm run dev command is configured to automatically copy the built files to a local Obsidian vault for testing.

You must edit the vaultDir variable inside the esbuild.config.mjs file to point to your local vault's plugin folder (<YourVault>/.obsidian/plugins/obsidian-theme-engine) before running this command.

Load into Obsidian: The compiled files (main.js, styles.css, manifest.json) will be in the project's root. Copy these files into your vault's plugin folder:
```
<YourVault>/.obsidian/plugins/obsidian-theme-engine/
```

Project Structure

The codebase is organized by concern: plugin core, UI, modal system, i18n, and SCSS layers.

src/
|- main.ts                  # Plugin entrypoint and lifecycle orchestration
|- constants.ts             # Built-in defaults, maps, and static config
|- types.ts                 # Shared TypeScript domain types
|- utils.ts                 # Cross-cutting utility helpers
|
|- commands/
|  |- index.ts              # Command registration and command handlers
|
|- i18n/
|  |- strings.ts            # Translation engine + fallback behavior
|  |- types.ts              # i18n-specific typings
|  |- locales/              # Built-in locales + custom locale files
|     |- en.ts
|     |- ar.ts
|     |- fr.ts
|     |- fa.ts
|
|- styles/
|  |- main.scss             # Root SCSS entry (compiled to styles.css)
|  |- base/                 # Core tokens, animation, layout direction, editor styles
|  |- components/           # Shared component-level styles
|  |- modals/               # Styles scoped to modal experiences
|  |- settings/             # Settings tab layout, controls, search, accessibility
|
|- ui/
   |- settingsTab.ts        # Main settings screen composition
   |- components/           # Reusable settings UI sections/widgets
   |- modals/               # Modal architecture split by feature domain
      |- index.ts           # Central modal exports
      |- base.ts            # Shared modal base class/infrastructure
      |- info.ts            # Informational modal(s)
      |- common/            # Generic dialogs (confirmation, file conflict)
      |- editors/           # Content editors (CSS, notice rules, custom vars)
      |- profiles/          # Profile creation/import/browser modals
      |- settings/          # Settings-related modals (language, translator, etc.)

Contributing

Contributions are welcome!

Fork the repo.
Create a feature branch: git checkout -b feat/your-feature.
Run npm install and npm run build locally to ensure no errors.
Open a pull request with a clear description.
Update CHANGELOG.md and this README.md where relevant.

Please follow the existing code style, and ensure your contributions are innovative and consistent with the plugin's vision.

[!TIP]

Are you a developer of another plugin? If you'd like your plugin to be natively supported by Theme Engine (e.g., controlling a specific color variable of your UI), feel free to open a Pull Request. Supporting integration is a great way to gain more visibility for your work!

Roadmap

Here are the future plans for Theme Engine. Feel free to contribute or suggest features!

Changelog (Summary)

For full details, see CHANGELOG.md.

v2.1.0 - Expanded core variable coverage, introduced native Obsidian language detection, improved build architecture, strengthened CSS safety, and refined overall performance and maintainability.
v2.0.0 - The Theme Engine Update. Re-wrote the core to dynamically capture your active theme's colors. UI now shows "Pristine" (dimmed) vs. "Modified" (bright) states. Added a complete Custom Language and translation editor system. Implemented granular data reset and SCSS/ESLint.
v1.1.1 - Added Per-Profile Video Background support, enhanced settings display performance by restoring scroll position, and refactored the translation structure.
v1.1.0 - Added Per-Profile Custom Backgrounds (Image & Video), background browser, and media management tools.
v1.0.9 - Added Import from Installed Themes/Snippets, Quick Theme Toggle, Reset Plugin button, and Theme Interference Warning.

Troubleshooting / FAQ

Having problems or questions?

See the complete FAQ documentation:

Open FAQ →

Common topics include:

Community theme conflicts
Background transparency behavior
Profile vs Global snippets
Snapshots
RTL support
Migrating from Color Master

License

MIT - see LICENSE.

[!NOTE] This license does not grant rights to use the project's logo or visual identity see TRADEMARK.md.

Trademark & Branding

The official logo (phoenix emblem) and visual identity of this project are protected.

You may use, modify, and distribute the code under the MIT license
You may NOT use the official logo or visual identity in forks, derivatives, or redistributed versions

For full trademark and branding rules, see TRADEMARK.md.

Contact / Links

GitHub Repository: https://github.com/YazanAmmar/obsidian-theme-engine
Issues & Feature Requests: https://github.com/YazanAmmar/obsidian-theme-engine/issues
Telegram Channel: https://t.me/ThemeEngine
Support My Open Source Work: https://limitra.xyz/#support

Theme Engine

Description

Reviews

Stats

Latest Version

Changelog

README file from