Auto-Linking Tool

  1. Save the file and run as python obs-linkr.py {path to vault}.

  2. One copy of the script will work for all vaults, since the vault path is passed on the command line.

  3. The script builds a list of note titles each time it is run - they aren’t saved. It’s really up to you how often you want to run the script, but your use case sounds too frequent. It’s designed to auto-link a block of text, not to auto-link an entire vault or work unattended. My experience was that I commonly had to review the generated output to make sure that the text wasn’t ‘overlinked’ and ambiguities that I might want to un-link for one reason or another. There is no mechanism to identify which notes need to be amended/updated.

  4. I don’t think the script should be run according to a frequency. It should be run when there is a block of text on the clipboard that needs to be linked. It does not operate directly on any files, only on the clipboard text.

  5. See the other responses. This is more of an ‘incremental’ tool, not a bulk editing type of tool. Spend some time with it and you’ll see that it’s probably a more simple tool than you’re making it out to be (at least for now).

OK, many thanks for that explanation.

We need this built-in. Like link suggestions

6 Likes

Fantastic! Already making great use of this. Much appreciated


Wanted to throw in my addition to this in case others also find it useful.

I wasn’t a fan of managing a secondary alias document which I would have to manually update whenever I created new notes … so I have automated the process slightly.

Instead of adding aliases to the aliases.yml file, I add the aliases on a line directly within the note and ‘tag’ the start of the line with a unique key/string which flags that line as containing the note’s alias names.

Executing the script cycles through your vault and searches for the existence of the alias tag within all your notes and creates your aliases.yml file for direct usage with benperkins’ Auto-linking tool.

Current workflow has me periodically running the script to update the yaml file, and running the Auto-linking tool off keyboard shortcut whilst notetaking.

Example usage

While working on your note called Working from home.md you would add the alias tag :::: which identifies alternative aliases for the file, and add additional aliases you wish to link this note to.

# Working from home
:::: Remote working, Remote worker, WFH

A side effect of the pandemic is that ...

Executing the script will generate the following entry into your yml alias file:

Working from home:
- Remote working
- Remote worker
- WFH

Code can be found here:
Obsidian Alias Generator

8 Likes

This is an amazing function! Thanks for sharing.

Sincerely hope it can be a in-built function that Obsidian automatically browse file names and aliases in the vault and enable an auto-completion on bracketing when aliases found in the text, which works similarly to ‘Wikilinks’ in DEVONthink 3.

I believe that this function makes sense after having hundreds of notes in a knowledge management database.

2 Likes

I recently added the ability to exclude certain pages from the auto-linking process. I found that some pages were linked too often (“Work”, “Art”, etc.) and I wanted to exclude them. This is done using aliases.yml:

Note Title to Ignore:
- 
- alias (optional)

The empty alias ("-") on a line by itself signals to the application that the note title shouldn’t be linked, but any aliases provided will continue to be linked to the page.

4 Likes

First of all big thanks for the automation. It has been a default tool for me. I wanted to know if there is a way to ignore matches to certain notes (and their aliases). Because it overwrites the aliases.html file every time it is run, It is difficult to implement the ability to exclude notes from auto-linking, added by @benperkins (Auto-Linking Tool). So, is it possible to exclude the pages from being linked right from the note?

Added a small feature to the tool called “Wikipedia mode”. If the ‘-w’ flag is provided on the command line, only the first instance of a page title (or alias) in the clipboard text will be linked.

1 Like

It would make much more sense not to have to maintain an alias file at all and add aliases into each .md file. The best way to do this would be to use front matter in each file. Front matter is meant as metadata for parsers and plugins so this is the best place to put it.

Some of the reasoning behind consolidating the aliases into a single file:

Speed: Only one file needs to be opened to determine all of the aliases as opposed to cracking open every .md file in your vault in order to parse the frontmatter.
Portability: If for some reason my script or Obsidian ceases to exist and you need to port your notes elsewhere, you have a bunch of orphaned YAML spread across your vault.
Safety: If I can avoid opening your Markdown files, I can avoid any issues relating to data loss, privacy, etc. much more easily.
Visibility: It’s much easier to see the entire scope of your aliases when they’re in one file.
Fragility: If the aliases were defined in frontmatter and I decide that the format of them needs to change in the future, people are stuck updating potentially hundreds of files as opposed to just one.

Perhaps one day I’ll add the aliases to the frontmatter or provide it as an option. I suspect a plugin (hopefully an official one) may also solve the problem. For now, @Spec04 has provided a solution that works with this tool to allow you to put aliases in the frontmatter and extract them into aliases.yml.

3 Likes

Added a feature today to link only the first instance of a title in each paragraph (-p on command line).

2 Likes

Added a companion script to “unlink” a block of text in the clipboard. When the script is run, any wikilinks in text are removed.

It scrubs links of the type:

  • [[this]] becomes this
  • [[Great Page|that]] becomes that

