Update README.md

Toni500github · Toni500github · commit bd7d578da46f · 2025-11-25T18:47:45.000+01:00
diff --git a/README.md b/README.md
@@ -5,11 +5,11 @@
 <h2></h2> <!-- add a separating line -->
 
 > [!WARNING]
-> Parts of this README refers to the `v2.0.0-beta1` release.  
+> Parts of this README refers to the `v2.0.0-beta1` release.
 > Some features such as the plugin system may differ from the upcoming stable release.
 
 <p align="center">
-    A modular information fetching (neofetch-like) tool, which its focus point is the performance and <b>customizability</b>
+    A modular information fetching tool (neofetch-like), focused on <b>performance</b> and <b>customizability</b>
 </p>
 
 <p align="center">
@@ -37,6 +37,7 @@
 </p>
 <img src="https://upload.wikimedia.org/wikipedia/commons/2/24/Transparent_Square_Tiles_Texture.png" width="1px" height="1px" align="left" />
 <img src="screenshots/pipeline-style.png" />
+
 <!-- Leaving this here for future, it's not as fire as the one above
 | | |
 |:-:|:-:|
@@ -47,23 +48,52 @@
 ## Key Features
 - Works as a **terminal program**, **GTK3 GUI app**, or **native Android widget**
 - Modular design - fetch anything through `$<>` tags and plugins
