1
0
mirror of https://github.com/AvengeMedia/DankMaterialShell.git synced 2026-01-24 21:42:51 -05:00

readme updoot

This commit is contained in:
bbedward
2025-08-04 21:33:55 -04:00
parent 739f3eff01
commit 63243e3ae5

513
README.md
View File

@@ -1,347 +1,320 @@
# DankMaterialShell
A [Quickshell](https://quickshell.org/)-based desktop shell with Material 3 design principles, built for functionality and modern aesthetics.
<div align=center>
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
</div>
- [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
<details><summary>Font Installation</summary>
**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
</details>
**Arch Linux:**
<details><summary>Optional Features</summary>
**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+,`
</details>
## 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 <target> <function> [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:
<details><summary>Configuration Steps</summary>
**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
```
</details>
4. **Configure automatic sync:**
```bash
crontab -e
# Add: */5 * * * * /usr/bin/vdirsyncer sync
```
## Configuration
5. **Configure khal:**
```bash
khal configure
# Follow the interactive setup
```
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.