Link Management

Link Management in Notebooks

You have seen it many times: you click on a link on a web page, but instead of taking you to the expected target, the browser displays an error message. I tells you the link cannot be resolved, because target does not exist, has been moved, renamed or even deleted.

Any system supporting links between documents faces the challenge of keeping references consistent and up to date – and Notebooks is not an exception. Notebooks uses a document’s title as link or reference. When you move or rename a document or one of a document’s parent books, links pointing to that document brake. ¹

To address this problem, Notebooks applies various techniques.

Link Management Options

Definitions

Before diving into more detail, let us start with a few specifications.

When talking about links in this document, we are referring to Notebooks internal links. These point from one document in Notebooks to another document in Notebooks. External links are not managed by Notebooks.

Links can have any the following formats:

• Wiki links have the format of [[wiki-link]] or [[wiki-link | a label]]
• Markdown links look like [This is the label](link-to-target)
• Notebooks links, like notebooks://links/to/documents
• File references in the form file:///path/to/a/notebooks/document.

Wiki links and Markdown links are used in plain text and in Markdown documents, but not in formatted documents. Notebooks’ links and file references are automatically used in formatted documents, and they also work in Markdown and plain text documents.

When using links in plain text, please make sure to percent encode them, otherwise Notebooks (or the respective Markdown converter) many not correctly detect and resolve them.

Smart Link Resolution

With SLR active, clicking on a broken link never leads an error message. Instead, Notebooks tries to find an alternative target for you, or it assumes that you want to create the target document from scratch.

SLR in Action

To better explain how SLR works, let us look at an example in detail.

• The user clicks on the link [[medicine/ophthalmology]]. Notebooks would expect a document Ophthalmology.* in the sub book medicine (that is what we refer to as the specified book). Notebooks is generous regarding the filename extension and accepts Ophthalmology.txt as well as Ophthalmology.pdf, Ophthalmology.md or anything else.
• If no such document exists, Notebooks looks at all documents in the book medicine to find out if any of them contains the word ophthalmology in its title. So it could resolve the link to the document medicine/Handbook of Ophthalmology.pdf, for example.
• If no document contains that word in its title, Notebooks can search for documents in the book medicine containing ophthalmology in their contents. So the link could resolve to the document Medical Terminology.html which contains the term ophthalmology anywhere in its contents,.
• If still no match is found, Notebooks could search for ophthalmology in the title of any document anywhere within Notebooks and open the first one it finds.
• If that still fails, Notebooks asks whether the user wants to create a document with the title “ophthalmology” in the book medicine. This is a convenient way of creating new documents, but it can also be a hint of a mistyped link or a document that was renamed.

So Notebooks‘ SLR dynamically resolves links, and it is also a quick and convenient way of creating a network of interlinked documents (see below).

Settings and Options

• SLR is inactive by default and has to be enabled in Notebooks‘ Settings > Write & Edit > Links.
• A few options allow you to control how Notebooks should identify alternative targets:
  1. Accept a document as target (we call that resolve) if the given link is part of its title and it is located in the specified book.
  2. Resolve if the link is part of any document’s title anywhere within Notebooks (resolving that may take a little longer).
  3. Resolve when the link appears in the contents of any document in the specified book.
• If no alternative is found, Notebooks asks whether you want to create a new document, using the given link as document title.

Scenario: SLR and Personal Wiki

In a Wiki style environment, you can already take advantage of SLR in its most basic form, even with all options disabled: while working on an article, you can add links to documents you want to reference but that don’t yet exist , like [[personal Wiki]], for example. Then click on that link, allow Notebooks to create the document, and continue working on that. Notebooks automatically creates backlinks which make sure that the documents link to one another.

SLR differs from Automatic Link Management, as it does not modify your documents. SLR performs a search across the documents, so works within Notebooks only. It is ideal for Wiki style collections of documents or for a Zettelkasten.
For collections of documents which rely on stable references or are intended to be exported and reused in other system, Notebooks‘ ALM is the better choice.

Backlinks

Backlinks are closely related to Automatic Link Management. With link management active, documents track their outbound ² and inbound ³ links, so each document “knows” which other documents refer to it. This makes it easy to follow links back to the origin, which opens up new opportunities.

Benefits of Using Backlinks

1. Notebooks can provide you with a list of references³, so you can always see which documents refer to the current document.
   • A clickable list of backlinks is available in each item’s info.
   • Notebooks provides an option to append the list of backlinks to the rendered version of Markdown documents. The section has the label Mentions
