Auto-Linking Tool

I put together a Python script to auto-create forward links in clipboard text based on the note titles in your vault. It includes:

  • Defining aliases for pages (using aliases.yml)
  • Handling of mismatched link text case
  • Smart identification of links (won’t identify partial words or previously-linked text)

You pass the location of your vault to the script, which then:

  • Scans your vault location recursively for .md files and builds a list of note titles
  • Imports title aliases from aliases.yml in vault root
  • Sorts the titles from longest to shortest
  • Pulls the text from your clipboard
  • Searches through that text for instances of the titles or aliases
  • Replaces the text with the link (includes handling of differing case)
  • Pushes the linked text back to the clipboard


Assuming you had a file in your vault named problem


problem solving:
- solving problems
- problem solve

Input text:
In order to properly problem solve, you should wear your Problem Solving Hat.

Output text:
In order to properly [[problem solving|problem solve]], you should wear your [[problem solving|Problem Solving]] Hat.

Here’s a gratuitous example of linking a large block of text:

Hopefully it’s of use to someone else.


This could be an awesome plugin when possible!


This is incredible and seems to solve problems I’ve seen in other posts about forward linking. I’d love to see this as a plugin somehow!

Hey, I’ve added this to the Public List of Obsidian Resources, just so you know. Thanks for making this!


Thanks indeed :+1:

This is brilliant!

I have integrated this script with bettertouchtool, and now I can use a keyboard shortcut to execute this script

If anyone needs a detail description about how I tweak this, I can describe in detail here

please explain!

  1. flow the author’s step to install all dependent python packages
  2. then go to bettertouchtool
    1. add a new keyboard shortcut for Obsidian, here I use “alt+cmd+p”(p stands for python code, easier to remember)
    2. add actions for this shortcut:
      1. select action type " execute terminal command (synchronous, blocking)
      2. input one line of script: /path/to/python /path/to/ /path/to/your/vault
  3. then you are good to go
  • if there is space in any of those 3 paths, put a \ in front of that space
  • you can check the path to python with this which python

Now that my collection of notes is becoming bigger, this starting to be a relevant tool for me.

It is not quite clear to me how the process works between amending notes/adding new notes, and getting the tool’s output back in my notes, so I have a few questions.

  1. from you Github page I understand I can copy the python code and save that file as python, right?
  2. I can either keep the script in a central place, or a copy of it in each vault.
  3. the 1st time I run the script, it builds a list of note titles. If no new notes are added, and existing notes are amended, do I need to run the script each time I amend a note? If so, how do I know which notes were amended by the tool and that I therefore need to copy/paste from the clipboard to pick up tool’s output?
  4. if what I say in point 2 is correct, it is easiest to run it once a day, or once a week, right?
  5. if point 2 is right, the same procedure applies if new notes are added, right?
  1. Save the file and run as python {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


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 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

Code can be found here:
Obsidian Alias Generator


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.

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.


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.


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

1 Like