Links

Write links as Org does, follow them with a key or a click, and see which headings link to the one you are reading.

Link syntax

orgstar reads links the way org-element-link-parser does. There are three forms.

Inside a bracket link, a target that starts with /, ~, ./ or ../ is a file link. A target in parentheses, (name), is a coderef. One that starts with # is a custom ID. Anything without a known type: prefix is a search for text in the current file (a "fuzzy" link). A link may run over a line break; the break and surrounding blanks read as one space.

Backslashes before brackets are escaped as in org-link-escape: when orgstar writes a link it doubles backslashes that come before a bracket or the end, and it reads them back the same way.

How links display

With View ▸ Show Markup off (the default, ⇧⌘M toggles it), a link with a description shows only its description, and its brackets and target are hidden. This is org-link-descriptive. The full text appears on the line that holds the caret, so you can edit it. With Show Markup on, every link shows as written. The setting is show-markup under [orgstar] in the config file (see Configuration).

Links without a description show their target, with the brackets hidden in the same way. Radio targets (<<<words>>>) turn every other occurrence of those words in the file into a link, matched case-insensitively, as in Org.

Following links

org-open-at-point follows the link at the caret, or opens the agenda for a timestamp.

A message in the echo area explains a link that can't be followed.

What each link type does

The text search follows org-link-search. A dedicated <<target>> matches its words case-insensitively, with any run of blanks between them. A heading matches when its title, with statistics cookies such as [2/5] and a leading COMMENT removed, has the same words as the link, ignoring case. A search that starts with * looks at headings only. Regular-expression searches (/re/) are not supported.

Following a radio link moves to its <<<radio target>>>, matching the words without regard to case, as org-link--search-radio-target does. When the target is gone, the echo area shows No match for radio target: and the text.

File links

A relative path is resolved against the folder of the file that holds the link, as Org does; ~ is your home folder; an absolute path is used as written. Links between files in different sidebar folders work the same way, for example [[file:../work/projects.org]] or [[file:~/Documents/org/inbox.org]].

What happens depends on the file:

• An .org or .org_archive file opens as a buffer in orgstar.
• Another text file opens in orgstar as a plain buffer.
• Anything else (images, PDFs, archives, media) is handed to macOS, which opens it in the default app for that type.

If the file doesn't exist, the echo area shows No file and the path.

After ::, a file link can carry a search option:

Attachment links

An attachment: link names a file in the attachment folder of the entry that holds the link (see Outlines for the attachment commands). Relative folders are resolved against the folder of the file that holds the link:

1. When the entry has a DIR property, or the older ATTACH_DIR, that folder.
2. Otherwise, for an entry with an ID, the first of these folders that exists: org-attach-id-dir (data/) followed by the ID's first two characters, / and the rest of the ID; followed by its first six characters, / and the rest; __/, the ID's first character, / and the whole ID. When org-attach-id-dir is something else, the same folders under data/ are found too.

org-attach-use-inheritance decides whether DIR and ID may come from an ancestor.

When the folder does not exist, the path is relative to the file's own folder. The file then opens as a file: link would, and a search option after :: works the same way.

id links

id: links are resolved through the index, so the target heading must be in a file under one of your sidebar folders. An ID in the property drawer before a file's first heading names the file, as org-roam's file nodes do, and the link opens the file. A link to an ID that isn't indexed shows No heading has the ID followed by the ID.

Timestamps

C-c C-o (Mac ⌃⌘O) or ⌘-click on a timestamp opens the agenda on that day, as org-follow-timestamp-link does. On a date range such as <2026-10-05 Mon>--<2026-10-09 Fri>, the agenda shows the whole span. See Agenda.

Inserting and editing links

org-insert-link asks for a link and a description in the echo area.

The first prompt reads Insert link:, or Insert link (default …): when you have stored links. It completes from:

• your stored links, most recent first, and their descriptions;
• the link abbreviations defined in the file (see Link abbreviations);
• the link types attachment, id, eww, rmail, mhe, irc, info, gnus, docview, bibtex, bbdb, w3m, doi, file+sys, file+emacs, shell, news, mailto, https, http, ftp, shortdoc, help, file and elisp, each followed by :.

Pressing Return on an empty answer inserts the most recent stored link. Choosing a description inserts the link it belongs to. If you choose a bare type such as https:, a second prompt, Link (no completion support):, asks for the rest.

The next prompt, Description:, offers the stored link's description, or the selected text if you selected some before running the command. An empty description inserts a link without one. With text selected, the link replaces the selection.

When the caret is on an existing link, the same command edits it: the Link: prompt starts with the current target and Description: with the current description.

A stored link that you insert is removed from the stored list, as with org-link-keep-stored-after-insertion set to nil.

File paths in inserted links

