Files

T

Frank 62a70caebb docs(okf): 53 Obsidian wikilinks become OKF links

`[[page|Label]]` is Obsidian syntax, not OKF. `kb-lint` resolves it Obsidian-style — by
filename, anywhere in the bundle — so it has never tripped the link gate, while every other
consumer of the bundle (an OKF renderer, a Gitea wiki export, `grep` for reachability) sees
bracketed text where a link should be. That is how two generated pages ended up with no
inbound link at all and nobody noticed: the my-first link census of the bundle reported them
as orphans because their only inbound edges were wikilinks.

Mechanical conversion, 52 links across 17 pages, each resolved against the same page set
`kb-lint` uses: an explicit `|Label` is kept verbatim, an unlabelled link takes the target's
frontmatter `title`. Targets are emitted bundle-absolute (`/tools/niri/tips.md`), the form
the spec recommends and the form 99 existing links in this bundle already use.

Two links were `[[index]]`, which resolves by filename to 21 pages — the ambiguity that
filename-resolution invites. Both meant their own directory's index, so both are now written
out in full: `/tools/gitea/index.md`, `/tools/niri/index.md`.

The linter still tolerates wikilinks; whether it should reject them outright is an open
question on #64, because that would replace the two tests pinning today's tolerance.

Refs #64

2026-10-21 02:11:56 -07:00

16 KiB

Raw Permalink Blame History

type, title, description, resource, tags, timestamp, verified

type

title

description

resource

Noctalia Shell

Noctalia is a native, minimal desktop environment for the Niri compositor. It provides an application launcher, control center, settings GUI, lock screen, session menu, hotkey overlay, media controls, brightness/volume controls, wallpaper management, and system-level utilities.

Version: 5.2.1-1.1 Binary: /usr/bin/noctalia (native Qt application, no Quickshell dependency) Config: ~/.config/noctalia/

Architecture

Noctalia is a native Qt binary that communicates with Niri and system services via direct IPC (noctalia msg) and shell scripts (spawn-sh). It does not depend on Quickshell.

IPC Interface

All primary functionality is exposed via the noctalia msg command:

noctalia msg <command>

See noctalia msg --help for the complete command list.

Historical Note: v4.x used Quickshell IPC (qs -c noctalia-shell ipc call ...), but v5+ is a native binary with its own IPC interface.

Command Reference

Commands are grouped by functional area.

Shells / Surfaces

Command	Description
`bar-show [bar-name]`	Show a named bar or all bars
`bar-hide [bar-name]`	Hide a named bar or all bars
`bar-layer-set <layer>`	Set bar layer (e.g., `top`, `bottom`)
`bar-reserve-toggle [bar-name]`	Temporarily toggle reserve space
`bar-toggle [bar-name]`	Toggle visibility for a named bar or all bars
`dock-hide`	Hide the dock (persists override)
`dock-reload`	Reload dock configuration
`dock-show`	Show the dock (persists override)
`dock-toggle`	Toggle dock visibility (persists override)
`panel-close [id]`	Close the active or named panel
`panel-open <id> [context]`	Open a panel by id, optionally with context (e.g., `launcher /emo`, `control-center audio`)
`panel-toggle <id> [context]`	Toggle a panel by id, optionally with context
`settings-close`	Close the settings window
`settings-open [context]`	Open the settings window, optionally at a specific section
`settings-open-plugin <plugin-id>`	Open settings at a plugin's settings (e.g., `noctalia/notes`)
`settings-open-widget [bar-name] [widget-name]`	Open settings at a bar widget
`settings-toggle [context]`	Toggle the settings window, optionally at a specific section
`window-switcher [action]`	Open or close the window switcher overlay

Lockscreen / Session

Command	Description
`session lock`	Lock the screen
`session lock-and-suspend`	Lock and suspend the system
`lockscreen-widgets-edit`	Open the lockscreen widgets editor
`lockscreen-widgets-exit`	Close the lockscreen widgets editor
`lockscreen-widgets-toggle-edit`	Toggle lockscreen widgets edit mode

Desktop Widgets

Command	Description
`desktop-widgets-edit`	Open the desktop widgets editor
`desktop-widgets-exit`	Close the desktop widgets editor
`desktop-widgets-hide`	Hide desktop widgets (runtime only)
`desktop-widgets-show`	Show desktop widgets (runtime only)
`desktop-widgets-toggle`	Toggle desktop widgets visibility (runtime only)
`desktop-widgets-toggle-edit`	Toggle desktop widgets edit mode

Greeter

Command	Description
`greeter-sync`	Sync wallpaper, colors, and monitor layout to Noctalia Greeter

