Slugify headings for filenames in Obsidian

I am integrating Obsidian into the publishing workflow for my various outputs. I figured, if I make getting my stuff out easier, I'll be inclined to do it more often. Will this strategy work? We'll find out.

With Obsidian, you can manage your filenames and note titles separately, which is nice, but slow. There's also obsidian-filename-heading-sync which allows you to synchronise the filename and the note title. Which is great, and makes finding stuff in the filesystem as well as in Obsidian very easy.

But for publishing, it creates some horrendous-looking URLs. Me? I like slugs.

Which creates a bit of a conflict when it comes to file-naming. Sure, I could push the markdown files as is to my Next.js sites and have that deal with it, but what if I want to link to my other content internally?

Oddly though, despite there being a bunch of things you can do with Obsidian or that someone else has created to solve my problems, this wasn't one of them.

So I made my own plugin: obsidian-slugify-heading-filename1

It's forked off of obsidian-filename-heading-sync, but the features of mine are:

  • Works one-way only. It renames the file but does not change the h1. If you manually rename the file it will not change the h1.

  • Is opt in only and only affects the files that you specify by regex. If you use the same regex that you use in obsidian-filename-heading-sync for exclusion, you won't get overlaps. Which is good because although I haven't tested it, I have a strong feeling2 that they won't work together.

  • Has an optional delimiter setting to account for filename-based sorting, eg. "1 -- A Title". This is because I am also using obsidian-file-order, which I'm doing because I'm also using this mechanism to manage a separate Obsidian vault as the knowledge-base for the SaaS I am releasing Soon(TM) and some of the items I want displayed in a specific order.

The slugification process is pretty basic and comes from How to slugify a string in JavaScript. In summary, it strips out special characters, simplifies diacritics, makes it all lowercase, then kebabcases it. It does not touch stop words. Why?

Tweet from John Mueller from Google saying not to worry about stop words and to write naturally
John Mueller, Search Analyst at Google, on stop words in searches

Also, removing stop words can sometimes change the intent of what that slug might convey.

If you use this, let me know. It works for me, so I hope it works for you, too.

Footnotes

  1. Should I be sharing this? I don't know. I made it for myself and I haven't released it in the official plugin ecosystem, so if you want it you have to do it the manual way and if you happen to find it works and is useful to you, maybe I'll submit it. ↩

  2. This means I don't expect it to work. If it does, that's great. If it doesn't, that's out of scope. ↩

Published December 31, 2023