It does not touch links of the type:

  • ![[untouchable]]
  • ![this link](is safe)
  • [so is](this one)

I use this to quickly unlink some text following auto-linking, when the text is linked too frequently for my liking.

1 Like

I agree with the aliases source file, but working on the fly & being able to explore, check, edit via the current note is extremely helpful. Perhaps an option could be a plugin panel which shows you the content from the aliases file of the current note you’re viewing and also allow you to edit or add more. Similar to the Backlink or Tag panel. We could have an Alias panel, with various options, and but it’s all tied back to the aliases file.

This way we can see essentially metadata on the note, but without cluttering the file & all the other reasons you listed and if anyone wanted to embed them in the note itself for whatever reason, an inverse of @Spec04’s solution could be an possible solution. Putting the all aliases from the single aliases file into all their respective notes.

There are some good ideas here. As a medium-term step, perhaps the aliases.yml file could become aliases.md with all of the aliases defined in YAML frontmatter. That way the file can at least be opened/edited in Obsidian and placed wherever the user likes. It wouldn’t sync the location to the current note or anything, but that’s probably the most that could be expected without this being a plugin.

I’ve been hanging back to see what happens with the plugin community and where the devs go with aliases. They’ve added aliases to the roadmap (although with no detail), but I would expect that their aliases feature will be the authority for any other plugins/tools that use aliases. That needs to play out before deciding how to proceed. I also don’t really have a lot of time to commit to porting to a plugin and maintaining it right now.

1 Like

If you’re an AutoHotKey user, this tool integrates nicely with that. I set up AHK scripts for linking and unlinking.

Linking (Shift+Ctrl+L links selected text):

+^l::
Clipboard=
Send ^c
RunWait, cmd.exe /c python obs-linkr.py c:\path\to\your\vault, c:\scripts\obs_tools\forward_linker, Hide
Send ^v

Unlinking (Shift+Ctrl+U unlinks selected text):

+^u::
Clipboard=
Send ^c
RunWait, cmd.exe /c python obs-unlinkr.py c:\path\to\your\vault, c:\scripts\obs_tools\forward_linker, Hide
Send ^v

Here are the scripts in action (Ctrl+A -> Shift+Ctrl+L, Ctrl+A -> Shift+Ctrl+U):

You’ll have to modify the paths to match your own, and may need to add Python to your Windows %PATH%.

2 Likes

Added a new feature today that was inspired by comments from @Fovea.

As an alternative to aliases.yml, the tool now supports using aliases.md at the root of the vault. The files use the same format, but aliases.md can be opened in Obsidian. This provides a few benefits:

  • The file can be edited on-the-fly, repositioned, etc. (best viewed in edit mode)
  • The page titles can be linked, eg.:
[[problem solving]]:
- solving problems
- problem solve
  • When page titles are linked, they will show in the backlinks section (linked mentions). This gives visibility into the aliases defined for a page being viewed (works best with ‘Show more context’ enabled in backlinks section).

You may wish to exclude the aliases file itself from being linked during the auto-linking process by adding the following to aliases.md:

aliases:
- 
2 Likes

With the introduction of aliases into Obsidian 0.9.16, it was time to rework the auto-linking tool. Here is an overview of what the tool does and what has changed.

The auto-linking tool is a Python script that scans your vault for Markdown files, collecting a list of all the note titles and any aliases that are defined in YAML frontmatter. Aliases were introduced in Obsidian v0.9.16 - https://publish.obsidian.md/help/How+to/Add+aliases+to+note.

To cut down on file access and increase speed, the aliases are stored in a file (aliases.md) in the root of the vault. This file can be regenerated at any time, or every time if desired.

The input to the script is the clipboard text, which is scanned for any instances of the titles or aliases. When one is identified, the text is replaced by a wikilink to the relevant note. The modified text is pushed back to the clipboard.

I use this when importing notes or other text so that it can be ‘linked’ into my graph. I also use it after composing notes, so that I don’t have to concern myself with linking as I enter text.

There are options that can be passed on the command line to limit the amount of link output, as well as a separate script to ‘unlink’ a block of text.

The latest version is available at https://github.com/perkinsben/obs_tools/tree/master/forward_linker. If you’re pulling this code down for the first time since aliases were introduced in Obsidian 0.9.16, you’ll need to install another Python dependency (‘pip install python-frontmatter’).

6 Likes

Any chance this might evolve into a plugin with quick shortcuts for autolinking and delinking? I think it would be really phenomenal if done!

6 Likes

It’s possible, but I don’t have time to work on a plugin right now. There is nice automation possible through AutoHotKey on Windows:

Great work - I might be misunderstanding the standard obsidian workflow here, but why is this not part of the core feature set? Surely we want the system to perform as many (meaningful) auto-links as possible to generate the emergent idea structure?

Manually doing this is only marginally better than taking notes in a filing system with tags.

Is it that with a large enough mass of notes, the number of auto-links would become unwieldy?

4 Likes