Emacs Docs

Appearance

The denote-org-store-link-to-heading user option ​

The user option denote-org-store-link-to-heading determines whether org-store-link links to the current Org heading.

[ Remember that what org-store-link does is merely collect a link. To actually insert it, use the command org-insert-link. Note that org-capture uses org-store-link internally when it needs to store a link. ]

When the value is nil, the Denote handler for org-store-link produces links only to the current file (by using the file’s identifier). For example:

bash
[[denote:20240118T060608][Some test]]

If the value is context, the link consists of the file’s identifier and the text of the current heading, like this:

bash
[[denote:20240118T060608::*Heading text][Some test::Heading text]].

If the value is local, the link consists of the text of the current heading, like this:

[[*Heading text][Heading text]].

[ The local option is part of 4.3.0-dev. ]

However, if there already exists a ‘CUSTOM_ID’ property for the current heading, this is always given priority and is used instead of the context or local heading.

If the value is id or, for backward-compatibility, any other non-nil value, then Denote will use the standard Org mechanism of the ‘CUSTOM_ID’ property to create a unique link to the heading. If the heading does not have a ‘CUSTOM_ID’, it creates it and includes it in its ‘PROPERTIES’ drawer. If a ‘CUSTOM_ID’ exists, it takes it as-is. The result is like this:

bash
[[denote:20240118T060608::#h:eed0fb8e-4cc7-478f][Some test::Heading text]]

The value of the ‘CUSTOM_ID’ is determined by the Org user option org-id-method. The sample shown above uses the default UUID infrastructure (though I deleted a few characters to not get complaints from the byte compiler about long lines in the doc string…).

Note that this option does not affect how Org behaves with regard to org-id-link-to-org-use-id. If that user option is set to create ‘ID’ properties, then those will be created by Org even if the Denote link handler will take care to not use/store the ‘ID’ value. Concretely, users who never want ‘ID’ properties under their headings should keep org-id-link-to-org-use-id in its nil value.

Context links are easier to break than those with a ‘CUSTOM_ID’ in cases where either the heading text changes or there is another heading that matches that text. The potential advantage of context links is that they do not require a ‘PROPERTIES’ drawer.

When visiting a link to a heading, Org opens the Denote file and then navigates to that heading.

[ This feature only works in Org mode files, as other file types do not have a linking mechanism that handles unique identifiers for headings or other patterns to jump to. If org-store-link is invoked in one such file, it captures only the Denote identifier of the file, even if this user option is set to a non-nil value. ]