Variable: denote-org-store-link-to-heading

denote-org-store-link-to-heading is a customizable variable defined in denote.el.

Value

nil

Documentation

Determine 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:

    [[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:

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

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.

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:

    [[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. ]

This variable was added, or its default value changed, in denote version 4.0.0.

Source Code

;; Defined in ~/.emacs.d/elpa/denote-4.2.3/denote.el
(defcustom denote-org-store-link-to-heading nil
  "Determine 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:

    [[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:

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

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.

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:

    [[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.  ]"
  :group 'denote
  :package-version '(denote . "4.0.0")
  :type '(choice (const :tag "No link to heading (default)" nil)
                 (const :tag "Link to the context" context)
                 (const :tag "Link wtih CUSTOM_ID, creating it if needed" id)))