mirror of
https://github.com/wez/wezterm.git
synced 2024-11-25 02:13:09 +03:00
docs: some adjustments for mkdocs
This commit is contained in:
Wez Furlong
parent
4770b38737
commit
107bcf6a89
@ -355,7 +355,7 @@ TOC = [
|
||||
],
|
||||
),
|
||||
Page(
|
||||
"Install",
|
||||
"Download",
|
||||
"installation.md",
|
||||
children=[
|
||||
Page("Windows", "install/windows.md"),
|
||||
@ -369,6 +369,7 @@ TOC = [
|
||||
"Configuration",
|
||||
"config/files.md",
|
||||
children=[
|
||||
Page("Colors & Appearance", "config/appearance.md"),
|
||||
Page("Launching Programs", "config/launch.md"),
|
||||
Page("Fonts", "config/fonts.md"),
|
||||
Page("Font Shaping", "config/font-shaping.md"),
|
||||
@ -378,7 +379,6 @@ TOC = [
|
||||
Page("Default Key Assignments", "config/default-keys.md"),
|
||||
Page("Keyboard Encoding", "config/key-encoding.md"),
|
||||
Page("Mouse Binding", "config/mouse.md"),
|
||||
Page("Colors & Appearance", "config/appearance.md"),
|
||||
GenColorScheme("Color Schemes", "colorschemes"),
|
||||
Gen("Recipes", "recipes", extract_title=True),
|
||||
],
|
||||
@ -479,9 +479,9 @@ TOC = [
|
||||
"Get Help",
|
||||
None,
|
||||
children=[
|
||||
Page("Getting Help", "help.md"),
|
||||
Page("Troubleshooting", "troubleshooting.md"),
|
||||
Page("F.A.Q.", "faq.md"),
|
||||
Page("Getting Help", "help.md"),
|
||||
Page("Contributing", "contributing.md"),
|
||||
],
|
||||
),
|
||||
|
||||
@ -1,5 +1,3 @@
|
||||
## Default Shortcut / Key Binding Assignments
|
||||
|
||||
The default key assignments are shown in the table below.
|
||||
|
||||
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).
|
||||
|
||||
|
||||
@ -3,8 +3,9 @@
|
||||
`wezterm` will look for a [lua](https://www.lua.org/manual/5.3/manual.html)
|
||||
configuration file using the logic shown below.
|
||||
|
||||
!!! tip
|
||||
The recommendation is to place your configuration file at `$HOME/.wezterm.lua`
|
||||
to get started.
|
||||
(`%HOME%/.wezterm.lua` on Windows) to get started.
|
||||
|
||||
More complex configurations that need to span multiple files can be placed in
|
||||
`$XDG_CONFIG_HOME/wezterm/wezterm.lua` (for X11/Wayland) or
|
||||
@ -33,16 +34,19 @@ 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
|
||||
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
|
||||
On Windows, to support users that carry their wezterm application and
|
||||
configuration around on a thumb drive, wezterm will look for the config file in
|
||||
the same location as wezterm.exe. That is shown in the chart above as thumb
|
||||
drive mode.
|
||||
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
|
||||
configuration will be automatically reloaded and the majority of options will
|
||||
take effect immediately. You may also use the `CTRL+SHIFT+R` keyboard shortcut
|
||||
to force the configuration to be reloaded.
|
||||
|
||||
!!! info
|
||||
**The configuration file may be evaluated multiple times for each wezterm
|
||||
process** both at startup and in response to the configuration file being
|
||||
reloaded. You should avoid taking actions in the main flow of the config file
|
||||
@ -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.
|
||||
|
||||
@ -1,7 +1,7 @@
|
||||
### Font Related Configuration
|
||||
|
||||
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
|
||||
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
|
||||
in the fallback list.
|
||||
|
||||
The default fallback includes the popular
|
||||
[PowerlineExtraSymbols](https://github.com/ryanoasis/powerline-extra-symbols)
|
||||
font, which means that you don't need to use specially patched fonts to use the
|
||||
powerline glyphs.
|
||||
The default fallback includes the popular [Nerd Font
|
||||
Symbols](https://nerdfonts.com) font, which means that you don't need to use
|
||||
specially patched fonts to use the powerline or Nerd Fonts symbol glyphs.
|
||||
|
||||
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
|
||||
@ -80,7 +79,7 @@ You may use `wezterm ls-fonts` to have wezterm explain information about which f
|
||||
|
||||
It shows output like this:
|
||||
|
||||
```
|
||||
```console
|
||||
$ wezterm ls-fonts
|
||||
Primary font:
|
||||
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:
|
||||
|
||||
```
|
||||
```console
|
||||
$ wezterm ls-fonts --list-system
|
||||
<same output as above, but then:>
|
||||
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 main font, so we expect to see a different font used for that glyph:
|
||||
|
||||
```
|
||||
wezterm ls-fonts --text a🞄b
|
||||
```console
|
||||
$ 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})
|
||||
/home/wez/.fonts/OperatorMonoSSmLig-Medium.otf, FontDirs
|
||||
🞄 \u{1f784} x_adv=4 glyph=9129 wezterm.font("Symbola", {weight="Regular", stretch="SemiCondensed", italic=false})
|
||||
|
||||
@ -1,5 +1,3 @@
|
||||
## Key Tables
|
||||
|
||||
*Since: 20220408-101518-b908e2dd*
|
||||
|
||||
In addition to the default key table defined by the `keys` configuration
|
||||
|
||||
@ -1,5 +1,3 @@
|
||||
## Keyboard Concepts
|
||||
|
||||
`wezterm` allows assigning action(s) to specific key events, and comes
|
||||
pre-configured with a number of commonly useful assignments.
|
||||
|
||||
|
||||
@ -4,7 +4,7 @@ By default, when opening new tabs or windows, your shell will be spawned.
|
||||
|
||||
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
|
||||
2. Otherwise, it will resolve your current uid and try to look up your
|
||||
@ -25,7 +25,7 @@ value.
|
||||
*Since: 20220903-194523-3bb1ed61*: wezterm will now always resolve the shell via the
|
||||
password database.
|
||||
|
||||
### On Windows Systems
|
||||
=== "On Windows Systems"
|
||||
|
||||
1. The value of the `%COMSPEC%` environment variable is used if it is set.
|
||||
2. Otherwise, `cmd.exe`
|
||||
@ -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 edit your wezterm configuration:
|
||||
|
||||
```bash
|
||||
wezterm start -- vim ~/.wezterm.lua
|
||||
```console
|
||||
$ wezterm start -- vim ~/.wezterm.lua
|
||||
```
|
||||
|
||||
## 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:
|
||||
|
||||
```bash
|
||||
wezterm start --cwd /some/path
|
||||
```console
|
||||
$ wezterm start --cwd /some/path
|
||||
```
|
||||
|
||||
* The [`SpawnCommandInNewTab`](lua/keyassignment/SpawnCommandInNewTab.md),
|
||||
|
||||
@ -1,5 +1,3 @@
|
||||
## Copy Mode
|
||||
|
||||
*since: 20200607-144723-74889cd4*
|
||||
|
||||
Copy mode allows you to make selections using the keyboard; no need to reach
|
||||
|
||||
@ -1,3 +1,8 @@
|
||||
---
|
||||
hide:
|
||||
- toc
|
||||
---
|
||||
|
||||
## Available Features
|
||||
|
||||
* Runs on Linux, macOS, Windows 10 and FreeBSD
|
||||
@ -12,7 +17,7 @@
|
||||
* Multiple Windows (Hotkey: `Super-N`)
|
||||
* 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]`)
|
||||
<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)
|
||||
* [Connect to serial ports for embedded/Arduino work](serial.md)
|
||||
* Connect to a local multiplexer server over unix domain sockets
|
||||
|
||||
@ -1,5 +1,3 @@
|
||||
## Hyperlinks
|
||||
|
||||
wezterm has support for both implicit and explicit hyperlinks.
|
||||
|
||||
### Implicit Hyperlinks
|
||||
|
||||
@ -1,5 +1,3 @@
|
||||
## iTerm Image Protocol Support
|
||||
|
||||
wezterm implements support for the [iTerm2 inline images
|
||||
protocol](https://iterm2.com/documentation-images.html) and provides a handy
|
||||
`imgcat` subcommand to make it easy to try out. Because the protocol is
|
||||
|
||||
@ -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>
|
||||
|
||||
|
||||
[Download :material-tray-arrow-down:](installation.md){ .md-button }
|
||||
|
||||
## 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
|
||||
to activate the search function!**
|
||||
|
||||
<figure markdown>
|
||||
|
||||
|
||||
|
||||
*Screenshot of wezterm on macOS, running vim*
|
||||
|
||||
<figcaption>Screenshot of wezterm on macOS, running vim</figcaption>
|
||||
</figure>
|
||||
|
||||
@ -1,3 +1,8 @@
|
||||
---
|
||||
hide:
|
||||
- navigation
|
||||
---
|
||||
|
||||
WezTerm is available pre-built for the major platforms and, because it is open
|
||||
source, you may also build it for yourself.
|
||||
|
||||
|
||||
@ -10,7 +10,7 @@ site_dir: gh_pages
|
||||
theme:
|
||||
name: material
|
||||
logo: favicon.svg
|
||||
favicon: favicon.svg
|
||||
favicon: favicon.png
|
||||
custom_dir: docs/overrides
|
||||
palette:
|
||||
- media: "(prefers-color-scheme: light)"
|
||||
@ -80,6 +80,8 @@ markdown_extensions:
|
||||
- attr_list
|
||||
- md_in_html
|
||||
- def_list
|
||||
- toc:
|
||||
permalink: true
|
||||
- pymdownx.highlight:
|
||||
anchor_linenums: true
|
||||
line_spans: __span
|
||||
@ -103,3 +105,7 @@ extra:
|
||||
social:
|
||||
- icon: fontawesome/brands/github
|
||||
link: https://github.com/wez/wezterm
|
||||
- icon: fontawesome/brands/mastodon
|
||||
link: https://fosstodon.org/@wez
|
||||
- icon: fontawesome/brands/twitter
|
||||
link: https://twitter.com/wezfurlong
|
||||
|
||||
@ -1,5 +1,5 @@
|
||||
**Notice:** *multiplexing is still a young feature and is evolving rapidly.
|
||||
Your feedback is welcomed!*
|
||||
!!! note
|
||||
*multiplexing is still a young feature and is evolving rapidly. Your feedback is welcomed!*
|
||||
|
||||
## Multiplexing
|
||||
|
||||
@ -55,7 +55,7 @@ settings to use with SSH domains.
|
||||
|
||||
To connect to the system, run:
|
||||
|
||||
```bash
|
||||
```console
|
||||
$ wezterm connect my.server
|
||||
```
|
||||
|
||||
@ -96,7 +96,7 @@ return {
|
||||
If you prefer to connect manually, omit the `default_gui_startup_args` setting
|
||||
and then run:
|
||||
|
||||
```bash
|
||||
```console
|
||||
$ 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:
|
||||
|
||||
```bash
|
||||
```console
|
||||
$ 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
|
||||
remote terminal session
|
||||
|
||||
```bash
|
||||
```console
|
||||
$ wezterm connect server.name
|
||||
```
|
||||
|
||||
@ -1,5 +1,3 @@
|
||||
## Quick Select Mode
|
||||
|
||||
*Since: 20210502-154244-3f7122cb*
|
||||
|
||||
Quick Select mode allows you to quickly highlight text that matches
|
||||
|
||||
@ -1,5 +1,3 @@
|
||||
## Scrollback
|
||||
|
||||
WezTerm provides a searchable scrollback buffer with a configurable maximum
|
||||
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
|
||||
|
||||
@ -1,24 +1,22 @@
|
||||
## Serial Ports
|
||||
|
||||
wezterm can also connect to serial ports as a client. This is useful
|
||||
for example when working with embedded devices such as Arduino, or
|
||||
when connecting to a serial console on a headless server.
|
||||
|
||||
For example, on Linux:
|
||||
|
||||
```bash
|
||||
```console
|
||||
$ wezterm serial /dev/ttyUSB0
|
||||
```
|
||||
|
||||
or on Windows:
|
||||
|
||||
```bash
|
||||
```console
|
||||
$ wezterm serial COM0
|
||||
```
|
||||
|
||||
You can also specify the baud rate:
|
||||
|
||||
```bash
|
||||
```console
|
||||
$ wezterm serial --baud 38400 /dev/ttyUSB0
|
||||
```
|
||||
|
||||
|
||||
@ -1,5 +1,3 @@
|
||||
## Shell Integration
|
||||
|
||||
wezterm supports integrating with the shell through the following means:
|
||||
|
||||
* `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).
|
||||
|
||||
### User Vars
|
||||
## User Vars
|
||||
|
||||
`OSC 1337` provides a means for setting *user vars*, which are somewhat similar
|
||||
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
|
||||
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
|
||||
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
|
||||
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,
|
||||
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
|
||||
[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
|
||||
OSC 7 can be achieved this way instead:
|
||||
|
||||
@ -1,10 +1,8 @@
|
||||
## SSH Connections
|
||||
|
||||
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
|
||||
by invoking the client like this:
|
||||
|
||||
```bash
|
||||
```console
|
||||
$ wezterm ssh wez@my.server
|
||||
```
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user