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

docs: switch doc build to Material for MkDocs

Browse Source 
It's a more mature and actively developed toolset for
technical writing, and looks nicer.
This commit is contained in:
Wez Furlong 2023-03-15 19:22:51 -07:00
parent 2bfb29f1be
commit 4770b38737
No known key found for this signature in database
GPG Key ID: 7A7F66A31EC9B387
40 changed files with 594 additions and 332 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

44
.github/workflows/pages.yml vendored
View File

@ -10,7 +10,6 @@ on:
- "ci/generate-docs.py" - "ci/generate-docs.py"
- "ci/subst-release-info.py" - "ci/subst-release-info.py"
- ".github/workflows/pages.yml" - ".github/workflows/pages.yml"
- ".github/ISSUE_TEMPLATE/*"
schedule: schedule:
- cron: "50 * * * *" - cron: "50 * * * *"
@ -43,40 +42,33 @@ jobs:
components: "rustfmt" components: "rustfmt"
env: env:
ACTIONS_ALLOW_UNSECURE_COMMANDS: "true" ACTIONS_ALLOW_UNSECURE_COMMANDS: "true"
- uses: actions/cache@v3
name: Cache mdbook
with:
path: |
~/.cargo/bin/
~/.cargo/registry/index/
~/.cargo/registry/cache/
~/.cargo/git/db/
key: ${{ runner.os }}-cargo-mdbook-${{ hashFiles('.github/workflows/pages.yml') }}
- name: Install mdBook
run: |
(test -x ~/.cargo/bin/mdbook || (cd && cargo install mdbook --no-default-features --features search --vers "^0.4" --locked))
- name: Install mdBook linkcheck
run: |
(test -x ~/.cargo/bin/mdbook-linkcheck || (cd && cargo install mdbook-linkcheck --locked))
- name: Install mdBook mermaid
run: |
(test -x ~/.cargo/bin/mdbook-mermaid || (cd && cargo install mdbook-mermaid --locked))
- name: Install mdBook admonish
run: |
(test -x ~/.cargo/bin/mdbook-admonish || (cd && cargo install mdbook-admonish --locked))
- name: Install gelatyx - name: Install gelatyx
run: | uses: baptiste0928/cargo-install@v1
(test -x ~/.cargo/bin/gelatyx || (cd && cargo install gelatyx --version "^0.2" --locked)) with:
crate: gelatyx
args: --locked
- name: Install mdbook-linkcheck
uses: baptiste0928/cargo-install@v1
with:
crate: mdbook-linkcheck
args: --locked
- uses: actions/setup-python@v4
with:
python-version: 3.x
- uses: actions/cache@v2
with:
key: ${{ github.ref }}
path: .cache
- name: Build - name: Build
env: env:
GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
run: | run: |
source $HOME/.cargo/env source $HOME/.cargo/env
./ci/build-docs.sh CARDS=true ./ci/build-docs.sh
- name: Upload artifact - name: Upload artifact
uses: actions/upload-pages-artifact@v1 uses: actions/upload-pages-artifact@v1
with: with:
path: gh_pages/html path: gh_pages
deploy: deploy:
environment: environment:

6
.gitignore vendored
View File

@ -1,6 +1,10 @@
.DS_Store .DS_Store
dhat-heap.json dhat-heap.json
/docs/_site /docs/_site
/docs/favicon.png
/docs/favicon.svg
/docs/fonts/*
/mkdocs.yml
/PKGBUILD /PKGBUILD
/WezTerm*.zip /WezTerm*.zip
/WezTerm*.exe /WezTerm*.exe
@ -16,6 +20,8 @@ dhat-heap.json
/docs/cli/cli/index.md /docs/cli/cli/index.md
/docs/recipes/index.md /docs/recipes/index.md
/docs/colorschemes/**/index.md /docs/colorschemes/**/index.md
/docs/colorschemes/scheme.css
/docs/colorschemes/scheme.js
/docs/config/lua/color/index.md /docs/config/lua/color/index.md
/docs/config/lua/config/index.md /docs/config/lua/config/index.md
/docs/config/lua/gui-events/index.md /docs/config/lua/gui-events/index.md

26
ci/build-docs.sh
View File

