From 63243e3ae5c177b18ab385fc7b30f2f868a6d6a1 Mon Sep 17 00:00:00 2001 From: bbedward Date: Mon, 4 Aug 2025 21:33:55 -0400 Subject: [PATCH] readme updoot --- README.md | 513 ++++++++++++++++++++++++++---------------------------- 1 file changed, 243 insertions(+), 270 deletions(-) diff --git a/README.md b/README.md index 161d071e..2d44ec61 100644 --- a/README.md +++ b/README.md @@ -1,347 +1,320 @@ # DankMaterialShell -A [Quickshell](https://quickshell.org/)-based desktop shell with Material 3 design principles, built for functionality and modern aesthetics. +
-Specifically optimized for the [niri](https://github.com/YaLTeR/niri) compositor, but compatible with other Wayland compositors. +![GitHub last commit](https://img.shields.io/github/last-commit/bbedward/DankMaterialShell?style=for-the-badge&labelColor=101418&color=9ccbfb) +![GitHub License](https://img.shields.io/github/license/bbedward/DankMaterialShell?style=for-the-badge&labelColor=101418&color=b9c8da) +![GitHub repo size](https://img.shields.io/github/repo-size/bbedward/DankMaterialShell?style=for-the-badge&labelColor=101418&color=d3bfe6) -## Table of Contents +
-- [Features](#features) -- [Requirements](#requirements) -- [Installation](#installation) - - [Core Dependencies](#core-dependencies) - - [Optional Dependencies](#optional-dependencies) - - [Shell Installation](#shell-installation) -- [Configuration](#configuration) - - [Theme Configuration](#theme-configuration) - - [App Theming Setup](#app-theming-setup) -- [Usage](#usage) - - [Basic Controls](#basic-controls) - - [IPC Commands](#ipc-commands) -- [Calendar Integration](#calendar-integration) -- [Troubleshooting](#troubleshooting) +A modern Wayland desktop shell built with [Quickshell](https://quickshell.org/) and designed specifically for the [niri](https://github.com/YaLTeR/niri) compositor. Features Material 3 design principles with a heavy focus on functionality and customizability. -## Features +## Screenshots -- **Material 3 Design**: Modern, clean interface following Google's latest design language -- **Dynamic Theming**: Automatic color extraction from wallpapers using matugen -- **System Integration**: Built-in audio controls, brightness management, and media controls -- **Application Launcher**: Spotlight-style launcher for quick app access -- **Clipboard History**: Visual clipboard manager with search functionality -- **Process Manager**: Built-in task manager for system monitoring -- **Notification Center**: Centralized notification management -- **Calendar Support**: Integration with various calendar services -- **Lockscreen**: Secure screen locking functionality +> WIP -## Requirements +## What's Inside -**Base Requirements:** -- Wayland compositor (niri recommended) -- NetworkManager (for WiFi functionality) -- Material Symbols font -- Inter and Fira Code fonts (recommended) +**Core Widgets:** +- **TopBar**: fully customizable bar where widgets can be added, removed, and re-arranged. + - **App Launcher** with fuzzy search, categories, and auto-sorting by most used apps. + - **Workspace Switcher** Dynamically resizing niri workspace switcher. + - **Focused Window** Displays the currently focused window app name and title. + - **Media Player** Short form media player with equalizer, song title, and controls. + - **Clock** Clock and date widget + - **Weather** Weather widget with customizable location + - **System Tray** System tray applets with context menus. + - **Process Monitor** CPU/Ram usage indicators - with a detailed process list PopUp + - **Power/Battery** Power/Battery widget for battery metrics and power profile changing. + - **Notifications** Notification bell with a notification center popup + - **Control Center** High-level view of network, bluetooth, and audio status +- **Spotlight Launcher** A central app launcher/search that can be triggered via an IPC keybinding. +- **Central Command** A combined music, weather, calendar, and events PopUp. +- **Process List** A process list, with system metrics and information. More detailed modal available via IPC. +- **Notification Center** A center for notifications that has support for grouping. +- **Dock** A dock with pinned apps support, recent apps support, and currently running application support. +- **Control Center** A full control center with user profile information, network, bluetooth, audio input/output, and display controls. +- **Lock Screen** Using quickshell's WlSessionLock -**Distribution Support:** -- Compatible with any Linux distribution -- Installation examples provided for Arch Linux and Fedora +**Features:** +- Dynamic wallpaper-based theming with matugen integration +- Numerous IPCs to trigger actions and open various modals. +- Calendar integration with [khal](https://github.com/pimutils/khal) +- Audio/media controls +- Grouped notifications +- Brightness control for internal and external displays +- Qt and GTK app theming synchronization, as well as [Ghostty](https://ghostty.org/) auto-theme support. ## Installation -### Core Dependencies +### Quick Start -#### Material Symbols Font - -**Manual Installation:** +**Dependencies:** ```bash +# Arch Linux +paru -S quickshell-git ttf-material-symbols-variable-git inter-font ttf-fira-code + +# Fedora +sudo dnf copr enable errornointernet/quickshell && sudo dnf install quickshell-git +# Install fonts manually (see instructions below) +``` + +**Get the shell:** +```bash +# Arch linux available via AUR +paru -S dankmaterialshell-git + +# Manual install +mkdir -p ~/.config/quickshell +git clone https://github.com/bbedward/DankMaterialShell.git ~/.config/quickshell/DankMaterialShell +qs -c DankMaterialShell +``` + +### Detailed Setup + +
Font Installation + +**Material Symbols (Required):** +```bash +# Manual installation mkdir -p ~/.local/share/fonts curl -L "https://github.com/google/material-design-icons/raw/master/variablefont/MaterialSymbolsRounded%5BFILL%2CGRAD%2Copsz%2Cwght%5D.ttf" -o ~/.local/share/fonts/MaterialSymbolsRounded.ttf fc-cache -f -``` -**Package Installation:** -```bash # Arch Linux paru -S ttf-material-symbols-variable-git - -# Fedora -# Use manual installation - Fedora packages contain legacy Material Icons ``` -#### Typography - -**Inter Variable Font:** +**Typography (Recommended):** ```bash -# Manual -mkdir -p ~/.local/share/fonts +# Inter Variable Font curl -L "https://github.com/rsms/inter/releases/download/v4.0/Inter-4.0.zip" -o /tmp/Inter.zip unzip -j /tmp/Inter.zip "InterVariable.ttf" "InterVariable-Italic.ttf" -d ~/.local/share/fonts/ rm /tmp/Inter.zip && fc-cache -f -# Package managers -# Arch: pacman -S inter-font -# Fedora: sudo dnf install rsms-inter-fonts -``` - -**Fira Code Font:** -```bash -# Manual -mkdir -p ~/.local/share/fonts +# Fira Code curl -L "https://github.com/tonsky/FiraCode/releases/download/6.2/Fira_Code_v6.2.zip" -o /tmp/FiraCode.zip unzip -j /tmp/FiraCode.zip "ttf/*.ttf" -d ~/.local/share/fonts/ rm /tmp/FiraCode.zip && fc-cache -f - -# Package managers -# Arch: pacman -S ttf-fira-code -# Fedora: sudo dnf install fira-code-fonts ``` -#### Quickshell +
-**Arch Linux:** +
Optional Features + +**Enhanced Functionality:** ```bash -paru -S quickshell-git -``` - -**Fedora:** -```bash -sudo dnf copr enable errornointernet/quickshell -sudo dnf install quickshell -# or for git version -sudo dnf install quickshell-git -``` - -### Optional Dependencies - -| Component | Purpose | Missing Functionality | -|-----------|---------|----------------------| -| matugen | Dynamic wallpaper-based theming | Limited to preconfigured themes | -| ddcutil | External monitor brightness control | No DDC/CI brightness control | -| brightnessctl | Laptop display brightness control | No backlight control | -| wl-clipboard | Copy functionality for PIDs and other elements | No clipboard operations | -| qt5ct + qt6ct | Qt application theming | No Qt theme integration | -| gsettings | GTK application theming | No GTK theme integration | - -#### Installation by Distribution - -**Arch Linux:** -```bash -# Core optional packages +# Arch Linux pacman -S cava wl-clipboard cliphist ddcutil brightnessctl qt5ct qt6ct - -# AUR packages paru -S matugen -``` -**Fedora:** -```bash -# Core packages +# Fedora sudo dnf install cava wl-clipboard ddcutil brightnessctl qt5ct qt6ct - -# COPR repositories sudo dnf copr enable wef/cliphist && sudo dnf install cliphist sudo dnf copr enable heus-sueh/packages && sudo dnf install matugen ``` -### Shell Installation +**What you get:** +- `matugen`: Wallpaper-based dynamic theming +- `ddcutil`: External monitor brightness control +- `brightnessctl`: Laptop display brightness +- `wl-clipboard`: Required for copying various elements to clipboard. +- `qt5ct/qt6ct`: Qt application theming +- `cava`: Audio visualizer +- `cliphist`: Clipboard history -1. **Create configuration directory:** - ```bash - mkdir -p ~/.config/quickshell - ``` - -2. **Clone the repository:** - ```bash - git clone https://github.com/bbedward/DankMaterialShell.git ~/.config/quickshell/DankMaterialShell - ``` - -3. **Launch the shell:** - ```bash - qs -c DankMaterialShell - ``` - -## Configuration - -### Theme Configuration - -#### GTK Applications - -Install a compatible theme like [Colloid](https://github.com/vinceliuice/Colloid-gtk-theme): - -```bash -# Install Colloid theme -./install.sh -s standard -l --tweaks normal -``` - -Configure in `~/.config/gtk-3.0/settings.ini` and `~/.config/gtk-4.0/settings.ini`: -```ini -[Settings] -gtk-theme-name=Colloid -``` - -#### Qt Applications - -**Install Breeze theme:** -```bash -# Arch -pacman -S breeze breeze5 -``` - -**Configure Qt5 and Qt6:** - -In `~/.config/qt5ct/qt5ct.conf` and `~/.config/qt6ct/qt6ct.conf`: -```ini -[Appearance] -style=Breeze -``` - -#### KDE Applications - -Create `~/.config/kdeglobals`: -```ini -[UiSettings] -ColorScheme=qt6ct -``` - -### App Theming Setup - -Enable system app theming in **Settings → Appearance → System App Theming** after installing the required dependencies. - -### Ghostty Theming -If using [Ghostty](https://ghostty.org/), you can automatically theme its colors as well by adding the following to your `~/.config/ghostty/config` file - -``` -config-file = ./config-dankcolors -``` - -Ghostty doesn't hot-reload config changes, but does with a keyboard shortcut `ctrl+,` +
## Usage -### Basic Controls +### Niri Integration -#### Niri Configuration - -Add to your niri configuration: +Add to your niri config ```bash -# Auto-start spawn-at-startup "qs" "-c" "DankMaterialShell" -# Key bindings -Mod+Space hotkey-overlay-title="Run an Application: Spotlight" { - spawn "qs" "-c" "DankMaterialShell" "ipc" "call" "spotlight" "toggle"; -} - -Mod+V hotkey-overlay-title="Open Clipboard History" { - spawn "qs" "-c" "DankMaterialShell" "ipc" "call" "clipboard" "toggle"; +// Dank keybinds +binds { + Mod+Space hotkey-overlay-title="Application Launcher" { + spawn "qs" "-c" "DankMaterialShell" "ipc" "call" "spotlight" "toggle"; + } + Mod+V hotkey-overlay-title="Clipboard Manager" { + spawn "qs" "-c" "DankMaterialShell" "ipc" "call" "clipboard" "toggle"; + } + Mod+M hotkey-overlay-title="Task Manager" { + spawn "qs" "-c" "DankMaterialShell" "ipc" "call" "processlist" "toggle"; + } + Mod+Comma hotkey-overlay-title="Settings" { + spawn "qs" "-c" "DankMaterialShell" "ipc" "call" "settings" "toggle"; + } + Super+Alt+L hotkey-overlay-title="Lock Screen" { + spawn "qs" "-c" "DankMaterialShell" "ipc" "call" "lock" "lock"; + } + XF86AudioRaiseVolume allow-when-locked=true { + spawn "qs" "-c" "DankMaterialShell" "ipc" "call" "audio" "increment" "3"; + } + XF86AudioLowerVolume allow-when-locked=true { + spawn "qs" "-c" "DankMaterialShell" "ipc" "call" "audio" "decrement" "3"; + } + XF86AudioMute allow-when-locked=true { + spawn "qs" "-c" "DankMaterialShell" "ipc" "call" "audio" "mute"; + } + XF86AudioMicMute allow-when-locked=true { + spawn "qs" "-c" "DankMaterialShell" "ipc" "call" "audio" "micmute"; + } } ``` ### IPC Commands -The shell provides extensive IPC (Inter-Process Communication) functionality: +Control everything from the command line, or via keybinds: ```bash -qs -c DankMaterialShell ipc call [parameters] +# Audio control +qs -c DankMaterialShell ipc call audio setvolume 50 +qs -c DankMaterialShell ipc call audio mute + +# Launch applications +qs -c DankMaterialShell ipc call spotlight toggle +qs -c DankMaterialShell ipc call processlist toggle + +# System control +qs -c DankMaterialShell ipc call wallpaper set /path/to/image.jpg +qs -c DankMaterialShell ipc call theme toggle +qs -c DankMaterialShell ipc call lock lock + +# Media control +qs -c DankMaterialShell ipc call mpris playPause +qs -c DankMaterialShell ipc call mpris next ``` -#### Audio Controls +## Theming -| Command | Function | -|---------|----------| -| `audio setvolume 50` | Set volume to 50% | -| `audio increment 10` | Increase volume by 10% | -| `audio decrement 5` | Decrease volume by 5% | -| `audio mute` | Toggle audio mute | -| `audio setmic 75` | Set microphone to 75% | -| `audio micmute` | Toggle microphone mute | -| `audio status` | Get current audio status | - -#### Application Controls - -| Command | Function | -|---------|----------| -| `spotlight toggle` | Toggle application launcher | -| `clipboard toggle` | Toggle clipboard history | -| `processlist toggle` | Toggle process manager | -| `settings toggle` | Toggle settings | -| `lock lock` | Activate lockscreen | - -#### Media Controls - -| Command | Function | -|---------|----------| -| `mpris list` | List available media players | -| `mpris playPause` | Toggle play/pause | -| `mpris next` | Next track | -| `mpris previous` | Previous track | - -#### System Services - -| Command | Function | -|---------|----------| -| `wallpaper set /path/to/image.jpg` | Set wallpaper and refresh theme | -| `theme toggle` | Toggle light/dark mode | -| `notifs clear` | Clear all notifications | - -## Calendar Integration - -### Prerequisites - -Install required packages: +### System App Integration +**GTK Apps:** +Install [Colloid](https://github.com/vinceliuice/Colloid-gtk-theme) or similar Material theme: ```bash -# Arch Linux +./install.sh -s standard -l --tweaks normal +``` + +Configure in `~/.config/gtk-3.0/settings.ini`: +```ini +[Settings] +gtk-theme-name=Colloid +``` + +**Qt Apps:** +```bash +# Install Breeze +pacman -S breeze breeze5 # Arch +sudo dnf install breeze # Fedora + +# Configure qt5ct/qt6ct +echo 'style=Breeze' >> ~/.config/qt5ct/qt5ct.conf +``` + +**Dynamic Theming:** +Enable wallpaper-based theming in **Settings → Appearance → System App Theming** after installing matugen. + +### Terminal Integration + +**Ghostty users** can add automatic color theming: +```bash +echo "config-file = ./config-dankcolors" >> ~/.config/ghostty/config +``` + +## Calendar Setup + +Sync your Google Calendar for dashboard integration: + +
Configuration Steps + +**Install dependencies:** +```bash +# Arch pacman -S vdirsyncer khal python-aiohttp-oauthlib -# Fedora +# Fedora sudo dnf install python3-vdirsyncer khal python3-aiohttp-oauthlib ``` -### Configuration +**Configure vdirsyncer** (`~/.vdirsyncer/config`): +```ini +[general] +status_path = "~/.calendars/status" -1. **Create vdirsyncer directory:** - ```bash - mkdir -p ~/.vdirsyncer - ``` +[pair personal_sync] +a = "personal" +b = "personallocal" +collections = ["from a", "from b"] +conflict_resolution = "a wins" +metadata = ["color"] -2. **Configure calendar sync** in `~/.vdirsyncer/config`: - ```ini - [general] - status_path = "~/.calendars/status" +[storage personal] +type = "google_calendar" +token_file = "~/.vdirsyncer/google_calendar_token" +client_id = "your_client_id" +client_secret = "your_client_secret" - [pair personal_sync] - a = "personal" - b = "personallocal" - collections = ["from a", "from b"] - conflict_resolution = "a wins" - metadata = ["color"] +[storage personallocal] +type = "filesystem" +path = "~/.calendars/Personal" +fileext = ".ics" +``` - [storage personal] - type = "google_calendar" - token_file = "~/.vdirsyncer/google_calendar_token" - client_id = "your_client_id" - client_secret = "your_client_secret" +**Setup sync:** +```bash +vdirsyncer sync +khal configure - [storage personallocal] - type = "filesystem" - path = "~/.calendars/Personal" - fileext = ".ics" - ``` +# Auto-sync every 5 minutes +crontab -e +# Add: */5 * * * * /usr/bin/vdirsyncer sync +``` -3. **Initial sync:** - ```bash - vdirsyncer sync - ``` +
-4. **Configure automatic sync:** - ```bash - crontab -e - # Add: */5 * * * * /usr/bin/vdirsyncer sync - ``` +## Configuration -5. **Configure khal:** - ```bash - khal configure - # Follow the interactive setup - ``` \ No newline at end of file +All settings are configurable in `~/.config/DankMaterialShell/settings.json`, or more intuitively the built-in settings modal. + +**Key configuration areas:** +- Widget positioning and behavior +- Theme and color preferences +- Time format, weather units and location +- Light/Dark modes +- Wallpaper and Profile picture +- Dock enable/disable and various tunes. + +## Troubleshooting + +**Common issues:** +- **Missing icons:** Verify Material Symbols font installation with `fc-list | grep Material` +- **No dynamic theming:** Install matugen and enable in settings +- **Qt apps not themed:** Configure qt5ct/qt6ct and set QT_QPA_PLATFORMTHEME +- **Calendar not syncing:** Check vdirsyncer credentials and network connectivity + +**Getting help:** +- Check the [issues](https://github.com/bbedward/DankMaterialShell/issues) for known problems +- Share logs from `qs -c DankMaterialShell` for debugging +- Join the niri community for compositor-specific questions + +## Contributing + +DankMaterialShell welcomes contributions! Whether it's bug fixes, new widgets, theme improvements, or documentation updates - all help is appreciated. + +**Areas that need attention:** +- More widget options and customization +- Additional compositor compatibility +- Performance optimizations +- Documentation and examples + +## Credits + +- [quickshell](https://quickshell.org/) the core of what makes a shell like this possible. +- [niri](https://github.com/YaLTeR/niri) for the awesome scrolling compositor. +- [soramanew](https://github.com/soramanew) who built [caelestia](https://github.com/caelestia-dots/shell) which served as inspiration and guidance for many dank widgets. +- [end-4](https://github.com/end-4) for [dots-hyprland](https://github.com/end-4/dots-hyprland) which also served as inspiration and guidance for many dank widgets. \ No newline at end of file