wez/wezterm
1
1
Fork 0
mirror of https://github.com/wez/wezterm.git synced 2024-11-25 10:22:43 +03:00
Code Issues Projects Releases Wiki Activity

docs: some adjustments for mkdocs

Browse Source
This commit is contained in:
Wez Furlong 2023-03-15 20:54:02 -07:00
parent 4770b38737
commit 107bcf6a89
No known key found for this signature in database
GPG Key ID: 7A7F66A31EC9B387
20 changed files with 105 additions and 90 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

6
ci/generate-docs.py
View File

@ -355,7 +355,7 @@ TOC = [
], ],
), ),
Page( Page(
"Install", "Download",
"installation.md", "installation.md",
children=[ children=[
Page("Windows", "install/windows.md"), Page("Windows", "install/windows.md"),
@ -369,6 +369,7 @@ TOC = [
"Configuration", "Configuration",
"config/files.md", "config/files.md",
children=[ children=[
Page("Colors & Appearance", "config/appearance.md"),
Page("Launching Programs", "config/launch.md"), Page("Launching Programs", "config/launch.md"),
Page("Fonts", "config/fonts.md"), Page("Fonts", "config/fonts.md"),
Page("Font Shaping", "config/font-shaping.md"), Page("Font Shaping", "config/font-shaping.md"),
@ -378,7 +379,6 @@ TOC = [
Page("Default Key Assignments", "config/default-keys.md"), Page("Default Key Assignments", "config/default-keys.md"),
Page("Keyboard Encoding", "config/key-encoding.md"), Page("Keyboard Encoding", "config/key-encoding.md"),
Page("Mouse Binding", "config/mouse.md"), Page("Mouse Binding", "config/mouse.md"),
Page("Colors & Appearance", "config/appearance.md"),
GenColorScheme("Color Schemes", "colorschemes"), GenColorScheme("Color Schemes", "colorschemes"),
Gen("Recipes", "recipes", extract_title=True), Gen("Recipes", "recipes", extract_title=True),
], ],
@ -479,9 +479,9 @@ TOC = [
"Get Help", "Get Help",
None, None,
children=[ children=[
Page("Getting Help", "help.md"),
Page("Troubleshooting", "troubleshooting.md"), Page("Troubleshooting", "troubleshooting.md"),
Page("F.A.Q.", "faq.md"), Page("F.A.Q.", "faq.md"),
Page("Getting Help", "help.md"),
Page("Contributing", "contributing.md"), Page("Contributing", "contributing.md"),
], ],
), ),

10
docs/config/default-keys.md
View File

@ -1,5 +1,3 @@
## Default Shortcut / Key Binding Assignments
The default key assignments are shown in the table below. The default key assignments are shown in the table below.
You may also use `wezterm show-keys --lua` to see the assignments You may also use `wezterm show-keys --lua` to see the assignments
@ -92,3 +90,11 @@ return {
} }
``` ```
!!! tip
When using `disable_default_key_bindings`, it is recommended that you
assign [ShowDebugOverlay](lua/keyassignment/ShowDebugOverlay.md) to
something to aid in potential future troubleshooting.
Likewise, you may wish to assign
[ActivateCommandPalette](lua/keyassignment/ActivateCommandPalette.md).

32
docs/config/files.md
View File

@ -3,8 +3,9 @@
`wezterm` will look for a [lua](https://www.lua.org/manual/5.3/manual.html) `wezterm` will look for a [lua](https://www.lua.org/manual/5.3/manual.html)
configuration file using the logic shown below. configuration file using the logic shown below.
The recommendation is to place your configuration file at `$HOME/.wezterm.lua` !!! tip
to get started. The recommendation is to place your configuration file at `$HOME/.wezterm.lua`
(`%HOME%/.wezterm.lua` on Windows) to get started.
More complex configurations that need to span multiple files can be placed in More complex configurations that need to span multiple files can be placed in
`$XDG_CONFIG_HOME/wezterm/wezterm.lua` (for X11/Wayland) or `$XDG_CONFIG_HOME/wezterm/wezterm.lua` (for X11/Wayland) or
@ -33,22 +34,25 @@ failed to parse, wezterm would treat it as though it didn't exist and continue
to try other candidate file locations. In all current versions of wezterm, an to try other candidate file locations. In all current versions of wezterm, an
error will be shown and the default configuration will be used instead. error will be shown and the default configuration will be used instead.
Note that on Windows, to support users that carry their wezterm application and !!! note
configuration around on a thumb drive, wezterm will look for the config file in On Windows, to support users that carry their wezterm application and
the same location as wezterm.exe. That is shown in the chart above as thumb configuration around on a thumb drive, wezterm will look for the config file in
drive mode. the same location as wezterm.exe. That is shown in the chart above as thumb
drive mode. It is **not** recommended to store your configs in that
location if you are not running off a thumb drive.
`wezterm` will watch the config file that it loads; if/when it changes, the `wezterm` will watch the config file that it loads; if/when it changes, the
configuration will be automatically reloaded and the majority of options will configuration will be automatically reloaded and the majority of options will
take effect immediately. You may also use the `CTRL+SHIFT+R` keyboard shortcut take effect immediately. You may also use the `CTRL+SHIFT+R` keyboard shortcut
to force the configuration to be reloaded. to force the configuration to be reloaded.
**The configuration file may be evaluated multiple times for each wezterm !!! info
process** both at startup and in response to the configuration file being **The configuration file may be evaluated multiple times for each wezterm
reloaded. You should avoid taking actions in the main flow of the config file process** both at startup and in response to the configuration file being
that have side effects; for example, unconditionally launching background reloaded. You should avoid taking actions in the main flow of the config file
processes can result in many of them being spawned over time if you launch that have side effects; for example, unconditionally launching background
many copies of wezterm, or are frequently reloading your config file. processes can result in many of them being spawned over time if you launch
many copies of wezterm, or are frequently reloading your config file.
### Configuration Overrides ### Configuration Overrides
@ -110,5 +114,7 @@ return {
} }
``` ```
## Configuration Reference
Continue browsing this section of the docs for an overview of the commonly
adjusted settings, or visit the [Lua Config Reference](lua/config/index.md) for a more detailed list of possibilities.

17
docs/config/fonts.md
View File

@ -1,7 +1,7 @@
### Font Related Configuration ### Font Related Configuration
WezTerm bundles [JetBrains Mono](https://www.jetbrains.com/lp/mono/), WezTerm bundles [JetBrains Mono](https://www.jetbrains.com/lp/mono/),
[PowerlineExtraSymbols](https://github.com/ryanoasis/powerline-extra-symbols) and [Nerd Font Symbols](https://nerdfonts.com) and
[Noto Color Emoji](https://www.google.com/get/noto/help/emoji/) fonts [Noto Color Emoji](https://www.google.com/get/noto/help/emoji/) fonts
and uses those for the default font configuration. and uses those for the default font configuration.
@ -26,10 +26,9 @@ text into glyphs the first font in the list is consulted, and if the
glyph isn't present in that font, WezTerm proceeds to the next font glyph isn't present in that font, WezTerm proceeds to the next font
in the fallback list. in the fallback list.
The default fallback includes the popular The default fallback includes the popular [Nerd Font
[PowerlineExtraSymbols](https://github.com/ryanoasis/powerline-extra-symbols) Symbols](https://nerdfonts.com) font, which means that you don't need to use
font, which means that you don't need to use specially patched fonts to use the specially patched fonts to use the powerline or Nerd Fonts symbol glyphs.
powerline glyphs.
You can specify your own fallback; that's useful if you've got a killer You can specify your own fallback; that's useful if you've got a killer
monospace font, but it doesn't have glyphs for the asian script that you monospace font, but it doesn't have glyphs for the asian script that you
@ -80,7 +79,7 @@ You may use `wezterm ls-fonts` to have wezterm explain information about which f
It shows output like this: It shows output like this:
``` ```console
$ wezterm ls-fonts $ wezterm ls-fonts
Primary font: Primary font:
wezterm.font_with_fallback({ wezterm.font_with_fallback({
@ -121,7 +120,7 @@ wezterm.font_with_fallback({
You can ask wezterm to including a listing of all of the fonts on the system in a form that can be copied and pasted into the configuration file: You can ask wezterm to including a listing of all of the fonts on the system in a form that can be copied and pasted into the configuration file:
``` ```console
$ wezterm ls-fonts --list-system $ wezterm ls-fonts --list-system
<same output as above, but then:> <same output as above, but then:>
112 fonts found in your font_dirs + built-in fonts: 112 fonts found in your font_dirs + built-in fonts:
@ -152,8 +151,8 @@ You may also display the shaping plan for a given text string; in this example,
the `a` and the `b` are separated by a special symbol which is not present in the `a` and the `b` are separated by a special symbol which is not present in
the main font, so we expect to see a different font used for that glyph: the main font, so we expect to see a different font used for that glyph:
``` ```console
wezterm ls-fonts --text a🞄b $ wezterm ls-fonts --text a🞄b
a \u{61} x_adv=8 glyph=29 wezterm.font("Operator Mono SSm Lig", {weight="DemiLight", stretch="Normal", italic=false}) a \u{61} x_adv=8 glyph=29 wezterm.font("Operator Mono SSm Lig", {weight="DemiLight", stretch="Normal", italic=false})
/home/wez/.fonts/OperatorMonoSSmLig-Medium.otf, FontDirs /home/wez/.fonts/OperatorMonoSSmLig-Medium.otf, FontDirs
🞄 \u{1f784} x_adv=4 glyph=9129 wezterm.font("Symbola", {weight="Regular", stretch="SemiCondensed", italic=false}) 🞄 \u{1f784} x_adv=4 glyph=9129 wezterm.font("Symbola", {weight="Regular", stretch="SemiCondensed", italic=false})

2
docs/config/key-tables.md
View File

@ -1,5 +1,3 @@
## Key Tables
*Since: 20220408-101518-b908e2dd* *Since: 20220408-101518-b908e2dd*
In addition to the default key table defined by the `keys` configuration In addition to the default key table defined by the `keys` configuration

2
docs/config/keyboard-concepts.md
View File

@ -1,5 +1,3 @@
## Keyboard Concepts
`wezterm` allows assigning action(s) to specific key events, and comes `wezterm` allows assigning action(s) to specific key events, and comes
pre-configured with a number of commonly useful assignments. pre-configured with a number of commonly useful assignments.

42
docs/config/launch.md
View File

@ -4,31 +4,31 @@ By default, when opening new tabs or windows, your shell will be spawned.
Your shell is determined by the following rules: Your shell is determined by the following rules:
### On Posix Systems === "On Posix Systems"
1. The value of the `$SHELL` environment variable is used if it is set 1. The value of the `$SHELL` environment variable is used if it is set
2. Otherwise, it will resolve your current uid and try to look up your 2. Otherwise, it will resolve your current uid and try to look up your
shell from the password database. shell from the password database.
`wezterm` will spawn the shell and pass `-l` as an argument to request `wezterm` will spawn the shell and pass `-l` as an argument to request
a login shell. A login shell generally loads additional startup files a login shell. A login shell generally loads additional startup files
and sets up more environment than a non-login shell. and sets up more environment than a non-login shell.
*Since: 20210502-154244-3f7122cb*: instead of passing `-l` to the shell, wezterm *Since: 20210502-154244-3f7122cb*: instead of passing `-l` to the shell, wezterm
will spawn the shell as `-$SHELL` to invoke it as a login shell. will spawn the shell as `-$SHELL` to invoke it as a login shell.
Note: if you have recently changed your shell using `chsh` and you Note: if you have recently changed your shell using `chsh` and you
have `$SHELL` set in the environment, you will need to sign out and have `$SHELL` set in the environment, you will need to sign out and
sign back in again for the environment to pick up your new `$SHELL` sign back in again for the environment to pick up your new `$SHELL`
value. value.
*Since: 20220903-194523-3bb1ed61*: wezterm will now always resolve the shell via the *Since: 20220903-194523-3bb1ed61*: wezterm will now always resolve the shell via the
password database. password database.
### On Windows Systems === "On Windows Systems"
1. The value of the `%COMSPEC%` environment variable is used if it is set. 1. The value of the `%COMSPEC%` environment variable is used if it is set.
2. Otherwise, `cmd.exe` 2. Otherwise, `cmd.exe`
## Changing the default program ## Changing the default program
@ -51,8 +51,8 @@ for example, open an editor in wezterm you can use the `start` subcommand
to launch it. This example opens up a new terminal window running vim to launch it. This example opens up a new terminal window running vim
to edit your wezterm configuration: to edit your wezterm configuration:
```bash ```console
wezterm start -- vim ~/.wezterm.lua $ wezterm start -- vim ~/.wezterm.lua
``` ```
## Specifying the current working directory ## Specifying the current working directory
@ -71,8 +71,8 @@ directory you can do so via the config, CLI, and when using
* One off program in a specific working directory via the CLI: * One off program in a specific working directory via the CLI:
```bash ```console
wezterm start --cwd /some/path $ wezterm start --cwd /some/path
``` ```
* The [`SpawnCommandInNewTab`](lua/keyassignment/SpawnCommandInNewTab.md), * The [`SpawnCommandInNewTab`](lua/keyassignment/SpawnCommandInNewTab.md),

2
docs/copymode.md
View File

@ -1,5 +1,3 @@
## Copy Mode
*since: 20200607-144723-74889cd4* *since: 20200607-144723-74889cd4*
Copy mode allows you to make selections using the keyboard; no need to reach Copy mode allows you to make selections using the keyboard; no need to reach

7
docs/features.md
View File

@ -1,3 +1,8 @@
---
hide:
- toc
---
## Available Features ## Available Features
* Runs on Linux, macOS, Windows 10 and FreeBSD * Runs on Linux, macOS, Windows 10 and FreeBSD
@ -12,7 +17,7 @@
* Multiple Windows (Hotkey: `Super-N`) * Multiple Windows (Hotkey: `Super-N`)
* Splits/Panes (Split horizontally/vertically: `Ctrl-Shift-Alt-%` and `Ctrl-Shift-Alt-"`, move between panes: `Ctrl-Shift-ArrowKey`) * Splits/Panes (Split horizontally/vertically: `Ctrl-Shift-Alt-%` and `Ctrl-Shift-Alt-"`, move between panes: `Ctrl-Shift-ArrowKey`)
* Tabs (Hotkey: `Super-T`, next/prev: `Super-Shift-[` and `Super-Shift-]`, go-to: `Super-[1-9]`) * Tabs (Hotkey: `Super-T`, next/prev: `Super-Shift-[` and `Super-Shift-]`, go-to: `Super-[1-9]`)
<video width="80%" controls src="screenshots/wezterm-tabs.mp4" loop></video> <video width="80%" controls src="../screenshots/wezterm-tabs.mp4" loop></video>
* [SSH client with native tabs](ssh.md) * [SSH client with native tabs](ssh.md)
* [Connect to serial ports for embedded/Arduino work](serial.md) * [Connect to serial ports for embedded/Arduino work](serial.md)
* Connect to a local multiplexer server over unix domain sockets * Connect to a local multiplexer server over unix domain sockets

2
docs/hyperlinks.md
View File

@ -1,5 +1,3 @@
## Hyperlinks
wezterm has support for both implicit and explicit hyperlinks. wezterm has support for both implicit and explicit hyperlinks.
### Implicit Hyperlinks ### Implicit Hyperlinks

2
docs/imgcat.md
View File

@ -1,5 +1,3 @@
## iTerm Image Protocol Support
wezterm implements support for the [iTerm2 inline images wezterm implements support for the [iTerm2 inline images
protocol](https://iterm2.com/documentation-images.html) and provides a handy protocol](https://iterm2.com/documentation-images.html) and provides a handy
`imgcat` subcommand to make it easy to try out. Because the protocol is `imgcat` subcommand to make it easy to try out. Because the protocol is

16
docs/index.md
View File

@ -1,7 +1,13 @@
---
hide:
- toc
---
<img alt="WezTerm Icon" height="128" src="https://raw.githubusercontent.com/wez/wezterm/master/assets/icon/wezterm-icon.svg" align="left" style="padding-right: 1em"> *WezTerm is a GPU-accelerated cross-platform terminal emulator and multiplexer written by <a href="https://github.com/wez/">@wez</a> and implemented in <a href="https://www.rust-lang.org/">Rust</a>* *WezTerm is a powerful cross-platform terminal emulator and multiplexer written by <a href="https://github.com/wez/">@wez</a> and implemented in <a href="https://www.rust-lang.org/">Rust</a>*
<a class="btn" href="installation.md">Download</a> ![Screenshot](screenshots/wezterm-vday-screenshot.png)
[Download :material-tray-arrow-down:](installation.md){ .md-button }
## Features ## Features
@ -16,7 +22,9 @@ Looking for a [configuration reference?](config/files.md)
**These docs are searchable: press `S` or click on the magnifying glass icon **These docs are searchable: press `S` or click on the magnifying glass icon
to activate the search function!** to activate the search function!**
<figure markdown>
![Screenshot](screenshots/two.png) ![Screenshot](screenshots/two.png)
*Screenshot of wezterm on macOS, running vim* <figcaption>Screenshot of wezterm on macOS, running vim</figcaption>
</figure>

5
docs/installation.md
View File

@ -1,3 +1,8 @@
---
hide:
- navigation
---
WezTerm is available pre-built for the major platforms and, because it is open WezTerm is available pre-built for the major platforms and, because it is open
source, you may also build it for yourself. source, you may also build it for yourself.

8
docs/mkdocs-base.yml
View File

@ -10,7 +10,7 @@ site_dir: gh_pages
theme: theme:
name: material name: material
logo: favicon.svg logo: favicon.svg
favicon: favicon.svg favicon: favicon.png
custom_dir: docs/overrides custom_dir: docs/overrides
palette: palette:
- media: "(prefers-color-scheme: light)" - media: "(prefers-color-scheme: light)"
@ -80,6 +80,8 @@ markdown_extensions:
- attr_list - attr_list
- md_in_html - md_in_html
- def_list - def_list
- toc:
permalink: true
- pymdownx.highlight: - pymdownx.highlight:
anchor_linenums: true anchor_linenums: true
line_spans: __span line_spans: __span
@ -103,3 +105,7 @@ extra:
social: social:
- icon: fontawesome/brands/github - icon: fontawesome/brands/github
link: https://github.com/wez/wezterm link: https://github.com/wez/wezterm
- icon: fontawesome/brands/mastodon
link: https://fosstodon.org/@wez
- icon: fontawesome/brands/twitter
link: https://twitter.com/wezfurlong

12
docs/multiplexing.md
View File

@ -1,5 +1,5 @@
**Notice:** *multiplexing is still a young feature and is evolving rapidly. !!! note
Your feedback is welcomed!* *multiplexing is still a young feature and is evolving rapidly. Your feedback is welcomed!*
## Multiplexing ## Multiplexing
@ -55,7 +55,7 @@ settings to use with SSH domains.
To connect to the system, run: To connect to the system, run:
```bash ```console
$ wezterm connect my.server $ wezterm connect my.server
``` ```
@ -96,7 +96,7 @@ return {
If you prefer to connect manually, omit the `default_gui_startup_args` setting If you prefer to connect manually, omit the `default_gui_startup_args` setting
and then run: and then run:
```bash ```console
$ wezterm connect unix $ wezterm connect unix
``` ```
@ -217,7 +217,7 @@ Now when you start wezterm you'll be presented with a WSL tab.
You can also omit `default_gui_startup_args` and use: You can also omit `default_gui_startup_args` and use:
```bash ```console
$ wezterm connect wsl $ wezterm connect wsl
``` ```
@ -285,6 +285,6 @@ will automatically reconnect using the certificate it obtained during
bootstrapping if your connection was interrupted and resume your bootstrapping if your connection was interrupted and resume your
remote terminal session remote terminal session
```bash ```console
$ wezterm connect server.name $ wezterm connect server.name
``` ```

2
docs/quickselect.md
View File

@ -1,5 +1,3 @@
## Quick Select Mode
*Since: 20210502-154244-3f7122cb* *Since: 20210502-154244-3f7122cb*
Quick Select mode allows you to quickly highlight text that matches Quick Select mode allows you to quickly highlight text that matches

2
docs/scrollback.md
View File

@ -1,5 +1,3 @@
## Scrollback
WezTerm provides a searchable scrollback buffer with a configurable maximum WezTerm provides a searchable scrollback buffer with a configurable maximum
size limit that allows you to review information that doesn't fit in the size limit that allows you to review information that doesn't fit in the
physical window size. As content is printed to the display the display may be physical window size. As content is printed to the display the display may be

8
docs/serial.md
View File

@ -1,24 +1,22 @@
## Serial Ports
wezterm can also connect to serial ports as a client. This is useful wezterm can also connect to serial ports as a client. This is useful
for example when working with embedded devices such as Arduino, or for example when working with embedded devices such as Arduino, or
when connecting to a serial console on a headless server. when connecting to a serial console on a headless server.
For example, on Linux: For example, on Linux:
```bash ```console
$ wezterm serial /dev/ttyUSB0 $ wezterm serial /dev/ttyUSB0
``` ```
or on Windows: or on Windows:
```bash ```console
$ wezterm serial COM0 $ wezterm serial COM0
``` ```
You can also specify the baud rate: You can also specify the baud rate:
```bash ```console
$ wezterm serial --baud 38400 /dev/ttyUSB0 $ wezterm serial --baud 38400 /dev/ttyUSB0
``` ```

12
docs/shell-integration.md
View File

@ -1,5 +1,3 @@
## Shell Integration
wezterm supports integrating with the shell through the following means: wezterm supports integrating with the shell through the following means:
* `OSC 7` Escape sequences to advise the terminal of the working directory * `OSC 7` Escape sequences to advise the terminal of the working directory
@ -28,7 +26,7 @@ can be found below.
[Learn more about OSC 133 Semantic Prompt Escapes](https://gitlab.freedesktop.org/Per_Bothner/specifications/blob/master/proposals/semantic-prompts.md). [Learn more about OSC 133 Semantic Prompt Escapes](https://gitlab.freedesktop.org/Per_Bothner/specifications/blob/master/proposals/semantic-prompts.md).
### User Vars ## User Vars
`OSC 1337` provides a means for setting *user vars*, which are somewhat similar `OSC 1337` provides a means for setting *user vars*, which are somewhat similar
to environment variables, except that they are variables associated with a to environment variables, except that they are variables associated with a
@ -66,7 +64,7 @@ struct.
You may wish to use this information to adjust what is shown in your tab titles You may wish to use this information to adjust what is shown in your tab titles
or in the status area. or in the status area.
### OSC 7 Escape sequence to set the working directory ## OSC 7 Escape sequence to set the working directory
`OSC 7` means Operating System Command number 7. This is an escape sequence `OSC 7` means Operating System Command number 7. This is an escape sequence
that originated in the macOS Terminal application that is used to advise the that originated in the macOS Terminal application that is used to advise the
@ -91,7 +89,7 @@ zsh source a `vte.sh` script that configures the shell to emit this
sequence. On other systems you will likely need to configure this sequence. On other systems you will likely need to configure this
for yourself. for yourself.
### OSC 7 on Windows with cmd.exe ## OSC 7 on Windows with cmd.exe
`cmd.exe` doesn't allow a lot of flexibility in configuring the prompt, `cmd.exe` doesn't allow a lot of flexibility in configuring the prompt,
but fortunately it does allow for emitting escape sequences. You but fortunately it does allow for emitting escape sequences. You
@ -109,7 +107,7 @@ return {
} }
``` ```
### OSC 7 on Windows with powershell ## OSC 7 on Windows with powershell
You can configure a custom prompt in powershell by creating/editing your You can configure a custom prompt in powershell by creating/editing your
[powershell profile](https://docs.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_profiles?view=powershell-7.1) [powershell profile](https://docs.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_profiles?view=powershell-7.1)
@ -128,7 +126,7 @@ function prompt {
} }
``` ```
### OSC 7 on Windows with powershell (with starship) ## OSC 7 on Windows with powershell (with starship)
When using [Starship](https://starship.rs/), since it has taken control of the prompt, hooking in to set When using [Starship](https://starship.rs/), since it has taken control of the prompt, hooking in to set
OSC 7 can be achieved this way instead: OSC 7 can be achieved this way instead:

4
docs/ssh.md
View File

@ -1,10 +1,8 @@
## SSH Connections
wezterm uses an embedded ssh library to provide an integrated SSH client. The wezterm uses an embedded ssh library to provide an integrated SSH client. The
client can be used to make ad-hoc SSH connections to remote hosts client can be used to make ad-hoc SSH connections to remote hosts
by invoking the client like this: by invoking the client like this:
```bash ```console
$ wezterm ssh wez@my.server $ wezterm ssh wez@my.server
``` ```