docs: shift from return {} style to config.something style

Nudge new users towards using this style:

```lua
local config = {}
config.color_scheme = 'Batman'
return config
```

and surface how to write lua modules closer to the main section
on config files. In that lua modules section, nudge towards using
a convention similar to that of the plugin spec described in
this commit: e4ae8a844d

ci/generate-docs.py

@@ -307,9 +307,7 @@ function load_scheme_player(ident) {{
                     idx.write(
                         f"""
 ```lua
-return {{
+config.color_scheme = "{title}"
-  color_scheme = "{title}",
-}}
 ```
 
 """

docs/config/appearance.md

@@ -9,9 +9,12 @@ WezTerm ships with over 700 color schemes available from
 You can select a color scheme with a line like this:
 
 ```lua
-return {
+local wezterm = require 'wezterm'
-  color_scheme = 'Batman',
+local config = {}
-}
+
+config.color_scheme = 'Batman'
+
+return config
 ```
 
 You can find a list of available color schemes and screenshots
@@ -49,8 +52,10 @@ you can use `#RRGGBB` to specify a color code using the
 usual hex notation; eg: `#000000` is equivalent to `black`:
 
 ```lua
-return {
+local wezterm = require 'wezterm'
-  colors = {
+local config = {}
+
+config.colors = {
   -- The default text color
   foreground = 'silver',
   -- The default background color
@@ -125,8 +130,9 @@ return {
   quick_select_label_fg = { Color = '#ffffff' },
   quick_select_match_bg = { AnsiColor = 'Navy' },
   quick_select_match_fg = { Color = '#ffffff' },
-  },
 }
+
+return config
 ```
 
 *Since: 20220101-133340-7edc5b5a*
@@ -134,8 +140,7 @@ return {
 You may specify colors in the HSL color space, if you prefer that over RGB, by using:
 
 ```lua
-return {
+config.colors = {
-  colors = {
   -- the first number is the hue measured in degrees with a range
   -- of 0-360.
   -- The second number is the saturation measured in percentage with
@@ -143,7 +148,6 @@ return {
   -- The third number is the lightness measured in percentage with
   -- a range of 0-100.
   foreground = 'hsl:235 100 50',
-  },
 }
 ```
 
@@ -174,8 +178,7 @@ The alpha value is ignored except when used with `selection_fg` and
 `selection_bg`:
 
 ```lua
-return {
+config.colors = {
-  colors = {
   -- Make the selection text color fully transparent.
   -- When fully transparent, the current text color will be used.
   selection_fg = 'none',
@@ -183,7 +186,6 @@ return {
   -- When selection_bg is transparent, it will be alpha blended over
   -- the current cell background color, rather than replace it
   selection_bg = 'rgba(50% 50% 50% 50%)',
-  },
 }
 ```
 
@@ -201,17 +203,15 @@ All of the settings available from the `colors` section are available
 to use in the `color_schemes` sections.
 
 ```lua
-return {
+config.color_scheme = 'Red Scheme'
-  color_scheme = 'Red Scheme',
 
-  color_schemes = {
+config.color_schemes = {
   ['Red Scheme'] = {
     background = 'red',
   },
   ['Blue Scheme'] = {
     background = 'blue',
   },
-  },
 }
 ```
 
@@ -236,9 +236,7 @@ will need to instruct wezterm where to look for your scheme files; the
 `color_scheme_dirs` setting specifies a list of directories to be searched:
 
 ```lua
-return {
+config.color_scheme_dirs = { '/some/path/to/my/color/schemes' }
-  color_scheme_dirs = { '/some/path/to/my/color/schemes' },
-}
 ```
 
 Color scheme names that are defined in files in your `color_scheme_dirs` list
@@ -253,14 +251,14 @@ of the color scheme repo contains shell scripts that can change the color
 scheme immediately on the fly.  This can be used in your own scripts to alter
 the terminal appearance programmatically:
 
-```bash
+```console
 $ git clone https://github.com/mbadolato/iTerm2-Color-Schemes.git
 $ cd iTerm2-Color-Schemes/dynamic-colors
 $ for scheme in *.sh ; do ; echo $scheme ; \
    bash "$scheme" ; ../tools/screenshotTable.sh; sleep 0.5; done
 ```
 
-  <video width="80%" controls src="../../screenshots/wezterm-dynamic-colors.mp4" loop></video>
+  <video width="80%" controls src="../screenshots/wezterm-dynamic-colors.mp4" loop></video>
 
 ### Tab Bar Appearance & Colors
 
@@ -285,10 +283,7 @@ details.
 The following options affect the fancy tab bar:
 
 ```lua
-local wezterm = require 'wezterm'
+config.window_frame = {
-
-return {
-  window_frame = {
   -- The font used in the tab bar.
   -- Roboto Bold is the default; this font is bundled
   -- with wezterm.
@@ -308,14 +303,13 @@ return {
   -- The overall background color of the tab bar when
   -- the window is not focused
   inactive_titlebar_bg = '#333333',
-  },
+}
 
-  colors = {
+window.colors = {
   tab_bar = {
     -- The color of the inactive tab bar edge/divider
     inactive_tab_edge = '#575757',
   },
-  },
 }
 ```
 
@@ -327,8 +321,7 @@ to the items displayed in the tab bar.
 The following options control the appearance of the tab bar:
 
 ```lua
-return {
+config.colors = {
-  colors = {
   tab_bar = {
     -- The color of the strip that goes along the top of the window
     -- (does not apply when fancy tab bar is in use)
@@ -400,7 +393,6 @@ return {
       -- can also be used for `new_tab_hover`.
     },
   },
-  },
 }
 ```
 
@@ -424,11 +416,9 @@ In this example, inactive panes will be slightly de-saturated and dimmed;
 this is the default configuration:
 
 ```lua
-return {
+config.inactive_pane_hsb = {
-  inactive_pane_hsb = {
   saturation = 0.9,
   brightness = 0.8,
-  },
 }
 ```
 
@@ -458,9 +448,7 @@ reduce it by half, and 2.0 will double the value.
 You can attach an image to the background of the wezterm window:
 
 ```lua
-return {
+config.window_background_image = '/path/to/wallpaper.jpg'
-  window_background_image = '/path/to/wallpaper.jpg',
-}
 ```
 
 If the path is a relative path then it will be expanded relative
@@ -478,10 +466,9 @@ You can optionally transform the background image by specifying
 a hue, saturation, brightness multiplier:
 
 ```lua
-return {
+config.window_background_image = '/path/to/wallpaper.jpg'
-  window_background_image = '/path/to/wallpaper.jpg',
 
-  window_background_image_hsb = {
+config.window_background_image_hsb = {
   -- Darken the background image by reducing it to 1/3rd
   brightness = 0.3,
 
@@ -491,7 +478,6 @@ return {
 
   -- You can adjust the saturation also.
   saturation = 1.0,
-  },
 }
 ```
 
@@ -533,9 +519,7 @@ Setting this to a value other than the default `1.0` may impact render
 performance.
 
 ```lua
-return {
+config.window_background_opacity = 1.0
-  window_background_opacity = 1.0,
-}
 ```
 
 ## Text Background Opacity
@@ -556,8 +540,6 @@ The range of values permitted are `0.0` (completely translucent)
 through to `1.0` (completely opaque).
 
 ```lua
-return {
+config.text_background_opacity = 0.3
-  text_background_opacity = 0.3,
-}
 ```
 

docs/config/default-keys.md

@@ -85,9 +85,7 @@ disable all of them with this configuration; if you chose to do this,
 you must explicitly register every binding.
 
 ```lua
-return {
+config.disable_default_key_bindings = true
-  disable_default_key_bindings = true,
-}
 ```
 
 !!! tip

docs/config/files.md

@@ -1,3 +1,31 @@
+
+## Quick Start
+
+Create a file named `wezterm.lua` in your home directory, with the following
+contents:
+
+```lua
+-- Pull in the wezterm API
+local wezterm = require 'wezterm'
+
+-- This table will hold the configuration.
+local config = {}
+
+-- In newer versions of wezterm, use the config_builder which will
+-- help provide clearer error messages
+if wezterm.config_builder then
+  config = wezterm.config_builder()
+end
+
+-- This is where you actually apply your config choices
+
+-- For example, changing the color scheme:
+config.color_scheme = 'AdventureTime'
+
+-- and finally, return the configuration to wezterm
+return config
+```
+
 ## Configuration Files
 
 `wezterm` will look for a [lua](https://www.lua.org/manual/5.3/manual.html)
@@ -79,7 +107,8 @@ for more information and examples of how to use that functionality.
 
 The `wezterm.lua` configuration file is a lua script which allows for a high
 degree of flexibility.   The script is expected to return a configuration
-table, so a basic empty configuration file will look like this:
+table, so a basic empty (and rather useless!) configuration file will look like
+this:
 
 ```lua
 return {}
@@ -89,18 +118,23 @@ Throughout these docs you'll find configuration fragments that demonstrate
 configuration and that look something like this:
 
 ```lua
-return {
+local wezterm = require 'wezterm'
-  color_scheme = 'Batman',
+local config = {}
-}
+
+config.color_scheme = 'Batman'
+
+return config
 ```
 
 and perhaps another one like this:
 
 ```lua
 local wezterm = require 'wezterm'
-return {
+local config = {}
-  font = wezterm.font 'JetBrains Mono',
+
-}
+config.font = wezterm.font 'JetBrains Mono'
+
+return config
 ```
 
 If you wanted to use both of these in the same file, you would merge them together
@@ -108,12 +142,77 @@ like this:
 
 ```lua
 local wezterm = require 'wezterm'
-return {
+local config = {}
-  font = wezterm.font 'JetBrains Mono',
+
-  color_scheme = 'Batman',
+config.font = wezterm.font 'JetBrains Mono'
-}
+config.color_scheme = 'Batman'
+
+return config
 ```
 
+For the sake of brevity in these docs, individual snippets may be shown as
+just the config assignments:
+
+```lua
+config.color_scheme = 'Batman'
+```
+
+## Making your own Lua Modules
+
+If you'd like to break apart your configuration into multiple files, you'll
+be interested in this information.
+
+The Lua `package.path` is configured with the following paths in this order:
+
+* On Windows: a `wezterm_modules` dir in the same directory as `wezterm.exe`. This is for thumb drive mode, and is not recommended to be used otherwise.
+* `~/.config/wezterm`
+* `~/.wezterm`
+* A system specific set of paths which may (or may not!) find locally installed lua modules
+
+That means that if you wanted to break your config up into a `helpers.lua` file
+you would place it in `~/.config/wezterm/helpers.lua` with contents like this:
+
+```lua
+-- I am helpers.lua and I should live in ~/.config/wezterm/helpers.lua
+
+local wezterm = require 'wezterm'
+
+-- This is the module table that we will export
+local module = {}
+
+-- This function is private to this module and is not visible
+-- outside.
+local function private_helper()
+  wezterm.log_error 'hello!'
+end
+
+-- define a function in the module table.
+-- Only functions defined in `module` will be exported to
+-- code that imports this module.
+-- The suggested convention for making modules that update
+-- the config is for them to export an `apply_to_config`
+-- function that accepts the config object, like this:
+function module.apply_to_config(config)
+  private_helper()
+
+  config.color_scheme = 'Batman'
+end
+
+-- return our module table
+return module
+```
+
+and then in your `wezterm.lua`
+you would use it like this:
+
+```lua
+local helpers = require 'helpers'
+local config = {}
+helpers.apply_to_config(config)
+return config
+```
+
+
 ## Configuration Reference
 
 Continue browsing this section of the docs for an overview of the commonly

docs/config/font-shaping.md

@@ -20,9 +20,7 @@ If you want to disable ligatures in most fonts, then you may want to
 use a setting like this:
 
 ```lua
-return {
+config.harfbuzz_features = { 'calt=0', 'clig=0', 'liga=0' }
-  harfbuzz_features = { 'calt=0', 'clig=0', 'liga=0' },
-}
 ```
 
 Some fonts make available extended options via stylistic sets.
@@ -33,11 +31,9 @@ it lists available stylistic sets here:
 and you can set them in wezterm:
 
 ```lua
-return {
 -- Use this for a zero with a dot rather than a line through it
 -- when using the Fira Code font
-  harfbuzz_features = { 'zero' },
+config.harfbuzz_features = { 'zero' }
-}
 ```
 
 *Since: 20220101-133340-7edc5b5a*
@@ -46,12 +42,9 @@ You can specify `harfbuzz_features` on a per-font basis, rather than
 globally for all fonts:
 
 ```lua
-local wezterm = require 'wezterm'
+config.font = wezterm.font {
-return {
-  font = wezterm.font {
   family = 'JetBrains Mono',
   harfbuzz_features = { 'calt=0', 'clig=0', 'liga=0' },
-  },
 }
 ```
 
@@ -59,10 +52,7 @@ and this example disables ligatures for JetBrains Mono,
 but keeps the default for the other fonts in the fallback:
 
 ```lua
-local wezterm = require 'wezterm'
+config.font = wezterm.font_with_fallback {
-
-return {
-  font = wezterm.font_with_fallback {
   {
     family = 'JetBrains Mono',
     weight = 'Medium',
@@ -70,7 +60,6 @@ return {
   },
   { family = 'Terminus', weight = 'Bold' },
   'Noto Color Emoji',
-  },
 }
 ```
 

docs/config/fonts.md

@@ -9,14 +9,11 @@ If you wish to use a different font face, then you can use
 the [wezterm.font](lua/wezterm/font.md) function to specify it:
 
 ```lua
-local wezterm = require 'wezterm'
+config.font = wezterm.font 'Fira Code'
-
-return {
-  font = wezterm.font 'Fira Code',
 -- You can specify some parameters to influence the font selection;
 -- for example, this selects a Bold, Italic font variant.
-  font = wezterm.font('JetBrains Mono', { weight = 'Bold', italic = true }),
+config.font =
-}
+  wezterm.font('JetBrains Mono', { weight = 'Bold', italic = true })
 ```
 
 #### Fallback
@@ -35,12 +32,9 @@ monospace font, but it doesn't have glyphs for the asian script that you
 sometimes work with:
 
 ```lua
-local wezterm = require 'wezterm'
+config.font = wezterm.font_with_fallback {
-return {
-  font = wezterm.font_with_fallback {
   'Fira Code',
   'DengXian',
-  },
 }
 ```
 

docs/config/key-tables.md

@@ -18,6 +18,7 @@ modes, using `r` for resize and `a` for activation:
 ```lua
 local wezterm = require 'wezterm'
 local act = wezterm.action
+local config = {}
 
 -- Show which key table is active in the status area
 wezterm.on('update-right-status', function(window, pane)
@@ -28,9 +29,8 @@ wezterm.on('update-right-status', function(window, pane)
   window:set_right_status(name or '')
 end)
 
-return {
+config.leader = { key = 'Space', mods = 'CTRL|SHIFT' }
-  leader = { key = 'Space', mods = 'CTRL|SHIFT' },
+config.keys = {
-  keys = {
   -- CTRL+SHIFT+Space, followed by 'r' will put us in resize-pane
   -- mode until we cancel that mode.
   {
@@ -53,9 +53,9 @@ return {
       timeout_milliseconds = 1000,
     },
   },
-  },
+}
 
-  key_tables = {
+config.key_tables = {
   -- Defines the keys that are active in our resize-pane mode.
   -- Since we're likely to want to make multiple adjustments,
   -- we made the activation one_shot=false. We therefore need
@@ -95,8 +95,9 @@ return {
     { key = 'DownArrow', action = act.ActivatePaneDirection 'Down' },
     { key = 'j', action = act.ActivatePaneDirection 'Down' },
   },
-  },
 }
+
+return config
 ```
 
 ### Key Table Activation Stack

docs/config/keyboard-concepts.md

@@ -109,10 +109,8 @@ with no composition effects, while the right `Option` key performs composition
 You can control this behavior in your configuration:
 
 ```lua
-return {
+config.send_composed_key_when_left_alt_is_pressed = false
-  send_composed_key_when_left_alt_is_pressed = false,
+config.send_composed_key_when_right_alt_is_pressed = true
-  send_composed_key_when_right_alt_is_pressed = true,
-}
 ```
 
 *since: 20210203-095643-70a364eb*
@@ -153,9 +151,7 @@ You can tell WezTerm to disable dead keys by setting this in your configuration
 file:
 
 ```lua
-return {
+config.use_dead_keys = false
-  use_dead_keys = false,
-}
 ```
 
 Note that for X11 systems with `use_ime=true`, depending on the configured IME,

docs/config/keys.md

@@ -5,10 +5,7 @@ The default key table assignments can be overridden or extended using the
 disable a default assignment like this:
 
 ```lua
-local wezterm = require 'wezterm'
+config.keys = {
-
-return {
-  keys = {
   -- Turn off the default CMD-m Hide action, allowing CMD-m to
   -- be potentially recognized and handled by the tab
   {
@@ -16,7 +13,6 @@ return {
     mods = 'CMD',
     action = wezterm.action.DisableDefaultAssignment,
   },
-  },
 }
 ```
 
@@ -142,12 +138,9 @@ milliseconds).  While `LEADER` is active, the `|` key (with no other modifiers)
 will trigger the current pane to be split.
 
 ```lua
-local wezterm = require 'wezterm'
-
-return {
 -- timeout_milliseconds defaults to 1000 and can be omitted
-  leader = { key = 'a', mods = 'CTRL', timeout_milliseconds = 1000 },
+config.leader = { key = 'a', mods = 'CTRL', timeout_milliseconds = 1000 }
-  keys = {
+config.keys = {
   {
     key = '|',
     mods = 'LEADER|SHIFT',
@@ -159,7 +152,6 @@ return {
     mods = 'LEADER|CTRL',
     action = wezterm.action.SendString '\x01',
   },
-  },
 }
 ```
 
@@ -174,13 +166,10 @@ uses `CapsLock` as a `LEADER` without it affecting the shift / capital state as
 long as you have `setxkbmap -option caps:none` configured.
 
 ```lua
-local wezterm = require 'wezterm'
-
-return {
 -- timeout_milliseconds defaults to 1000 and can be omitted
 -- for this example use `setxkbmap -option caps:none` in your terminal.
-  leader = { key = 'VoidSymbol', mods = '', timeout_milliseconds = 1000 },
+config.leader = { key = 'VoidSymbol', mods = '', timeout_milliseconds = 1000 }
-  keys = {
+config.keys = {
   {
     key = '|',
     mods = 'LEADER|SHIFT',
@@ -191,7 +180,6 @@ return {
     mods = 'LEADER',
     action = wezterm.action.SplitVertical { domain = 'CurrentPaneDomain' },
   },
-  },
 }
 ```
 

docs/config/launch.md

@@ -38,10 +38,8 @@ the argument array; the array allows specifying the program and arguments
 portably:
 
 ```lua
-return {
 -- Spawn a fish shell in login mode
-  default_prog = { '/usr/local/bin/fish', '-l' },
+config.default_prog = { '/usr/local/bin/fish', '-l' }
-}
 ```
 
 ## Launching a different program as a one off via the CLI
@@ -64,9 +62,7 @@ directory you can do so via the config, CLI, and when using
 * Setting the [`default_cwd`](lua/config/default_cwd.md) via the config:
 
   ```lua
-  return {
+  config.default_cwd = "/some/path"
-    default_cwd = "/some/path",
-  }
   ```
 
 * One off program in a specific working directory via the CLI:
@@ -108,13 +104,11 @@ The behavior is to take the environment of the `wezterm` process
 and then set the specified variables for the spawned process.
 
 ```lua
-return {
+config.set_environment_variables = {
-  set_environment_variables = {
   -- This changes the default prompt for cmd.exe to report the
   -- current directory using OSC 7, show the current time and
   -- the current directory colored in the prompt.
   prompt = '$E]7;file://localhost/$P$E\\$E[32m$T$E[0m $E[35m$P$E[36m$_$G$E[0m ',
-  },
 }
 ```
 
@@ -140,8 +134,7 @@ Each entry in `launch_menu` is an instance of a
 [SpawnCommand](lua/SpawnCommand.md) object.
 
 ```lua
-return {
+config.launch_menu = {
-  launch_menu = {
   {
     args = { 'top' },
   },
@@ -164,7 +157,6 @@ return {
     -- set_environment_variables configuration option described above
     -- set_environment_variables = { FOO = "bar" },
   },
-  },
 }
 ```
 
@@ -175,7 +167,6 @@ menu when running on Windows:
 
 ```lua
 local wezterm = require 'wezterm'
-
 local launch_menu = {}
 
 if wezterm.target_triple == 'x86_64-pc-windows-msvc' then

docs/config/lua/ExecDomain.md

@@ -78,6 +78,7 @@ that affect the styling of the text. You may wish to use
 
 ```lua
 local wezterm = require 'wezterm'
+local config = {}
 
 -- Equivalent to POSIX basename(3)
 -- Given "/foo/bar" returns "bar"
@@ -86,8 +87,7 @@ local function basename(s)
   return string.gsub(s, '(.*[/\\])(.*)', '%2')
 end
 
-return {
+config.exec_domains = {
-  exec_domains = {
   -- Defines a domain called "scoped" that will run the requested
   -- command inside its own individual systemd scope.
   -- This defines a strong boundary for resource control and can
@@ -135,12 +135,13 @@ return {
     -- and return the SpawnCommand that we want to execute
     return cmd
   end),
-  },
+}
 
 -- Making the domain the default means that every pane/tab/window
 -- spawned by wezterm will have its own scope
-  default_domain = 'scoped',
+config.default_domain = 'scoped'
-}
+
+return config
 ```
 
 ## Example: docker domains
@@ -150,6 +151,7 @@ gist of it is:
 
 ```lua
 local wezterm = require 'wezterm'
+local config = {}
 
 function docker_list()
   -- Use wezterm.run_child_process to run
@@ -200,9 +202,8 @@ for id, name in pairs(docker_list()) do
   )
 end
 
-return {
+config.exec_domains = exec_domains
-  exec_domains = exec_domains,
+return config
-}
 ```
 
 With something like the config above, each time the config is reloaded, the

docs/config/lua/PaneInformation.md

@@ -73,6 +73,7 @@ tab in the tab bar when there is unseen output.
 
 ```lua
 local wezterm = require 'wezterm'
+local config = {}
 
 wezterm.on(
   'format-tab-title',
@@ -100,7 +101,7 @@ wezterm.on(
   end
 )
 
-return {}
+return config
 ```
 
 *Since: 20220624-141144-bd1b7c5d*
@@ -111,6 +112,7 @@ This example shows the domain name of the active pane appended to the tab title:
 
 ```lua
 local wezterm = require 'wezterm'
+local config = {}
 
 wezterm.on('format-tab-title', function(tab)
   local pane = tab.active_pane
@@ -121,6 +123,6 @@ wezterm.on('format-tab-title', function(tab)
   return title
 end)
 
-return {}
+return config
 ```
 

docs/config/lua/SshDomain.md

@@ -6,8 +6,7 @@ The `SshDomain` struct specifies information about an individual
 It is a lua object with the following fields:
 
 ```lua
-return {
+config.ssh_domains = {
-  ssh_domains = {
   {
     -- The name of this specific domain.  Must be unique amongst
     -- all types of domain in the configuration file.
@@ -36,7 +35,6 @@ return {
     -- that is configure for ssh.
     -- remote_wezterm_path = "/home/yourusername/bin/wezterm"
   },
-  },
 }
 ```
 
@@ -45,8 +43,7 @@ return {
 You may now specify a table with ssh config overrides:
 
 ```lua
-return {
+config.ssh_domains = {
-  ssh_domains = {
   {
     name = 'my.server',
     remote_address = '192.168.1.1',
@@ -54,7 +51,6 @@ return {
       identityfile = '/path/to/id_rsa.pub',
     },
   },
-  },
 }
 ```
 
@@ -85,8 +81,7 @@ panes and tabs.  The following values are recognized for `assume_shell`:
   `env -c DIR ENV1=VAL1 ENV2=VAL2 $SHELL`.
 
 ```lua
-return {
+config.ssh_domains = {
-  ssh_domains = {
   {
     name = 'my.server',
     remote_address = '192.168.1.1',
@@ -106,10 +101,9 @@ return {
     -- the current directory on the remote host.
     assume_shell = 'Posix',
   },
-  },
-
-  default_domain = 'my.server',
 }
+
+config.default_domain = 'my.server'
 ```
 
 You may now specify the round-trip latency threshold for enabling predictive
@@ -120,14 +114,12 @@ result of that prediction locally without waiting, hence hiding latency to the
 user. This option only applies when `multiplexing = "WezTerm"`.
 
 ```lua
-return {
+config.ssh_domains = {
-  ssh_domains = {
   {
     name = 'my.server',
     remote_address = '192.168.1.1',
     local_echo_threshold_ms = 10,
   },
-  },
 }
 ```
 

docs/config/lua/TlsDomainClient.md

@@ -6,8 +6,7 @@ to a [TLS Domain](../../multiplexing.md#tls-domains).
 It is a lua object with the following fields:
 
 ```lua
-return {
+config.tls_domains = {
-  tls_domains = {
   {
     -- The name of this specific domain.  Must be unique amongst
     -- all types of domain in the configuration file.
@@ -66,7 +65,6 @@ return {
     -- The path to the wezterm binary on the remote host
     -- remote_wezterm_path = "/home/myname/bin/wezterm"
   },
-  },
 }
 ```
 
@@ -80,15 +78,13 @@ result of that prediction locally without waiting, hence hiding latency to the
 user. This option only applies when `multiplexing = "WezTerm"`.
 
 ```lua
-return {
+config.tls_domains = {
-  tls_domains = {
   {
     name = 'server,name',
     bootstrap_via_ssh = 'server.hostname',
     remote_address = 'server.hostname:8080',
     local_echo_threshold_ms = 10,
   },
-  },
 }
 ```
 

docs/config/lua/TlsDomainServer.md

@@ -6,8 +6,7 @@ the server side of a [TLS Domain](../../multiplexing.md#tls-domains).
 It is a lua object with the following fields:
 
 ```lua
-return {
+config.tls_servers = {
-  tls_servers = {
   {
     -- The address:port combination on which the server will listen
     -- for client connections
@@ -33,6 +32,5 @@ return {
     -- You can omit this if your tls_client is using bootstrap_via_ssh.
     -- pem_root_certs = { "/some/path/ca1.pem", "/some/path/ca2.pem" },
   },
-  },
 }
 ```

docs/config/lua/WslDomain.md

@@ -18,8 +18,7 @@ output from `wsl -l -v` and assigns that as the value of the
 A `WslDomain` is a lua object with the following fields:
 
 ```lua
-return {
+config.wsl_domains = {
-  wsl_domains = {
   {
     -- The name of this specific domain.  Must be unique amonst all types
     -- of domain in the configuration file.
@@ -47,6 +46,5 @@ return {
 
     -- default_prog = {"fish"}
   },
-  },
 }
 ```

docs/config/lua/config/animation_fps.md

@@ -14,10 +14,8 @@ If you are running with a CPU renderer (eg: you have [front_end](front_end.md)
 transitions:
 
 ```lua
-return {
+config.animation_fps = 1
-  animation_fps = 1,
+config.cursor_blink_ease_in = 'Constant'
-  cursor_blink_ease_in = 'Constant',
+config.cursor_blink_ease_out = 'Constant'
-  cursor_blink_ease_out = 'Constant',
-}
 ```
 

docs/config/lua/config/automatically_reload_config.md

@@ -10,7 +10,5 @@ with a key bound to the action [ReloadConfiguration](../keyassignment/ReloadConf
 For example, to disable auto config reload:
 
 ```lua
-return {
+config.automatically_reload_config = false
-  automatically_reload_config = false,
-}
 ```

docs/config/lua/config/background.md

@@ -104,13 +104,12 @@ The video at the top of this page demonstrate this configuration in action.
 -- for text, so we're going to dim it down to 10% of its normal brightness
 local dimmer = { brightness = 0.1 }
 
-return {
+config.enable_scroll_bar = true
-  enable_scroll_bar = true,
+config.min_scroll_bar_height = '2cell'
-  min_scroll_bar_height = '2cell',
+config.colors = {
-  colors = {
   scrollbar_thumb = 'white',
-  },
+}
-  background = {
+config.background = {
   -- This is the deepest/back-most layer. It will be rendered first
   {
     source = {
@@ -182,6 +181,5 @@ return {
     hsb = dimmer,
     attachment = { Parallax = 0.5 },
   },
-  },
 }
 ```

docs/config/lua/config/bypass_mouse_reporting_modifiers.md

@@ -16,8 +16,6 @@ as though `SHIFT` was not pressed and then match it against the mouse
 assignments.
 
 ```lua
-return {
 -- Use ALT instead of SHIFT to bypass application mouse reporting
-  bypass_mouse_reporting_modifiers = 'ALT',
+config.bypass_mouse_reporting_modifiers = 'ALT'
-}
 ```

docs/config/lua/config/check_for_updates.md

@@ -13,8 +13,6 @@ Set `check_for_updates` to `false` to disable this completely or set
 `check_for_updates_interval_seconds` for an alternative update interval.
 
 ```lua
-return {
+config.check_for_updates = true
-  check_for_updates = true,
+config.check_for_updates_interval_seconds = 86400
-  check_for_updates_interval_seconds = 86400,
-}
 ```

docs/config/lua/config/clean_exit_codes.md

@@ -15,9 +15,7 @@ with SIGINT, but that bash itself wasn't.  In that situation you may wish
 to set this config to treat `130` as OK:
 
 ```lua
-return {
+config.clean_exit_codes = { 130 }
-  clean_exit_codes = { 130 },
-}
 ```
 
 Note that `0` is always treated as a clean exit code and can be omitted

docs/config/lua/config/cursor_blink_rate.md

@@ -11,9 +11,7 @@ It is recommended to avoid blinking cursors when on battery power, as it is
 relatively costly to keep re-rendering for the blink!
 
 ```lua
-return {
+config.cursor_blink_rate = 800
-  cursor_blink_rate = 800,
-}
 ```
 
 *Since: 20220319-142410-0fcdea07*

docs/config/lua/config/daemon_options.md

@@ -12,11 +12,9 @@ There are three fields supported:
 * `stderr` - specifies where a log of the stderr stream from the daemon will be placed.  The default is `$XDG_RUNTIME_DIR/wezterm/stderr` on X11/Wayland systems, or `$HOME/.local/share/wezterm/stderr`.
 
 ```lua
-return {
+config.daemon_options = {
-  daemon_options = {
   stdout = '/some/where/stdout',
   stderr = '/some/where/stderr',
   pid_file = '/some/where/pid_file',
-  },
 }
 ```

docs/config/lua/config/debug_key_events.md

@@ -8,9 +8,7 @@ This can be helpful in figuring out how keys are being decoded on your system,
 or for discovering the system-dependent "raw" key code values.
 
 ```lua
-return {
+config.debug_key_events = true
-  debug_key_events = true,
-}
 ```
 
 Produces logs like the following when typing `ls`: (artificially wrapped

docs/config/lua/config/default_cursor_style.md

@@ -11,9 +11,7 @@ Acceptable values are `SteadyBlock`, `BlinkingBlock`,
 and `BlinkingBar`.
 
 ```lua
-return {
+config.default_cursor_style = 'SteadyBlock'
-  default_cursor_style = 'SteadyBlock',
-}
 ```
 
 Using a blinking style puts more load on the graphics subsystem.

docs/config/lua/config/default_domain.md

@@ -27,9 +27,7 @@ then wezterm will by default create a `WslDomain` with the name `"WSL:Ubuntu-18.
 and if I set my config like this:
 
 ```lua
-return {
+config.default_domain = 'WSL:Ubuntu-18.04'
-  default_domain = 'WSL:Ubuntu-18.04',
-}
 ```
 
 then when wezterm starts up, it will open with a shell running inside that Ubuntu

docs/config/lua/config/default_gui_startup_args.md

@@ -13,9 +13,7 @@ If you know that you always want to use wezterm's ssh client to login to a
 particular host, then you might consider using this configuration:
 
 ```lua
-return {
+config.default_gui_startup_args = { 'ssh', 'some-host' }
-  default_gui_startup_args = { 'ssh', 'some-host' },
-}
 ```
 
 which will cause `wezterm` with no additional subcommand arguments to be

docs/config/lua/config/default_prog.md

@@ -7,9 +7,7 @@ For example, to have `wezterm` always run `top` by default,
 you'd use this:
 
 ```lua
-return {
+config.default_prog = { 'top' }
-  default_prog = { 'top' },
-}
 ```
 
 `default_prog` is implemented as an array where the 0th element

docs/config/lua/config/enable_scroll_bar.md

@@ -6,9 +6,7 @@ It will occupy the right window padding space.
 If right padding is set to 0 then it will be increased to a single cell width.
 
 ```lua
-return {
+config.enable_scroll_bar = true
-  enable_scroll_bar = true,
-}
 ```
 
 

docs/config/lua/config/enable_wayland.md

@@ -6,14 +6,10 @@ when starting the gui frontend, and instead use X11.
 This option is only considered on X11/Wayland systems and
 has no effect on macOS or Windows.
 
-The default is false.
+The default is true.  In versions prior to 20220624-141144-bd1b7c5d it was
+disabled by default.
 
 ```lua
-return {
+config.enable_wayland = true
-  enable_wayland = true,
-}
 ```
 
-*Since: 20220624-141144-bd1b7c5d*
-
-The default is now `true`.

docs/config/lua/config/exit_behavior.md

@@ -10,9 +10,7 @@ There are three possible values:
 * `"CloseOnCleanExit"` - if the shell program exited with a successful status, behave like `"Close"`, otherwise, behave like `"Hold"`.  This is the default setting.
 
 ```lua
-return {
+console.exit_behavior = 'Hold'
-  exit_behavior = 'Hold',
-}
 ```
 
 Note that most unix shells will exit with the status of the last command that
@@ -22,9 +20,9 @@ For example, if you interrupt a command and then use `exit` (with no arguments),
 CTRL-D to send EOF to the shell, the shell will return an unsuccessful exit
 status.  The same thing holds if you were to run:
 
-```
+```console
-false
+$ false
-exit
+$ exit
 ```
 
 With the default `exit_behavior="CloseOnCleanExit"` setting, that will cause

docs/config/lua/config/font_dirs.md

@@ -6,13 +6,11 @@ if you configure the `font_dirs` option, wezterm will load fonts from that
 set of directories:
 
 ```lua
-return {
 -- This tells wezterm to look first for fonts in the directory named
 -- `fonts` that is found alongside your `wezterm.lua` file.
 -- As this option is an array, you may list multiple locations if
 -- you wish.
-  font_dirs = { 'fonts' },
+config.font_dirs = { 'fonts' }
-}
 ```
 
 wezterm will scan the `font_dirs` to build a database of available fonts.  When
@@ -27,9 +25,7 @@ systems and don't want to install those fonts on every system that you use,
 then you can set:
 
 ```lua
-return {
+config.font_locator = 'ConfigDirsOnly'
-  font_locator = 'ConfigDirsOnly',
-}
 ```
 
 

docs/config/lua/config/font_rules.md

@@ -59,11 +59,8 @@ font-weights that are either too bold or too light for the default rules to
 produce great results, hence this set of rules.
 
 ```lua
-local wezterm = require 'wezterm'
+config.font = wezterm.font_with_fallback 'Operator Mono SSm Lig Medium'
-
+config.font_rules = {
-return {
-  font = wezterm.font_with_fallback 'Operator Mono SSm Lig Medium',
-  font_rules = {
   -- For Bold-but-not-italic text, use this relatively bold font, and override
   -- its color to a tomato-red color to make bold text really stand out.
   {
@@ -120,19 +117,15 @@ return {
       weight = 'Light',
     },
   },
-  },
 }
 ```
 
 Here's another example combining `FiraCode` with `Victor Mono`, using `Victor Mono` only for italics:
 
 ```lua
-local wezterm = require 'wezterm'
+config.font = wezterm.font { family = 'FiraCode' }
 
-return {
+config.font_rules = {
-  font = wezterm.font { family = 'FiraCode' },
-
-  font_rules = {
   {
     intensity = 'Bold',
     italic = true,
@@ -159,7 +152,6 @@ return {
       style = 'Italic',
     },
   },
-  },
 }
 ```
 
@@ -168,7 +160,7 @@ return {
 You can run `wezterm ls-fonts` to summarize the font rules and the fonts that
 match them:
 
-```bash
+```console
 $ wezterm ls-fonts
 Primary font:
 wezterm.font_with_fallback({

docs/config/lua/config/foreground_text_hsb.md

@@ -23,13 +23,11 @@ values, so the default of 1.0 preserves the existing component, whilst 0.5 will
 reduce it by half, and 2.0 will double the value.
 
 ```lua
-return {
 -- This increases color saturation by 50%
-  foreground_text_hsb = {
+config.foreground_text_hsb = {
   hue = 1.0,
   saturation = 1.5,
   brightness = 1.0,
-  },
 }
 ```
 

docs/config/lua/config/freetype_load_flags.md

@@ -21,10 +21,8 @@ Available flags are:
 * `NO_AUTOHINT` - don't use the freetype auto-hinter
 
 ```lua
-return {
 -- You probably don't want to do this, but this demonstrates
 -- that the flags can be combined
-  freetype_load_flags = 'NO_HINTING|MONOCHROME',
+config.freetype_load_flags = 'NO_HINTING|MONOCHROME'
-}
 ```
 

docs/config/lua/config/freetype_render_target.md

@@ -13,9 +13,7 @@ For example, this configuration uses light hinting but produces
 subpixel-antialiased glyph bitmaps:
 
 ```lua
-return {
+config.freetype_load_target = 'Light'
-  freetype_load_target = 'Light',
+config.freetype_render_target = 'HorizontalLcd'
-  freetype_render_target = 'HorizontalLcd',
-}
 ```
 

docs/config/lua/config/hide_mouse_cursor_when_typing.md

@@ -8,7 +8,5 @@ hovering over the window.
 The default is `true`. Set to `false` to disable this behavior.
 
 ```lua
-return {
+config.hide_mouse_cursor_when_typing = true
-  hide_mouse_cursor_when_typing = true,
-}
 ```

docs/config/lua/config/hyperlink_rules.md

@@ -24,8 +24,7 @@ The default value for `hyperlink_rules` can be retrieved using
 and is shown below:
 
 ```lua
-return {
+config.hyperlink_rules = {
-  hyperlink_rules = {
   -- Matches: a URL in parens: (URL)
   {
     regex = '\\((\\w+://\\S+)\\)',
@@ -60,7 +59,6 @@ return {
     regex = '\\b\\w+@[\\w-]+(\\.[\\w-]+)+\\b',
     format = 'mailto:$0',
   },
-  },
 }
 ```
 
@@ -84,14 +82,12 @@ return {
 Some other examples include:
 
 ```lua
-local wezterm = require 'wezterm'
-
 -- Use the defaults as a base
-local hyperlink_rules = wezterm.default_hyperlink_rules()
+config.hyperlink_rules = wezterm.default_hyperlink_rules()
 
 -- make task numbers clickable
 -- the first matched regex group is captured in $1.
-table.insert(hyperlink_rules, {
+table.insert(config.hyperlink_rules, {
   regex = [[\b[tt](\d+)\b]],
   format = 'https://example.com/tasks/?t=$1',
 })
@@ -100,12 +96,8 @@ table.insert(hyperlink_rules, {
 -- ( "nvim-treesitter/nvim-treesitter" | wbthomason/packer.nvim | wez/wezterm | "wez/wezterm.git" )
 -- as long as a full url hyperlink regex exists above this it should not match a full url to
 -- github or gitlab / bitbucket (i.e. https://gitlab.com/user/project.git is still a whole clickable url)
-table.insert(hyperlink_rules, {
+table.insert(config.hyperlink_rules, {
   regex = [[["]?([\w\d]{1}[-\w\d]+)(/){1}([-\w\d\.]+)["]?]],
   format = 'https://www.github.com/$1/$3',
 })
-
-return {
-  hyperlink_rules = hyperlink_rules,
-}
 ```

docs/config/lua/config/ime_preedit_rendering.md

@@ -25,9 +25,7 @@ WezTerm supports the following IME preedit rendering.
 You can control IME preedit rendering in your configuraiton file:
 
 ```lua
-return {
+config.ime_preedit_rendering = 'System'
-  ime_preedit_rendering = 'System',
-}
 ```
 
 Otherwise, the default is `"Builtin"`.

docs/config/lua/config/index.markdown

@@ -1,3 +1,8 @@
+---
+search:
+  exclude: true
+---
+
 # `Config` struct
 
 The `return` statement at the end of your `wezterm.lua` file returns

docs/config/lua/config/launch_menu.md

@@ -11,8 +11,7 @@ Each entry in `launch_menu` is an instance of a
 [SpawnCommand](../SpawnCommand.md) object.
 
 ```lua
-return {
+config.launch_menu = {
-  launch_menu = {
   {
     args = { 'top' },
   },
@@ -35,7 +34,6 @@ return {
     -- set_environment_variables configuration option described above
     -- set_environment_variables = { FOO = "bar" },
   },
-  },
 }
 ```
 

docs/config/lua/config/mux_env_remove.md

@@ -12,11 +12,9 @@ spawned by the multiplexer server.
 The default value for this is:
 
 ```lua
-return {
+config.mux_env_remove = {
-  mux_env_remove = {
   'SSH_AUTH_SOCK',
   'SSH_CLIENT',
   'SSH_CONNECTION',
-  },
 }
 ```

docs/config/lua/config/quick_select_patterns.md

@@ -6,12 +6,10 @@ Specify additional patterns to match when in [quick select mode](../../../quicks
 This setting is a table listing out a set of regular expressions.
 
 ```lua
-return {
+config.quick_select_patterns = {
-  quick_select_patterns = {
   -- match things that look like sha1 hashes
   -- (this is actually one of the default patterns)
   '[0-9a-f]{7,40}',
-  },
 }
 ```
 

docs/config/lua/config/selection_word_boundary.md

@@ -10,7 +10,5 @@ Defaults to ``" \t\n{}[]()\"'`"``.
 
 For example, to always include spaces and newline when selecting a word, but stop on punctuations:
 ```lua
-return {
+config.selection_word_boundary = '{}[]()"\'`.,;:'
-  selection_word_boundary = '{}[]()"\'`.,;:',
-}
 ```

docs/config/lua/config/show_new_tab_button_in_tab_bar.md

@@ -12,17 +12,13 @@ This example turns off the tabs and new-tab button, leaving just the left and
 right status areas:
 
 ```lua
-local wezterm = require 'wezterm'
-
 wezterm.on('update-right-status', function(window, pane)
   window:set_left_status 'left'
   window:set_right_status 'right'
 end)
 
-return {
+config.use_fancy_tab_bar = false
-  use_fancy_tab_bar = false,
+config.show_tabs_in_tab_bar = false
-  show_tabs_in_tab_bar = false,
+config.show_new_tab_button_in_tab_bar = false
-  show_new_tab_button_in_tab_bar = false,
-}
 ```
 

docs/config/lua/config/show_tabs_in_tab_bar.md

@@ -11,16 +11,12 @@ This example turns off the tabs and new-tab button, leaving just the left and
 right status areas:
 
 ```lua
-local wezterm = require 'wezterm'
-
 wezterm.on('update-right-status', function(window, pane)
   window:set_left_status 'left'
   window:set_right_status 'right'
 end)
 
-return {
+config.use_fancy_tab_bar = false
-  use_fancy_tab_bar = false,
+config.show_tabs_in_tab_bar = false
-  show_tabs_in_tab_bar = false,
+config.show_new_tab_button_in_tab_bar = false
-  show_new_tab_button_in_tab_bar = false,
-}
 ```

docs/config/lua/config/show_update_window.md

@@ -8,7 +8,5 @@ See [check_for_updates](check_for_updates.md) for more information on
 the automatic update checks.
 
 ```lua
-return {
+config.show_update_window = false
-  show_update_window = false,
-}
 ```

docs/config/lua/config/skip_close_confirmation_for_processes_named.md

@@ -15,26 +15,7 @@ not prompt for closing that particular pane.
 The default value for this setting is shown below:
 
 ```lua
-return {
+config.skip_close_confirmation_for_processes_named = {
-  skip_close_confirmation_for_processes_named = {
-    'bash',
-    'sh',
-    'zsh',
-    'fish',
-    'tmux',
-  },
-}
-```
-
-*Since: 20210814-124438-54e29167*:
-
-This option now also works on Windows (prior versions only worked on Linux and
-macOS), and the default value for this setting now includes some windows shell
-processes:
-
-```lua
-return {
-  skip_close_confirmation_for_processes_named = {
   'bash',
   'sh',
   'zsh',
@@ -44,12 +25,9 @@ return {
   'cmd.exe',
   'pwsh.exe',
   'powershell.exe',
-  },
 }
 ```
 
-*Since: 20220101-133340-7edc5b5a*
-
 More advanced control over this behavior can be achieved by defining a
 [mux-is-process-stateful](../mux-events/mux-is-process-stateful.md) event handler.
 

docs/config/lua/config/tab_bar_style.md

@@ -41,13 +41,12 @@ This example changes the tab edges to the PowerLine arrow symbols:
 local wezterm = require 'wezterm'
 
 -- The filled in variant of the < symbol
-local SOLID_LEFT_ARROW = utf8.char(0xe0b2)
+local SOLID_LEFT_ARROW = wezterm.nerdfonts.pl_right_hard_divider
 
 -- The filled in variant of the > symbol
-local SOLID_RIGHT_ARROW = utf8.char(0xe0b0)
+local SOLID_RIGHT_ARROW = wezterm.nerdfonts.pl_left_hard_divider
 
-return {
+config.tab_bar_style = {
-  tab_bar_style = {
   active_tab_left = wezterm.format {
     { Background = { Color = '#0b0022' } },
     { Foreground = { Color = '#2b2042' } },
@@ -68,7 +67,6 @@ return {
     { Foreground = { Color = '#1b1032' } },
     { Text = SOLID_RIGHT_ARROW },
   },
-  },
 }
 ```
 

docs/config/lua/config/tab_max_width.md

@@ -7,7 +7,5 @@ using fancy tab mode.
 Defaults to 16 glyphs in width.
 
 ```lua
-return {
+config.tab_max_width = 16
-  tab_max_width = 16,
-}
 ```

docs/config/lua/config/term.md

@@ -8,8 +8,8 @@ data.
 If you want to get the most application support out of wezterm, then you may
 wish to install a copy of the `wezterm` TERM definition:
 
-```
+```console
-tempfile=$(mktemp) \
+$ tempfile=$(mktemp) \
   && curl -o $tempfile https://raw.githubusercontent.com/wez/wezterm/main/termwiz/data/wezterm.terminfo \
   && tic -x -o ~/.terminfo $tempfile \
   && rm $tempfile
@@ -29,11 +29,9 @@ If your package manager installed the terminfo data in a non-standard location,
 The following snippet works if you installed `wezterm.terminfo` with nix into your user profile. Update the path to `TERMINFO_DIRS` to match the location on your system.
 
 ```lua
-return {
+config.set_environment_variables = {
-  set_environment_variables = {
   TERMINFO_DIRS = '/home/user/.nix-profile/share/terminfo',
   WSLENV = 'TERMINFO_DIRS',
-  },
-  term = 'wezterm',
 }
+config.term = 'wezterm'
 ```

docs/config/lua/config/text_blink_rate.md

@@ -9,9 +9,7 @@ event loop schedulers manage timers; non-zero values will be at least the
 interval specified with some degree of slop.
 
 ```lua
-return {
+config.text_blink_rate = 500
-  text_blink_rate = 500,
-}
 ```
 
 *Since: 20220319-142410-0fcdea07*

docs/config/lua/config/text_blink_rate_rapid.md

@@ -9,9 +9,7 @@ event loop schedulers manage timers; non-zero values will be at least the
 interval specified with some degree of slop.
 
 ```lua
-return {
+config.text_blink_rate_rapid = 250
-  text_blink_rate_rapid = 250,
-}
 ```
 
 *Since: 20220319-142410-0fcdea07*

docs/config/lua/config/treat_left_ctrlalt_as_altgr.md

@@ -11,7 +11,5 @@ To fix this behavior you can tell WezTerm to treat left *Ctrl-Alt* keys as
 bindings using separate Ctrl and Alt won't be triggered anymore.
 
 ```lua
-return {
+config.treat_left_ctrlalt_as_altgr = true
-  treat_left_ctrlalt_as_altgr = true,
-}
 ```

docs/config/lua/config/use_ime.md

@@ -16,9 +16,7 @@ IME support is a platform dependent feature
 You can control whether the IME is enabled in your configuration file:
 
 ```lua
-return {
+config.use_ime = false
-  use_ime = false,
-}
 ```
 
 Changing `use_ime` usually requires re-launching WezTerm to take full effect.

docs/config/lua/config/visual_bell.md

@@ -32,28 +32,24 @@ The following easing functions are supported:
 The following configuration enables a low intensity visual bell that takes a total of 300ms to "flash" the screen:
 
 ```lua
-return {
+config.visual_bell = {
-  visual_bell = {
   fade_in_function = 'EaseIn',
   fade_in_duration_ms = 150,
   fade_out_function = 'EaseOut',
   fade_out_duration_ms = 150,
-  },
+}
-  colors = {
+config.colors = {
   visual_bell = '#202020',
-  },
 }
 ```
 
 The follow configuration make the cursor briefly flare when the bell is run:
 
 ```lua
-return {
+config.visual_bell = {
-  visual_bell = {
   fade_in_duration_ms = 75,
   fade_out_duration_ms = 75,
   target = 'CursorColor',
-  },
 }
 ```
 

docs/config/lua/config/webgpu_preferred_adapter.md

@@ -48,10 +48,7 @@ Based on that list, I might choose to explicitly target the discrete Gpu like
 this (but note that this would be the default selection anyway):
 
 ```lua
-local wezterm = require 'wezterm'
+config.webgpu_preferred_adapter = {
-
-return {
-  webgpu_preferred_adapter = {
   backend = 'Vulkan',
   device = 29730,
   device_type = 'DiscreteGpu',
@@ -59,21 +56,20 @@ return {
   driver_info = 'Mesa 22.3.4',
   name = 'AMD Radeon Pro W6400 (RADV NAVI24)',
   vendor = 4098,
-  },
-  front_end = 'WebGpu',
 }
+config.front_end = 'WebGpu'
 ```
 
 alternatively, I might use:
 
 ```lua
 local wezterm = require 'wezterm'
+local config = {}
 local gpus = wezterm.gui.enumerate_gpus()
 
-return {
+config.webgpu_preferred_adapter = gpus[1]
-  webgpu_preferred_adapter = gpus[1],
+config.front_end = 'WebGpu'
-  front_end = 'WebGpu',
+return config
-}
 ```
 
 If you have a more complex situation you can get a bit more elaborate; this
@@ -82,21 +78,17 @@ Vulkan drivers:
 
 ```lua
 local wezterm = require 'wezterm'
-local adapter = nil
+local config = {}
-local front_end = nil
 
 for _, gpu in ipairs(wezterm.gui.enumerate_gpus()) do
   if gpu.backend == 'Vulkan' and gpu.device_type == 'Integrated' then
-    adapter = gpu
+    config.webgpu_preferred_adapter = gpu
-    front_end = 'WebGpu'
+    config.front_end = 'WebGpu'
     break
   end
 end
 
-return {
+return config
-  webgpu_preferred_adapter = adapter,
-  front_end = front_end,
-}
 ```
 
 See also [webgpu_power_preference](webgpu_power_preference.md),

docs/config/lua/config/window_background_gradient.md

@@ -9,8 +9,7 @@ for `window_background_image` is ignored.
 Linear gradients with vertical or horizontal orientation are supported:
 
 ```lua
-return {
+config.window_background_gradient = {
-  window_background_gradient = {
   -- Can be "Vertical" or "Horizontal".  Specifies the direction
   -- in which the color gradient varies.  The default is "Horizontal",
   -- with the gradient going from left-to-right.
@@ -59,7 +58,6 @@ return {
 
   -- segment_size = 11,
   -- segment_smoothness = 0.0,
-  },
 }
 ```
 
@@ -86,12 +84,10 @@ clockwise, so `-45` is equivalent to `315` degrees and results in a gradient
 that is moving from the top left corner down to the bottom right corner.
 
 ```lua
-return {
+config.window_background_gradient = {
-  window_background_gradient = {
   colors = { '#EEBD89', '#D13ABD' },
   -- Specifices a Linear gradient starting in the top left corner.
   orientation = { Linear = { angle = -45.0 } },
-  },
 }
 ```
 
@@ -103,9 +99,8 @@ Radial gradients are implemented using a notional perfect circle that is
 subsequently stretched to fill the dimensions of the window.
 
 ```lua
-return {
+config.color_scheme = 'Github'
-  color_scheme = 'Github',
+config.window_background_gradient = {
-  window_background_gradient = {
   colors = { 'deeppink', 'gold' },
   orientation = {
     Radial = {
@@ -127,7 +122,6 @@ return {
       radius = 1.25,
     },
   },
-  },
 }
 ```
 

docs/config/lua/config/window_close_confirmation.md

@@ -8,9 +8,7 @@ Set this to `"NeverPrompt"` if you don't like confirming closing
 windows every time.
 
 ```lua
-return {
+config.window_close_confirmation = 'AlwaysPrompt'
-  window_close_confirmation = 'AlwaysPrompt',
-}
 ```
 
 See also

docs/config/lua/config/window_frame.md

@@ -10,8 +10,7 @@ It allows you to customize the colors of the window frame.
 Some of these colors are used by the fancy tab bar.
 
 ```lua
-return {
+config.window_frame = {
-  window_frame = {
   inactive_titlebar_bg = '#353535',
   active_titlebar_bg = '#2b2042',
   inactive_titlebar_fg = '#cccccc',
@@ -22,7 +21,6 @@ return {
   button_bg = '#2b2042',
   button_hover_fg = '#ffffff',
   button_hover_bg = '#3b3052',
-  },
 }
 ```
 
@@ -31,8 +29,7 @@ return {
 You may explicitly add a border around the window area:
 
 ```lua
-return {
+config.window_frame = {
-  window_frame = {
   border_left_width = '0.5cell',
   border_right_width = '0.5cell',
   border_bottom_height = '0.25cell',
@@ -41,6 +38,5 @@ return {
   border_right_color = 'purple',
   border_bottom_color = 'purple',
   border_top_color = 'purple',
-  },
 }
 ```

docs/config/lua/config/window_padding.md

@@ -11,13 +11,11 @@ enabled the scrollbar and have set `right` to `0` then the right padding
 (and thus the scrollbar width) will instead match the width of a cell.
 
 ```lua
-return {
+config.window_padding = {
-  window_padding = {
   left = 2,
   right = 2,
   top = 0,
   bottom = 0,
-  },
 }
 ```
 
@@ -36,13 +34,11 @@ You may use a fractional number such as `"0.5cell"` or numbers large than one su
 The default padding is shown below.  In earlier releases, the default padding was 0 for each of the possible edges.
 
 ```lua
-return {
+config.window_padding = {
-  window_padding = {
   left = '1cell',
   right = '1cell',
   top = '0.5cell',
   bottom = '0.5cell',
-  },
 }
 ```
 

docs/config/lua/config/xim_im_name.md

@@ -13,9 +13,7 @@ to quickly evaluate a different input method server, then you could
 update your config to specify it explicitly:
 
 ```lua
-return {
+config.xim_im_name = 'fcitx'
-  xim_im_name = 'fcitx',
-}
 ```
 
 will cause wezterm to connect to fcitx regardless of the value of `XMODIFIERS`.

docs/config/lua/general.md

@@ -6,55 +6,8 @@ be imported into your configuration file:
 
 ```lua
 local wezterm = require 'wezterm'
-return {
+local config = {}
-  font = wezterm.font 'JetBrains Mono',
+config.font = wezterm.font 'JetBrains Mono'
-}
+return config
 ```
 
-### Making your own Lua Modules
-
-If you'd like to break apart your configuration into multiple files, you'll
-be interested in this information.
-
-The `package.path` is configured with the following paths in this order:
-
-* On Windows: a `wezterm_modules` dir in the same directory as `wezterm.exe`
-* `~/.config/wezterm`
-* `~/.wezterm`
-* A system specific set of paths which may (or may not!) find locally installed lua modules
-
-That means that if you wanted to break your config up into a `helpers.lua` file
-you would place it in `~/.config/wezterm/helpers.lua` with contents like this:
-
-```lua
--- I am helpers.lua and I should live in ~/.config/wezterm/helpers.lua
-
-local wezterm = require 'wezterm'
-
--- This is the module table that we will export
-local module = {}
-
--- This function is private to this module and is not visible
--- outside.
-local function private_helper()
-  wezterm.log_error 'hello!'
-end
-
--- define a function in the module table.
--- Only functions defined in `module` will be exported to
--- code that imports this module
-function module.my_function()
-  private_helper()
-end
-
--- return our module table
-return module
-```
-
-and then in your `wezterm.lua`
-you would use it like this:
-
-```lua
-local helpers = require 'helpers'
-helpers.my_function()
-```

docs/config/lua/gui-events/gui-startup.md

@@ -35,6 +35,7 @@ This basic example splits an initial window into thirds:
 ```lua
 local wezterm = require 'wezterm'
 local mux = wezterm.mux
+local config = {}
 
 wezterm.on('gui-startup', function(cmd)
   local tab, pane, window = mux.spawn_window(cmd or {})
@@ -46,7 +47,7 @@ wezterm.on('gui-startup', function(cmd)
   pane:split { size = 0.5 }
 end)
 
-return {}
+return config
 ```
 
 This example creates a default window but makes it maximize on startup:
@@ -54,13 +55,14 @@ This example creates a default window but makes it maximize on startup:
 ```lua
 local wezterm = require 'wezterm'
 local mux = wezterm.mux
+local config = {}
 
 wezterm.on('gui-startup', function(cmd)
   local tab, pane, window = mux.spawn_window(cmd or {})
   window:gui_window():maximize()
 end)
 
-return {}
+return config
 ```
 
 Here's a more elaborate example that configures two workspaces:
@@ -68,6 +70,7 @@ Here's a more elaborate example that configures two workspaces:
 ```lua
 local wezterm = require 'wezterm'
 local mux = wezterm.mux
+local config = {}
 
 wezterm.on('gui-startup', function(cmd)
   -- allow `wezterm start -- something` to affect what we spawn
@@ -104,7 +107,7 @@ wezterm.on('gui-startup', function(cmd)
   mux.set_active_workspace 'coding'
 end)
 
-return {}
+return config
 ```
 
 See also:

docs/config/lua/keyassignment/ActivateCommandPalette.md

@@ -5,14 +5,12 @@
 Activates the Command Palette, a modal overlay that enables discovery and activation of various commands.
 
 ```lua
-return {
+config.keys = {
-  keys = {
   {
     key = 'P',
     mods = 'CTRL',
     action = wezterm.action.ActivateCommandPalette,
   },
-  },
 }
 ```
 

docs/config/lua/keyassignment/ActivateCopyMode.md

@@ -5,10 +5,8 @@
 Activates copy mode!
 
 ```lua
-return {
+config.keys = {
-  keys = {
   { key = 'X', mods = 'CTRL', action = wezterm.action.ActivateCopyMode },
-  },
 }
 ```
 

docs/config/lua/keyassignment/ActivateLastTab.md

@@ -5,16 +5,14 @@
 Activate the previously active tab. If there is none, it will do nothing.
 
 ```lua
-return {
+config.leader = { key = 'a', mods = 'CTRL' }
-  leader = { key = 'a', mods = 'CTRL' },
+config.keys = {
-  keys = {
   -- CTRL-a, followed by CTRL-o will switch back to the last active tab
   {
     key = 'o',
     mods = 'LEADER|CTRL',
     action = wezterm.action.ActivateLastTab,
   },
-  },
 }
 ```
 

docs/config/lua/keyassignment/ActivatePaneByIndex.md

@@ -11,12 +11,13 @@ panes, respectively:
 ```lua
 local wezterm = require 'wezterm'
 local act = wezterm.action
+local config = {}
 
-return {
+config.keys = {
-  keys = {
   { key = 'a', mods = 'ALT', action = act.ActivatePaneByIndex(0) },
   { key = 'b', mods = 'ALT', action = act.ActivatePaneByIndex(1) },
   { key = 'c', mods = 'ALT', action = act.ActivatePaneByIndex(2) },
-  },
 }
+
+return config
 ```

docs/config/lua/keyassignment/ActivatePaneDirection.md

@@ -12,9 +12,9 @@ by the [`unzoom_on_switch_pane`](../config/unzoom_on_switch_pane.md) flag.
 ```lua
 local wezterm = require 'wezterm'
 local act = wezterm.action
+local config = {}
 
-return {
+config.keys = {
-  keys = {
   {
     key = 'LeftArrow',
     mods = 'CTRL|SHIFT',
@@ -35,8 +35,8 @@ return {
     mods = 'CTRL|SHIFT',
     action = act.ActivatePaneDirection 'Down',
   },
-  },
 }
+return config
 ```
 
 *Since: 20220101-133340-7edc5b5a*

docs/config/lua/keyassignment/ActivateTab.md

@@ -13,25 +13,24 @@ to its left and so on.
 ```lua
 local wezterm = require 'wezterm'
 local act = wezterm.action
+local config = {}
 
-local mykeys = {}
+config.keys = {}
 for i = 1, 8 do
   -- CTRL+ALT + number to activate that tab
-  table.insert(mykeys, {
+  table.insert(config.keys, {
     key = tostring(i),
     mods = 'CTRL|ALT',
     action = act.ActivateTab(i - 1),
   })
   -- F1 through F8 to activate that tab
-  table.insert(mykeys, {
+  table.insert(config.keys, {
     key = 'F' .. tostring(i),
     action = act.ActivateTab(i - 1),
   })
 end
 
-return {
+return config
-  keys = mykeys,
-}
 ```
 
 

docs/config/lua/keyassignment/ActivateTabRelative.md

@@ -7,13 +7,14 @@ activates the tab to the right.
 ```lua
 local wezterm = require 'wezterm'
 local act = wezterm.action
+local config = {}
 
-return {
+config.keys = {
-  keys = {
   { key = '{', mods = 'ALT', action = act.ActivateTabRelative(-1) },
   { key = '}', mods = 'ALT', action = act.ActivateTabRelative(1) },
-  },
 }
+
+return config
 ```
 
 See also [ActivateTabRelativeNoWrap](ActivateTabRelativeNoWrap.md)

docs/config/lua/keyassignment/ActivateTabRelativeNoWrap.md

@@ -14,13 +14,13 @@ but this one will not wrap around; for example, if the first tab is active
 ```lua
 local wezterm = require 'wezterm'
 local act = wezterm.action
+local config = {}
 
-return {
+config.keys = {
-  keys = {
   { key = '{', mods = 'ALT', action = act.ActivateTabRelativeNoWrap(-1) },
   { key = '}', mods = 'ALT', action = act.ActivateTabRelativeNoWrap(1) },
-  },
 }
+return config
 ```
 
 

docs/config/lua/keyassignment/ActivateWindow.md

@@ -15,20 +15,19 @@ Here's an example of setting up hotkeys to activate specific windows:
 ```lua
 local wezterm = require 'wezterm'
 local act = wezterm.action
+local config = {}
 
-local mykeys = {}
+config.keys = {}
 for i = 1, 8 do
   -- CMD+ALT + number to activate that window
-  table.insert(mykeys, {
+  table.insert(config.keys, {
     key = tostring(i),
     mods = 'CMD|ALT',
     action = act.ActivateWindow(i - 1),
   })
 end
 
-return {
+return config
-  keys = mykeys,
-}
 ```
 
 

docs/config/lua/keyassignment/ActivateWindowRelative.md

@@ -16,13 +16,13 @@ windows:
 ```lua
 local wezterm = require 'wezterm'
 local act = wezterm.action
+local config = {}
 
-return {
+config.keys = {
-  keys = {
   { key = 'r', mods = 'ALT', action = act.ActivateWindowRelative(1) },
   { key = 'e', mods = 'ALT', action = act.ActivateWindowRelative(-1) },
-  },
 }
+return config
 ```
 
 See also [ActivateWindowRelativeNoWrap](ActivateWindowRelativeNoWrap.md),

docs/config/lua/keyassignment/ActivateWindowRelativeNoWrap.md

@@ -15,9 +15,9 @@ windows:
 ```lua
 local wezterm = require 'wezterm'
 local act = wezterm.action
+local config = {}
 
-return {
+config.keys = {
-  keys = {
   {
     key = 'r',
     mods = 'ALT',
@@ -28,8 +28,8 @@ return {
     mods = 'ALT',
     action = act.ActivateWindowRelativeNoWrap(-1),
   },
-  },
 }
+return config
 ```
 
 See also [ActivateWindowRelative](ActivateWindowRelative.md),

docs/config/lua/keyassignment/AdjustPaneSize.md

@@ -19,10 +19,10 @@ respectively.
 ```lua
 local wezterm = require 'wezterm'
 local act = wezterm.action
+local config = {}
 
-return {
+config.leader = { key = 'a', mods = 'CTRL' }
-  leader = { key = 'a', mods = 'CTRL' },
+config.keys = {
-  keys = {
   {
     key = 'H',
     mods = 'LEADER',
@@ -39,6 +39,6 @@ return {
     mods = 'LEADER',
     action = act.AdjustPaneSize { 'Right', 5 },
   },
-  },
 }
+return config
 ```

docs/config/lua/keyassignment/AttachDomain.md

@@ -19,22 +19,18 @@ entries with this action.
 The example below shows how to bind a key to trigger attaching to an ssh domain:
 
 ```lua
-local wezterm = require 'wezterm'
+config.ssh_domains = {
-
-return {
-  ssh_domains = {
   {
     name = 'devhost',
     remote_address = 'devhost.example.com',
   },
-  },
+}
-  keys = {
+config.keys = {
   {
     key = 'U',
     mods = 'CTRL|SHIFT',
     action = wezterm.action.AttachDomain 'devhost',
   },
-  },
 }
 ```
 

docs/config/lua/keyassignment/CharSelect.md

@@ -42,24 +42,19 @@ This action is by default assigned to `CTRL-SHIFT-U` (`U` for `Unicode`).
 The default assignment is equivalent to this config:
 
 ```lua
-local wezterm = require 'wezterm'
-local act = wezterm.action
-
-return {
 -- Control the size of the font.
 -- Uses the same font as window_frame.font
 -- char_select_font_size = 18.0,
 
-  keys = {
+config.keys = {
   {
     key = 'u',
     mods = 'SHIFT|CTRL',
-      action = act.CharSelect {
+    action = wezterm.action.CharSelect {
       copy_on_select = true,
       copy_to = 'ClipboardAndPrimarySelection',
     },
   },
-  },
 }
 ```
 

docs/config/lua/keyassignment/ClearScrollback.md

@@ -11,8 +11,7 @@ Added a parameter that allows additionally clear the viewport:
 local wezterm = require 'wezterm'
 local act = wezterm.action
 
-return {
+config.keys = {
-  keys = {
   -- Clears only the scrollback and leaves the viewport intact.
   -- You won't see a difference in what is on screen, you just won't
   -- be able to scroll back until you've output more stuff on screen.
@@ -38,6 +37,5 @@ return {
       act.SendKey { key = 'L', mods = 'CTRL' },
     },
   },
-  },
 }
 ```

docs/config/lua/keyassignment/ClearSelection.md

@@ -12,28 +12,20 @@ CTRL-C to the terminal when there is no selection:
 local wezterm = require 'wezterm'
 local act = wezterm.action
 
-return {
+config.keys = {
-  keys = {
   {
     key = 'c',
     mods = 'CTRL',
     action = wezterm.action_callback(function(window, pane)
       local has_selection = window:get_selection_text_for_pane(pane) ~= ''
       if has_selection then
-          window:perform_action(
+        window:perform_action(act.CopyTo 'ClipboardAndPrimarySelection', pane)
-            act.CopyTo 'ClipboardAndPrimarySelection',
-            pane
-          )
 
         window:perform_action(act.ClearSelection, pane)
       else
-          window:perform_action(
+        window:perform_action(act.SendKey { key = 'c', mods = 'CTRL' }, pane)
-            act.SendKey { key = 'c', mods = 'CTRL' },
-            pane
-          )
       end
     end),
   },
-  },
 }
 ```

docs/config/lua/keyassignment/CloseCurrentPane.md

@@ -8,16 +8,12 @@ The act of closing a pane shuts down the PTY associated with the pane and
 then kills the process associated with that pane.
 
 ```lua
-local wezterm = require 'wezterm'
+config.keys = {
-
-return {
-  keys = {
   {
     key = 'w',
     mods = 'CMD',
     action = wezterm.action.CloseCurrentPane { confirm = true },
   },
-  },
 }
 ```
 

docs/config/lua/keyassignment/CloseCurrentTab.md

@@ -4,14 +4,12 @@ Closes the current tab, terminating all contained panes.  If that was the last
 tab, closes that window.  If that was the last window, wezterm terminates.
 
 ```lua
-return {
+config.keys = {
-  keys = {
   {
     key = 'w',
     mods = 'CMD',
     action = wezterm.action.CloseCurrentTab { confirm = true },
   },
-  },
 }
 ```
 

docs/config/lua/keyassignment/CompleteSelection.md

@@ -11,10 +11,7 @@ which clipboard buffer the selection will populate; the copy action
 is now equivalent to [CopyTo](CopyTo.md).
 
 ```lua
-local wezterm = require 'wezterm'
+config.mouse_bindings = {
-
-return {
-  mouse_bindings = {
   -- Change the default click behavior so that it only selects
   -- text and doesn't open hyperlinks, and that it populates
   -- the Clipboard rather the PrimarySelection which is part
@@ -24,6 +21,5 @@ return {
     mods = 'NONE',
     action = wezterm.action.CompleteSelection 'Clipboard',
   },
-  },
 }
 ```

docs/config/lua/keyassignment/CompleteSelectionOrOpenLinkAtMouseCursor.md

@@ -12,10 +12,7 @@ which clipboard buffer the selection will populate. The copy action
 is now equivalent to [CopyTo](CopyTo.md).
 
 ```lua
-local wezterm = require 'wezterm'
+config.mouse_bindings = {
-
-return {
-  mouse_bindings = {
   -- Change the default click behavior so that it populates
   -- the Clipboard rather the PrimarySelection.
   {
@@ -23,6 +20,5 @@ return {
     mods = 'NONE',
     action = wezterm.action.CompleteSelectionOrOpenLinkAtMouseCursor 'Clipboard',
   },
-  },
 }
 ```

docs/config/lua/keyassignment/Copy.md

@@ -15,11 +15,8 @@ This action has been removed. Please use [CopyTo](CopyTo.md) instead.
 
 
 ```lua
-local wezterm = require 'wezterm'
+config.keys = {
-return {
-  keys = {
   { key = 'C', mods = 'CTRL', action = wezterm.action.Copy },
-  },
 }
 ```
 

docs/config/lua/keyassignment/CopyTo.md

@@ -9,16 +9,12 @@ Possible values for destination are:
 * `ClipboardAndPrimarySelection` - Copy to both the clipboard and the primary selection.
 
 ```lua
-local wezterm = require 'wezterm'
+config.keys = {
-
-return {
-  keys = {
   {
     key = 'C',
     mods = 'CTRL',
     action = wezterm.action.CopyTo 'ClipboardAndPrimarySelection',
   },
-  },
 }
 ```
 

docs/config/lua/keyassignment/DecreaseFontSize.md

@@ -3,12 +3,8 @@
 Decreases the font size of the current window by 10%
 
 ```lua
-local wezterm = require 'wezterm'
+config.keys = {
-
-return {
-  keys = {
   { key = '-', mods = 'CTRL', action = wezterm.action.DecreaseFontSize },
-  },
 }
 ```
 

docs/config/lua/keyassignment/DetachDomain.md

@@ -14,14 +14,13 @@ error log/debug overlay.
 local wezterm = require 'wezterm'
 local act = wezterm.action
 
-return {
+config.ssh_domains = {
-  ssh_domains = {
   {
     name = 'devhost',
     remote_address = 'devhost.example.com',
   },
-  },
+}
-  keys = {
+config.keys = {
   { key = 'U', mods = 'CTRL|SHIFT', action = act.AttachDomain 'devhost' },
   -- Detaches the domain associated with the current pane
   {
@@ -35,7 +34,6 @@ return {
     mods = 'CTRL|SHIFT',
     action = act.DetachDomain { DomainName = 'devhost' },
   },
-  },
 }
 ```
 

docs/config/lua/keyassignment/DisableDefaultAssignment.md

@@ -6,10 +6,7 @@ default assignments and cause the key press to be propagated through
 to the tab for processing.
 
 ```lua
-local wezterm = require 'wezterm'
+config.keys = {
-
-return {
-  keys = {
   -- Turn off the default CMD-m Hide action, allowing CMD-m to
   -- be potentially recognized and handled by the tab
   {
@@ -17,7 +14,6 @@ return {
     mods = 'CMD',
     action = wezterm.action.DisableDefaultAssignment,
   },
-  },
 }
 ```
 

docs/config/lua/keyassignment/ExtendSelectionToMouseCursor.md

@@ -9,16 +9,12 @@ the scope of the selection.
 The mode argument can also be `"Block"` to enable a rectangular block selection.
 
 ```lua
-local wezterm = require 'wezterm'
+config.mouse_bindings = {
-
-return {
-  mouse_bindings = {
   {
     event = { Up = { streak = 1, button = 'Left' } },
     mods = 'SHIFT',
     action = wezterm.action.ExtendSelectionToMouseCursor 'Word',
   },
-  },
 }
 ```
 

docs/config/lua/keyassignment/Hide.md

@@ -3,11 +3,7 @@
 Hides (or minimizes, depending on the platform) the current window.
 
 ```lua
-local wezterm = require 'wezterm'
+config.keys = {
-
-return {
-  keys = {
   { key = 'h', mods = 'CMD', action = wezterm.action.Hide },
-  },
 }
 ```

docs/config/lua/keyassignment/HideApplication.md

@@ -3,11 +3,7 @@
 On macOS, hide the WezTerm application.
 
 ```lua
-local wezterm = require 'wezterm'
+config.keys = {
-
-return {
-  keys = {
   { key = 'h', mods = 'CMD', action = wezterm.action.HideApplication },
-  },
 }
 ```

docs/config/lua/keyassignment/IncreaseFontSize.md

@@ -3,12 +3,8 @@
 Increases the font size of the current window by 10%
 
 ```lua
-local wezterm = require 'wezterm'
+config.keys = {
-
-return {
-  keys = {
   { key = '=', mods = 'CTRL', action = wezterm.action.IncreaseFontSize },
-  },
 }
 ```
 

docs/config/lua/keyassignment/MoveTab.md

@@ -6,20 +6,20 @@ from the left, and so on.
 
 ```lua
 local wezterm = require 'wezterm'
+local config = {}
+
+config.keys = {}
 
-local mykeys = {}
 for i = 1, 8 do
   -- CTRL+ALT + number to move to that position
-  table.insert(mykeys, {
+  table.insert(config.keys, {
     key = tostring(i),
     mods = 'CTRL|ALT',
     action = wezterm.action.MoveTab(i - 1),
   })
 end
 
-return {
+return config
-  keys = mykeys,
-}
 ```
 
 

docs/config/lua/keyassignment/MoveTabRelative.md

@@ -5,14 +5,11 @@ offset. eg: `-1` moves the tab to the left of the current tab, while `1` moves
 the tab to the right.
 
 ```lua
-local wezterm = require 'wezterm'
 local act = wezterm.action
 
-return {
+config.keys = {
-  keys = {
   { key = '{', mods = 'SHIFT|ALT', action = act.MoveTabRelative(-1) },
   { key = '}', mods = 'SHIFT|ALT', action = act.MoveTabRelative(1) },
-  },
 }
 ```
 

docs/config/lua/keyassignment/Multiple.md

@@ -8,11 +8,9 @@ want a single key press to trigger multiple actions.
 The example below causes `LeftArrow` to effectively type `left`:
 
 ```lua
-local wezterm = require 'wezterm'
 local act = wezterm.action
 
-return {
+config.keys = {
-  keys = {
   {
     key = 'LeftArrow',
     action = act.Multiple {
@@ -22,6 +20,5 @@ return {
       act.SendKey { key = 't' },
     },
   },
-  },
 }
 ```

docs/config/lua/keyassignment/Nop.md

@@ -7,13 +7,9 @@ If instead of this you want the key presses to pass through to
 the terminal, look at [DisableDefaultAssignment](DisableDefaultAssignment.md).
 
 ```lua
-local wezterm = require 'wezterm'
+config.keys = {
-
-return {
-  keys = {
   -- Turn off any side effects from pressing CMD-m
   { key = 'm', mods = 'CMD', action = wezterm.action.Nop },
-  },
 }
 ```
 

docs/config/lua/keyassignment/OpenLinkAtMouseCursor.md

@@ -4,16 +4,12 @@ If the current mouse cursor position is over a cell that contains
 a hyperlink, this action causes that link to be opened.
 
 ```lua
-local wezterm = require 'wezterm'
+config.mouse_bindings = {
-
-return {
-  mouse_bindings = {
   -- Ctrl-click will open the link under the mouse cursor
   {
     event = { Up = { streak = 1, button = 'Left' } },
     mods = 'CTRL',
     action = wezterm.action.OpenLinkAtMouseCursor,
   },
-  },
 }
 ```

docs/config/lua/keyassignment/PaneSelect.md

@@ -23,12 +23,11 @@ The selection alphabet defaults to the same value as [quick_select_alphabet](../
 local wezterm = require 'wezterm'
 local act = wezterm.action
 
-return {
 -- 36 is the default, but you can choose a different size.
 -- Uses the same font as window_frame.font
-  -- pane_select_font_size=36,
+-- config.pane_select_font_size=36,
 
-  keys = {
+config.keys = {
   -- activate pane selection mode with the default alphabet (labels are "a", "s", "d", "f" and so on)
   { key = '8', mods = 'CTRL', action = act.PaneSelect },
   -- activate pane selection mode with numeric labels
@@ -47,7 +46,6 @@ return {
       mode = 'SwapWithActive',
     },
   },
-  },
 }
 ```