From 917213afb127ec982fc75bb43284ec0a408fc0fd Mon Sep 17 00:00:00 2001
From: Erin Shaben <eshaben@icloud.com>
Date: Thu, 2 Apr 2026 22:39:55 -0400
Subject: [PATCH 01/15] extend functionality of the per page llms dropdown

- Add ability to anchor the per page widget to any class
- Add ability to specify between two different styles of dropdown menus
---
 docs/ai-docs.md                           |  38 +++++
 docs/ai-page-actions.md                   |  26 ++++
 helper_lib/ai_file_utils/ai_file_utils.py | 103 +++++++++++--
 plugins/ai_docs/plugin.py                 |  66 ++++++--
 tests/ai_docs/test_ai_docs.py             | 180 ++++++++++++++++++++++
 tests/ai_file_utils/test_ai_file_utils.py | 128 +++++++++++++--
 6 files changed, 501 insertions(+), 40 deletions(-)

diff --git a/docs/ai-docs.md b/docs/ai-docs.md
index f81ce62..6730ae0 100644
--- a/docs/ai-docs.md
+++ b/docs/ai-docs.md
@@ -33,6 +33,9 @@ plugins:
 | `llms_config` | `string` | `llms_config.json` | Path to the LLM config file, relative to `mkdocs.yml`. |
 | `ai_resources_page` | `bool` | `true` | Generate the AI resources page from `ai-resources.md`. Set to `false` to disable. |
 | `ai_page_actions` | `bool` | `true` | Inject the per-page AI actions widget next to each H1. Set to `false` to disable. |
