Tips

Org-super-links is quite flexible and there have been a lot of good questions and tips come up. This just a bit of a dumping ground to accumulate those somewhere.

Use ids

Links are fragile without them.

org-id

you can use org-id to automatically generate an id if one doesn't exist when linking headings. org-id is included in org-mode. Add this somewhere in your config.

(require 'org-id)
(setq org-id-link-to-org-use-id 'create-if-interactive-and-no-custom-id)

Useful functions

Link to last capture

If you use org-capture it can be handy sometimes to link to the last thing you captured. This function will do that.

(defun org-super-links-related-to-last-capture ()
  (interactive)
  (org-super-links--insert-link org-capture-last-stored-marker))

I use it a lot when I'm capturing a stream of things. In this case I normally use it from within the next capture template.

Typical usage example is when I'm working on something and capturing a lot of notes about it. I will call org-capture to create a note, back to what I was working on. Call org-capture again for a new note related to the last. This time I'll call sl-related-to-last-capture from inside the new capture to link it to the previous. With this process I end up with a chain of related notes so that I can later follow my previous train of thought a bit and have a lot more context to the individual notes.

Create a new target and auto link to it

Use case: you are on a heading and want to create a new heading and link to it.

I use this similar to the way I use Link to last capture only when the "work" I'm doing is actually in an org file, maybe I'm writing about some subject or documenting something, whatever. Basically anytime I want to create a new note related to the heading I'm currently on.

(defun org-super-links-create-new-target ()
  (interactive)
  (add-hook 'org-capture-after-finalize-hook 'org-super-links-related-to-last-capture)
  (org-capture))

(defun org-super-links-related-to-last-capture ()
  (interactive)
  (org-super-links--insert-link org-capture-last-stored-marker)
  (remove-hook 'org-capture-after-finalize-hook 'org-super-links-related-to-last-capture))

org-super-links-create-new-target simply adds a hook to org-capture-after-finalize-hook that calls org-super-links-related-to-last-capture and then calls org-capture. org-super-links-related-to-last-capture is the same as in Link to last capture only it's modified to remove the org-capture-after-finalize-hook after it's called. It's a little hacky, but it works well.

The end effect is a newly created heading, through org-capture, that is auto linked to the current heading.

Remove statistics cookies from link descriptions

If you don't like the statistics cookies (dates, priorities, [1/4], etc.) from headings in your link descriptions, novoid came up with this to strip them out. see issue #25 for more details

  (defun my-org-super-links-filter-description (link desc)
      ;; replace double bracket links with their description
      (replace-regexp-in-string org-link-bracket-re "\\2"
          ;; removes: <2020-08-04 Tue>--<2020-08-04 Tue 23:37>  (2nd time/date-stamp is optional; including inactive variants)
          (replace-regexp-in-string org-element--timestamp-regexp ""
                ;; removes priority indicators such as [#A]
  	      (replace-regexp-in-string org-priority-regexp ""
                    ;; removes staistic cookies with absolute numbers such as [2/5]
         	          (replace-regexp-in-string " ?\\[[0-9]+/[0-9]\\]" "" 
                            ;; removes staistic cookies with percentages such as [33%]
           	          (replace-regexp-in-string " ?\\[[0-9]+%\\]" "" desc)
  			      ))))
  )

(setq org-super-links-default-description-formatter 'my-org-super-links-filter-description)