tmux-python · tony · Jan 25, 2026 · Jan 25, 2026 · Jan 25, 2026 · Jan 25, 2026
diff --git a/CHANGES b/CHANGES
@@ -35,6 +35,17 @@ $ pipx install --suffix=@next 'tmuxp' --pip-args '\--pre' --force
 _Notes on the upcoming release will go here._
 <!-- END PLACEHOLDER - ADD NEW CHANGELOG ENTRIES BELOW THIS LINE -->
 
+### Documentation
+
+#### Linkable CLI arguments and options (#1010)
+
+CLI documentation now supports direct linking to specific arguments:
+
+- **Linkable options**: Each `--option` and positional argument has a permanent URL anchor (e.g., `cli/load.html#-d`)
+- **Headerlinks**: Hover over any argument to reveal a ¶ link for easy sharing
+- **Visual styling**: Argument names displayed with syntax-highlighted backgrounds for better readability
+- **Default value badges**: Default values shown as styled inline code (e.g., `auto`)
+
 ## tmuxp 1.64.0 (2026-01-24)
 
 ### Documentation

diff --git a/docs/_ext/sphinx_argparse_neo/nodes.py b/docs/_ext/sphinx_argparse_neo/nodes.py
@@ -26,6 +26,48 @@
 from sphinx_argparse_neo.utils import strip_ansi  # noqa: E402
 
 
+def _generate_argument_id(names: list[str], id_prefix: str = "") -> str:
+    """Generate unique ID for an argument based on its names.
+
+    Creates a slug-style ID suitable for HTML anchors by:
+    1. Stripping leading dashes from option names
+    2. Joining multiple names with hyphens
+    3. Prepending optional prefix for namespace isolation
+
+    Parameters
+    ----------
+    names : list[str]
+        List of argument names (e.g., ["-L", "--socket-name"]).
+    id_prefix : str
+        Optional prefix for uniqueness (e.g., "shell" -> "shell-L-socket-name").
+
+    Returns
+    -------
+    str
+        A slug-style ID suitable for HTML anchors.
+
+    Examples
+    --------
+    >>> _generate_argument_id(["-L"])
+    'L'
+    >>> _generate_argument_id(["--help"])
+    'help'
+    >>> _generate_argument_id(["-v", "--verbose"])
+    'v-verbose'
+    >>> _generate_argument_id(["-L"], "shell")
+    'shell-L'
+    >>> _generate_argument_id(["filename"])
+    'filename'
+    >>> _generate_argument_id([])
+    ''
+    """
+    clean_names = [name.lstrip("-") for name in names if name.lstrip("-")]
+    if not clean_names:
+        return ""
+    name_part = "-".join(clean_names)
+    return f"{id_prefix}-{name_part}" if id_prefix else name_part
+
+
 def _token_to_css_class(token_type: t.Any) -> str:
     """Map a Pygments token type to its CSS class abbreviation.
 
@@ -419,6 +461,9 @@ def visit_argparse_argument_html(
     - Positional arguments get class 'nl' (Name.Label)
     - Metavars get class 'nv' (Name.Variable)
 
+    The argument is wrapped in a container div with a unique ID for linking.
+    A headerlink anchor (¶) is added for direct navigation.
+
     Parameters
     ----------
     self : HTML5Translator
@@ -428,11 +473,28 @@ def visit_argparse_argument_html(
     """
     names: list[str] = node.get("names", [])
     metavar = node.get("metavar")
+    id_prefix: str = node.get("id_prefix", "")
+
+    # Generate unique ID for this argument
+    arg_id = _generate_argument_id(names, id_prefix)
+
+    # Open wrapper div with ID for linking
+    if arg_id:
+        self.body.append(f'<div class="argparse-argument-wrapper" id="{arg_id}">\n')
+    else:
+        self.body.append('<div class="argparse-argument-wrapper">\n')
 
     # Build the argument signature with syntax highlighting
     highlighted_sig = _highlight_argument_names(names, metavar, self.encode)
 
-    self.body.append(f'<dt class="argparse-argument-name">{highlighted_sig}</dt>\n')
+    # Add headerlink anchor inside dt for navigation
+    headerlink = ""
+    if arg_id:
+        headerlink = f'<a class="headerlink" href="#{arg_id}">¶</a>'
+
+    self.body.append(
+        f'<dt class="argparse-argument-name">{highlighted_sig}{headerlink}</dt>\n'
+    )
     self.body.append('<dd class="argparse-argument-help">')
 
     # Add help text
