Chapter 5: Links and Images - Connecting Your Knowledge

Links in Org-Mode look like this:

[[link-target][description]]

Or without a description:

[[link-target]]

The target can be almost anything: URLs, files, headings, custom IDs, emails, code references, or even custom link types you define yourself.

The simplest case:

[[https://orgmode.org][Org-Mode Official Site]]

Displays as a clickable link: “Org-Mode Official Site”

Without a description:

[[https://orgmode.org]]

Displays the URL itself.

Press C-c C-o (Control-c Control-o) on a link to open it. Web links open in your browser. That’s it.

Link to other files:

[[file:~/org/projects.org][My Projects]]
[[file:./meeting-notes.org][Today's Meeting]]
[[file:/path/to/document.pdf]]

Relative paths work. Absolute paths work. ~/ expansion works. Press C-c C-o on a file link and Org opens it—in Emacs for text files, external programs for PDFs, images, etc.

Background information here… #+end_example

The * prefix links to a heading by name in the current file. Click it, jump instantly. This is how you build internal document structure.

Critical information here.

For details, see the important section. #+end_example

Rename “Important Section” to anything—the link still works because it targets the custom ID, not the heading text.

For serious knowledge management, use IDs:

#+begin_example

#+end_example

Generate an ID with M-x org-id-get-create. Then link to it:

[[id:8A7F6B2C-3D4E-5F6A-9B8C-1D2E3F4A5B6C][Meeting Notes]]

IDs are globally unique. Move the heading to another file? The link follows. Rename the heading? Link still works. This is how you build a personal knowledge base that survives reorganization.

Enable ID tracking in your config:

(setq org-id-link-to-org-use-id 'create-if-interactive-and-no-custom-id)

Don’t memorize syntax. Use C-c C-l:

1. Press C-c C-l
2. Start typing a link type (file, http, id, etc.)
3. Use completion to select
4. Enter the target
5. Enter an optional description

Org writes the link for you.

Tired of typing long URLs? Define abbreviations:

(setq org-link-abbrev-alist
      '(("wiki" . "https://en.wikipedia.org/wiki/")
        ("rfc"  . "https://www.rfc-editor.org/rfc/rfc%s.txt")
        ("gh"   . "https://github.com/%s")))

Then use:

[[wiki:Org-mode][Org-Mode Wikipedia]]
[[rfc:2616][HTTP/1.1 Specification]]
[[gh:org-mode/org-mode][Org-Mode GitHub]]

Much cleaner.

Org-Mode can display images inline:

[[file:~/Pictures/diagram.png]]

With a description:

[[file:./screenshot.png][Project Screenshot]]

To actually see images in your Emacs buffer:

• C-c C-x C-v - Toggle inline images

Suddenly your text editor shows images. Welcome to the future of 1990s technology.

If you use Emacs for email (with mu4e, notmuch, or similar):

[[mailto:alice@example.com][Email Alice]]

Or link to specific emails (with appropriate email client):

[[mu4e:msgid:abc123@example.com][Project Discussion Thread]]

Your email archive becomes part of your knowledge base.

Execute commands:

[[shell:ls -la ~][List home directory]]
[[elisp:(message "Hello from Org-Mode")][Run elisp code]]

C-c C-o on these runs the command. Use with caution—shell links can do anything your user account can do.

Practical use:

[[elisp:(org-agenda nil "a")][Open Agenda]]
[[shell:open ~/Documents][Open Documents Folder]]

Link to search results:

[[grep:TODO][Find all TODOs]]
[[occur:IMPORTANT][Find IMPORTANT in buffer]]

Not standard, but you can define custom link types that perform searches.

Define your own link types:

(org-link-set-parameters "jira"
                         :follow (lambda (path)
                                   (browse-url
                                    (concat "https://jira.mycompany.com/browse/" path)))
                         :export (lambda (path desc backend)
                                   (format "<a href='https://jira.mycompany.com/browse/%s'>%s</a>"
                                           path desc)))

Now use:

[[jira:PROJ-1234][Bug Report]]

Links become infinitely extensible. Point them at internal databases, APIs, custom tools—whatever you need.

Remember footnotes from Chapter 3? They’re really just links:

#+begin_example The Org manual¹ contains everything, though it’s dense².

By default, links show their description text. To see the underlying link syntax:

• M-x org-toggle-link-display - Toggle between showing descriptions and raw link syntax

Useful when editing or debugging links.

Check for broken links:

M-x org-lint

Reports problems in your document, including broken links, malformed structures, etc.

When you export to HTML, LaTeX, or other formats (Chapter 12), links convert appropriately:

• Web links become hyperlinks
• File links become relative paths or references
• Images embed in the output
• Custom links export according to their export function

One source, many outputs, links preserved.

With file links, custom IDs, and inline images, you can build a personal wiki:

~/wiki/
  ├── index.org          # Main entry point
  ├── projects.org       # Project documentation
  ├── notes.org          # Random notes
  ├── people.org         # People and contacts
  └── images/
      └── diagrams/

In index.org: #+begin_example

Welcome to my personal knowledge base.

Standard Org-Mode doesn’t track backlinks (what links TO this heading), but extensions exist:

• org-roam - Full Roam Research-style backlinks and knowledge graph
• org-brain - Concept mapping with bidirectional links

If you’re building a serious knowledge base, explore these packages. They supercharge Org-Mode’s linking.

1. Download the installer
2. Follow the
3. Configure using this example config
4. See expected result

#+end_example

1. Create at least three org files
2. Add links between them (heading links, file links, custom IDs)
3. Add some web links to external resources
4. Include at least one image and enable inline display
5. Practice C-c C-o to follow links and C-c C-l to create them
6. Store links with C-c l and insert them elsewhere

Build a small interconnected set of documents. Feel the knowledge web forming.

Links transform documents into networks. A single isolated note has limited value. That same note, connected to related ideas, becomes part of a larger understanding.

Org-Mode makes linking frictionless enough to actually do it. Most systems make linking just annoying enough that people don’t bother. The accumulated result? Isolated notes that rot in isolation.

Link liberally. Your future self will thank you.

You’ve built document structure, created tables, and connected ideas. Now let’s turn Org-Mode into a task management powerhouse. TODO items await.