Improve the documentation for gtk-custom-css (#7190)

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

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 ?