docs: upgrade to mdbook 0.4, enable link checking

Standardize on `thing.md` rather than `thing.markdown` to make it
easier to cross link.

.github/workflows/pages.yml

@@ -22,11 +22,12 @@ jobs:
         uses: actions/cache@v1
         with:
           path: ~/mdbook-bin
-          key: cargo-bin-mdbook
+          key: cargo-bin-mdbook-1
       - name: Install mdBook
         run: |
           mkdir -p ~/mdbook-bin
-          (test -x ~/mdbook-bin/mdbook || (cd && cargo install --vers "^0.3" mdbook && cp -p ~/.cargo/bin/mdbook ~/mdbook-bin))
+          (test -x ~/mdbook-bin/mdbook || (cd && cargo install --vers "^0.4" mdbook && cp -p ~/.cargo/bin/mdbook ~/mdbook-bin))
+          (test -x ~/mdbook-bin/mdbook-linkcheck || (cd && cargo install mdbook-linkcheck && cp -p ~/.cargo/bin/mdbook-linkcheck ~/mdbook-bin))
       - name: Build
         run: |
           source $HOME/.cargo/env
@@ -37,7 +38,7 @@ jobs:
         uses: crazy-max/ghaction-github-pages@v2
         with:
           target_branch: gh-pages
-          build_dir: gh_pages
+          build_dir: gh_pages/html
           keep_history: true
           allow_empty_commit: false
         env:

.gitignore

@@ -9,7 +9,6 @@
 /target/
 /gh_pages/
 /docs/SUMMARY.md
-/docs/installation.md
 /docs/install/*.md
 /docs/colorschemes/**/index.md
 /docs/config/lua/config/index.md

ci/build-docs.sh

@@ -8,8 +8,8 @@ mdbook build docs
 # mdBook can append js includes but it is too late to register syntax
 # highlighting extensions, so we apply brute force here
 
-mv gh_pages/book.js gh_pages/book.2
-cat docs/lua.js gh_pages/book.2 > gh_pages/book.js
-rm gh_pages/book.2
-cp assets/icon/terminal.png gh_pages/favicon.png
-cp assets/icon/wezterm-icon.svg gh_pages/favicon.svg
+mv gh_pages/html/book.js gh_pages/html/book.2
+cat docs/lua.js gh_pages/html/book.2 > gh_pages/html/book.js
+rm gh_pages/html/book.2
+cp assets/icon/terminal.png gh_pages/html/favicon.png
+cp assets/icon/wezterm-icon.svg gh_pages/html/favicon.svg

ci/generate-docs.py

@@ -109,7 +109,7 @@ return {{
 TOC = [
     Page(
         "wezterm",
-        "index.markdown",
+        "index.md",
         children=[
             Page(
                 "Install",
@@ -121,32 +121,32 @@ TOC = [
                     Page("Build from source", "install/source.md"),
                 ],
             ),
-            Page("Features", "features.markdown"),
-            Page("Change Log", "changelog.markdown"),
+            Page("Features", "features.md"),
+            Page("Change Log", "changelog.md"),
             Page(
                 "Configuration",
-                "config/files.markdown",
+                "config/files.md",
                 children=[
-                    Page("Launching Programs", "config/launch.markdown"),
-                    Page("Fonts", "config/fonts.markdown"),
-                    Page("Font Shaping", "config/font-shaping.markdown"),
-                    Page("Misc", "config/misc.markdown"),
-                    Page("Key & Mouse Binding", "config/keys.markdown"),
-                    Page("Colors & Appearance", "config/appearance.markdown"),
+                    Page("Launching Programs", "config/launch.md"),
+                    Page("Fonts", "config/fonts.md"),
+                    Page("Font Shaping", "config/font-shaping.md"),
+                    Page("Misc", "config/misc.md"),
+                    Page("Key & Mouse Binding", "config/keys.md"),
+                    Page("Colors & Appearance", "config/appearance.md"),
                 ],
             ),
-            Page("Scrollback", "scrollback.markdown"),
-            Page("Copy Mode", "copymode.markdown"),
-            Page("Hyperlinks", "hyperlinks.markdown"),
-            Page("Shell Integration", "shell-integration.markdown"),
-            Page("iTerm Image Protocol", "imgcat.markdown"),
-            Page("SSH", "ssh.markdown"),
-            Page("Serial Ports & Arduino", "serial.markdown"),
-            Page("Mulitplexing", "multiplexing.markdown"),
-            Page("Escape Sequences", "escape-sequences.markdown"),
-            Page("F.A.Q.", "faq.markdown"),
-            Page("Getting Help", "help.markdown"),
-            Page("Contributing", "contributing.markdown"),
+            Page("Scrollback", "scrollback.md"),
+            Page("Copy Mode", "copymode.md"),
+            Page("Hyperlinks", "hyperlinks.md"),
+            Page("Shell Integration", "shell-integration.md"),
+            Page("iTerm Image Protocol", "imgcat.md"),
+            Page("SSH", "ssh.md"),
+            Page("Serial Ports & Arduino", "serial.md"),
+            Page("Mulitplexing", "multiplexing.md"),
+            Page("Escape Sequences", "escape-sequences.md"),
+            Page("F.A.Q.", "faq.md"),
+            Page("Getting Help", "help.md"),
+            Page("Contributing", "contributing.md"),
             GenColorScheme("Color Schemes", "colorschemes"),
             Page(
                 "Lua Reference",

ci/subst-release-info.py

@@ -79,7 +79,7 @@ def load_release_info():
     build_subst(subst, "nightly", nightly)
     print(pretty(subst))
 
-    for name in ['installation', 'install/windows', 'install/macos', 'install/linux', 'install/source']:
+    for name in ['install/windows', 'install/macos', 'install/linux', 'install/source']:
         with open(f"docs/{name}.markdown", "r") as input:
             with open(f"docs/{name}.md", "w") as output:
                 for line in input:

docs/book.toml

@@ -12,3 +12,6 @@ additional-css = ["custom.css"]
 default-theme = "ayu"
 preferred-dark-theme = "ayu"
 git-repository-url = "https://github.com/wez/wezterm"
+
+[output.linkcheck]
+traverse-parent-directories = false

docs/config/launch.md

@@ -85,7 +85,7 @@ directory you can do so via the config, CLI, and when using
 
 Panes/Tabs/Windows created after the first will generally try to resolve the
 current working directory of the current Pane, preferring
-[a value set by OSC 7](../shell-integration.markdown) and falling back to
+[a value set by OSC 7](../shell-integration.md) and falling back to
 attempting to lookup the `cwd` of the current process group leader attached to a
 local Pane. If no `cwd` can be resolved, then the `default_cwd` will be used.
 If `default_cwd` is not specified, then the home directory of the user will be

docs/config/lua/config/default_cwd.md

@@ -11,7 +11,7 @@ Commands launched using [`SpawnCommand`](../SpawnCommand.md) will use the
 
 Panes/Tabs/Windows created after the first will generally try to resolve the
 current working directory of the current Pane, preferring
-[a value set by OSC 7](../../../shell-integration.markdown) and falling back to
+[a value set by OSC 7](../../../shell-integration.md) and falling back to
 attempting to lookup the `cwd` of the current process group leader attached to a
 local Pane. If no `cwd` can be resolved, then the `default_cwd` will be used.
 If `default_cwd` is not specified, then the home directory of the user will be

docs/config/lua/keyassignment/ShowLauncher.md

@@ -1,6 +1,6 @@
 # ShowLauncher
 
-Activate the [Launcher Menu](launch.html#the-launcher-menu)
+Activate the [Launcher Menu](../../launch.md#the-launcher-menu)
 in the current tab.
 
 ```lua

docs/escape-sequences.md

@@ -81,7 +81,7 @@ the action described below.
 | ^X |0x18|CAN |Cancel       |Ignored|
 | ^Y |0x19|EM  |End of Medium|Ignored|
 | ^Z |0x1A|SUB |Substitute   |Ignored|
-| ^[ |0x1B|ESC |Escape       |Introduces various escape sequences described below|
+| ^\[ |0x1B|ESC |Escape       |Introduces various escape sequences described below|
 | ^\\|0x1C|FS  |File Separator|Ignored|
 | ^] |0x1D|GS  |Group Separator|Ignored|
 | ^^ |0x1E|RS  |Record Separator|Ignored|
@@ -293,7 +293,7 @@ In the table below, `DCS` can be either the 7-bit representation (`ESC P`) or th
 |DCS $ q " p ST | [DECRQSS](https://vt100.net/docs/vt510-rm/DECRQSS.html) for [DECSCL](https://vt100.net/docs/vt510-rm/DECSCL.html) | Request Conformance Level; Reports the conformance level |
 |DCS $ q r ST   | [DECRQSS](https://vt100.net/docs/vt510-rm/DECRQSS.html) for [DECSTBM](https://vt100.net/docs/vt510-rm/DECSTBM.html) | Request top and bottom margin report; Reports the margins |
 |DCS $ q s ST   | [DECRQSS](https://vt100.net/docs/vt510-rm/DECRQSS.html) for [DECSLRM](https://vt100.net/docs/vt510-rm/DECSLRM.html) | Request left and right margin report; Reports the margins |
-|DCS [PARAMS] q [DATA] ST | Sixel Graphic Data | Decodes [Sixel graphic data](https://vt100.net/docs/vt3xx-gp/chapter14.html) and apply the image to the terminal model. Support is preliminary and incomplete; see [this issue](https://github.com/wez/wezterm/issues/217) for status. |
+|DCS \[PARAMS\] q \[DATA\] ST | Sixel Graphic Data | Decodes [Sixel graphic data](https://vt100.net/docs/vt3xx-gp/chapter14.html) and apply the image to the terminal model. Support is preliminary and incomplete; see [this issue](https://github.com/wez/wezterm/issues/217) for status. |
 |DCS 1000 q | tmux control mode | Bridges tmux into the WezTerm multiplexer.  Currently incomplete, see [this issue](https://github.com/wez/wezterm/issues/336) for status. |
 
 ### Operating System Command Sequences

docs/index.md

@@ -6,12 +6,12 @@
 ## Features
 
 * Runs on Linux, macOS and Windows 10
-* [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).
-* [Hyperlinks](hyperlinks.html)
+* [Hyperlinks](hyperlinks.md)
 * <a href="features.html">a full list of features can be found here</a>
 
-Looking for a [configuration reference?](config/files.html)
+Looking for a [configuration reference?](config/files.md)
 
 <img width="100%" height="100%" src="screenshots/two.png" alt="Screenshot">