Add deeplink anchors to dropdown directive

docs/syntax/dropdowns.md

@@ -50,3 +50,44 @@ Dropdown content
 ::::
 
 :::::
+
+## Deeplinking
+
+Dropdowns support deeplinking through anchor links. When you navigate to a URL with a hash that points to a dropdown or content within a dropdown, the dropdown will automatically open. When you manually open a dropdown that has a name/anchor, the URL will automatically update to reflect the current state.
+
+:::::{tab-set}
+
+::::{tab-item} Output
+
+:::{dropdown} Deeplink Example
+:name: deeplink-example
+
+This dropdown can be opened by navigating to `#deeplink-example`.
+
+When you open this dropdown manually by clicking the title, the URL will automatically update to show `#deeplink-example`.
+
+#### Nested Content [#nested-content]
+
+You can also link directly to content within dropdowns. This content has the anchor `#nested-content`.
+
+:::
+
+::::
+
+::::{tab-item} Markdown
+```markdown
+:::{dropdown} Deeplink Example
+:name: deeplink-example
+
+This dropdown can be opened by navigating to `#deeplink-example`.
+
+When you open this dropdown manually by clicking the title, the URL will automatically update to show `#deeplink-example`.
+
+#### Nested Content [#nested-content]
+
+You can also link directly to content within dropdowns. This content has the anchor `#nested-content`.
+
+:::
+::::
+
+:::::

docs/testing/nested/index.md

@@ -11,3 +11,10 @@ The files in this directory are used for testing purposes. Do not edit these fil
 ## Injecting a {{x}} is supported in headers.
 
 This should show up in the file's table of contents too.
+
+:::{dropdown} Dropdown Title
+:name: dropdown-title
+
+Text.
+
+:::

src/Elastic.Documentation.Site/Assets/main.ts

@@ -2,7 +2,7 @@ import { initCopyButton } from './copybutton'
 import { initHighlight } from './hljs'
 import { initImageCarousel } from './image-carousel'
 import './markdown/applies-to'
-import { openDetailsWithAnchor } from './open-details-with-anchor'
+import { initOpenDetailsWithAnchor } from './open-details-with-anchor'
 import { initNav } from './pages-nav'
 import { initSmoothScroll } from './smooth-scroll'
 import { initTabs } from './tabs'
@@ -31,7 +31,7 @@ document.addEventListener('htmx:load', function (event) {
         initNav()
     }
     initSmoothScroll()
-    openDetailsWithAnchor()
+    initOpenDetailsWithAnchor()
     initImageCarousel()
 
     const urlParams = new URLSearchParams(window.location.search)

src/Elastic.Documentation.Site/Assets/open-details-with-anchor.ts

@@ -1,23 +1,66 @@
-import { UAParser } from 'ua-parser-js'
-
-const { getBrowser } = new UAParser()
-
-// This is a fix for anchors in details elements in non-Chrome browsers.
+// Opens details elements (dropdowns) when navigating to an anchor link within them
+// This enables deeplinking to collapsed dropdown content
 export function openDetailsWithAnchor() {
     if (window.location.hash) {
         const target = document.querySelector(window.location.hash)
         if (target) {
             const closestDetails = target.closest('details')
             if (closestDetails) {
-                const browser = getBrowser()
-                if (browser.name !== 'Chrome') {
-                    closestDetails.open = true
+                closestDetails.open = true
+                // Small delay to ensure the details element is open before scrolling
+                setTimeout(() => {
                     target.scrollIntoView({
-                        behavior: 'instant',
+                        behavior: 'smooth',
                         block: 'start',
                     })
-                }
+                }, 50)
             }
         }
     }
 }
+
+// Updates the URL when a dropdown is manually opened/closed
+function updateUrlForDropdown(details: HTMLDetailsElement, isOpening: boolean) {
+    const dropdownId = details.id
+    if (!dropdownId) return
+
+    if (isOpening) {
+        // Update URL to show the dropdown anchor (like clicking a heading link)
+        window.history.pushState(null, '', `#${dropdownId}`)
+    }
+    // Note: We don't remove the hash when closing, just like headings don't
+    // This keeps the URL consistent with how headings behave
+}
+
+// Initialize the anchor handling functionality
+export function initOpenDetailsWithAnchor() {
+    // Handle initial page load
+    openDetailsWithAnchor()
+
+    // Handle hash changes within the same page (e.g., clicking anchor links)
+    window.addEventListener('hashchange', openDetailsWithAnchor)
+
+    // Handle manual dropdown toggling to update URL
+    // Use event delegation to catch all toggle events
+    document.addEventListener(
+        'toggle',
+        (event) => {
+            const target = event.target as HTMLElement
+
+            // Check if the target is a details element with dropdown class
+            if (
+                target.tagName === 'DETAILS' &&
+                target.classList.contains('dropdown')
+            ) {
+                const details = target as HTMLDetailsElement
+                const isOpening = details.open
+
+                // Use setTimeout to ensure the toggle state has been processed
+                setTimeout(() => {
+                    updateUrlForDropdown(details, isOpening)
+                }, 0)
+            }
+        },
+        true
+    ) // Use capture phase to ensure we catch the event
+}

tests/Elastic.Markdown.Tests/Directives/AdmonitionTests.cs

@@ -99,3 +99,27 @@ A regular paragraph.
 	[Fact]
 	public void SetsDropdownOpen() => Block!.DropdownOpen.Should().BeTrue();
 }
+
+public class DropdownWithNameTests(ITestOutputHelper output) : DirectiveTest<AdmonitionBlock>(output,
+"""
+:::{dropdown} Dropdown with name
+:name: test-dropdown
+:open:
+This is a dropdown with a name
+:::
+A regular paragraph.
+"""
+)
+{
+	[Fact]
+	public void SetsCorrectAdmonitionType() => Block!.Admonition.Should().Be("dropdown");
+
+	[Fact]
+	public void SetsCustomTitle() => Block!.Title.Should().Be("Dropdown with name");
+
+	[Fact]
+	public void SetsDropdownOpen() => Block!.DropdownOpen.Should().BeTrue();
+
+	[Fact]
+	public void SetsCrossReferenceName() => Block!.CrossReferenceName.Should().Be("test-dropdown");
+}