feat(org): add kbd & doom-{module,package}} links

I make extensive use of these in our new in-repo Org documentation.

modules/lang/org/autoload/org-link.el

@@ -9,6 +9,19 @@
   (let ((file (funcall (or fn #'read-file-name) (format "%s: " (capitalize key)) dir)))
     (format "%s:%s" key (file-relative-name file dir))))
 
+;;;###autoload
+(defun +org-read-link-description-at-point (&optional default context)
+  "TODO"
+  (if (and (stringp default) (not (string-empty-p default)))
+      (string-trim default)
+    (if-let* ((context (or context (org-element-context)))
+              (context (org-element-lineage context '(link) t))
+              (beg (org-element-property :contents-begin context))
+              (end (org-element-property :contents-end context)))
+        (unless (= beg end)
+          (replace-regexp-in-string
+           "[ \n]+" " " (string-trim (buffer-substring-no-properties beg end)))))))
+
 ;;;###autoload
 (defun +org-define-basic-link (key dir-var &rest plist)
   "Define a link with some basic completion & fontification.
@@ -154,3 +167,81 @@ exist, and `org-link' otherwise."
   (or (+org-play-gif-at-point-h)
       (user-error "No gif at point")))
 
+
+;;
+;;; Org-link parameters
+
+;;; doom-module:
+(defun +org-link--doom-module--read-link (link)
+  (cl-destructuring-bind (category &optional module flag)
+      (let ((desc (+org-read-link-description-at-point link)))
+        (if (string-prefix-p "+" (string-trim-left desc))
+            (list nil nil (intern desc))
+          (mapcar #'intern (split-string desc " " nil))))
+    (list :category category
+          :module module
+          :flag flag)))
+
+;;;###autoload
+(defun +org-link--doom-module-follow-fn (link)
+  (cl-destructuring-bind (&key category module flag)
+      (+org-link--doom-module--read-link link)
+    (when category
+      (if-let* ((path (doom-module-locate-path category module))
+                (path (or (car (doom-glob path "README.org"))
+                          path)))
+          (find-file path)
+        (user-error "Can't find Doom module '%s'" link)))
+    (when flag
+      (goto-char (point-min))
+      (and (re-search-forward "^\\*+ \\(?:TODO \\)?Module Flags")
+           (re-search-forward (format "^\\s-*- %s :: "
+                                      (regexp-quote (symbol-name flag)))
+                              (save-excursion (org-get-next-sibling)
+                                              (point)))
+           (recenter)))))
+
+;;;###autoload
+(defun +org-link--doom-module-face-fn (link)
+  (cl-destructuring-bind (&key category module flag)
+      (+org-link--doom-module--read-link link)
+    (if (doom-module-locate-path category module)
+        `(:inherit org-priority
+          :weight bold)
+      'error)))
+
+
+;;; doom-package:
+;;;###autoload
+(defun +org-link--doom-package-follow-fn (link)
+  "TODO"
+  (doom/describe-package
+   (intern-soft
+    (+org-read-link-description-at-point link))))
+
+
+;;; kbd:
+
+(defun +org--describe-kbd (keystr)
+  (dolist (key `(("<leader>" . ,doom-leader-key)
+                 ("<localleader>" . ,doom-localleader-key)
+                 ("<prefix>" . ,(if (bound-and-true-p evil-mode)
+                                    (concat doom-leader-key " u")
+                                  "C-u"))
+                 ("<help>" . ,(if (bound-and-true-p evil-mode)
+                                  (concat doom-leader-key " h")
+                                "C-h"))
+                 ("\\<M-" . "alt-")
+                 ("\\<S-" . "shift-")
+                 ("\\<s-" . "super-")
+                 ("\\<C-" . "ctrl-")))
+    (setq keystr
+          (replace-regexp-in-string (car key) (cdr key)
+                                    keystr t t)))
+  keystr)
+
+;;;###autoload
+(defun +org-read-kbd-at-point (&optional default context)
+  "TODO"
+  (+org--describe-kbd
+   (+org-read-link-description-at-point default context)))

modules/lang/org/config.el

@@ -182,8 +182,25 @@ Is relative to `org-directory', unless it is absolute. Is used in Doom's default
   (defadvice! +org-display-link-in-eldoc-a (&rest _)
     "Display full link in minibuffer when cursor/mouse is over it."
     :before-until #'org-eldoc-documentation-function
-    (when-let (link (org-element-property :raw-link (org-element-context)))
+    (when-let* ((context (org-element-context))
-      (format "Link: %s" link)))
+                (path (org-element-property :path context)))
+      (pcase (org-element-property :type context)
+        ("kbd"
+         (format "%s %s"
+                 (propertize "Key sequence:" 'face 'bold)
+                 (propertize (+org-read-kbd-at-point path context)
+                             'face 'help-key-binding)))
+        ("doom-module"
+         (format "%s %s"
+                 (propertize "Doom module:" 'face 'bold)
+                 (propertize (+org-read-link-description-at-point path)
+                             'face 'org-priority)))
+        ("doom-package"
+         (format "%s %s"
+                 (propertize "Doom package:" 'face 'bold)
+                 (propertize (+org-read-link-description-at-point path)
+                             'face 'org-priority)))
+        (type (format "Link: %s" (org-element-property :raw-link context))))))
 
   ;; Automatic indent detection in org files is meaningless
   (add-to-list 'doom-detect-indentation-excluded-modes 'org-mode)
@@ -471,7 +488,7 @@ relative to `org-directory', unless it is an absolute path."
 
 
 (defun +org-init-custom-links-h ()
-  ;; Highlight broken file links
+  ;; Modify default file: links to colorize broken file links red
   (org-link-set-parameters
    "file"
    :face (lambda (path)
@@ -482,7 +499,7 @@ relative to `org-directory', unless it is an absolute path."
                'org-link
              '(warning org-link))))
 
-  ;; Add custom link types
+  ;; Additional custom links for convenience
   (pushnew! org-link-abbrev-alist
             '("github"      . "https://github.com/%s")
             '("youtube"     . "https://youtube.com/watch?v=%s")
@@ -499,6 +516,22 @@ relative to `org-directory', unless it is an absolute path."
   (+org-define-basic-link "doom-docs" 'doom-docs-dir)
   (+org-define-basic-link "doom-modules" 'doom-modules-dir)
 
+  ;; Add "lookup" links for packages and keystrings; useful for Emacs
+  ;; documentation -- especially Doom's!
+  (org-link-set-parameters
+   "kbd"
+   :follow (lambda (_) (minibuffer-message "%s" (+org-display-link-in-eldoc-a)))
+   :help-echo #'+org-read-kbd-at-point
+   :face 'help-key-binding)
+  (org-link-set-parameters
+   "doom-package"
+   :follow #'+org-link--doom-package-follow-fn
+   :face (lambda (_) '(:inherit org-priority :slant italic)))
+  (org-link-set-parameters
+   "doom-module"
+   :follow #'+org-link--doom-module-follow-fn
+   :face #'+org-link--doom-module-face-fn)
+
   ;; Allow inline image previews of http(s)? urls or data uris.
   ;; `+org-http-image-data-fn' will respect `org-display-remote-inline-images'.
   (setq org-display-remote-inline-images 'download) ; TRAMP urls