-- Super lightweight
-- Easy to configure and script
-- Optional dependencies only, no runtime bloat (as like as [fastfetch](https://github.com/fastfetch-cli/fastfetch)
-- Plugin system for adding new info sources
+- Super lightweight with no required dependencies
+- Easy to configure with auto-generated, well-commented config files
+- Plugin system for extending beyond system info (weather, GitHub, APIs, etc.)
+- Live mode for continuous updates
+
+## Quick Start
+
+After [installing](#installation) customfetch, simply run:
+
+```bash
+customfetch
+```
+
+On first run, customfetch automatically creates a config file `~/.config/customfetch/config.toml` (or `$XDG_CONFIG_HOME/customfetch/config.toml` if set) with helpful comments explaining every option.
+
+**Useful commands to get started:**
+
+| Command | Description |
+|---------|-------------|
+| `customfetch` | Run with default/current config |
+| `customfetch -w` | Show comprehensive guide on tags, colors, and syntax |
+| `customfetch -l` | List all available modules (including from plugins) |
+| `customfetch --gen-config <path>` | Regenerate the default config file (if to a path) |
+| `customfetch -h` | Show all CLI arguments |
+| `customfetch -C /path/to/config.toml` | Use a custom config file |
+| `customfetch -n` | Disable logo display |
+| `customfetch -N` | Disable all colors |
+| `customfetch -d NAME` | Use a specific distro logo |
+| `customfetch -s PATH` | Path to custom ASCII art or image (must specify `--image-backend` `-i`) |
+| `customfetch -N -m "\$<gpu>" -m "\$<cpu>"` | Display only CPU and GPU info, no logo, no colors |
+| `customfetch -m "\${cyan}Kernel: \$<os.kernel>" -m "\${green}Uptime: \$<os.uptime>"` | Quick system check with custom formatting in the terminal |
+| `customfetch --loop-ms 1000` | Update display every second |
 
 ## Dependencies
-Customfetch has no required dependencies unless you build the GUI app version.\
+
+Customfetch has **no required dependencies** unless you build the GUI app version.
 For compiling from source, all you need is a **C++20** compiler (C++17 might still work).
 
-Packages for running the GUI app:
+**GUI app packages:**
 * `gtk3`
 * `gtkmm3`
 
-Optional packages that will make customfetch system query faster:
-* `dconf`: Alternative to the slow `gsettings` command
-* `libxfce4util`: Query XFCE4 version faster
-* `wayland-client`: Library for getting the Wayland compositor faster
+**Optional packages** (for faster system queries):
+* `dconf` - Alternative to the slow `gsettings` command
+* `libxfce4util` - Query XFCE4 version faster
+* `wayland-client` - Get Wayland compositor info faster
 
 ## Installation
 
@@ -72,7 +102,7 @@ Grab the latest `.deb` file from the [releases page](https://github.com/Toni500g
 
 ### Arch (AUR)
 ```bash
-# Binary 
+# Binary (stable)
 yay -S customfetch-bin       # Terminal only
 yay -S customfetch-gui-bin   # GUI version
 
@@ -90,7 +120,7 @@ Download the `.tar.gz` from [releases](https://github.com/Toni500github/customfe
 It includes a `/usr` folder so you can install it manually or through your package manager.
 
 ### Android widget
-Moved to its own repo:  
+Moved to its own repo:
 https://github.com/Toni500github/customfetch-android-app
 
 ### Build from source
@@ -101,15 +131,16 @@ cd customfetch
 # DEBUG=0 for release build
 # GUI_APP=0 or 1 for terminal or GUI app
 make install DEBUG=0 GUI_APP=0
-
-customfetch
 ```
 
-## How to customize
-This is only an explanation about tags and preview, that can be always found in the documentation.
+## Configuration
+
+### Example config
+
+Here's an example config and its output:
 
-Here's an example using my config
 ![image](screenshots/demo.png)
+
 ```toml
 [config]
 
@@ -141,32 +172,93 @@ layout = [
 ]
 ```
 
-### Tag Syntax (both ASCII art and layout)
+### Tag Syntax
+
+Customfetch uses a tag system in both the layout and ASCII art. Here's a quick reference:
+
+| Tag | Description | Example |
+|-----|-------------|---------|
+| `$<module.member>` | Print info from a module | `$<cpu>`, `$<ram.used>`, `$<os.kernel.version>` |
+| `${color}` | Set text color | `${red}`, `${#ff5500}` |
+| `$(command)` | Run a shell command | `$(date +%H:%M)`, `$(!cbonsai)` |
+| `$[x,y,eq,neq]` | Conditional output | `$[$<os.name>,Arch,btw,]` |
+| `$%n1,n2%` | Colored percentage | `$%$<ram.used>,$<ram.total>%` |
+
+> [!NOTE]
+> - Use `$(!command)` (with `!`) in ASCII art to prevent color leaking
+> - Use `!` in the begin of the `$%%` for inverting red and green
+> - Escape `<` as `\<` and `&` as `\&` when needed (especially for GUI app)
+> - Run `customfetch -w` for the complete syntax reference with all color modifiers and advanced examples
 
-| Tag | Description |
-|-----|--------------|
-| `$<info.module>` | Print a module info (for example `$<cpu>` or `$<github.user.followers>`) |
-| `${color}` | Set output color (hex or ANSI escape colors) |
-| `$(bash command)` | Print the output of a shell command (`!` prefix if in ASCII art or big ANSI escape color outputs) |
-| `$[x,y,if_equal,if_not]` | Conditional tag to print based on comparision |
-| `$%n1,n2%` | Colored percentage between two numbers (prefix `!` to invert colors) |
+### Colors and formatting
 
-Run `customfetch -w` or `man customfetch` for full syntax reference.\
-Escape `<` or `&` when needed (especially for GUI compatibility).
+Colors can be specified as:
+- **Named colors**: `${red}`, `${green}`, `${cyan}`, `${auto}` (matches logo colors), `${auto2}`, `${auto3}`...
+- **Hex colors**: `${#ff5500}`, `${#f50}` (shorthand)
+- **ANSI escapes**: `${\e[1;33m}` (e.g., bold yellow)
+- **Reset**: `${0}` (normal reset), `${1}` (bold reset)
+
+**Text modifiers** (prefix before hex color):
+
+| Modifier | Effect | Example |
+|----------|--------|---------|
+| `!` | Bold | `${!#ff0000}` |
+| `u` | Underline | `${u#00ff00}` |
+| `i` | Italic | `${i#0000ff}` |
+| `s` | Strikethrough | `${s#888888}` |
+| `l` | Blink (terminal only) | `${l#ff00ff}` |
+| `b` | Background color | `${b#222222}` |
+
+**Combining modifiers:** `${!u#ff0000}` (bold + underlined red)
+
+<details>
+<summary><b>GUI-only modifiers</b></summary>
+
+| Modifier | Effect |
+|----------|--------|
+| `o` | Overline |
+| `a(value)` | Foreground alpha (0%-100% or 1-65536) |
+| `A(value)` | Background alpha |
+| `L(value)` | Underline style (none/single/double/low/error) |
+| `U(color)` | Underline color (hex) |
+| `B(color)` | Background color (hex) |
+| `S(color)` | Strikethrough color (hex) |
+| `O(color)` | Overline color (hex) |
+| `w(value)` | Font weight (light/normal/bold/ultrabold or 100-1000) |
+
+Example: `${oU(#ff0000)L(double)#ffffff}Error` — white text with double red underline and overline
+
+</details>
 
 ## Plugins
-Thanks to plugins, customfetch is able to fetch beyond system information and be able to fetch anything — weather, GitHub data, APIs, etc.
 
-You can easily install plugins from repositories using `cufetchpm`.  
-For example:
+Plugins extend customfetch beyond system information — fetch weather, GitHub stats, API data, and more.
+
+### Installing plugins
+
+Use `cufetchpm` to install plugins from repositories:
+
+```bash
+cufetchpm install https://github.com/Toni500github/customfetch-plugins-github
+```
+
+After installing, run `customfetch -l` to see newly available modules from the plugin.
+
+### Managing plugins
+
 ```bash
-$ cufetchpm install https://github.com/Toni500github/customfetch-plugins-github
+cufetchpm list              # List installed plugins
+cufetchpm enable <plugin>   # Enable a plugin
+cufetchpm disable <plugin>  # Disable a plugin
+cufetchpm remove <plugin>   # Remove a plugin
 ```
-For more plugin managing, such as enabling/disabling or removing them, refer to the `cufetchpm --help` guide.
+
+See `cufetchpm --help` for all options.
 
 ### Writing your own plugins
-Plugins are just shared libraries.  
-There’s a [guide here](https://github.com/Toni500github/customfetch/blob/main/docs/build-plugin.md) that walks you through writing one.
+
+Plugins are shared libraries (`.so` files) that register custom modules.
+See the [plugin development guide](https://github.com/Toni500github/customfetch/blob/main/docs/build-plugin.md) to create your own.
 
 ## Star History
 
diff --git a/src/config.cpp b/src/config.cpp
@@ -59,8 +59,7 @@ void Config::loadConfigFile(const std::filesystem::path& filename)
         die(_("Parsing config file '{}' failed:\n"
               "{}\n"
               "\t(error occurred at line {} column {})"),
-            filename.string(), err.description(),
-            err.source().begin.line, err.source().begin.column);
+            filename.string(), err.description(), err.source().begin.line, err.source().begin.column);
     }
 
     // clang-format off
@@ -95,23 +94,23 @@ void Config::loadConfigFile(const std::filesystem::path& filename)
     this->flatpak_dirs = getValueArrayStr("os.pkgs.flatpak-dirs", {"/var/lib/flatpak/app", "~/.local/share/flatpak/app"});
     this->apk_files    = getValueArrayStr("os.pkgs.apk-files",    {"/var/lib/apk/db/installed"});
 
-    colors.black       = getValueStr("config.black",   "\033[1;30m");
-    colors.red         = getValueStr("config.red",     "\033[1;31m");
-    colors.green       = getValueStr("config.green",   "\033[1;32m");
-    colors.yellow      = getValueStr("config.yellow",  "\033[1;33m");
-    colors.blue        = getValueStr("config.blue",    "\033[1;34m");
-    colors.magenta     = getValueStr("config.magenta", "\033[1;35m");
-    colors.cyan        = getValueStr("config.cyan",    "\033[1;36m");
-    colors.white       = getValueStr("config.white",   "\033[1;37m");
-
-    colors.gui_black   = getValueStr("gui.black",   "!#000005");
-    colors.gui_red     = getValueStr("gui.red",     "!#ff2000");
-    colors.gui_green   = getValueStr("gui.green",   "!#00ff00");
-    colors.gui_blue    = getValueStr("gui.blue",    "!#00aaff");
-    colors.gui_cyan    = getValueStr("gui.cyan",    "!#00ffff");
-    colors.gui_yellow  = getValueStr("gui.yellow",  "!#ffff00");
-    colors.gui_magenta = getValueStr("gui.magenta", "!#ff11cc");
-    colors.gui_white   = getValueStr("gui.white",   "!#ffffff");
+    this->colors.black       = getValueStr("config.black",   "\033[1;30m");
+    this->colors.red         = getValueStr("config.red",     "\033[1;31m");
+    this->colors.green       = getValueStr("config.green",   "\033[1;32m");
+    this->colors.yellow      = getValueStr("config.yellow",  "\033[1;33m");
+    this->colors.blue        = getValueStr("config.blue",    "\033[1;34m");
+    this->colors.magenta     = getValueStr("config.magenta", "\033[1;35m");
+    this->colors.cyan        = getValueStr("config.cyan",    "\033[1;36m");
+    this->colors.white       = getValueStr("config.white",   "\033[1;37m");
+
+    this->colors.gui_black   = getValueStr("gui.black",   "!#000005");
+    this->colors.gui_red     = getValueStr("gui.red",     "!#ff2000");
+    this->colors.gui_green   = getValueStr("gui.green",   "!#00ff00");
+    this->colors.gui_blue    = getValueStr("gui.blue",    "!#00aaff");
+    this->colors.gui_cyan    = getValueStr("gui.cyan",    "!#00ffff");
+    this->colors.gui_yellow  = getValueStr("gui.yellow",  "!#ffff00");
+    this->colors.gui_magenta = getValueStr("gui.magenta", "!#ff11cc");
+    this->colors.gui_white   = getValueStr("gui.white",   "!#ffffff");
 
     if (this->percentage_colors.size() < 3)
     {
diff --git a/src/display.cpp b/src/display.cpp
@@ -145,9 +145,9 @@ static std::vector<std::string> render_with_image(const moduleMap_t& modulesInfo
     const size_t height = image_height / font_height;
 
     if (config.args_image_backend == "kitty")
-        TinyProcessLib::Process({ "kitty", "+kitten", "icat",
-                    "--align", (config.logo_position == "top" ? "center" : config.logo_position),
-                    "--place", fmt::format("{}x{}@0x0", width, height), path.string() });
+        TinyProcessLib::Process({ "kitty", "+kitten", "icat", "--align",
+                                  (config.logo_position == "top" ? "center" : config.logo_position), "--place",
+                                  fmt::format("{}x{}@0x0", width, height), path.string() });
     else if (config.args_image_backend == "viu")
         TinyProcessLib::Process(
             { "viu", "-t", "-w", fmt::to_string(width), "-h", fmt::to_string(height), path.string() });
