docs: switch doc build to Material for MkDocs

It's a more mature and actively developed toolset for technical writing, and looks nicer.
2024-10-05 18:58:52 +03:00 · 2023-03-15 19:22:51 -07:00 · 2023-03-15 19:22:51 -07:00 · 4770b38737
commit 4770b38737
parent 2bfb29f1be
40 changed files with 594 additions and 332 deletions
--- a/.github/workflows/pages.yml
+++ b/.github/workflows/pages.yml
@ -10,7 +10,6 @@ on:
      - "ci/generate-docs.py"
      - "ci/subst-release-info.py"
      - ".github/workflows/pages.yml"
-      - ".github/ISSUE_TEMPLATE/*"
  schedule:
    - cron: "50 * * * *"

@ -43,40 +42,33 @@ jobs:
          components: "rustfmt"
        env:
          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
-        run: |
-          (test -x ~/.cargo/bin/gelatyx || (cd && cargo install gelatyx --version "^0.2" --locked))
+        uses: baptiste0928/cargo-install@v1
+        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
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          source $HOME/.cargo/env
-          ./ci/build-docs.sh
+          CARDS=true ./ci/build-docs.sh
      - name: Upload artifact
        uses: actions/upload-pages-artifact@v1
        with:
-          path: gh_pages/html
+          path: gh_pages

  deploy:
    environment:
--- a/.gitignore
+++ b/.gitignore
@ -1,6 +1,10 @@
 .DS_Store
 dhat-heap.json
 /docs/_site
+/docs/favicon.png
+/docs/favicon.svg
+/docs/fonts/*
+/mkdocs.yml
 /PKGBUILD
 /WezTerm*.zip
 /WezTerm*.exe
@ -16,6 +20,8 @@ dhat-heap.json
 /docs/cli/cli/index.md
 /docs/recipes/index.md
 /docs/colorschemes/**/index.md
+/docs/colorschemes/scheme.css
+/docs/colorschemes/scheme.js
 /docs/config/lua/color/index.md
 /docs/config/lua/config/index.md
 /docs/config/lua/gui-events/index.md
