Links, IDs and attachments

Emacs keys work too: C-c C-o opens, C-c C-l inserts, C-c l stores, C-c M-l / C-c C-M-l insert the last / all stored links, C-c C-x C-n and C-c C-x C-p move between links, C-c C-a attaches.

By default org.nvim conceals the brackets and the target of described links (the ui.conceal_links option, Emacs' org-link-descriptive). The cursor line still shows the full text in Insert mode, and <prefix>lt toggles the concealment for the whole buffer (links only: emphasis markers stay as they are).

Try: press <prefix>lt now.

Expect: the first example above now reads [[https://orgmode.org/manual/][the Org manual]] in full. Press <prefix>lt again and it shrinks back to "the Org manual".

Link syntax inside verbatim or code markup, comment lines and blocks is not a link for Org: it is not exported as a link and <prefix>ln (next link) skips it.

• In verbatim [[*Anatomy of a link]] or code https://x.org a link is text.

[[*Anatomy of a link]]  <- inside an example block: not a link either

The real link: 2.

Try: put the cursor on the heading "What is not a link" and press <prefix>ln.

Expect: the cursor skips the three fake links and lands on the [[ of the real link in the line "The real link: …". (In org.nvim, <CR> on the text of a fake link still follows it.)

Try: on the link Radio targets press 4<CR>.

Expect: the window splits; the new window shows the "Radio targets" heading, the old one stays here. Close it with :q.

On a headline (not on a link), <C-c><C-o> lists the links in the entry and lets you pick one, or "Open all links". On the tags of a headline it opens a tags agenda for the tag under the cursor instead.

<prefix>' (C-c ', the "edit special" key) follows the link under the cursor too, which is handy if you have remapped <CR>.

Try: on this link press <prefix>'.

Expect: the cursor is on "* Anatomy of a link". <C-o> comes back.

• Exact title: 5.2
• Different case and spacing: 5.2
• With a description: jump to the practice area
• The heading has a TODO keyword, priority, cookie and tags, which are ignored: still the same heading

Try: press <CR> on each of the links above, then <C-o> to return.

Expect: every one lands on the line "Target practice" (the one with TODO, [#B], a [0/0] cookie and the tag :practice:).

This heading is the destination of the links in the previous section.

A CUSTOM_ID property gives a heading a stable name that you choose. Links to it start with #. The headings "Anatomy of a link" and "Following links" above have the custom IDs anatomy and following.

• Go to "Anatomy of a link"
• 3

• [BROKEN LINK: no-such-id]

Try: follow each link.

Expect: the first two land on their headings; the last one shows the message "No match for custom ID: no-such-id" and the cursor stays here.

A dedicated target is <<text>> anywhere in the text; a link [[text]] jumps to it. The target itself is shown in a special colour.

• A link to the 5.4 further down.
• The same target, found despite the capitals: here.

Some filler text so the jump is visible. Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore.

This line is the , where the two links above land.

Try: press <CR> on "parking spot" in the first item.

Expect: the cursor is on the <<parking spot>> target in the last paragraph.

A link can also point to any element with a #+NAME: line: a table, a block, a list, a paragraph.

• Jump to the table named No description for this link.
• Jump to the block named the hello block.

echo "hello"

Try: press <CR> on "prices" in the first item.

Expect: the cursor lands on the #+NAME: prices line above the table.

Inside a source or example block, a line can end with (ref:label). The link [[(label)]] jumps to that line.

local total = 0
for i = 1, 10 do (loop)
  total = total + i (add)
end
print(total)

In line loop we start the loop, and line the addition adds each number.

Try: press <CR> on (loop) in the sentence above.

Expect: the cursor jumps to the line for i = 1, 10 do (ref:loop) in the block.

When a [[words]] link finds no target, name or headline, org.nvim asks "No match - create this as a new heading?" (the default of links.search_must_match_exact_headline, "query-to-create"). Answer y and the heading is added at the end of this file; answer n and you get "No match for fuzzy expression: …".

• [BROKEN LINK: A heading that does not exist yet]

Try: press <CR> on the link above and answer n.

Expect: the message "No match for fuzzy expression: A heading that does not exist yet". Do it again and answer y: a new heading "A heading that does not exist yet" appears at the very end of the file and the cursor is on it. Press u to remove it again.

Add ::something after the file name to jump somewhere inside the file:

• [BROKEN LINK: 18]

• the Tables section of the tutorial
• start of the footnotes file

• the tutorial's footnotes

• [BROKEN LINK: agenda_files]

• every description line

• every "radio" in this file

Try: follow "line 18 of the init file".

Expect: minimal_init.lua opens in another window with the cursor on line 18, vim.opt.termguicolors = true.

Try: follow "every description line".

Expect: the init file opens and a location list lists the lines containing =description = = (one per capture template and custom agenda command), and the message "8 matches for description = ".

Try: follow "every "radio" in this file".

Expect: this buffer turns into a sparse tree: only the headings with a match are unfolded and the matches are highlighted. <S-Tab> brings back the normal view.

• A file name with a wildcard (*, ?, {) lists the matching files: all Org files in examples/. In the list, <CR> opens the file on the line and q closes it.
• file+sys:path always uses the system application and file+emacs:path always opens the file in Neovim. Emacs considers both deprecated (:Org lint says so): prefer a count on an ordinary file: link, 4<CR> for Neovim and 16<CR> for the system application.
• Files Neovim cannot show (images, PDF, office documents, HTML) open with the system application: a screenshot. links.file_apps changes that per extension.

Try: press <CR> on "all Org files in examples/".

Expect: a scratch buffer that starts with the directory name and "wildcard *.org", then lists 00-index.org, 01-outline.org … tutorial.org, one per line. Put the cursor on 14-footnotes.org and press <CR> to open it; q closes the list.

shell: links run a command in the directory of this file. For safety, org.nvim asks first (links.confirm_shell). The output goes to a new *Org Shell Output* buffer, or is echoed when it is one line.

• say hello

• list the example files

Try: press <CR> on "say hello" and answer y.

Expect: the question Execute echo "hello from a link" in shell? and, after y, the message hello from a link.

Try: press <CR> on "list the example files" and answer y.

Expect: a window *Org Shell Output* with one file name per line (00-index.org, 01-outline.org, …).

elisp: links evaluate Emacs Lisp in a separate emacs --batch process (you need Emacs installed; it cannot touch your Neovim buffers). They ask first too (links.confirm_elisp):

• add 1 + 2 + 3 in Emacs

Expect: the question Execute (+ 1 2 3) as Elisp? and, after y, the message (+ 1 2 3) => 6.

<prefix>ls works in any buffer, not only Org files. What it stores depends on where you are:

With links.use_id = true headings are stored as id: links instead (and get an ID property).

<prefix>li asks for the link. The prompt completes stored links, link types (https:, file:, id:, gh: …) and file names. An empty answer inserts the last stored link. Then it asks for a description, pre-filled with the stored one: edit it, or clear it with <C-u> for none.

• On an existing link, <prefix>li edits it: the prompt starts with its target, then its description.
• In Visual mode, the selected text becomes the description.
• Stored links are removed from the list once inserted (links.keep_stored_after_insertion).
• Links to places in the same file are shortened: file:13-links.org::*X is inserted as [[*X]].

In Insert mode, after [[ press <C-x><C-o> (or let blink.cmp / nvim-cmp do it): link types and stored links are offered; after [[* the headings of this file; after [[# the custom IDs.

Try: on the empty line below, type [[*Rad in Insert mode and press <C-x><C-o>.

Expect: "Radio targets" is offered. Accept it and close the link with ]].

This entry has an ID. Links to it:

• this entry, by ID

• [BROKEN LINK: 7f3c9a52-1d2e-4c6b-9a0f-13a1b2c3d4e5::*A child without an ID]
• [BROKEN LINK: 7f3c9a52-1d2e-4c6b-9a0f-13a1b2c3d4e5::hidden spot]

This line holds the the third link goes to.

Try: follow the three links (from here, or after moving this entry around with <M-j>: IDs don't care where the entry is).

Expect: the first lands on the heading "An entry with an ID", the second on its child "A child without an ID", the third on the line "This line holds the …".

The footnotes example file has an entry with the ID 0f5e2d1c-7b3a-4e8f-9c6d-14f00e1d2c3b:

• [BROKEN LINK: 0f5e2d1c-7b3a-4e8f-9c6d-14f00e1d2c3b]

Try: follow the link.

Expect: 14-footnotes.org opens in another window, on the heading "Named footnotes" (org.nvim scanned the agenda files to find the ID and recorded where it is).

<prefix>A (C-c C-a) on a headline opens this menu:

This entry's attachment directory is docs/media of the repository, so these links work without attaching anything first:

• the column view screenshot
• the media README

Try: press <CR> on "the media README".

Expect: docs/media/README.md opens in another window.

Try: on this entry's headline, press <prefix>A then F.

Expect: the docs/media directory opens in Neovim (netrw or your file explorer).