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
For folks who don’t know, you can email the Org mode mailing list
email@example.com) 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: https://www.gnu.org/software/emacs/manual/html_mono/emacs.html#Browse_002dURL I think, a better variant is https://www.gnu.org/software/emacs/manual/html_node/emacs/Browse_002dURL.html 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.
- After implementing this fix, the exported link points to a separate
HTML page for that node e.g.
For consistency, all
info: links will now be exported to URLs
pointing to the separate node HTML pages, even for Org manual links.
💪 2: Export Org manual links to
orgmode.org URLs #
- (About an example
info:link pointing to Org manual:
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
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.
[[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.
💪 3: Link hover text shows the elisp code for accessing the Info node #
I would prefer info "(org) Top" to 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 😃 :
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.
Final code in
ox-hugo that exports the
info: links #
Here’s the version of the
org-hugo--org-info-export function that
handles the exports of
info: links as of today ( ):
org-hugo--org-info-export function from
(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
(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))))
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 🍀.
Just for giggles, I am using 💪 as a replacement for “Improvement” ↩︎