--- a/ci/build-docs.sh
+++ b/ci/build-docs.sh
@ -32,10 +32,24 @@ function ghapi() {
 [[ -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/generate-docs.py || exit 1
-mdbook-mermaid install docs
-mdbook build docs

-rm gh_pages/html/README.markdown
-cp assets/fonts/Symbols-Nerd-Font-Mono.ttf gh_pages/html/fonts/
-cp assets/icon/terminal.png gh_pages/html/favicon.png
-cp "assets/icon/wezterm-icon.svg" gh_pages/html/favicon.svg
+mdbook-linkcheck --standalone docs
+
+# Adjust path to pick up pip-installed binaries
+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
--- a/ci/generate-docs.py
+++ b/ci/generate-docs.py
@ -14,12 +14,24 @@ class Page(object):
        self.filename = filename
        self.children = children or []

-    def render(self, output, depth=0):
+    def render(self, output, depth=0, mode="mdbook"):
        indent = "  " * depth
        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:
-            kid.render(output, depth + 1)
+            kid.render(output, depth + 1, mode)


 # autogenerate an index page from the contents of a directory
@ -30,8 +42,7 @@ class Gen(object):
        self.index = index
        self.extract_title = extract_title

-    def render(self, output, depth=0):
-        print(self.dirname)
+    def render(self, output, depth=0, mode="mdbook"):
        names = sorted(glob.glob(f"{self.dirname}/*.md"))
        children = []
        for filename in names:
@ -41,13 +52,13 @@ class Gen(object):

            if self.extract_title:
                with open(filename, "r") as f:
-                    title = f.readline().strip('#').strip()
+                    title = f.readline().strip("#").strip()

            children.append(Page(title, filename))

        index_filename = f"{self.dirname}/index.md"
        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:
            if self.index:
                idx.write(self.index)
@ -187,7 +198,7 @@ class GenColorScheme(object):
        self.dirname = dirname
        self.index = index

-    def render(self, output, depth=0):
+    def render(self, output, depth=0, mode="mdbook"):
        with open("colorschemes/data.json") as f:
            scheme_data = json.load(f)
        by_prefix = {}
@ -209,6 +220,34 @@ class GenColorScheme(object):
            else:
                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 = []
        for scheme_prefix in sorted(by_prefix.keys()):
            scheme_filename = f"{self.dirname}/{scheme_prefix}/index.md"
@ -216,6 +255,7 @@ class GenColorScheme(object):
            children.append(Page(scheme_prefix, scheme_filename))

            with open(scheme_filename, "w") as idx:
+                idents_to_load = []

                for scheme in by_prefix[scheme_prefix]:
                    title = scheme["name"]
@ -223,26 +263,11 @@ class GenColorScheme(object):

                    data = screen_shot_table(scheme)
                    ident = scheme["ident"]
+                    idents_to_load.append(ident)

                    idx.write(
                        f"""
 <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:
                                    alias_list.append(f"[{a}]({alias_link})")
                                else:
-                                    alias_list.append(f"`{a}` (but that name isn't used here)")
-                            aliases = ', '.join(alias_list)
+                                    alias_list.append(
+                                        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")
                        else:
                            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(
@ -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_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:
            idx.write(f"{len(scheme_data)} Color schemes listed by first letter\n\n")
@ -300,41 +339,10 @@ return {{

 TOC = [
    Page(
-        "wezterm",
+        "WezTerm",
        "index.md",
        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("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("Quick Select Mode", "quickselect.md"),
            Page("Copy Mode", "copymode.md"),
@ -344,100 +352,153 @@ TOC = [
            Page("SSH", "ssh.md"),
            Page("Serial Ports & Arduino", "serial.md"),
            Page("Multiplexing", "multiplexing.md"),
-            Page("Escape Sequences", "escape-sequences.md"),
-            Page("F.A.Q.", "faq.md"),
-            Page("Getting Help", "help.md"),
-            Page("Contributing", "contributing.md"),
-            Page("What is a Terminal?", "what-is-a-terminal.md"),
-            Page(
-                "CLI Reference",
-                "cli/general.md",
-                children=[
-                    Gen("cli", "cli/cli"),
-                    Page("show-keys", "cli/show-keys.md"),
-                ],
+        ],
+    ),
+    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(
+        "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(
-                "Lua Reference",
-                "config/lua/general.md",
-                children=[
-                    Gen(
-                        "module: wezterm",
-                        "config/lua/wezterm",
-                    ),
-                    Gen(
-                        "module: wezterm.color",
-                        "config/lua/wezterm.color",
-                    ),
-                    Gen(
-                        "module: wezterm.gui",
-                        "config/lua/wezterm.gui",
-                    ),
-                    Gen(
-                        "module: wezterm.mux",
-                        "config/lua/wezterm.mux",
-                    ),
-                    Gen(
-                        "module: wezterm.procinfo",
-                        "config/lua/wezterm.procinfo",
-                    ),
-                    Gen(
-                        "module: wezterm.time",
-                        "config/lua/wezterm.time",
-                    ),
-                    Gen(
-                        "struct: Config",
-                        "config/lua/config",
-                    ),
-                    Gen(
-                        "enum: KeyAssignment",
-                        "config/lua/keyassignment",
-                    ),
-                    Gen(
-                        "enum: CopyModeAssignment",
-                        "config/lua/keyassignment/CopyMode",
-                    ),
-                    Gen("object: Color", "config/lua/color"),
-                    Page("object: ExecDomain", "config/lua/ExecDomain.md"),
-                    Page("object: LocalProcessInfo", "config/lua/LocalProcessInfo.md"),
-                    Gen("object: MuxDomain", "config/lua/MuxDomain"),
-                    Gen("object: MuxWindow", "config/lua/mux-window"),
-                    Gen("object: MuxTab", "config/lua/MuxTab"),
-                    Page("object: PaneInformation", "config/lua/PaneInformation.md"),
-                    Page("object: TabInformation", "config/lua/TabInformation.md"),
-                    Page("object: SshDomain", "config/lua/SshDomain.md"),
-                    Page("object: SpawnCommand", "config/lua/SpawnCommand.md"),
-                    Gen("object: Time", "config/lua/wezterm.time/Time"),
-                    Page("object: TlsDomainClient", "config/lua/TlsDomainClient.md"),
-                    Page("object: TlsDomainServer", "config/lua/TlsDomainServer.md"),
-                    Gen(
-                        "object: Pane",
-                        "config/lua/pane",
-                    ),
-                    Gen(
-                        "object: Window",
-                        "config/lua/window",
-                    ),
-                    Page("object: WslDomain", "config/lua/WslDomain.md"),
-                    Gen(
-                        "events: Gui",
-                        "config/lua/gui-events",
-                    ),
-                    Gen(
-                        "events: Multiplexer",
-                        "config/lua/mux-events",
-                    ),
-                    Gen(
-                        "events: Window",
-                        "config/lua/window-events",
-                    ),
-                ],
+            Gen(
+                "module: wezterm.color",
+                "config/lua/wezterm.color",
+            ),
+            Gen(
+                "module: wezterm.gui",
+                "config/lua/wezterm.gui",
+            ),
+            Gen(
+                "module: wezterm.mux",
+                "config/lua/wezterm.mux",
+            ),
+            Gen(
+                "module: wezterm.procinfo",
+                "config/lua/wezterm.procinfo",
+            ),
+            Gen(
+                "module: wezterm.time",
+                "config/lua/wezterm.time",
+            ),
+            Gen(
+                "struct: Config",
+                "config/lua/config",
+            ),
+            Gen(
+                "enum: KeyAssignment",
+                "config/lua/keyassignment",
+            ),
+            Gen(
+                "enum: CopyModeAssignment",
+                "config/lua/keyassignment/CopyMode",
+            ),
+            Gen("object: Color", "config/lua/color"),
+            Page("object: ExecDomain", "config/lua/ExecDomain.md"),
+            Page("object: LocalProcessInfo", "config/lua/LocalProcessInfo.md"),
+            Gen("object: MuxDomain", "config/lua/MuxDomain"),
+            Gen("object: MuxWindow", "config/lua/mux-window"),
+            Gen("object: MuxTab", "config/lua/MuxTab"),
+            Page("object: PaneInformation", "config/lua/PaneInformation.md"),
+            Page("object: TabInformation", "config/lua/TabInformation.md"),
+            Page("object: SshDomain", "config/lua/SshDomain.md"),
+            Page("object: SpawnCommand", "config/lua/SpawnCommand.md"),
+            Gen("object: Time", "config/lua/wezterm.time/Time"),
+            Page("object: TlsDomainClient", "config/lua/TlsDomainClient.md"),
+            Page("object: TlsDomainServer", "config/lua/TlsDomainServer.md"),
+            Gen(
+                "object: Pane",
+                "config/lua/pane",
+            ),
+            Gen(
+                "object: Window",
+                "config/lua/window",
+            ),
+            Page("object: WslDomain", "config/lua/WslDomain.md"),
+            Gen(
+                "events: Gui",
+                "config/lua/gui-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")
-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:
-        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")
--- a/docs/changelog.md
+++ b/docs/changelog.md
@ -1,3 +1,9 @@
+---
+hide:
+    - navigation
+toc_depth: 3
+---
+
 ## Changes

 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).
 * 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)
 * [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)
@ -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: 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)
-* 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: 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)!
@ -994,7 +1000,7 @@ As features stabilize some brief notes about them will accumulate here.
 ### 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: 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 [ResetFontAndWindowSize](config/lua/keyassignment/ResetFontAndWindowSize.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)
 * 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 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)
 * 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)
@ -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)
 * 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)
-* 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: [default_cwd](config/lua/config/default_cwd.html) to specify an alternative current working directory. 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.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.
 * 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.
@ -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.
 * 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
-  [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
  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
@ -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 can suppress this behavior if you wish by setting
  `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
-  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.

 ### 20200517-122836-92c201c6
@ -1325,7 +1331,7 @@ As features stabilize some brief notes about them will accumulate here.
 ### 20200503-171512-b13ef15f

 * 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 missing icon when running under X11 and Wayland
 * Wayland client-side-decorations improved and now also render window title
--- a/docs/config/appearance.md
+++ b/docs/config/appearance.md
@ -259,7 +259,7 @@ $ for scheme in *.sh ; do ; echo $scheme ; \
   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

@ -450,7 +450,7 @@ reduce it by half, and 2.0 will double the value.

 ## 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*

@ -505,7 +505,7 @@ behavior and more, take a look at the more power

 *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)
 for configuration information on gradients.
--- a/docs/config/launch.md
+++ b/docs/config/launch.md
@ -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
 menu when running on Windows:
--- a/docs/config/lua/config/color_schemes.md
+++ b/docs/config/lua/config/color_schemes.md
@ -2,4 +2,4 @@

 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)
--- a/docs/config/lua/config/default_prog.md
+++ b/docs/config/lua/config/default_prog.md
@ -16,4 +16,4 @@ return {
 is the command to run and the rest of the elements are passed
 as the positional arguments to that command.

-See also: [Launching Programs](../../launch.html)
+See also: [Launching Programs](../../launch.md)
--- a/docs/config/lua/config/foreground_text_hsb.md
+++ b/docs/config/lua/config/foreground_text_hsb.md
@ -33,11 +33,7 @@ return {
 }
 ```

-<img src="../../../screenshots/foreground-text-hsb-1-1-1.png"
-     alt="demonstrating the appearance of the default value">
-<img src="../../../screenshots/foreground-text-hsb-1-1.5-1.png"
-     alt="demonstrating setting saturating to 1.5">
-<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">
+![demonstrating the appearance of the default value](../../../screenshots/foreground-text-hsb-1-1-1.png)
+![demonstrating setting saturating to 1.5](../../../screenshots/foreground-text-hsb-1-1.5-1.png)
+![demonstrating setting brightness to 1.5](../../../screenshots/foreground-text-hsb-1-1-1.5.png)
+![demonstrating setting hue to 1.5](../../../screenshots/foreground-text-hsb-1.5-1-1.png)
--- a/docs/config/lua/config/harfbuzz_features.md
+++ b/docs/config/lua/config/harfbuzz_features.md
@ -3,6 +3,6 @@
 When `font_shaper = "Harfbuzz"`, this setting affects how font shaping
 takes place.

-See [Font Shaping](../../font-shaping.html) for more information
+See [Font Shaping](../../font-shaping.md) for more information
 and examples.

--- a/docs/config/lua/config/set_environment_variables.md
+++ b/docs/config/lua/config/set_environment_variables.md
@ -7,4 +7,4 @@ running program on any Operating System.

 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)
--- a/docs/config/lua/config/tab_bar_style.md
+++ b/docs/config/lua/config/tab_bar_style.md
@ -15,7 +15,7 @@ have been removed and replaced by the more flexible
 *Since: 20210314-114017-04b7cedd*

 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.

 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:

-<img width="100%" height="100%" src="../../../screenshots/wezterm-tab-edge-styled.png"
-  alt="Demonstrating setting the styling of the left and right tab edges">
+![Demonstrating setting the styling of the left and right tab edges](../../../screenshots/wezterm-tab-edge-styled.png)

 ```lua
 local wezterm = require 'wezterm'
--- a/docs/config/lua/config/unix_domains.md
+++ b/docs/config/lua/config/unix_domains.md
@ -3,4 +3,4 @@
 Defines a list of multiplexer domains for both the multiplexer
 server and multiplexer client.

-[Read more about multiplexing](../../../multiplexing.html#unix-domains)
+[Read more about multiplexing](../../../multiplexing.md#unix-domains)
--- a/docs/config/lua/config/window_background_gradient.md
+++ b/docs/config/lua/config/window_background_gradient.md
@ -63,7 +63,7 @@ return {
 }
 ```

-<img src="../../../screenshots/vertical-gradient.png">
+![Vertical Gradient](../../../screenshots/vertical-gradient.png)

 Gradients are implemented using the `colorgrad` crate.
 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:

@ -131,7 +131,7 @@ return {
 }
 ```

-<img src="../../../screenshots/radial-gradient.png">
+![Radial Gradient](../../../screenshots/radial-gradient.png)

 ## Presets

--- a/docs/config/lua/keyassignment/ActivateCommandPalette.md
+++ b/docs/config/lua/keyassignment/ActivateCommandPalette.md
@ -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
 palette.

-<img src="../../../screenshots/command-palette.png">
+![Command Palette](../../../screenshots/command-palette.png)

 ### Key Assignments

--- a/docs/config/lua/keyassignment/ActivateCopyMode.md
+++ b/docs/config/lua/keyassignment/ActivateCopyMode.md
@ -12,5 +12,5 @@ return {
 }
 ```

-[Learn more about copy mode](../../../copymode.html)
+[Learn more about copy mode](../../../copymode.md)

--- a/docs/config/lua/keyassignment/PaneSelect.md
+++ b/docs/config/lua/keyassignment/PaneSelect.md
@ -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
 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.
 Pressing `Escape` or `CTRL-g` will exit pane selection mode without taking any
--- a/docs/config/lua/keyassignment/Search.md
+++ b/docs/config/lua/keyassignment/Search.md
@ -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*

--- a/docs/config/lua/wezterm/strftime_utc.md
+++ b/docs/config/lua/wezterm/strftime_utc.md
@ -12,4 +12,4 @@ local date_and_time = wezterm.strftime_utc '%Y-%m-%d %H:%M:%S'
 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).
--- a/docs/config/lua/window/set_right_status.md
+++ b/docs/config/lua/window/set_right_status.md
@ -14,8 +14,7 @@ the string.

 Here's a basic example that displays the time in the status area:

-<img width="100%" height="100%" src="../../../screenshots/wezterm-status-date.png"
-  alt="Demonstrating setting the right status area to the current date and time">
+![Demonstrating setting the right status area to the current date and time](../../../screenshots/wezterm-status-date.png)

 ```lua
 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
 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
-[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"
-  alt="Demonstrating setting the right status area with powerline styling">
+![Demonstrating setting the right status area with powerline styling](../../../screenshots/wezterm-status-powerline.png)

 ```lua
 wezterm.on('update-right-status', function(window, pane)
--- a/docs/contributing.md
+++ b/docs/contributing.md
@ -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)
 * [GitHub Discussions](https://github.com/wez/wezterm/discussions)
-* [Realtime conversation with wez on Element.io/Gitter](help.html)
-* [Building from Source](install/source.html)
+* [Realtime conversation with wez on Element.io/Gitter](help.md)
+* [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)

 I like to think that I have an open mind and I try to be open to ideas,
--- a/docs/copymode.md
+++ b/docs/copymode.md
@ -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
 `wezterm show-keys --lua --key-table copy_mode`.

-{{#include examples/default-copy-mode-key-table.markdown}}
+{% include "examples/default-copy-mode-key-table.markdown" %}
--- a/docs/escape-sequences.md
+++ b/docs/escape-sequences.md
@ -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.

 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
 should be rendered from your fonts; it is at this stage that emoji and ligatures are
 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\\` |
 |5  |Change/Query Special Color Number | 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) ||
-|8  |Set Hyperlink | [See Explicit Hyperlinks](hyperlinks.html#explicit-hyperlinks) | |
+|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.md#explicit-hyperlinks) | |
 |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"` |
 |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. |
 |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 | |
-|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"` |
-|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 Window Title (Sun) | Same as OSC 2 | `\x1b]lwindow-title\x1b\\` |

--- a/docs/faq.md
+++ b/docs/faq.md
@ -123,13 +123,13 @@ issue.

 ### 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
 one [ligature](https://en.wikipedia.org/wiki/Ligature_(writing)). You may be
 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
-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.

 ## 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
 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
 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
 sequences.  If you're missing this feature in your WSL instance, you will need
 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.

 ## I use Powershell for my shell, and I have problems with cursor keys in other apps
--- a/docs/features.md
+++ b/docs/features.md
@ -1,22 +1,22 @@
 ## Available Features

 * 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)
-* <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)
-* [Searchable Scrollback](scrollback.html) (use mouse wheel and `Shift-PageUp` and `Shift PageDown` to navigate, Ctrl-Shift-F to activate search mode)
+* [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.md#colors).
+* [Hyperlinks](hyperlinks.md)
+* [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!)
 * 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)
-* 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`)
 * Splits/Panes (Split horizontally/vertically: `Ctrl-Shift-Alt-%` and `Ctrl-Shift-Alt-"`, move between panes: `Ctrl-Shift-ArrowKey`)
 * Tabs (Hotkey: `Super-T`, next/prev: `Super-Shift-[` and `Super-Shift-]`, go-to: `Super-[1-9]`)
  <video width="80%" controls src="screenshots/wezterm-tabs.mp4" loop></video>
-* [SSH client with native tabs](ssh.html)
-* [Connect to serial ports for embedded/Arduino work](serial.html)
+* [SSH client with native tabs](ssh.md)
+* [Connect to serial ports for embedded/Arduino work](serial.md)
 * Connect to a local multiplexer server over unix domain sockets
 * 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
 * Sixel graphics support (experimental: starting in `20200620-160318-e00b076c`)
--- a/docs/imgcat.md
+++ b/docs/imgcat.md
@ -7,11 +7,11 @@ just a protocol, wezterm's `imgcat` also renders images in iTerm2.

 To render an image inline in your terminal:

-```
+```console
 $ 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
--- a/docs/index.md
+++ b/docs/index.md
@ -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>*

-<a class="btn" href="installation.html">Download</a>
+<a class="btn" href="installation.md">Download</a>

 ## Features

 * 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)
-* <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)
-* <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)

 **These docs are searchable: press `S` or click on the magnifying glass icon
 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*

--- a/docs/install/linux.markdown
+++ b/docs/install/linux.markdown
@ -11,20 +11,20 @@ To install using the command line:

 First, [setup flatpak on your system](https://flatpak.org/setup/), then:

-```bash
-flatpak install flathub org.wezfurlong.wezterm
+```console
+$ flatpak install flathub org.wezfurlong.wezterm
 ```

 and then run:

-```bash
-flatpak run org.wezfurlong.wezterm
+```console
+$ flatpak run org.wezfurlong.wezterm
 ```

 You may wish to define an alias for convenience:

-```bash
-alias wezterm='flatpak run org.wezfurlong.wezterm'
+```console
+$ alias wezterm='flatpak run org.wezfurlong.wezterm'
 ```

 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!

-<a href="{{ ubuntu18_AppImage_stable }}" class="btn">AppImage</a>
-<a href="{{ ubuntu18_AppImage_nightly }}" class="btn">Nightly AppImage</a>
+[AppImage :material-tray-arrow-down:]({{ ubuntu18_AppImage_stable }}){ .md-button }
+[Nightly AppImage :material-tray-arrow-down:]({{ ubuntu18_AppImage_nightly }}){ .md-button }

-```bash
-curl -LO {{ ubuntu18_AppImage_stable }}
-chmod +x {{ ubuntu18_AppImage_stable_asset }}
+```console
+$ curl -LO {{ ubuntu18_AppImage_stable }}
+$ chmod +x {{ ubuntu18_AppImage_stable_asset }}
 ```

 You may then execute the appimage directly to launch wezterm, with no
 specific installation steps required:

-```bash
-./{{ ubuntu18_AppImage_stable_asset }}
+```console
+$ ./{{ ubuntu18_AppImage_stable_asset }}
 ```

 That said, you may wish to make it a bit more convenient:

-```bash
-mkdir ~/bin
-mv ./{{ ubuntu18_AppImage_stable_asset }} ~/bin/wezterm
-~/bin/wezterm
+```console
+$ mkdir ~/bin
+$ mv ./{{ ubuntu18_AppImage_stable_asset }} ~/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

@ -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
 shows how to install the Ubuntu 20 package:

-```bash
-curl -LO {{ ubuntu20_deb_stable }}
-sudo apt install -y ./{{ ubuntu20_deb_stable_asset }}
+```console
+$ curl -LO {{ ubuntu20_deb_stable }}
+$ sudo apt install -y ./{{ ubuntu20_deb_stable_asset }}
 ```

 * 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

@ -121,22 +121,22 @@ on most Linux systems.
 To download and install from the CLI you can use something like this, which
 shows how to install the Fedora 35 package:

-```bash
-sudo dnf install -y {{ fedora35_rpm_stable }}
+```console
+$ sudo dnf install -y {{ fedora35_rpm_stable }}
 ```

 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
 it as root user with

-```bash
-zypper addrepo https://download.opensuse.org/repositories/openSUSE:Factory/standard/openSUSE:Factory.repo
-zypper refresh
-zypper install wezterm
+```console
+$ zypper addrepo https://download.opensuse.org/repositories/openSUSE:Factory/standard/openSUSE:Factory.repo
+$ zypper refresh
+$ zypper install wezterm
 ```

 * 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

@ -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
 wezterm from our tap:

-```bash
+```console
 $ brew tap wez/wezterm-linuxbrew
 $ brew install wezterm
 ```

 If you'd like to use a nightly build you can perform a head install:

-```bash
+```console
 $ brew install --HEAD wezterm
 ```

 to upgrade to a newer nightly, it is simplest to remove then
 install:

-```bash
+```console
 $ brew rm 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
 are built for Ubuntu but provided in a tarball.

-<a href="{{ linux_raw_bin_stable }}" class="btn">Download raw Linux binaries</a>
-<a href="{{ linux_raw_bin_nightly }}" class="btn">Nightly raw Linux binaries</a>
+[Raw Linux Binary :material-tray-arrow-down:]({{ linux_raw_bin_stable }}){ .md-button }
+[Nightly Raw Linux Binary :material-tray-arrow-down:]({{ linux_raw_bin_nightly }}){ .md-button }


--- a/docs/install/macos.markdown
+++ b/docs/install/macos.markdown
@ -7,8 +7,9 @@ been tested.
 Starting with version 20210203-095643-70a364eb, WezTerm is a Universal binary
 with support for both Apple Silicon and Intel hardware.

-<a href="{{ macos_zip_stable }}" class="btn">Download for macOS</a>
-<a href="{{ macos_zip_nightly }}" class="btn">Nightly for macOS</a>
+[:simple-apple: Download for macOS :material-tray-arrow-down:]({{ macos_zip_stable }}){ .md-button }
+[:simple-apple: Nightly for macOS :material-tray-arrow-down:]({{ macos_zip_nightly }}){ .md-button }
+
 1. Download <a href="{{ macos_zip_stable }}">Release</a>
 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
@ -19,26 +20,26 @@ with support for both Apple Silicon and Intel hardware.
 PATH="$PATH:/Applications/WezTerm.app/Contents/MacOS"
 export PATH
 ```
-5. Configuration instructions can be [found here](../config/files.html)
+5. Configuration instructions can be [found here](../config/files.md)

 ## Homebrew

 WezTerm is available for [brew](https://brew.sh/) users in a tap:

-```bash
+```console
 $ brew tap wez/wezterm
 $ brew install --cask wez/wezterm/wezterm
 ```

 If you'd like to use a nightly build:

-```bash
+```console
 $ brew install --cask wez/wezterm/wezterm-nightly
 ```

 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
 ```

@ -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):

-```bash
+```console
 $ sudo port selfupdate
 $ sudo port install wezterm
 ```
--- a/docs/install/source.markdown
+++ b/docs/install/source.markdown
@ -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
 download a smaller source tarball using these steps:

-```bash
-curl https://sh.rustup.rs -sSf | sh -s
-curl -LO {{ src_stable }}
-tar -xzf {{ src_stable_asset }}
-cd {{ src_stable_dir }}
-./get-deps
-cargo build --release
-cargo run --release --bin wezterm -- start
+```console
+$ curl https://sh.rustup.rs -sSf | sh -s
+$ curl -LO {{ src_stable }}
+$ tar -xzf {{ src_stable_asset }}
+$ cd {{ src_stable_dir }}
+$ ./get-deps
+$ cargo build --release
+$ cargo run --release --bin wezterm -- start
 ```

 Alternatively, use the full git repo:

-```bash
-curl https://sh.rustup.rs -sSf | sh -s
-git clone --depth=1 --branch=main --recursive https://github.com/wez/wezterm.git
-cd wezterm
-git submodule update --init --recursive
-./get-deps
-cargo build --release
-cargo run --release --bin wezterm -- start
+```console
+$ curl https://sh.rustup.rs -sSf | sh -s
+$ git clone --depth=1 --branch=main --recursive https://github.com/wez/wezterm.git
+$ cd wezterm
+$ git submodule update --init --recursive
+$ ./get-deps
+$ cargo build --release
+$ cargo run --release --bin wezterm -- start
 ```

 **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
 Wayland support by changing the `build` invocation:

-```bash
-cargo build --release --no-default-features vendored-fonts
+```console
+$ cargo build --release --no-default-features vendored-fonts
 ```

 Building without X11 is not supported.
--- a/docs/install/windows.markdown
+++ b/docs/install/windows.markdown
@ -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
 yourself (no special privileges required).

-<a href="{{ windows_exe_stable }}" class="btn">Windows (setup.exe)</a>
-<a href="{{ windows_exe_nightly }}" class="btn">Nightly Windows (setup.exe)</a>
+[:simple-windows: Windows (setup.exe) :material-tray-arrow-down:]({{ windows_exe_stable }}){ .md-button }
+[: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
 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)
 to configure/script the installation process.

-<a href="{{ windows_zip_stable }}" class="btn">Windows (zip)</a>
-<a href="{{ windows_zip_nightly }}" class="btn">Nightly Windows (zip)</a>
+[:simple-windows: Windows (zip) :material-tray-arrow-down:]({{ windows_zip_stable }}){ .md-button }
+[: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
 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>
 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

@ -39,14 +39,14 @@ that is available from the Microsoft Store.

 Once you have `winget`, you can install wezterm like so:

-```bash
-winget install wez.wezterm
+```console
+$ winget install wez.wezterm
 ```

 and to later upgrade it:

-```bash
-winget upgrade wez.wezterm
+```console
+$ winget upgrade wez.wezterm
 ```

 ### 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
 scoop itself can be installed like so:

-```bash
-scoop bucket add extras
-scoop install wezterm
+```console
+$ scoop bucket add extras
+$ scoop install wezterm
 ```

 ### 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
 so:

-```bash
-choco install wezterm -y
+```console
+$ choco install wezterm -y
 ```
--- a/docs/javascript/fix-codeblock-console-copy-button.js
+++ b/docs/javascript/fix-codeblock-console-copy-button.js
@ -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;
+}
--- a/docs/mkdocs-base.yml
+++ b/docs/mkdocs-base.yml
@ -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
--- a/docs/multiplexing.md
+++ b/docs/multiplexing.md
@ -22,7 +22,7 @@ the domain of the current tab, or a specific numbered domain.

 ## 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
 of a multiplexing session that uses ssh as a channel*

--- a/docs/overrides/partials/toc-item.html
+++ b/docs/overrides/partials/toc-item.html
@ -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 %}
--- a/docs/quickselect.md
+++ b/docs/quickselect.md
@ -29,4 +29,4 @@ text, and cancel quick select mod.

 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)
--- a/docs/scrollback.md
+++ b/docs/scrollback.md
@ -9,7 +9,7 @@ down.

 This section describes working with the scrollback and discusses some
 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

@ -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

@ -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
 `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)).

@ -143,5 +143,5 @@ With that in your config you can now:

 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.
--- a/docs/ssh.md
+++ b/docs/ssh.md
@ -21,7 +21,7 @@ create.
 SSH sessions created in this way are non-persistent and all associated
 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
 and preserves your tabs.

--- a/docs/style.css
+++ b/docs/style.css
@ -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;
+}
+