Obsidian Note Codes

2025-09-1812:2211555ezhik.jp

I made a little plugin for Obsidian: Note Codes.

Show article

Obsidian with the Note Code plugin on the bottom right showing the code for a note about hedgehogs.

I made a little plugin for Obsidian: Note Codes.

It will assign a 4-character code to every note in your Obsidian vault. Those codes let you quickly reference notes in your vault from other places such as hand-written notes.

Click here to try it out.

To make things nicer, there's also a protocol handler, so something like obsidian://note-codes/open?code=XX-XX will open the note with the code XX-XX.

I tried to make these codes look nice even if they are handwritten. They're just four characters and some of the similar-looking ones are removed (though the plugin is smart enough to know that AA-0A is the same as AA-OA.

As usual, it's all open source: https://github.com/SilverEzhik/obsidian-note-codes

Note codes are generated based on a note's name and path, meaning that the note code will change if you rename your note.

Each note code consists of 4 alphanumeric characters. For clarity, O, I, L, and U are excluded from the codes, but this plugin will automatically handle these correctly - so OI-LU will automatically be treated as 01-1V when searching. Same with the missing dash or lowercase letters.

Note codes are generated by SHA-256-hashing the note's path in the vault, then taking the first 20 bits of the hash and encoding them using Douglas Crockford's Base32 encoding scheme.

32^4 = 1,048,576, which is hopefully enough.

🦔 🦔 🦔

_{2025-08-13 • Discuss on Mastodon • Discuss on Bluesky}

Read the original article

Comments

By sethaurus 2025-09-228:052 reply

(From the article, talking about the number of available codes)

> 32^4 = 1,048,576, which is hopefully enough.

Unfortunately, it really isn't enough. Since these 4-character codes are based only on a hash of the note's filename, and there's no other collision-resistance built in, the likelihood of two notes getting the same code rises very quickly. With 500 notes in the vault, the chance of two notes having the same code is about 1-in-10. At 900 notes, the odds are 1-in-3, and at 1200 notes, the chances of a collision rise above 50%: it's more likely that there will be a collision than not. These are realistic numbers of notes for an Obsidian vault.

This is all solvable by having something allocating IDs (and attaching them to the notes), but when using a hash, 32 bits just isn't enough to give uniqueness at even small scales.

By Ezhik 2025-09-229:023 reply

(developer here)

Thanks for raising the birthday paradox problem.

The search panel should show all the notes with the same code, so hopefully even with collisions you'd still be able to tell from context which note you're looking for.

I did consider allocating IDs, but I'm a bit worried about this tying notes to a specific Obsidian vault - with the way note codes work now, there is no dependence on the vault itself, only on the note's name. Something to think about...

By medstrom 2025-09-2210:091 reply

You're lucky to regard note names as stable enough that they work as unchanging IDs for you!

But is it not then the same thing, because you already "allocated an ID" by naming it? Did you, before coming up with the 4-char hash, often label things outside the vault with the same names as those found in your vault?

By Ezhik 2025-09-2211:25

I keep a paper journal and refer to my Obsidian notes once in a while.

By spott 2025-09-2221:591 reply

I like the idea of throwing the note code in the frontmatter of the note.

Then it is stable, not tied to the vault, not tied to the name, can be customized on a per note basis if a user wants (00-00 is a specific note for example), and can be deduplicated within a vault.

By jlaternman 2025-09-233:191 reply

Agreed, this would be a nice setting to "burn in" the codes to frontmatter on e.g first save. And with this enabled the plugin could also check for and avoid duplicates by modifying the code until its unique).

One other possibility is use git log --follow to grab the original filepath + commit hash, to base the code on. Imperfect but should reduce code changes vs. on rename.

I really like the simple 4 letter code for shorthand!

By Ezhik 2025-09-235:361 reply

It's an interesting idea - sadly the problem with it is that there's no way to add these tags to other kinds of files that don't have frontmatter. Not sure how to best to deal with it. Right now I'm leaning towards having some vault-specific storage for it.

By jlaternman 2025-09-241:21

Ah yep, I hadn't considered these codes appear for all files, not just frontmatter-friendly formats, which my vaults mostly are… Watermarks for media files? EXIF? — I joke.

It's an interesting problem to think on and also reminds me of resource fork advantages. My two cents is it's worth having a setting for "more permanent" codes at whatever compromise it forces. The idea of very short note codes is really nice, especially if it's "that's the code, it won't change" (I constantly rename and move notes to improve organisation and I expect others do) — I'll be trying out your plugin soon!

The Git idea was to track the original commit of note, assuming the vault is in a repo, and use that original path + git hash as the thing that doesn't change. Log tracking is imperfect, but I'd expect it to work in a vast majority of cases in Obsidian context.

By inhumantsar 2025-09-2214:11

