✅ 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)
✅ 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 CUSTOMID |
| *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 CUSTOMID 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 CUSTOMID |
| ::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:
[[_static/drawing.excalidraw]]
| 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 |
Hover Preview: Hovering over an Excalidraw link shows:
Click to Edit: Clicking the link opens the drawing in the Excalidraw editor
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-editorSearch: "Excalidraw" in VS Code extensions
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.ref.insertCitation | Insert citation link |
✅ 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]] |