Added anchor links to admonition blocks for direct referencing

CHANGELOG.md

@@ -3,6 +3,12 @@
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## Unreleased
+
+### Changed
+
+* Added anchor links to admonition blocks, making it possible to create direct links to specific admonitions. ([#2505], [#2676])
+
 ## Version [v1.10.1] - 2025-03-31
 
 ### Fixed

assets/html/scss/documenter/components/_admonition.scss

@@ -94,6 +94,30 @@ $admonition-border-color: () !default;
     // fa-circle-exclamation
     content: "\f06a";
   }
+
+  .admonition-anchor {
+    opacity: 0;
+    margin-left: 0.5em;
+    font-size: 0.75em;
+    color: inherit;
+    text-decoration: none;
+    transition: opacity 0.2s ease-in-out;
+
+    &:before {
+      @include font-awesome;
+      // fa-link
+      content: "\f0c1";
+    }
+
+    &:hover {
+      opacity: 1 !important;
+      text-decoration: none;
+    }
+  }
+
+  &:hover .admonition-anchor {
+    opacity: 0.8;
+  }
 }
 
 details.admonition.is-details > .admonition-header {

src/html/HTMLWriter.jl

@@ -2378,15 +2378,26 @@ function domify(dctx::DCtx, node::Node, a::MarkdownAST.Admonition)
             isempty(cat_sanitized) ? "" : ".is-category-$(cat_sanitized)"
         end
 
+    admonition_id = if !isempty(a.title)
+        base_id = Documenter.slugify(a.title)
+        node_repr = sprint(io -> show(io, node))
+        content_hash = bytes2hex(SHA.sha1(node_repr))[1:8]
+        "$(base_id)-$(content_hash)"
+    else
+        node_repr = sprint(io -> show(io, node))
+        content_hash = bytes2hex(SHA.sha1(node_repr))[1:8]
+        "$(a.category)-$(content_hash)"
+    end
+    anchor_link = DOM.Tag(:a)[".admonition-anchor", :href => "#$(admonition_id)", :title => "Permalink"]()
     inner_div = div[".admonition-body"](domify(dctx, node.children))
     if a.category == "details"
         # details admonitions are rendered as <details><summary> blocks
-        return details[".admonition.is-details"](
-            summary[".admonition-header"](a.title), inner_div
+        return details[".admonition.is-details", :id => admonition_id](
+            summary[".admonition-header"](a.title, anchor_link), inner_div
         )
     else
-        return div[".admonition$(colorclass)"](
-            header[".admonition-header"](a.title), inner_div
+        return div[".admonition$(colorclass)", :id => admonition_id](
+            header[".admonition-header"](a.title, anchor_link), inner_div
         )
     end
 end