Create links with auto backlinks is the general idea.
I’m trying to keep this as flexible as possible. There are a few different ways to use this to support different use cases and workflows. See Usage for a more detailed explanation. There are also a few tips and useful functions on the wiki tips page.
I also want to keep this as close to pure org-mode as possible. No external db, no functions required for reading, etc. It should function as just a regular org-mode file. This makes it much more usable for me on my phone. Using beorg or organice for example. It also allows the links to function as normal for exporting and things like that. It’s just pure org.
Everybody loves screenshots, right?
org-super-links-link
related drawer
capture template
View the org source to get a better idea of how this looks.
* TODO Test heading target :PROPERTIES: :ID: 02a5da87-46e5-4ae0-85c1-ee63a570270a :END: :BACKLINKS: [2020-04-11 Sat 00:26] <- [[id:3835d3d0-931a-4a45-a015-a3d6a0baa99a][This has a link]] :END: This has a backlink as you can see from the BACKLINKS drawer above. * TODO This has a link :PROPERTIES: :ID: 3835d3d0-931a-4a45-a015-a3d6a0baa99a :END: This has a link pointing to the heading above [[id:02a5da87-46e5-4ae0-85c1-ee63a570270a][Test heading target]]
Maybe someday I’ll put this on melpa, but it is not currently.
I personally use straight and use-package for package management. It’s pretty nice.
Install develop branch using straight.
(use-package org-super-links
:straight (org-super-links :type git :host github :repo "toshism/org-super-links" :branch "develop")
:bind (("C-c s s" . org-super-links-link)
("C-c s l" . org-super-links-store-link)
("C-c s C-l" . org-super-links-insert-link)))You can also use quelpa with quelpa-use-package. Example basic configuration using quelpa:
(use-package org-super-links
:quelpa (org-super-links :repo "toshism/org-super-links" :fetcher github :commit "0.4")
:bind (("C-c s s" . org-super-links-link)
("C-c s l" . org-super-links-store-link)
("C-c s C-l" . org-super-links-insert-link)))The idea is to keep this as simple as possible and not enforce any particular system or workflow, but to be flexible enough to support many. It’s a simple concept, when you insert a link, insert a backlink at the target.
There are a few different ways you can use this to integrate into your preferred workflow.
Use it just like you would use regular org links. Instead of calling org-store-link call org-super-links-store-link. Then to insert the link instead of org-insert-link call org-super-links-insert-link. That will insert a link as normal while also adding a backlink at the target of the link. This should work the same as regular org links, with the benefit of adding the backlink.
To create a link at point call org-super-links-link. That will bring up the configured search interface (helm-org-ql by default) and allow you to select the target. Once selected a link will be inserted at point, and a backlink added to target.
There is also a helm-org-ql and helm-org-rifle action. To use this method, with the point at the place you would like the link, call helm-org-ql / helm-org-rifle. Select the target of the link and from the actions menu choose Super Link. A link pointing to the selected candidate will be created at point, and a backlink will be added to the target.
Whenever org-capture is called a link to the current point is automatically stored. To insert this link simply call org-super-links-insert-link. The backlink will be created automatically as usual.
Creates a link ignoring the org-super-links-related-into-drawer and org-super-links-link-prefix settings and inserts a link with no prefix at point.
The inverse of org-super-links-quick-insert-inline-link. Insert a link ignoring the org-super-links-related-into-drawer and org-super-links-link-prefix settings. Inserts a link using org-super-links-link-prefix-timestamp for the prefix and either org-super-links-related-into-drawer or org-super-links-related-drawer-default-name for the drawer name. org-super-links-related-into-drawer has precedence if it’s set to a string.
Delete the link at point, and the corresponding reverse link. If no reverse link exists, just delete link at point. This works from either side, and deletes both sides of a link.
Convert a normal org-mode link at `point’ to super link. If
org-super-links-related-into-drawer is non-nil move the link into drawer.
When called interactively with a C-u prefix argument ignore
org-super-links-related-into-drawer configuration and do not modify existing
link. Only add the backlink.
The variables below allow quite a bit of flexibility to allow you to fit org-super-links into your workflow. None of these are required. My personal config is here
Controls how/where to insert the backlinks. If non-nil a drawer will be created and backlinks inserted there. The default is BACKLINKS. If this is set to a string a drawer will be created using that string. For example LINKS. If nil backlinks will just be inserted under the heading.
Default: t
Prefix to insert before the backlink.
This can be a string, nil, or a function that takes no arguments and returns a string.
Default is the function org-super-links-backlink-prefix-timestamp which returns
an inactive timestamp formatted according to the variable
org-time-stamp-formats and a separator ` <- `.
Postfix to insert after the backlink. This can be a string, nil, or a function that takes no arguments and returns a string
Default nil
Controls how/where to insert links.
If non-nil a drawer will be created and links inserted there. The
default is org-super-links-related-drawer-default-name. If this is set to a
string a drawer will be created using that string. For example LINKS.
If nil links will just be inserted at point.
Default: nil
Default name to use for link drawer if org-super-links-related-into-drawer is
t. See org-super-links-related-into-drawer for more info. This is also used
when calling org-super-links-quick-insert-drawer-link if
org-super-links-related-into-drawer is nil.
Default: RELATED
Prefix to insert before the link.
This can be a string, nil, or a function that takes no arguments and
returns a string
Default nil
Postfix to insert after the link.
This can be a string, nil, or a function that takes no arguments and
returns a string
Default nil
What to use if no description is provided.
This can be a string, nil or a function that accepts two arguments
LINK and DESC and returns a string.
nil will return the default desciption or the link.
string will be used only as a default fall back if set.
function will be called for every link.
Default is the variable org-make-link-desciption-function.
The interface to use for finding target links.
This can be a string with one of the values ‘helm-org-ql’,
‘helm-org-rifle’, or a function. If you provide a custom
function it will be called with the `point` at the location the link
should be inserted. The only other requirement is that it should call
the function org-super-links--insert-link with the buffer and pos of the
target link. AKA the place you want the backlink.
Using helm-org-ql or helm-org-rifle will also add a new action to the respective action menu.
See the functions org-super-links-get-location (in the org-super-links.el file) or org-super-links-org-ql-link-search-interface (in org-super-links-org-ql.el) for examples.
Default is set based on currently installed packages. In order of priority:
- “helm-org-ql”
- “helm-org-rifle”
org-super-links-get-location
org-super-links-get-location internally uses org-refile-get-location.
These are just a few tips on things you can do that may be interesting or helpful.
When creating links it’s generally better to use an id. Add this to your config file so that any headings you link to or from get an id added automatically. I would strongly recommend using this.
(require 'org-id)
(setq org-id-link-to-org-use-id 'create-if-interactive-and-no-custom-id)OUTDATED: I’ve added two functions to replace these. org-super-links-quick-insert-drawer-link and org-super-links-quick-insert-inline-link. I’ll leave these here in case someone may still be interested for some reason.
Often when I’m writing I just want to quickly add a link to another heading that may be related. I found it’s convenient to use something like this.
(defun org-super-links-quick-related ()
(interactive)
(let ((org-super-links-link-prefix "\nrelated: "))
(org-super-links-link)))
(global-set-key (kbd "C-c s r") 'org-super-links-quick-related)Since org-super-links automatically stores the current heading any time you call org-capture. I use this one a lot to just quickly insert a link in the capture template without necessarily wanting to explain the context before I start writing.
(defun org-super-links-quick-insert-related ()
(interactive)
(let ((org-super-links-link-prefix "\nrelated: "))
(org-super-links-insert-link)))
(global-set-key (kbd "C-c s i") 'org-super-links-quick-insert-related)These quick related links make me think I should possibly add the option to log links into a drawer too. I find myself wanting to do this reasonably often. If anybody else feels the same I’ll probably add that option.
Sometimes heading titles can get a bit long. You can define a custom function to limit their length and set org-super-links-default-description-formatter. Here’s a very naive way to keep them short. This will blindly truncate all link descriptions to a maximum of 20 characters. You could come up with a more sophisticated function for limiting the length by words or something.
(defun org-super-links-truncate-description (link desc)
(truncate-string-to-width desc 20))
(setq org-super-links-default-description-formatter 'org-super-links-truncate-description)The default value of org-super-links-default-description-formatter is set to org-make-link-description so you can also set that to apply the changes to all org-mode links globally.
I’ve found it’s useful to create “index headlines” to make navigating notes convenient. For example I have a hierarchy of locations I use for location specific notes such as restaurant recommendations or vacation planning. These often end up being just a heading with a bunch of backlinks from various notes.
* Locations
** Germany :germany:
*** Berlin :berlin:
:BACKLINKS:
[2020-04-11 Sat 00:26] <- [[id:3835d3d0-931a-4a45-a015-a3d6a0baa99a][some restaurant]]
:END:
*** Wuerzburg :wuerzburg:
:BACKLINKS:
[2020-05-21 Sat 00:26] <- [[id:3835d3d0-931a-4a45-a015-a3d6a0baa99a][some other thing]]
[2020-04-11 Sat 00:26] <- [[id:3835d3d0-931a-4a45-a015-a3d6a0baa99][So and so's house]]
:END:
** USA
*** Texas :texas:
**** Amarillo :amarillo:
:BACKLINKS:
[2020-05-21 Sat 00:26] <- [[id:3835d3d0-931a-4a45-a015-a3d6a0baa99a][yeah again]]
[2020-04-11 Sat 00:26] <- [[id:3835d3d0-931a-4a45-a015-a3d6a0baa99a][rental car place]]
:END:
**** Austin :austin:
etc...
I do a similar thing for any topic I find myself creating a lot of notes for but that I may not want to be under the same heading, or if I want it under multiple headings.
This combination of tags and index headings makes it easy to find things.
(use-package org-super-links
:quelpa (org-super-links :repo "toshism/org-super-links" :fetcher github :commit "develop")
:bind (("C-c s s" . org-super-links-link)
("C-c s l" . org-super-links-store-link)
("C-c s C-l" . org-super-links-insert-link)
("C-c s d" . org-super-links-quick-insert-drawer-link)
("C-c s i" . org-super-links-quick-insert-inline-link)
("C-c s C-d" . org-super-links-delete-link))
:config
(setq org-super-links-related-into-drawer t
org-super-links-link-prefix 'org-super-links-link-prefix-timestamp))
Over time I’ve grown to prefer to just add links and backlinks both into drawers. I map C-c s i to org-super-links-quick-insert-inline-link for the rare occasion where I want a link inline. This ends up functioning sort of zettelkasten style.
This is not specific to org-super-links but I like to set the face for drawers to be fairly small and the color close to the background. It helps keep things from looking cluttered when the drawers are collapsed.
I use something like this in my theme.
(org-drawer :foreground "#2F3841" :height 0.8)That will make the drawer quite small when collapsed but the text inside full size when expanded.
If you export subheadings from your org file that have links/backlinks you may want to set org-export-with-broken-links to t. Otherwise you may see an error like
user-error: Unable to resolve link: "*Heading with a backlink"
See issue #22
org-super-links-peek - take a peek at your links
org-linker-edna - link headings as dependencies
org-linker - utility package to serve as a base for linking org headings in various ways
- fixed bug when linking to narrowed buffer
- fixed bug with converting links to super links when related-into-drawer nil
- refactor org-super-links–insert-link
- change prefix from sl- to org-super-links-
Bugfixes
- fixed incorrect link when backlink-into-drawer nil
[2020-09-21]
- add org-super-links-convert-link-to-super
- add delete link
- remove dependency on helm
- add org-super-links-get-location search function @piater
- add related into drawer option
- add quick inserts
- org-super-links-quick-insert-drawer-link
- org-super-links-quick-insert-inline-link
- switch to using markers internally for all positions
- add hooks
- org-super-links-pre-link-hook
- org-super-links-pre-backlink-hook
- license change to GPLv3
- support backlinks in org derived modes from @philScholl
Bugfixes
- fixed bug with org-capture prefix being swallowed (thanks! @piater)
- respect org-mode link configurations
- fix possible incorrect link location after buffer modified by hook(s)
- fix void-variable helm-org-ql-actions bug
[2020-04-25]
- Default target heading search changed to
helm-org-ql - Allow target heading search to be configurable through
org-super-links-search-function - Add more configuration options for link formatting
- Support for customizing the default link description
org-super-links-default-description-formatter
Bugfixes:
- fix issue when calling
org-capturefrom a non-org-mode buffer.
[2020-04-11] First release
Thanks to:
GPLv3
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent