✅ 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

This opens a dialog to enter:

1. Stored link or

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

3. Description (optional)

✅ Angle Link Syntax

Simple URLs can be written with angle brackets:

✅ Plain URLs

Plain URLs are also recognized:

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

✅ 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

✅ 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]]

✅ 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.

✅ Excalidraw Drawing Links

Link to Excalidraw drawings for visual diagrams:

[[_static/drawing.excalidraw]]

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

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

3. Auto-creation: If you link to a non-existent Excalidraw file and click it,

Install the Excalidraw extension from the VS Code marketplace:

• Extension ID: pomdtr.excalidraw-editor

• Search: "Excalidraw" in VS Code extensions

• 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

✅ Link Syntax Summary