@ -32,10 +32,24 @@ function ghapi() {
[[ -f /tmp/wezterm.nightly.json ]] || ghapi /repos/wez/wezterm/releases/tags/nightly > /tmp/wezterm.nightly.json [[ -f /tmp/wezterm.nightly.json ]] || ghapi /repos/wez/wezterm/releases/tags/nightly > /tmp/wezterm.nightly.json
python3 ci/subst-release-info.py || exit 1 python3 ci/subst-release-info.py || exit 1
python3 ci/generate-docs.py || exit 1 python3 ci/generate-docs.py || exit 1
mdbook-mermaid install docs
mdbook build docs
rm gh_pages/html/README.markdown mdbook-linkcheck --standalone docs
cp assets/fonts/Symbols-Nerd-Font-Mono.ttf gh_pages/html/fonts/
cp assets/icon/terminal.png gh_pages/html/favicon.png # Adjust path to pick up pip-installed binaries
cp "assets/icon/wezterm-icon.svg" gh_pages/html/favicon.svg PATH="$HOME/.local/bin;$PATH"
pip install --quiet mkdocs-material mkdocs-git-revision-date-localized-plugin black mkdocs-exclude mkdocs-include-markdown-plugin
if test -n "${CARDS}" ; then
pip install --quiet pillow cairosvg
fi
black ci/generate-docs.py ci/subst-release-info.py
cp "assets/icon/terminal.png" docs/favicon.png
cp "assets/icon/wezterm-icon.svg" docs/favicon.svg
mkdir docs/fonts
cp assets/fonts/Symbols-Nerd-Font-Mono.ttf docs/fonts/
mkdocs build
# mdbook-mermaid install docs
# mdbook build docs

363
ci/generate-docs.py
View File

@ -14,12 +14,24 @@ class Page(object):
self.filename = filename self.filename = filename
self.children = children or [] self.children = children or []
def render(self, output, depth=0): def render(self, output, depth=0, mode="mdbook"):
indent = " " * depth indent = " " * depth
bullet = "- " if depth > 0 else "" bullet = "- " if depth > 0 else ""
output.write(f"{indent}{bullet}[{self.title}]({self.filename})\n") if mode == "mdbook":
if self.filename:
output.write(f"{indent}{bullet}[{self.title}]({self.filename})\n")
elif mode == "mkdocs":
if depth > 0:
if len(self.children) == 0:
output.write(f'{indent}{bullet}"{self.title}": {self.filename}\n')
else:
output.write(f'{indent}{bullet}"{self.title}":\n')
if self.filename:
output.write(
f'{indent} {bullet}"{self.title}": {self.filename}\n'
)
for kid in self.children: for kid in self.children:
kid.render(output, depth + 1) kid.render(output, depth + 1, mode)
# autogenerate an index page from the contents of a directory # autogenerate an index page from the contents of a directory
@ -30,8 +42,7 @@ class Gen(object):
self.index = index self.index = index
self.extract_title = extract_title self.extract_title = extract_title
def render(self, output, depth=0): def render(self, output, depth=0, mode="mdbook"):
print(self.dirname)
names = sorted(glob.glob(f"{self.dirname}/*.md")) names = sorted(glob.glob(f"{self.dirname}/*.md"))
children = [] children = []
for filename in names: for filename in names:
@ -41,13 +52,13 @@ class Gen(object):
if self.extract_title: if self.extract_title:
with open(filename, "r") as f: with open(filename, "r") as f:
title = f.readline().strip('#').strip() title = f.readline().strip("#").strip()
children.append(Page(title, filename)) children.append(Page(title, filename))
index_filename = f"{self.dirname}/index.md" index_filename = f"{self.dirname}/index.md"
index_page = Page(self.title, index_filename, children=children) index_page = Page(self.title, index_filename, children=children)
index_page.render(output, depth) index_page.render(output, depth, mode)
with open(f"{self.dirname}/index.md", "w") as idx: with open(f"{self.dirname}/index.md", "w") as idx:
if self.index: if self.index:
idx.write(self.index) idx.write(self.index)
@ -187,7 +198,7 @@ class GenColorScheme(object):
self.dirname = dirname self.dirname = dirname
self.index = index self.index = index
def render(self, output, depth=0): def render(self, output, depth=0, mode="mdbook"):
with open("colorschemes/data.json") as f: with open("colorschemes/data.json") as f:
scheme_data = json.load(f) scheme_data = json.load(f)
by_prefix = {} by_prefix = {}
@ -209,6 +220,34 @@ class GenColorScheme(object):
else: else:
return None return None
style_filename = f"{self.dirname}/scheme.css"
with open(style_filename, "w") as style_file:
for scheme in by_name.values():
style_file.write(scheme["css"])
style_file.write("\n")
js_filename = f"{self.dirname}/scheme.js"
with open(js_filename, "w") as js_file:
data_by_scheme = {}
for scheme in by_name.values():
ident = scheme["ident"]
data = screen_shot_table(scheme)
data_by_scheme[ident] = data
js_file.write(f"SCHEME_DATA = {json.dumps(data_by_scheme)};\n")
js_file.write(
f"""
function load_scheme_player(ident) {{
var data = SCHEME_DATA[ident];
AsciinemaPlayer.create(
'data:text/plain;base64,' + data,
document.getElementById(ident + '-player'), {{
theme: ident,
autoPlay: true,
}});
}}
"""
)
children = [] children = []
for scheme_prefix in sorted(by_prefix.keys()): for scheme_prefix in sorted(by_prefix.keys()):
scheme_filename = f"{self.dirname}/{scheme_prefix}/index.md" scheme_filename = f"{self.dirname}/{scheme_prefix}/index.md"
@ -216,6 +255,7 @@ class GenColorScheme(object):
children.append(Page(scheme_prefix, scheme_filename)) children.append(Page(scheme_prefix, scheme_filename))
with open(scheme_filename, "w") as idx: with open(scheme_filename, "w") as idx:
idents_to_load = []
for scheme in by_prefix[scheme_prefix]: for scheme in by_prefix[scheme_prefix]:
title = scheme["name"] title = scheme["name"]
@ -223,26 +263,11 @@ class GenColorScheme(object):
data = screen_shot_table(scheme) data = screen_shot_table(scheme)
ident = scheme["ident"] ident = scheme["ident"]
idents_to_load.append(ident)
idx.write( idx.write(
f""" f"""
<div id="{ident}-player"></div> <div id="{ident}-player"></div>
<style>
{scheme["css"]}
</style>
<script>
window.addEventListener('load', function () {{
AsciinemaPlayer.create(
'data:text/plain;base64,{data}',
document.getElementById('{ident}-player'), {{
theme: "{ident}",
autoPlay: true,
}});
}});
</script>
""" """
) )
@ -267,13 +292,16 @@ window.addEventListener('load', function () {{
if alias_link: if alias_link:
alias_list.append(f"[{a}]({alias_link})") alias_list.append(f"[{a}]({alias_link})")
else: else:
alias_list.append(f"`{a}` (but that name isn't used here)") alias_list.append(
aliases = ', '.join(alias_list) f"`{a}` (but that name isn't used here)"
)
aliases = ", ".join(alias_list)
idx.write(f"This scheme is also known as {aliases}.<br/>\n") idx.write(f"This scheme is also known as {aliases}.<br/>\n")
else: else:
canon_link = scheme_link(canon_name) canon_link = scheme_link(canon_name)
idx.write(f"This scheme is the same as [{canon_name}]({canon_link}).<br/>\n") idx.write(
f"This scheme is the same as [{canon_name}]({canon_link}).<br/>\n"
)
idx.write("\nTo use this scheme, add this to your config:\n") idx.write("\nTo use this scheme, add this to your config:\n")
idx.write( idx.write(
@ -287,9 +315,20 @@ return {{
""" """
) )
idents_to_load = json.dumps(idents_to_load)
idx.write(
f"""
<script>
document.addEventListener("DOMContentLoaded", function() {{
{idents_to_load}.forEach(ident => load_scheme_player(ident));
}});
</script>
"""
)
index_filename = f"{self.dirname}/index.md" index_filename = f"{self.dirname}/index.md"
index_page = Page(self.title, index_filename, children=children) index_page = Page(self.title, index_filename, children=children)
index_page.render(output, depth) index_page.render(output, depth, mode)
with open(f"{self.dirname}/index.md", "w") as idx: with open(f"{self.dirname}/index.md", "w") as idx:
idx.write(f"{len(scheme_data)} Color schemes listed by first letter\n\n") idx.write(f"{len(scheme_data)} Color schemes listed by first letter\n\n")
@ -300,41 +339,10 @@ return {{
TOC = [ TOC = [
Page( Page(
"wezterm", "WezTerm",
"index.md", "index.md",
children=[ children=[
Page(
"Install",
"installation.md",
children=[
Page("Windows", "install/windows.md"),
Page("macOS", "install/macos.md"),
Page("Linux", "install/linux.md"),
Page("FreeBSD", "install/freebsd.md"),
Page("Build from source", "install/source.md"),
],
),
Page("Features", "features.md"), Page("Features", "features.md"),
Page("Change Log", "changelog.md"),
Page(
"Configuration",
"config/files.md",
children=[
Page("Launching Programs", "config/launch.md"),
Page("Fonts", "config/fonts.md"),
Page("Font Shaping", "config/font-shaping.md"),
Page("Keyboard Concepts", "config/keyboard-concepts.md"),
Page("Key Binding", "config/keys.md"),
Page("Key Tables", "config/key-tables.md"),
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"),
],
),
Page("Troubleshooting", "troubleshooting.md"),
Gen("Recipes", "recipes", extract_title=True),
Page("Scrollback", "scrollback.md"), Page("Scrollback", "scrollback.md"),
Page("Quick Select Mode", "quickselect.md"), Page("Quick Select Mode", "quickselect.md"),
Page("Copy Mode", "copymode.md"), Page("Copy Mode", "copymode.md"),
@ -344,100 +352,153 @@ TOC = [
Page("SSH", "ssh.md"), Page("SSH", "ssh.md"),
Page("Serial Ports & Arduino", "serial.md"), Page("Serial Ports & Arduino", "serial.md"),
Page("Multiplexing", "multiplexing.md"), Page("Multiplexing", "multiplexing.md"),
Page("Escape Sequences", "escape-sequences.md"), ],
Page("F.A.Q.", "faq.md"), ),
Page("Getting Help", "help.md"), Page(
Page("Contributing", "contributing.md"), "Install",
Page("What is a Terminal?", "what-is-a-terminal.md"), "installation.md",
Page( children=[
"CLI Reference", Page("Windows", "install/windows.md"),
"cli/general.md", Page("macOS", "install/macos.md"),
children=[ Page("Linux", "install/linux.md"),
Gen("cli", "cli/cli"), Page("FreeBSD", "install/freebsd.md"),
Page("show-keys", "cli/show-keys.md"), Page("Build from source", "install/source.md"),
], ],
),
Page(
"Configuration",
"config/files.md",
children=[
Page("Launching Programs", "config/launch.md"),
Page("Fonts", "config/fonts.md"),
Page("Font Shaping", "config/font-shaping.md"),
Page("Keyboard Concepts", "config/keyboard-concepts.md"),
Page("Key Binding", "config/keys.md"),
Page("Key Tables", "config/key-tables.md"),
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),
],
),
Page(
"Lua Reference",
"config/lua/general.md",
children=[
Gen(
"module: wezterm",
"config/lua/wezterm",
), ),
Page( Gen(
"Lua Reference", "module: wezterm.color",
"config/lua/general.md", "config/lua/wezterm.color",
children=[ ),
Gen( Gen(
"module: wezterm", "module: wezterm.gui",
"config/lua/wezterm", "config/lua/wezterm.gui",
), ),
Gen( Gen(
"module: wezterm.color", "module: wezterm.mux",
"config/lua/wezterm.color", "config/lua/wezterm.mux",
), ),
Gen( Gen(
"module: wezterm.gui", "module: wezterm.procinfo",
"config/lua/wezterm.gui", "config/lua/wezterm.procinfo",
), ),
Gen( Gen(
"module: wezterm.mux", "module: wezterm.time",
"config/lua/wezterm.mux", "config/lua/wezterm.time",
), ),
Gen( Gen(
"module: wezterm.procinfo", "struct: Config",
"config/lua/wezterm.procinfo", "config/lua/config",
), ),
Gen( Gen(
"module: wezterm.time", "enum: KeyAssignment",
"config/lua/wezterm.time", "config/lua/keyassignment",
), ),
Gen( Gen(
"struct: Config", "enum: CopyModeAssignment",
"config/lua/config", "config/lua/keyassignment/CopyMode",
), ),
Gen( Gen("object: Color", "config/lua/color"),
"enum: KeyAssignment", Page("object: ExecDomain", "config/lua/ExecDomain.md"),
"config/lua/keyassignment", Page("object: LocalProcessInfo", "config/lua/LocalProcessInfo.md"),
), Gen("object: MuxDomain", "config/lua/MuxDomain"),
Gen( Gen("object: MuxWindow", "config/lua/mux-window"),
"enum: CopyModeAssignment", Gen("object: MuxTab", "config/lua/MuxTab"),
"config/lua/keyassignment/CopyMode", Page("object: PaneInformation", "config/lua/PaneInformation.md"),
), Page("object: TabInformation", "config/lua/TabInformation.md"),
Gen("object: Color", "config/lua/color"), Page("object: SshDomain", "config/lua/SshDomain.md"),
Page("object: ExecDomain", "config/lua/ExecDomain.md"), Page("object: SpawnCommand", "config/lua/SpawnCommand.md"),
Page("object: LocalProcessInfo", "config/lua/LocalProcessInfo.md"), Gen("object: Time", "config/lua/wezterm.time/Time"),
Gen("object: MuxDomain", "config/lua/MuxDomain"), Page("object: TlsDomainClient", "config/lua/TlsDomainClient.md"),
Gen("object: MuxWindow", "config/lua/mux-window"), Page("object: TlsDomainServer", "config/lua/TlsDomainServer.md"),
Gen("object: MuxTab", "config/lua/MuxTab"), Gen(
Page("object: PaneInformation", "config/lua/PaneInformation.md"), "object: Pane",
Page("object: TabInformation", "config/lua/TabInformation.md"), "config/lua/pane",
Page("object: SshDomain", "config/lua/SshDomain.md"), ),
Page("object: SpawnCommand", "config/lua/SpawnCommand.md"), Gen(
Gen("object: Time", "config/lua/wezterm.time/Time"), "object: Window",
Page("object: TlsDomainClient", "config/lua/TlsDomainClient.md"), "config/lua/window",
Page("object: TlsDomainServer", "config/lua/TlsDomainServer.md"), ),
Gen( Page("object: WslDomain", "config/lua/WslDomain.md"),
"object: Pane", Gen(
"config/lua/pane", "events: Gui",
), "config/lua/gui-events",
Gen( ),
"object: Window", Gen(
"config/lua/window", "events: Multiplexer",
), "config/lua/mux-events",
Page("object: WslDomain", "config/lua/WslDomain.md"), ),
Gen( Gen(
"events: Gui", "events: Window",
"config/lua/gui-events", "config/lua/window-events",
),
Gen(
"events: Multiplexer",
"config/lua/mux-events",
),
Gen(
"events: Window",
"config/lua/window-events",
),
],
), ),
], ],
) ),
Page(
"CLI Reference",
"cli/general.md",
children=[
Gen("wezterm cli", "cli/cli"),
Page("wezterm show-keys", "cli/show-keys.md"),
],
),
Page(
"Reference",
None,
children=[
Page("Escape Sequences", "escape-sequences.md"),
Page("What is a Terminal?", "what-is-a-terminal.md"),
],
),
Page(
"Get Help",
None,
children=[
Page("Getting Help", "help.md"),
Page("Troubleshooting", "troubleshooting.md"),
Page("F.A.Q.", "faq.md"),
Page("Contributing", "contributing.md"),
],
),
Page("Change Log", "changelog.md"),
] ]
os.chdir("docs") os.chdir("docs")
with open("SUMMARY.md", "w") as f:
with open("../mkdocs.yml", "w") as f:
f.write("# this is auto-generated by docs/generate-toc.py, do not edit\n")
f.write("INHERIT: docs/mkdocs-base.yml\n")
f.write("nav:\n")
for page in TOC: for page in TOC:
page.render(f) page.render(f, depth=1, mode="mkdocs")
with open("SUMMARY.md", "w") as f:
f.write("[root](index.md)\n")
for page in TOC:
page.render(f, depth=1, mode="mdbook")

26
docs/changelog.md
View File

@ -1,3 +1,9 @@
---
hide:
- navigation
toc_depth: 3
---
## Changes ## Changes
Releases are named using the date, time and git commit hash. Releases are named using the date, time and git commit hash.
@ -680,7 +686,7 @@ As features stabilize some brief notes about them will accumulate here.
* Fancy Tab Bars are now the default. The default tab bar colors have changed to accommodate the new more native look. You can turn them off by setting [use_fancy_tab_bar = false](config/lua/config/use_fancy_tab_bar.md). * Fancy Tab Bars are now the default. The default tab bar colors have changed to accommodate the new more native look. You can turn them off by setting [use_fancy_tab_bar = false](config/lua/config/use_fancy_tab_bar.md).
* Support for the [Kitty Image Protocol](https://sw.kovidgoyal.net/kitty/graphics-protocol/) is now enabled by default. Most of the protocol is supported; animation support is not yet implemented. Try the amazing [notcurses](https://notcurses.com/) if you want to see what modern terminal graphics can do! [#986](https://github.com/wez/wezterm/issues/986) * Support for the [Kitty Image Protocol](https://sw.kovidgoyal.net/kitty/graphics-protocol/) is now enabled by default. Most of the protocol is supported; animation support is not yet implemented. Try the amazing [notcurses](https://notcurses.com/) if you want to see what modern terminal graphics can do! [#986](https://github.com/wez/wezterm/issues/986)
* unix domains now support an optional `proxy_command` to use in place of a direct unix socket connection. [Read more about multiplexing unix domains](multiplexing.html#unix-domains) * unix domains now support an optional `proxy_command` to use in place of a direct unix socket connection. [Read more about multiplexing unix domains](multiplexing.md#unix-domains)
* [ScrollToTop](config/lua/keyassignment/ScrollToTop.md) and [ScrollToBottom](config/lua/keyassignment/ScrollToBottom.md) key assignments [#1360](https://github.com/wez/wezterm/issues/1360) * [ScrollToTop](config/lua/keyassignment/ScrollToTop.md) and [ScrollToBottom](config/lua/keyassignment/ScrollToBottom.md) key assignments [#1360](https://github.com/wez/wezterm/issues/1360)
* [SSH Domains](config/lua/SshDomain.md) now support specifying `ssh_config` overrides. [#1149](https://github.com/wez/wezterm/issues/1149) * [SSH Domains](config/lua/SshDomain.md) now support specifying `ssh_config` overrides. [#1149](https://github.com/wez/wezterm/issues/1149)
* [default_gui_startup_args](config/lua/config/default_gui_startup_args.md) allows defaulting to starting the ssh client (for example). [#1030](https://github.com/wez/wezterm/issues/1030) * [default_gui_startup_args](config/lua/config/default_gui_startup_args.md) allows defaulting to starting the ssh client (for example). [#1030](https://github.com/wez/wezterm/issues/1030)
@ -841,7 +847,7 @@ As features stabilize some brief notes about them will accumulate here.
* Fixed: incorrect Sixel HLS hue handling [#775](https://github.com/wez/wezterm/issues/775) * Fixed: incorrect Sixel HLS hue handling [#775](https://github.com/wez/wezterm/issues/775)
* Fixed: we now recognize the `CSI 48:2:0:214:255m` form of specifying true color text attributes [#785](https://github.com/wez/wezterm/issues/785) * Fixed: we now recognize the `CSI 48:2:0:214:255m` form of specifying true color text attributes [#785](https://github.com/wez/wezterm/issues/785)
* Fixed: split separators didn't respect `tab_bar_at_bottom=true` and were rendered in the wrong place [#797](https://github.com/wez/wezterm/issues/797) * Fixed: split separators didn't respect `tab_bar_at_bottom=true` and were rendered in the wrong place [#797](https://github.com/wez/wezterm/issues/797)
* Improved: messaging around [exit_behavior](https://wezfurlong.org/wezterm/config/lua/config/exit_behavior.html) * Improved: messaging around [exit_behavior](https://wezfurlong.org/wezterm/config/lua/config/exit_behavior.md)
* Fixed: errors loading custom color schemes are now logged to the error log [#794](https://github.com/wez/wezterm/issues/794) * Fixed: errors loading custom color schemes are now logged to the error log [#794](https://github.com/wez/wezterm/issues/794)
* Fixed: OSC 7 (current working directory) now works with paths that contain spaces and other special characters. Thanks to [@Arvedui](https://github.com/Arvedui)! [#799](https://github.com/wez/wezterm/pull/799) * Fixed: OSC 7 (current working directory) now works with paths that contain spaces and other special characters. Thanks to [@Arvedui](https://github.com/Arvedui)! [#799](https://github.com/wez/wezterm/pull/799)
* Changed: the homebrew tap is now a Cask that installs to the /Applications directory on macOS. Thanks to [@laggardkernel](https://github.com/laggardkernel)! * Changed: the homebrew tap is now a Cask that installs to the /Applications directory on macOS. Thanks to [@laggardkernel](https://github.com/laggardkernel)!
@ -994,7 +1000,7 @@ As features stabilize some brief notes about them will accumulate here.
### 20210314-114017-04b7cedd ### 20210314-114017-04b7cedd
* New: [tab_bar_style](config/lua/config/tab_bar_style.md) allows customizing the appearance of the rest of tha tab bar. * New: [tab_bar_style](config/lua/config/tab_bar_style.md) allows customizing the appearance of the rest of tha tab bar.
* New: animated gif and png images displayed via `wezterm imgcat` (the iTerm2 image protocol), or attached to the window background via [window_background_image](config/appearance.html#window-background-image) will now animate while the window has focus. * New: animated gif and png images displayed via `wezterm imgcat` (the iTerm2 image protocol), or attached to the window background via [window_background_image](config/appearance.md#window-background-image) will now animate while the window has focus.
* New: added [foreground_text_hsb](config/lua/config/foreground_text_hsb.md) setting to adjust hue, saturation and brightness when text is rendered. * New: added [foreground_text_hsb](config/lua/config/foreground_text_hsb.md) setting to adjust hue, saturation and brightness when text is rendered.
* New: added [ResetFontAndWindowSize](config/lua/keyassignment/ResetFontAndWindowSize.md) key assignment. * New: added [ResetFontAndWindowSize](config/lua/keyassignment/ResetFontAndWindowSize.md) key assignment.
* New: added [ScrollByLine](config/lua/keyassignment/ScrollByLine.md) key assignment. * New: added [ScrollByLine](config/lua/keyassignment/ScrollByLine.md) key assignment.
@ -1065,7 +1071,7 @@ As features stabilize some brief notes about them will accumulate here.
* Fixed an issue where a symbol-only font would be seen as 0-width and panic wezterm [#404](https://github.com/wez/wezterm/issues/404) * Fixed an issue where a symbol-only font would be seen as 0-width and panic wezterm [#404](https://github.com/wez/wezterm/issues/404)
* Tweaked mouse selection: we now round the x-coordinate to the nearest cell which makes it a bit more forgiving if the mouse cursor is slightly to the left of the intended cell start. [#350](https://github.com/wez/wezterm/issues/350) * Tweaked mouse selection: we now round the x-coordinate to the nearest cell which makes it a bit more forgiving if the mouse cursor is slightly to the left of the intended cell start. [#350](https://github.com/wez/wezterm/issues/350)
* Added `selection_word_boundary` option to control double-click word selection boundaries. The default is <tt> \t\n{}\[\]()\"'\`</tt>. [#405](https://github.com/wez/wezterm/issues/405) * Added `selection_word_boundary` option to control double-click word selection boundaries. The default is <tt> \t\n{}\[\]()\"'\`</tt>. [#405](https://github.com/wez/wezterm/issues/405)
* Added support for Curly, Dotted and Dashed underlines. See [this documentation](faq.html#how-do-i-enable-undercurl-curly-underlines) on the escape sequences how enable undercurl support in vim and nvim. [#415](https://github.com/wez/wezterm/issues/415) * Added support for Curly, Dotted and Dashed underlines. See [this documentation](faq.md#how-do-i-enable-undercurl-curly-underlines) on the escape sequences how enable undercurl support in vim and nvim. [#415](https://github.com/wez/wezterm/issues/415)
* Fixed an issue where wezterm would spawn processes with `umask 077` on unix systems, rather than the more commonly expected `umask 022`. [#416](https://github.com/wez/wezterm/issues/416) * Fixed an issue where wezterm would spawn processes with `umask 077` on unix systems, rather than the more commonly expected `umask 022`. [#416](https://github.com/wez/wezterm/issues/416)
* macOS: We now ship a Universal binary containing both Intel and "Apple Silicon" architectures * macOS: We now ship a Universal binary containing both Intel and "Apple Silicon" architectures
* Setting a really large or really small font scale (using CTRL +/-) no longer causes a panic [#428](https://github.com/wez/wezterm/issues/428) * Setting a really large or really small font scale (using CTRL +/-) no longer causes a panic [#428](https://github.com/wez/wezterm/issues/428)
@ -1075,8 +1081,8 @@ As features stabilize some brief notes about them will accumulate here.
* New: `adjust_window_size_when_changing_font_size` option to control whether changing the font size adjusts the dimensions of the window (true) or adjusts the number of terminal rows/columns (false). The default is `true`. [#431](https://github.com/wez/wezterm/issues/431) * New: `adjust_window_size_when_changing_font_size` option to control whether changing the font size adjusts the dimensions of the window (true) or adjusts the number of terminal rows/columns (false). The default is `true`. [#431](https://github.com/wez/wezterm/issues/431)
* macOS: we no longer use MetalANGLE to render the gui; it was short lived as macOS Big Sur now uses Metal in its CGL implementation. Support for using MetalANGLE is still present if the dylib is found on startup, but we no longer ship the dylib. * macOS: we no longer use MetalANGLE to render the gui; it was short lived as macOS Big Sur now uses Metal in its CGL implementation. Support for using MetalANGLE is still present if the dylib is found on startup, but we no longer ship the dylib.
* Windows: when pasting text, ensure that the text has CRLF line endings unless bracketed paste is enabled. This imperfect heuristic helps to keep multi-line pastes on multiple lines when using Windows console applications and to avoid interleaved blank lines when using unix applications. [#411](https://github.com/wez/wezterm/issues/411) * Windows: when pasting text, ensure that the text has CRLF line endings unless bracketed paste is enabled. This imperfect heuristic helps to keep multi-line pastes on multiple lines when using Windows console applications and to avoid interleaved blank lines when using unix applications. [#411](https://github.com/wez/wezterm/issues/411)
* New: [ClearScrollback](config/lua/keyassignment/ClearScrollback.html) now accepts a parameter to control whether the viewport is cleared along with the scrollback. Thanks to [@dfrankland](https://github.com/dfrankland)! * New: [ClearScrollback](config/lua/keyassignment/ClearScrollback.md) now accepts a parameter to control whether the viewport is cleared along with the scrollback. Thanks to [@dfrankland](https://github.com/dfrankland)!
* New: [default_cwd](config/lua/config/default_cwd.html) to specify an alternative current working directory. Thanks to [@dfrankland](https://github.com/dfrankland)! * New: [default_cwd](config/lua/config/default_cwd.md) to specify an alternative current working directory. Thanks to [@dfrankland](https://github.com/dfrankland)!
* New: [CopyTo](config/lua/keyassignment/CopyTo.md) and [PasteFrom](config/lua/keyassignment/PasteFrom.md) actions. [Copy](config/lua/keyassignment/Copy.md), [Paste](config/lua/keyassignment/Paste.md) and [PastePrimarySelection](config/lua/keyassignment/PastePrimarySelection.md) are now deprecated in favor of these new options. * New: [CopyTo](config/lua/keyassignment/CopyTo.md) and [PasteFrom](config/lua/keyassignment/PasteFrom.md) actions. [Copy](config/lua/keyassignment/Copy.md), [Paste](config/lua/keyassignment/Paste.md) and [PastePrimarySelection](config/lua/keyassignment/PastePrimarySelection.md) are now deprecated in favor of these new options.
* X11: Mouse-based selection now copies-to and pastes-from the `PrimarySelection` by default. The [CompleteSelection](config/lua/keyassignment/CompleteSelection.md) and [CompleteSelectionOrOpenLinkAtMouseCursor](config/lua/keyassignment/CompleteSelectionOrOpenLinkAtMouseCursor.md) actions now require a parameter to specify the clipboard. * X11: Mouse-based selection now copies-to and pastes-from the `PrimarySelection` by default. The [CompleteSelection](config/lua/keyassignment/CompleteSelection.md) and [CompleteSelectionOrOpenLinkAtMouseCursor](config/lua/keyassignment/CompleteSelectionOrOpenLinkAtMouseCursor.md) actions now require a parameter to specify the clipboard.
* X11: `SHIFT-CTRL-C` and `SHIFT-CTRL-V` now copy-to and paste from the `Clipboard` by default. `SHIFT-Insert` pastes from the `PrimarySelection` by default. * X11: `SHIFT-CTRL-C` and `SHIFT-CTRL-V` now copy-to and paste from the `Clipboard` by default. `SHIFT-Insert` pastes from the `PrimarySelection` by default.
@ -1285,7 +1291,7 @@ As features stabilize some brief notes about them will accumulate here.
enables "Open WezTerm Here" in the explorer.exe context menu. enables "Open WezTerm Here" in the explorer.exe context menu.
* Added `ClearScrollback` key assignment to clear the scrollback. This is bound to CMD-K and CTRL-SHIFT-K by default. * Added `ClearScrollback` key assignment to clear the scrollback. This is bound to CMD-K and CTRL-SHIFT-K by default.
* Added `Search` key assignment to search the scrollback. Read the new * Added `Search` key assignment to search the scrollback. Read the new
[scrollback](scrollback.html) section for more information! [scrollback](scrollback.md) section for more information!
* Fixed an issue where ALT+number would send the wrong output for European * Fixed an issue where ALT+number would send the wrong output for European
keyboard layouts on macOS and Linux. As part of this the default behavior keyboard layouts on macOS and Linux. As part of this the default behavior
has changed: we used to force ALT+number to produce ALT+number instead of has changed: we used to force ALT+number to produce ALT+number instead of
@ -1297,9 +1303,9 @@ As features stabilize some brief notes about them will accumulate here.
you have installed so that you can quickly spawn a shell in any of them. you have installed so that you can quickly spawn a shell in any of them.
You can suppress this behavior if you wish by setting You can suppress this behavior if you wish by setting
`add_wsl_distributions_to_launch_menu = false`. `add_wsl_distributions_to_launch_menu = false`.
[Read more about the launcher menu](config/launch.html#the-launcher-menu) [Read more about the launcher menu](config/launch.md#the-launcher-menu)
* Added `ActivateCopyMode` key assignment to put the tab into mouseless-copy * Added `ActivateCopyMode` key assignment to put the tab into mouseless-copy
mode; [use the keyboard to define the selected text region](copymode.html). mode; [use the keyboard to define the selected text region](copymode.md).
This is bound to CTRL-SHIFT-X by default. This is bound to CTRL-SHIFT-X by default.
### 20200517-122836-92c201c6 ### 20200517-122836-92c201c6
@ -1325,7 +1331,7 @@ As features stabilize some brief notes about them will accumulate here.
### 20200503-171512-b13ef15f ### 20200503-171512-b13ef15f
* Added the `launch_menu` configuration for the launcher menu * Added the `launch_menu` configuration for the launcher menu
as described in [Launching Programs](config/launch.html). as described in [Launching Programs](config/launch.md).
* Fixed a crash when reloading a config with `enable_tab_bar=false` * Fixed a crash when reloading a config with `enable_tab_bar=false`
* Fixed missing icon when running under X11 and Wayland * Fixed missing icon when running under X11 and Wayland
* Wayland client-side-decorations improved and now also render window title * Wayland client-side-decorations improved and now also render window title

6
docs/config/appearance.md
View File

@ -259,7 +259,7 @@ $ for scheme in *.sh ; do ; echo $scheme ; \
bash "$scheme" ; ../tools/screenshotTable.sh; sleep 0.5; done 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 ### Tab Bar Appearance & Colors
@ -450,7 +450,7 @@ reduce it by half, and 2.0 will double the value.
## Window Background Image ## Window Background Image
<img width="100%" height="100%" src="../screenshots/wezterm-vday-screenshot.png" alt="Screenshot"> ![Screenshot](../screenshots/wezterm-vday-screenshot.png)
*since: 20201031-154415-9614e117* *since: 20201031-154415-9614e117*
@ -505,7 +505,7 @@ behavior and more, take a look at the more power
*Since: 20210814-124438-54e29167* *Since: 20210814-124438-54e29167*
<img src="../screenshots/radial-gradient.png"> ![Gradient](../screenshots/radial-gradient.png)
See [window_background_gradient](lua/config/window_background_gradient.md) See [window_background_gradient](lua/config/window_background_gradient.md)
for configuration information on gradients. for configuration information on gradients.

2
docs/config/launch.md
View File

@ -168,7 +168,7 @@ return {
} }
``` ```
<img src="../screenshots/launch-menu.png" alt="Screenshot"> ![Launch Menu](../screenshots/launch-menu.png)
Here's a fancy example that will add some helpful entries to the launcher Here's a fancy example that will add some helpful entries to the launcher
menu when running on Windows: menu when running on Windows:

2
docs/config/lua/config/color_schemes.md
View File

@ -2,4 +2,4 @@
Specifies various named color schemes in your configuration file. Specifies various named color schemes in your configuration file.
Described in more detail in [Colors & Appearance](../../appearance.html#defining-a-color-scheme-in-your-weztermlua) Described in more detail in [Colors & Appearance](../../appearance.md#defining-a-color-scheme-in-your-weztermlua)

2
docs/config/lua/config/default_prog.md
View File

@ -16,4 +16,4 @@ return {
is the command to run and the rest of the elements are passed is the command to run and the rest of the elements are passed
as the positional arguments to that command. as the positional arguments to that command.
See also: [Launching Programs](../../launch.html) See also: [Launching Programs](../../launch.md)

12
docs/config/lua/config/foreground_text_hsb.md
View File

@ -33,11 +33,7 @@ return {
} }
``` ```
<img src="../../../screenshots/foreground-text-hsb-1-1-1.png" ![demonstrating the appearance of the default value](../../../screenshots/foreground-text-hsb-1-1-1.png)
alt="demonstrating the appearance of the default value"> ![demonstrating setting saturating to 1.5](../../../screenshots/foreground-text-hsb-1-1.5-1.png)
<img src="../../../screenshots/foreground-text-hsb-1-1.5-1.png" ![demonstrating setting brightness to 1.5](../../../screenshots/foreground-text-hsb-1-1-1.5.png)
alt="demonstrating setting saturating to 1.5"> ![demonstrating setting hue to 1.5](../../../screenshots/foreground-text-hsb-1.5-1-1.png)
<img src="../../../screenshots/foreground-text-hsb-1-1-1.5.png"
alt="demonstrating setting brightness to 1.5">
<img src="../../../screenshots/foreground-text-hsb-1.5-1-1.png"
alt="demonstrating setting hue to 1.5">

2
docs/config/lua/config/harfbuzz_features.md
View File

@ -3,6 +3,6 @@
When `font_shaper = "Harfbuzz"`, this setting affects how font shaping When `font_shaper = "Harfbuzz"`, this setting affects how font shaping
takes place. takes place.
See [Font Shaping](../../font-shaping.html) for more information See [Font Shaping](../../font-shaping.md) for more information
and examples. and examples.

2
docs/config/lua/config/set_environment_variables.md
View File

@ -7,4 +7,4 @@ running program on any Operating System.
This is not used when working with remote domains. This is not used when working with remote domains.
See also: [Launching Programs](../../launch.html#passing-environment-variables-to-the-spawned-program) See also: [Launching Programs](../../launch.md#passing-environment-variables-to-the-spawned-program)

5
docs/config/lua/config/tab_bar_style.md
View File

@ -15,7 +15,7 @@ have been removed and replaced by the more flexible
*Since: 20210314-114017-04b7cedd* *Since: 20210314-114017-04b7cedd*
This config option allows styling the elements that appear in the tab bar. This config option allows styling the elements that appear in the tab bar.
This configuration supplements the [tab bar color](../../appearance.html#tab-bar-appearance--colors) This configuration supplements the [tab bar color](../../appearance.md#tab-bar-appearance--colors)
options. options.
Styling in this context refers to how the edges of the tabs and the new tab button are rendered. Styling in this context refers to how the edges of the tabs and the new tab button are rendered.
@ -35,8 +35,7 @@ The available elements are:
This example changes the tab edges to the PowerLine arrow symbols: This example changes the tab edges to the PowerLine arrow symbols:
<img width="100%" height="100%" src="../../../screenshots/wezterm-tab-edge-styled.png" ![Demonstrating setting the styling of the left and right tab edges](../../../screenshots/wezterm-tab-edge-styled.png)
alt="Demonstrating setting the styling of the left and right tab edges">
```lua ```lua
local wezterm = require 'wezterm' local wezterm = require 'wezterm'

2
docs/config/lua/config/unix_domains.md
View File

@ -3,4 +3,4 @@
Defines a list of multiplexer domains for both the multiplexer Defines a list of multiplexer domains for both the multiplexer
server and multiplexer client. server and multiplexer client.
[Read more about multiplexing](../../../multiplexing.html#unix-domains) [Read more about multiplexing](../../../multiplexing.md#unix-domains)

6
docs/config/lua/config/window_background_gradient.md
View File

@ -63,7 +63,7 @@ return {
} }
``` ```
<img src="../../../screenshots/vertical-gradient.png"> ![Vertical Gradient](../../../screenshots/vertical-gradient.png)
Gradients are implemented using the `colorgrad` crate. Gradients are implemented using the `colorgrad` crate.
Take a look at <https://github.com/mazznoer/colorgrad-rs#using-web-color-format> Take a look at <https://github.com/mazznoer/colorgrad-rs#using-web-color-format>
@ -95,7 +95,7 @@ return {
} }
``` ```
<img src="../../../screenshots/linear-gradient.png"> ![Linear Gradient](../../../screenshots/linear-gradient.png)
## Radial gradient: ## Radial gradient:
@ -131,7 +131,7 @@ return {
} }
``` ```
<img src="../../../screenshots/radial-gradient.png"> ![Radial Gradient](../../../screenshots/radial-gradient.png)
## Presets ## Presets

2
docs/config/lua/keyassignment/ActivateCommandPalette.md
View File

@ -22,7 +22,7 @@ The command palette shows a list of possible actions ranked by
[frecency](https://en.wikipedia.org/wiki/Frecency) of use from the command [frecency](https://en.wikipedia.org/wiki/Frecency) of use from the command
palette. palette.
<img src="../../../screenshots/command-palette.png"> ![Command Palette](../../../screenshots/command-palette.png)
### Key Assignments ### Key Assignments

2
docs/config/lua/keyassignment/ActivateCopyMode.md
View File

@ -12,5 +12,5 @@ return {
} }
``` ```
[Learn more about copy mode](../../../copymode.html) [Learn more about copy mode](../../../copymode.md)

2
docs/config/lua/keyassignment/PaneSelect.md
View File

@ -6,7 +6,7 @@ This action activates the pane selection modal display. In this mode, each pane
will be overlayed with a one- or two-character label taken from the selection will be overlayed with a one- or two-character label taken from the selection
alphabet. alphabet.
<img width="100%" height="100%" src="../../../screenshots/pane-select.png"> ![Pane Select](../../../screenshots/pane-select.png)
Typing the label will select the pane, take an action and exit selection mode. Typing the label will select the pane, take an action and exit selection mode.
Pressing `Escape` or `CTRL-g` will exit pane selection mode without taking any Pressing `Escape` or `CTRL-g` will exit pane selection mode without taking any

2
docs/config/lua/keyassignment/Search.md
View File

@ -41,7 +41,7 @@ return {
} }
``` ```
[Learn more about the search overlay](../../../scrollback.html#searching-the-scrollback) [Learn more about the search overlay](../../../scrollback.md#searching-the-scrollback)
*since: 20220624-141144-bd1b7c5d* *since: 20220624-141144-bd1b7c5d*

2
docs/config/lua/wezterm/strftime_utc.md
View File

@ -12,4 +12,4 @@ local date_and_time = wezterm.strftime_utc '%Y-%m-%d %H:%M:%S'
wezterm.log_info(date_and_time) wezterm.log_info(date_and_time)
``` ```
See also [strftime](strftime.md) and [wezterm.time](../wezterm.time/index.markdown). See also [strftime](strftime.md) and [wezterm.time](../wezterm.time/index.md).

8
docs/config/lua/window/set_right_status.md
View File

@ -14,8 +14,7 @@ the string.
Here's a basic example that displays the time in the status area: Here's a basic example that displays the time in the status area:
<img width="100%" height="100%" src="../../../screenshots/wezterm-status-date.png" ![Demonstrating setting the right status area to the current date and time](../../../screenshots/wezterm-status-date.png)
alt="Demonstrating setting the right status area to the current date and time">
```lua ```lua
local wezterm = require 'wezterm' local wezterm = require 'wezterm'
@ -38,10 +37,9 @@ Here's a rather more elaborate example that employs the popular PowerLine glyphs
to show a visually appealing status area. It also extracts the current to show a visually appealing status area. It also extracts the current
working directory and hostname from the current pane. That way working directory and hostname from the current pane. That way
it can potentially pick up the remote hostname if your remote shell session is using it can potentially pick up the remote hostname if your remote shell session is using
[OSC 7 shell integration](../../../shell-integration.html#osc-7-escape-sequence-to-set-the-working-directory). [OSC 7 shell integration](../../../shell-integration.md#osc-7-escape-sequence-to-set-the-working-directory).
<img width="100%" height="100%" src="../../../screenshots/wezterm-status-powerline.png" ![Demonstrating setting the right status area with powerline styling](../../../screenshots/wezterm-status-powerline.png)
alt="Demonstrating setting the right status area with powerline styling">
```lua ```lua
wezterm.on('update-right-status', function(window, pane) wezterm.on('update-right-status', function(window, pane)

4
docs/contributing.md
View File

@ -7,8 +7,8 @@ If you're thinking of helping out, then the following resources may be helpful:
* [WezTerm on GitHub](https://github.com/wez/wezterm) * [WezTerm on GitHub](https://github.com/wez/wezterm)
* [GitHub Discussions](https://github.com/wez/wezterm/discussions) * [GitHub Discussions](https://github.com/wez/wezterm/discussions)
* [Realtime conversation with wez on Element.io/Gitter](help.html) * [Realtime conversation with wez on Element.io/Gitter](help.md)
* [Building from Source](install/source.html) * [Building from Source](install/source.md)
* [Where to find things and hacking on wezterm](https://github.com/wez/wezterm/blob/master/CONTRIBUTING.md#contributing-to-wezterm) * [Where to find things and hacking on wezterm](https://github.com/wez/wezterm/blob/master/CONTRIBUTING.md#contributing-to-wezterm)
I like to think that I have an open mind and I try to be open to ideas, I like to think that I have an open mind and I try to be open to ideas,

2
docs/copymode.md
View File

@ -96,4 +96,4 @@ may be more recent than your version of wezterm) is shown below.
You can see the configuration in your version of wezterm by running You can see the configuration in your version of wezterm by running
`wezterm show-keys --lua --key-table copy_mode`. `wezterm show-keys --lua --key-table copy_mode`.
{{#include examples/default-copy-mode-key-table.markdown}} {% include "examples/default-copy-mode-key-table.markdown" %}

10
docs/escape-sequences.md
View File

@ -41,7 +41,7 @@ applied to the terminal display using the following rules:
* The cursor position will be updated based on the column width of the grapheme. * The cursor position will be updated based on the column width of the grapheme.
After the graphemes are applied to the terminal display, the rendering portion of After the graphemes are applied to the terminal display, the rendering portion of
WezTerm will attempt to apply your [font shaping](config/font-shaping.html) configuration WezTerm will attempt to apply your [font shaping](config/font-shaping.md) configuration
based on runs of graphemes with matching graphic attributes to determine which glyphs based on runs of graphemes with matching graphic attributes to determine which glyphs
should be rendered from your fonts; it is at this stage that emoji and ligatures are should be rendered from your fonts; it is at this stage that emoji and ligatures are
resolved. resolved.
@ -390,17 +390,17 @@ The table below is keyed by the OSC code.
|4 |Change/Query Color Number | Set or query color palette entries 0-255. | query color number 1: `\x1b]4;1;?\x1b\\` <br/> Set color number 2: `\x1b]4;2;#cccccc\x1b\\` | |4 |Change/Query Color Number | Set or query color palette entries 0-255. | query color number 1: `\x1b]4;1;?\x1b\\` <br/> Set color number 2: `\x1b]4;2;#cccccc\x1b\\` |
|5 |Change/Query Special Color Number | Ignored | | |5 |Change/Query Special Color Number | Ignored | |
|6 |iTerm2 Change Title Tab Color | Ignored | | |6 |iTerm2 Change Title Tab Color | Ignored | |
|7 |Set Current Working Directory | [See Shell Integration](shell-integration.html#osc-7-escape-sequence-to-set-the-working-directory) || |7 |Set Current Working Directory | [See Shell Integration](shell-integration.md#osc-7-escape-sequence-to-set-the-working-directory) ||
|8 |Set Hyperlink | [See Explicit Hyperlinks](hyperlinks.html#explicit-hyperlinks) | | |8 |Set Hyperlink | [See Explicit Hyperlinks](hyperlinks.md#explicit-hyperlinks) | |
|9 |iTerm2 Show System Notification | Show a "toast" notification | `printf "\e]9;%s\e\\" "hello there"` | |9 |iTerm2 Show System Notification | Show a "toast" notification | `printf "\e]9;%s\e\\" "hello there"` |
|10 |Set Default Text Foreground Color| | `\x1b]10;#ff0000\x1b\\`.<br/> Also supports RGBA in nightly builds: `printf "\e]10;rgba(127,127,127,0.4)\x07"` | |10 |Set Default Text Foreground Color| | `\x1b]10;#ff0000\x1b\\`.<br/> Also supports RGBA in nightly builds: `printf "\e]10;rgba(127,127,127,0.4)\x07"` |
|11 |Set Default Text Background Color| | `\x1b]11;#0000ff\x1b\\`.<br/> Also supports RGBA in nightly builds: `printf "\e]11;rgba:efff/ecff/f4ff/d000\x07"` | |11 |Set Default Text Background Color| | `\x1b]11;#0000ff\x1b\\`.<br/> Also supports RGBA in nightly builds: `printf "\e]11;rgba:efff/ecff/f4ff/d000\x07"` |
|12 |Set Text Cursor Color| | `\x1b]12;#00ff00\x1b\\`.<br/> Also supports RGBA in nightly builds. | |12 |Set Text Cursor Color| | `\x1b]12;#00ff00\x1b\\`.<br/> Also supports RGBA in nightly builds. |
|52 |Manipulate clipboard | Requests to query the clipboard are ignored. Allows setting or clearing the clipboard | | |52 |Manipulate clipboard | Requests to query the clipboard are ignored. Allows setting or clearing the clipboard | |
|104|ResetColors | Reset color palette entries to their default values | | |104|ResetColors | Reset color palette entries to their default values | |
|133|FinalTerm semantic escapes| Informs the terminal about Input, Output and Prompt regions on the display | [See Shell Integration](shell-integration.html) | |133|FinalTerm semantic escapes| Informs the terminal about Input, Output and Prompt regions on the display | [See Shell Integration](shell-integration.md) |
|777|Call rxvt extension| Only the notify extension is supported; it shows a "toast" notification | `printf "\e]777;notify;%s;%s\e\\" "title" "body"` | |777|Call rxvt extension| Only the notify extension is supported; it shows a "toast" notification | `printf "\e]777;notify;%s;%s\e\\" "title" "body"` |
|1337 |iTerm2 File Upload Protocol | Allows displaying images inline | [See iTerm Image Protocol](imgcat.html) | |1337 |iTerm2 File Upload Protocol | Allows displaying images inline | [See iTerm Image Protocol](imgcat.md) |
|L |Set Icon Name (Sun) | Same as OSC 1 | `\x1b]Ltab-title\x1b\\` | |L |Set Icon Name (Sun) | Same as OSC 1 | `\x1b]Ltab-title\x1b\\` |
|l |Set Window Title (Sun) | Same as OSC 2 | `\x1b]lwindow-title\x1b\\` | |l |Set Window Title (Sun) | Same as OSC 2 | `\x1b]lwindow-title\x1b\\` |

8
docs/faq.md
View File

@ -123,13 +123,13 @@ issue.
### Multiple characters being rendered/combined as one character? ### Multiple characters being rendered/combined as one character?
`wezterm` supports [advanced font shaping](config/font-shaping.html), which, `wezterm` supports [advanced font shaping](config/font-shaping.md), which,
amongst other things, allows for multiple characters/glyphs to be combined into amongst other things, allows for multiple characters/glyphs to be combined into
one [ligature](https://en.wikipedia.org/wiki/Ligature_(writing)). You may be one [ligature](https://en.wikipedia.org/wiki/Ligature_(writing)). You may be
experiencing this if, e.g., `!=` becomes rendered as `≠` in `wezterm`. experiencing this if, e.g., `!=` becomes rendered as `≠` in `wezterm`.
If you are seeing this kind of "font combining" and wish to disable it, then If you are seeing this kind of "font combining" and wish to disable it, then
this is documented in [advanced font shaping options](config/font-shaping.html) this is documented in [advanced font shaping options](config/font-shaping.md)
page. page.
## How to troubleshoot keys that don't work or produce weird characters!? ## How to troubleshoot keys that don't work or produce weird characters!?
@ -142,7 +142,7 @@ reflect this; there is more information on that above.
If the key in question is produced in combination with Alt/Option then [this If the key in question is produced in combination with Alt/Option then [this
section of the docs describes how wezterm processes section of the docs describes how wezterm processes
Alt/Option](config/keys.html), as well as options that influence that behavior. Alt/Option](config/keys.md), as well as options that influence that behavior.
The next thing to verify is what byte sequences are being produced when you The next thing to verify is what byte sequences are being produced when you
press keys. I generally suggest running `xxd`, pressing the relevant key, then press keys. I generally suggest running `xxd`, pressing the relevant key, then
@ -249,7 +249,7 @@ env TERM=wezterm nvim
Note: on Windows, the ConPTY layer strips out the curly underline escape Note: on Windows, the ConPTY layer strips out the curly underline escape
sequences. If you're missing this feature in your WSL instance, you will need sequences. If you're missing this feature in your WSL instance, you will need
to use either `wezterm ssh` or to use either `wezterm ssh` or
[multiplexing](multiplexing.html#connecting-into-windows-subsystem-for-linux) [multiplexing](multiplexing.md#connecting-into-windows-subsystem-for-linux)
to bypass ConPTY. to bypass ConPTY.
## I use Powershell for my shell, and I have problems with cursor keys in other apps ## I use Powershell for my shell, and I have problems with cursor keys in other apps

16
docs/features.md
View File

@ -1,22 +1,22 @@
## Available Features ## Available Features
* Runs on Linux, macOS, Windows 10 and FreeBSD * Runs on Linux, macOS, Windows 10 and FreeBSD
* [Multiplex terminal panes, tabs and windows on local and remote hosts, with native mouse and scrollback](multiplexing.html) * [Multiplex terminal panes, tabs and windows on local and remote hosts, with native mouse and scrollback](multiplexing.md)
* <a href="https://github.com/tonsky/FiraCode#fira-code-monospaced-font-with-programming-ligatures">Ligatures</a>, Color Emoji and font fallback, with true color and [dynamic color schemes](config/appearance.html#colors). * <a href="https://github.com/tonsky/FiraCode#fira-code-monospaced-font-with-programming-ligatures">Ligatures</a>, Color Emoji and font fallback, with true color and [dynamic color schemes](config/appearance.md#colors).
* [Hyperlinks](hyperlinks.html) * [Hyperlinks](hyperlinks.md)
* [Searchable Scrollback](scrollback.html) (use mouse wheel and `Shift-PageUp` and `Shift PageDown` to navigate, Ctrl-Shift-F to activate search mode) * [Searchable Scrollback](scrollback.md) (use mouse wheel and `Shift-PageUp` and `Shift PageDown` to navigate, Ctrl-Shift-F to activate search mode)
* xterm style selection of text with mouse; paste selection via `Shift-Insert` (bracketed paste is supported!) * xterm style selection of text with mouse; paste selection via `Shift-Insert` (bracketed paste is supported!)
* SGR style mouse reporting (works in vim and tmux) * SGR style mouse reporting (works in vim and tmux)
* Render underline, double-underline, italic, bold, strikethrough (most other terminal emulators do not support as many render attributes) * Render underline, double-underline, italic, bold, strikethrough (most other terminal emulators do not support as many render attributes)
* Configuration via a <a href="config/files.html">configuration file</a> with hot reloading * Configuration via a <a href="config/files.md">configuration file</a> with hot reloading
* 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.html) * [SSH client with native tabs](ssh.md)
* [Connect to serial ports for embedded/Arduino work](serial.html) * [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
* Connect to a remote multiplexer using SSH or TLS over TCP/IP * Connect to a remote multiplexer using SSH or TLS over TCP/IP
* iTerm2 compatible image protocol support, and built-in [imgcat command](imgcat.html) * iTerm2 compatible image protocol support, and built-in [imgcat command](imgcat.md)
* Kitty graphics support * Kitty graphics support
* Sixel graphics support (experimental: starting in `20200620-160318-e00b076c`) * Sixel graphics support (experimental: starting in `20200620-160318-e00b076c`)

4
docs/imgcat.md
View File

@ -7,11 +7,11 @@ just a protocol, wezterm's `imgcat` also renders images in iTerm2.
To render an image inline in your terminal: To render an image inline in your terminal:
``` ```console
$ wezterm imgcat /path/to/image.png $ wezterm imgcat /path/to/image.png
``` ```
<img width="100%" height="100%" src="screenshots/wezterm-imgcat.png" alt="inline image display"> ![inline image display](screenshots/wezterm-imgcat.png)
**Note that the image protocol isn't fully handled by multiplexer sessions **Note that the image protocol isn't fully handled by multiplexer sessions

8
docs/index.md
View File

@ -1,22 +1,22 @@
<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>* <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>*
<a class="btn" href="installation.html">Download</a> <a class="btn" href="installation.md">Download</a>
## Features ## Features
* Runs on Linux, macOS, Windows 10 and FreeBSD * Runs on Linux, macOS, Windows 10 and FreeBSD
* [Multiplex terminal panes, tabs and windows on local and remote hosts, with native mouse and scrollback](multiplexing.md) * [Multiplex terminal panes, tabs and windows on local and remote hosts, with native mouse and scrollback](multiplexing.md)
* <a href="https://github.com/tonsky/FiraCode#fira-code-monospaced-font-with-programming-ligatures">Ligatures</a>, Color Emoji and font fallback, with true color and [dynamic color schemes](config/appearance.html#colors). * <a href="https://github.com/tonsky/FiraCode#fira-code-monospaced-font-with-programming-ligatures">Ligatures</a>, Color Emoji and font fallback, with true color and [dynamic color schemes](config/appearance.md#colors).
* [Hyperlinks](hyperlinks.md) * [Hyperlinks](hyperlinks.md)
* <a href="features.html">a full list of features can be found here</a> * <a href="features.md">a full list of features can be found here</a>
Looking for a [configuration reference?](config/files.md) 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!**
<img width="100%" height="100%" src="screenshots/two.png" alt="Screenshot"> ![Screenshot](screenshots/two.png)
*Screenshot of wezterm on macOS, running vim* *Screenshot of wezterm on macOS, running vim*

68
docs/install/linux.markdown
View File

@ -11,20 +11,20 @@ To install using the command line:
First, [setup flatpak on your system](https://flatpak.org/setup/), then: First, [setup flatpak on your system](https://flatpak.org/setup/), then:
```bash ```console
flatpak install flathub org.wezfurlong.wezterm $ flatpak install flathub org.wezfurlong.wezterm
``` ```
and then run: and then run:
```bash ```console
flatpak run org.wezfurlong.wezterm $ flatpak run org.wezfurlong.wezterm
``` ```
You may wish to define an alias for convenience: You may wish to define an alias for convenience:
```bash ```console
alias wezterm='flatpak run org.wezfurlong.wezterm' $ alias wezterm='flatpak run org.wezfurlong.wezterm'
``` ```
Note: flatpaks run in a sandbox so some functionality may behave a little Note: flatpaks run in a sandbox so some functionality may behave a little
@ -46,30 +46,30 @@ range of Linux distributions.
Download and make the file executable and you're ready to run! Download and make the file executable and you're ready to run!
<a href="{{ ubuntu18_AppImage_stable }}" class="btn">AppImage</a> [AppImage :material-tray-arrow-down:]({{ ubuntu18_AppImage_stable }}){ .md-button }
<a href="{{ ubuntu18_AppImage_nightly }}" class="btn">Nightly AppImage</a> [Nightly AppImage :material-tray-arrow-down:]({{ ubuntu18_AppImage_nightly }}){ .md-button }
```bash ```console
curl -LO {{ ubuntu18_AppImage_stable }} $ curl -LO {{ ubuntu18_AppImage_stable }}
chmod +x {{ ubuntu18_AppImage_stable_asset }} $ chmod +x {{ ubuntu18_AppImage_stable_asset }}
``` ```
You may then execute the appimage directly to launch wezterm, with no You may then execute the appimage directly to launch wezterm, with no
specific installation steps required: specific installation steps required:
```bash ```console
./{{ ubuntu18_AppImage_stable_asset }} $ ./{{ ubuntu18_AppImage_stable_asset }}
``` ```
That said, you may wish to make it a bit more convenient: That said, you may wish to make it a bit more convenient:
```bash ```console
mkdir ~/bin $ mkdir ~/bin
mv ./{{ ubuntu18_AppImage_stable_asset }} ~/bin/wezterm $ mv ./{{ ubuntu18_AppImage_stable_asset }} ~/bin/wezterm
~/bin/wezterm $ ~/bin/wezterm
``` ```
* Configuration instructions can be [found here](../config/files.html) * Configuration instructions can be [found here](../config/files.md)
## Installing on Ubuntu and Debian-based Systems ## Installing on Ubuntu and Debian-based Systems
@ -90,13 +90,13 @@ you can try the AppImage download which should work on most Linux systems.
To download and install from the CLI, you can use something like this, which To download and install from the CLI, you can use something like this, which
shows how to install the Ubuntu 20 package: shows how to install the Ubuntu 20 package:
```bash ```console
curl -LO {{ ubuntu20_deb_stable }} $ curl -LO {{ ubuntu20_deb_stable }}
sudo apt install -y ./{{ ubuntu20_deb_stable_asset }} $ sudo apt install -y ./{{ ubuntu20_deb_stable_asset }}
``` ```
* The package installs `/usr/bin/wezterm` and `/usr/share/applications/org.wezfurlong.wezterm.desktop` * The package installs `/usr/bin/wezterm` and `/usr/share/applications/org.wezfurlong.wezterm.desktop`
* Configuration instructions can be [found here](../config/files.html) * Configuration instructions can be [found here](../config/files.md)
## Installing on Fedora and rpm-based Systems ## Installing on Fedora and rpm-based Systems
@ -121,22 +121,22 @@ on most Linux systems.
To download and install from the CLI you can use something like this, which To download and install from the CLI you can use something like this, which
shows how to install the Fedora 35 package: shows how to install the Fedora 35 package:
```bash ```console
sudo dnf install -y {{ fedora35_rpm_stable }} $ sudo dnf install -y {{ fedora35_rpm_stable }}
``` ```
WezTerm is also available in the official Factory repo in openSUSE Tumbleweed. To install from Factory instead WezTerm is also available in the official Factory repo in openSUSE Tumbleweed. To install from Factory instead
from the rpm provided by WezTerm's Github repository, you can use Yast. If you prefer the CLI, you can install from the rpm provided by WezTerm's Github repository, you can use Yast. If you prefer the CLI, you can install
it as root user with it as root user with
```bash ```console
zypper addrepo https://download.opensuse.org/repositories/openSUSE:Factory/standard/openSUSE:Factory.repo $ zypper addrepo https://download.opensuse.org/repositories/openSUSE:Factory/standard/openSUSE:Factory.repo
zypper refresh $ zypper refresh
zypper install wezterm $ zypper install wezterm
``` ```
* The package installs `/usr/bin/wezterm` and `/usr/share/applications/org.wezfurlong.wezterm.desktop` * The package installs `/usr/bin/wezterm` and `/usr/share/applications/org.wezfurlong.wezterm.desktop`
* Configuration instructions can be [found here](../config/files.html) * Configuration instructions can be [found here](../config/files.md)
## Arch Linux ## Arch Linux
@ -165,21 +165,21 @@ APKs are built out from the `main` branch.
If you are a [Linuxbrew](https://docs.brew.sh/Homebrew-on-Linux) user, you can install If you are a [Linuxbrew](https://docs.brew.sh/Homebrew-on-Linux) user, you can install
wezterm from our tap: wezterm from our tap:
```bash ```console
$ brew tap wez/wezterm-linuxbrew $ brew tap wez/wezterm-linuxbrew
$ brew install wezterm $ brew install wezterm
``` ```
If you'd like to use a nightly build you can perform a head install: If you'd like to use a nightly build you can perform a head install:
```bash ```console
$ brew install --HEAD wezterm $ brew install --HEAD wezterm
``` ```
to upgrade to a newer nightly, it is simplest to remove then to upgrade to a newer nightly, it is simplest to remove then
install: install:
```bash ```console
$ brew rm wezterm $ brew rm wezterm
$ brew install --HEAD wezterm $ brew install --HEAD wezterm
``` ```
@ -189,7 +189,7 @@ $ brew install --HEAD wezterm
Another option for linux is a raw binary archive. These are the same binaries that Another option for linux is a raw binary archive. These are the same binaries that
are built for Ubuntu but provided in a tarball. are built for Ubuntu but provided in a tarball.
<a href="{{ linux_raw_bin_stable }}" class="btn">Download raw Linux binaries</a> [Raw Linux Binary :material-tray-arrow-down:]({{ linux_raw_bin_stable }}){ .md-button }
<a href="{{ linux_raw_bin_nightly }}" class="btn">Nightly raw Linux binaries</a> [Nightly Raw Linux Binary :material-tray-arrow-down:]({{ linux_raw_bin_nightly }}){ .md-button }

15
docs/install/macos.markdown
View File

@ -7,8 +7,9 @@ been tested.
Starting with version 20210203-095643-70a364eb, WezTerm is a Universal binary Starting with version 20210203-095643-70a364eb, WezTerm is a Universal binary
with support for both Apple Silicon and Intel hardware. with support for both Apple Silicon and Intel hardware.
<a href="{{ macos_zip_stable }}" class="btn">Download for macOS</a> [:simple-apple: Download for macOS :material-tray-arrow-down:]({{ macos_zip_stable }}){ .md-button }
<a href="{{ macos_zip_nightly }}" class="btn">Nightly for macOS</a> [:simple-apple: Nightly for macOS :material-tray-arrow-down:]({{ macos_zip_nightly }}){ .md-button }
1. Download <a href="{{ macos_zip_stable }}">Release</a> 1. Download <a href="{{ macos_zip_stable }}">Release</a>
2. Extract the zipfile and drag the `WezTerm.app` bundle to your `Applications` folder 2. Extract the zipfile and drag the `WezTerm.app` bundle to your `Applications` folder
3. First time around, you may need to right click and select `Open` to allow launching 3. First time around, you may need to right click and select `Open` to allow launching
@ -19,26 +20,26 @@ with support for both Apple Silicon and Intel hardware.
PATH="$PATH:/Applications/WezTerm.app/Contents/MacOS" PATH="$PATH:/Applications/WezTerm.app/Contents/MacOS"
export PATH export PATH
``` ```
5. Configuration instructions can be [found here](../config/files.html) 5. Configuration instructions can be [found here](../config/files.md)
## Homebrew ## Homebrew
WezTerm is available for [brew](https://brew.sh/) users in a tap: WezTerm is available for [brew](https://brew.sh/) users in a tap:
```bash ```console
$ brew tap wez/wezterm $ brew tap wez/wezterm
$ brew install --cask wez/wezterm/wezterm $ brew install --cask wez/wezterm/wezterm
``` ```
If you'd like to use a nightly build: If you'd like to use a nightly build:
```bash ```console
$ brew install --cask wez/wezterm/wezterm-nightly $ brew install --cask wez/wezterm/wezterm-nightly
``` ```
to upgrade to a newer nightly (normal `brew upgrade` will not upgrade it!): to upgrade to a newer nightly (normal `brew upgrade` will not upgrade it!):
```bash ```console
$ brew upgrade --cask wez/wezterm/wezterm-nightly --no-quarantine --greedy-latest $ brew upgrade --cask wez/wezterm/wezterm-nightly --no-quarantine --greedy-latest
``` ```
@ -46,7 +47,7 @@ $ brew upgrade --cask wez/wezterm/wezterm-nightly --no-quarantine --greedy-lates
WezTerm is also available via [MacPorts](https://ports.macports.org/port/wezterm/summary): WezTerm is also available via [MacPorts](https://ports.macports.org/port/wezterm/summary):
```bash ```console
$ sudo port selfupdate $ sudo port selfupdate
$ sudo port install wezterm $ sudo port install wezterm
``` ```

36
docs/install/source.markdown
View File

@ -17,26 +17,26 @@ attempt to install them for you. If it doesn't know about your system,
If you don't plan to submit a pull request to the wezterm repo, you can If you don't plan to submit a pull request to the wezterm repo, you can
download a smaller source tarball using these steps: download a smaller source tarball using these steps:
```bash ```console
curl https://sh.rustup.rs -sSf | sh -s $ curl https://sh.rustup.rs -sSf | sh -s
curl -LO {{ src_stable }} $ curl -LO {{ src_stable }}
tar -xzf {{ src_stable_asset }} $ tar -xzf {{ src_stable_asset }}
cd {{ src_stable_dir }} $ cd {{ src_stable_dir }}
./get-deps $ ./get-deps
cargo build --release $ cargo build --release
cargo run --release --bin wezterm -- start $ cargo run --release --bin wezterm -- start
``` ```
Alternatively, use the full git repo: Alternatively, use the full git repo:
```bash ```console
curl https://sh.rustup.rs -sSf | sh -s $ curl https://sh.rustup.rs -sSf | sh -s
git clone --depth=1 --branch=main --recursive https://github.com/wez/wezterm.git $ git clone --depth=1 --branch=main --recursive https://github.com/wez/wezterm.git
cd wezterm $ cd wezterm
git submodule update --init --recursive $ git submodule update --init --recursive
./get-deps $ ./get-deps
cargo build --release $ cargo build --release
cargo run --release --bin wezterm -- start $ cargo run --release --bin wezterm -- start
``` ```
**If you get an error about zlib then you most likely didn't initialize the submodules; **If you get an error about zlib then you most likely didn't initialize the submodules;
@ -48,8 +48,8 @@ By default, support for both X11 and Wayland is included on Unix systems.
If your distribution has X11 but not Wayland, then you can build WezTerm without If your distribution has X11 but not Wayland, then you can build WezTerm without
Wayland support by changing the `build` invocation: Wayland support by changing the `build` invocation:
```bash ```console
cargo build --release --no-default-features vendored-fonts $ cargo build --release --no-default-features vendored-fonts
``` ```
Building without X11 is not supported. Building without X11 is not supported.

28
docs/install/windows.markdown
View File

@ -9,8 +9,8 @@ You can download a setup.exe style installer to guide the installation
(requires admin privileges) or a simple zip file and manage the files for (requires admin privileges) or a simple zip file and manage the files for
yourself (no special privileges required). yourself (no special privileges required).
<a href="{{ windows_exe_stable }}" class="btn">Windows (setup.exe)</a> [:simple-windows: Windows (setup.exe) :material-tray-arrow-down:]({{ windows_exe_stable }}){ .md-button }
<a href="{{ windows_exe_nightly }}" class="btn">Nightly Windows (setup.exe)</a> [:simple-windows: Nightly Windows (setup.exe) :material-tray-arrow-down:]({{ windows_exe_nightly }}){ .md-button }
WezTerm is available in a setup.exe style installer; the installer is produced WezTerm is available in a setup.exe style installer; the installer is produced
with Inno Setup and will install wezterm to your program files directory and with Inno Setup and will install wezterm to your program files directory and
@ -19,8 +19,8 @@ as a GUI to guide you through the install, but also offers the [standard
Inno Setup command line options](https://jrsoftware.org/ishelp/index.php?topic=setupcmdline) Inno Setup command line options](https://jrsoftware.org/ishelp/index.php?topic=setupcmdline)
to configure/script the installation process. to configure/script the installation process.
<a href="{{ windows_zip_stable }}" class="btn">Windows (zip)</a> [:simple-windows: Windows (zip) :material-tray-arrow-down:]({{ windows_zip_stable }}){ .md-button }
<a href="{{ windows_zip_nightly }}" class="btn">Nightly Windows (zip)</a> [:simple-windows: Nightly Windows (zip) :material-tray-arrow-down:]({{ windows_zip_nightly }}){ .md-button }
WezTerm is also available in a simple zip file that can be extracted and WezTerm is also available in a simple zip file that can be extracted and
run from anywhere, including a flash drive for a portable/relocatable run from anywhere, including a flash drive for a portable/relocatable
@ -28,7 +28,7 @@ installation.
1. Download <a href="{{ windows_zip_stable }}">Release</a> 1. Download <a href="{{ windows_zip_stable }}">Release</a>
2. Extract the zipfile and double-click `wezterm.exe` to run the UI 2. Extract the zipfile and double-click `wezterm.exe` to run the UI
3. Configuration instructions can be [found here](../config/files.html) 3. Configuration instructions can be [found here](../config/files.md)
### For `winget` users ### For `winget` users
@ -39,14 +39,14 @@ that is available from the Microsoft Store.
Once you have `winget`, you can install wezterm like so: Once you have `winget`, you can install wezterm like so:
```bash ```console
winget install wez.wezterm $ winget install wez.wezterm
``` ```
and to later upgrade it: and to later upgrade it:
```bash ```console
winget upgrade wez.wezterm $ winget upgrade wez.wezterm
``` ```
### For `Scoop` users ### For `Scoop` users
@ -57,9 +57,9 @@ software, is [Scoop](https://scoop.sh/).
Wezterm is available from the "Extras" bucket and once you have installed Wezterm is available from the "Extras" bucket and once you have installed
scoop itself can be installed like so: scoop itself can be installed like so:
```bash ```console
scoop bucket add extras $ scoop bucket add extras
scoop install wezterm $ scoop install wezterm
``` ```
### For `Chocolatey` users ### For `Chocolatey` users
@ -68,6 +68,6 @@ If you prefer to use [Chocolatey](https://chocolatey.org) to manage software,
wezterm is availabe from the Community Repository. It can be installed like wezterm is availabe from the Community Repository. It can be installed like
so: so:
```bash ```console
choco install wezterm -y $ choco install wezterm -y
``` ```

42
docs/javascript/fix-codeblock-console-copy-button.js Normal file
View File

@ -0,0 +1,42 @@
document.addEventListener("DOMContentLoaded", function() {
fixCopyOnlyUserSelectable();
});
function fixCopyOnlyUserSelectable() {
buttonsToFix = document.querySelectorAll(
'.language-console button.md-clipboard');
if (buttonsToFix.length)
console.log('Fixing copy-to-clipboard text of console code-blocks.');
buttonsToFix.forEach((btn) => {
var content = extractUserSelectable(btn.dataset.clipboardTarget);
btn.dataset.clipboardText = content;
});
}
function extractUserSelectable(selector) {
var result = '';
var element = document.querySelector(selector);
// Attempt to remove the non-selectable sections based on style,
// but we haven't seen this work reliably...
element.childNodes.forEach((child) => {
if (child instanceof Element) {
var s=window.getComputedStyle(child);
if (s.getPropertyValue('user-select') == 'none' ||
s.getPropertyValue('-webkit-user-select') == 'none' ||
s.getPropertyValue('-ms-user-select') == 'none')
{
return;
}
}
result += child.textContent;
});
// ... so we fall back to simple but effective:
// remove "$ " and "# " prompt at start of lines in code
result = result.replace(/^[\s]?[\$#]\s+/gm, "")
// remove empty lines
result = result.replace(/^\s*\n/gm, '')
return result;
}

105
docs/mkdocs-base.yml Normal file
View File

@ -0,0 +1,105 @@
copyright: Copyright &copy; 2018-Present Wez Furlong
site_name: Wez's Terminal Emulator
site_url: https://wezfurlong.org/wezterm/
site_description: Wez's Terminal Emulator
repo_url: https://github.com/wez/wezterm
repo_name: wez/wezterm
edit_uri: edit/main/docs/
docs_dir: docs
site_dir: gh_pages
theme:
name: material
logo: favicon.svg
favicon: favicon.svg
custom_dir: docs/overrides
palette:
- media: "(prefers-color-scheme: light)"
scheme: default
primary: deep purple
accent: deep purple
toggle:
icon: material/weather-sunny
name: Switch to dark mode
# Palette toggle for dark mode
- media: "(prefers-color-scheme: dark)"
scheme: slate
primary: deep purple
accent: purple
toggle:
icon: material/weather-night
name: Switch to light mode
features:
- content.action.edit
- content.action.view
- content.code.copy
- content.tabs.link
- navigation.footer
- navigation.indexes
- navigation.instant
#- navigation.expand
- navigation.tabs
- navigation.tabs.sticky
- navigation.tracking
- navigation.top
- search.highlight
- search.share
- search.suggest
- toc.follow
plugins:
- include-markdown
- search
- social:
cards: !ENV [CARDS, false]
#- git-revision-date-localized:
# enable_creation_date: true
# type: timeago
- exclude:
glob:
- "**/_index.md"
- "**/*.markdown"
- "generate_toc.py"
- "README.markdown"
- "build.sh"
- "SUMMARY.md"
- "book.toml"
- "overrides/**"
extra_css:
- style.css
- colorschemes/scheme.css
- asciinema-player.css
extra_javascript:
- asciinema-player.min.js
- javascript/fix-codeblock-console-copy-button.js
- colorschemes/scheme.js
markdown_extensions:
- admonition
- pymdownx.details
- attr_list
- md_in_html
- def_list
- pymdownx.highlight:
anchor_linenums: true
line_spans: __span
pygments_lang_class: true
- pymdownx.inlinehilite
- pymdownx.snippets
- pymdownx.emoji:
emoji_index: !!python/name:materialx.emoji.twemoji
emoji_generator: !!python/name:materialx.emoji.to_svg
- pymdownx.tasklist:
custom_checkbox: true
- pymdownx.tabbed:
alternate_style: true
- pymdownx.superfences:
custom_fences:
- name: mermaid
class: mermaid
format: !!python/name:pymdownx.superfences.fence_code_format
extra:
social:
- icon: fontawesome/brands/github
link: https://github.com/wez/wezterm

2
docs/multiplexing.md
View File

@ -22,7 +22,7 @@ the domain of the current tab, or a specific numbered domain.
## SSH Domains ## SSH Domains
*wezterm also supports [regular ad-hoc ssh connections](ssh.html). *wezterm also supports [regular ad-hoc ssh connections](ssh.md).
This section of the docs refers to running a wezterm daemon on the remote end This section of the docs refers to running a wezterm daemon on the remote end
of a multiplexing session that uses ssh as a channel* of a multiplexing session that uses ssh as a channel*

19
docs/overrides/partials/toc-item.html Normal file
View File

@ -0,0 +1,19 @@
{% if not page.meta.toc_depth or toc_item.level <= page.meta.toc_depth %}
<!-- Table of contents item -->
<li class="md-nav__item">
<a href="{{ toc_item.url }}" class="md-nav__link">
{{ toc_item.title }}
</a>
<!-- Table of contents list -->
{% if toc_item.children %}
<nav class="md-nav" aria-label="{{ toc_item.title }}">
<ul class="md-nav__list">
{% for toc_item in toc_item.children %}
{% include "partials/toc-item.html" %}
{% endfor %}
</ul>
</nav>
{% endif %}
</li>
{% endif %}

2
docs/quickselect.md
View File

@ -29,4 +29,4 @@ text, and cancel quick select mod.
Pressing `ESCAPE` will cancel quick select mode. Pressing `ESCAPE` will cancel quick select mode.
<img width="100%" height="100%" src="screenshots/wezterm-quick-select.png" alt="Screenshot demonstrating the quickselect text highlights"> ![Screenshot demonstrating the quickselect text highlights](screenshots/wezterm-quick-select.png)

8
docs/scrollback.md
View File

@ -9,7 +9,7 @@ down.
This section describes working with the scrollback and discusses some This section describes working with the scrollback and discusses some
configuration options; be sure to read the [configuration configuration options; be sure to read the [configuration
docs](config/files.html) to learn how to change your settings! docs](config/files.md) to learn how to change your settings!
### Controlling the scrollback size ### Controlling the scrollback size
@ -50,7 +50,7 @@ return {
} }
``` ```
You may [change the color of the scrollbar](config/appearance.html#defining-your-own-colors) if you wish! You may [change the color of the scrollbar](config/appearance.md#defining-your-own-colors) if you wish!
### Scrolling without a scrollbar ### Scrolling without a scrollbar
@ -103,7 +103,7 @@ may be more recent than your version of wezterm) is shown below.
You can see the configuration in your version of wezterm by running You can see the configuration in your version of wezterm by running
`wezterm show-keys --lua --key-table search_mode`. `wezterm show-keys --lua --key-table search_mode`.
{{#include examples/default-search-mode-key-table.markdown}} {% include "examples/default-search-mode-key-table.markdown" %}
(Those assignments reference `CopyMode` because search mode is a facet of [Copy Mode](copymode.md)). (Those assignments reference `CopyMode` because search mode is a facet of [Copy Mode](copymode.md)).
@ -143,5 +143,5 @@ With that in your config you can now:
without needing to reach for your mouse. without needing to reach for your mouse.
See [the Search action docs](config/lua/keyassignment/Search.html) for more information on See [the Search action docs](config/lua/keyassignment/Search.md) for more information on
using the `Search` action. using the `Search` action.

2
docs/ssh.md
View File

@ -21,7 +21,7 @@ create.
SSH sessions created in this way are non-persistent and all associated SSH sessions created in this way are non-persistent and all associated
tabs will die if your network connection is interrupted. tabs will die if your network connection is interrupted.
Take a look at [the multiplexing section](multiplexing.html) for an Take a look at [the multiplexing section](multiplexing.md) for an
alternative configuration that connects to a remote wezterm instance alternative configuration that connects to a remote wezterm instance
and preserves your tabs. and preserves your tabs.

23
docs/style.css Normal file
View File

@ -0,0 +1,23 @@
/* prevent selection of prefix and output for console syntax */
.language-console .gp, .language-console .go {
user-select: none;
-webkit-user-select: none; /* Chrome/Safari */
-ms-user-select: none; /* IE10+ */
color: !important pink;
}
@font-face {
font-family: "Symbols Nerd Font Mono";
src: url(fonts/Symbols-Nerd-Font-Mono.ttf) format("truetype");
font-weight: normal;
font-style: normal;
}
.nf {
font-family: "Symbols Nerd Font Mono";
speak: none;
line-height: 1;
-webkit-font-smoothing: antialiased;
-moz-osx-font-smoothing: grayscale;
}