Using itHUD sections
HUD sections
A command section of the HUD shows what a program of yours prints.
[[plugins.hud.sections]]
type = "command"
name = "ci" # lowercase letters, digits, hyphens
command = ["/home/you/bin/ci-hud", "--branch", "main"] # argv, not a shell line
interval_seconds = 30 # run again this long after it exits; 1–86400The HUD starts the program with stdin closed and VENDETTA_HUD_SECTION set to the
section’s name; its stderr goes to the worker’s log. Each line it prints on stdout
is one JSON section that replaces what the card shows. A program can print once and
exit, to run again after interval_seconds, or keep running and print a line
whenever something changes. It ends with the HUD.
A section
Section titled “A section”{
"title": "CI",
"icon": "◆",
"summary": [{"text": "1 failing", "color": "error"}],
"rows": [
{
"icons": [{"text": "●", "color": "#f38ba8"}],
"text": "vendetta main",
"detail": "failed 3m ago",
"tooltip": "Build 1842",
"command": ["xdg-open", "https://ci.example.com/builds/1842"]
}
],
"empty": "All green",
"footer": "+2 more"
}Every field is optional.
| Field | Meaning |
|---|---|
title |
The header’s title; the section’s name when empty. |
icon |
A glyph before the title. |
summary |
Text at the right of the header, shown while minimized too. |
rows |
Up to 50 rows. |
empty |
Shown when there are no rows. |
footer |
Text under the rows. |
error |
Shown instead of the rows. |
A row has icons (up to four glyphs, each in a narrow column), text, detail
(at the right), note (shown whole under the row, keeping its lines, up to 4,096
characters), tooltip, and command: an argv that runs, detached and without a
shell, when the row is clicked.
Text is a string, or a list of spans {"text": "…", "color": "…"}, each also
"bold", "italic", or "code" (monospaced) when true. A color is
#rrggbb, or a role that follows Noctalia’s theme: primary, text, muted, or
error. Text is shown literally, never as markup; control characters are dropped,
and long text is cut.
A line that is not a valid section, or a program that fails before printing one, shows the error in the card. Lines are at most 256 KiB.
Example
Section titled “Example”#!/bin/sh
# Free space on /, every minute: interval_seconds = 60.
used=$(df --output=pcent / | tail -1 | tr -dc 0-9)
color=muted; [ "$used" -ge 90 ] && color=error
printf '{"title":"Disk","icon":"▤","summary":[{"text":"%s%% used","color":"%s"}]}\n' "$used" "$color"