From 8f0e2ade53056c8eab9d9174425b0ccf7df84857 Mon Sep 17 00:00:00 2001
From: Sorawee Porncharoenwase <sorawee.pwase@gmail.com>
Date: Fri, 13 Oct 2023 14:36:09 +0700
Subject: [PATCH] feat: add explicit buttons to heading titles

This commit adds two buttons to each heading title.

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.
---
 scribble-lib/scribble/html-render.rkt  | 30 ++++++++++++++++++++------
 scribble-lib/scribble/manual-racket.js |  9 +++++---
 scribble-lib/scribble/manual-style.css | 15 +++++++++++++
 3 files changed, 45 insertions(+), 9 deletions(-)

diff --git a/scribble-lib/scribble/html-render.rkt b/scribble-lib/scribble/html-render.rkt
index e26cca4589..e0480079e9 100644
--- a/scribble-lib/scribble/html-render.rkt
+++ b/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
@@ -1170,14 +1171,31 @@
                                   '())
                               (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)
+                          " "
+                          ,@(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
diff --git a/scribble-lib/scribble/manual-racket.js b/scribble-lib/scribble/manual-racket.js
index 1ca4116213..6864c001ee 100644
--- a/scribble-lib/scribble/manual-racket.js
+++ b/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";
+          }
         }
     }
 }
diff --git a/scribble-lib/scribble/manual-style.css b/scribble-lib/scribble/manual-style.css
index a4a179cde6..310a3b2538 100644
--- a/scribble-lib/scribble/manual-style.css
+++ b/scribble-lib/scribble/manual-style.css
@@ -31,6 +31,21 @@
     font-size: 1rem;
 }
 
+.heading-anchor {
+    font-size: 40%;
+    /* 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: 10%;
+}
+
+.heading-source {
+    font-size: 70%;
+    cursor: pointer;
+    user-select: none;
+    color: gray;
+}
+
 /* 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 */