Linking and Exporting Org "info:" links

This post was inspired out of the exercise of support info: Org link exports in ox-hugo.

There are 3 steps:

1. Storing a link from any buffer that you want to later document in an Org file.
2. Inserting that link that you stored earlier.
3. Exporting the Org document.

I am focusing on the info: Org links in this post, they these steps apply to any Org link type.

1 Storing links to Info nodes #

If you follow the instructions on Org Info: Activation, you’ll see that it is recommended  This post assumes that you have actually set this binding. If you haven’t yet, go do it already! (global-set-key (kbd "C-c l") #'org-store-link) to bind the org-store-link command to C-c l in your Emacs global map.

org-store-link stores an Org Mode compatible link based on the context i.e. type of buffer where the point is. Org supports a variety of links as documented in Org Info: External Links.

If the point is in an ∗Info∗ buffer and org-store-link is called, it stores an info: type link that will lead back to the same node where the point was.

Let’s say you have opened the Org Info manual and you hit C-c l. You should then see this in the Echo Area:

Stored: org#Top

The link to Org manual’s Top node is stored by that command, but only temporarily – it isn’t yet saved anywhere.

2 Inserting stored links #

These stored links can now be saved in an Org file. To do that,

• Visit an Org file or a buffer and call M-x org-insert-link (bound to C-c C-l by default) and follow the prompts.
• An immediate RET after the prompt will select the last stored link to be inserted.
• The second prompt allows you to change the link description, and then the link will be inserted.

If I insert the org#Top Info link that I stored earlier over here, and accept the default link description, it will paste as [[info:org#Top][org#Top]].

But .. how did the link description become “org#Top” by default?

Org Link library for info: links (ol-info) #

The default description for info: type links was set at the time of storing those links, with the help of the org-info-store-link function in ol-info.el. That same description is then suggested at the time of inserting that link.

This library defines these “actions” for [[info:..]] type of links:

:store

Defines when (in which buffer, major mode, etc.) the “store” operation should store to an info: type link, and what metadata should be stored. Some of the stored metadata are: the Info file name, node name, link string and description string.

:follow

Defines what action to perform when org-open-at-point (C-c C-o) is called with point on the link. Hitting this binding with point on an info: link will open or switch to that ∗Info∗ node.

:export

Defines how the link should be exported for various backends. ol-info defines how the info: links should be exported, but only for html and texinfo backends.

3 Exporting [[info:..]] links using ox-hugo #

ol-info.el defines the :export “action” such that info: links get converted to hyperlinks pointing to online Org manual pages, when exporting using ox-html.

But it didn’t do the same when exporting using ox-hugo. That feature got added recently in this ox-hugo commit. Now ox-hugo exports [[info:org#Top][org#Top]] to org#Top.

I didn’t like the # that org-info-store-link added to the default description (notice that previous link). So I added a tiny little feature to the info: export behavior 😁 — If you leave the info: link descriptions empty when inserting the links, ox-hugo injects its own “auto description” which are better (in my opinion).

Now when that same Info link is inserted description-less as [[info:org#Top]], it renders to: Org Info.

Summary #

1. Store link (from anywhere in Emacs) : C-c l
2. Insert link (in an Org file) : C-c C-l
3. Export the Org file as usual.