Folder Note Plugin: Add description note to folder

Hi everybody, I have just completed a beta version of Folder Note Plugin for Obsidian. The plugin attaches a description note to a folder which makes your vault a hierarchy note system. Moreover, card-view style overview of the folder can be generated based on the contents of the folder.


  • Create a note for folder by just Ctrl+Click the folder.
  • Support 3 different methods for folder note.
  • Click a folder to show its note.
  • Configure different flder note methods.
  • Configure folder note template to generate initial content.
  • Card view of folder overview which can be edit easily.
  • The card view block can be inserted to other normal note if you like.

The plugin can be installed through the Obsidian’s community plugin tab or manually. The plugin is inspired by the software Trilium and the discussion Folder as markdown note, thanks @navakelvin for suggestions. Visit the GitHub repo to find out how it works. Leave a message if you have any suggestion or create an issue on GitHub.


Thanks for the plug-in. I’m already trying it out!.

Keyword {{FOLDER_NAME}} can be used to set the note name same as folder name, HOWEVER, it is not recommended, because you have to manually change the note file name if you rename a folder.

Should this really be not recommended? Having folder notes set to folder name opens up the possibility to link to folders using [[{FOLDER_NAME}]] …

I have tried to automatically rename the note file if a folder name is changed, but there will be some issues due to the limitation of obsidian’s api. Currently, if you use {{FOLDER_NAME}} as the note filename, the safer strategy is to manually change the note filename.
The folder note file can be linked in a normal way, such as [[folder_name/]], and it can be automatically updated if you rename the folder. I don’t think it is possible to link to folders using [[{FOLDER_NAME}]] in plugin-level unless it is supported inside Obsidian.

If your index note is called the same name as the folder, then linking to this note can be done using the double bracket syntax. Which is equivalent to linking to the folder. That’s what I meant initially :slight_smile:

  • You are right, it could be better to link the folder note in this way, though I personally prefer the index style.
  • I have updated the plugin to support this. Please check the updated information about the plugin.
  • However, to link the folder in this way, you have to move all the folder note files out of the folder. Sorry for the inconvenience.

Why would you need to move the folder notes outside the folder?

Two considerations for this:

  1. if a folder note file has the same name as folder and is inside, then you have to use [[folderName/]] for linking. If it is outside the folder, the link becomes strightforward: [[folderName]].
  2. There will be some issues when rename a folder due to the limitation of Obsidian’s API for the inside-style note file.

then you have to use [[folderName/]] for linking

