feat: add explicit buttons to heading titles

This commit adds two buttons to each heading title.
These buttons are by default hidden, but they will
appear on hovering on the heading titles.

The first button is a "link here" button, which adjusts the URL of the
current page to include an anchor to link to that heading title, similar
to how GitHub makes each heading title in README documents a link
to add an anchor.

The second button is to view Scribble source and internal link.
Previously, clicking heading titles serves this functionality,
but without an indicator that heading titles can be clicked,
the feature is not discoverable. So this commit makes a
transition toward an explicit button.

Author: sorawee

scribble-lib/scribble/html-render.rkt

@@ -4,6 +4,7 @@
          "html-properties.rkt"
          "private/literal-anchor.rkt"
          racket/class
+         racket/match
          racket/path
          racket/file
          racket/port
@@ -1154,6 +1155,7 @@
                              (append
                               (if (and src taglet)
                                   `([x-source-module ,(format "~s" src)]
+                                    [class "heading"]
                                     ,@(let* ([path (resolved-module-path-name
                                                     (module-path-index-resolve
                                                      (module-path-index-join src #f)))]
@@ -1170,14 +1172,32 @@
                                   '())
                               (style->attribs (part-style d))))
                           ,@(format-number number '((tt nbsp)))
-                          ,@(map (lambda (t)
-                                   `(a ([name ,(format "~a" (anchor-name
-                                                             (add-current-tag-prefix
-                                                              (tag-key t ri))))])))
-                                 (part-tags d))
                           ,@(if (part-title-content d)
                                 (render-content (part-title-content d) d ri)
-                                null)))])
+                                null)
+                          " "
+                          (span ([class "button-group"])
+                                ,@(let ([make-anchor
+                                         (lambda (t #:content [content '()])
+                                           `(a ([name ,(format "~a" (anchor-name
+                                                                     (add-current-tag-prefix
+                                                                      (tag-key t ri))))]
+                                                [href ,(format "#~a" (anchor-name
+                                                                      (add-current-tag-prefix
+                                                                       (tag-key t ri))))])
+                                               ,@content))])
+                                    (match (part-tags d)
+                                      ['() '()]
+                                      [(cons t ts)
+                                       (cons (make-anchor t
+                                                          #:content
+                                                          (list `(span ([class "heading-anchor"]
+                                                                        [title "Link here"])
+                                                                       "🔗")))
+                                             (map make-anchor ts))]))
+                                " "
+                                (a ([class "heading-source"]
+                                    [title "Internal Scribble link and Scribble source"]) "ℹ"))))])
              ,@(let ([auths (extract-authors d)])
                  (if (null? auths)
                      null

scribble-lib/scribble/manual-racket.js

@@ -236,12 +236,15 @@ function AddPartTitleOnClick(elem) {
         else
             elem.parentNode.appendChild(info);
 
-        /* Clicking the header shows the explanation element: */
-        elem.onclick = function () {
-            if (info.style.display == "none")
+        /* Clicking the information button shows the explanation element: */
+        const heading = elem.querySelector('.heading-source');
+        if (heading) {
+          heading.onclick = function () {
+            if (info.style.display === "none")
                 info.style.display = "block";
             else
                 info.style.display = "none";
+          }
         }
     }
 }

scribble-lib/scribble/manual-style.css

@@ -31,6 +31,30 @@
     font-size: 1rem;
 }
 
+/** Begin headings */
+
+/* Hide the button group by default, but show them on hovering the heading title */
+.heading:hover > .button-group {
+    visibility: visible;
+}
+.button-group {
+    visibility: hidden;
+}
+
+.heading-anchor {
+    font-size: 60%;
+    /* A trick to color an emoji from https://stackoverflow.com/questions/32413731/color-for-unicode-emoji */
+    color: transparent;
+    text-shadow: 0 0 0 gray;
+    vertical-align: 5%;
+}
+.heading-source {
+    cursor: pointer;
+    user-select: none;
+    color: gray;
+}
+/** End headings */
+
 /* embolden the "Racket Guide" and "Racket Reference" links on the TOC */
 /* there isn't an obvious tag in the markup that designates the top TOC page, which is called "start.scrbl" */
 /* nor a tag that designates these two links as special */