Media / UI

Command	Description
`notification-show <summary> <body...>`	Show an internal Noctalia notification
`notification-clear-active`	Dismiss all currently active notifications
`notification-clear-history`	Clear notification history
`notification-dnd-set <state>`	Set notification Do Not Disturb state
`notification-dnd-status`	Print notification DND state
`notification-dnd-toggle`	Toggle notification DND
`notification-invoke-latest`	Invoke the default action of the most recent active notification
`clipboard-copy <text>`	Copy text to the clipboard
`clipboard-text`	Print the most recent clipboard text
`clipboard-clear`	Clear clipboard history
`wallpaper-set [connector] <path>`	Set wallpaper for all or a specific output (persisted)
`wallpaper-next [connector]`	Switch to the next wallpaper immediately
`wallpaper-previous [connector]`	Switch to the previous wallpaper immediately
`wallpaper-random [connector]`	Switch to a random wallpaper immediately
`wallpaper-get [connector]`	Print default wallpaper path, or effective path for an output
`theme-mode-set <mode>`	Set theme mode and persist to `settings.toml`
`theme-mode-toggle`	Toggle theme mode between dark and light
`theme-mode-get`	Print the current resolved theme mode
`color-scheme-set <{builtin\|wallpaper\|community\|custom}> ...`	Set palette source and selection in `settings.toml`
`color-scheme-get`	Print active color scheme: `<source> <name>`
`screenshot-region`	Start an interactive region screenshot
`screenshot-fullscreen [mode]`	Capture the focused monitor by default, `pick` interactively, or `all` outputs
`screenshot-annotate`	Freeze the screen and annotate it, then copy or save
`annotate [path]`	Draw on the screen over running apps, or annotate an image file; press F or the Freeze button to capture the background

System Controls

Command	Description
`volume-up [step]`	Increase speaker volume
`volume-down [step]`	Decrease speaker volume
`volume-set <value>`	Set speaker volume
`volume-mute`	Toggle speaker mute
`volume-osd [value]`	Show the volume OSD without changing volume
`mic-mute`	Toggle microphone mute
`mic-volume-up [step]`	Increase microphone volume
`mic-volume-down [step]`	Decrease microphone volume
`mic-volume-set <value>`	Set microphone volume
`mic-volume-osd [value]`	Show the microphone volume OSD
`brightness-up [target] [step]`	Increase brightness (defaults to current monitor)
`brightness-down [target] [step]`	Decrease brightness (defaults to current monitor)
`brightness-set [target] <value>`	Set brightness (defaults to current monitor)
`brightness-osd <value>`	Show brightness OSD without changing brightness
`brightness-list-backlight-devices`	List available sysfs backlight device names
`keyboard-backlight-up`	Increase all keyboard backlights by one level
`keyboard-backlight-down`	Decrease all keyboard backlights by one level
`keyboard-backlight-toggle`	Toggle all keyboard backlights on/off
`keyboard-backlight-set <value>`	Set all keyboard backlights (0-100 percentage)
`keyboard-backlight-osd <value>`	Show keyboard backlight OSD without changing brightness
`keyboard-layout-cycle`	Switch to the next keyboard layout
`network-toggle`	Disconnect the active network, or reconnect when nothing is connected
`wifi-toggle`	Toggle Wi-Fi
`wifi-enable`	Enable Wi-Fi
`wifi-disable`	Disable Wi-Fi
`wifi-status`	Print Wi-Fi state
`bluetooth-toggle`	Toggle Bluetooth
`bluetooth-enable`	Enable Bluetooth
`bluetooth-disable`	Disable Bluetooth
`bluetooth-status`	Print Bluetooth state
`power-cycle [direction]`	Step through UPower's ordered profile list, forward by default (wraps)
`power-set <profile>`	Set the UPower power profile (e.g., `performance`, `balanced`, `power-saver`)
`caffeine-toggle`	Toggle caffeine (idle inhibitor)
`caffeine-enable`	Enable caffeine (idle inhibitor)
`caffeine-disable`	Disable caffeine (idle inhibitor)
`dpms-on`	Turn monitors on
`dpms-off`	Turn monitors off
`effects-profile-set <kind> <profile>`	Set the EasyEffects output or input profile
`log-level-set <level>`	Set the console log level
`log-level-status`	Print the current console log level
`session <action>`	Run a built-in session action (e.g., `lock`, `lock-and-suspend`)
`config-reload`	Reload the config file
`status`	Print current state as JSON
`taskbar-cycle <direction>`	Step to the adjacent task or workspace group in the invoking taskbar
`templates-apply`	Apply configured theme templates for the current palette
`osd-toggle`	Toggle OSD popups
`osd-enable`	Enable OSD popups
`osd-disable`	Disable OSD popups
`plugin <author/plugin:entry> <target[:bar-name]> <event> [payload]`	Dispatch an event to a plugin entry
`plugins <{list\|enable\|disable\|update\|source}> ...`	Manage plugins and sources (`list`/`enable`/`disable`/`update`, `source` list/add/remove)