When the inserted link is a file: link, orgstar rewrites it as org-link-make-string-for-buffer does:

• A link to a heading or target in the file you are editing loses its file: part and keeps only the search, for example [[*Ideas]].
• A path under the current file's folder becomes relative to it.
• Any other path is written with ~ for your home folder.

Completion while typing

You can also type a link by hand. With the caret right after [[, completion at point offers attachment:, doi:, file:, http:, https:, id: and mailto:, plus the file's link abbreviations. After [[*, it offers the headings of the current file. Completion at point is C-M-i in the Emacs preset and C-SPC in Doom's insert state; see The editor.

Storing links

org-store-link remembers a link to where the caret is, for a later Insert Link.

The stored link is a file: link to the current file, written with ~ for your home folder, followed by a search option chosen as Org does with org-link-context-for-files on:

1. If the caret touches a <<target>> on its line, the link points at the target.
2. Otherwise, if text is selected, the link searches for that text.
3. Otherwise, if the caret is in an element with a #+NAME, the link uses the name.
4. Otherwise, inside a heading's entry, the link uses #custom-id if the heading has a CUSTOM_ID property, and *Title if not. The title becomes the description.
5. Before the first heading, the link searches for the text of the current line.

The echo area shows Stored: and the description or link. Storing the same link again moves it to the front of the list. Stored links last until you quit orgstar; they aren't saved between sessions, as in Emacs.

IDs

Org identifies headings across files with an ID property. Two commands manage it.

Create ID gives the heading at the caret an ID property if it doesn't have one. The ID is a new UUID in lower case, for example 6a3c2f9e-…, as org-id-uuid makes them. Before the first heading, the property goes into the file-level property drawer.

Store ID Link does the same, then stores an id: link to the heading with its title as the description. Before the first heading, the description is the #+TITLE, or the file name. If the caret is on a target or named element inside the entry, the link carries that search, as id:…::search, which mirrors org-id-link-use-context.

CUSTOM_ID is a property you set yourself, with the property commands in Outlines. Link to it with [[#name]] in the same file or [[file:other.org::#name]] from another. Store Link uses it when the heading has one.

Targets and radio targets

<<target>> marks a place in the text that a link with the same words reaches: [[target]]. Store Link with the caret on a target stores a link to it.

<<<radio target>>> makes every other occurrence of its words in the file a link, matched case-insensitively and between non-word characters. Radio links are highlighted as links and exported as links to the target (see Export). Following one moves to the radio target.

Link abbreviations

A #+LINK: line defines an abbreviation, as org-link-abbrev-alist-local does:

#+LINK: gh https://github.com/%s
#+LINK: search https://duckduckgo.com/?q=%h
#+LINK: wiki https://en.wikipedia.org/wiki/

[[gh:orgmode/org-mode]]   → https://github.com/orgmode/org-mode
[[search:org tables]]     → https://duckduckgo.com/?q=org%20tables
[[wiki:Org-mode]]         → https://en.wikipedia.org/wiki/Org-mode

In the template, %s is replaced by the text after the colon, %h by the same text percent-encoded, and a template with neither has the text appended. Function templates (%(…)) are not supported. Abbreviations from a #+SETUPFILE count too. When a key is defined twice, the first definition wins.

The backlinks pane

View ▸ Show or Hide Backlinks shows a pane beside the editor of an org file. It has two sections:

• Links to the heading at the caret, named after that heading.
• Links to this file.

Each row shows the linking heading and its file name; a link in the text before a file's first heading is listed under the file's name. Click a row to open it. The pane is shown by default and updates as you move the caret and edit.

The pane looks at every org file in your sidebar folders, including unsaved changes in open buffers. A link counts when following it would lead to the heading or the file:

• id: links to the heading's ID, or to the file's own ID for the file section;
• file: links and plain paths (./, ../, /, ~/) to the file, with no search option for the file section, or with ::*Title, ::#custom-id or ::Title for a heading;
• within the same file, [[*Title]], [[#custom-id]] and [[Title]].

Links to targets, names and line numbers are not counted. A heading's links to itself are left out.

Nodes and daily notes

orgstar works with notes kept the org-roam way: headings and files with an ID are nodes, linked with id: links, and a daily note is a file a day. It reads them from the index, without org-roam's database.

The keys are the ones org-roam's manual suggests for Emacs and Doom's. Titles that repeat show their file's name. A file node's title is its #+TITLE, or its name.

Daily notes are in org-roam-dailies-directory (daily/) under org-roam-directory, which is the first sidebar folder unless set. A new note is named and started as org-roam's default daily template does it, with an ID like every new org-roam file:

,:PROPERTIES:
,:ID:       5f0c1e2a-…
,:END:
#+title: 2026-10-11

org-roam-dailies-file ("%<%Y-%m-%d>.org"), org-roam-dailies-head ("#+title: %<%Y-%m-%d>\n") and org-roam-dailies-entry ("* %?") change the file name, what a new note starts with, and what capturing adds; %<…> formats the note's date as format-time-string does. The entry is an org-capture template; its date escapes (%t, %U and the like) use the note's day. Import from Emacs reads them from the first of org-roam-dailies-capture-templates. See Configuration.

Inline images

org-toggle-inline-images shows image links as images.

The echo area reports how many images are shown, or that inline display is off.

A line shows an image when it holds nothing but a bracket link, without a description, to a file ending in .png, .jpg, .jpeg, .gif, .svg, .webp, .tif, .tiff, .bmp, .heic or .avif (in any case):

[[file:images/diagram.png]]
[[./photo.jpg]]

Relative paths are resolved against the file's folder, and attachment: links against the entry's attachment folder. The link text is hidden while the image is shown, except on the line that holds the caret, where the image is drawn under the link.

Pasting and dropping images

Paste (⌘V, or Edit ▸ Paste on iOS) with an image on the clipboard and no text runs yank-media, as in Emacs 29 and later: the image is saved as org-yank-image-save-method says and a link to it is inserted at the caret. M-x yank-media does the same on the Mac.

The name is Org's: clipboard- and the time, as in clipboard-20261011T232238.png; a second image in the same second gets -2. PNG, JPEG and GIF are saved as they are, and other image types as PNG. Before the first heading, attach gives the file a file-level ID, as Emacs does.

Files dropped on the editor on the Mac, or pasted after copying them in Finder, are handled as org-yank-dnd-method says: attach copies them into the entry's attachment folder (an image goes to the org-yank-image-save-method folder when that is a folder), file-link links to them where they are, open opens them, and ask, the default, asks which. An image dragged in without a file, such as one from a browser, is pasted as above. On iOS, dropped files are always attached, since what a drop hands over is a copy. Attach Photo or Video… and Take Photo… also insert their links at the caret.

Two things differ from Emacs, so that a pasted image shows at once: the link has no description (Org writes [[attachment:NAME][NAME]], which inline display skips), and it goes on a line of its own, breaking the line around the caret when it holds text.

Remote images

Images at http and https links show as org-display-remote-inline-images in config.toml says:

[[https://example.com/chart.png]]

An image is fetched in the background; the link shows as text until it arrives. A link that can't be fetched stays text, and isn't tried again until orgstar starts again. This applies to the editor on the Mac and iOS and to the iOS reader. Emacs's download fetches the image each time it's displayed; orgstar keeps it for the session instead.

Sizing

An image is drawn at its own width, up to the width of the text area. To set a width, put #+ATTR_ORG: :width with a number of points among the keywords above the link:

#+CAPTION: Network layout
#+ATTR_ORG: :width 300
[[file:images/network.png]]

The height follows the image's proportions. #+ATTR_HTML and other exporters' attributes don't affect the editor.

Showing images when a file opens

The config key org-startup-with-inline-images (default false) shows images in every file when it opens. In a file, #+STARTUP: inlineimages or #+STARTUP: noinlineimages overrides it.

org-protocol store-link

orgstar handles org-protocol://store-link URLs, in the new form org-protocol://store-link?url=…&title=… and the old form org-protocol://store-link:/URL/TITLE. The URL is added to your stored links with the title as its description, and is also copied to the clipboard. Insert it with Insert Link. Setting up a browser bookmarklet, and org-protocol://capture, are in Capture.

On iOS

The iOS app follows links: tap a link in the reader. Org files open in the app, and web, mail and other files go to the system. The iOS editor shows inline images as the Mac does; the reader doesn't. In the editor, Store Link, Store ID Link and Insert Link… are in Commands, and on a hardware keyboard the Emacs keys run them; they work as described above, and stored links last until the app quits. org-protocol://store-link links opened on the device are stored and copied too. More ▸ Backlinks lists the same links as the Mac's backlinks pane, for the heading at the caret and the file. See iOS.

Code references

A label at the end of a line in a src or example block, (ref:name) by default, is a code reference, and [[(name)]] links to it. Following the link moves to the label. A block's -l "<<%s>>" switch changes the label's form for that block; %s is the name.

In export, the label is taken off the line. A block with -n numbers its lines from 1, or -n 10 from 10; +n goes on from the numbers of the blocks before it. -r leaves the label out of the exported line, and then the link shows the line's number instead of the name; -k with -n keeps the label while the link still shows the number. A link's description may contain %s for the name or number: [[(call)][line %s]]. In HTML, the line with the label is the link's target, coderef-name.

A regexp link, or a file:…::/regexp/ search, exports as its description, or its text when it has none.