Next: Context-sensitive commands, Previous: Add-on packages, Up: Hacking

### A.3 Adding hyperlink types

Org has a large number of hyperlink types built-in (see Hyperlinks). If you would like to add new link types, Org provides an interface for doing so. Let's look at an example file, `org-man.el`, that will add support for creating links like ‘`[[man:printf][The printf manpage]]`’ to show Unix manual pages inside Emacs:

         ;;; org-man.el - Support for links to manpages in Org

         (require 'org)

         (org-add-link-type "man" 'org-man-open)
         (add-hook 'org-store-link-functions 'org-man-store-link)

         (defcustom org-man-command 'man
           "The Emacs command to be used to display a man page."
           :group 'org-link
           :type '(choice (const man) (const woman)))

         (defun org-man-open (path)
           "Visit the manpage on PATH.
         PATH should be a topic that can be thrown at the man command."
           (funcall org-man-command path))

         (defun org-man-store-link ()
           "Store a link to a manpage."
           (when (memq major-mode '(Man-mode woman-mode))
             ;; This is a man page, we do make this link
             (let* ((page (org-man-get-page-name))
                    (link (concat "man:" page))
                    (description (format "Manpage for %s" page)))
               (org-store-link-props
                :type "man"
                :link link
                :description description))))

         (defun org-man-get-page-name ()
           "Extract the page name from the buffer name."
           ;; This works for both `Man-mode' and `woman-mode'.
           (if (string-match " \\(\\S-+\\)\\*" (buffer-name))
               (match-string 1 (buffer-name))
             (error "Cannot create link to this man page")))

         (provide 'org-man)

         ;;; org-man.el ends here

You would activate this new link type in `.emacs` with

         (require 'org-man)

Let's go through the file and see what it does.

1. It does `(require 'org)` to make sure that `org.el` has been loaded.
2. The next line calls `org-add-link-type` to define a new link type with prefix ‘`man`’. The call also contains the name of a function that will be called to follow such a link.
3. The next line adds a function to `org-store-link-functions`, in order to allow the command `C-c l` to record a useful link in a buffer displaying a man page.

The rest of the file defines the necessary variables and functions. First there is a customization variable that determines which Emacs command should be used to display man pages. There are two options, `man` and `woman`. Then the function to follow a link is defined. It gets the link path as an argument—in this case the link path is just a topic for the manual command. The function calls the value of `org-man-command` to display the man page.

Finally the function `org-man-store-link` is defined. When you try to store a link with `C-c l`, this function will be called to try to make a link. The function must first decide if it is supposed to create the link for this buffer type; we do this by checking the value of the variable `major-mode`. If not, the function must exit and return the value `nil`. If yes, the link is created by getting the manual topic from the buffer name and prefixing it with the string ‘`man:`’. Then it must call the command `org-store-link-props` and set the `:type` and `:link` properties. Optionally you can also set the `:description` property to provide a default for the link description when the link is later inserted into an Org buffer with `C-c C-l`.

When it makes sense for your new link type, you may also define a function `org-PREFIX-complete-link` that implements special (e.g. completion) support for inserting such a link with `C-c C-l`. Such a function should not accept any arguments, and return the full link with prefix.