Configuration Files

`~/.config/noctalia/config.toml`

Main configuration file for runtime and persisted settings.

Live config (tracked in repo):

[shell]
polkit_agent = true

[wallpaper]
directory = "/home/blank/.local/share/noctalia/wallpapers"

`~/.local/state/noctalia/settings.toml`

Settings GUI configuration (bar widgets, theme, wallpaper automation, plugins). Note the location: ~/.local/state/, not ~/.config/.

Location: ~/.local/state/noctalia/settings.toml Status: Tracked in repo — dotfiles/noctalia/.local/state/noctalia/settings.toml; the Settings GUI rewrites the live file, so deploy adopts divergents. Bar layout lives in [bar.default]: center = [ "taskbar", "cat" ], end = [ "notifications", "clipboard", "network", "bluetooth", "tray", "battery", "session", "control-center", "clock" ]. The taskbar widget lists open windows of the focused workspace (added 2026-10-09). Apply changes with noctalia msg config-reload.

`~/.config/noctalia/palettes/`

Custom palette folders.

Live config (tracked in repo):

~/.config/noctalia/palettes/Gruber Red.json → /home/blank/.omp/dotfiles/noctalia/.config/noctalia/palettes/Gruber Red.json

Usage:

noctalia msg color-scheme-set custom "Gruber Red"

Custom palettes are folder-based and immune to the community-palette catalog sync mechanism.

`~/.config/niri/noctalia.kdl`

