From 107bcf6a8955fba86df2d219d130bd1c33334c19 Mon Sep 17 00:00:00 2001 From: Wez Furlong Date: Wed, 15 Mar 2023 20:54:02 -0700 Subject: [PATCH] docs: some adjustments for mkdocs --- ci/generate-docs.py | 6 ++--- docs/config/default-keys.md | 10 ++++++-- docs/config/files.md | 32 +++++++++++++---------- docs/config/fonts.md | 17 ++++++------ docs/config/key-tables.md | 2 -- docs/config/keyboard-concepts.md | 2 -- docs/config/launch.md | 44 ++++++++++++++++---------------- docs/copymode.md | 2 -- docs/features.md | 7 ++++- docs/hyperlinks.md | 2 -- docs/imgcat.md | 2 -- docs/index.md | 16 +++++++++--- docs/installation.md | 5 ++++ docs/mkdocs-base.yml | 8 +++++- docs/multiplexing.md | 12 ++++----- docs/quickselect.md | 2 -- docs/scrollback.md | 2 -- docs/serial.md | 8 +++--- docs/shell-integration.md | 12 ++++----- docs/ssh.md | 4 +-- 20 files changed, 105 insertions(+), 90 deletions(-) diff --git a/ci/generate-docs.py b/ci/generate-docs.py index b84eb1033..65034a7f8 100644 --- a/ci/generate-docs.py +++ b/ci/generate-docs.py @@ -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"), ], ), diff --git a/docs/config/default-keys.md b/docs/config/default-keys.md index c9abaeb10..8ceb5ab93 100644 --- a/docs/config/default-keys.md +++ b/docs/config/default-keys.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). + diff --git a/docs/config/files.md b/docs/config/files.md index fa2a828d7..15983c217 100644 --- a/docs/config/files.md +++ b/docs/config/files.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. -The recommendation is to place your configuration file at `$HOME/.wezterm.lua` -to get started. +!!! tip + 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 `$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 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 -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. +!!! 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. 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. -**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 -that have side effects; for example, unconditionally launching background -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. +!!! 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 + that have side effects; for example, unconditionally launching background + 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 @@ -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. diff --git a/docs/config/fonts.md b/docs/config/fonts.md index 94cc93820..d6a4ac1e6 100644 --- a/docs/config/fonts.md +++ b/docs/config/fonts.md @@ -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 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}) diff --git a/docs/config/key-tables.md b/docs/config/key-tables.md index df0f66556..9506ed474 100644 --- a/docs/config/key-tables.md +++ b/docs/config/key-tables.md @@ -1,5 +1,3 @@ -## Key Tables - *Since: 20220408-101518-b908e2dd* In addition to the default key table defined by the `keys` configuration diff --git a/docs/config/keyboard-concepts.md b/docs/config/keyboard-concepts.md index b507dc0da..fd197b80e 100644 --- a/docs/config/keyboard-concepts.md +++ b/docs/config/keyboard-concepts.md @@ -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. diff --git a/docs/config/launch.md b/docs/config/launch.md index 407c10de5..400d810cb 100644 --- a/docs/config/launch.md +++ b/docs/config/launch.md @@ -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: -### 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 - shell from the password database. + 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 + shell from the password database. -`wezterm` will spawn the shell and pass `-l` as an argument to request -a login shell. A login shell generally loads additional startup files -and sets up more environment than a non-login shell. + `wezterm` will spawn the shell and pass `-l` as an argument to request + a login shell. A login shell generally loads additional startup files + and sets up more environment than a non-login shell. -*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. + *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. -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 -sign back in again for the environment to pick up your new `$SHELL` -value. + 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 + sign back in again for the environment to pick up your new `$SHELL` + value. -*Since: 20220903-194523-3bb1ed61*: wezterm will now always resolve the shell via the -password database. + *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` + 1. The value of the `%COMSPEC%` environment variable is used if it is set. + 2. Otherwise, `cmd.exe` ## 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 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), diff --git a/docs/copymode.md b/docs/copymode.md index 734043921..6e3224d65 100644 --- a/docs/copymode.md +++ b/docs/copymode.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 diff --git a/docs/features.md b/docs/features.md index a6c4d7efb..c5bd6ecf5 100644 --- a/docs/features.md +++ b/docs/features.md @@ -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]`) - + * [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 diff --git a/docs/hyperlinks.md b/docs/hyperlinks.md index 8f2276086..d0b0dfdf5 100644 --- a/docs/hyperlinks.md +++ b/docs/hyperlinks.md @@ -1,5 +1,3 @@ -## Hyperlinks - wezterm has support for both implicit and explicit hyperlinks. ### Implicit Hyperlinks diff --git a/docs/imgcat.md b/docs/imgcat.md index 354896222..4a50593ec 100644 --- a/docs/imgcat.md +++ b/docs/imgcat.md @@ -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 diff --git a/docs/index.md b/docs/index.md index 7b4b79465..081a2ba24 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,7 +1,13 @@ +--- +hide: + - toc +--- -WezTerm Icon *WezTerm is a GPU-accelerated cross-platform terminal emulator and multiplexer written by @wez and implemented in Rust* +*WezTerm is a powerful cross-platform terminal emulator and multiplexer written by @wez and implemented in Rust* -Download +![Screenshot](screenshots/wezterm-vday-screenshot.png) + +[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!** +
+ ![Screenshot](screenshots/two.png) -*Screenshot of wezterm on macOS, running vim* - +
Screenshot of wezterm on macOS, running vim
+
diff --git a/docs/installation.md b/docs/installation.md index 1c05b14aa..db095f704 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -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. diff --git a/docs/mkdocs-base.yml b/docs/mkdocs-base.yml index 3d2a512ba..96f2f15e5 100644 --- a/docs/mkdocs-base.yml +++ b/docs/mkdocs-base.yml @@ -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 diff --git a/docs/multiplexing.md b/docs/multiplexing.md index 37bca2923..fc62640c2 100644 --- a/docs/multiplexing.md +++ b/docs/multiplexing.md @@ -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 ``` diff --git a/docs/quickselect.md b/docs/quickselect.md index c048f78e9..9e460fce1 100644 --- a/docs/quickselect.md +++ b/docs/quickselect.md @@ -1,5 +1,3 @@ -## Quick Select Mode - *Since: 20210502-154244-3f7122cb* Quick Select mode allows you to quickly highlight text that matches diff --git a/docs/scrollback.md b/docs/scrollback.md index a9d238a0a..4e664cee0 100644 --- a/docs/scrollback.md +++ b/docs/scrollback.md @@ -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 diff --git a/docs/serial.md b/docs/serial.md index c5f9a61c0..8b6db12bc 100644 --- a/docs/serial.md +++ b/docs/serial.md @@ -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 ``` diff --git a/docs/shell-integration.md b/docs/shell-integration.md index 333f6e87e..acdff54b9 100644 --- a/docs/shell-integration.md +++ b/docs/shell-integration.md @@ -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: diff --git a/docs/ssh.md b/docs/ssh.md index dbf26d780..32b6759e4 100644 --- a/docs/ssh.md +++ b/docs/ssh.md @@ -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 ```