maybe pick an ID at random, record it in a "used" list, and store the code in the note as a property? an event handlers(1) could manage removing used codes from the list when a note is deleted. likewise, another handler could check if new notes (ie those imported from another vault) already have an ID and register it as used or ask the user if they want to generate a fresh ID.

[1] https://docs.obsidian.md/Plugins/Events

By xnorswap 2025-09-228:11

> 32 bits just isn't enough to give uniqueness at even small scales

You're right, but it's actually just 20 bits here, not even 32 bits.

By 1dom 2025-09-227:301 reply

I feel this needs more explanation as to why and what problem is being solved.

> Note codes are generated based on a note's name and path, meaning that the note code will change if you rename your note.

I get the idea of assigning a short identifier to things, but then why would I ever want that ID to change when I change random properties about the note?!

It was interesting to read about the idea of 4 characters with minimal similar looking characters, but the application of that here seems like a solution looking for a problem.

By wiether 2025-09-228:311 reply

Same reaction here.

I could see it being useful... until it said that changing the note name will change its code.

It's the exact opposite of how it should work. It's also the exact opposite of how Obsidian works, automatically updating references to a note when you rename it.

By Ezhik 2025-09-229:052 reply

(developer here)

Interesting to hear that you think this is the opposite of how Obsidian works. I specifically opted for this approach so that these note codes are entirely independent of Obsidian itself and can be ported over to other solutions.

The other way to do it would be to store note codes in some vault-specific storage, but then those codes would be tied to Obsidian, which worries me a bit.

That said, I do want to figure out a nice way to improve it. One idea I've had was to introduce a cache of sorts, so that the plugin will remember all the older codes a note previously had. Do you think this would help your use case?

By wiether 2025-09-229:331 reply

I'm starting to think that I completely misunderstood the goal of your plugin.

I understood that it provided a unique identifier for a note, that could be referenced elsewhere. Meaning that I expect it to last the lifetime of the note. Like a SSN for instance.

But when you talk about being tied to Obsidian, I'm not sure I follow. If it's an identifier to an Obsidian note, sure, the ID should be tied to Obsidian. But if it's an identifier to a .md file, then the ID should not be tied to Obsidian.

For the second case, it's not an issue: think about Obsidian as an IDE, and your vault as a GIT repository. You can create your own ID logic, idependant of Obsidian itself, but stored in the vault. Your pluging will implement this logic, and add the necessary requirements to make it work in Obsidian. And you could make a plugin for VSC that would implement the same logic, and adding the requirements to make it work in VSC.

In this case, I would expect the note ID to be the same, weither I access the vault (GIT repo) through Obsidian or VSC.

By Ezhik 2025-09-2210:19

That's a good point. I'll consider it for the next version.

By unfamiliar 2025-09-229:391 reply

What problem is it aiming to solve (that the file name doesn't already solve)?

By Ezhik 2025-09-2210:12

Being too lazy to write out the whole file name :)

By sfkgtbor 2025-09-226:462 reply

Very interesting to see another person also landing on using 4 base32 characters for labeling things - it really is enough for a human.

Personally I use it for labeling physical things - mainly boxes. With a corresponding note in my Obsidian vault it really helps with getting content, context, and history about random stuff in my basement.

Python oneliner for generating them I've aliased in my Bash config: python3 -c "import base64; import secrets; print(''.join(secrets.choice(base64._b32alphabet.decode()) for _ in range(4)))"

By fastball 2025-09-227:211 reply

The space has 1M IDs available, which sounds like enough until you take into account how the probability of collision works (birthday problem). With only 1200 notes (not many in my experience running a notes platform), your probability of collision is already about 50%.

By medstrom 2025-09-227:44

Aye, so this is fine as long as there's just one entity generating IDs, so it can automatically check for collision and re-generate.

In a distributed system it's another matter.

I'm currently using 6 base-40 chars (upcase and lowcase letters, so e.g. "SXJwzQY") that represent an integer Unix time.

The base-40 alphabet is enough that all IDs up until year ~2099 will fit in 6 chars, and it's nicer to type on the phone when you only have to switch between two keyboard modes, the upcase and lowcase but not also the numbers and symbols mode.

By mungoman2 2025-09-227:231 reply

Interested as I have a basement full of stuff in questionable order.

Could you explain a bit more? If a box in the basement box is marked with 4 emoticons, how does this help you understand content, context, history of it?

By high_priest 2025-09-229:12

I can imagine a QR generator for "obsidian://" links, which would open tagged locations, could be very useful, to identify contents of boxes without opening them.

If the codes are written by hand, then typing them into UI and manually searching for them could be tedious.

---

Emojis/Random Images on boxes, could be used to quickly, visually find the right box in a sea of identical gray boxes.

Hacker News