Documents : Document Linking

Quick links:

Document Linking

Documents in DEVONthink are independent items but often have contextual relationships with other documents in your databases. Efficiently creating and using these links is key in many peoples' use cases. DEVONthink supports three types of links.

Link Types

Relative and Absolute Links: Almost exclusively used in Markdown documents, these are links similar to what is seen in the source code of web pages; e.g., /stylesheets/styles.css. It is possible to manually add these links to an HTML document, but that is certainly less commonly done in DEVONthink. In regards to Markdown, you can read more about linking in the Markdown section of this chapter.

WikiLinks: WikiLinks are a way to create interconnected documents in your databases. When enabled, DEVONthink attempts to detect other documents matching the words you've typed in plain text, rich text, or Markdown documents. This creates an active hyperlink to the detected item, allowing you to quickly jump to it by clicking the link in the document. WikiLinks can be used in plain text, rich text, and Markdown documents. Use them to link to existing items or create documents on-the-fly. For existing items, these links are automatically detected depending on the method chosen in the WikiLinks settings. If a matching document isn't found, a new document will be created with the text as the filename and containing text as defined in the template in the settings. If you enable Update name of WikiLinks in square brackets automatically in the settings, the link text in a document will update if you change the name of a WikiLinked item.

Square bracket WikiLinks support using a description as an alternate name in Markdown. The description comes after a pipe | character, e.g., [[fw4.pdf|W4 Tax Form]] displays as "W4 Tax Form" but links to the "fw4.pdf" file. They also support section anchors following a hash symbol #, e.g., [[Choosing a Mac.html#workrequirements]] jumps to a "Work Requirements" section in the linked document.

Note WikiLinks are not item links, which are discussed next.

Item Links: Many applications today have a URL scheme — a special URL that provides some extra functionality for that application. In DEVONthink, every item has a unique URL called an item link, pointing only to that item. When used with in-application documents or in external applications that support URL schemes, the item link will open the linked document in our software. In some cases, the link may even contain certain parameters to do things like open a video to a specific time.

Item links are either incoming and outgoing links. The two types of links function as sides of one operation. If you create an item link to an image, the file will have an outgoing link detected. The image you have linked to will have an incoming link detected since the file has a link pointing to it. Documents with these links will have a special property icon displayed to the right of the filename in the item list. You can display a sortable Incoming Item Links and Outgoing Item Links column in the headers of the item list in List view. There also are incoming and outgoing item link criteria usable in toolbar searches, smart groups, smart rules, and AppleScript.

Similar to the behavior of WikiLinks, the link text in a document can be updated automatically when you rename a linked document. Enable the Update name of item links automatically in the WikiLinks settings. If this is disabled, you can use the Tools > Item Links > Update Name of Item Links command to manually update a document. To switch from WikiLinks to item links in a document, use the Tools > Item Links > Convert WikiLinks to Item Links command.

Note: Item links also have some utility in automation, discussed in the Automation > Item Links section of this help.

Creating Links

Making links to other documents should be easy to do. However, working within the constraints of certain file formats sometimes requires different methods to create them. Listed below are the most common ways to add links between documents.

Crosslinks: Item links added in documents are also known as crosslinks. You can very quickly insert them into plain/rich text or Markdown documents by typing >> followed by the beginning letters of an item's name. Note this will only match items in the current database, whereas Insert > Item Link can link from any open database.
Make Link: In rich text files, you can select words and choose Format > Make Link to create an active hyperlink of the selected words. Clicking on the hyperlink will generate a new WikiLinked document.
Add Link: For text in rich text and formatted notes, you can select words and choose Format > Add Link. You can then add a URL, including an item link, to create an active hyperlink of the selected words.
Insert Link: Edit > Insert > Item Link opens the Insert Item Link popover, allowing you to add an item link to a document.
Drag and Drop: You can Option-Command-drag and drop a file into a compatible document to insert an item link. This is an efficient way to insert links into rich text or Markdown documents.
Copy and Paste: Select an item in the item list and choose Copy Item Link. This captures the item's unique link to the clipboard so you can paste it into another document or even another application. Some other types of links can be captured, e.g., page links. Item linking methods specific to certain file formats are covered in their respective sections of this chapter.
Source Links: A very powerful method involves selected text in a document. Select some text and choose Edit > Copy with Source Link. This captures the text and a link to it. this can be pasted into other documents, potentially including documents in other applications. The opposite command is similarly powerful: Paste with Source Link. If text is on the clipboard and has a reference to its origin, use this command to paste into a document in DEVONthink. You should get the selected text and a reference to the original document, if available.

Viewing links

If you want to view the links in a document, open the Document > Links inspector. Outgoing links show item links from the current document to other documents or other URLs, e.g., to web pages. If you're viewing the source of a Markdown document, WikiLinks are not listed as outgoing links. If you want to see what documents are linking to the current document, those are listed in the Incoming Links section at the bottom of the pane. This section does include WikiLinks pointing to the active document.

Another inspector, the Graph inspector, can also show links between documents, including both WikiLinks and item links.