Niri-specific integration file (generated by Noctalia, untracked in repo). Contains theme colors (live: #f43841 red theme), layer rules, and wallpaper backdrop rules.

Niri Integration

Noctalia is deeply integrated with the Niri compositor configuration.

Autostart

File: ~/.config/niri/cfg/autostart.kdl

spawn-at-startup "noctalia"

Window Rules

File: ~/.config/niri/cfg/rules.kdl

// Geometry and clipping
window-rule {
    geometry-corner-radius 20
    clip-to-geometry true
}

// Floating settings window
window-rule {
    match app-id="dev.noctalia.Noctalia"
    open-floating true
    default-column-width { fixed 1080; }
    default-window-height { fixed 920; }
}

// Wallpaper backdrop
layer-rule {
    match namespace="^noctalia-wallpaper"
    place-within-backdrop true
}

// Panels and overlays
layer-rule {
    match namespace="^noctalia-(bar-[^\"]+|notification|dock|panel|attached-panel|osd)$"
    background-effect {
        xray false
    }
}

Keybindings

File: ~/.config/niri/cfg/keybinds.kdl

Keybind	Action	IPC Command
`Mod+Shift+Return`	Wallpaper panel	`noctalia msg panel-toggle wallpaper`
`Mod+S`	Control center	`noctalia msg panel-toggle control-center`
`Mod+Shift+S`	Settings	`noctalia msg settings-toggle`
`Mod+D`	App launcher	`noctalia msg panel-toggle launcher`
`Mod+ALT+L`	Lock screen	`noctalia msg session lock`
`Mod+Shift+Q`	Session menu	`noctalia msg panel-toggle session`
`Mod+V`	Clipboard history panel	`noctalia msg panel-toggle clipboard`
`Alt+Tab`	Window switcher (app icons + titles)	`noctalia msg window-switcher`
`XF86AudioRaiseVolume`	Volume up	`noctalia msg volume-up`
`XF86AudioLowerVolume`	Volume down	`noctalia msg volume-down`
`XF86AudioMute`	Mute	`noctalia msg volume-mute`
`XF86AudioMicMute`	Mic mute	`noctalia msg mic-mute`
`XF86AudioNext`	Next track	`noctalia msg media next`
`XF86AudioPrev`	Previous track	`noctalia msg media previous`
`XF86AudioPlay`	Play	`noctalia msg media play`
`XF86AudioPause`	Pause/stop	`noctalia msg media stop`
`XF86MonBrightnessUp`	Brightness up	`noctalia msg brightness-up`
`XF86MonBrightnessDown`	Brightness down	`noctalia msg brightness-down`
`Mod+Shift+ESCAPE`	Show hotkey overlay	`niri show-hotkey-overlay`

Recommended IPC binds (from docs):

Mod+Space — Launcher
Mod+S — Control center
Mod+Comma — Settings
Alt+Tab — Window switcher (hold)

Wallpaper Backdrop

The wallpaper layer is placed in the backdrop:

File: ~/.config/niri/cfg/rules.kdl

layer-rule {
    match namespace="^noctalia-wallpaper"
    place-within-backdrop true
}

Background Color

File: ~/.config/niri/cfg/layout.kdl

layout {
    background-color "transparent" // <- needed for noctalia-shell to set wallpaper
}

Widgets use namespace-based layer rules:

layer-rule {
    match namespace="^noctalia-(bar-[^\"]+|notification|dock|panel|attached-panel|osd)$"
    background-effect {
        xray false
    }
}

Laptop / Lid Policy

File: ~/.config/niri/cfg/keybinds.kdl

Mod+ALT+L hotkey-overlay-title="Lock Screen: noctalia lock" { spawn-sh "noctalia msg session lock"; }

File: ~/.config/niri/cfg/autostart.kdl

// Lid close policy (optional)
switch-events {
    lid-close {
        spawn "noctalia" "msg" "session" "lock-and-suspend";
    }
}

Also requires logind configuration: HandleLidSwitch=ignore in /etc/logind.conf.

Theme / Palette Workflow

Builtin Themes

# List available builtin themes
noctalia msg theme-mode-get

# Set a builtin theme
noctalia msg theme-mode-set dark
noctalia msg theme-mode-set light

# Toggle between dark and light
noctalia msg theme-mode-toggle

Community Palettes

# Set a community palette by ID
noctalia msg color-scheme-set community "Palette Name"

Custom Palettes

# Set a custom palette from a folder
noctalia msg color-scheme-set custom "Gruber Red"

Custom palettes live in ~/.config/noctalia/palettes/ and are immune to the community-palette catalog sync.

Apply templates:

noctalia msg templates-apply

Dependencies

Package	Purpose	Version on blankpad (2026-10-21)
`noctalia` (Qt)	the shell: bar, widgets, `noctalia msg`	5.3.0-1.1
`qt6-base`	Qt6 runtime	6.12.0-3.1
`niri`	Wayland compositor	26.04-1.1
`polkit`	PolicyKit integration	128-1.1
`imagemagick`	image processing for palette wallpapers	7.1.2.34-2.1
`ffmpeg`	media processing	2:9.0.2-2.1

Three rows this page used to claim are not installed, verified with pacman -Q and command -v: wlr-randr (display information is niri msg outputs — no package needed, and displays owns that procedure), qt6-multimedia (audio reaches PipeWire through noctalia's own dependency), and brightnessctl (/sys/class/backlight/amdgpu_bl1 exists and nothing on this box drives it — laptop brightness is a gap to close, not a feature to document). A dependency table is a claim about the machine: check it before writing it.

16 KiB

Raw Permalink Blame History

Noctalia Shell

Architecture

IPC Interface

Command Reference

Shells / Surfaces

Lockscreen / Session

Desktop Widgets

Greeter

Media / UI

System Controls

Configuration Files

`~/.config/noctalia/config.toml`

`~/.local/state/noctalia/settings.toml`

`~/.config/noctalia/palettes/`

`~/.config/niri/noctalia.kdl`

Niri Integration

Autostart

Window Rules

Keybindings

Wallpaper Backdrop

Background Color

Per-Widget Layer Namespaces

Laptop / Lid Policy

Theme / Palette Workflow

Builtin Themes

Community Palettes

Custom Palettes

Dependencies

See Also

16 KiB Raw Permalink Blame History

Noctalia Shell

Architecture

IPC Interface

Command Reference

Shells / Surfaces

Lockscreen / Session

Desktop Widgets

Greeter

Media / UI

System Controls

Configuration Files

~/.config/noctalia/config.toml

~/.local/state/noctalia/settings.toml

~/.config/noctalia/palettes/

~/.config/niri/noctalia.kdl

Niri Integration

Autostart

Window Rules

Keybindings

Wallpaper Backdrop

Background Color

Per-Widget Layer Namespaces

Laptop / Lid Policy

Theme / Palette Workflow

Builtin Themes

Community Palettes

Custom Palettes

Dependencies

See Also

16 KiB

Raw Permalink Blame History

`~/.config/noctalia/config.toml`

`~/.local/state/noctalia/settings.toml`

`~/.config/noctalia/palettes/`

`~/.config/niri/noctalia.kdl`