2. Combined with SLR and its option to create new documents by clicking a link, backlinks ideally complement personal Wikis and similar bi-directionally linked information systems.
3. Backlinks help Notebooks keep links consistent through its automatic link management.
   • Notebooks automatically tracks backlinks when ALM is active.
   • The Process menu of books and documents provides actions to manage backlinks, if necessary.
     • Find Broken Backlinks
       Scans the contents of the current book and looks for links that don’t have a valid target. When finding broken links, Notebooks offers an option to repair them.
     • Refresh Backlinks
       Walks through the contents of the current book, looking for inbound links not yet registered as backlinks. This is useful after adding documents externally, while Notebooks was not running.
     • Remove Backlinks
       When called for a book, this action removes the backlinks from all documents contained in the book.
       When called for a document, removes that document’s backlinks.
       • Without backlinks, Notebooks is unable to manage a document’s links. So removing backlinks can be an option to reorganize contents without managing links.
       • Removing backlinks may clean up left over references.
       • Backlinks automatically update as you open documents linking to other documents.

Automatic Link Management

With ALM active, links follow their targets even if the targets change their titles or locations. You can rename or move books and documents without breaking any internal links. To achieve this, Notebooks adjusts the links for you, which means it actively modifies your documents if necessary. That is why link management is not active by default.

How ALM Works

• Activate link management from Settings > Write and Edit > Links > Automatic Link Management.
• Notebooks starts by collecting the Backlinks for each document, which is the prerequisite for detecting and correcting broken links.
• Whenever you rename or move an item, link management automatically kicks in and corrects links if necessary.
• When you open a document which contains links to other documents, Notebooks adjusts the target documents’ backlinks if necessary. – This is important to know in case you delete a document’s backlinks (see below),.
• Notebooks manages links between internal documents in the format of [[wiki links]], [Markdown](links), links in formatted documents (which includes embedded images) and plain notebooks://links/to/documents.
• From time to time you might see a small popup window stating that Notebooks is searching for broken links. That may happen after a WiFi sharing session (on iOS) or when documents are edited externally, for example.
• Documents display the list of references and backlinks (mentions) in their info.

Options

• Link management is a location specific setting, so you can have different settings for different storage locations.
• For Markdown documents there is an option to append the list of backlinks at the end of the document, in a section labeled Mentions.
• A document’s process menu contains an option to delete a document’s backlinks. This is like deactivating link management for this document, so you can move or rename it, but links pointing to the document won’t follow. – As soon as you open a document pointing to that document, Notebooks adds backlinks to it again.
• Each book’s process menu provides a sub menu with link management options. You probably won’t need them very often, but you can scan the book for broken links and repair them; you can remove the backlinks from all documents in the book, and you can refresh backlinks, which is the opposite of removing them.

Side Effects of Automatic Link Management

While the advantages of automatic link management are obvious (rename and restructure content without breaking any links), there are side effects, too.

Links Follow the Document, Without Exception

With ALM active, renaming or moving a document automatically adjusts all links pointing to that document. So if you want to replace a document with a new version and rename it from Introduction.md to Introduction-old.md, for example, link management immediately kicks in and changes all links from Introduction.md to Introduction-old.md. When you then add a new document Introduction.md, the links still point to Introduction-old.md, which is probably not what you want.

There are workarounds for this case:

• Duplicate the document and then replace the original’s (not the duplicate’s) contents. This creates a backup of the original version, but the links still point to the original.
• Remove backlinks from Introduction.md before renaming and replacing it. Without backlinks, Notebooks won’t adjust any links. The backlinks will automatically update as you open links pointing to Introduction.md. Alternatively, you can choose Refresh Backlinks for the book containing the document.
• Finally, you can temporarily turn off ALM while replacing Introduction.md, then turn it back on.

Tips

For best results, please try to manage your documents from within Notebooks, so it is aware of what you do and can react accordingly. If you need to restructure Notebooks‘ content externally, make sure to include the .plist files, which contain the relevant details for link management. Also, use the Find broken Links option mentioned above to trigger link management proactively.

Summary

While Automatic Link Management and Smart Link Resolution address the same problem, they operate in fundamentally different ways. While one modifies documents to adjust links, the other searches for alternative link targets on demand.

You can use them side by side, but you can also choose to use only one or the other, and you can toggle them anytime.

Smart Link Resolution

• works within Notebooks only,
• can search target documents across Notebooks,
• resolves partial and incomplete links,
• is for “live use”, as it kicks in as you click a link,
• is ideal for personal Wiki and the like.

Automatic Link Management

• works on fully qualified links,
• modifies the contents of documents if needed,
• makes sure the links work outside of Notebooks,
• is ideal for collections of documents with clearly defined references, like books, scientific papers etc.

---

1. Notebooks stores documents as regular files in the file system and uses the path as unique identifier. When the path changes, the identifier changes as well. – This is in contrast to systems storing documents in databases, but they have the disadvantage that documents cannot be as easily reused as in Notebooks. ↩︎
2. Outbound links point from the current document to other documents. ↩︎
3. Inbound links point from other documents to the current document. They can be considered references or mentions, two terms we use throughout our documentation, too. ↩︎