Plugin for keeping the filename and first heading of a file in sync

Found myself always having the first heading of a file to be the same as the filename, so I wrote a little plugin to automate keeping them in sync.


Note: This plugin will overwrite your existing heading and rename your file when you change that heading, so this can be considered destructive.

Make sure you have a backup of your data


Sounds great! Just to clarify – it doesn’t rename files retroactively, does it? Only on active file? Do you plan to add it to the community plugins?

1 Like

This solves a workflow issue for me! Does the H1 have to be on the first line, or will the plug-in find the first H1 regardless of which line it is on?

(Also curious about the backlink section. How do you do that?)

It doesn’t rename retroactively, but when you open a file it will rename the first heading to the current filename. Probably should add a setting for that or some kind of way to identify which files it should run on and ignore existing files by default, hmmmm

It’s submitted to the community plugins now

There’s a setting where you can adjust how many lines it should check. By default it’s 1 but you can change it up to 10 currently

In my tests on files that I never opened before, it ended up renaming the heading somewhere down the file so I prefer just the top.


Before Obsidian, I used NotebooksApp, which names your files based on their first line of text… but only if the filename it would generate for the current heading matched its existing filename when you opened it, or if the file was untitled to begin with.

It didn’t support front matter, alas. But this approach is nicely non-destructive since it effectvely only renames files that it named in the first place.

(Of course, my personal preference is to sync from header to filename, almost never the other way around.)


Yeah the logic definitely needs some revamping to make it less destructive. Maybe some toggles in the settings, or commands you have to manually run to “start syncing”.

When you open a file, it doesn’t rewrite the filename, just the heading of that file. Only if you were to update that heading it would rename the file, but even for me it messed up some headings that I created before using this plugin :innocent:

I want to add some kind of tag to the file to mark it as “this is enabled for syncing” but don’t want to insert random stuff into documents


could we have a setting to exclude a Templates folder?


If you have any good ideas how to handle exclusions (or inclusions) in a nice way, let me know and I’ll try to get it in.

Having a “excluded folder” setting doesn’t scale nicely and doesn’t fix the underlaying problem on what should happen when.

Maybe an “exclude this file” command? And save that into the state of this plugin. Although that could get big over a longer period of time.

I asked about the availability of the plug-in in the Discord channel. Excellent work, btw.

Some people like myself prefer lower case filenames. A setting to lower case the filename perhaps?

Thanks, this looks useful

This plugin is currently not updating backlinks yet. That’s a bug in obsidian is and being worked on according to some folks on the discord.

I also created Vault.rename(file, path) is not updating existing links

The plugin should insert the heading after the YAML frontmatter, if present.


Released 1.1.0 with support for ignoring certain files through a new “ignore this file” command

Also fixed the issue that links aren’t updated when renaming through this plugin

1 Like

It’s failing to install for me.

I had it installed previously, then it said there was an update. Tried to update, failed. Removed the plugin and attempted to install, but now it fails installation. So it seems something is wrong with the most recent release.

Are you on the required version (0.11.0)? I just tried to reinstall it on a different machine (both update from 1.0 and remove → install) and had no issues here
Screen Shot 2021-02-23 at 11.15.14

1 Like

I thought automatic updates kept it updated, but turns out I needed to relaunch.

I now have it reinstalled. Thank you!

Can we just use some internal reference to file name?
Some something like:

## {file_name}

  • so it will just refers to file name
  • when the filename is changed the header is change.

With this we don’t need plugin.


Could this update the title in yaml frontmatter as well? That would be even more useful to me :slight_smile:


I don’t use frontmatter. How does this look like, can you post an example?
Is this normalized and common, or more something specific to your setup?