Emacs, scripting and anything text oriented.

Improving ox-hugo exported Org "info:" links

Kaushal Modi

In my previous post, I talked about how info: Org link export support got added to ox-hugo. This post is about making those exported links a tiny 🤏 bit better.

After writing my previous post, I had shared its link on the Org mode mailing list  For folks who don’t know, you can email the Org mode mailing list (emacs-orgmode@gnu.org) about pretty much anything Org mode related: any help you want, a bug you want to report, a patch you want to submit, or just share your positive or negative experiences with Org mode or thank someone for their awesome work. here, and received some helpful feedback from Max Nikulin.

        Thank you Max!

This post is a response to his feedback, and it also describes a few improvements made for info: link exports in ox-hugo based on that.

The commits for this info: link export improvements can be found in ox-hugo PR # 620.

  For <info:emacs#Browse-URL> export to html produces the following link:
  I think, a better variant is
  even though for the Org manual I often prefer single-page HTML version.

I really liked this suggestion!

  • Earlier, the Info node references were exporting to an anchor on a huge single-page HTML manual e.g. emacs.html#Browse_002dURL
  • After implementing this fix, the exported link points to a separate HTML page for that node e.g. emacs/Browse_002dURL.html.

Now, [[info:emacs#Screen]] exports and renders to Emacs Info: Screen, and a Top level node like [[info:emacs#Top]] exports and renders to Emacs Info.

For consistency, all info: links will now be exported to URLs pointing to the separate node HTML pages, even for Org manual links.

(About an example info: link pointing to Org manual: [[info:org#Top]])
And the link target ideally should be https://orgmode.org/manual/index.html

This was another great suggestion!

By default, the Org manual info: links will export to URLs pointing to the Org manual shipped with Emacs. That manual will be associated with the Org mode version that shipped with the last stable version of Emacs. So depending on how long it has been since the last Emacs release, you could be referring to quite an older version of the Org manual.

If you install Org from GNU Elpa, you can get an update of the latest stable Org version every week There’s a related post on Org mode’s Release Flow that might interest you. And the manual hosted on https://orgmode.org gets updated every week as well. I would like to always refer to the latest Org manual with the latest fixes and documentation improvements, and so I agree with Max’s suggestion above.

Now [[info:org#Top]] exports and renders as Org Info and the Org manual nodes like [[info:org#Working with Source Code]] also export as a link to a page in that manual: Org Info: Working with Source Code.

  I would prefer
      info "(org) Top"
      Org Info: Top
  since the former may be pasted to M-x : or to shell command prompt.

I wanted the link descriptions in the exported markdown to be more “English” and understandable to people not familiar with the Emacs Info interface. So I decided to keep this mostly unchanged ..

I did not change the link description, but I did add a new HTML title attribute to the link. This attribute contains the Emacs Lisp code needed to access the Info manual from Emacs. The user will see the text from this attribute when they hover the mouse over the links. If you haven’t already discovered this feature, try hovering the mouse over that last link above and you should see this 😃 :

Figure 1: Hovering the mouse over the exported info: links will show the Emacs Lisp code for accessing the same node from Emacs

Figure 1: Hovering the mouse over the exported info: links will show the Emacs Lisp code for accessing the same node from Emacs

Of course, the user will still not be able to copy that text and paste in Emacs. But it will still provide them enough hint on how to access Info nodes in Emacs.

Here’s the version of the org-hugo--org-info-export function that handles the exports of info: links as of today (<2022-04-15 Fri>):

org-hugo--org-info-export function from ox-hugo

(defun org-hugo--org-info-export (path desc format)
  "Add support for exporting [[info:..]] links for `hugo' format."
  (let* ((parts (split-string path "#\\|::"))
         (manual (car parts))
         (node (or (nth 1 parts) "Top"))
         (title (format "Emacs Lisp: (info \\\"(%s) %s\\\")" manual node))
         (desc (or desc
                   (if (string= node "Top")
                       (format "%s Info" (capitalize manual))
                     (format "%s Info: %s" (capitalize manual) node))))
         ;; `link' below is mostly derived from the code in
         ;; `org-info-map-html-url'.
         (link (cond ((member manual org-info-emacs-documents)
                      (let ((manual-url (if (string= (downcase manual) "org")
                                          (format "https://www.gnu.org/software/emacs/manual/html_node/%s" manual)))
                            (node-url (if (string= node "Top")
                                        (concat (org-info--expand-node-name node) ".html"))))
                        (format "%s/%s" manual-url node-url)))
                     ((cdr (assoc manual org-info-other-documents)))
                      (concat manual ".html")))))
    (when (member format '(md hugo))
      (format "[%s](%s \"%s\")" desc link title))))
Code Snippet 1: ox-hugo's version of org-info-export (ol-info.el) function

Link to code in the repo

I will leave it as an exercise for the reader to map the lines in above code snippet to the features described in this post 🍀.

  1. Just for giggles, I am using 💪 as a replacement for “Improvement” ↩︎