Link Management

Notesdir facilitates the use of regular hyperlinks, with relative file paths, for linking between notes or referencing attachments. The advantage of this over a more specialized syntax is that it allows a wide variety of viewing/editing software to understand the links out-of-the-box.

One challenge to that approach is that if you rename or move a file, links to and from it are broken. To address this, when the notesdir mv command moves a file, it also updates all links to it in other files so that they point to the new location.

The list of links to a file (backlinks) can also be accessed from the CLI or API if you want to conduct analysis of the relationships between your notes.

File type support

Links to any type of file or folder can be detected, as long as the link is from a supported file type:

• Markdown: links like [link text](path/to/file.xyz) are recognized, along with some but not all other syntaxes. See notesdir.accessors.markdown.MarkdownAccessor for more details of what is supported.

• HTML: links like <a href="path/to/file.xyz">link text</a> are recognized, along with references to resources in various elements like img. See notesdir.accessors.html.HTMLAccessor for more details of what is supported.

Configuration

When searching for backlinks, notesdir scans all the files it knows about from your configuration - see notesdir.conf.RepoConf. All files (of supported file types) in roots will be checked, unless they are filtered out by skip_parse or ignore.

Viewing links and backlinks

Use the notesdir info command to view links to and from a particular file:

notesdir info philosophy-of-language-the-classics-explained.md

The output looks like this (alternatively, pass -j to get JSON output):

path: /Users/jacob/Zettel/personal/active/philosophy-of-language-the-classics-explained.md
title: Philosophy of Language: The Classics Explained
created: 2020-06-18 05:33:35.183691
tags: book, language, nonfiction, philosophy, unit
links:
        ../archive/2020/06/frege-on-sense-and-reference-mcginn.md -> /Users/jacob/Zettel/personal/archive/2020/06/frege-on-sense-and-reference-mcginn.md
        ../archive/2020/07/kripke-on-names.md -> /Users/jacob/Zettel/personal/archive/2020/07/kripke-on-names.md
        ../archive/2020/07/russell-on-definite-descriptions-mcginn.md -> /Users/jacob/Zettel/personal/archive/2020/07/russell-on-definite-descriptions-mcginn.md
backlinks:
        /Users/jacob/Zettel/personal/archive/2020/06/frege-on-sense-and-reference-mcginn.md
        /Users/jacob/Zettel/personal/archive/2020/07/kripke-on-names.md
        /Users/jacob/Zettel/personal/archive/2020/07/russell-on-definite-descriptions-mcginn.md

In the links section, the text to the left of the arrow is the actual link as it appears in the file, while the text to the right of the arrow is the absolute path of the target file. The backlinks section lists the absolute paths of files that contain links to this file.

Moving files without breaking links

Suppose you have this directory tree:

notes/
    one.md : "I link to [file two](two.md)"
    two.md : "I link to [file one](one.md)"
    subdir/

You can run the following command to move two.md:

notesdir mv notes/two.md notes/two.md/subdir/newname.md

Now your directory tree and files will look like this:

notes/
    one.md : "I link to [file two](subdir/newname.md)"
    subdir/
        newname.md : "I link to [file one](../one.md)"

If you want a list of what files will be changed without actually changing them, use notesdir mv --preview.

Replacing links

Sometimes you may want to replace links without moving any files. For example, if you convert an HTML file to Markdown, you would want to find all links to the old .html file and replace them with links to the new .md file. Use the relink command to do this. It does not move any files, or even care whether the old or new paths refer to real files.

notesdir relink old.html new.md

If you want a list of what files will be changed without actually changing them, use notesdir relink --preview.