Keybinding Note: This extension uses Emacs-style keybindings where Ctrl is used on all platforms (not Cmd on Mac), except where explicitly noted. Mac alternatives are shown as Cmd where applicable.
✅ Hyperlinks
Links in org documents connect your notes to files, websites, headings, and more. Scimax VS Code supports a variety of link types and provides commands for creating and following links.
✅ Link Types
Org-mode supports many types of links. Scimax VS Code handles the most common ones:
✅ External Links
Links to resources outside your document:
| Type | Example |
|---|---|
| HTTP(S) | https://www.example.com |
| File | file:~/documents/report.pdf |
| mailto:user@example.com | |
| FTP | ftp://ftp.example.com/file.txt |
✅ Internal Links
Links to locations within your documents:
| Type | Example |
|---|---|
| Heading | *My Heading |
| Custom ID | #my-custom-id |
| Target | |
| ID | id:550e8400-e29b-41d4-a716-446655440000 |
✅ Citation Links (org-ref style)
For academic references (see References):
| Type | Example |
|---|---|
| cite | (smith-2024) |
| citet | jones-2023 |
| citep | (doe-2022) |
✅ Creating Links
✅ 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
| Key | Command |
|---|---|
| C-c l | Store link (scimax.org.storeLink) |
| C-c C-l | Insert link (scimax.org.insertLink) |
This opens a dialog to enter:
Stored link or
Link target (URL, file path, or internal reference)
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:
✅ Plain URLs
Plain URLs are also recognized:
Visit https://www.example.com for more info.✅ Following Links
✅ Open Link
| Key | Command |
|---|---|
| C-c C-o | Open link at point (scimax.org.openLink) |
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 Type | Behavior |
|---|---|
| https:// | Opens in default browser |
| http:// | Opens in default browser |
| file: | Opens in VS Code or associated app |
| mailto: | Opens default email client |
| #custom-id | Jumps to heading with CUSTOM_ID |
| *Heading | Jumps to heading with that title |
| id: | Jumps to entry with that ID property |
| nb: | Opens file in a notebook project |
✅ Link Targets and Anchors
✅ 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:
ID links work across files:
✅ File Links
✅ Basic File Links
✅ 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:
| Syntax | Searches for |
|---|---|
| ::*Heading | Heading with that title |
| ::#id | Entry with that CUSTOM_ID |
| ::search text | First occurrence of text |
| ::123 | Line number 123 |
✅ 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.
✅ Special Link Types
✅ Protocol Links
Not many protocols are supported beyond HTTP(S) and FILE, but a few useful ones include:
✅ 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:
Supported Extensions:
| Extension | Description |
|---|---|
| .excalidraw | Native Excalidraw format |
| .excalidraw.json | Explicit JSON format |
| .excalidraw.svg | Exported SVG with scene data |
| .excalidraw.png | Exported PNG with scene data |
Features:
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)
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
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-editorSearch: "Excalidraw" in VS Code extensions
Usage Tips:
Save drawings as
.excalidraw.svgor.excalidraw.pngto get hover previewsThese formats embed the full Excalidraw scene data, so they remain editable
Store drawings alongside your org files for easy linking with relative paths
✅ 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.
✅ Link Format
[[nb:project-name::relative-file-path::target][description]]| Component | Description |
|---|---|
| project-name | Name of the notebook/project |
| relative-path | Path to file relative to project root |
| target | Optional: line number, char offset, heading or ID |
✅ Examples
| Link | Description |
|---|---|
| nb:my-research::README.org | Open README.org in my-research |
| nb:my-research::data/notes.org | Open notes.org in data/ subfolder |
| nb:my-research::paper.org::10 | Jump to line 10 |
| nb:my-research::paper.org::c453 | Jump to character offset 453 |
| nb:my-research::paper.org::*Methods | Jump to "Methods" heading |
| nb:my-research::doc.org::#intro | Jump to custom ID "intro" |
✅ Target Syntax
The target component (after the second ::) supports:
| Syntax | Description |
|---|---|
123 | Jump to line 123 |
c456 | Jump to character 456 |
*Heading | Jump to heading by name |
#id | Jump to custom ID |
✅ Commands
| Key | Command | Description |
|---|---|---|
| C-c C-o | scimax.org.openLink | Open notebook link |
| (none) | scimax.notebook.insertLink | Insert a notebook link |
✅ Inserting Notebook Links
Use the command Scimax: Insert Notebook Link to interactively create links:
Select a project from registered notebooks
Select a file within that project
Optionally specify a target (line, heading, ID)
The link is inserted at the cursor position.
✅ Project Resolution
The project-name is matched against registered notebooks by:
Exact name match (from
.scimax/config.jsonor directory name)Case-insensitive name match
Directory name at the end of the path
If multiple projects match, you'll be prompted to select one.
✅ Link Descriptions
✅ With Description
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.
✅ Links in Export
✅ HTML Export
Links become elements:
<a href="https://www.example.com">Visit Example.com</a>Internal links become anchor references.
✅ LaTeX Export
Links become \href{}{} commands:
\href{https://www.example.com}{Visit Example.com}Internal links become \ref{} or \hyperref[]{} commands.
✅ Markdown Export
Links become standard Markdown format:
[Visit Example.com](https://www.example.com)✅ Citation Links
For academic documents, Scimax VS Code supports citation links. See References for complete documentation.
✅ Quick Insert
| Key | Command |
|---|---|
| C-c ] | Insert citation |
✅ 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) ; Author only: Kitchin (kitchin-2015-examp-effec) ; Year only: 2015
✅ Best Practices
✅ 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]]
✅ Quick Reference
✅ Keybindings
| Key | Action |
|---|---|
| C-c l | Store link |
| C-c C-l | Insert link |
| C-c C-o | Open link at point |
| C-c ] | Insert citation (org-ref) |
✅ Commands
| Command | Description |
|---|---|
| scimax.org.storeLink | Store a new link |
| scimax.org.insertLink | Insert a new link |
| scimax.org.openLink | Open link at cursor |
| scimax.org.insertFinderLink | Insert link from Finder selection (macOS) |
| scimax.org.insertChromeLink | Insert link from front Chrome tab (macOS) |
| scimax.ref.insertCitation | Insert citation link |
macOS Quick Links
Two commands pull link targets from other macOS apps via AppleScript and insert them at the cursor as org-mode links.
| Command | What it inserts |
|---|---|
| scimax.org.insertFinderLink | [[file:/path][name]] for each item selected in Finder. |
| Falls back to the front Finder window's folder if no items. | |
| scimax.org.insertChromeLink | [[url][title]] for the front tab of Google Chrome. |
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
| Format | Example |
|---|---|
| URL with description | desc |
| URL only | url |
| Angle brackets | |
| Heading link | *Heading |
| Custom ID link | #id |
| ID link | id:uuid |
| File link | file:path |
| File with line | file:path::123 |
| File with search | file:path::text |
| Target | target-name |
| Notebook link | nb:project::file::target |