From a11f036d8715494f4a16016fd2074c5f05eef7e9 Mon Sep 17 00:00:00 2001 From: Wez Furlong Date: Sun, 29 Dec 2019 20:41:08 -0800 Subject: [PATCH] Start migrating to mdbook for the docs Build the docs by installing mdbook and then running: `mdbook build docs` or run them live with `mdbook serve docs` --- .gitignore | 1 + docs/Gemfile | 6 - docs/Gemfile.lock | 256 ------------- docs/SUMMARY.md | 14 + docs/_includes/anchor_headings.html | 100 ------ docs/_includes/toc.html | 95 ----- docs/_layouts/default.html | 75 ---- docs/_layouts/notoc.html | 41 --- docs/book.toml | 9 + docs/changelog.markdown | 14 +- docs/config/appearance.markdown | 120 +++++++ docs/config/files.markdown | 22 ++ docs/config/font-shaping.markdown | 39 ++ docs/config/fonts.markdown | 134 +++++++ docs/config/index.markdown | 21 ++ docs/config/keys.markdown | 147 ++++++++ docs/config/misc.markdown | 79 ++++ docs/configuration.markdown | 536 ---------------------------- docs/features.markdown | 6 +- docs/imgcat.markdown | 4 - docs/index.markdown | 6 +- docs/install-jekyll.sh | 5 - docs/installation.markdown | 26 +- docs/multiplexing.markdown | 4 - docs/serial.markdown | 4 - docs/ssh.markdown | 4 - docs/toc.markdown | 17 - 27 files changed, 611 insertions(+), 1174 deletions(-) delete mode 100644 docs/Gemfile delete mode 100644 docs/Gemfile.lock create mode 100644 docs/SUMMARY.md delete mode 100644 docs/_includes/anchor_headings.html delete mode 100644 docs/_includes/toc.html delete mode 100644 docs/_layouts/default.html delete mode 100644 docs/_layouts/notoc.html create mode 100644 docs/book.toml create mode 100644 docs/config/appearance.markdown create mode 100644 docs/config/files.markdown create mode 100644 docs/config/font-shaping.markdown create mode 100644 docs/config/fonts.markdown create mode 100644 docs/config/index.markdown create mode 100644 docs/config/keys.markdown create mode 100644 docs/config/misc.markdown delete mode 100644 docs/configuration.markdown delete mode 100755 docs/install-jekyll.sh delete mode 100644 docs/toc.markdown diff --git a/.gitignore b/.gitignore index 0e2a152d3..3f5d2819e 100644 --- a/.gitignore +++ b/.gitignore @@ -5,6 +5,7 @@ /wezterm*.tar.xz /pkg /target/ +/gh_pages/ **/*.rs.bk .*.sw* /esctest.log diff --git a/docs/Gemfile b/docs/Gemfile deleted file mode 100644 index 4fb7a1418..000000000 --- a/docs/Gemfile +++ /dev/null @@ -1,6 +0,0 @@ -source 'https://rubygems.org' -gem 'github-pages', group: :jekyll_plugins -gem 'jekyll-redirect-from' -gem 'jekyll-octicons' -gem 'jekyll-avatar' - diff --git a/docs/Gemfile.lock b/docs/Gemfile.lock deleted file mode 100644 index 0dd95403c..000000000 --- a/docs/Gemfile.lock +++ /dev/null @@ -1,256 +0,0 @@ -GEM - remote: https://rubygems.org/ - specs: - activesupport (4.2.11.1) - i18n (~> 0.7) - minitest (~> 5.1) - thread_safe (~> 0.3, >= 0.3.4) - tzinfo (~> 1.1) - addressable (2.6.0) - public_suffix (>= 2.0.2, < 4.0) - coffee-script (2.4.1) - coffee-script-source - execjs - coffee-script-source (1.11.1) - colorator (1.1.0) - commonmarker (0.17.13) - ruby-enum (~> 0.5) - concurrent-ruby (1.1.5) - dnsruby (1.61.2) - addressable (~> 2.5) - em-websocket (0.5.1) - eventmachine (>= 0.12.9) - http_parser.rb (~> 0.6.0) - ethon (0.12.0) - ffi (>= 1.3.0) - eventmachine (1.2.7) - execjs (2.7.0) - faraday (0.15.4) - multipart-post (>= 1.2, < 3) - ffi (1.11.1) - forwardable-extended (2.6.0) - gemoji (3.0.1) - github-pages (198) - activesupport (= 4.2.11.1) - github-pages-health-check (= 1.16.1) - jekyll (= 3.8.5) - jekyll-avatar (= 0.6.0) - jekyll-coffeescript (= 1.1.1) - jekyll-commonmark-ghpages (= 0.1.5) - jekyll-default-layout (= 0.1.4) - jekyll-feed (= 0.11.0) - jekyll-gist (= 1.5.0) - jekyll-github-metadata (= 2.12.1) - jekyll-mentions (= 1.4.1) - jekyll-optional-front-matter (= 0.3.0) - jekyll-paginate (= 1.1.0) - jekyll-readme-index (= 0.2.0) - jekyll-redirect-from (= 0.14.0) - jekyll-relative-links (= 0.6.0) - jekyll-remote-theme (= 0.3.1) - jekyll-sass-converter (= 1.5.2) - jekyll-seo-tag (= 2.5.0) - jekyll-sitemap (= 1.2.0) - jekyll-swiss (= 0.4.0) - jekyll-theme-architect (= 0.1.1) - jekyll-theme-cayman (= 0.1.1) - jekyll-theme-dinky (= 0.1.1) - jekyll-theme-hacker (= 0.1.1) - jekyll-theme-leap-day (= 0.1.1) - jekyll-theme-merlot (= 0.1.1) - jekyll-theme-midnight (= 0.1.1) - jekyll-theme-minimal (= 0.1.1) - jekyll-theme-modernist (= 0.1.1) - jekyll-theme-primer (= 0.5.3) - jekyll-theme-slate (= 0.1.1) - jekyll-theme-tactile (= 0.1.1) - jekyll-theme-time-machine (= 0.1.1) - jekyll-titles-from-headings (= 0.5.1) - jemoji (= 0.10.2) - kramdown (= 1.17.0) - liquid (= 4.0.0) - listen (= 3.1.5) - mercenary (~> 0.3) - minima (= 2.5.0) - nokogiri (>= 1.8.5, < 2.0) - rouge (= 2.2.1) - terminal-table (~> 1.4) - github-pages-health-check (1.16.1) - addressable (~> 2.3) - dnsruby (~> 1.60) - octokit (~> 4.0) - public_suffix (~> 3.0) - typhoeus (~> 1.3) - html-pipeline (2.11.0) - activesupport (>= 2) - nokogiri (>= 1.4) - http_parser.rb (0.6.0) - i18n (0.9.5) - concurrent-ruby (~> 1.0) - jekyll (3.8.5) - addressable (~> 2.4) - colorator (~> 1.0) - em-websocket (~> 0.5) - i18n (~> 0.7) - jekyll-sass-converter (~> 1.0) - jekyll-watch (~> 2.0) - kramdown (~> 1.14) - liquid (~> 4.0) - mercenary (~> 0.3.3) - pathutil (~> 0.9) - rouge (>= 1.7, < 4) - safe_yaml (~> 1.0) - jekyll-avatar (0.6.0) - jekyll (~> 3.0) - jekyll-coffeescript (1.1.1) - coffee-script (~> 2.2) - coffee-script-source (~> 1.11.1) - jekyll-commonmark (1.3.1) - commonmarker (~> 0.14) - jekyll (>= 3.7, < 5.0) - jekyll-commonmark-ghpages (0.1.5) - commonmarker (~> 0.17.6) - jekyll-commonmark (~> 1) - rouge (~> 2) - jekyll-default-layout (0.1.4) - jekyll (~> 3.0) - jekyll-feed (0.11.0) - jekyll (~> 3.3) - jekyll-gist (1.5.0) - octokit (~> 4.2) - jekyll-github-metadata (2.12.1) - jekyll (~> 3.4) - octokit (~> 4.0, != 4.4.0) - jekyll-mentions (1.4.1) - html-pipeline (~> 2.3) - jekyll (~> 3.0) - jekyll-octicons (9.1.1) - jekyll (~> 3.1) - octicons (= 9.1.1) - jekyll-optional-front-matter (0.3.0) - jekyll (~> 3.0) - jekyll-paginate (1.1.0) - jekyll-readme-index (0.2.0) - jekyll (~> 3.0) - jekyll-redirect-from (0.14.0) - jekyll (~> 3.3) - jekyll-relative-links (0.6.0) - jekyll (~> 3.3) - jekyll-remote-theme (0.3.1) - jekyll (~> 3.5) - rubyzip (>= 1.2.1, < 3.0) - jekyll-sass-converter (1.5.2) - sass (~> 3.4) - jekyll-seo-tag (2.5.0) - jekyll (~> 3.3) - jekyll-sitemap (1.2.0) - jekyll (~> 3.3) - jekyll-swiss (0.4.0) - jekyll-theme-architect (0.1.1) - jekyll (~> 3.5) - jekyll-seo-tag (~> 2.0) - jekyll-theme-cayman (0.1.1) - jekyll (~> 3.5) - jekyll-seo-tag (~> 2.0) - jekyll-theme-dinky (0.1.1) - jekyll (~> 3.5) - jekyll-seo-tag (~> 2.0) - jekyll-theme-hacker (0.1.1) - jekyll (~> 3.5) - jekyll-seo-tag (~> 2.0) - jekyll-theme-leap-day (0.1.1) - jekyll (~> 3.5) - jekyll-seo-tag (~> 2.0) - jekyll-theme-merlot (0.1.1) - jekyll (~> 3.5) - jekyll-seo-tag (~> 2.0) - jekyll-theme-midnight (0.1.1) - jekyll (~> 3.5) - jekyll-seo-tag (~> 2.0) - jekyll-theme-minimal (0.1.1) - jekyll (~> 3.5) - jekyll-seo-tag (~> 2.0) - jekyll-theme-modernist (0.1.1) - jekyll (~> 3.5) - jekyll-seo-tag (~> 2.0) - jekyll-theme-primer (0.5.3) - jekyll (~> 3.5) - jekyll-github-metadata (~> 2.9) - jekyll-seo-tag (~> 2.0) - jekyll-theme-slate (0.1.1) - jekyll (~> 3.5) - jekyll-seo-tag (~> 2.0) - jekyll-theme-tactile (0.1.1) - jekyll (~> 3.5) - jekyll-seo-tag (~> 2.0) - jekyll-theme-time-machine (0.1.1) - jekyll (~> 3.5) - jekyll-seo-tag (~> 2.0) - jekyll-titles-from-headings (0.5.1) - jekyll (~> 3.3) - jekyll-watch (2.2.1) - listen (~> 3.0) - jemoji (0.10.2) - gemoji (~> 3.0) - html-pipeline (~> 2.2) - jekyll (~> 3.0) - kramdown (1.17.0) - liquid (4.0.0) - listen (3.1.5) - rb-fsevent (~> 0.9, >= 0.9.4) - rb-inotify (~> 0.9, >= 0.9.7) - ruby_dep (~> 1.2) - mercenary (0.3.6) - mini_portile2 (2.4.0) - minima (2.5.0) - jekyll (~> 3.5) - jekyll-feed (~> 0.9) - jekyll-seo-tag (~> 2.1) - minitest (5.11.3) - multipart-post (2.1.1) - nokogiri (1.10.4) - mini_portile2 (~> 2.4.0) - octicons (9.1.1) - nokogiri (>= 1.6.3.1) - octokit (4.14.0) - sawyer (~> 0.8.0, >= 0.5.3) - pathutil (0.16.2) - forwardable-extended (~> 2.6) - public_suffix (3.1.0) - rb-fsevent (0.10.3) - rb-inotify (0.10.0) - ffi (~> 1.0) - rouge (2.2.1) - ruby-enum (0.7.2) - i18n - ruby_dep (1.5.0) - rubyzip (1.2.3) - safe_yaml (1.0.5) - sass (3.7.4) - sass-listen (~> 4.0.0) - sass-listen (4.0.0) - rb-fsevent (~> 0.9, >= 0.9.4) - rb-inotify (~> 0.9, >= 0.9.7) - sawyer (0.8.2) - addressable (>= 2.3.5) - faraday (> 0.8, < 2.0) - terminal-table (1.8.0) - unicode-display_width (~> 1.1, >= 1.1.1) - thread_safe (0.3.6) - typhoeus (1.3.1) - ethon (>= 0.9.0) - tzinfo (1.2.5) - thread_safe (~> 0.1) - unicode-display_width (1.6.0) - -PLATFORMS - ruby - -DEPENDENCIES - github-pages - jekyll-avatar - jekyll-octicons - jekyll-redirect-from - -BUNDLED WITH - 1.17.2 diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md new file mode 100644 index 000000000..e4b4cba03 --- /dev/null +++ b/docs/SUMMARY.md @@ -0,0 +1,14 @@ +[wezterm](index.markdown) +- [Install](installation.markdown) +- [Features](features.markdown) +- [Change Log](changelog.markdown) +- [Configuration](config/index.markdown) + - [Fonts](config/fonts.markdown) + - [Font Shaping](config/font-shaping.markdown) + - [Misc](config/misc.markdown) + - [Key Binding](config/keys.markdown) + - [Colors & Appearance](config/appearance.markdown) +- [iTerm Image Protocol](imgcat.markdown) +- [SSH](ssh.markdown) +- [Serial Ports & Arduino](serial.markdown) +- [Multiplexing](multiplexing.markdown) diff --git a/docs/_includes/anchor_headings.html b/docs/_includes/anchor_headings.html deleted file mode 100644 index 25397df93..000000000 --- a/docs/_includes/anchor_headings.html +++ /dev/null @@ -1,100 +0,0 @@ -{% capture headingsWorkspace %} - {% comment %} - Version 1.0.3 - https://github.com/allejo/jekyll-anchor-headings - - "Be the pull request you wish to see in the world." ~Ben Balter - - Usage: - {% include anchor_headings.html html=content %} - - Parameters: - * html (string) - the HTML of compiled markdown generated by kramdown in Jekyll - - Optional Parameters: - * beforeHeading (bool) : false - Set to true if the anchor should be placed _before_ the heading's content - * anchorBody (string) : '' - The content that will be placed inside the anchor; the `%heading%` placeholder is available - * anchorClass (string) : '' - The class(es) that will be used for each anchor. Separate multiple classes with a space - * anchorTitle (string) : '' - The `title` attribute that will be used for anchors - * h_min (int) : 1 - The minimum header level to build an anchor for; any header lower than this value will be ignored - * h_max (int) : 6 - The maximum header level to build an anchor for; any header greater than this value will be ignored - * bodyPrefix (string) : '' - Anything that should be inserted inside of the heading tag _before_ its anchor and content - * bodySuffix (string) : '' - Anything that should be inserted inside of the heading tag _after_ its anchor and content - - Output: - The original HTML with the addition of anchors inside of all of the h1-h6 headings. - {% endcomment %} - - {% assign minHeader = include.h_min | default: 1 %} - {% assign maxHeader = include.h_max | default: 6 %} - {% assign beforeHeading = include.beforeHeading %} - {% assign nodes = include.html | split: ' - {% if headerLevel == 0 %} - {% if nextChar != '<' and nextChar != '' %} - {% capture node %}' | first }}>{% endcapture %} - {% assign header = _workspace[0] | replace: _hAttrToStrip, '' %} - - - {% capture anchor %}{% endcapture %} - - {% if html_id and headerLevel >= minHeader and headerLevel <= maxHeader %} - {% capture anchor %}href="#{{ html_id}}"{% endcapture %} - - {% if include.anchorClass %} - {% capture anchor %}{{ anchor }} class="{{ include.anchorClass }}"{% endcapture %} - {% endif %} - - {% if include.anchorTitle %} - {% capture anchor %}{{ anchor }} title="{{ include.anchorTitle | replace: '%heading%', header }}"{% endcapture %} - {% endif %} - - {% capture anchor %}{{ include.anchorBody | replace: '%heading%', header | default: '' }}{% endcapture %} - - - {% if beforeHeading %} - {% capture anchor %}{{ anchor }} {% endcapture %} - {% else %} - {% capture anchor %} {{ anchor }}{% endcapture %} - {% endif %} - {% endif %} - - {% capture new_heading %} - maxHeader %} - {% continue %} - {% endif %} - - {% if firstHeader %} - {% assign firstHeader = false %} - {% assign minHeader = headerLevel %} - {% endif %} - - {% assign indentAmount = headerLevel | minus: minHeader | add: 1 %} - {% assign _workspace = node | split: '' | first }}>{% endcapture %} - {% assign header = _workspace[0] | replace: _hAttrToStrip, '' %} - - {% assign space = '' %} - {% for i in (1..indentAmount) %} - {% assign space = space | prepend: ' ' %} - {% endfor %} - - {% unless include.item_class == blank %} - {% capture listItemClass %}{:.{{ include.item_class | replace: '%level%', headerLevel }}}{% endcapture %} - {% endunless %} - - {% capture my_toc %}{{ my_toc }} -{{ space }}{{ listModifier }} {{ listItemClass }} [{% if include.sanitize %}{{ header | strip_html }}{% else %}{{ header }}{% endif %}]({% if include.baseurl %}{{ include.baseurl }}{% endif %}#{{ html_id }}){% if include.anchor_class %}{:.{{ include.anchor_class }}}{% endif %}{% endcapture %} - {% endfor %} - - {% if include.class %} - {% capture my_toc %}{:.{{ include.class }}} -{{ my_toc | lstrip }}{% endcapture %} - {% endif %} - - {% if include.id %} - {% capture my_toc %}{: #{{ include.id }}} -{{ my_toc | lstrip }}{% endcapture %} - {% endif %} -{% endcapture %}{% assign tocWorkspace = '' %}{{ my_toc | markdownify | strip }} \ No newline at end of file diff --git a/docs/_layouts/default.html b/docs/_layouts/default.html deleted file mode 100644 index 2aeeeb7c4..000000000 --- a/docs/_layouts/default.html +++ /dev/null @@ -1,75 +0,0 @@ - - - - - - - -{% seo %} - - - - - - -
- {% if site.title and site.title != page.title %} -

{{ site.title }}

- {% endif %} - -{% include anchor_headings.html html=content %} - -
- Full Table of Contents -
- {{ site.github.repository_name }} is maintained by {{ site.github.owner_name }}. -
-
-
- - - {% if site.google_analytics %} - - {% endif %} - - - diff --git a/docs/_layouts/notoc.html b/docs/_layouts/notoc.html deleted file mode 100644 index a1072a320..000000000 --- a/docs/_layouts/notoc.html +++ /dev/null @@ -1,41 +0,0 @@ - - - - - - - -{% seo %} - - - -
- {% if site.title and site.title != page.title %} -

{{ site.title }}

- {% endif %} - -{% include anchor_headings.html html=content %} -
- Full Table of Contents -
- {{ site.github.repository_name }} is maintained by {{ site.github.owner_name }}. -
-
- -
- - - {% if site.google_analytics %} - - {% endif %} - - diff --git a/docs/book.toml b/docs/book.toml new file mode 100644 index 000000000..16c4d8cbb --- /dev/null +++ b/docs/book.toml @@ -0,0 +1,9 @@ +[book] +title = "Wez's Terminal Emulator" +author = "Wez Furlong" +src = "." + +[build] +build-dir = "../gh_pages" +create-missing = false + diff --git a/docs/changelog.markdown b/docs/changelog.markdown index 84660a785..f3f525830 100644 --- a/docs/changelog.markdown +++ b/docs/changelog.markdown @@ -1,9 +1,15 @@ ---- -title: Change Log ---- - ## Changes +Releases are named using the date, time and git commit +hash. + +### Nightly + +A bleeding edge build is produced continually (at least +daily) from the master branch. It may not be usable and +the feature set may change. As features stabilize some +brief notes about them may accumulate here. + ### 20191229-193639-e7aa2f3 * Fixed a hang when using middle mouse button to paste diff --git a/docs/config/appearance.markdown b/docs/config/appearance.markdown new file mode 100644 index 000000000..a5044e6c5 --- /dev/null +++ b/docs/config/appearance.markdown @@ -0,0 +1,120 @@ +### Colors + +You can configure colors with a section like this. In addition to specifying +[SVG/CSS3 color names](https://docs.rs/palette/0.4.1/palette/named/index.html#constants), +you can use `#RRGGBB` to specify a color code using the +usual hex notation; eg: `#000000` is equivalent to `black`: + +```toml +[colors] +# The default text color +foreground = "silver" +# The default background color +background = "black" + +# Overrides the cell background color when the current cell is occupied by the +# cursor and the cursor style is set to Block +cursor_bg = "#52ad70" +# Overrides the text color when the current cell is occupied by the cursor +cursor_fg = "black" +# Specifies the border color of the cursor when the cursor style is set to Block, +# of the color of the vertical or horizontal bar when the cursor style is set to +# Bar or Underline. +cursor_border = "#52ad70" + +# The color of the scrollbar "thumb"; the portion that represents the current viewport +scrollbar_thumb = "#222222" + +ansi = ["black", "maroon", "green", "olive", "navy", "purple", "teal", "silver"] +brights = ["grey", "red", "lime", "yellow", "blue", "fuchsia", "aqua", "white"] +``` + +You can find a variety of color schemes [here](https://github.com/mbadolato/iTerm2-Color-Schemes). +There are two ways to use them with wezterm: + +* [The wezterm directory](https://github.com/mbadolato/iTerm2-Color-Schemes/tree/master/wezterm) contains + configuration snippets that you can copy and paste into your `wezterm.toml` file + to set the default configuration. +* [The dynamic-colors directory](https://github.com/mbadolato/iTerm2-Color-Schemes/tree/master/dynamic-colors) + contains shell scripts that can change the color scheme immediately on the fly. + This is super convenient for trying out color schemes, and can be used in + your own scripts to alter the terminal appearance programmatically: + +```bash +$ git clone https://github.com/mbadolato/iTerm2-Color-Schemes.git +$ cd iTerm2-Color-Schemes/dynamic-colors +$ for scheme in *.sh ; do ; echo $scheme ; \ + bash "$scheme" ; ../tools/screenshotTable.sh; sleep 0.5; done +``` + + + +### Tab Bar Colors + +The following options control the appearance of the tab bar: + +```toml +[colors.tab_bar] +# The color of the strip that goes along the top of the window +background = "#0b0022" + +# The active tab is the one that has focus in the window +[colors.tab_bar.active_tab] +# The color of the background area for the tab +bg_color = "#2b2042" +# The color of the text for the tab +fg_color = "#c0c0c0" + +# Specify whether you want "Half", "Normal" or "Bold" intensity for the +# label shown for this tab. +# The default is "Normal" +intensity = "Normal" + +# Specify whether you want "None", "Single" or "Double" underline for +# label shown for this tab. +# The default is "None" +underline = "None" + +# Specify whether you want the text to be italic (true) or not (false) +# for this tab. The default is false. +italic = false + +# Specify whether you want the text to be rendered with strikethrough (true) +# or not for this tab. The default is false. +strikethrough = false + +# Inactive tabs are the tabs that do not have focus +[colors.tab_bar.inactive_tab] +bg_color = "#1b1032" +fg_color = "#808080" + +# The same options that were listed under the `active_tab` section above +# can also be used for `inactive_tab`. + +# You can configure some alternate styling when the mouse pointer +# moves over inactive tabs +[colors.tab_bar.inactive_tab_hover] +bg_color = "#3b3052" +fg_color = "#909090" +italic = true + +# The same options that were listed under the `active_tab` section above +# can also be used for `inactive_tab_hover`. +``` + + +### Window Padding + +You may add padding around the edges of the terminal cells: + +``` +[window_padding] +left = 2 + +# This will become the scrollbar width if you have enabled the scrollbar! +right = 2 + +top = 0 +bottom = 0 +``` + diff --git a/docs/config/files.markdown b/docs/config/files.markdown new file mode 100644 index 000000000..019ab60f5 --- /dev/null +++ b/docs/config/files.markdown @@ -0,0 +1,22 @@ +## Configuration Files + +`wezterm` will look for a TOML configuration file in the following locations, +stopping at the first file that it finds: + +* If the environment variable `$WEZTERM_CONFIG_FILE` is set, it will be treated as the + path to a configuration file. +* On Windows, `wezterm.toml` from the directory that contains `wezterm.exe`. + This is handy for users that want to carry their wezterm install around on a thumb drive. +* `$HOME/.config/wezterm/wezterm.toml`, +* `$HOME/.wezterm.toml` + +`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. + +Configuration is currently very simple and the format is considered unstable and subject +to change. The code for configuration can be found in [`src/config/mod.rs`](https://github.com/wez/wezterm/blob/master/src/config/mod.rs). + + diff --git a/docs/config/font-shaping.markdown b/docs/config/font-shaping.markdown new file mode 100644 index 000000000..054f7e8af --- /dev/null +++ b/docs/config/font-shaping.markdown @@ -0,0 +1,39 @@ +### Advanced Font Shaping Options + +The `harfbuzz_features` option allows specifying the features to enable when +using harfbuzz for font shaping. + +There is some light documentation here: + +but it boils down to allowing opentype feature names to be specified +using syntax similar to the CSS font-feature-settings options: +. +The OpenType spec lists a number of features here: + + +Options of likely interest will be: + +* `calt` - +* `clig` - + +If you want to disable ligatures in most fonts, then you may want to +use a setting like this: + +```toml +harfbuzz_features = ["calt=0", "clig=0", "liga=0"] +``` + +Some fonts make available extended options via stylistic sets. +If you use the [Fira Code font](https://github.com/tonsky/FiraCode), +it lists available stylistic sets here: + + +and you can set them in wezterm: + +```toml +# Use this for a zero with a dot rather than a line through it +# when using the Fira Code font +harfbuzz_features = ["zero"] +``` + + diff --git a/docs/config/fonts.markdown b/docs/config/fonts.markdown new file mode 100644 index 000000000..6393b45fd --- /dev/null +++ b/docs/config/fonts.markdown @@ -0,0 +1,134 @@ +### Font Related Configuration + +By default, wezterm will use an appropriate system-specific method for +locating the fonts that you specify using the options below. In addition, +if you configure the `font_dirs` option, wezterm will load fonts from that +set of directories: + +```toml +# This tells wezterm to look first for fonts in the directory named +# `fonts` that is found alongside your `wezterm.toml` file. +# As this option is an array, you may list multiple locations if +# you wish. +font_dirs = ["fonts"] +``` + +The following options impact how text is rendered: + +```toml +# The font size, measured in points +font_size = 11 + +# The DPI to assume, measured in dots-per-inch +# This is not automatically probed! If you experience blurry text +# or notice slight differences when comparing with other terminal +# emulators, you may wish to tune this value! +dpi = 96 +``` + +The baseline font is configured via the `[[font.font]]` section: + +```toml +[[font.font]] +# The font family name. The default is "Menlo" on macOS, +# "Consolas" on Windows and "monospace" on X11 based systems. +# "Fira Code" to enjoy ligatures without buying an expensive font! +family = "Operator Mono SSm Lig Medium" +# Whether the font should be a bold variant +# bold = false +# Whether the font should be an italic variant +# italic = false +``` + +You may specify rules that apply different font styling based on +the attributes of the text rendered in the terminal. Rules are +applied in the order that they are specified in the configuration +file, stopping with the first matching rule. + +``` +# Define a rule that matches when italic text is shown +[[font_rules]] +# If specified, this rule matches when a cell's italic value exactly +# matches this. If unspecified, the attribute value is irrelevant +# with respect to matching. +italic = true + +# Match based on intensity: "Bold", "Normal" and "Half" are supported +# intensity = "Normal" + +# Match based on underline: "None", "Single", and "Double" are supported +# underline = "None" + +# Match based on the blink attribute: "None", "Slow", "Rapid" +# blink = "None" + +# Match based on reverse video +# reverse = false + +# Match based on strikethrough +# strikethrough = false + +# Match based on the invisible attribute +# invisible = false + + # When the above attributes match, apply this font styling + [font_rules.font] + font = [{family = "Operator Mono SSm Lig Medium", italic=true}] + +``` + +Here's an example from my configuration file: + +``` +# Select a fancy italic font for italic text +[[font_rules]] +italic = true + [font_rules.font] + font = [{family = "Operator Mono SSm Lig Medium", italic=true}] + +# Similarly, a fancy bold+italic font +[[font_rules]] +italic = true +intensity = "Bold" + [font_rules.font] + font = [{family = "Operator Mono SSm Lig", italic=true, bold=true}] + +# Make regular bold text a different color to make it stand out even more +[[font_rules]] +intensity = "Bold" + [font_rules.font] + font = [{family = "Operator Mono SSm", bold=true}] + foreground="tomato" + +# For half-intensity text, use a lighter weight font +[[font_rules]] +intensity = "Half" + [font_rules.font] + font=[{family = "Operator Mono SSm Lig Light" }] +``` + +There are a couple of additional advanced font configuration options: + +* `font_locator` - specifies the method by which system fonts are + located and loaded. You may specify `ConfigDirsOnly` to disable + loading system fonts and use only the fonts found in the directories + that you specify in your `font_dirs` configuration option. Otherwise, + it is recommended to omit this setting. +* `font_shaper` - specifies the method by which text is mapped to glyphs + in the available fonts. The shaper is responsible for handling + kerning, ligatures and emoji composition. The default is `Harfbuzz` + and we have very preliminary support for `Allsorts`. +* `font_rasterizer` - specifies the method by which fonts are rendered + on screen. The only available implementation is `FreeType`. + +These options affect the appearance of the text. `Subpixel` antialiasing +is approximatley equivalent to ClearType rendering on Windows, but some +people find that it appears blurry. You may wish to try `Greyscale` in +that case. + +``` +font_antialias = "Subpixel" # None, Greyscale, Subpixel +font_hinting = "Full" # None, Vertical, VerticalSubpixel, Full +``` + + diff --git a/docs/config/index.markdown b/docs/config/index.markdown new file mode 100644 index 000000000..1b8ae1033 --- /dev/null +++ b/docs/config/index.markdown @@ -0,0 +1,21 @@ +## Configuration Files + +`wezterm` will look for a TOML configuration file in the following locations, +stopping at the first file that it finds: + +* If the environment variable `$WEZTERM_CONFIG_FILE` is set, it will be treated as the + path to a configuration file. +* On Windows, `wezterm.toml` from the directory that contains `wezterm.exe`. + This is handy for users that want to carry their wezterm install around on a thumb drive. +* `$HOME/.config/wezterm/wezterm.toml`, +* `$HOME/.wezterm.toml` + +`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. + +Configuration is currently very simple and the format is considered unstable and subject +to change. The code for configuration can be found in [`src/config/mod.rs`](https://github.com/wez/wezterm/blob/master/src/config/mod.rs). + diff --git a/docs/config/keys.markdown b/docs/config/keys.markdown new file mode 100644 index 000000000..803ace35a --- /dev/null +++ b/docs/config/keys.markdown @@ -0,0 +1,147 @@ +### Shortcut / Key Binding Assignments + +The default key bindings are: + +| Modifiers | Key | Action | +| --------- | --- | ------ | +| `SUPER` | `c` | `Copy` | +| `SUPER` | `v` | `Paste` | +| `CTRL+SHIFT` | `c` | `Copy` | +| `CTRL+SHIFT` | `v` | `Paste` | +| `SHIFT` | `Insert` | `Paste` | +| `SUPER` | `m` | `Hide` | +| `SUPER` | `n` | `SpawnWindow` | +| `CTRL+SHIFT` | `n` | `SpawnWindow` | +| `ALT` | `Enter` | `ToggleFullScreen` | +| `SUPER` | `-` | `DecreaseFontSize` | +| `CTRL` | `-` | `DecreaseFontSize` | +| `SUPER` | `=` | `IncreaseFontSize` | +| `CTRL` | `=` | `IncreaseFontSize` | +| `SUPER` | `0` | `ResetFontSize` | +| `CTRL` | `0` | `ResetFontSize` | +| `SUPER` | `t` | `SpawnTabInCurrentTabDomain` | +| `CTRL+SHIFT` | `t` | `SpawnTabInCurrentTabDomain` | +| `SUPER+SHIFT` | `T` | `SpawnTab` | +| `SUPER` | `w` | `CloseCurrentTab` | +| `SUPER` | `1` | `ActivateTab(0)` | +| `SUPER` | `2` | `ActivateTab(1)` | +| `SUPER` | `3` | `ActivateTab(2)` | +| `SUPER` | `4` | `ActivateTab(3)` | +| `SUPER` | `5` | `ActivateTab(4)` | +| `SUPER` | `6` | `ActivateTab(5)` | +| `SUPER` | `7` | `ActivateTab(6)` | +| `SUPER` | `8` | `ActivateTab(7)` | +| `SUPER` | `9` | `ActivateTab(8)` | +| `CTRL+SHIFT` | `w` | `CloseCurrentTab` | +| `CTRL+SHIFT` | `1` | `ActivateTab(0)` | +| `CTRL+SHIFT` | `2` | `ActivateTab(1)` | +| `CTRL+SHIFT` | `3` | `ActivateTab(2)` | +| `CTRL+SHIFT` | `4` | `ActivateTab(3)` | +| `CTRL+SHIFT` | `5` | `ActivateTab(4)` | +| `CTRL+SHIFT` | `6` | `ActivateTab(5)` | +| `CTRL+SHIFT` | `7` | `ActivateTab(6)` | +| `CTRL+SHIFT` | `8` | `ActivateTab(7)` | +| `CTRL+SHIFT` | `9` | `ActivateTab(8)` | +| `SUPER+SHIFT` | `[` | `ActivateTabRelative(-1)` | +| `SUPER+SHIFT` | `]` | `ActivateTabRelative(1)` | + +These can be overridden using the `keys` section in your `~/.wezterm.toml` config file. +For example, you can disable a default assignment like this: + +``` +# Turn off the default CMD-m Hide action +[[keys]] +key = "m" +mods = "CMD" +action = "Nop" +``` + +The `key` value can be one of the following keycode identifiers. Note that not +all of these are meaningful on all platforms: + +`Hyper`, `Super`, `Meta`, `Cancel`, `Backspace`, `Tab`, `Clear`, `Enter`, +`Shift`, `Escape`, `LeftShift`, `RightShift`, `Control`, `LeftControl`, +`RightControl`, `Alt`, `LeftAlt`, `RightAlt`, `Menu`, `LeftMenu`, `RightMenu`, +`Pause`, `CapsLock`, `PageUp`, `PageDown`, `End`, `Home`, `LeftArrow`, +`RightArrow`, `UpArrow`, `DownArrow`, `Select`, `Print`, `Execute`, +`PrintScreen`, `Insert`, `Delete`, `Help`, `LeftWindows`, `RightWindows`, +`Applications`, `Sleep`, `Numpad0`, `Numpad1`, `Numpad2`, `Numpad3`, +`Numpad4`, `Numpad5`, `Numpad6`, `Numpad7`, `Numpad8`, `Numpad9`, `Multiply`, +`Add`, `Separator`, `Subtract`, `Decimal`, `Divide`, `NumLock`, `ScrollLock`, +`BrowserBack`, `BrowserForward`, `BrowserRefresh`, `BrowserStop`, +`BrowserSearch`, `BrowserFavorites`, `BrowserHome`, `VolumeMute`, +`VolumeDown`, `VolumeUp`, `MediaNextTrack`, `MediaPrevTrack`, `MediaStop`, +`MediaPlayPause`, `ApplicationLeftArrow`, `ApplicationRightArrow`, +`ApplicationUpArrow`, `ApplicationDownArrow`. + +Alternatively, a single unicode character can be specified to indicate +pressing the corresponding key. + +Possible Modifier labels are: + + * `SUPER`, `CMD`, `WIN` - these are all equivalent: on macOS the `Command` key, + on Windows the `Windows` key, on Linux this can also be the `Super` or `Hyper` + key. Left and right are equivalent. + * `SHIFT` - The shift key. Left and right are equivalent. + * `ALT`, `OPT`, `META` - these are all equivalent: on macOS the `Option` key, + on other systems the `Alt` or `Meta` key. Left and right are equivalent. + +You can combine modifiers using the `|` symbol (eg: `"CMD|CTRL"`). + +Possible actions are listed below. Some actions require a parameter that is +specified via the `arg` key; see examples below. + +| Name | Effect | +| ------------------ | ------------------ | +| `SpawnTab` | Create a new local tab in the current window | +| `SpawnTabInCurrentTabDomain` | Create a new tab in the current window. The tab will be spawned in the same domain as the currently active tab | +| `SpawnTabInDomain` | Create a new tab in the current window. The tab will be spawned in the domain specified by the `arg` value | +| `SpawnWindow` | Create a new window | +| `ToggleFullScreen` | Toggles full screen mode for current window | +| `Paste` | Paste the clipboard to the current tab | +| `ActivateTabRelative` | Activate a tab relative to the current tab. The `arg` value specifies an offset. eg: `-1` activates the tab to the left of the current tab, while `1` activates the tab to the right. | +| `ActivateTab` | Activate the tab specified by the `arg` value. eg: `0` activates the leftmost tab, while `1` activates the second tab from the left, and so on. | +| `IncreaseFontSize` | Increases the font size of the current window by 10% | +| `DecreaseFontSize` | Decreases the font size of the current window by 10% | +| `ResetFontSize` | Reset the font size for the current window to the value in your configuration | +| `SendString` | Sends the string specified by the `arg` value to the terminal in the current tab, as though that text were literally typed into the terminal. | +| `Nop` | Does nothing. This is useful to disable a default key assignment. | +| `Hide` | Hides the current window | +| `Show` | Shows the current window | +| `CloseCurrentTab` | Equivalent to clicking the `x` on the window title bar to close it: Closes the current tab. If that was the last tab, closes that window. If that was the last window, wezterm terminates. | + +Example: + +```toml +# Turn off the default CMD-m Hide action +[[keys]] +key = "m" +mods = "CMD" +action = "Nop" + +# Macro for sending in some boiler plate. This types `wtf!?` each +# time CMD+SHIFT+W is pressed +[[keys]] +key = "W" +mods = "CMD|SHIFT" +action = "SendString" +arg = "wtf!?" + +# CTRL+ALT+0 activates the leftmost tab +[[keys]] +key = "0" +mods = "CTRL|ALT" +action = "ActivateTab" +# the tab number +arg = "0" + +# CMD+y spawns a new tab in Domain 1 +[[keys]] +key = "y" +mods = "CMD" +action = "SpawnTabInDomain" +# the domain ID +arg = "1" +``` + + diff --git a/docs/config/misc.markdown b/docs/config/misc.markdown new file mode 100644 index 000000000..edf4c3f32 --- /dev/null +++ b/docs/config/misc.markdown @@ -0,0 +1,79 @@ +### Misc configuration + +```toml +# How many lines of scrollback you want to retain per tab +scrollback_lines = 3500 + +# Enable the scrollbar. This is currently disabled by default. +# It will occupy the right window padding space. +# If right padding is set to 0 then it will be increased +# to a single cell width +enable_scroll_bar = true + +# If no `prog` is specified on the command line, use this +# instead of running the user's shell. +# The value is the argument array, with the 0th element being +# the executable to run. The path will be searched to locate +# this if needed. +# For example, to have `wezterm` always run `top` by default, +# you'd use this: +default_prog = ["top"] + +# What to set the TERM variable to +term = "xterm-256color" + +# Constrains the rate at which output from a child command is +# processed and applied to the terminal model. +# This acts as a brake in the case of a command spewing a +# ton of output and allows for the UI to remain responsive +# so that you can hit CTRL-C to interrupt it if desired. +# The default value is 200,000 bytes/s. +ratelimit_output_bytes_per_second = 200_000 + +# Constrains the rate at which the multiplexer server will +# unilaterally push data to the client. +# This helps to avoid saturating the link between the client +# and server. +# Each time the screen is updated as a result of the child +# command outputting data (rather than in response to input +# from the client), the server considers whether to push +# the result to the client. +# That decision is throttled by this configuration value +# which has a default value of 10/s +ratelimit_mux_output_pushes_per_second = 10 + +# Constrain how often the mux server scans the terminal +# model to compute a diff to send to the mux client. +# The default value is 100/s +ratelimit_mux_output_scans_per_second = 100 + +# If false, do not try to use a Wayland protocol connection +# when starting the gui frontend, and instead use X11. +# This option is only considered on X11/Wayland systems and +# has no effect on macOS or Windows. +# The default is true. +enable_wayland = true + + +# Specifies how often a blinking cursor transitions between visible +# and invisible, expressed in milliseconds. +# Setting this to 0 disables blinking. +# Note that this value is approximate due to the way that the system +# event loop schedulers manage timers; non-zero values will be at +# least the interval specified with some degree of slop. +# It is recommended to avoid blinking cursors when on battery power, +# as it is relatively costly to keep re-rendering for the blink! +cursor_blink_rate = 800 + +# Specifies the default cursor style. various escape sequences +# can override the default style in different situations (eg: +# an editor can change it depending on the mode), but this value +# controls how the cursor appears when it is reset to default. +# The default is `SteadyBlock`. +# Acceptable values are `SteadyBlock`, `BlinkingBlock`, +# `SteadyUnderline`, `BlinkingUnderline`, `SteadyBar`, +# and `BlinkingBar`. +default_cursor_style = "SteadyBlock" +``` + + diff --git a/docs/configuration.markdown b/docs/configuration.markdown deleted file mode 100644 index a40247e26..000000000 --- a/docs/configuration.markdown +++ /dev/null @@ -1,536 +0,0 @@ ---- -title: Configuration ---- - -## Configuration - -`wezterm` will look for a TOML configuration file in the following locations, -stopping at the first file that it finds: - -* If the environment variable `$WEZTERM_CONFIG_FILE` is set, it will be treated as the - path to a configuration file. -* On Windows, `wezterm.toml` from the directory that contains `wezterm.exe`. - This is handy for users that want to carry their wezterm install around on a thumb drive. -* `$HOME/.config/wezterm/wezterm.toml`, -* `$HOME/.wezterm.toml` - -`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. - -Configuration is currently very simple and the format is considered unstable and subject -to change. The code for configuration can be found in [`src/config/mod.rs`](https://github.com/wez/wezterm/blob/master/src/config/mod.rs). - -### Font Related Configuration - -By default, wezterm will use an appropriate system-specific method for -locating the fonts that you specify using the options below. In addition, -if you configure the `font_dirs` option, wezterm will load fonts from that -set of directories: - -```toml -# This tells wezterm to look first for fonts in the directory named -# `fonts` that is found alongside your `wezterm.toml` file. -# As this option is an array, you may list multiple locations if -# you wish. -font_dirs = ["fonts"] -``` - -The following options impact how text is rendered: - -```toml -# The font size, measured in points -font_size = 11 - -# The DPI to assume, measured in dots-per-inch -# This is not automatically probed! If you experience blurry text -# or notice slight differences when comparing with other terminal -# emulators, you may wish to tune this value! -dpi = 96 -``` - -The baseline font is configured via the `[[font.font]]` section: - -```toml -[[font.font]] -# The font family name. The default is "Menlo" on macOS, -# "Consolas" on Windows and "monospace" on X11 based systems. -# "Fira Code" to enjoy ligatures without buying an expensive font! -family = "Operator Mono SSm Lig Medium" -# Whether the font should be a bold variant -# bold = false -# Whether the font should be an italic variant -# italic = false -``` - -You may specify rules that apply different font styling based on -the attributes of the text rendered in the terminal. Rules are -applied in the order that they are specified in the configuration -file, stopping with the first matching rule. - -``` -# Define a rule that matches when italic text is shown -[[font_rules]] -# If specified, this rule matches when a cell's italic value exactly -# matches this. If unspecified, the attribute value is irrelevant -# with respect to matching. -italic = true - -# Match based on intensity: "Bold", "Normal" and "Half" are supported -# intensity = "Normal" - -# Match based on underline: "None", "Single", and "Double" are supported -# underline = "None" - -# Match based on the blink attribute: "None", "Slow", "Rapid" -# blink = "None" - -# Match based on reverse video -# reverse = false - -# Match based on strikethrough -# strikethrough = false - -# Match based on the invisible attribute -# invisible = false - - # When the above attributes match, apply this font styling - [font_rules.font] - font = [{family = "Operator Mono SSm Lig Medium", italic=true}] - -``` - -Here's an example from my configuration file: - -``` -# Select a fancy italic font for italic text -[[font_rules]] -italic = true - [font_rules.font] - font = [{family = "Operator Mono SSm Lig Medium", italic=true}] - -# Similarly, a fancy bold+italic font -[[font_rules]] -italic = true -intensity = "Bold" - [font_rules.font] - font = [{family = "Operator Mono SSm Lig", italic=true, bold=true}] - -# Make regular bold text a different color to make it stand out even more -[[font_rules]] -intensity = "Bold" - [font_rules.font] - font = [{family = "Operator Mono SSm", bold=true}] - foreground="tomato" - -# For half-intensity text, use a lighter weight font -[[font_rules]] -intensity = "Half" - [font_rules.font] - font=[{family = "Operator Mono SSm Lig Light" }] -``` - -There are a couple of additional advanced font configuration options: - -* `font_locator` - specifies the method by which system fonts are - located and loaded. You may specify `ConfigDirsOnly` to disable - loading system fonts and use only the fonts found in the directories - that you specify in your `font_dirs` configuration option. Otherwise, - it is recommended to omit this setting. -* `font_shaper` - specifies the method by which text is mapped to glyphs - in the available fonts. The shaper is responsible for handling - kerning, ligatures and emoji composition. The default is `Harfbuzz` - and we have very preliminary support for `Allsorts`. -* `font_rasterizer` - specifies the method by which fonts are rendered - on screen. The only available implementation is `FreeType`. - -These options affect the appearance of the text. `Subpixel` antialiasing -is approximatley equivalent to ClearType rendering on Windows, but some -people find that it appears blurry. You may wish to try `Greyscale` in -that case. - -``` -font_antialias = "Subpixel" # None, Greyscale, Subpixel -font_hinting = "Full" # None, Vertical, VerticalSubpixel, Full -``` - -### Advanced Font Shaping Options - -The `harfbuzz_features` option allows specifying the features to enable when -using harfbuzz for font shaping. - -There is some light documentation here: - -but it boils down to allowing opentype feature names to be specified -using syntax similar to the CSS font-feature-settings options: -. -The OpenType spec lists a number of features here: - - -Options of likely interest will be: - -* `calt` - -* `clig` - - -If you want to disable ligatures in most fonts, then you may want to -use a setting like this: - -```toml -harfbuzz_features = ["calt=0", "clig=0", "liga=0"] -``` - -Some fonts make available extended options via stylistic sets. -If you use the [Fira Code font](https://github.com/tonsky/FiraCode), -it lists available stylistic sets here: - - -and you can set them in wezterm: - -```toml -# Use this for a zero with a dot rather than a line through it -# when using the Fira Code font -harfbuzz_features = ["zero"] -``` - -### Misc configuration - -```toml -# How many lines of scrollback you want to retain per tab -scrollback_lines = 3500 - -# Enable the scrollbar. This is currently disabled by default. -# It will occupy the right window padding space. -# If right padding is set to 0 then it will be increased -# to a single cell width -enable_scroll_bar = true - -# If no `prog` is specified on the command line, use this -# instead of running the user's shell. -# The value is the argument array, with the 0th element being -# the executable to run. The path will be searched to locate -# this if needed. -# For example, to have `wezterm` always run `top` by default, -# you'd use this: -default_prog = ["top"] - -# What to set the TERM variable to -term = "xterm-256color" - -# Constrains the rate at which output from a child command is -# processed and applied to the terminal model. -# This acts as a brake in the case of a command spewing a -# ton of output and allows for the UI to remain responsive -# so that you can hit CTRL-C to interrupt it if desired. -# The default value is 200,000 bytes/s. -ratelimit_output_bytes_per_second = 200_000 - -# Constrains the rate at which the multiplexer server will -# unilaterally push data to the client. -# This helps to avoid saturating the link between the client -# and server. -# Each time the screen is updated as a result of the child -# command outputting data (rather than in response to input -# from the client), the server considers whether to push -# the result to the client. -# That decision is throttled by this configuration value -# which has a default value of 10/s -ratelimit_mux_output_pushes_per_second = 10 - -# Constrain how often the mux server scans the terminal -# model to compute a diff to send to the mux client. -# The default value is 100/s -ratelimit_mux_output_scans_per_second = 100 - -# If false, do not try to use a Wayland protocol connection -# when starting the gui frontend, and instead use X11. -# This option is only considered on X11/Wayland systems and -# has no effect on macOS or Windows. -# The default is true. -enable_wayland = true - - -# Specifies how often a blinking cursor transitions between visible -# and invisible, expressed in milliseconds. -# Setting this to 0 disables blinking. -# Note that this value is approximate due to the way that the system -# event loop schedulers manage timers; non-zero values will be at -# least the interval specified with some degree of slop. -# It is recommended to avoid blinking cursors when on battery power, -# as it is relatively costly to keep re-rendering for the blink! -cursor_blink_rate = 800 - -# Specifies the default cursor style. various escape sequences -# can override the default style in different situations (eg: -# an editor can change it depending on the mode), but this value -# controls how the cursor appears when it is reset to default. -# The default is `SteadyBlock`. -# Acceptable values are `SteadyBlock`, `BlinkingBlock`, -# `SteadyUnderline`, `BlinkingUnderline`, `SteadyBar`, -# and `BlinkingBar`. -default_cursor_style = "SteadyBlock" -``` - -### Shortcut / Key Binding Assignments - -The default key bindings are: - -| Modifiers | Key | Action | -| --------- | --- | ------ | -| `SUPER` | `c` | `Copy` | -| `SUPER` | `v` | `Paste` | -| `CTRL|SHIFT` | `c` | `Copy` | -| `CTRL|SHIFT` | `v` | `Paste` | -| `SHIFT` | `Insert` | `Paste` | -| `SUPER` | `m` | `Hide` | -| `SUPER` | `n` | `SpawnWindow` | -| `CTRL|SHIFT` | `n` | `SpawnWindow` | -| `ALT` | `Enter` | `ToggleFullScreen` | -| `SUPER` | `-` | `DecreaseFontSize` | -| `CTRL` | `-` | `DecreaseFontSize` | -| `SUPER` | `=` | `IncreaseFontSize` | -| `CTRL` | `=` | `IncreaseFontSize` | -| `SUPER` | `0` | `ResetFontSize` | -| `CTRL` | `0` | `ResetFontSize` | -| `SUPER` | `t` | `SpawnTabInCurrentTabDomain` | -| `CTRL|SHIFT` | `t` | `SpawnTabInCurrentTabDomain` | -| `SUPER|SHIFT` | `T` | `SpawnTab` | -| `SUPER` | `w` | `CloseCurrentTab` | -| `SUPER` | `1` | `ActivateTab(0)` | -| `SUPER` | `2` | `ActivateTab(1)` | -| `SUPER` | `3` | `ActivateTab(2)` | -| `SUPER` | `4` | `ActivateTab(3)` | -| `SUPER` | `5` | `ActivateTab(4)` | -| `SUPER` | `6` | `ActivateTab(5)` | -| `SUPER` | `7` | `ActivateTab(6)` | -| `SUPER` | `8` | `ActivateTab(7)` | -| `SUPER` | `9` | `ActivateTab(8)` | -| `CTRL|SHIFT` | `w` | `CloseCurrentTab` | -| `CTRL|SHIFT` | `1` | `ActivateTab(0)` | -| `CTRL|SHIFT` | `2` | `ActivateTab(1)` | -| `CTRL|SHIFT` | `3` | `ActivateTab(2)` | -| `CTRL|SHIFT` | `4` | `ActivateTab(3)` | -| `CTRL|SHIFT` | `5` | `ActivateTab(4)` | -| `CTRL|SHIFT` | `6` | `ActivateTab(5)` | -| `CTRL|SHIFT` | `7` | `ActivateTab(6)` | -| `CTRL|SHIFT` | `8` | `ActivateTab(7)` | -| `CTRL|SHIFT` | `9` | `ActivateTab(8)` | -| `SUPER\|SHIFT` | `[` | `ActivateTabRelative(-1)` | -| `SUPER\|SHIFT` | `]` | `ActivateTabRelative(1)` | - -These can be overridden using the `keys` section in your `~/.wezterm.toml` config file. -For example, you can disable a default assignment like this: - -``` -# Turn off the default CMD-m Hide action -[[keys]] -key = "m" -mods = "CMD" -action = "Nop" -``` - -The `key` value can be one of the following keycode identifiers. Note that not -all of these are meaningful on all platforms: - -`Hyper`, `Super`, `Meta`, `Cancel`, `Backspace`, `Tab`, `Clear`, `Enter`, -`Shift`, `Escape`, `LeftShift`, `RightShift`, `Control`, `LeftControl`, -`RightControl`, `Alt`, `LeftAlt`, `RightAlt`, `Menu`, `LeftMenu`, `RightMenu`, -`Pause`, `CapsLock`, `PageUp`, `PageDown`, `End`, `Home`, `LeftArrow`, -`RightArrow`, `UpArrow`, `DownArrow`, `Select`, `Print`, `Execute`, -`PrintScreen`, `Insert`, `Delete`, `Help`, `LeftWindows`, `RightWindows`, -`Applications`, `Sleep`, `Numpad0`, `Numpad1`, `Numpad2`, `Numpad3`, -`Numpad4`, `Numpad5`, `Numpad6`, `Numpad7`, `Numpad8`, `Numpad9`, `Multiply`, -`Add`, `Separator`, `Subtract`, `Decimal`, `Divide`, `NumLock`, `ScrollLock`, -`BrowserBack`, `BrowserForward`, `BrowserRefresh`, `BrowserStop`, -`BrowserSearch`, `BrowserFavorites`, `BrowserHome`, `VolumeMute`, -`VolumeDown`, `VolumeUp`, `MediaNextTrack`, `MediaPrevTrack`, `MediaStop`, -`MediaPlayPause`, `ApplicationLeftArrow`, `ApplicationRightArrow`, -`ApplicationUpArrow`, `ApplicationDownArrow`. - -Alternatively, a single unicode character can be specified to indicate -pressing the corresponding key. - -Possible Modifier labels are: - - * `SUPER`, `CMD`, `WIN` - these are all equivalent: on macOS the `Command` key, - on Windows the `Windows` key, on Linux this can also be the `Super` or `Hyper` - key. Left and right are equivalent. - * `SHIFT` - The shift key. Left and right are equivalent. - * `ALT`, `OPT`, `META` - these are all equivalent: on macOS the `Option` key, - on other systems the `Alt` or `Meta` key. Left and right are equivalent. - -You can combine modifiers using the `|` symbol (eg: `"CMD|CTRL"`). - -Possible actions are listed below. Some actions require a parameter that is -specified via the `arg` key; see examples below. - -| Name | Effect | -| ------------------ | ------------------ | -| `SpawnTab` | Create a new local tab in the current window | -| `SpawnTabInCurrentTabDomain` | Create a new tab in the current window. The tab will be spawned in the same domain as the currently active tab | -| `SpawnTabInDomain` | Create a new tab in the current window. The tab will be spawned in the domain specified by the `arg` value | -| `SpawnWindow` | Create a new window | -| `ToggleFullScreen` | Toggles full screen mode for current window | -| `Paste` | Paste the clipboard to the current tab | -| `ActivateTabRelative` | Activate a tab relative to the current tab. The `arg` value specifies an offset. eg: `-1` activates the tab to the left of the current tab, while `1` activates the tab to the right. | -| `ActivateTab` | Activate the tab specified by the `arg` value. eg: `0` activates the leftmost tab, while `1` activates the second tab from the left, and so on. | -| `IncreaseFontSize` | Increases the font size of the current window by 10% | -| `DecreaseFontSize` | Decreases the font size of the current window by 10% | -| `ResetFontSize` | Reset the font size for the current window to the value in your configuration | -| `SendString` | Sends the string specified by the `arg` value to the terminal in the current tab, as though that text were literally typed into the terminal. | -| `Nop` | Does nothing. This is useful to disable a default key assignment. | -| `Hide` | Hides the current window | -| `Show` | Shows the current window | -| `CloseCurrentTab` | Equivalent to clicking the `x` on the window title bar to close it: Closes the current tab. If that was the last tab, closes that window. If that was the last window, wezterm terminates. | - -Example: - -```toml -# Turn off the default CMD-m Hide action -[[keys]] -key = "m" -mods = "CMD" -action = "Nop" - -# Macro for sending in some boiler plate. This types `wtf!?` each -# time CMD+SHIFT+W is pressed -[[keys]] -key = "W" -mods = "CMD|SHIFT" -action = "SendString" -arg = "wtf!?" - -# CTRL+ALT+0 activates the leftmost tab -[[keys]] -key = "0" -mods = "CTRL|ALT" -action = "ActivateTab" -# the tab number -arg = "0" - -# CMD+y spawns a new tab in Domain 1 -[[keys]] -key = "y" -mods = "CMD" -action = "SpawnTabInDomain" -# the domain ID -arg = "1" -``` - -### Window Padding - -You may add padding around the edges of the terminal cells: - -``` -[window_padding] -left = 2 - -# This will become the scrollbar width if you have enabled the scrollbar! -right = 2 - -top = 0 -bottom = 0 -``` - -### Colors - -You can configure colors with a section like this. In addition to specifying -[SVG/CSS3 color names](https://docs.rs/palette/0.4.1/palette/named/index.html#constants), -you can use `#RRGGBB` to specify a color code using the -usual hex notation; eg: `#000000` is equivalent to `black`: - -```toml -[colors] -# The default text color -foreground = "silver" -# The default background color -background = "black" - -# Overrides the cell background color when the current cell is occupied by the -# cursor and the cursor style is set to Block -cursor_bg = "#52ad70" -# Overrides the text color when the current cell is occupied by the cursor -cursor_fg = "black" -# Specifies the border color of the cursor when the cursor style is set to Block, -# of the color of the vertical or horizontal bar when the cursor style is set to -# Bar or Underline. -cursor_border = "#52ad70" - -# The color of the scrollbar "thumb"; the portion that represents the current viewport -scrollbar_thumb = "#222222" - -ansi = ["black", "maroon", "green", "olive", "navy", "purple", "teal", "silver"] -brights = ["grey", "red", "lime", "yellow", "blue", "fuchsia", "aqua", "white"] -``` - -You can find a variety of color schemes [here](https://github.com/mbadolato/iTerm2-Color-Schemes). -There are two ways to use them with wezterm: - -* [The wezterm directory](https://github.com/mbadolato/iTerm2-Color-Schemes/tree/master/wezterm) contains - configuration snippets that you can copy and paste into your `wezterm.toml` file - to set the default configuration. -* [The dynamic-colors directory](https://github.com/mbadolato/iTerm2-Color-Schemes/tree/master/dynamic-colors) - contains shell scripts that can change the color scheme immediately on the fly. - This is super convenient for trying out color schemes, and can be used in - your own scripts to alter the terminal appearance programmatically: - -```bash -$ git clone https://github.com/mbadolato/iTerm2-Color-Schemes.git -$ cd iTerm2-Color-Schemes/dynamic-colors -$ for scheme in *.sh ; do ; echo $scheme ; \ - bash "$scheme" ; ../tools/screenshotTable.sh; sleep 0.5; done -``` - - - -### Tab Bar Colors - -The following options control the appearance of the tab bar: - -```toml -[colors.tab_bar] -# The color of the strip that goes along the top of the window -background = "#0b0022" - -# The active tab is the one that has focus in the window -[colors.tab_bar.active_tab] -# The color of the background area for the tab -bg_color = "#2b2042" -# The color of the text for the tab -fg_color = "#c0c0c0" - -# Specify whether you want "Half", "Normal" or "Bold" intensity for the -# label shown for this tab. -# The default is "Normal" -intensity = "Normal" - -# Specify whether you want "None", "Single" or "Double" underline for -# label shown for this tab. -# The default is "None" -underline = "None" - -# Specify whether you want the text to be italic (true) or not (false) -# for this tab. The default is false. -italic = false - -# Specify whether you want the text to be rendered with strikethrough (true) -# or not for this tab. The default is false. -strikethrough = false - -# Inactive tabs are the tabs that do not have focus -[colors.tab_bar.inactive_tab] -bg_color = "#1b1032" -fg_color = "#808080" - -# The same options that were listed under the `active_tab` section above -# can also be used for `inactive_tab`. - -# You can configure some alternate styling when the mouse pointer -# moves over inactive tabs -[colors.tab_bar.inactive_tab_hover] -bg_color = "#3b3052" -fg_color = "#909090" -italic = true - -# The same options that were listed under the `active_tab` section above -# can also be used for `inactive_tab_hover`. -``` - diff --git a/docs/features.markdown b/docs/features.markdown index 9f4fad8e9..53be5b341 100644 --- a/docs/features.markdown +++ b/docs/features.markdown @@ -1,8 +1,4 @@ ---- -title: Feature list ---- - -## {% octicon list-unordered height:24 %} Available Features +## Available Features * Runs on Linux, macOS and Windows 10 * [Multiplex terminal tabs and windows on local and remote hosts, with native mouse and scrollback](multiplexing.html) diff --git a/docs/imgcat.markdown b/docs/imgcat.markdown index 69db53431..c2827cc56 100644 --- a/docs/imgcat.markdown +++ b/docs/imgcat.markdown @@ -1,7 +1,3 @@ ---- -title: iTerm Image Protocol Support ---- - ## iTerm Image Protocol Support wezterm implements support for the [iTerm2 inline images diff --git a/docs/index.markdown b/docs/index.markdown index db74a548f..785d7a82a 100644 --- a/docs/index.markdown +++ b/docs/index.markdown @@ -1,11 +1,7 @@ ---- -title: Wez's Terminal -layout: notoc ---- *A GPU-accelerated cross-platform terminal emulator and multiplexer written by @wez and implemented in Rust* -{% octicon cloud-download %} Download +Download ## Features diff --git a/docs/install-jekyll.sh b/docs/install-jekyll.sh deleted file mode 100755 index 3d3c02c21..000000000 --- a/docs/install-jekyll.sh +++ /dev/null @@ -1,5 +0,0 @@ -#!/bin/sh -gem install --user-install bundler jekyll -GEM_HOME=$HOME/.gem bundle install - -echo "You can now use 'GEM_HOME=$HOME/.gem bundle exec jekyll serve' to test the docs locally" diff --git a/docs/installation.markdown b/docs/installation.markdown index 638cf28ac..6e08473b6 100644 --- a/docs/installation.markdown +++ b/docs/installation.markdown @@ -40,23 +40,23 @@ title: Installation {% endfor %} -## {% octicon cloud-download height:24 %} Installing a pre-built package on Windows +## Installing a pre-built package on Windows Windows 10 or later is required to run WezTerm. -{% octicon cloud-download %} Download for Windows -{% octicon beaker %} Nightly for Windows +Download for Windows +Nightly for Windows 1. Download Release 2. Extract the zipfile and double-click `wezterm.exe` to run the UI 3. Configuration instructions can be [found here](configuration.html) -## {% octicon cloud-download height:24 %} Installing a pre-built package on macOS +## Installing a pre-built package on macOS The CI system builds the package on macOS Mojave (10.14). It may run on earlier versions of macOS, but that has not been tested. -{% octicon cloud-download %} Download for macOS -{% octicon beaker %} Nightly for macOS +Download for macOS +Nightly for macOS 1. Download Release 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 @@ -64,30 +64,30 @@ versions of macOS, but that has not been tested. 3. Subsequently, a simple double-click will launch the UI 4. Configuration instructions can be [found here](configuration.html) -## {% octicon cloud-download height:24 %} Installing a pre-built package on Ubuntu +## Installing a pre-built package on Ubuntu The CI system builds a `.deb` file on Ubuntu 16.04. It is compatible with other debian style systems, including Debian 9 (Stretch) and later versions. -{% octicon cloud-download %} Download for Ubuntu -{% octicon beaker %} Nightly for Ubuntu +Download for Ubuntu +Nightly for Ubuntu * curl -LO {{ deb_stable }} * `sudo apt install -y ./{{ deb_stable_asset }}` * The package installs `/usr/bin/wezterm` and `/usr/share/applications/wezterm.desktop` * Configuration instructions can be [found here](configuration.html) -## {% octicon cloud-download height:24 %} Installing a pre-built package on Fedora +## Installing a pre-built package on Fedora The CI system builds an `.rpm` file on Fedora 31. -{% octicon cloud-download %} Download for Fedora -{% octicon beaker %} Nightly for Fedora +Download for Fedora +{Nightly for Fedora * curl -LO {{ fedora_stable }} * `sudo dnf install -y ./{{ fedora_stable_asset }}` * The package installs `/usr/bin/wezterm` and `/usr/share/applications/wezterm.desktop` * Configuration instructions can be [found here](configuration.html) -## {% octicon git-branch height:24 %} Installing from source +## Installing from source * Install `rustup` to get the `rust` compiler installed on your system. [Install rustup](https://www.rust-lang.org/en-US/install.html) diff --git a/docs/multiplexing.markdown b/docs/multiplexing.markdown index dd7df7635..5e970f612 100644 --- a/docs/multiplexing.markdown +++ b/docs/multiplexing.markdown @@ -1,7 +1,3 @@ ---- -title: Multiplexing ---- - **Notice:** *multiplexing is still a young feature and is evolving rapidly. Your feedback is welcomed!* diff --git a/docs/serial.markdown b/docs/serial.markdown index 93cf6abb3..8978da122 100644 --- a/docs/serial.markdown +++ b/docs/serial.markdown @@ -1,7 +1,3 @@ ---- -title: Serial Ports ---- - ## Serial Ports wezterm can also connect to serial ports as a client. This is useful diff --git a/docs/ssh.markdown b/docs/ssh.markdown index cbf208bc1..b54ccf4d0 100644 --- a/docs/ssh.markdown +++ b/docs/ssh.markdown @@ -1,7 +1,3 @@ ---- -title: SSH Connections ---- - ## SSH Connections wezterm uses libssh2 to provide an integrated SSH client. The diff --git a/docs/toc.markdown b/docs/toc.markdown deleted file mode 100644 index eea3a7f7c..000000000 --- a/docs/toc.markdown +++ /dev/null @@ -1,17 +0,0 @@ ---- -title: Full Table of Contents -layout: notoc ---- - -# Full Table of Contents - -
    - {% for page in site.html_pages %} - {% if page.url contains "toc.html" %} - {% else %} - {% assign p_url = page.url | absolute_url %} -
  • {{ page.title }}
    • - {% include toc.html baseurl=p_url sanitize=true html=page.content class="toc" %} - {% endif %} - {% endfor %} -