✅ External Links

Links to resources outside your document:

✅ Internal Links

Links to locations within your documents:

✅ Citation Links (org-ref style)

For academic references (see References):

✅ Bracket Link Syntax

The standard link format uses double brackets:

[[link-target][description]]

Examples:

[[https://www.example.com][Example Website]]
[[file:report.pdf][Quarterly Report]]
[[*Introduction][Go to Introduction]]
[[#methods][Methods Section]]

If no description is provided, the link target is displayed:

[[https://www.example.com]]

Insert Link Command

With the cursor on an existing [[target][description]] link, C-c C-l edits that link instead of inserting a new one: it prompts for the target and then the description, both prefilled. Clear the description to leave a bare [[target]]; press Escape to leave the link unchanged.

This opens a dialog to enter:

1. Stored link or

2. Link target (URL, file path, or internal reference)

3. Description (optional) ┌───────────────────────────────┬────────────────────────────────┐ │ Link Format │ Action │ ├───────────────────────────────┼────────────────────────────────┤ │ file:name.org::123 │ Jump to line 123 │ ├───────────────────────────────┼────────────────────────────────┤ │ file:name.org::c456 │ Jump to character offset 456 │ ├───────────────────────────────┼────────────────────────────────┤ │ file:name.org::*Heading │ Jump to heading │ ├───────────────────────────────┼────────────────────────────────┤ │ file:name.org::#custom-id │ Jump to custom ID │ ├───────────────────────────────┼────────────────────────────────┤ │ *Heading │ Jump to heading in same file │ ├───────────────────────────────┼────────────────────────────────┤ │ #custom-id │ Jump to custom ID in same file │ ├───────────────────────────────┼────────────────────────────────┤ │ block-name │ Jump to #+NAME: block-name │ └───────────────────────────────┴────────────────────────────────┘

✅ Angle Link Syntax

Simple URLs can be written with angle brackets: https://www.example.com

Plain URLs

Plain URLs are also recognized:

Visit https://www.example.com for more info.

In HTML and LaTeX export and the Org Preview, plain and angle-bracket http://, https:// and mailto: URLs become links. A plain URL can contain one level of balanced parentheses (as in Wikipedia URLs), and punctuation at its end, such as a full stop or comma, is left out of the link. The // in a URL does not start italics.

✅ Open Link

Click on a link or use this command to:

• Open URLs in your default browser

• Open files in VS Code (or associated application)

• Jump to internal targets

✅ Link Behavior by Type

✅ Link Display (Descriptive vs Literal)

By default org links are shown by their description only, like Emacs org-link-descriptive. The brackets and target are hidden, so [[file:25-commands.org::1868][* Utilities]] reads as just * Utilities, and a link without a description such as [[https://orgmode.org]] reads as https://orgmode.org. The text stays clickable.

Links stay collapsed when the cursor moves into them. To change a link, put the cursor on it and press C-c C-l (see Insert Link Command). Set scimax.org.descriptiveLinksReveal to cursor to have the literal link reappear while the cursor is inside it instead. Links inside source and example blocks are always shown literally.

The hidden brackets and target are still in the text, but the cursor skips over them, as Emacs skips invisible text. Arrow keys move one visible character at a time, and a click never leaves the cursor inside the hidden part. For clicks and the cursor to line up with the collapsed text, scimax sets editor.disableMonospaceOptimizations to true for org files. If you override it to false, the cursor on lines of plain ASCII text is drawn as if the hidden text were still there, and clicking a link puts the cursor in the wrong place. Tables measure links as displayed, so a table of links lines up on screen (see the Tables chapter).

✅ Headings as Targets

Link to headings by title using *:

* Introduction
...content...

* Methods
See [[*Introduction][the introduction]] for background.

✅ Custom IDs

Create stable link targets with CUSTOM_ID property:

* Introduction
:PROPERTIES:
:CUSTOM_ID: intro
:END:

Link to it with:

[[#intro][Introduction section]]

Custom IDs are preferred over heading text because:

• They don't break when heading text changes

• They're shorter and cleaner

• They're unique within the document

✅ Dedicated Targets

Create named anchors anywhere with :

This paragraph contains a that we reference later.

...

As mentioned at important-point, this is significant.

✅ Radio Targets

Radio targets create automatic links throughout the document:

We introduce the concept of Machine Learning here.

...

Later, when we mention Machine Learning, it automatically links back.

Any occurrence of "Machine Learning" becomes a link to the radio target.

✅ ID Properties

The ID property provides globally unique identifiers:

That important section

ID links work across files:

See References Document

✅ Basic File Links

14-journal.org

A link to a directory, such as [[file:../src/]], opens the directory in dired (cmd:scimax.dired.open) instead of the "this is a directory" page VS Code would otherwise show. This works for Ctrl+click, C-c C-o, and links in the agenda hover preview.

✅ File Links with Line Numbers

Jump to a specific line:

Line 42 in references.org

✅ File Links with Search

Search for text in the target file by heading, ID, or text:

File Links with Search Section

By Custom ID in Links Document

By Text Search in Links Document

Search options:

✅ Relative vs Absolute Paths

file:./14-journal.org ; Same directory file:../tasks.org ; Relative path file:~/Dropbox/emacs/projects/scimax_vscode/docs/14-journal.org ; Home-relative file:/Users/jkitchin/Dropbox/emacs/projects/scimax_vscode/docs/14-journal.org ; Absolute path

Prefer relative paths for portability.

✅ Protocol Links

Not many protocols are supported beyond HTTP(S) and FILE, but a few useful ones include:

DOI Reference

✅ Image Links

Link to images (see also Image Overlays):

Images are displayed in tooltips or overlays when hovering over the link.

Marp Slideshow Links

A marp: link presents a Marp slide deck (a Markdown file with marp: true) as a slideshow in the browser. Click it, or press C-c C-o on it.

[[marp:talks/group-meeting.md][Group meeting slides]]
[[marp:talks/group-meeting.md::5][Start at slide 5]]

The path is relative to the org file; absolute paths and ~/ work too. ::N starts at slide /N/. In exported HTML or LaTeX the link points to the .md file. See Slideshow.

Hovering over the link shows a picture of the deck's first slide, the number of slides, and links to Edit the .md file, open its Preview beside the editor, or Present the slideshow (from slide N for a ::N link). The picture uses the deck's theme and inlines local images; remote images and web fonts are not loaded, so those may look different from the slideshow.

✅ Excalidraw Drawing Links

Link to Excalidraw drawings for visual diagrams:

_static/drawing.excalidraw

Supported Extensions:

Features:

1. Hover Preview: Hovering over an Excalidraw link shows:

   • A visual preview of the drawing (for SVG/PNG exports)

   • File information (size, modification date)

   • Element count (for JSON files)

2. Click to Edit: Clicking the link opens the drawing in the Excalidraw editor

   • Requires the Excalidraw VS Code extension (excalidraw-editor)

   • If the file doesn't exist, a new empty drawing is created

3. Auto-creation: If you link to a non-existent Excalidraw file and click it, the file is automatically created with an empty drawing.

Prerequisites:

Install the Excalidraw extension from the VS Code marketplace:

• Extension ID: pomdtr.excalidraw-editor

• Search: "Excalidraw" in VS Code extensions

Usage Tips:

• Save drawings as .excalidraw.svg or .excalidraw.png to get hover previews

• These formats embed the full Excalidraw scene data, so they remain editable

• Store drawings alongside your org files for easy linking with relative paths

✅ ID Links

Universal identifiers for cross-file linking:

Section in another file

✅ Notebook Links

Notebook links provide cross-project navigation using the nb: link type. Inspired by scimax-notebook in Emacs, they allow you to link to files within registered notebook projects.

[[nb:project-name::relative-file-path::target][description]]

✅ With Description

Visit Example.com

Note it is not currently possible to use a display mode like Emacs does, but descriptions can be used for export.

✅ Without Description

[[https://www.example.com]]

Displays as: https://www.example.com

✅ Description Formatting

Descriptions can contain emphasis:

[[https://important.com][/Very/ *Important* Link]]

But descriptions cannot contain other links.

✅ HTML Export

Links become elements:

<a href="https://www.example.com">Visit Example.com</a>

✅ Quick Insert

✅ Citation Styles

(kitchin-2015-examp-effec) (skitchin-2015-examp-effec) ; Basic citation kitchin-2015-examp-effec ; Textual: Kitchin (2015) (kitchin-2015-examp-effec) ; Parenthetical: (Kitchin, 2015) kitchin-2015-examp-effec ; Author only: Kitchin (kitchin-2015-examp-effec) ; Year only: 2015

✅ Use Stable Link Targets

Prefer stable identifiers over content-based links:

; Fragile - breaks if heading changes: *My Current Heading Title

; Stable - survives heading changes: #my-heading-id

; Most stable - globally unique: id:uuid-here

✅ Organize File Links

Keep related files together with relative paths:

project/
├── notes.org          ; Main document
├── data/
│   └── results.csv    ; [[file:./data/results.csv]]
├── images/
│   └── figure1.png    ; [[file:./images/figure1.png]]
└── references/
    └── paper.pdf      ; [[file:./references/paper.pdf]]

✅ Descriptive Link Text

Good:

See the Methods section for details.

Avoid:

See here for details. Click this link.

✅ Link Collections

Group related links in lists:

• Org-mode website

• GitHub

• My Notes

✅ Keybindings

✅ Commands

macOS Quick Links

Two commands pull link targets from other macOS apps via AppleScript and insert them at the cursor as org-mode links.

Both commands require macOS. On first run, macOS will prompt you to grant VS Code permission to control Finder / Google Chrome via Automation (System Settings → Privacy & Security → Automation).

These commands are intentionally unbound by default — assign your own keybindings in keybindings.json if you use them often.

✅ Link Syntax Summary