diff --git a/src/cli/help.zig b/src/cli/help.zig index e75b1b617..c0db37afe 100644 --- a/src/cli/help.zig +++ b/src/cli/help.zig @@ -3,9 +3,9 @@ const Allocator = std.mem.Allocator; const args = @import("args.zig"); const Action = @import("action.zig").Action; -// Note that this options struct doesn't implement the `help` decl like -// other actions. That is because the help command is special and wants to -// handle its own logic around help detection. +// Note that this options struct doesn't implement the `help` decl like other +// actions. That is because the help command is special and wants to handle its +// own logic around help detection. pub const Options = struct { /// This must be registered so that it isn't an error to pass `--help` help: bool = false, @@ -15,9 +15,9 @@ pub const Options = struct { } }; -/// The `help` command shows general help about Ghostty. You can also -/// specify `--help` or `-h` along with any action such as `+list-themes` -/// to see help for a specific action. +/// The `help` command shows general help about Ghostty. You can also specify +/// `--help` or `-h` along with any action such as `+list-themes` to see help +/// for a specific action. pub fn run(alloc: Allocator) !u8 { var opts: Options = .{}; defer opts.deinit(); diff --git a/src/cli/list_colors.zig b/src/cli/list_colors.zig index 447f70552..a275142bc 100644 --- a/src/cli/list_colors.zig +++ b/src/cli/list_colors.zig @@ -15,7 +15,7 @@ pub const Options = struct { } }; -/// The "list-colors" command is used to list all the named RGB colors in +/// The `list-colors` command is used to list all the named RGB colors in /// Ghostty. pub fn run(alloc: std.mem.Allocator) !u8 { var opts: Options = .{}; diff --git a/src/cli/list_fonts.zig b/src/cli/list_fonts.zig index b49e43a30..2f6b2cee8 100644 --- a/src/cli/list_fonts.zig +++ b/src/cli/list_fonts.zig @@ -35,22 +35,21 @@ pub const Config = struct { } }; -/// The list-fonts command is used to list all the available fonts for Ghostty. -/// This uses the exact same font discovery mechanism Ghostty uses to find -/// fonts to use. +/// The `list-fonts` command is used to list all the available fonts for +/// Ghostty. This uses the exact same font discovery mechanism Ghostty uses to +/// find fonts to use. /// -/// When executed with no arguments, this will list all available fonts, -/// sorted by family name, then font name. If a family name is given -/// with "--family", the sorting will be disabled and the results instead -/// will be shown in the same priority order Ghostty would use to pick a -/// font. +/// When executed with no arguments, this will list all available fonts, sorted +/// by family name, then font name. If a family name is given with `--family`, +/// the sorting will be disabled and the results instead will be shown in the +/// same priority order Ghostty would use to pick a font. /// -/// The "--family" argument can be used to filter results to a specific family. -/// The family handling is identical to the "font-familiy" set of Ghostty -/// configuration values, so this can be used to debug why your desired font -/// may not be loading. +/// The `--family` argument can be used to filter results to a specific family. +/// The family handling is identical to the `font-familiy` set of Ghostty +/// configuration values, so this can be used to debug why your desired font may +/// not be loading. /// -/// The "--bold" and "--italic" arguments can be used to filter results to +/// The `--bold` and `--italic` arguments can be used to filter results to /// specific styles. It is not guaranteed that only those styles are returned, /// it will just prioriiize fonts that match those styles. pub fn run(alloc: Allocator) !u8 { diff --git a/src/cli/list_keybinds.zig b/src/cli/list_keybinds.zig index ed831837e..ef80d6442 100644 --- a/src/cli/list_keybinds.zig +++ b/src/cli/list_keybinds.zig @@ -23,16 +23,16 @@ pub const Options = struct { } }; -/// The "list-keybinds" command is used to list all the available keybinds -/// for Ghostty. +/// The `list-keybinds` command is used to list all the available keybinds for +/// Ghostty. /// /// When executed without any arguments this will list the current keybinds /// loaded by the config file. If no config file is found or there aren't any /// changes to the keybinds it will print out the default ones configured for /// Ghostty /// -/// The "--default" argument will print out all the default keybinds -/// configured for Ghostty +/// The `--default` argument will print out all the default keybinds configured +/// for Ghostty pub fn run(alloc: Allocator) !u8 { var opts: Options = .{}; defer opts.deinit(); diff --git a/src/cli/list_themes.zig b/src/cli/list_themes.zig index 98c3859c6..82c461893 100644 --- a/src/cli/list_themes.zig +++ b/src/cli/list_themes.zig @@ -19,15 +19,15 @@ pub const Options = struct { } }; -/// The "list-themes" command is used to list all the available themes -/// for Ghostty. +/// The `list-themes` command is used to list all the available themes for +/// Ghostty. /// -/// Themes require that Ghostty have access to the resources directory. -/// On macOS this is embedded in the app bundle. On Linux, this is usually -/// in `/usr/share/ghostty`. If you're compiling from source, this is the -/// `zig-out/share/ghostty` directory. You can also set the `GHOSTTY_RESOURCES_DIR` -/// environment variable to point to the resources directory. Themes -/// live in the `themes` subdirectory of the resources directory. +/// Themes require that Ghostty have access to the resources directory. On macOS +/// this is embedded in the app bundle. On Linux, this is usually in `/usr/ +/// share/ghostty`. If you're compiling from source, this is the `zig-out/share/ +/// ghostty` directory. You can also set the `GHOSTTY_RESOURCES_DIR` environment +/// variable to point to the resources directory. Themes live in the `themes` +/// subdirectory of the resources directory. pub fn run(alloc: Allocator) !u8 { var opts: Options = .{}; defer opts.deinit(); diff --git a/src/cli/show_config.zig b/src/cli/show_config.zig index c62dfe9f5..e3f1341e8 100644 --- a/src/cli/show_config.zig +++ b/src/cli/show_config.zig @@ -21,15 +21,15 @@ pub const Options = struct { _ = self; } - /// Enables "-h" and "--help" to work. + /// Enables `-h` and `--help` to work. pub fn help(self: Options) !void { _ = self; return Action.help_error; } }; -/// The "show-config" command shows the current configuration in a valid -/// Ghostty configuration file format. +/// The `show-config` command shows the current configuration in a valid Ghostty +/// configuration file format. /// /// When executed without any arguments this will output the current /// configuration that is different from the default configuration. If you're @@ -38,24 +38,23 @@ pub const Options = struct { /// If you are a new user and want to see all available options with /// documentation, run `ghostty +show-config --default --docs`. /// -/// The output is not in any specific order, but the order should be -/// consistent between runs. The output is not guaranteed to be exactly -/// match the input configuration files, but it will result in the same -/// behavior. Comments, whitespace, and other formatting is not preserved -/// from user configuration files. +/// The output is not in any specific order, but the order should be consistent +/// between runs. The output is not guaranteed to be exactly match the input +/// configuration files, but it will result in the same behavior. Comments, +/// whitespace, and other formatting is not preserved from user configuration +/// files. /// /// Flags: /// -/// - "--default": Show the default configuration instead of loading +/// * `--default`: Show the default configuration instead of loading /// the user configuration. /// -/// - "--changes-only": Only show the options that have been changed -/// from the default. This has no effect if "--default" is specified. +/// * `--changes-only`: Only show the options that have been changed +/// from the default. This has no effect if `--default` is specified. /// -/// - "--docs": Print the documentation above each option as a comment, +/// * `--docs`: Print the documentation above each option as a comment, /// This is very noisy but is very useful to learn about available -/// options, especially paired with "--default". -/// +/// options, especially paired with `--default`. pub fn run(alloc: Allocator) !u8 { var opts: Options = .{}; defer opts.deinit(); diff --git a/src/cli/version.zig b/src/cli/version.zig index fb12faa2e..fc23fae2a 100644 --- a/src/cli/version.zig +++ b/src/cli/version.zig @@ -12,15 +12,14 @@ pub const Options = struct { _ = self; } - /// Enables "-h" and "--help" to work. + /// Enables `-h` and `--help` to work. pub fn help(self: Options) !void { _ = self; return Action.help_error; } }; -/// The `version` command is used to display information -/// about Ghostty. +/// The `version` command is used to display information about Ghostty. pub fn run(alloc: Allocator) !u8 { var opts: Options = .{}; defer opts.deinit(); @@ -34,6 +33,7 @@ pub fn run(alloc: Allocator) !u8 { const stdout = std.io.getStdOut().writer(); try stdout.print("Ghostty {s}\n\n", .{build_config.version_string}); try stdout.print("Build Config\n", .{}); + try stdout.print(" - Zig version: {s}\n", .{builtin.zig_version_string}); try stdout.print(" - build mode : {}\n", .{builtin.mode}); try stdout.print(" - app runtime: {}\n", .{build_config.app_runtime}); try stdout.print(" - font engine: {}\n", .{build_config.font_backend}); diff --git a/src/config/Config.zig b/src/config/Config.zig index 86a046889..13f9fb338 100644 --- a/src/config/Config.zig +++ b/src/config/Config.zig @@ -1,5 +1,13 @@ /// Config is the main config struct. These fields map directly to the /// CLI flag names hence we use a lot of `@""` syntax to support hyphens. + +// Pandoc is used to automatically generate manual pages and other forms of +// documentation, so documentation comments on fields in the Config struct +// should use Pandoc's flavor of Markdown. +// +// For a reference to Pandoc's Markdown see their [online +// manual.](https://pandoc.org/MANUAL.html#pandocs-markdown) + const Config = @This(); const std = @import("std"); @@ -32,106 +40,105 @@ const c = @cImport({ /// The font families to use. /// /// You can generate the list of valid values using the CLI: -/// path/to/ghostty/cli +list-fonts /// -/// This configuration can be repeated multiple times to specify -/// preferred fallback fonts when the requested codepoint is not -/// available in the primary font. This is particularly useful for -/// multiple languages, symbolic fonts, etc. +/// ghostty +list-fonts /// -/// If you want to overwrite a previous set value rather than append -/// a fallback, specify the value as "" (empty string) to reset the list -/// and then set the new values. For example: +/// This configuration can be repeated multiple times to specify preferred +/// fallback fonts when the requested codepoint is not available in the primary +/// font. This is particularly useful for multiple languages, symbolic fonts, +/// etc. +/// +/// If you want to overwrite a previous set value rather than append a fallback, +/// specify the value as `""` (empty string) to reset the list and then set the +/// new values. For example: /// /// font-family = "" /// font-family = "My Favorite Font" /// -/// Changing this configuration at runtime will only affect new terminals, -/// i.e. new windows, tabs, etc. +/// Changing this configuration at runtime will only affect new terminals, i.e. +/// new windows, tabs, etc. @"font-family": RepeatableString = .{}, @"font-family-bold": RepeatableString = .{}, @"font-family-italic": RepeatableString = .{}, @"font-family-bold-italic": RepeatableString = .{}, -/// The named font style to use for each of the requested terminal font -/// styles. This looks up the style based on the font style string advertised -/// by the font itself. For example, "Iosevka Heavy" has a style of "Heavy". +/// The named font style to use for each of the requested terminal font styles. +/// This looks up the style based on the font style string advertised by the +/// font itself. For example, "Iosevka Heavy" has a style of "Heavy". /// -/// You can also use these fields to completely disable a font style. If -/// you set the value of the configuration below to literal "false" then -/// that font style will be disabled. If the running program in the terminal -/// requests a disabled font style, the regular font style will be used -/// instead. +/// You can also use these fields to completely disable a font style. If you set +/// the value of the configuration below to literal `false` then that font style +/// will be disabled. If the running program in the terminal requests a disabled +/// font style, the regular font style will be used instead. /// -/// These are only valid if its corresponding font-family is also specified. -/// If no font-family is specified, then the font-style is ignored unless -/// you're disabling the font style. +/// These are only valid if its corresponding font-family is also specified. If +/// no font-family is specified, then the font-style is ignored unless you're +/// disabling the font style. @"font-style": FontStyle = .{ .default = {} }, @"font-style-bold": FontStyle = .{ .default = {} }, @"font-style-italic": FontStyle = .{ .default = {} }, @"font-style-bold-italic": FontStyle = .{ .default = {} }, -/// Apply a font feature. This can be repeated multiple times to enable -/// multiple font features. You can NOT set multiple font features with -/// a single value (yet). +/// Apply a font feature. This can be repeated multiple times to enable multiple +/// font features. You can NOT set multiple font features with a single value +/// (yet). /// -/// The font feature will apply to all fonts rendered by Ghostty. A -/// future enhancement will allow targeting specific faces. +/// The font feature will apply to all fonts rendered by Ghostty. A future +/// enhancement will allow targeting specific faces. /// -/// A valid value is the name of a feature. Prefix the feature with a -/// "-" to explicitly disable it. Example: "ss20" or "-ss20". +/// A valid value is the name of a feature. Prefix the feature with a `-` to +/// explicitly disable it. Example: `ss20` or `-ss20`. /// -/// To disable programming ligatures, use "-calt" since this is the typical +/// To disable programming ligatures, use `-calt` since this is the typical /// feature name for programming ligatures. To look into what font features /// your font has and what they do, use a font inspection tool such as -/// fontdrop.info. +/// [fontdrop.info](https://fontdrop.info). /// -/// To generally disable most ligatures, use "-calt", "-liga", and "-dlig" -/// (as separate repetitive entries in your config). +/// To generally disable most ligatures, use `-calt`, `-liga`, and `-dlig` (as +/// separate repetitive entries in your config). @"font-feature": RepeatableString = .{}, /// Font size in points @"font-size": u8 = switch (builtin.os.tag) { - // On Mac we default a little bigger since this tends to look better. - // This is purely subjective but this is easy to modify. + // On macOS we default a little bigger since this tends to look better. This + // is purely subjective but this is easy to modify. .macos => 13, else => 12, }, -/// A repeatable configuration to set one or more font variations values -/// for a variable font. A variable font is a single font, usually -/// with a filename ending in "-VF.ttf" or "-VF.otf" that contains -/// one or more configurable axes for things such as weight, slant, -/// etc. Not all fonts support variations; only fonts that explicitly -/// state they are variable fonts will work. +/// A repeatable configuration to set one or more font variations values for +/// a variable font. A variable font is a single font, usually with a filename +/// ending in `-VF.ttf` or `-VF.otf` that contains one or more configurable axes +/// for things such as weight, slant, etc. Not all fonts support variations; +/// only fonts that explicitly state they are variable fonts will work. /// -/// The format of this is "id=value" where "id" is the axis identifier. -/// An axis identifier is always a 4 character string, such as "wght". -/// To get the list of supported axes, look at your font documentation -/// or use a font inspection tool. +/// The format of this is `id=value` where `id` is the axis identifier. An axis +/// identifier is always a 4 character string, such as `wght`. To get the list +/// of supported axes, look at your font documentation or use a font inspection +/// tool. /// -/// Invalid ids and values are usually ignored. For example, if a font -/// only supports weights from 100 to 700, setting "wght=800" will -/// do nothing (it will not be clamped to 700). You must consult your -/// font's documentation to see what values are supported. +/// Invalid ids and values are usually ignored. For example, if a font only +/// supports weights from 100 to 700, setting `wght=800` will do nothing (it +/// will not be clamped to 700). You must consult your font's documentation to +/// see what values are supported. /// -/// Common axes are: "wght" (weight), "slnt" (slant), "ital" (italic), -/// "opsz" (optical size), "wdth" (width), "GRAD" (gradient), etc. +/// Common axes are: `wght` (weight), `slnt` (slant), `ital` (italic), `opsz` +/// (optical size), `wdth` (width), `GRAD` (gradient), etc. @"font-variation": RepeatableFontVariation = .{}, @"font-variation-bold": RepeatableFontVariation = .{}, @"font-variation-italic": RepeatableFontVariation = .{}, @"font-variation-bold-italic": RepeatableFontVariation = .{}, -/// Force one or a range of Unicode codepoints to map to a specific named -/// font. This is useful if you want to support special symbols or if you -/// want to use specific glyphs that render better for your specific font. +/// Force one or a range of Unicode codepoints to map to a specific named font. +/// This is useful if you want to support special symbols or if you want to use +/// specific glyphs that render better for your specific font. /// -/// The syntax is "codepoint=fontname" where "codepoint" is either a -/// single codepoint or a range. Codepoints must be specified as full -/// Unicode hex values, such as "U+ABCD". Codepoints ranges are specified -/// as "U+ABCD-U+DEFG". You can specify multiple ranges for the same font -/// separated by commas, such as "U+ABCD-U+DEFG,U+1234-U+5678=fontname". -/// The font name is the same value as you would use for "font-family". +/// The syntax is `codepoint=fontname` where `codepoint` is either a single +/// codepoint or a range. Codepoints must be specified as full Unicode +/// hex values, such as `U+ABCD`. Codepoints ranges are specified as +/// `U+ABCD-U+DEFG`. You can specify multiple ranges for the same font separated +/// by commas, such as `U+ABCD-U+DEFG,U+1234-U+5678=fontname`. The font name is +/// the same value as you would use for `font-family`. /// /// This configuration can be repeated multiple times to specify multiple /// codepoint mappings. @@ -141,34 +148,34 @@ const c = @cImport({ @"font-codepoint-map": RepeatableCodepointMap = .{}, /// Draw fonts with a thicker stroke, if supported. This is only supported -/// currently on macOS. +/// currently on MacOS. @"font-thicken": bool = false, -/// All of the configurations behavior adjust various metrics determined -/// by the font. The values can be integers (1, -1, etc.) or a percentage -/// (20%, -15%, etc.). In each case, the values represent the amount to -/// change the original value. +/// All of the configurations behavior adjust various metrics determined by the +/// font. The values can be integers (1, -1, etc.) or a percentage (20%, -15%, +/// etc.). In each case, the values represent the amount to change the original +/// value. /// -/// For example, a value of "1" increases the value by 1; it does not set -/// it to literally 1. A value of "20%" increases the value by 20%. And so -/// on. +/// For example, a value of `1` increases the value by 1; it does not set it to +/// literally 1. A value of `20%` increases the value by 20%. And so on. /// -/// There is little to no validation on these values so the wrong values -/// (i.e. "-100%") can cause the terminal to be unusable. Use with caution -/// and reason. +/// There is little to no validation on these values so the wrong values (i.e. +/// `-100%`) can cause the terminal to be unusable. Use with caution and reason. /// /// Some values are clamped to minimum or maximum values. This can make it -/// appear that certain values are ignored. For example, the underline -/// position is clamped to the height of a cell. If you set the underline -/// position so high that it extends beyond the bottom of the cell size, -/// it will be clamped to the bottom of the cell. +/// appear that certain values are ignored. For example, the underline position +/// is clamped to the height of a cell. If you set the underline position so +/// high that it extends beyond the bottom of the cell size, it will be clamped +/// to the bottom of the cell. /// -/// "adjust-cell-height" has some additional behaviors to describe: -/// - The font will be centered vertically in the cell. -/// - The cursor will remain the same size as the font. -/// - Powerline glyphs will be adjusted along with the cell height so -/// that things like status lines continue to look aligned. +/// `adjust-cell-height` has some additional behaviors to describe: /// +/// * The font will be centered vertically in the cell. +/// +/// * The cursor will remain the same size as the font. +/// +/// * Powerline glyphs will be adjusted along with the cell height so +/// that things like status lines continue to look aligned. @"adjust-cell-width": ?MetricModifier = null, @"adjust-cell-height": ?MetricModifier = null, @"adjust-font-baseline": ?MetricModifier = null, @@ -178,49 +185,49 @@ const c = @cImport({ @"adjust-strikethrough-thickness": ?MetricModifier = null, /// The method to use for calculating the cell width of a grapheme cluster. -/// The default value is "unicode" which uses the Unicode standard to -/// determine grapheme width. This results in correct grapheme width but -/// may result in cursor-desync issues with some programs (such as shells) -/// that may use a legacy method such as "wcswidth". +/// The default value is `unicode` which uses the Unicode standard to determine +/// grapheme width. This results in correct grapheme width but may result in +/// cursor-desync issues with some programs (such as shells) that may use a +/// legacy method such as `wcswidth`. /// /// Valid values are: /// -/// - "wcswidth" - Use the wcswidth function to determine grapheme width. +/// * `wcswidth` - Use the wcswidth function to determine grapheme width. /// This maximizes compatibility with legacy programs but may result /// in incorrect grapheme width for certain graphemes such as skin-tone /// emoji, non-English characters, etc. /// -/// Note that this "wcswidth" functionality is based on the libc wcswidth, +/// Note that this `wcswidth` functionality is based on the libc wcswidth, /// not any other libraries with that name. /// -/// - "unicode" - Use the Unicode standard to determine grapheme width. +/// * `unicode` - Use the Unicode standard to determine grapheme width. /// -/// If a running program explicitly enables terminal mode 2027, then -/// "unicode" width will be forced regardless of this configuration. When -/// mode 2027 is reset, this configuration will be used again. +/// If a running program explicitly enables terminal mode 2027, then `unicode` +/// width will be forced regardless of this configuration. When mode 2027 is +/// reset, this configuration will be used again. /// /// This configuration can be changed at runtime but will not affect existing /// printed cells. Only new cells will use the new configuration. @"grapheme-width-method": GraphemeWidthMethod = .unicode, -/// A named theme to use. The available themes are currently hardcoded to -/// the themes that ship with Ghostty. On macOS, this list is in the -/// `Ghostty.app/Contents/Resources/themes` directory. On Linux, this -/// list is in the `share/ghostty/themes` directory (wherever you installed -/// the Ghostty "share" directory. +/// A named theme to use. The available themes are currently hardcoded to the +/// themes that ship with Ghostty. On macOS, this list is in the `Ghostty.app/ +/// Contents/Resources/themes` directory. On Linux, this list is in the `share/ +/// ghostty/themes` directory (wherever you installed the Ghostty "share" +/// directory. /// /// To see a list of available themes, run `ghostty +list-themes`. /// -/// Any additional colors specified via background, foreground, palette, -/// etc. will override the colors specified in the theme. +/// Any additional colors specified via background, foreground, palette, etc. +/// will override the colors specified in the theme. /// -/// This configuration can be changed at runtime, but the new theme will -/// only affect new cells. Existing colored cells will not be updated. -/// Therefore, after changing the theme, you should restart any running -/// programs to ensure they get the new colors. +/// This configuration can be changed at runtime, but the new theme will only +/// affect new cells. Existing colored cells will not be updated. Therefore, +/// after changing the theme, you should restart any running programs to ensure +/// they get the new colors. /// -/// A future update will allow custom themes to be installed in -/// certain directories. +/// A future update will allow custom themes to be installed in certain +/// directories. theme: ?[]const u8 = null, /// Background color for the window. @@ -229,376 +236,366 @@ background: Color = .{ .r = 0x28, .g = 0x2C, .b = 0x34 }, /// Foreground color for the window. foreground: Color = .{ .r = 0xFF, .g = 0xFF, .b = 0xFF }, -/// The foreground and background color for selection. If this is not -/// set, then the selection color is just the inverted window background -/// and foreground (note: not to be confused with the cell bg/fg). +/// The foreground and background color for selection. If this is not set, then +/// the selection color is just the inverted window background and foreground +/// (note: not to be confused with the cell bg/fg). @"selection-foreground": ?Color = null, @"selection-background": ?Color = null, -/// Swap the foreground and background colors of cells for selection. -/// This option overrides the "selection-foreground" and "selection-background" +/// Swap the foreground and background colors of cells for selection. This +/// option overrides the `selection-foreground` and `selection-background` /// options. /// -/// If you select across cells with differing foregrounds and backgrounds, -/// the selection color will vary across the selection. +/// If you select across cells with differing foregrounds and backgrounds, the +/// selection color will vary across the selection. @"selection-invert-fg-bg": bool = false, -/// The minimum contrast ratio between the foreground and background -/// colors. The contrast ratio is a value between 1 and 21. A value of -/// 1 allows for no contrast (i.e. black on black). This value is -/// the contrast ratio as defined by the WCAG 2.0 specification. +/// The minimum contrast ratio between the foreground and background colors. +/// The contrast ratio is a value between 1 and 21. A value of 1 allows for no +/// contrast (i.e. black on black). This value is the contrast ratio as defined +/// by the [WCAG 2.0 specification](https://www.w3.org/TR/WCAG20/). /// -/// If you want to avoid invisible text (same color as background), -/// a value of 1.1 is a good value. If you want to avoid text that is -/// difficult to read, a value of 3 or higher is a good value. The higher -/// the value, the more likely that text will become black or white. +/// If you want to avoid invisible text (same color as background), a value of +/// 1.1 is a good value. If you want to avoid text that is difficult to read, a +/// value of 3 or higher is a good value. The higher the value, the more likely +/// that text will become black or white. /// /// This value does not apply to Emoji or images. @"minimum-contrast": f64 = 1, -/// Color palette for the 256 color form that many terminal applications -/// use. The syntax of this configuration is "N=HEXCODE" where "n" -/// is 0 to 255 (for the 256 colors) and HEXCODE is a typical RGB -/// color code such as "#AABBCC". The 0 to 255 correspond to the -/// terminal color table. +/// Color palette for the 256 color form that many terminal applications use. +/// The syntax of this configuration is `N=HEXCODE` where `N` is 0 to 255 (for +/// the 256 colors in the terminal color table) and `HEXCODE` is a typical RGB +/// color code such as `#AABBCC`. /// -/// For definitions on all the codes: -/// https://www.ditig.com/256-colors-cheat-sheet +/// For definitions on all the codes [see this cheat +/// sheet](https://www.ditig.com/256-colors-cheat-sheet). palette: Palette = .{}, /// The color of the cursor. If this is not set, a default will be chosen. @"cursor-color": ?Color = null, -/// The opacity level (opposite of transparency) of the cursor. -/// A value of 1 is fully opaque and a value of 0 is fully transparent. -/// A value less than 0 or greater than 1 will be clamped to the nearest -/// valid value. Note that a sufficiently small value such as 0.3 may be -/// effectively invisible and may make it difficult to find the cursor. +/// The opacity level (opposite of transparency) of the cursor. A value of 1 +/// is fully opaque and a value of 0 is fully transparent. A value less than 0 +/// or greater than 1 will be clamped to the nearest valid value. Note that a +/// sufficiently small value such as 0.3 may be effectively invisible and may +/// make it difficult to find the cursor. @"cursor-opacity": f64 = 1.0, -/// The style of the cursor. This sets the default style. A running -/// programn can still request an explicit cursor style using escape -/// sequences (such as CSI q). Shell configurations will often request -/// specific cursor styles. +/// The style of the cursor. This sets the default style. A running programn can +/// still request an explicit cursor style using escape sequences (such as `CSI +/// q`). Shell configurations will often request specific cursor styles. /// -/// Note that shell integration will automatically set the cursor to a bar -/// at a prompt, regardless of this configuration. You can disable that -/// behavior by specifying `shell-integration-features = no-cursor` -/// or disabling shell integration entirely. +/// Note that shell integration will automatically set the cursor to a bar at +/// a prompt, regardless of this configuration. You can disable that behavior +/// by specifying `shell-integration-features = no-cursor` or disabling shell +/// integration entirely. @"cursor-style": terminal.Cursor.Style = .block, -/// Sets the default blinking state of the cursor. This is just the -/// default state; running programs may override the cursor style -/// using DECSCUSR (CSI q). +/// Sets the default blinking state of the cursor. This is just the default +/// state; running programs may override the cursor style using `DECSCUSR` (`CSI +/// q`). /// -/// If this is not set, the cursor blinks by default. Note that -/// this is not the same as a "true" value, as noted below. +/// If this is not set, the cursor blinks by default. Note that this is not the +/// same as a "true" value, as noted below. /// -/// If this is not set at all (null), then Ghostty will respect -/// DEC Mode 12 (AT&T cursor blink) as an alternate approach to -/// turning blinking on/off. If this is set to any value other -/// than null, DEC mode 12 will be ignored but DECSCUSR will still -/// be respected. +/// If this is not set at all (`null`), then Ghostty will respect DEC Mode 12 +/// (AT&T cursor blink) as an alternate approach to turning blinking on/off. If +/// this is set to any value other than null, DEC mode 12 will be ignored but +/// `DECSCUSR` will still be respected. @"cursor-style-blink": ?bool = null, -/// The color of the text under the cursor. If this is not set, a default -/// will be chosen. +/// The color of the text under the cursor. If this is not set, a default will +/// be chosen. @"cursor-text": ?Color = null, -/// Enables the ability to move the cursor at prompts by using alt+click -/// on Linux and option+click on macOS. +/// Enables the ability to move the cursor at prompts by using `alt+click` on +/// Linux and `option+click` on macOS. /// /// This feature requires shell integration (specifically prompt marking -/// via OSC 133) and only works in primary screen mode. Alternate screen -/// applications like vim usually have their own version of this feature -/// but this configuration doesn't control that. +/// via `OSC 133`) and only works in primary screen mode. Alternate screen +/// applications like vim usually have their own version of this feature but +/// this configuration doesn't control that. /// /// It should be noted that this feature works by translating your desired /// position into a series of synthetic arrow key movements, so some weird -/// behavior around edge cases are to be expected. This is unfortunately -/// how this feature is implemented across terminals because there isn't -/// any other way to implement it. +/// behavior around edge cases are to be expected. This is unfortunately how +/// this feature is implemented across terminals because there isn't any other +/// way to implement it. @"cursor-click-to-move": bool = true, -/// Hide the mouse immediately when typing. The mouse becomes visible -/// again when the mouse is used. The mouse is only hidden if the mouse -/// cursor is over the active terminal surface. +/// Hide the mouse immediately when typing. The mouse becomes visible again when +/// the mouse is used. The mouse is only hidden if the mouse cursor is over the +/// active terminal surface. @"mouse-hide-while-typing": bool = false, -/// Determines whether running programs can detect the shift key pressed -/// with a mouse click. Typically, the shift key is used to extend mouse -/// selection. +/// Determines whether running programs can detect the shift key pressed with a +/// mouse click. Typically, the shift key is used to extend mouse selection. /// -/// The default value of "false" means that the shift key is not sent -/// with the mouse protocol and will extend the selection. This value -/// can be conditionally overridden by the running program with the -/// XTSHIFTESCAPE sequence. +/// The default value of `false` means that the shift key is not sent with +/// the mouse protocol and will extend the selection. This value can be +/// conditionally overridden by the running program with the `XTSHIFTESCAPE` +/// sequence. /// -/// The value "true" means that the shift key is sent with the mouse -/// protocol but the running program can override this behavior with -/// XTSHIFTESCAPE. +/// The value `true` means that the shift key is sent with the mouse protocol +/// but the running program can override this behavior with `XTSHIFTESCAPE`. /// -/// The value "never" is the same as "false" but the running program -/// cannot override this behavior with XTSHIFTESCAPE. The value "always" -/// is the same as "true" but the running program cannot override this -/// behavior with XTSHIFTESCAPE. +/// The value `never` is the same as `false` but the running program cannot +/// override this behavior with `XTSHIFTESCAPE`. The value `always` is the +/// same as `true` but the running program cannot override this behavior with +/// `XTSHIFTESCAPE`. /// -/// If you always want shift to extend mouse selection even if the -/// program requests otherwise, set this to "never". +/// If you always want shift to extend mouse selection even if the program +/// requests otherwise, set this to `never`. @"mouse-shift-capture": MouseShiftCapture = .false, -/// The opacity level (opposite of transparency) of the background. -/// A value of 1 is fully opaque and a value of 0 is fully transparent. -/// A value less than 0 or greater than 1 will be clamped to the nearest -/// valid value. +/// The opacity level (opposite of transparency) of the background. A value of +/// 1 is fully opaque and a value of 0 is fully transparent. A value less than 0 +/// or greater than 1 will be clamped to the nearest valid value. /// -/// Changing this value at runtime (and reloading config) will only -/// affect new windows, tabs, and splits. +/// Changing this value at runtime (and reloading config) will only affect new +/// windows, tabs, and splits. @"background-opacity": f64 = 1.0, -/// A positive value enables blurring of the background when -/// background-opacity is less than 1. The value is the blur radius to -/// apply. A value of 20 is reasonable for a good looking blur. -/// Higher values will cause strange rendering issues as well as -/// performance issues. +/// A positive value enables blurring of the background when background-opacity +/// is less than 1. The value is the blur radius to apply. A value of 20 +/// is reasonable for a good looking blur. Higher values will cause strange +/// rendering issues as well as performance issues. /// /// This is only supported on macOS. @"background-blur-radius": u8 = 0, /// The opacity level (opposite of transparency) of an unfocused split. -/// Unfocused splits by default are slightly faded out to make it easier -/// to see which split is focused. To disable this feature, set this -/// value to 1. +/// Unfocused splits by default are slightly faded out to make it easier to see +/// which split is focused. To disable this feature, set this value to 1. /// -/// A value of 1 is fully opaque and a value of 0 is fully transparent. -/// Because "0" is not useful (it makes the window look very weird), the -/// minimum value is 0.15. This value still looks weird but you can at least -/// see what's going on. A value outside of the range 0.15 to 1 will be -/// clamped to the nearest valid value. +/// A value of 1 is fully opaque and a value of 0 is fully transparent. Because +/// "0" is not useful (it makes the window look very weird), the minimum value +/// is 0.15. This value still looks weird but you can at least see what's going +/// on. A value outside of the range 0.15 to 1 will be clamped to the nearest +/// valid value. @"unfocused-split-opacity": f64 = 0.7, // The color to dim the unfocused split. Unfocused splits are dimmed by -// rendering a semi-transparent rectangle over the split. This sets -// the color of that rectangle and can be used to carefully control -// the dimming effect. +// rendering a semi-transparent rectangle over the split. This sets the color of +// that rectangle and can be used to carefully control the dimming effect. // // This will default to the background color. @"unfocused-split-fill": ?Color = null, -/// The command to run, usually a shell. If this is not an absolute path, -/// it'll be looked up in the PATH. If this is not set, a default will -/// be looked up from your system. The rules for the default lookup are: +/// The command to run, usually a shell. If this is not an absolute path, it'll +/// be looked up in the `PATH`. If this is not set, a default will be looked up +/// from your system. The rules for the default lookup are: /// -/// - SHELL environment variable -/// - passwd entry (user information) +/// * `SHELL` environment variable /// -/// This can contain additional arguments to run the command with. -/// If additional arguments are provided, the command will be executed -/// using "/bin/sh -c". Ghostty does not do any shell command parsing. +/// * `passwd` entry (user information) /// -/// If you're using the `ghostty` CLI there is also a shortcut -/// to run a command with argumens directly: you can use the `-e` -/// flag. For example: `ghostty -e fish --with --custom --args`. +/// This can contain additional arguments to run the command with. If additional +/// arguments are provided, the command will be executed using `/bin/sh -c`. +/// Ghostty does not do any shell command parsing. +/// +/// If you're using the `ghostty` CLI there is also a shortcut to run a command +/// with argumens directly: you can use the `-e` flag. For example: `ghostty -e +/// fish --with --custom --args`. command: ?[]const u8 = null, -/// If true, keep the terminal open after the command exits. Normally, -/// the terminal window closes when the running command (such as a shell) -/// exits. With this true, the terminal window will stay open until any -/// keypress is received. +/// If true, keep the terminal open after the command exits. Normally, the +/// terminal window closes when the running command (such as a shell) exits. +/// With this true, the terminal window will stay open until any keypress is +/// received. /// /// This is primarily useful for scripts or debugging. @"wait-after-command": bool = false, -/// The number of milliseconds of runtime below which we consider a process -/// exit to be abnormal. This is used to show an error message when the -/// process exits too quickly. +/// The number of milliseconds of runtime below which we consider a process exit +/// to be abnormal. This is used to show an error message when the process exits +/// too quickly. /// -/// On Linux, this must be paired with a non-zero exit code. On macOS, -/// we allow any exit code because of the way shell processes are launched -/// via the login command. +/// On Linux, this must be paired with a non-zero exit code. On macOS, we allow +/// any exit code because of the way shell processes are launched via the login +/// command. @"abnormal-command-exit-runtime": u32 = 250, -/// Match a regular expression against the terminal text and associate -/// clicking it with an action. This can be used to match URLs, file paths, -/// etc. Actions can be opening using the system opener (i.e. "open" or -/// "xdg-open") or executing any arbitrary binding action. +/// Match a regular expression against the terminal text and associate clicking +/// it with an action. This can be used to match URLs, file paths, etc. Actions +/// can be opening using the system opener (i.e. `open` or `xdg-open`) or +/// executing any arbitrary binding action. /// -/// Links that are configured earlier take precedence over links that -/// are configured later. +/// Links that are configured earlier take precedence over links that are +/// configured later. /// -/// A default link that matches a URL and opens it in the system opener -/// always exists. This can be disabled using "link-url". +/// A default link that matches a URL and opens it in the system opener always +/// exists. This can be disabled using `link-url`. /// /// TODO: This can't currently be set! link: RepeatableLink = .{}, -/// Enable URL matching. URLs are matched on hover and open using the -/// default system application for the linked URL. +/// Enable URL matching. URLs are matched on hover and open using the default +/// system application for the linked URL. /// -/// The URL matcher is always lowest priority of any configured links -/// (see "link"). If you want to customize URL matching, use "link" -/// and disable this. +/// The URL matcher is always lowest priority of any configured links (see +/// `link`). If you want to customize URL matching, use `link` and disable this. @"link-url": bool = true, -/// Start new windows in fullscreen. This setting applies to new -/// windows and does not apply to tabs, splits, etc. However, this -/// setting will apply to all new windows, not just the first one. +/// Start new windows in fullscreen. This setting applies to new windows and +/// does not apply to tabs, splits, etc. However, this setting will apply to all +/// new windows, not just the first one. /// -/// On macOS, this always creates the window in native fullscreen. -/// Non-native fullscreen is not currently supported with this -/// setting. +/// On macOS, this always creates the window in native fullscreen. Non-native +/// fullscreen is not currently supported with this setting. fullscreen: bool = false, -/// The title Ghostty will use for the window. This will force the title -/// of the window to be this title at all times and Ghostty will ignore any -/// set title escape sequences programs (such as Neovim) may send. +/// The title Ghostty will use for the window. This will force the title of the +/// window to be this title at all times and Ghostty will ignore any set title +/// escape sequences programs (such as Neovim) may send. title: ?[:0]const u8 = null, /// The setting that will change the application class value. /// -/// This controls the class field of the WM_CLASS X11 property (when running +/// This controls the class field of the `WM_CLASS` X11 property (when running /// under X11), and the Wayland application ID (when running under Wayland). /// /// Note that changing this value between invocations will create new, separate -/// instances, of Ghostty when running with --gtk-single-instance=true. See -/// that option for more details. +/// instances, of Ghostty when running with `gtk-single-instance=true`. See that +/// option for more details. /// -/// The class name must follow the GTK requirements defined here: -/// https://docs.gtk.org/gio/type_func.Application.id_is_valid.html +/// The class name must follow the requirements defined [in the GTK +/// documentation](https://docs.gtk.org/gio/type_func.Application.id_is_valid.html). /// -/// The default is "com.mitchellh.ghostty". +/// The default is `com.mitchellh.ghostty`. /// /// This only affects GTK builds. class: ?[:0]const u8 = null, -/// This controls the instance name field of the WM_CLASS X11 property when +/// This controls the instance name field of the `WM_CLASS` X11 property when /// running under X11. It has no effect otherwise. /// -/// The default is "ghostty". +/// The default is `ghostty`. /// /// This only affects GTK builds. @"x11-instance-name": ?[:0]const u8 = null, /// The directory to change to after starting the command. /// -/// This setting is secondary to the "window-inherit-working-directory" +/// This setting is secondary to the `window-inherit-working-directory` /// setting. If a previous Ghostty terminal exists in the same process, -/// "window-inherit-working-directory" will take precedence. Otherwise, -/// this setting will be used. Typically, this setting is used only -/// for the first window. +/// `window-inherit-working-directory` will take precedence. Otherwise, this +/// setting will be used. Typically, this setting is used only for the first +/// window. /// -/// The default is "inherit" except in special scenarios listed next. -/// On macOS, if Ghostty can detect it is launched from launchd -/// (double-clicked) or `open`, then it defaults to "home". -/// On Linux with GTK, if Ghostty can detect it was launched from -/// a desktop launcher, then it defaults to "home". +/// The default is `inherit` except in special scenarios listed next. On macOS, +/// if Ghostty can detect it is launched from launchd (double-clicked) or +/// `open`, then it defaults to `home`. On Linux with GTK, if Ghostty can detect +/// it was launched from a desktop launcher, then it defaults to `home`. /// -/// The value of this must be an absolute value or one of the special -/// values below: +/// The value of this must be an absolute value or one of the special values +/// below: /// -/// - "home" - The home directory of the executing user. -/// - "inherit" - The working directory of the launching process. +/// * `home` - The home directory of the executing user. /// +/// * `inherit` - The working directory of the launching process. @"working-directory": ?[]const u8 = null, -/// Key bindings. The format is "trigger=action". Duplicate triggers -/// will overwrite previously set values. +/// Key bindings. The format is `trigger=action`. Duplicate triggers will +/// overwrite previously set values. /// -/// Trigger: "+"-separated list of keys and modifiers. Example: -/// "ctrl+a", "ctrl+shift+b", "up". Some notes: +/// Trigger: `+`-separated list of keys and modifiers. Example: `ctrl+a`, +/// `ctrl+shift+b`, `up`. Some notes: /// -/// - modifiers cannot repeat, "ctrl+ctrl+a" is invalid. -/// - modifiers and keys can be in any order, "shift+a+ctrl" is weird, +/// * modifiers cannot repeat, `ctrl+ctrl+a` is invalid. +/// +/// * modifiers and keys can be in any order, `shift+a+ctrl` is *weird*, /// but valid. -/// - only a single key input is allowed, "ctrl+a+b" is invalid. /// -/// Valid modifiers are "shift", "ctrl" (alias: "control"), -/// "alt" (alias: "opt", "option"), and "super" (alias: "cmd", "command"). -/// You may use the modifier or the alias. When debugging keybinds, -/// the non-aliased modifier will always be used in output. +/// * only a single key input is allowed, `ctrl+a+b` is invalid. /// -/// Action is the action to take when the trigger is satisfied. It takes -/// the format "action" or "action:param". The latter form is only valid -/// if the action requires a parameter. +/// Valid modifiers are `shift`, `ctrl` (alias: `control`), `alt` (alias: `opt`, +/// `option`), and `super` (alias: `cmd`, `command`). You may use the modifier +/// or the alias. When debugging keybinds, the non-aliased modifier will always +/// be used in output. /// -/// - "ignore" - Do nothing, ignore the key input. This can be used to +/// Action is the action to take when the trigger is satisfied. It takes the +/// format `action` or `action:param`. The latter form is only valid if the +/// action requires a parameter. +/// +/// * `ignore` - Do nothing, ignore the key input. This can be used to /// black hole certain inputs to have no effect. -/// - "unbind" - Remove the binding. This makes it so the previous action +/// +/// * `unbind` - Remove the binding. This makes it so the previous action /// is removed, and the key will be sent through to the child command /// if it is printable. -/// - "csi:text" - Send a CSI sequence. i.e. "csi:A" sends "cursor up". -/// - "esc:text" - Send an Escape sequence. i.e. "esc:d" deletes to the +/// +/// * `csi:text` - Send a CSI sequence. i.e. `csi:A` sends "cursor up". +/// +/// * `esc:text` - Send an escape sequence. i.e. `esc:d` deletes to the /// end of the word to the right. /// /// Some notes for the action: /// -/// - The parameter is taken as-is after the ":". Double quotes or +/// * The parameter is taken as-is after the `:`. Double quotes or /// other mechanisms are included and NOT parsed. If you want to /// send a string value that includes spaces, wrap the entire -/// trigger/action in double quotes. Example: --keybind="up=csi:A B" +/// trigger/action in double quotes. Example: `--keybind="up=csi:A B"` /// /// There are some additional special values that can be specified for /// keybind: /// -/// - `keybind = clear` will clear all set keybindings. Warning: this +/// * `keybind=clear` will clear all set keybindings. Warning: this /// removes ALL keybindings up to this point, including the default /// keybindings. -/// keybind: Keybinds = .{}, -/// Window padding. This applies padding between the terminal cells and -/// the window border. The "x" option applies to the left and right -/// padding and the "y" option is top and bottom. The value is in points, -/// meaning that it will be scaled appropriately for screen DPI. +/// Window padding. This applies padding between the terminal cells and the +/// window border. The `x` option applies to the left and right padding and the +/// `y` option is top and bottom. The value is in points, meaning that it will +/// be scaled appropriately for screen DPI. /// -/// If this value is set too large, the screen will render nothing, because -/// the grid will be completely squished by the padding. It is up to you -/// as the user to pick a reasonable value. If you pick an unreasonable -/// value, a warning will appear in the logs. +/// If this value is set too large, the screen will render nothing, because the +/// grid will be completely squished by the padding. It is up to you as the user +/// to pick a reasonable value. If you pick an unreasonable value, a warning +/// will appear in the logs. @"window-padding-x": u32 = 2, @"window-padding-y": u32 = 2, -/// The viewport dimensions are usually not perfectly divisible by -/// the cell size. In this case, some extra padding on the end of a -/// column and the bottom of the final row may exist. If this is true, -/// then this extra padding is automatically balanced between all four -/// edges to minimize imbalance on one side. If this is false, the top -/// left grid cell will always hug the edge with zero padding other than -/// what may be specified with the other "window-padding" options. +/// The viewport dimensions are usually not perfectly divisible by the cell +/// size. In this case, some extra padding on the end of a column and the bottom +/// of the final row may exist. If this is `true`, then this extra padding +/// is automatically balanced between all four edges to minimize imbalance on +/// one side. If this is `false`, the top left grid cell will always hug the +/// edge with zero padding other than what may be specified with the other +/// `window-padding` options. /// -/// If other "window-padding" fields are set and this is true, this will -/// still apply. The other padding is applied first and may affect how -/// many grid cells actually exist, and this is applied last in order -/// to balance the padding given a certain viewport size and grid cell size. +/// If other `window-padding` fields are set and this is `true`, this will still +/// apply. The other padding is applied first and may affect how many grid cells +/// actually exist, and this is applied last in order to balance the padding +/// given a certain viewport size and grid cell size. @"window-padding-balance": bool = false, -/// If true, new windows and tabs will inherit the working directory of -/// the previously focused window. If no window was previously focused, -/// the default working directory will be used (the "working-directory" -/// option). +/// If true, new windows and tabs will inherit the working directory of the +/// previously focused window. If no window was previously focused, the default +/// working directory will be used (the `working-directory` option). @"window-inherit-working-directory": bool = true, /// If true, new windows and tabs will inherit the font size of the previously -/// focused window. If no window was previously focused, the default -/// font size will be used. If this is false, the default font size -/// specified in the configuration "font-size" will be used. +/// focused window. If no window was previously focused, the default font size +/// will be used. If this is false, the default font size specified in the +/// configuration `font-size` will be used. @"window-inherit-font-size": bool = true, /// If false, windows won't have native decorations, i.e. titlebar and /// borders. @"window-decoration": bool = true, -/// The theme to use for the windows. The default is "system" which -/// means that whatever the system theme is will be used. This can -/// also be set to "light" or "dark" to force a specific theme regardless -/// of the system settings. +/// The theme to use for the windows. The default is `system` which means that +/// whatever the system theme is will be used. This can also be set to `light` +/// or `dark` to force a specific theme regardless of the system settings. /// -/// This is currently only supported on macOS and linux. +/// This is currently only supported on macOS and Linux. @"window-theme": WindowTheme = .system, -/// The colorspace to use for the terminal window. The default is "srgb" -/// but this can also be set to "display-p3" to use the Display P3 -/// colorspace. +/// The colorspace to use for the terminal window. The default is `srgb` but +/// this can also be set to `display-p3` to use the Display P3 colorspace. /// /// Changing this value at runtime will only affect new windows. /// @@ -607,69 +604,72 @@ keybind: Keybinds = .{}, /// The initial window size. This size is in terminal grid cells by default. /// -/// We don't currently support specifying a size in pixels but a future -/// change can enable that. If this isn't specified, the app runtime will -/// determine some default size. +/// We don't currently support specifying a size in pixels but a future change +/// can enable that. If this isn't specified, the app runtime will determine +/// some default size. /// -/// Note that the window manager may put limits on the size or override -/// the size. For example, a tiling window manager may force the window -/// to be a certain size to fit within the grid. There is nothing Ghostty -/// will do about this, but it will make an effort. +/// Note that the window manager may put limits on the size or override the +/// size. For example, a tiling window manager may force the window to be a +/// certain size to fit within the grid. There is nothing Ghostty will do about +/// this, but it will make an effort. /// -/// This will not affect new tabs, splits, or other nested terminal -/// elements. This only affects the initial window size of any new window. -/// Changing this value will not affect the size of the window after -/// it has been created. This is only used for the initial size. +/// This will not affect new tabs, splits, or other nested terminal elements. +/// This only affects the initial window size of any new window. Changing this +/// value will not affect the size of the window after it has been created. This +/// is only used for the initial size. /// -/// BUG: On Linux with GTK, the calculated window size will not properly -/// take into account window decorations. As a result, the grid dimensions -/// will not exactly match this configuration. If window decorations are -/// disabled (see window-decorations), then this will work as expected. +/// BUG: On Linux with GTK, the calculated window size will not properly take +/// into account window decorations. As a result, the grid dimensions will not +/// exactly match this configuration. If window decorations are disabled (see +/// window-decorations), then this will work as expected. /// /// Windows smaller than 10 wide by 4 high are not allowed. @"window-height": u32 = 0, @"window-width": u32 = 0, -/// Whether to enable saving and restoring window state. Window state -/// includes their position, size, tabs, splits, etc. Some window state -/// requires shell integration, such as preserving working directories. -/// See shell-integration for more information. +/// Whether to enable saving and restoring window state. Window state includes +/// their position, size, tabs, splits, etc. Some window state requires shell +/// integration, such as preserving working directories. See `shell-integration` +/// for more information. /// /// There are three valid values for this configuration: -/// - "default" will use the default system behavior. On macOS, this +/// +/// * `default` will use the default system behavior. On macOS, this /// will only save state if the application is forcibly terminated /// or if it is configured systemwide via Settings.app. -/// - "never" will never save window state. -/// - "always" will always save window state whenever Ghostty is exited. /// -/// If you change this value to "never" while Ghostty is not running, -/// the next Ghostty launch will NOT restore the window state. +/// * `never` will never save window state. /// -/// If you change this value to "default" while Ghostty is not running -/// and the previous exit saved state, the next Ghostty launch will -/// still restore the window state. This is because Ghostty cannot know -/// if the previous exit was due to a forced save or not (macOS doesn't -/// provide this information). +/// * `always` will always save window state whenever Ghostty is exited. /// -/// If you change this value so that window state is saved while Ghostty -/// is not running, the previous window state will not be restored because -/// Ghostty only saves state on exit if this is enabled. +/// If you change this value to `never` while Ghostty is not running, the next +/// Ghostty launch will NOT restore the window state. /// -/// The default value is "default". +/// If you change this value to `default` while Ghostty is not running and the +/// previous exit saved state, the next Ghostty launch will still restore the +/// window state. This is because Ghostty cannot know if the previous exit was +/// due to a forced save or not (macOS doesn't provide this information). +/// +/// If you change this value so that window state is saved while Ghostty is not +/// running, the previous window state will not be restored because Ghostty only +/// saves state on exit if this is enabled. +/// +/// The default value is `default`. /// /// This is currently only supported on macOS. This has no effect on Linux. @"window-save-state": WindowSaveState = .default, -/// Resize the window in discrete increments of the focused surface's -/// cell size. If this is disabled, surfaces are resized in pixel increments. -/// Currently only supported on macOS. +/// Resize the window in discrete increments of the focused surface's cell size. +/// If this is disabled, surfaces are resized in pixel increments. Currently +/// only supported on macOS. @"window-step-resize": bool = false, /// The position where new tabs are created. Valid values: /// -/// - "current" - Insert the new tab after the currently focused tab, +/// * `current` - Insert the new tab after the currently focused tab, /// or at the end if there are no focused tabs. -/// - "end" - Insert the new tab at the end of the tab list. +/// +/// * `end` - Insert the new tab at the end of the tab list. /// /// This configuration currently only works with GTK. @"window-new-tab-position": WindowNewTabPosition = .current, @@ -678,22 +678,21 @@ keybind: Keybinds = .{}, /// manager's simple titlebar. The behavior of this option will vary with your /// window manager. /// -/// This option does nothing when window-decoration is false or when running -/// under MacOS. +/// This option does nothing when `window-decoration` is false or when running +/// under macOS. /// /// Changing this value at runtime and reloading the configuration will only /// affect new windows. @"gtk-titlebar": bool = true, -/// Whether to allow programs running in the terminal to read/write to -/// the system clipboard (OSC 52, for googling). The default is to -/// allow clipboard reading after prompting the user and allow writing -/// unconditionally. +/// Whether to allow programs running in the terminal to read/write to the +/// system clipboard (OSC 52, for googling). The default is to allow clipboard +/// reading after prompting the user and allow writing unconditionally. @"clipboard-read": ClipboardAccess = .ask, @"clipboard-write": ClipboardAccess = .allow, -/// Trims trailing whitespace on data that is copied to the clipboard. -/// This does not affect data sent to the clipboard via "clipboard-write". +/// Trims trailing whitespace on data that is copied to the clipboard. This does +/// not affect data sent to the clipboard via `clipboard-write`. @"clipboard-trim-trailing-spaces": bool = true, /// Require confirmation before pasting text that appears unsafe. This helps @@ -701,108 +700,114 @@ keybind: Keybinds = .{}, /// commands by pasting text with newlines. @"clipboard-paste-protection": bool = true, -/// If true, bracketed pastes will be considered safe. By default, -/// bracketed pastes are considered safe. "Bracketed" pastes are pastes -/// while the running program has bracketed paste mode enabled (a setting -/// set by the running program, not the terminal emulator). +/// If true, bracketed pastes will be considered safe. By default, bracketed +/// pastes are considered safe. "Bracketed" pastes are pastes while the running +/// program has bracketed paste mode enabled (a setting set by the running +/// program, not the terminal emulator). @"clipboard-paste-bracketed-safe": bool = true, -/// The total amount of bytes that can be used for image data (i.e. -/// the Kitty image protocol) per terminal scren. The maximum value -/// is 4,294,967,295 (4GB). The default is 320MB. If this is set to zero, -/// then all image protocols will be disabled. +/// The total amount of bytes that can be used for image data (i.e. the Kitty +/// image protocol) per terminal scren. The maximum value is 4,294,967,295 +/// (4GiB). The default is 320MB. If this is set to zero, then all image +/// protocols will be disabled. /// -/// This value is separate for primary and alternate screens so the -/// effective limit per surface is double. +/// This value is separate for primary and alternate screens so the effective +/// limit per surface is double. @"image-storage-limit": u32 = 320 * 1000 * 1000, -/// Whether to automatically copy selected text to the clipboard. "true" -/// will only copy on systems that support a selection clipboard. +/// Whether to automatically copy selected text to the clipboard. `true` will +/// only copy on systems that support a selection clipboard. /// -/// The value "clipboard" will copy to the system clipboard, making this -/// work on macOS. Note that middle-click will also paste from the system -/// clipboard in this case. +/// The value `clipboard` will copy to the system clipboard, making this work on +/// macOS. Note that middle-click will also paste from the system clipboard in +/// this case. /// -/// Note that if this is disabled, middle-click paste will also be -/// disabled. +/// Note that if this is disabled, middle-click paste will also be disabled. @"copy-on-select": CopyOnSelect = .true, /// The time in milliseconds between clicks to consider a click a repeat -/// (double, triple, etc.) or an entirely new single click. A value of -/// zero will use a platform-specific default. The default on macOS -/// is determined by the OS settings. On every other platform it is 500ms. +/// (double, triple, etc.) or an entirely new single click. A value of zero will +/// use a platform-specific default. The default on macOS is determined by the +/// OS settings. On every other platform it is 500ms. @"click-repeat-interval": u32 = 0, /// Additional configuration files to read. This configuration can be repeated /// to read multiple configuration files. Configuration files themselves can -/// load more configuration files. Paths are relative to the file containing -/// the `config-file` directive. For command-line arguments, paths are -/// relative to the current working directory. +/// load more configuration files. Paths are relative to the file containing the +/// `config-file` directive. For command-line arguments, paths are relative to +/// the current working directory. /// -/// Cycles are not allowed. If a cycle is detected, an error will be logged -/// and the configuration file will be ignored. +/// Cycles are not allowed. If a cycle is detected, an error will be logged and +/// the configuration file will be ignored. @"config-file": RepeatablePath = .{}, -/// Confirms that a surface should be closed before closing it. This defaults -/// to true. If set to false, surfaces will close without any confirmation. +/// Confirms that a surface should be closed before closing it. This defaults to +/// true. If set to false, surfaces will close without any confirmation. @"confirm-close-surface": bool = true, -/// Whether or not to quit after the last window is closed. This defaults -/// to false. Currently only supported on macOS. On Linux, the process always -/// exits after the last window is closed. +/// Whether or not to quit after the last window is closed. This defaults to +/// false. Currently only supported on macOS. On Linux, the process always exits +/// after the last window is closed. @"quit-after-last-window-closed": bool = false, -/// Whether to enable shell integration auto-injection or not. Shell -/// integration greatly enhances the terminal experience by enabling -/// a number of features: +/// Whether to enable shell integration auto-injection or not. Shell integration +/// greatly enhances the terminal experience by enabling a number of features: /// /// * Working directory reporting so new tabs, splits inherit the /// previous terminal's working directory. +/// /// * Prompt marking that enables the "jump_to_prompt" keybinding. +/// /// * If you're sitting at a prompt, closing a terminal will not ask /// for confirmation. +/// /// * Resizing the window with a complex prompt usually paints much /// better. /// /// Allowable values are: /// -/// * "none" - Do not do any automatic injection. You can still manually +/// * `none` - Do not do any automatic injection. You can still manually /// configure your shell to enable the integration. -/// * "detect" - Detect the shell based on the filename. -/// * "fish", "zsh" - Use this specific shell injection scheme. /// -/// The default value is "detect". +/// * `detect` - Detect the shell based on the filename. +/// +/// * `fish`, `zsh` - Use this specific shell injection scheme. +/// +/// The default value is `detect`. @"shell-integration": ShellIntegration = .detect, /// Shell integration features to enable if shell integration itself is enabled. -/// The format of this is a list of features to enable separated by commas. -/// If you prefix a feature with "no-" then it is disabled. If you omit -/// a feature, its default value is used, so you must explicitly disable -/// features you don't want. +/// The format of this is a list of features to enable separated by commas. If +/// you prefix a feature with `no-` then it is disabled. If you omit a feature, +/// its default value is used, so you must explicitly disable features you don't +/// want. /// /// Available features: /// -/// - "cursor" - Set the cursor to a blinking bar at the prompt. -/// - "sudo" - Set sudo wrapper to preserve terminfo. +/// * `cursor` - Set the cursor to a blinking bar at the prompt. /// -/// Example: "cursor", "no-cursor", "sudo", "no-sudo" +/// * `sudo` - Set sudo wrapper to preserve terminfo. +/// +/// Example: `cursor`, `no-cursor`, `sudo`, `no-sudo` @"shell-integration-features": ShellIntegrationFeatures = .{}, /// Sets the reporting format for OSC sequences that request color information. -/// Ghostty currently supports OSC 10 (foreground), OSC 11 (background), and OSC -/// 4 (256 color palette) queries, and by default the reported values are -/// scaled-up RGB values, where each component are 16 bits. This is how most -/// terminals report these values. However, some legacy applications may require -/// 8-bit, unscaled, components. We also support turning off reporting +/// Ghostty currently supports OSC 10 (foreground), OSC 11 (background), and +/// OSC 4 (256 color palette) queries, and by default the reported values +/// are scaled-up RGB values, where each component are 16 bits. This is how +/// most terminals report these values. However, some legacy applications may +/// require 8-bit, unscaled, components. We also support turning off reporting /// alltogether. The components are lowercase hex values. /// /// Allowable values are: /// -/// * "none" - OSC 4/10/11 queries receive no reply -/// * "8-bit" - Color components are return unscaled, i.e. rr/gg/bb -/// * "16-bit" - Color components are returned scaled, e.g. rrrr/gggg/bbbb +/// * `none` - OSC 4/10/11 queries receive no reply /// -/// The default value is "16-bit". +/// * `8-bit` - Color components are return unscaled, i.e. `rr/gg/bb` +/// +/// * `16-bit` - Color components are returned scaled, e.g. `rrrr/gggg/bbbb` +/// +/// The default value is `16-bit`. @"osc-color-report-format": OSCColorReportFormat = .@"16-bit", /// If true, allows the "KAM" mode (ANSI mode 2) to be used within @@ -831,7 +836,7 @@ keybind: Keybinds = .{}, /// related to shader compilation will not show up as configuration errors /// and only show up in the log, since shader compilation happens after /// configuration loading on the dedicated render thread. For interactive -/// development, use Shadertoy.com. +/// development, use [shadertoy.com](https://shadertoy.com). /// /// This can be repeated multiple times to load multiple shaders. The shaders /// will be run in the order they are specified. @@ -840,16 +845,16 @@ keybind: Keybinds = .{}, /// affect new windows, tabs, and splits. @"custom-shader": RepeatablePath = .{}, -/// If true (default), the focused terminal surface will run an animation +/// If `true` (default), the focused terminal surface will run an animation /// loop when custom shaders are used. This uses slightly more CPU (generally /// less than 10%) but allows the shader to animate. This only runs if there /// are custom shaders and the terminal is focused. /// -/// If this is set to false, the terminal and custom shader will only render +/// If this is set to `false`, the terminal and custom shader will only render /// when the terminal is updated. This is more efficient but the shader will /// not animate. /// -/// This can also be set to "always", which will always run the animation +/// This can also be set to `always`, which will always run the animation /// loop regardless of whether the terminal is focused or not. The animation /// loop will still only run when custom shaders are used. Note that this /// will use more CPU per terminal surface and can become quite expensive @@ -866,20 +871,21 @@ keybind: Keybinds = .{}, /// /// Allowable values are: /// -/// * "visible-menu" - Use non-native macOS fullscreen, keep the menu bar visible -/// * "true" - Use non-native macOS fullscreen, hide the menu bar -/// * "false" - Use native macOS fullscreeen +/// * `visible-menu` - Use non-native macOS fullscreen, keep the menu bar visible +/// +/// * `true` - Use non-native macOS fullscreen, hide the menu bar +/// +/// * `false` - Use native macOS fullscreeen @"macos-non-native-fullscreen": NonNativeFullscreen = .false, -/// If true, the Option key will be treated as Alt. This makes terminal -/// sequences expecting Alt to work properly, but will break Unicode -/// input sequences on macOS if you use them via the alt key. You may -/// set this to false to restore the macOS alt-key unicode sequences -/// but this will break terminal sequences expecting Alt to work. +/// If `true`, the *Option* key will be treated as *Alt*. This makes terminal +/// sequences expecting *Alt* to work properly, but will break Unicode input +/// sequences on macOS if you use them via the *Alt* key. You may set this to +/// `false` to restore the macOS *Alt* key unicode sequences but this will break +/// terminal sequences expecting *Alt* to work. /// -/// Note that if an Option-sequence doesn't produce a printable -/// character, it will be treated as Alt regardless of this setting. -/// (i.e. alt+ctrl+a). +/// Note that if an *Option*-sequence doesn't produce a printable character, it +/// will be treated as *Alt* regardless of this setting. (i.e. `alt+ctrl+a`). /// /// This does not work with GLFW builds. @"macos-option-as-alt": OptionAsAlt = .false, @@ -890,21 +896,21 @@ keybind: Keybinds = .{}, /// /// If false, each new ghostty process will launch a separate application. /// -/// The default value is "desktop" which will default to "true" if Ghostty -/// detects it was launched from the .desktop file such as an app launcher. -/// If Ghostty is launched from the command line, it will default to "false". +/// The default value is `desktop` which will default to `true` if Ghostty +/// detects it was launched from the `.desktop` file such as an app launcher. +/// If Ghostty is launched from the command line, it will default to `false`. /// /// Note that debug builds of Ghostty have a separate single-instance ID /// so you can test single instance without conflicting with release builds. @"gtk-single-instance": GtkSingleInstance = .desktop, -/// If true (default), then the Ghostty GTK tabs will be "wide." Wide tabs +/// If `true` (default), then the Ghostty GTK tabs will be "wide." Wide tabs /// are the new typical Gnome style where tabs fill their available space. -/// If you set this to false then tabs will only take up space they need, +/// If you set this to `false` then tabs will only take up space they need, /// which is the old style. @"gtk-wide-tabs": bool = true, -/// If true (default), Ghostty will enable libadwaita theme support. This +/// If `true` (default), Ghostty will enable libadwaita theme support. This /// will make `window-theme` work properly and will also allow Ghostty to /// properly respond to system theme changes, light/dark mode changing, etc. /// This requires a GTK4 desktop with a GTK4 theme. @@ -918,20 +924,20 @@ keybind: Keybinds = .{}, /// libadwaita support. @"gtk-adwaita": bool = true, -/// If true (default), applications running in the terminal can show desktop +/// If `true` (default), applications running in the terminal can show desktop /// notifications using certain escape sequences such as OSC 9 or OSC 777. @"desktop-notifications": bool = true, -/// This will be used to set the TERM environment variable. -/// HACK: We set this with an "xterm" prefix because vim uses that to enable key -/// protocols (specifically this will enable 'modifyOtherKeys'), among other +/// This will be used to set the `TERM` environment variable. +/// HACK: We set this with an `xterm` prefix because vim uses that to enable key +/// protocols (specifically this will enable `modifyOtherKeys`), among other /// features. An option exists in vim to modify this: `:set /// keyprotocol=ghostty:kitty`, however a bug in the implementation prevents it /// from working properly. https://github.com/vim/vim/pull/13211 fixes this. term: []const u8 = "xterm-ghostty", -/// String to send when we receive ENQ (0x05) from the command that we are -/// running. Defaults to "" if not set. +/// String to send when we receive `ENQ` (`0x05`) from the command that we are +/// running. Defaults to an empty string if not set. @"enquiry-response": []const u8 = "", /// This is set by the CLI parser for deinit.