@@ -447,6 +509,7 @@ def depart_argparse_argument_html(
     """Depart argparse_argument node - close argument entry.
 
     Adds default, choices, and type information if present.
+    Default values are wrapped in ``<span class="nv">`` for styled display.
 
     Parameters
     ----------
@@ -460,7 +523,8 @@ def depart_argparse_argument_html(
 
     default = node.get("default_string")
     if default is not None:
-        metadata.append(f"Default: {self.encode(default)}")
+        # Wrap default value in nv span for yellow/italic styling
+        metadata.append(f'Default: <span class="nv">{self.encode(default)}</span>')
 
     choices = node.get("choices")
     if choices:
@@ -480,6 +544,8 @@ def depart_argparse_argument_html(
         self.body.append(f'<p class="argparse-argument-meta">{meta_str}</p>')
 
     self.body.append("</dd>\n")
+    # Close wrapper div
+    self.body.append("</div>\n")
 
 
 def visit_argparse_subcommands_html(

diff --git a/docs/_ext/sphinx_argparse_neo/renderer.py b/docs/_ext/sphinx_argparse_neo/renderer.py
@@ -358,13 +358,18 @@ def render_group_section(
         section += nodes.title(title, title)
 
         # Create the styled group container (with empty title - section provides it)
-        group_node = self.render_group(group, include_title=False)
+        # Pass id_prefix to render_group so arguments get unique IDs
+        group_node = self.render_group(group, include_title=False, id_prefix=id_prefix)
         section += group_node
 
         return section
 
     def render_group(
-        self, group: ArgumentGroup, include_title: bool = True
+        self,
+        group: ArgumentGroup,
+        include_title: bool = True,
+        *,
+        id_prefix: str = "",
     ) -> argparse_group:
         """Render an argument group.
 
@@ -376,6 +381,10 @@ def render_group(
             Whether to include the title in the group node. When False,
             the title is assumed to come from a parent section node.
             Default is True for backwards compatibility.
+        id_prefix : str
+            Optional prefix for argument IDs (e.g., "shell" -> "shell-h").
+            Used to ensure unique IDs when multiple argparse directives exist
+            on the same page.
 
         Returns
         -------
@@ -397,23 +406,29 @@ def render_group(
 
         # Add individual arguments
         for arg in group.arguments:
-            arg_node = self.render_argument(arg)
+            arg_node = self.render_argument(arg, id_prefix=id_prefix)
             group_node.append(arg_node)
 
         # Add mutually exclusive groups
         for mutex in group.mutually_exclusive:
-            mutex_nodes = self.render_mutex_group(mutex)
+            mutex_nodes = self.render_mutex_group(mutex, id_prefix=id_prefix)
             group_node.extend(mutex_nodes)
 
         return group_node
 
-    def render_argument(self, arg: ArgumentInfo) -> argparse_argument:
+    def render_argument(
+        self, arg: ArgumentInfo, *, id_prefix: str = ""
+    ) -> argparse_argument:
         """Render a single argument.
 
         Parameters
         ----------
         arg : ArgumentInfo
             The argument to render.
+        id_prefix : str
+            Optional prefix for the argument ID (e.g., "shell" -> "shell-L").
+            Used to ensure unique IDs when multiple argparse directives exist
+            on the same page.
 
         Returns
         -------
@@ -425,6 +440,7 @@ def render_argument(self, arg: ArgumentInfo) -> argparse_argument:
         arg_node["help"] = arg.help
         arg_node["metavar"] = arg.metavar
         arg_node["required"] = arg.required
+        arg_node["id_prefix"] = id_prefix
 
         if self.config.show_defaults:
             arg_node["default_string"] = arg.default_string
@@ -438,14 +454,16 @@ def render_argument(self, arg: ArgumentInfo) -> argparse_argument:
         return arg_node
 
     def render_mutex_group(
-        self, mutex: MutuallyExclusiveGroup
+        self, mutex: MutuallyExclusiveGroup, *, id_prefix: str = ""
     ) -> list[argparse_argument]:
         """Render a mutually exclusive group.
 
         Parameters
         ----------
         mutex : MutuallyExclusiveGroup
             The mutually exclusive group.
+        id_prefix : str
+            Optional prefix for argument IDs (e.g., "shell" -> "shell-h").
 
         Returns
         -------
@@ -454,7 +472,7 @@ def render_mutex_group(
         """
         result: list[argparse_argument] = []
         for arg in mutex.arguments:
-            arg_node = self.render_argument(arg)
+            arg_node = self.render_argument(arg, id_prefix=id_prefix)
             # Mark as part of mutex group
             arg_node["mutex"] = True
             arg_node["mutex_required"] = mutex.required