That’s not true. I just tried it and [[foldername]] works fine even if it’s deeply nested. (e.g. I made a note called Apps and placed it inside Research/Apps and a plain link of [[Apps]] accesses it just fine.

There will be some issues when rename a folder due to the limitation of Obsidian’s API for the inside-style note file.

What limitation is that?

I think I see the problem: your plugin renames things without going through Obsidian’s auto-renaming. I wrote a plugin today that safely handles link moves, and it requires a lot more work to not corrupt the data.

My suggestion would be to not do the auto-renaming, but instead allow users to just manually rename if they need to, as that will then update all links.

Suppose this is your folder structure:

  • <-- Option 1
  • Research
    • <-- Option 2

There are two options to put your folder note file.
In, if you want to link to the folder Research, for Option 1, you use [[Research]]; for Option 2, you should use [[Research/Research]].
In, for Option 1, you use [[…/Research]] to link the folder note; for Option 2, you can use [[Research]] to link the folder.
Someone argues that the Option 1 is better, because the link looks fine. However, someone prefer the Option 2, because the Folder note file is inside the folder.

When I implemented the Option 2 in the plugin, I tried to automatically rename the note file when a folder name is changed by users, but the obsidian’s API will always create a copy of Research/ as Research/Research and failed to delete that. It is may related to file locking.

I’ve actually just written a plugin that manages option 2 just fine. Except instead of renaming the file when the folder is renamed, I do the opposite: rename the folder when the file is renamed. (I also have a lot of extra code to manage locking around the UI and link updating, as that was indeed difficult.)

The reason I chose to match the folder name to the file instead of the other way around is that it’s much easier to rename a note than a folder: it has a title bar and an F2 button. You can also easily move a note anywhere with the “Move file” command with just a few keystrokes. For my workflow, it works much better – I hate using the mouse for things I don’t have to, and I try not to use Obsidian’s file manager at all. This workflow lets me do everything from the keyboard in the context of the note. (Also, rather than creating folders and then wanting to have notes in them, I usually go the other way: I have a note and now I want it to be a folder.)

Anyway, it would be nice if the two plugins could be used together, e.g. if yours had a setting to let the user handle renames and not do any automatic renaming. With that setting, people could use my autorename plugin for the actual file/folder management, and yours for the file manager UI and other features. (Which I’d prefer not to reimplement in mine.)

1 Like

Now the plugin supports 3 methods of folder note which is configurable.

Looks good! I’ll try it with my plugin and see how it works.

I did notice, though that your docs had this to say about the “inside” method:

You may link the folder note as [[myFolder/myFolder]].

This is not necessary. You can link the folder note as [[myFolder]]. So it’s not really a con of that approach

Thanks, I have modified the doc.
I read your plugin source codes to see how you deal with the rename operation. I am new to js and ts and didn’t realize we could use await;. Good work!
I am thinking of integrating some of your codes and idea to the Folder Note plugin when I have time, is that permitted?

1 Like

Thanks, I have modified the doc.

And I’ve updated mine to reference your plugin and describe the compatible settings.

I am new to js and ts and didn’t realize we could use await;

The .after thing is because I basically hacked Obsidian internals. It’s not regular Javascript at all! (If you look at the bottom of the source code, you will see the function I am using to add an after() to those methods – serializeInstanceMethod().)

Unfortunately, I did it in a way that does not support more than one plugin doing the same trick. So if your plugin does it, too, then our plugins will be incompatible. The reason is that I am literally replacing methods on Obsidian’s file manager, so if you replace them as well, it isn’t really clear what will happen, especially if the plugins are deactivated in a different order than they were activated.

I am hoping that the Obsidian developers will take the idea (of serializing the rename API for safe access) or something like it and add it to the core app, so that it will be safe for all plugins to use. At this point my idea is more a technology demo of one way Obsidian can handle that.

If a safe way to rename files is added to Obsidian’s API, then we could both change our plugins to use it, and there would be no conflict between plugins.

However, I will also give some thought as to if there is a way to make the approach I am using safe for more than one plugin. I have a general idea that would work for serializing execution of the methods, but not a direct way of doing the after() part. If I come up with something I will let you know. I might be able to put it in a library so that other plugins can use it then.


Thanks. The hacking seems a little bit complicated for me. I also noticed that it maybe unsafe to add this into my plugin after read all your codes.
Currently, I provided a compromised approach in the updated version:
do the renaming operation 1 second after the internal rename event.
The approach is not a good trick, but I think it is simple and works for most cases.

1 Like

@xpgo Another problem I found is that I can’t open new notes from obsidian’s file explorer any longer because you have bonded Ctrl + Left Click to creating a note for folders. obsidian Hotkeys for users do not allow mouse buttons. If you bind creating a note folder to Alt + Left Click it would let Ctrl + Left Click free again in File Explorer.

Also it would be cool if there was a function that by pressing Alt + Click on a note it would create the folder for it and moved the note inside the folder (like the thing that is already happening for folders right now but for notes)

Thanks for the suggestion, maybe I shoud add a configuration to use Alt or Ctrl, I will try to implement them in the next release.

1 Like

Also it would be cool if there was a function that by pressing Alt + Click on a note it would create the folder for it and moved the note inside the folder (like the thing that is already happening for folders right now but for notes)

The note folder autorename plugin includes a command to turn a note into a folder in this fashion. I suppose if I added it to the right-click menu for files in the graphs and explorer, you could also do it with a click.

Probably @xpgo’s plugin could do the same (i.e. add it to the right-click menu) instead of taking over ctrl-click. (Or perhaps could make it a config option.)

(For developers: the way to add items to that menu is to do something roughly like: this.register("file-menu", (menu, file) => menu.addItem(item => item.setIcon("icon").setTitle("Do a thing").onClick(e => <code to do stuff to file>)));… hopefully with better formatting than that. :wink: )

1 Like

Forgot to mention… if you want to know if the file is a folder before you add the menu item (so it won’t appear on regular files), you can use if (file.children) menu.addItem().... If you want to do additional checks, like whether it already has a folder note, you can, but they have to be synchronous with no async/await. (So you can use e.g. app.vault.getAbstractFileByPath() to test for a file’s existence, but not .exists(), because the former is synchronous and the latter is not.)