Improve the documentation for gtk-custom-css (#7190)
Some checks are pending
Nix / Required Checks: Nix (push) Blocked by required conditions
Nix / check-zig-cache-hash (push) Waiting to run
Test / build-linux (namespace-profile-ghostty-md) (push) Blocked by required conditions
Test / zig-fmt (push) Waiting to run
Test / prettier (push) Waiting to run
Test / alejandra (push) Waiting to run
Test / typos (push) Waiting to run
Test / translations (push) Waiting to run
Test / Required Checks: Test (push) Blocked by required conditions
Test / build-bench (push) Blocked by required conditions
Test / build-flatpak (push) Blocked by required conditions
Test / build-linux (namespace-profile-ghostty-md-arm64) (push) Blocked by required conditions
Test / build-linux-libghostty (push) Blocked by required conditions
Test / build-nix (namespace-profile-ghostty-md) (push) Blocked by required conditions
Test / build-nix (namespace-profile-ghostty-md-arm64) (push) Blocked by required conditions
Test / build-dist (push) Blocked by required conditions
Test / build-macos (push) Blocked by required conditions
Test / build-macos-matrix (push) Blocked by required conditions
Test / build-snap (namespace-profile-ghostty-snap) (push) Blocked by required conditions
Test / build-snap (namespace-profile-ghostty-snap-arm64) (push) Blocked by required conditions
Test / build-windows (push) Blocked by required conditions
Test / blueprint-compiler (push) Waiting to run
Test / build-windows-cross (namespace-profile-ghostty-md, x86-windows-gnu) (push) Blocked by required conditions
Test / build-windows-cross (namespace-profile-ghostty-md, x86_64-windows-gnu) (push) Blocked by required conditions
Test / test (push) Waiting to run
Test / GTK x11=false wayland=false (push) Blocked by required conditions
Test / GTK x11=true wayland=false (push) Blocked by required conditions
Test / GTK x11=false wayland=true (push) Blocked by required conditions
Test / GTK x11=true wayland=true (push) Blocked by required conditions
Test / Build -Dsentry=false (push) Blocked by required conditions
Test / Build -Dsentry=true (push) Blocked by required conditions
Test / test-macos (push) Blocked by required conditions
Test / Test pkg/wuffs (push) Blocked by required conditions
Test / Test build on Debian 12 (push) Blocked by required conditions
Test / flatpak-check-zig-cache (push) Waiting to run
Test / Flatpak (map[arch:aarch64 runner:namespace-profile-ghostty-md-arm64]) (push) Blocked by required conditions
Test / Flatpak (map[arch:x86_64 runner:namespace-profile-ghostty-md]) (push) Blocked by required conditions

Recently when answering [a Discussion], I was reminded of when Tristan
once linked the GTK CSS documentation and said “Perhaps good to add this
to the docs of the GTK custom CSS config option”, so I decided to do
that now. I also added a few random things that I found helpful when
attempting to modify Ghostty's CSS; this information was mostly stolen
from random people on Discord or accidentally discovered.

I really do not care if this is merged or not, nor do I care if the
strings are changed considerably[^1], so I am going straight for a Pull
Request without bothering to open a Discussion, get that converted to an
Issue after a few years, then finally remember to open a Pull Request.

I only tested what this looks like in `ghostty +show-config --default
--docs`, the manpage and the HTML output; I notably did not try seeing
how it renders on the website. The links have to be in angle brackets
for the HTML output to have it rendered as URLs, but it looks odd
everywhere else; manpages have them with mathematical angle brackets,
⟨like this⟩. I also refrained from using an em (—) or en (–) dash
instead of a normal dash (-) as that does not seem to be common in the
rest of the documentation.

[a Discussion]: https://github.com/ghostty-org/ghostty/discussions/7189

[^1]: I didn't see any guidelines or standards for these strings, so
presumably these would be contested as I didn't know what to adhere to
when writing them.
This commit is contained in:
Leah Amelia Chen 2025-04-30 22:33:11 +02:00 committed by GitHub
commit 2b4f1f8b84
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194

View File

@ -2276,6 +2276,18 @@ keybind: Keybinds = .{},
/// Custom CSS files to be loaded.
///
/// GTK CSS documentation can be found at the following links:
///
/// * <https://docs.gtk.org/gtk4/css-overview.html> - An overview of GTK CSS.
/// * <https://docs.gtk.org/gtk4/css-properties.html> - A comprehensive list
/// of supported CSS properties.
///
/// Launch Ghostty with `env GTK_DEBUG=interactive ghostty` to tweak Ghostty's
/// CSS in real time using the GTK Inspector. Errors in your CSS files would
/// also be reported in the terminal you started Ghostty from. See
/// <https://developer.gnome.org/documentation/tools/inspector.html> for more
/// information about the GTK Inspector.
///
/// This configuration can be repeated multiple times to load multiple files.
/// Prepend a ? character to the file path to suppress errors if the file does
/// not exist. If you want to include a file that begins with a literal ?