+| `ai_page_actions_anchor` | `string` | `""` | CSS class name of the element(s) to append the widget into instead of wrapping the H1. When set, the default H1-wrapping behavior is replaced — see [Custom anchor](#custom-anchor). |
+| `ai_page_actions_style` | `string` | `"split"` | Widget layout style. `"split"` renders a copy button left of the dropdown arrow; `"dropdown"` renders a single labelled button with all actions inside — see [Widget style](#widget-style). |
+| `ai_page_actions_dropdown_label` | `string` | `"Markdown for LLMs"` | Trigger button label when `ai_page_actions_style` is `"dropdown"`. |
 | `enabled` | `bool` | `true` | Disable the entire plugin (all features). Supports `!ENV` for environment-based toggling. |
 
 The `llms_config` file controls content filtering, category definitions, and output paths. See [Resolve Markdown](resolve-md.md#-configuration) for a full breakdown of the `llms_config.json` schema.
@@ -56,6 +59,41 @@ Injects a split-button dropdown widget next to each page's H1 heading at build t
 
 See [AI Page Actions](ai-page-actions.md) for details on exclusion rules, toggle page handling, and styling.
 
+#### Widget style
+
+The widget supports two layout styles, controlled by `ai_page_actions_style`.
+
+**`split`** (default) — a copy button sits to the left of a chevron trigger that opens the dropdown:
+
+```yaml
+plugins:
+  - ai_docs:
+      ai_page_actions_style: split   # default, same as omitting the option
+```
+
+**`dropdown`** — a single labelled button opens a menu that contains all actions, including copy. No separate copy button is rendered outside the menu:
+
+```yaml
+plugins:
+  - ai_docs:
+      ai_page_actions_style: dropdown
+      ai_page_actions_dropdown_label: Markdown for LLMs   # default
+```
+
+The container gets the additional CSS class `ai-file-actions-container--dropdown` so you can style the two modes independently. Resources table widgets always carry `ai-file-actions-container--table`. See [Styling](ai-page-actions.md#styling) for the full class reference and CSS examples.
+
+#### Custom anchor
+
+By default, the widget is placed by wrapping the H1 in a `<div class="h1-ai-actions-wrapper">` flex container. If your theme or custom layout already has a dedicated slot for page-level actions, you can redirect the widget there instead:
+
+```yaml
+plugins:
+  - ai_docs:
+      ai_page_actions_anchor: my-page-actions
+```
+
+The plugin then finds every element that has the class `my-page-actions` within `.md-content` and appends the widget into it, leaving the H1 untouched. If no matching element is found on a given page, the page is left unchanged and a debug message is logged. Toggle-page variant handling is not applied in anchor mode — the widget always uses the page's own `.md` path.
+
 ### AI resources page (`ai_resources_page`)
 
 Automatically generates the content for a page named `ai-resources.md`, replacing it with a table listing all available LLM artifact files (global indexes and per-category bundles) with copy, view, and download actions.
diff --git a/docs/ai-page-actions.md b/docs/ai-page-actions.md
index 1ba6fdc..ab501a7 100644
--- a/docs/ai-page-actions.md
+++ b/docs/ai-page-actions.md
@@ -50,6 +50,32 @@ The plugin loads `llms_config.json` from the project root (the directory contain
 
 The widget uses the same CSS classes as the table widget (`ai-file-actions.css`). The H1 wrapper layout is controlled by `.h1-ai-actions-wrapper`, which includes mobile responsive styles that stack the H1 and widget vertically on small screens.
 
+### CSS classes
+
+Every widget shares the base container class. Modifier classes are added automatically based on context, giving you clean CSS selectors for each placement:
+
+| Class | Present on |
+| :--- | :--- |
+| `.ai-file-actions-container` | Every widget (base class) |
+| `.ai-file-actions-container--dropdown` | Per-page widget when `ai_page_actions_style: dropdown` |
+| `.ai-file-actions-container--table` | Widgets inside the AI resources page tables |
+
+### Targeting each widget independently
+
+```css
+/* All widgets */
+.ai-file-actions-container { }
+
+/* Per-page split style only (default) */
+.ai-file-actions-container:not(.ai-file-actions-container--dropdown):not(.ai-file-actions-container--table) { }
+
+/* Per-page dropdown style only */
+.ai-file-actions-container--dropdown { }
+
+/* Resources table widgets only */
+.ai-file-actions-container--table { }
+```
+
 ## Client-Side Behavior
 
 The widget relies on `ai-file-actions.js` for all client-side interactions (copy, download, dropdown toggle, keyboard navigation, analytics). No additional JavaScript is needed.
diff --git a/helper_lib/ai_file_utils/ai_file_utils.py b/helper_lib/ai_file_utils/ai_file_utils.py
index df7c5d0..2a88f80 100644
--- a/helper_lib/ai_file_utils/ai_file_utils.py
+++ b/helper_lib/ai_file_utils/ai_file_utils.py
@@ -359,14 +359,25 @@ def generate_dropdown_html(
         site_url: str = "",
         label_replace: dict[str, str] | None = None,
         content: str = "",
+        style: str = "split",
+        dropdown_label: str = "Markdown for LLMs",
+        extra_classes: str = "",
     ) -> str:
         """
-        Generate the HTML for the AI file actions split-button.
+        Generate the HTML for the AI file actions widget.
 
-        The action marked ``primary: true`` in the JSON renders
-        as the left-side button; all other actions render as
-        dropdown items.  The primary action is automatically
-        excluded from the dropdown.
+        Two styles are supported:
+
+        ``"split"`` (default)
+            The action marked ``primary: true`` in the JSON renders as a
+            left-side button; all other actions render as dropdown items.
+            The primary action is automatically excluded from the dropdown.
+
+        ``"dropdown"``
+            A single trigger button labelled ``dropdown_label`` (default
+            ``"Markdown for LLMs"``) opens a menu that contains *all*
+            actions, including the primary one.  No separate copy button
+            is rendered.
 
         Args:
             url: The relative URL of the file to act upon.
@@ -375,12 +386,18 @@ def generate_dropdown_html(
                      from the dropdown.
             primary_label: Optional label override for the primary
                      button (e.g., "Copy page" vs default "Copy file").
+                     Only used in ``"split"`` style.
             site_url: The base site URL (e.g., "https://docs.polkadot.com/").
                      When provided, ``page_url`` passed to prompt templates
                      will be the fully-qualified URL.
             label_replace: Optional dict of string replacements to apply
                      to dropdown item labels (e.g., ``{"file": "page"}``).
             content: Optional page content for prompt template interpolation.
+            style: Widget style — ``"split"`` or ``"dropdown"``.
+            dropdown_label: Trigger button label used in ``"dropdown"`` style.
+            extra_classes: Additional CSS class(es) to append to the container
+                     div (e.g., ``"ai-file-actions-container--table"``).
+                     Multiple classes can be space-separated.
 
         Returns:
             The HTML string for the component.
@@ -396,10 +413,71 @@ def generate_dropdown_html(
             page_url=url, filename=filename, content=content, prompt_page_url=full_url
         )
 
-        # Separate primary action from dropdown actions
+        exclude_set = set(exclude) if exclude else set()
+
+        # Build container class string — style modifier is auto-added, then
+        # any caller-supplied extra_classes are appended on top.
+        container_classes = "ai-file-actions-container"
+        if style == "dropdown":
+            container_classes += " ai-file-actions-container--dropdown"
+        if extra_classes:
+            container_classes += f" {extra_classes}"
+
+        chevron = (
+            '<svg xmlns="http://www.w3.org/2000/svg"'
+            ' width="24px" height="24px"'
+            ' viewBox="0 0 24 24"'
+            ' class="ai-file-actions-icon'
+            ' ai-file-actions-chevron"'
+            ' aria-hidden="true">'
+            '<path d="M7 10l5 5 5-5z"/></svg>'
+        )
+
+        # ------------------------------------------------------------------ #
+        # "dropdown" style — single trigger button, all actions in the menu   #
+        # ------------------------------------------------------------------ #
+        if style == "dropdown":
+            menu_items = ""
+            for action in actions:
+                if action.get("id") in exclude_set:
+                    continue
+                if label_replace and "label" in action:
+                    for old, new in label_replace.items():
+                        action["label"] = action["label"].replace(old, new)
+                menu_items += self._render_action_item(action, url)
+
+            safe_url = html.escape(url, quote=True)
+            escaped_label = html.escape(dropdown_label, quote=True)
+            trigger_btn = (
+                '<button class="ai-file-actions-btn ai-file-actions-trigger"'
+                f' title="{escaped_label}"'
+                ' type="button"'
+                f' aria-label="{escaped_label}"'
+                ' aria-haspopup="true"'
+                ' aria-expanded="false"'
+                ' role="button"'
+                f' data-url="{safe_url}">'
+                f'<span class="button-text">{escaped_label}</span>'
+                f"{chevron}"
+                "</button>"
+            )
+            dropdown_menu = (
+                '<div class="ai-file-actions-menu" role="menu">'
+                f"{menu_items}"
+                "</div>"
+            )
+            return (
+                f'<div class="{container_classes}">'
+                f"{trigger_btn}"
+                f"{dropdown_menu}"
+                "</div>"
+            )
+
+        # ------------------------------------------------------------------ #
+        # "split" style (default) — primary copy button + chevron trigger     #
+        # ------------------------------------------------------------------ #
         primary_action = None
         dropdown_actions = []
-        exclude_set = set(exclude) if exclude else set()
 
         for action in actions:
             if action.get("primary"):
@@ -416,15 +494,6 @@ def generate_dropdown_html(
         )
 
         # Dropdown trigger (right side of split button)
-        chevron = (
-            '<svg xmlns="http://www.w3.org/2000/svg"'
-            ' width="24px" height="24px"'
-            ' viewBox="0 0 24 24"'
-            ' class="ai-file-actions-icon'
-            ' ai-file-actions-chevron"'
-            ' aria-hidden="true">'
-            '<path d="M7 10l5 5 5-5z"/></svg>'
-        )
         dropdown_btn = (
             '<button class="ai-file-actions-btn'
             ' ai-file-actions-trigger"'
@@ -448,7 +517,7 @@ def generate_dropdown_html(
         )
 
         return (
-            '<div class="ai-file-actions-container">'
+            f'<div class="{container_classes}">'
             f"{copy_btn}"
             f"{dropdown_btn}"
             f"{dropdown_menu}"
diff --git a/plugins/ai_docs/plugin.py b/plugins/ai_docs/plugin.py
index f1d28f6..a1937a4 100644
--- a/plugins/ai_docs/plugin.py
+++ b/plugins/ai_docs/plugin.py
@@ -50,6 +50,9 @@ class AIDocsPlugin(BasePlugin):
         ("llms_config", Type(str, default="llms_config.json")),
         ("ai_resources_page", Type(bool, default=True)),
         ("ai_page_actions", Type(bool, default=True)),
+        ("ai_page_actions_anchor", Type(str, default="")),
+        ("ai_page_actions_style", Type(str, default="split")),
+        ("ai_page_actions_dropdown_label", Type(str, default="Markdown for LLMs")),
     )
 
     def __init__(self):
@@ -97,20 +100,28 @@ def _load_llms_config(self, project_root: Path) -> dict:
             log.warning(f"[ai_docs] Failed to load LLM config: {e}")
             return {}
 
-    def _wrap_h1(self, h1: Tag, md_path: str, soup: BeautifulSoup, site_url: str = "") -> None:
-        """Wrap an H1 element and the AI actions widget in a flex container."""
-        base_path = urlparse(site_url).path.rstrip("/") if site_url else ""
-        url = f"{base_path}/{md_path}"
+    def _build_widget_html(self, url: str, md_path: str, site_url: str) -> str:
+        """Generate the widget HTML using the configured style options."""
+        widget_style = self.config.get("ai_page_actions_style", "split")
+        dropdown_label = self.config.get("ai_page_actions_dropdown_label", "Markdown for LLMs")
         filename = md_path.rsplit("/", 1)[-1]
-
-        widget_html = self._file_utils.generate_dropdown_html(
+        return self._file_utils.generate_dropdown_html(
             url=url,
             filename=filename,
             primary_label="Copy page",
             site_url=site_url,
             label_replace={"file": "page"},
+            style=widget_style,
+            dropdown_label=dropdown_label,
         )
 
+    def _wrap_h1(self, h1: Tag, md_path: str, soup: BeautifulSoup, site_url: str = "") -> None:
+        """Wrap an H1 element and the AI actions widget in a flex container."""
+        base_path = urlparse(site_url).path.rstrip("/") if site_url else ""
+        url = f"{base_path}/{md_path}"
+
+        widget_html = self._build_widget_html(url, md_path, site_url)
+
         wrapper = soup.new_tag("div")
         wrapper["class"] = "h1-ai-actions-wrapper"
 
@@ -118,6 +129,23 @@ def _wrap_h1(self, h1: Tag, md_path: str, soup: BeautifulSoup, site_url: str = "
         widget = BeautifulSoup(widget_html, "html.parser")
         wrapper.append(widget)
 
+    def _inject_into_anchor(self, anchor_class: str, md_path: str, soup: BeautifulSoup, site_url: str = "") -> bool:
+        """Append the AI actions widget into every element with the given CSS class. Returns True if any were found."""
+        base_path = urlparse(site_url).path.rstrip("/") if site_url else ""
+        url = f"{base_path}/{md_path}"
+
+        widget_html = self._build_widget_html(url, md_path, site_url)
+
+        targets = soup.select(f".{anchor_class}")
+        if not targets:
+            return False
+
+        for target in targets:
+            widget = BeautifulSoup(widget_html, "html.parser")
+            target.append(widget)
+
+        return True
+
 
     # ------------------------------------------------------------------
     # Lifecycle hooks
@@ -286,18 +314,21 @@ def make_table(rows: list[str]) -> str:
             )
 
         actions_llms = self._file_utils.generate_dropdown_html(
-            url=f"{base_path}/llms.txt", filename="llms.txt", site_url=site_url
+            url=f"{base_path}/llms.txt", filename="llms.txt", site_url=site_url,
+            extra_classes="ai-file-actions-container--table",
         )
         actions_site_index = self._file_utils.generate_dropdown_html(
             url=f"{base_path}{public_root_stripped}/site-index.json",
             filename="site-index.json",
             site_url=site_url,
+            extra_classes="ai-file-actions-container--table",
         )
         actions_full = self._file_utils.generate_dropdown_html(
             url=f"{base_path}{public_root_stripped}/llms-full.jsonl",
             filename="llms-full.jsonl",
             exclude=["view-markdown"],
             site_url=site_url,
+            extra_classes="ai-file-actions-container--table",
         )
         return make_table([
             "<tr>"
@@ -362,10 +393,12 @@ def make_table(rows: list[str]) -> str:
         url = f"{base_path}{public_root_stripped}/categories/{filename}"
         light_url = f"{base_path}{public_root_stripped}/categories/{light_filename}"
         actions = self._file_utils.generate_dropdown_html(
-            url=url, filename=filename, site_url=site_url
+            url=url, filename=filename, site_url=site_url,
+            extra_classes="ai-file-actions-container--table",
         )
         light_actions = self._file_utils.generate_dropdown_html(
-            url=light_url, filename=light_filename, site_url=site_url
+            url=light_url, filename=light_filename, site_url=site_url,
+            extra_classes="ai-file-actions-container--table",
         )
         return make_table([
             "<tr>"
@@ -482,6 +515,7 @@ def on_post_page(
             return output
 
         site_url = config.get("site_url", "")
+        anchor_class = self.config.get("ai_page_actions_anchor", "").strip()
 
         soup = BeautifulSoup(output, "html.parser")
         md_content = soup.select_one(".md-content")
@@ -490,13 +524,25 @@ def on_post_page(
 
         modified = False
 
-        # --- Toggle pages ---
         # Normalize page URL: strip .html suffix (present when use_directory_urls=false)
         # so the derived .md path always matches the co-located artifact path.
         route = page.url.strip("/")
         if route.endswith(".html"):
             route = route[: -len(".html")]
 
+        # --- Anchor-class mode ---
+        # When ai_page_actions_anchor is set, inject the widget into every element
+        # that carries that class rather than wrapping the H1.
+        if anchor_class:
+            md_path = f"{route}.md"
+            modified = self._inject_into_anchor(anchor_class, md_path, soup, site_url=site_url)
+            if not modified:
+                log.debug(
+                    f"[ai_docs] ai_page_actions_anchor '.{anchor_class}' not found on {page.file.src_path}"
+                )
+            return str(soup) if modified else output
+
+        # --- Toggle pages ---
         toggle_containers = md_content.select(".toggle-container")
         if toggle_containers:
             for container in toggle_containers:
diff --git a/tests/ai_docs/test_ai_docs.py b/tests/ai_docs/test_ai_docs.py
index e01b0d7..e732bf5 100644
--- a/tests/ai_docs/test_ai_docs.py
+++ b/tests/ai_docs/test_ai_docs.py
@@ -935,3 +935,183 @@ def test_page_count_zero_for_unmatched_category(self, tmp_path):
         content = (ai_root / "categories" / "basics-light.md").read_text(encoding="utf-8")
         fm = yaml.safe_load(content.split("---")[1])
         assert fm["page_count"] == 0
+
+
+# ===========================================================================
+# ai_page_actions_anchor
+# ===========================================================================
+
+class TestAiPageActionsAnchor:
+    """Tests for the ai_page_actions_anchor config option."""
+
+    def _make_plugin(self, anchor_class=""):
+        plugin = AIDocsPlugin()
+        plugin.config = {
+            "llms_config": "llms_config.json",
+            "ai_resources_page": True,
+            "ai_page_actions": True,
+            "ai_page_actions_anchor": anchor_class,
+        }
+        plugin._config_loaded = True
+        return plugin
+
+    def _make_page(self, url="guide/", src_path="guide.md"):
+        page = MagicMock()
+        page.is_homepage = False
+        page.file.src_path = src_path
+        page.meta = {}
+        page.url = url
+        return page
+
+    def test_anchor_mode_injects_into_target_element(self):
+        """Widget is appended into the element with the configured class."""
+        plugin = self._make_plugin(anchor_class="page-actions-slot")
+        page = self._make_page()
+        output = (
+            '<div class="md-content">'
+            '<h1>Guide</h1>'
+            '<div class="page-actions-slot"></div>'
+            "</div>"
+        )
+        result = plugin.on_post_page(output, page=page, config={"site_url": ""})
+        soup = BeautifulSoup(result, "html.parser")
+        slot = soup.select_one(".page-actions-slot")
+        assert slot is not None
+        assert slot.find(attrs={"data-url": True}) is not None
+
+    def test_anchor_mode_does_not_wrap_h1(self):
+        """When anchor class is set, the H1 is not wrapped in h1-ai-actions-wrapper."""
+        plugin = self._make_plugin(anchor_class="page-actions-slot")
+        page = self._make_page()
+        output = (
+            '<div class="md-content">'
+            '<h1>Guide</h1>'
+            '<div class="page-actions-slot"></div>'
+            "</div>"
+        )
+        result = plugin.on_post_page(output, page=page, config={"site_url": ""})
+        assert "h1-ai-actions-wrapper" not in result
+
+    def test_anchor_mode_injects_into_all_matching_elements(self):
+        """Widget is appended into every element with the anchor class."""
+        plugin = self._make_plugin(anchor_class="action-slot")
+        page = self._make_page()
+        output = (
+            '<div class="md-content">'
+            '<div class="action-slot" id="a"></div>'
+            '<div class="action-slot" id="b"></div>'
+            "</div>"
+        )
+        result = plugin.on_post_page(output, page=page, config={"site_url": ""})
+        soup = BeautifulSoup(result, "html.parser")
+        slots = soup.select(".action-slot")
+        assert len(slots) == 2
+        for slot in slots:
+            assert slot.find(attrs={"data-url": True}) is not None
+
+    def test_anchor_mode_no_match_returns_output_unchanged(self):
+        """When the anchor class is not found, the page is returned unchanged."""
+        plugin = self._make_plugin(anchor_class="nonexistent-slot")
+        page = self._make_page()
+        output = '<div class="md-content"><h1>Guide</h1></div>'
+        result = plugin.on_post_page(output, page=page, config={"site_url": ""})
+        assert result == output
+
+    def test_anchor_mode_uses_page_route_for_md_path(self):
+        """The widget data-url is derived from the page route, not a toggle variant."""
+        plugin = self._make_plugin(anchor_class="slot")
+        page = self._make_page(url="api/reference/", src_path="api/reference.md")
+        output = (
+            '<div class="md-content">'
+            '<div class="slot"></div>'
+            "</div>"
+        )
+        result = plugin.on_post_page(output, page=page, config={"site_url": ""})
+        soup = BeautifulSoup(result, "html.parser")
+        data_url = soup.find(attrs={"data-url": True})["data-url"]
+        assert data_url == "/api/reference.md"
+
+    def test_empty_anchor_falls_back_to_h1_wrapping(self):
+        """When ai_page_actions_anchor is empty, the default H1-wrapping behavior runs."""
+        plugin = self._make_plugin(anchor_class="")
+        page = self._make_page()
+        output = '<div class="md-content"><h1>Guide</h1><p>Content</p></div>'
+        result = plugin.on_post_page(output, page=page, config={"site_url": ""})
+        assert "h1-ai-actions-wrapper" in result
+
+
+# ===========================================================================
+# ai_page_actions_style
+# ===========================================================================
+
+class TestAiPageActionsStyle:
+    """Tests for the ai_page_actions_style and ai_page_actions_dropdown_label options."""
+
+    def _make_plugin(self, style="split", dropdown_label="Markdown for LLMs"):
+        plugin = AIDocsPlugin()
+        plugin.config = {
+            "llms_config": "llms_config.json",
+            "ai_resources_page": True,
+            "ai_page_actions": True,
+            "ai_page_actions_anchor": "",
+            "ai_page_actions_style": style,
+            "ai_page_actions_dropdown_label": dropdown_label,
+        }
+        plugin._config_loaded = True
+        return plugin
+
+    def _make_page(self, url="guide/", src_path="guide.md"):
+        page = MagicMock()
+        page.is_homepage = False
+        page.file.src_path = src_path
+        page.meta = {}
+        page.url = url
+        return page
+
+    def test_split_style_renders_copy_button(self):
+        """Split style produces the primary copy button outside the dropdown menu."""
+        plugin = self._make_plugin(style="split")
+        page = self._make_page()
+        output = '<div class="md-content"><h1>Guide</h1></div>'
+        result = plugin.on_post_page(output, page=page, config={"site_url": ""})
+        assert "ai-file-actions-copy" in result
+
+    def test_split_style_no_dropdown_modifier(self):
+        """Split style does not apply the --dropdown container modifier."""
+        plugin = self._make_plugin(style="split")
+        page = self._make_page()
+        output = '<div class="md-content"><h1>Guide</h1></div>'
+        result = plugin.on_post_page(output, page=page, config={"site_url": ""})
+        assert "ai-file-actions-container--dropdown" not in result
+
+    def test_dropdown_style_no_copy_button(self):
+        """Dropdown style does not render a standalone copy button."""
+        plugin = self._make_plugin(style="dropdown")
+        page = self._make_page()
+        output = '<div class="md-content"><h1>Guide</h1></div>'
+        result = plugin.on_post_page(output, page=page, config={"site_url": ""})
+        assert "ai-file-actions-copy" not in result
+
+    def test_dropdown_style_container_modifier(self):
+        """Dropdown style applies the --dropdown modifier to the container."""
+        plugin = self._make_plugin(style="dropdown")
+        page = self._make_page()
+        output = '<div class="md-content"><h1>Guide</h1></div>'
+        result = plugin.on_post_page(output, page=page, config={"site_url": ""})
+        assert "ai-file-actions-container--dropdown" in result
+
+    def test_dropdown_style_trigger_label(self):
+        """Dropdown style uses the configured dropdown_label on the trigger."""
+        plugin = self._make_plugin(style="dropdown", dropdown_label="AI Tools")
+        page = self._make_page()
+        output = '<div class="md-content"><h1>Guide</h1></div>'
+        result = plugin.on_post_page(output, page=page, config={"site_url": ""})
+        assert "AI Tools" in result
+
+    def test_dropdown_style_default_label(self):
+        """Dropdown style uses 'Markdown for LLMs' as the default trigger label."""
+        plugin = self._make_plugin(style="dropdown")
+        page = self._make_page()
+        output = '<div class="md-content"><h1>Guide</h1></div>'
+        result = plugin.on_post_page(output, page=page, config={"site_url": ""})
+        assert "Markdown for LLMs" in result
diff --git a/tests/ai_file_utils/test_ai_file_utils.py b/tests/ai_file_utils/test_ai_file_utils.py
index 3200006..7c64fa1 100644
--- a/tests/ai_file_utils/test_ai_file_utils.py
+++ b/tests/ai_file_utils/test_ai_file_utils.py
@@ -309,16 +309,118 @@ def test_mcp_copy_code_escapes_html(self):
         assert "<script>" not in result
         assert "&lt;script&gt;" in result
 
-    def test_mcp_external_link_html(self):
-        """External link should have target=_blank and rel attributes."""
-        result = AIFileUtils.mcp_external_link("https://example.com/docs")
-
-        assert 'href="https://example.com/docs"' in result
-        assert 'target="_blank"' in result
-        assert 'rel="noopener noreferrer"' in result
-        assert ">Setup guide</a>" in result
-
-    def test_mcp_external_link_custom_label(self):
-        """Custom label should appear in the link text."""
-        result = AIFileUtils.mcp_external_link("https://example.com", label="Read more")
-        assert ">Read more</a>" in result
+
+class TestGenerateDropdownHtmlStyle:
+    """Tests for the style parameter of generate_dropdown_html."""
+
+    def setup_method(self):
+        self.utils = AIFileUtils()
+
+    # --- split style (default) ---
+
+    def test_split_style_renders_copy_button(self):
+        """Split style produces the primary copy button outside the menu."""
+        result = self.utils.generate_dropdown_html(
+            url="/page.md", filename="page.md", style="split"
+        )
+        assert "ai-file-actions-copy" in result
+
+    def test_split_style_excludes_primary_from_menu(self):
+        """Split style does not include the primary action as a menu item."""
+        result = self.utils.generate_dropdown_html(
+            url="/page.md", filename="page.md", style="split"
+        )
+        assert 'data-action-id="copy-markdown"' not in result
+
+    def test_split_style_container_has_no_dropdown_modifier(self):
+        """Split style container does not carry the --dropdown modifier class."""
+        result = self.utils.generate_dropdown_html(
+            url="/page.md", filename="page.md", style="split"
+        )
+        assert "ai-file-actions-container--dropdown" not in result
+
+    # --- dropdown style ---
+
+    def test_dropdown_style_has_no_copy_button(self):
+        """Dropdown style does not render a standalone copy button."""
+        result = self.utils.generate_dropdown_html(
+            url="/page.md", filename="page.md", style="dropdown"
+        )
+        assert "ai-file-actions-copy" not in result
+
+    def test_dropdown_style_primary_action_in_menu(self):
+        """Dropdown style includes the primary action as a menu item."""
+        result = self.utils.generate_dropdown_html(
+            url="/page.md", filename="page.md", style="dropdown"
+        )
+        assert 'data-action-id="copy-markdown"' in result
+
+    def test_dropdown_style_trigger_shows_label(self):
+        """Dropdown style trigger button shows the dropdown_label text."""
+        result = self.utils.generate_dropdown_html(
+            url="/page.md", filename="page.md", style="dropdown",
+            dropdown_label="Markdown for LLMs"
+        )
+        assert "Markdown for LLMs" in result
+
+    def test_dropdown_style_custom_label(self):
+        """dropdown_label is reflected in the trigger button."""
+        result = self.utils.generate_dropdown_html(
+            url="/page.md", filename="page.md", style="dropdown",
+            dropdown_label="AI Tools"
+        )
+        assert "AI Tools" in result
+        assert "Markdown for LLMs" not in result
+
+    def test_dropdown_style_container_modifier_class(self):
+        """Dropdown style container carries the --dropdown modifier class."""
+        result = self.utils.generate_dropdown_html(
+            url="/page.md", filename="page.md", style="dropdown"
+        )
+        assert "ai-file-actions-container--dropdown" in result
+
+    def test_dropdown_style_trigger_carries_data_url(self):
+        """Dropdown style trigger button carries data-url for JS."""
+        result = self.utils.generate_dropdown_html(
+            url="/page.md", filename="page.md", style="dropdown"
+        )
+        assert 'data-url="/page.md"' in result
+
+    def test_dropdown_style_exclude_still_works(self):
+        """Excluded action IDs are not present in dropdown style output."""
+        result = self.utils.generate_dropdown_html(
+            url="/page.md", filename="page.md", style="dropdown",
+            exclude=["view-markdown"]
+        )
+        assert 'data-action-id="view-markdown"' not in result
+
+    def test_default_style_is_split(self):
+        """Omitting style produces the same output as style='split'."""
+        default = self.utils.generate_dropdown_html(url="/page.md", filename="page.md")
+        explicit = self.utils.generate_dropdown_html(
+            url="/page.md", filename="page.md", style="split"
+        )
+        assert default == explicit
+
+    def test_extra_classes_appended_to_split_container(self):
+        """extra_classes are added to the container in split style."""
+        result = self.utils.generate_dropdown_html(
+            url="/page.md", filename="page.md", style="split",
+            extra_classes="ai-file-actions-container--table",
+        )
+        assert "ai-file-actions-container--table" in result
+        assert "ai-file-actions-container--dropdown" not in result
+
+    def test_extra_classes_appended_to_dropdown_container(self):
+        """extra_classes are added alongside --dropdown in dropdown style."""
+        result = self.utils.generate_dropdown_html(
+            url="/page.md", filename="page.md", style="dropdown",
+            extra_classes="ai-file-actions-container--table",
+        )
+        assert "ai-file-actions-container--dropdown" in result
+        assert "ai-file-actions-container--table" in result
+
+    def test_no_extra_classes_by_default(self):
+        """Without extra_classes, only the base class (and style modifier) appear."""
+        result = self.utils.generate_dropdown_html(url="/page.md", filename="page.md")
+        assert "ai-file-actions-container--table" not in result

From da840470c3d92a6c1de26ead8fa5925c7282c8d4 Mon Sep 17 00:00:00 2001
From: Erin Shaben <eshaben@icloud.com>
Date: Thu, 2 Apr 2026 22:41:08 -0400
Subject: [PATCH 02/15] remove mcp functionality ai_resources plugin, it only
 needs to be in the unified plugin

---
 plugins/ai_resources_page/plugin.py | 37 -----------------------------
 1 file changed, 37 deletions(-)

diff --git a/plugins/ai_resources_page/plugin.py b/plugins/ai_resources_page/plugin.py
index df63ede..60d00e2 100644
--- a/plugins/ai_resources_page/plugin.py
+++ b/plugins/ai_resources_page/plugin.py
@@ -46,37 +46,6 @@ def sanitize_table_content(self, text: str) -> str:
         # Replace newlines with space to keep it in one cell
         text = text.replace("\n", " ").replace("\r", "")
         return text
-    
-    def _generate_mcp_section(self, project_name: str, mcp_name: str, mcp_url: str) -> str:
-        """Return the full MCP Markdown section (heading, intro, table)."""
-        utils = self._file_utils
-
-        cursor_btn = utils.mcp_install_button(utils.build_cursor_deeplink(mcp_name, mcp_url))
-        vscode_btn = utils.mcp_install_button(utils.build_vscode_deeplink(mcp_name, mcp_url))
-        claude_cmd = utils.mcp_copy_code(f"claude mcp add --transport http {mcp_name} {mcp_url}")
-        codex_cmd = utils.mcp_copy_code(f"codex mcp add {mcp_name} --url {mcp_url}")
-        desktop_link = utils.mcp_external_link(
-            "https://modelcontextprotocol.io/docs/develop/connect-remote-servers#connecting-to-a-remote-mcp-server"
-        )
-
-        return f"""## Connect via MCP
-
-Use the [Model Context Protocol (MCP)](https://modelcontextprotocol.io) to connect your AI tools directly to {project_name} documentation.
-```
-{mcp_url}
-```
-
-| Client | Method | Action |
-|:---|:---|:---|
-| Cursor | One-click install | {cursor_btn} |
-| VS Code | One-click install | {vscode_btn} |
-| Claude Code CLI | Terminal command | {claude_cmd} |
-| Codex CLI | Terminal command | {codex_cmd} |
-| Claude Desktop | Manual setup | {desktop_link} |
-
-!!! note
-    For Claude Code, add `--scope user` to make the MCP server available across all projects.
-"""
 
     def on_page_markdown(self, markdown, page, config, files):
         # Target only the AI Resources page
@@ -193,10 +162,4 @@ def on_page_markdown(self, markdown, page, config, files):
 """
         output.append(note)
 
-        # MCP install section (only when both mcp_url and mcp_name are configured)
-        mcp_name = project_cfg.get("mcp_name")
-        mcp_url = project_cfg.get("mcp_url")
-        if mcp_url and mcp_name:
-            output.append(self._generate_mcp_section(project_name, mcp_name, mcp_url))
-
         return "\n".join(output)

From 652426312038e48be145f6d04abe42f19eb94524 Mon Sep 17 00:00:00 2001
From: Erin Shaben <eshaben@icloud.com>
Date: Thu, 2 Apr 2026 22:46:19 -0400
Subject: [PATCH 03/15] fix failing tests related to mcp, redesign of ai
 resources page, and swapping html div placeholders for comments

---
 tests/ai_docs/test_ai_docs.py                 | 27 +++++-----
 .../test_ai_resources_page.py                 | 52 -------------------
 2 files changed, 13 insertions(+), 66 deletions(-)

diff --git a/tests/ai_docs/test_ai_docs.py b/tests/ai_docs/test_ai_docs.py
index e732bf5..4cf5c48 100644
--- a/tests/ai_docs/test_ai_docs.py
+++ b/tests/ai_docs/test_ai_docs.py
@@ -492,39 +492,38 @@ class TestAiResourcesPageMarkdown:
     """Tests for on_page_markdown output: static prose and placeholder divs."""
 
     def test_emits_aggregate_placeholder_div(self, tmp_path):
-        """on_page_markdown should include the aggregate table placeholder."""
+        """on_page_markdown should include the aggregate table HTML comment placeholder."""
         plugin = _make_plugin()
         config = _make_mkdocs_config(tmp_path)
         page = _make_page(src_path="ai-resources.md")
         result = plugin.on_page_markdown("", page=page, config=config, files=[])
-        assert '<div id="ai-resources-aggregate-table"></div>' in result
+        assert '<!-- ai-resources-aggregate-table -->' in result
 
     def test_emits_category_placeholder_divs(self, tmp_path):
-        """on_page_markdown should include a placeholder div for each configured category."""
+        """on_page_markdown should include an HTML comment placeholder for each configured category."""
         plugin = _make_plugin()
         config = _make_mkdocs_config(tmp_path)
         page = _make_page(src_path="ai-resources.md")
         result = plugin.on_page_markdown("", page=page, config=config, files=[])
-        assert '<div id="ai-category-basics-table"></div>' in result
+        assert '<!-- ai-category-basics-table -->' in result
 
     def test_emits_static_prose(self, tmp_path):
-        """on_page_markdown should include the overview heading and how-to section."""
+        """on_page_markdown should include the overview heading and access section."""
         plugin = _make_plugin()
         config = _make_mkdocs_config(tmp_path)
         page = _make_page(src_path="ai-resources.md")
         result = plugin.on_page_markdown("", page=page, config=config, files=[])
         assert "# AI Resources" in result
-        assert "## How to Use These Files" in result
         assert "## Access LLM Files" in result
 
     def test_emits_category_headings_for_toc(self, tmp_path):
-        """on_page_markdown should emit ## Categories and per-category ### headings for TOC."""
+        """on_page_markdown should emit ### Category Files and per-category #### headings for TOC."""
         plugin = _make_plugin()
         config = _make_mkdocs_config(tmp_path)
         page = _make_page(src_path="ai-resources.md")
         result = plugin.on_page_markdown("", page=page, config=config, files=[])
-        assert "## Categories" in result
-        assert "### Basics" in result
+        assert "### Category Files" in result
+        assert "#### Basics" in result
 
     def test_no_table_rows_in_markdown(self, tmp_path):
         """on_page_markdown must not contain table rows — those are injected in on_post_build."""
@@ -597,7 +596,7 @@ def test_mcp_section_present_when_configured(self, tmp_path):
         assert "VS Code" in result
         assert "Claude Code CLI" in result
         assert "Codex CLI" in result
-        assert "Claude Desktop" in result
+        assert ":simple-claude: Claude" in result
         # Deeplinks should be generated
         assert "cursor://anysphere.cursor-deeplink" in result
         assert "vscode:mcp/install?" in result
@@ -739,8 +738,8 @@ def _write_html(self, path, content):
     def _base_html(self):
         return (
             '<html><body>'
-            '<div id="ai-resources-aggregate-table"></div>'
-            '<div id="ai-category-basics-table"></div>'
+            '<!-- ai-resources-aggregate-table -->'
+            '<!-- ai-category-basics-table -->'
             '</body></html>'
         )
 
@@ -757,8 +756,8 @@ def test_replaces_placeholder(self, tmp_path):
         plugin._patch_ai_resources_page(site_dir, config)
 
         result = html_path.read_text(encoding="utf-8")
-        assert '<div id="ai-resources-aggregate-table"></div>' not in result
-        assert '<div id="ai-category-basics-table"></div>' not in result
+        assert '<!-- ai-resources-aggregate-table -->' not in result
+        assert '<!-- ai-category-basics-table -->' not in result
         assert "<table>" in result
         assert "Token Estimate" in result
 
diff --git a/tests/ai_resources_page/test_ai_resources_page.py b/tests/ai_resources_page/test_ai_resources_page.py
index 708930d..47ea248 100644
--- a/tests/ai_resources_page/test_ai_resources_page.py
+++ b/tests/ai_resources_page/test_ai_resources_page.py
@@ -79,55 +79,3 @@ def test_empty_site_url(self, tmp_path):
         assert "/ai/categories/basics.md" in result
         assert "/llms.txt" in result
 
-
-class TestMCPSection:
-    """Tests for MCP install section on the AI Resources page."""
-
-    def test_mcp_section_present_when_configured(self, tmp_path):
-        """MCP section should appear when mcp_name and mcp_url are set."""
-        llms_config = {
-            "project": {
-                "name": "TestProject",
-                "mcp_name": "test-mcp",
-                "mcp_url": "https://mcp.example.com/sse",
-            },
-            "content": {
-                "categories_info": {
-                    "basics": {"name": "Basics", "description": "Basic docs."}
-                }
-            },
-            "outputs": {"public_root": "/ai/"},
-        }
-        config_file = tmp_path / "llms_config.json"
-        config_file.write_text(json.dumps(llms_config), encoding="utf-8")
-        mkdocs_yml = tmp_path / "mkdocs.yml"
-        mkdocs_yml.write_text("", encoding="utf-8")
-        config = {"config_file_path": str(mkdocs_yml), "site_url": "https://docs.example.com/"}
-
-        plugin = AiResourcesPagePlugin()
-        page = MagicMock()
-        page.file.src_path = "ai-resources.md"
-
-        result = plugin.on_page_markdown("", page, config, [])
-
-        assert "## Connect via MCP" in result
-        assert "https://mcp.example.com/sse" in result
-        assert "Cursor" in result
-        assert "VS Code" in result
-        assert "Claude Code CLI" in result
-        assert "Codex CLI" in result
-        assert "Claude Desktop" in result
-        assert "cursor://anysphere.cursor-deeplink" in result
-        assert "vscode:mcp/install?" in result
-
-    def test_mcp_section_absent_when_not_configured(self, tmp_path):
-        """MCP section should not appear when mcp_name/mcp_url are missing."""
-        config = _make_config(tmp_path)
-
-        plugin = AiResourcesPagePlugin()
-        page = MagicMock()
-        page.file.src_path = "ai-resources.md"
-
-        result = plugin.on_page_markdown("", page, config, [])
-
-        assert "## Connect via MCP" not in result

From 26177e08aa5cdd6f9379e988620f0a382ef5f9ba Mon Sep 17 00:00:00 2001
From: Erin Shaben <eshaben@icloud.com>
Date: Fri, 3 Apr 2026 16:23:08 -0400
Subject: [PATCH 04/15] add markdown icon

---
 helper_lib/ai_file_utils/ai_file_utils.py | 13 +++++++++++++
 1 file changed, 13 insertions(+)

diff --git a/helper_lib/ai_file_utils/ai_file_utils.py b/helper_lib/ai_file_utils/ai_file_utils.py
index 2a88f80..4e5c33a 100644
--- a/helper_lib/ai_file_utils/ai_file_utils.py
+++ b/helper_lib/ai_file_utils/ai_file_utils.py
@@ -448,6 +448,18 @@ def generate_dropdown_html(
 
             safe_url = html.escape(url, quote=True)
             escaped_label = html.escape(dropdown_label, quote=True)
+            markdown_icon = (
+                '<svg xmlns="http://www.w3.org/2000/svg"'
+                ' width="24px" height="24px"'
+                ' viewBox="0 0 24 24"'
+                ' class="ai-file-actions-icon"'
+                ' aria-hidden="true">'
+                '<path d="M20.56 18H3.44C2.65 18 2 17.37 2 16.59V7.41C2 6.63 2.65 6'
+                ' 3.44 6h17.12C21.35 6 22 6.63 22 7.41v9.18c0 .78-.65 1.41-1.44'
+                ' 1.41zM6 15v-4.5l2.5 2.5 2.5-2.5V15h2V9h-2l-2.5 2.5L6 9H4v6h2z'
+                'm11.5 0L20 12h-2V9h-2v3h-2l3.5 4z"/>'
+                '</svg>'
+            )
             trigger_btn = (
                 '<button class="ai-file-actions-btn ai-file-actions-trigger"'
                 f' title="{escaped_label}"'
@@ -457,6 +469,7 @@ def generate_dropdown_html(
                 ' aria-expanded="false"'
                 ' role="button"'
                 f' data-url="{safe_url}">'
+                f'{markdown_icon}'
                 f'<span class="button-text">{escaped_label}</span>'
                 f"{chevron}"
                 "</button>"

From c37dd5481eb96ecc46b6ca25a08abc7751a27340 Mon Sep 17 00:00:00 2001
From: Erin Shaben <eshaben@icloud.com>
Date: Fri, 3 Apr 2026 17:37:49 -0400
Subject: [PATCH 05/15] expose badges to canonical page so template can render
 correct badges

---
 plugins/page_toggle/plugin.py | 10 ++++++++++
 1 file changed, 10 insertions(+)

diff --git a/plugins/page_toggle/plugin.py b/plugins/page_toggle/plugin.py
index 5a05a06..47fc7bc 100644
--- a/plugins/page_toggle/plugin.py
+++ b/plugins/page_toggle/plugin.py
@@ -191,6 +191,15 @@ def render_toggle_page(self, group: str) -> str:
         ordered_variants = [canonical] + [
             v for v in variants.keys() if v != canonical
         ]
+
+        # Expose per-variant page_badges to the canonical page so the
+        # template can render badge blocks without the plugin knowing badge types.
+        canonical_page = variants[canonical]["page"]
+        canonical_page.meta["toggle_variant_metas"] = [
+            (v, variants[v]["page"].meta.get("page_badges") or {})
+            for v in ordered_variants
+        ]
+
         for variant in ordered_variants:
             data = variants[variant]
             active_class = "active" if variant == canonical else ""
@@ -234,6 +243,7 @@ def render_toggle_page(self, group: str) -> str:
         {''.join(buttons_html)}
     </div>
   </div>
+  <!-- toggle-badges -->
   <div class="toggle-content">
     {''.join(content_html)}
   </div>

From ade1139f4202d197027f5a076eaf20a956065cdf Mon Sep 17 00:00:00 2001
From: Erin Shaben <eshaben@icloud.com>
Date: Fri, 3 Apr 2026 18:10:54 -0400
Subject: [PATCH 06/15] update toggle functionality for configs that use a
 custom ai page actions anchor

---
 plugins/ai_docs/plugin.py | 67 +++++++++++++++++++++------------------
 1 file changed, 37 insertions(+), 30 deletions(-)

diff --git a/plugins/ai_docs/plugin.py b/plugins/ai_docs/plugin.py
index a1937a4..9caa985 100644
--- a/plugins/ai_docs/plugin.py
+++ b/plugins/ai_docs/plugin.py
@@ -530,49 +530,56 @@ def on_post_page(
         if route.endswith(".html"):
             route = route[: -len(".html")]
 
-        # --- Anchor-class mode ---
-        # When ai_page_actions_anchor is set, inject the widget into every element
-        # that carries that class rather than wrapping the H1.
-        if anchor_class:
-            md_path = f"{route}.md"
-            modified = self._inject_into_anchor(anchor_class, md_path, soup, site_url=site_url)
-            if not modified:
-                log.debug(
-                    f"[ai_docs] ai_page_actions_anchor '.{anchor_class}' not found on {page.file.src_path}"
-                )
-            return str(soup) if modified else output
-
         # --- Toggle pages ---
         toggle_containers = md_content.select(".toggle-container")
         if toggle_containers:
             for container in toggle_containers:
-                header_spans = container.select(
-                    ".toggle-header > span[data-variant]"
-                )
-                for span in header_spans:
-                    h1 = span.find("h1")
-                    if not h1:
-                        continue
-                    variant = span.get("data-variant", "")
-                    btn = container.select_one(
-                        f'.toggle-btn[data-variant="{variant}"]'
-                    )
-                    data_filename = btn.get("data-filename", "") if btn else ""
+                for btn in container.select(".toggle-btn[data-variant]"):
+                    variant = btn.get("data-variant", "")
+                    data_filename = btn.get("data-filename", "")
                     if data_filename:
                         segments = route.split("/")
                         md_path = "/".join(segments[:-1] + [f"{data_filename}.md"])
                     else:
                         md_path = f"{route}.md"
-                    self._wrap_h1(h1, md_path, soup, site_url=site_url)
-                    modified = True
+
+                    if anchor_class:
+                        # Inject into the per-variant anchor element so each
+                        # variant gets its own correctly-scoped widget.
+                        anchor_el = container.select_one(
+                            f'.{anchor_class}[data-variant="{variant}"]'
+                        )
+                        if anchor_el:
+                            base_path = urlparse(site_url).path.rstrip("/") if site_url else ""
+                            url = f"{base_path}/{md_path}"
+                            widget_html = self._build_widget_html(url, md_path, site_url)
+                            anchor_el.append(BeautifulSoup(widget_html, "html.parser"))
+                            modified = True
+                    else:
+                        span = container.select_one(
+                            f'.toggle-header > span[data-variant="{variant}"]'
+                        )
+                        if span:
+                            h1 = span.find("h1")
+                            if h1:
+                                self._wrap_h1(h1, md_path, soup, site_url=site_url)
+                                modified = True
 
         # --- Normal pages (no toggle) ---
         if not toggle_containers:
-            h1 = md_content.find("h1")
-            if h1:
+            if anchor_class:
                 md_path = f"{route}.md"
-                self._wrap_h1(h1, md_path, soup, site_url=site_url)
-                modified = True
+                modified = self._inject_into_anchor(anchor_class, md_path, soup, site_url=site_url)
+                if not modified:
+                    log.debug(
+                        f"[ai_docs] ai_page_actions_anchor '.{anchor_class}' not found on {page.file.src_path}"
+                    )
+            else:
+                h1 = md_content.find("h1")
+                if h1:
+                    md_path = f"{route}.md"
+                    self._wrap_h1(h1, md_path, soup, site_url=site_url)
+                    modified = True
 
         if not modified:
             return output

From 9abc1585e18c0cd43cf5c020dccca5766fca9654 Mon Sep 17 00:00:00 2001
From: Erin Shaben <eshaben@icloud.com>
Date: Mon, 6 Apr 2026 13:22:33 -0400
Subject: [PATCH 07/15] scope selector to .md-content

---
 plugins/ai_docs/plugin.py | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/plugins/ai_docs/plugin.py b/plugins/ai_docs/plugin.py
index 9caa985..b3677ae 100644
--- a/plugins/ai_docs/plugin.py
+++ b/plugins/ai_docs/plugin.py
@@ -129,14 +129,14 @@ def _wrap_h1(self, h1: Tag, md_path: str, soup: BeautifulSoup, site_url: str = "
         widget = BeautifulSoup(widget_html, "html.parser")
         wrapper.append(widget)
 
-    def _inject_into_anchor(self, anchor_class: str, md_path: str, soup: BeautifulSoup, site_url: str = "") -> bool:
-        """Append the AI actions widget into every element with the given CSS class. Returns True if any were found."""
+    def _inject_into_anchor(self, anchor_class: str, md_path: str, md_content, site_url: str = "") -> bool:
+        """Append the AI actions widget into every element with the given CSS class within .md-content. Returns True if any were found."""
         base_path = urlparse(site_url).path.rstrip("/") if site_url else ""
         url = f"{base_path}/{md_path}"
 
         widget_html = self._build_widget_html(url, md_path, site_url)
 
-        targets = soup.select(f".{anchor_class}")
+        targets = md_content.select(f".{anchor_class}")
         if not targets:
             return False
 
@@ -569,7 +569,7 @@ def on_post_page(
         if not toggle_containers:
             if anchor_class:
                 md_path = f"{route}.md"
-                modified = self._inject_into_anchor(anchor_class, md_path, soup, site_url=site_url)
+                modified = self._inject_into_anchor(anchor_class, md_path, md_content, site_url=site_url)
                 if not modified:
                     log.debug(
                         f"[ai_docs] ai_page_actions_anchor '.{anchor_class}' not found on {page.file.src_path}"

From 0e802b9cf6b69a5735e00afdc28e9b6b70f6a397 Mon Sep 17 00:00:00 2001
From: Erin Shaben <eshaben@icloud.com>
Date: Mon, 6 Apr 2026 13:26:13 -0400
Subject: [PATCH 08/15] strip leading periods in front of classes and add
 try/catches and log errors with selectors

---
 plugins/ai_docs/plugin.py | 18 +++++++++++++-----
 1 file changed, 13 insertions(+), 5 deletions(-)

diff --git a/plugins/ai_docs/plugin.py b/plugins/ai_docs/plugin.py
index b3677ae..c0ed4a5 100644
--- a/plugins/ai_docs/plugin.py
+++ b/plugins/ai_docs/plugin.py
@@ -136,7 +136,11 @@ def _inject_into_anchor(self, anchor_class: str, md_path: str, md_content, site_
 
         widget_html = self._build_widget_html(url, md_path, site_url)
 
-        targets = md_content.select(f".{anchor_class}")
+        try:
+            targets = md_content.select(f".{anchor_class}")
+        except Exception:
+            log.warning(f"[ai_docs] Invalid ai_page_actions_anchor selector: '.{anchor_class}'. Skipping injection.")
+            return False
         if not targets:
             return False
 
@@ -515,7 +519,7 @@ def on_post_page(
             return output
 
         site_url = config.get("site_url", "")
-        anchor_class = self.config.get("ai_page_actions_anchor", "").strip()
+        anchor_class = self.config.get("ai_page_actions_anchor", "").strip().lstrip(".")
 
         soup = BeautifulSoup(output, "html.parser")
         md_content = soup.select_one(".md-content")
@@ -546,9 +550,13 @@ def on_post_page(
                     if anchor_class:
                         # Inject into the per-variant anchor element so each
                         # variant gets its own correctly-scoped widget.
-                        anchor_el = container.select_one(
-                            f'.{anchor_class}[data-variant="{variant}"]'
-                        )
+                        try:
+                            anchor_el = container.select_one(
+                                f'.{anchor_class}[data-variant="{variant}"]'
+                            )
+                        except Exception:
+                            log.warning(f"[ai_docs] Invalid ai_page_actions_anchor selector: '.{anchor_class}'. Skipping injection.")
+                            anchor_el = None
                         if anchor_el:
                             base_path = urlparse(site_url).path.rstrip("/") if site_url else ""
                             url = f"{base_path}/{md_path}"

From 11e9d7765af364642de3286a91ffc2454016dc05 Mon Sep 17 00:00:00 2001
From: Erin Shaben <eshaben@icloud.com>
Date: Mon, 6 Apr 2026 13:27:51 -0400
Subject: [PATCH 09/15] update docs to account for split and dropdown styles

---
 docs/ai-docs.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/ai-docs.md b/docs/ai-docs.md
index 6730ae0..f254137 100644
--- a/docs/ai-docs.md
+++ b/docs/ai-docs.md
@@ -55,7 +55,7 @@ Always runs when the plugin is enabled. Processes every documentation markdown f
 
 ### AI page actions (`ai_page_actions`)
 
-Injects a split-button dropdown widget next to each page's H1 heading at build time. The widget lets readers copy, download, or open the page's resolved markdown in an LLM tool. Pages listed in `llms_config.json` exclusions, dot-directories, and pages with `hide_ai_actions: true` in their front matter are automatically skipped.
+Injects an AI actions widget (split-button by default, or plain dropdown via `ai_page_actions_style`) next to each page's H1 heading at build time. The widget lets readers copy, download, or open the page's resolved markdown in an LLM tool. Pages listed in `llms_config.json` exclusions, dot-directories, and pages with `hide_ai_actions: true` in their front matter are automatically skipped.
 
 See [AI Page Actions](ai-page-actions.md) for details on exclusion rules, toggle page handling, and styling.
 

From 8864ed4bd67b12cd8afbb9026e4bcd30141b4034 Mon Sep 17 00:00:00 2001
From: Erin Shaben <eshaben@icloud.com>
Date: Mon, 6 Apr 2026 13:29:42 -0400
Subject: [PATCH 10/15] add clarity to docs

---
 docs/ai-page-actions.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/docs/ai-page-actions.md b/docs/ai-page-actions.md
index ab501a7..512b859 100644
--- a/docs/ai-page-actions.md
+++ b/docs/ai-page-actions.md
@@ -57,7 +57,7 @@ Every widget shares the base container class. Modifier classes are added automat
 | Class | Present on |
 | :--- | :--- |
 | `.ai-file-actions-container` | Every widget (base class) |
-| `.ai-file-actions-container--dropdown` | Per-page widget when `ai_page_actions_style: dropdown` |
+| `.ai-file-actions-container--dropdown` | Per-page widget rendered in dropdown style (applied by `ai_docs` when `ai_page_actions_style: dropdown`) |
 | `.ai-file-actions-container--table` | Widgets inside the AI resources page tables |
 
 ### Targeting each widget independently
@@ -69,7 +69,7 @@ Every widget shares the base container class. Modifier classes are added automat
 /* Per-page split style only (default) */
 .ai-file-actions-container:not(.ai-file-actions-container--dropdown):not(.ai-file-actions-container--table) { }
 
-/* Per-page dropdown style only */
+/* Per-page dropdown style only (when used via ai_docs with ai_page_actions_style: dropdown) */
 .ai-file-actions-container--dropdown { }
 
 /* Resources table widgets only */

From d4925f9d63e0710dafcf9e0395102248dc7b3df3 Mon Sep 17 00:00:00 2001
From: Erin Shaben <eshaben@icloud.com>
Date: Mon, 6 Apr 2026 13:46:49 -0400
Subject: [PATCH 11/15] add missing tests for toggles with specified anchor
 classes

---
 tests/ai_docs/test_ai_docs.py | 94 +++++++++++++++++++++++++++++++++++
 1 file changed, 94 insertions(+)

diff --git a/tests/ai_docs/test_ai_docs.py b/tests/ai_docs/test_ai_docs.py
index 4cf5c48..474fb15 100644
--- a/tests/ai_docs/test_ai_docs.py
+++ b/tests/ai_docs/test_ai_docs.py
@@ -1038,6 +1038,100 @@ def test_empty_anchor_falls_back_to_h1_wrapping(self):
         result = plugin.on_post_page(output, page=page, config={"site_url": ""})
         assert "h1-ai-actions-wrapper" in result
 
+    # --- Toggle page + anchor_class tests ---
+
+    def test_toggle_anchor_injects_widget_per_variant_with_data_filename(self):
+        """Each variant's anchor element gets a widget whose data-url matches data-filename."""
+        plugin = self._make_plugin(anchor_class="actions-slot")
+        page = self._make_page(url="runtime/", src_path="runtime.md")
+        output = (
+            '<div class="md-content">'
+            '<div class="toggle-container">'
+            '<button class="toggle-btn" data-variant="stable" data-filename="runtime-stable"></button>'
+            '<button class="toggle-btn" data-variant="latest" data-filename="runtime-latest"></button>'
+            '<div class="actions-slot" data-variant="stable"></div>'
+            '<div class="actions-slot" data-variant="latest"></div>'
+            "</div>"
+            "</div>"
+        )
+        result = plugin.on_post_page(output, page=page, config={"site_url": ""})
+        soup = BeautifulSoup(result, "html.parser")
+
+        stable_slot = soup.select_one('.actions-slot[data-variant="stable"]')
+        latest_slot = soup.select_one('.actions-slot[data-variant="latest"]')
+
+        assert stable_slot is not None
+        assert latest_slot is not None
+
+        stable_widget = stable_slot.find(attrs={"data-url": True})
+        latest_widget = latest_slot.find(attrs={"data-url": True})
+
+        assert stable_widget is not None, "stable slot should have a widget"
+        assert latest_widget is not None, "latest slot should have a widget"
+        assert stable_widget["data-url"] == "/runtime-stable.md"
+        assert latest_widget["data-url"] == "/runtime-latest.md"
+
+    def test_toggle_anchor_falls_back_to_route_when_no_data_filename(self):
+        """When data-filename is absent, the widget data-url falls back to the page route."""
+        plugin = self._make_plugin(anchor_class="actions-slot")
+        page = self._make_page(url="guide/", src_path="guide.md")
+        output = (
+            '<div class="md-content">'
+            '<div class="toggle-container">'
+            '<button class="toggle-btn" data-variant="v1"></button>'
+            '<div class="actions-slot" data-variant="v1"></div>'
+            "</div>"
+            "</div>"
+        )
+        result = plugin.on_post_page(output, page=page, config={"site_url": ""})
+        soup = BeautifulSoup(result, "html.parser")
+        widget = soup.select_one('.actions-slot[data-variant="v1"]').find(attrs={"data-url": True})
+        assert widget is not None
+        assert widget["data-url"] == "/guide.md"
+
+    def test_toggle_anchor_no_match_skips_injection(self):
+        """When the anchor class is not found for a variant, no widget is injected."""
+        plugin = self._make_plugin(anchor_class="actions-slot")
+        page = self._make_page(url="guide/", src_path="guide.md")
+        output = (
+            '<div class="md-content">'
+            '<div class="toggle-container">'
+            '<button class="toggle-btn" data-variant="v1" data-filename="guide-v1"></button>'
+            # No matching .actions-slot[data-variant="v1"] present
+            '<div class="other-class" data-variant="v1"></div>'
+            "</div>"
+            "</div>"
+        )
+        result = plugin.on_post_page(output, page=page, config={"site_url": ""})
+        soup = BeautifulSoup(result, "html.parser")
+        assert soup.find(attrs={"data-url": True}) is None
+
+    def test_toggle_anchor_does_not_inject_into_other_variants_slot(self):
+        """Each variant's widget only appears in its own anchor element, not another variant's."""
+        plugin = self._make_plugin(anchor_class="slot")
+        page = self._make_page(url="docs/", src_path="docs.md")
+        output = (
+            '<div class="md-content">'
+            '<div class="toggle-container">'
+            '<button class="toggle-btn" data-variant="a" data-filename="docs-a"></button>'
+            '<button class="toggle-btn" data-variant="b" data-filename="docs-b"></button>'
+            '<div class="slot" data-variant="a"></div>'
+            '<div class="slot" data-variant="b"></div>'
+            "</div>"
+            "</div>"
+        )
+        result = plugin.on_post_page(output, page=page, config={"site_url": ""})
+        soup = BeautifulSoup(result, "html.parser")
+
+        slot_a = soup.select_one('.slot[data-variant="a"]')
+        slot_b = soup.select_one('.slot[data-variant="b"]')
+
+        assert slot_a.find(attrs={"data-url": "/docs-a.md"}) is not None
+        assert slot_b.find(attrs={"data-url": "/docs-b.md"}) is not None
+        # Ensure cross-contamination didn't happen
+        assert slot_a.find(attrs={"data-url": "/docs-b.md"}) is None
+        assert slot_b.find(attrs={"data-url": "/docs-a.md"}) is None
+
 
 # ===========================================================================
 # ai_page_actions_style

From 71ac1585d732e3cd20f5d65d5f82265cf35b717a Mon Sep 17 00:00:00 2001
From: Erin Shaben <eshaben@icloud.com>
Date: Mon, 6 Apr 2026 16:42:33 -0400
Subject: [PATCH 12/15] update docs

---
 docs/ai-docs.md | 13 ++++++++++++-
 1 file changed, 12 insertions(+), 1 deletion(-)

diff --git a/docs/ai-docs.md b/docs/ai-docs.md
index f254137..bfed83f 100644
--- a/docs/ai-docs.md
+++ b/docs/ai-docs.md
@@ -92,7 +92,18 @@ plugins:
       ai_page_actions_anchor: my-page-actions
 ```
 
-The plugin then finds every element that has the class `my-page-actions` within `.md-content` and appends the widget into it, leaving the H1 untouched. If no matching element is found on a given page, the page is left unchanged and a debug message is logged. Toggle-page variant handling is not applied in anchor mode — the widget always uses the page's own `.md` path.
+The plugin then finds every element that has the class `my-page-actions` within `.md-content` and appends the widget into it, leaving the H1 untouched. If no matching element is found on a given page, the page is left unchanged and a debug message is logged.
+
+#### Toggle pages
+
+When using `ai_page_actions_anchor` alongside the [`page_toggle` plugin](page-toggle.md), your template must render one anchor element per variant inside the toggle container, each carrying the matching `data-variant` attribute. For example:
+
+```html
+<div class="my-page-actions" data-variant="stable"></div>
+<div class="my-page-actions" data-variant="latest"></div>
+```
+
+A Jinja macro is a convenient way to do this — iterate over your variants and emit the element with the correct `data-variant` for each one.
 
 ### AI resources page (`ai_resources_page`)
 

From eaf8f95cfd01939631cbdfd2c3406c6bb2eede86 Mon Sep 17 00:00:00 2001
From: Erin Shaben <eshaben@icloud.com>
Date: Mon, 6 Apr 2026 16:46:16 -0400
Subject: [PATCH 13/15] add debug message

---
 plugins/ai_docs/plugin.py | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/plugins/ai_docs/plugin.py b/plugins/ai_docs/plugin.py
index c0ed4a5..8a19943 100644
--- a/plugins/ai_docs/plugin.py
+++ b/plugins/ai_docs/plugin.py
@@ -563,6 +563,11 @@ def on_post_page(
                             widget_html = self._build_widget_html(url, md_path, site_url)
                             anchor_el.append(BeautifulSoup(widget_html, "html.parser"))
                             modified = True
+                        else:
+                            log.debug(
+                                f"[ai_docs] ai_page_actions_anchor '.{anchor_class}[data-variant=\"{variant}\"]' "
+                                f"not found in toggle container on {page.file.src_path}"
+                            )
                     else:
                         span = container.select_one(
                             f'.toggle-header > span[data-variant="{variant}"]'

From 0d99cbdb9855a9651f8e2ce5c610ab23aa0c8128 Mon Sep 17 00:00:00 2001
From: Erin Shaben <eshaben@icloud.com>
Date: Wed, 8 Apr 2026 15:08:09 -0400
Subject: [PATCH 14/15] remove dropdown tooltip label (isn't useful)

---
 helper_lib/ai_file_utils/ai_file_utils.py | 1 -
 1 file changed, 1 deletion(-)

diff --git a/helper_lib/ai_file_utils/ai_file_utils.py b/helper_lib/ai_file_utils/ai_file_utils.py
index 4e5c33a..65d8248 100644
--- a/helper_lib/ai_file_utils/ai_file_utils.py
+++ b/helper_lib/ai_file_utils/ai_file_utils.py
@@ -462,7 +462,6 @@ def generate_dropdown_html(
             )
             trigger_btn = (
                 '<button class="ai-file-actions-btn ai-file-actions-trigger"'
-                f' title="{escaped_label}"'
                 ' type="button"'
                 f' aria-label="{escaped_label}"'
                 ' aria-haspopup="true"'

From cfdd10ab4f3a256f7b6dac9fedf392543e63b986 Mon Sep 17 00:00:00 2001
From: Erin Shaben <eshaben@icloud.com>
Date: Wed, 8 Apr 2026 16:07:17 -0400
Subject: [PATCH 15/15] add logic to account for tests

---
 plugins/page_toggle/plugin.py | 36 +++++++++++++++++++++++++++++++----
 1 file changed, 32 insertions(+), 4 deletions(-)

diff --git a/plugins/page_toggle/plugin.py b/plugins/page_toggle/plugin.py
index 47fc7bc..daeec10 100644
--- a/plugins/page_toggle/plugin.py
+++ b/plugins/page_toggle/plugin.py
@@ -192,13 +192,21 @@ def render_toggle_page(self, group: str) -> str:
             v for v in variants.keys() if v != canonical
         ]
 
-        # Expose per-variant page_badges to the canonical page so the
-        # template can render badge blocks without the plugin knowing badge types.
+        # Expose per-variant page_badges and page_tests to the canonical page so the
+        # template can render badge/test blocks without the plugin knowing their types.
         canonical_page = variants[canonical]["page"]
         canonical_page.meta["toggle_variant_metas"] = [
             (v, variants[v]["page"].meta.get("page_badges") or {})
             for v in ordered_variants
         ]
+        canonical_page.meta["toggle_variant_test_metas"] = [
+            (
+                v,
+                variants[v]["page"].meta.get("page_tests") or {},
+                (variants[v]["page"].meta.get("page_badges") or {}).get("test_workflow"),
+            )
+            for v in ordered_variants
+        ]
 
         for variant in ordered_variants:
             data = variants[variant]
@@ -224,13 +232,16 @@ def render_toggle_page(self, group: str) -> str:
                 f' data-canonical="{str(variant == canonical).lower()}" data-filename="{esc_filename}">{esc_label}</button>'
             )
 
-            # Content panels
+            # Content panels — inject per-variant tests placeholder before
+            # "Where to Go Next" (or at end) so the template can replace it
+            # with the rendered test block for this variant.
+            panel_html = self._inject_tests_placeholder(data["html"], variant)
             toc_html_attr = escape(data["toc_html"], quote=True)
             content_html.append(
                 f'<div class="toggle-panel {active_class}" '
                 f'data-variant="{esc_variant}" '
                 f'data-toc-html="{toc_html_attr}">'
-                f'{data["html"]}'
+                f'{panel_html}'
                 f"</div>"
             )
 
@@ -250,6 +261,23 @@ def render_toggle_page(self, group: str) -> str:
 </div>
 """
 
+    # ------------------------------------------------------------
+    # Inject per-variant tests placeholder into panel HTML
+    # ------------------------------------------------------------
+    def _inject_tests_placeholder(self, html: str, variant: str) -> str:
+        """
+        Insert <!-- toggle-tests-{variant} --> immediately before the
+        'Where to Go Next' h2 section, or append it at the end if that
+        section is absent.  The template replaces each placeholder with
+        the rendered test block for the corresponding variant.
+        """
+        placeholder = f"<!-- toggle-tests-{variant} -->"
+        marker = '<h2 id="where-to-go-next"'
+        idx = html.find(marker)
+        if idx >= 0:
+            return html[:idx] + placeholder + html[idx:]
+        return html + placeholder
+
     # ------------------------------------------------------------
     # Render page TOC in MkDocs sidebar format
     # ------------------------------------------------------------