Docs(mermaid,highlighting): Responsive diagrams, shared lexer

docs/AGENTS.md

@@ -93,8 +93,10 @@ Two mechanical conventions, separate from voice:
   renders monospace —
   the way that text reads as code inline; leave prose and concept nodes
   unstyled. Prefer top-to-bottom (`flowchart TD`); wide left-to-right
-  charts don't scale on narrow viewports. `docs/configuration/workspace-builders.md`
-  is the reference.
+  charts don't scale on narrow viewports. Add `:alt:`, `:name:`, and
+  `:responsive: fit` to every diagram; use `:responsive: preserve` only
+  when the wide artifact is intentional and should scroll instead of
+  shrinking. `docs/configuration/workspace-builders.md` is the reference.
 - **Internal API pages** document a module with an `{eval-rst}` block
   wrapping `.. automodule:: <module>` (with `:members:`), the way the
   existing `docs/internals/api/**` pages do. A bare `.. py:module::`

docs/about_tmux.md

@@ -43,6 +43,9 @@ inside the text dimension. Inside tmux you can:
 
 :::{mermaid}
 :caption: A session holds windows; each window holds one or more panes.
+:alt: tmux session containing windows and panes
+:name: tmux-session-window-pane-tree
+:responsive: fit
 
 flowchart TD
     session["session"] --> w1["window"]
@@ -104,6 +107,9 @@ tmux supports as many terminals as you want.
 
 :::{mermaid}
 :caption: Switch between the windows in a session.
+:alt: switching from one active tmux window to another
+:name: tmux-window-switching
+:responsive: fit
 
 flowchart TD
     w1["window 1 · sys (active)"] -->|"switch-window 2"| w2["window 2 · vim (active)"]
@@ -118,6 +124,9 @@ a sandwich, and re-(attach), all applications are still running!
 
 :::{mermaid}
 :caption: Detach, leave everything running, and reattach later.
+:alt: detaching from and reattaching to a running tmux session
+:name: tmux-detach-reattach-cycle
+:responsive: fit
 
 flowchart TD
     running["session running"] -->|"detach · Prefix d"| detached["screen detached — apps keep running"]

docs/cli/load.md

@@ -103,6 +103,9 @@ Or (a)ppend windows in the current active session?
 
 :::{mermaid}
 :caption: Loading from inside an existing tmux client.
+:alt: tmuxp load prompt choices inside an existing tmux client
+:name: tmuxp-load-inside-client
+:responsive: fit
 
 flowchart TD
     load["tmuxp load"]:::cmd --> q{"y / n / a ?"}

docs/conf.py

@@ -35,9 +35,12 @@
         "sphinx_autodoc_api_style",
         "aafig",
         "sphinx_gp_mermaid",
+        "sphinx_gp_highlighting",
         "tmux_layout",
         "sphinx_autodoc_argparse.exemplar",
     ],
+    gp_highlighting_inline_literals="safe",
+    gp_highlighting_inline_commands=["tmuxp"],
     # Route a plain ```mermaid fence to the mermaid directive (the colon and
     # brace forms route there already via colon_fence). Redundant once the
     # pinned gp-sphinx release auto-routes when sphinx_gp_mermaid is active;

docs/configuration/index.md

@@ -64,6 +64,9 @@ tmuxp will offer to assist when:
 
 :::{mermaid}
 :caption: A workspace file mirrors tmux's own hierarchy.
+:alt: tmuxp workspace file hierarchy from session to windows, panes, and shell commands
+:name: tmuxp-workspace-hierarchy
+:responsive: fit
 
 flowchart TD
     session["session_name"]:::cmd --> w1["window"]

docs/configuration/workspace-builders.md

@@ -16,6 +16,9 @@ fall back to the default.**
 
 :::{mermaid}
 :caption: How a workspace file becomes a live tmux session.
+:alt: tmuxp load reading workspace config through a workspace builder to attach a session
+:name: tmuxp-workspace-builder-flow
+:responsive: fit
 
 ---
 config:

docs/internals/architecture.md

@@ -7,17 +7,25 @@ modules:
 
 :::{mermaid}
 :caption: How each tmuxp subcommand reaches libtmux.
+:alt: tmuxp CLI subcommands reaching workspace modules and libtmux
+:name: tmuxp-command-architecture
+:responsive: fit
 
-flowchart LR
+flowchart TD
     cli["tmuxp CLI (argparse)"]
-    cli -->|load| loader["workspace.loader"]:::cmd
+    cli --> load["load"]:::cmd
+    load --> loader["workspace.loader"]:::cmd
     loader --> builder["workspace.builder"]:::cmd
     builder --> libtmux["libtmux"]:::cmd
-    cli -->|freeze| freezer["workspace.freezer"]:::cmd
+    cli --> freeze["freeze"]:::cmd
+    freeze --> freezer["workspace.freezer"]:::cmd
     freezer --> libtmux
-    cli -->|convert| reader["_internal.config_reader"]:::cmd
-    cli -->|shell| interactive["libtmux (interactive)"]
-    cli -->|"ls / search"| finders["workspace.finders"]:::cmd
+    cli --> convert["convert"]:::cmd
+    convert --> reader["_internal.config_reader"]:::cmd
+    cli --> shell["shell"]:::cmd
+    shell --> interactive["libtmux (interactive)"]
+    cli --> search["ls / search"]:::cmd
+    search --> finders["workspace.finders"]:::cmd
 :::
 
 ## Key Components

docs/topics/plugins.md

@@ -40,6 +40,9 @@ nothing. {ref}`tmuxp load <cli-load>` drives the lifecycle in a fixed order:
 
 :::{mermaid}
 :caption: When each plugin hook fires.
+:alt: tmuxp plugin hook order during tmuxp load
+:name: tmuxp-plugin-hook-order
+:responsive: fit
 
 flowchart TD
     load["tmuxp load"]:::cmd --> bwb["before_workspace_builder"]:::cmd
@@ -71,7 +74,7 @@ interface tmuxp provides, {class}`~tmuxp.plugin.TmuxpPlugin`.
 works just as well. You need only one project file, for whichever packaging tool
 you choose.
 
-```console
+```tree
 python_module
 ├── tmuxp_plugin_my_plugin_module
 │   ├── __init__.py

docs/topics/workflows.md

@@ -31,6 +31,9 @@ you like it, freeze it to capture the layout, then edit and replay it anywhere:
 
 :::{mermaid}
 :caption: Capture a session once, replay it anywhere.
+:alt: manual tmux session captured with tmuxp freeze and replayed with tmuxp load
+:name: tmuxp-freeze-load-workflow
+:responsive: fit
 
 flowchart TD
     arrange["arrange tmux by hand"] --> freeze["tmuxp freeze"]:::cmd