Renami Obsidian Plugin

An Obsidian plugin for content-aware automatic note name management.

[!IMPORTANT]

Renami is in early development and specifically targets the author's niche use-cases.

It is not yet (and might never be) available in Obsidian's community plugin registry, and must be installed manually if you want to use it.

The plugin will remain zero-versioned until it's reasonably safe and intuitive to use. Caveat emptor.

Table of contents

• Overview
• Quick start
• Features
• Usage
• Privacy and security
• Background
• Maintainers
• License

Overview

Renami is a plugin for Obsidian that dynamically updates your notes' file names based on their content or other rules.

It provides extensively customizable, per-folder, template-based rules that can easily set Obsidian note file names based on their content or property (Markdown frontmatter) values.

Quick start

1. Prerequisites

   The Obsidian desktop application. (The Renami Obsidian plugin has been tested with Obsidian 1.12.4+ on macOS.)

2. Plugin installation

   Renami is not currently available in Obsidian's community plugin registry. Download the latest version from GitHub and unzip it into your vault's .obsidian/plugins folder. Then restart Obsidian.

3. Configure

   Open the Renami settings tab in Obsidian, pick a folder you'd like to manage with Renami, and define a template string for the filenames in that folder. (See the Settings section for more details.)

4. Rename

   Run the Renami: Update note file names command to rename your notes. You can also trigger a rename manually via the button in the Renami settings tab.

Features

• Name notes based on property fields (Markdown frontmatter) via simple string-based templates
• Name notes based on specific chunks of content like a # Heading with flexible CSS-like query selectors
• Format numbers and dates in your note names
• Enforce consistent case styles, e.g., kebab-case, Title Case, etc.
• Enforce maximum note name lengths (with customizable elision strings ..., and smart truncation on word boundaries)
• Automatic note name collision resolution with numeric increments
• Optional "Automatic rename" mode that runs Renami whenever your notes change

Usage

Commands

The Renami plugin provides a single command, which will rename all notes in the folders specified in the settings tab according to your template string:

Renami: Update note file names

Settings

Templates

Renami will rename notes in the listed folders according to the associated template strings. Renaming is always recursive, and templates defined lower in the list will take precedence over earlier ones matching the same files.

You can define multiple folder + template pairs. Use the drag handle (:::) to reorder rows, and the X to delete a row. Click the "Add folder" button to add a new pair.

Folder path

Specify the folder to watch in your vault. Renaming applies recursively to all sub-folders unless overridden by a rule below it that matches the same path. Start typing to get suggestions.

Template string

A template defining how to generate the filename.

Syntax

Single braces, { and }, surround accessors to the note's properties object (frontmatter), e.g. {title} or Meeting about {tags[0]}.

Double braces, {{ and }}, surround selector queries to the Markdown AST associated with the file, e.g. {{heading}}.

Single and double braces may also contain | characters to delimit basic per-placeholder inline transformation commands. More details below in the Inline formatting section.

Strings outside of braces are treated as literal text.

If no object or selection path can be resolved inside brackets, then an empty string '' is returned at that position.

Example of a template string for a folder full of meeting notes:

{Date|yyyy-MM-dd} - {Client} - {Project} - {Subject}

(This assumes that each note has Date, Client, Project, and Subject properties.)

Inline formatting

Within either single or double brace template keywords, an optional | character may be followed with a string to perform keyword-specific formatting. The interpolator will make a best-effort attempt to process the resolved value based on the string provided after the |. Multiple formatters may be chained.

Given a string template like {key|format}, the format string will be tested for a match against the following rules, in order:

Case changes

If the format string is a case type name, the content of the template key will be transformed accordingly. This may be overruled by the "global" case Transformation setting.

Note - {title|uppercase} → Note - TITLE FROM FRONTMATTER

Supported strings are 'camel', 'kebab', 'lowercase', 'pascal', 'preserve', 'screaming-kebab', 'screaming-snake', 'sentence', 'slug', 'snake', 'title', and 'uppercase'.

Number formatting

Next, Renami will attempt to parse the resolved value as a number and format it according to the numerable library's format syntax. (Similar to formats specified by TR35 / ICU 67.)

If the count property is 22000, then:

I have {count|0,0} → I have 22,000

Date formatting

Next, it will attempt to parse the resolved value as a date and format it, using patterns based on Unicode Technical Standard #35. (See here for a nice reference.)

'My Note about {{heading}} - {date|yyyy-MM-dd}' → My Note about Stuff - 2025-03-15

Max length

Passing a positive integer will truncate the resolved value to a specific character length.

If the title property is This is a very long title, then:

'Note - {title|5}' → Note - This...

If none of the above value / format string combinations are valid, then the format string is ignored and the resolved value is returned as-is.

Transformation

These options apply globally to all templates.

Case

Determines the character case of the generated filename.

Default: Preserve

Available options:

• Preserve - Keep the original case of the filename.
• camelCase
• kebab-case
• lowercase
• PascalCase
• SCREAMING-KEBAB
• SCREAMING_SNAKE
• Sentence case
• slug - Convert to a URL-friendly slug.
• snake_case
• Title Case
• UPPERCASE

Collapse whitespace

Enable to reduce sequences of multiple whitespace characters into a single space in the generated filename.

Default: Disabled

Trim

Enable to remove leading and trailing whitespace from the generated filename.

Default: Enabled

Truncation

These options apply globally to all templates and control how long filenames are handled.

Maximum length

Sets the maximum number of characters allowed in the generated filename (excluding the .md extension).

Default: 255

Elision text

The string used to indicate that a filename has been truncated (e.g., "..."). This string counts towards the maximum length.

Default: ...

Find word boundary

When enabled, the maximum length cut-off will occur at the nearest word boundary before the maximum length is reached, preventing words from being cut off mid-way. If disabled, truncation happens exactly at the maximum length.

Default: Enabled

Delimiters

These options apply globally to all templates and control the characters used between extracted parts of the filename.

Delimiter text

The character(s) used to join different parts selected by the template string.

Default: -

Collapse duplicates

Reduce multiple consecutive delimiter characters (resulting from empty template parts or adjacent delimiters in the template) into a single delimiter.

Default: Enabled

Advanced

Automatic rename

When enabled, Renami will monitor the notes specified in the Templates section and trigger a rename almost immediately after detecting a change that might affect the filename. When disabled, renaming must be initiated manually via a command or the "Rename now" button.

Default: Disabled

Automatic rename delay

The minimum time (in milliseconds) that must pass between automatic rename checks after a file change is detected. This prevents excessive renaming triggers during rapid edits. Obsidian must be restarted for changes to this setting to take effect.

Default: 1000

Ignore folder notes

Exclude notes that have the exact same name as their parent folder (e.g., FolderA/FolderA.md) from the renaming process. This is useful when using plugins like Folder notes.

Default: Disabled

Verbose notices

Enable to see additional details (via Obsidian notices) during the renaming process, which can be helpful for debugging templates.

Default: Disabled

Strict

Enables strict idempotence. If a template fails to generate a valid name for a file:

• When Strict mode is enabled, the file will be renamed to the default file name value (see below).
• When Strict mode is disabled, the file's original name will be preserved if the template fails.

Default: Disabled

Default file name

The fallback filename used for notes when "Strict" mode is enabled and the template fails to produce a valid name.

Default: Untitled

Configuration

Copies the underlying stand-alone Renami library configuration generated from the current plugin settings to the clipboard.

Privacy and security

Network use

Renami does not make any network calls.

Note that Obsidian itself may send data to other networks, such as synchronization services like Obsidian Sync. Please see Obsidian's terms and privacy policy for more details.

File access

File access is implemented with Obsidian's vault APIs.

Local logging

For debugging purposes, Renami maintains simple local counters of how many notes have been renamed successfully. Renami doesn't send these statistics anywhere, and they are accessible to you in the plugin's setting tab.

Background

Implementation notes

The Renami Obsidian plugin is built on Renami. All functionality not specifically related to Obsidian is managed under the Renami project repository, including automated tests and additional documentation.

If you want to rename files like the Renami Obsidian plugin does from outside of Obsidian, the stand-alone renami CLI tool and TypeScript library implement all of the same core features and also expose a more powerful configuration model that lets you easily write custom template logic in TypeScript or JavaScript.

Avoiding lock-in

Every Obsidian-only plugin, Markdown extension, and proprietary-API creates a subtle degree of lock-in to the tool — intentional or otherwise. Yes, your notes are "just" Markdown files, but where their utility or upkeep depend on Obsidian-specific features, their portability and future flexibility are diminished.

Obsidian's great for now, but it's inevitably transitory. Markdown is going to be around much longer than Obsidian will.

For this reason, I'm trying to ensure that the tools I write for my own workflows are "Markdown first" and as context-agnostic as possible, behaving identically whether invoked directly as stand-alone tools or through an Obsidian plugin command. That's why the Renami Obsidian plugin is architected as a very thin wrapper over the underlying stand-alone CLI version of Renami.

Other Obsidian file renaming plugins

There are lots of handy filename-related plugins available for Obsidian, but many are highly specialized.

I've linked to some below, and, where applicable, shown the Renami template string that does the same thing.

• Filename Heading Sync (Plugin)

  Keep the filename with the first heading of a file in sync.

  Filename Heading Sync does bidirectional sync — Renami only syncs from file content → file name. Nevertheless, you can replicate that half of the plugin's behavior with the following Renami template:

  {{heading}}
  

• Auto Filename (Plugin)

  Automatically rename files on the go based on the first x characters of files.

  To replicate this in Renami, combine the "all" selector with the inline or global max-length option to get the first X characters of the file content you'd like to use as the filename.

  {{*|20}}
  

• Safe Filename Linter (Plugin)

  Lint filenames for invalid or troublesome characters.

  Renami does this automatically on any file it touches via the filenamify library.

• Front Matter Title (Plugin)

  Define a title in frontmatter to be displayed as the filename.

  This plugin only changes the display of the filename in Obsidian, not the actual filename.

  To change the actual filename in Renami to match the title field in frontmatter, you'd use the following template:

  {title}
  

• Copy Metadata (Plugin)

  Copy file metadata, e.g., creation time, to clipboard. Insert copied metadata to file name.

  The lower-level stand-alone Renami CLI tool / library could do this sort of thing directly. In Obsidian, you could use the obsidian-frontmatter-modified-date plugin or similar to put the modification time in the file's frontmatter, and then use Renami to set the filename from the frontmatter field. If the frontmatter key where the modification date is stored is named modified, then the Renami template is as simple as:

  {modified}
  

• Vault File Renamer (Plugin)

  Automatically standardizes file names to GitHub style while preserving folder structure and file contents.

  In Renami, you can set the Case setting to "slug", and use an empty template string to preserve the existing filename while slugifying the filename. (Renami uses github-slugger, which should match GitHub's style.)

  {}
  

• Bulk Rename (Plugin)

  Rename files based on a pattern.

  Bulk Rename operates on existing filenames via find-and-replace patterns, which is a different approach from Renami's content-to-filename generation. No direct Renami template equivalent in the Obsidian plugin, but the stand-alone Renami library's custom transform functions receive the current filename and could implement similar logic.

• Title Generator (Plugin)

  Quickly and easily title your notes using OpenAI's GPT-3.5.

  Renami does not have AI integration. However, a custom transform function in the stand-alone Renami library could call an external API to generate titles.

• Filename Emoji Remover (Plugin)

  Automatically remove emojis from filenames.

  Renami automatically strips invalid filename characters via filenamify, but emojis are valid filename characters and are not removed. A custom transform function in the stand-alone Renami library could handle this.

  If you want to associate emojis with your notes without polluting the actual file names, I'd suggest looking at the iconize plugin.

Maintainers

@kitschpatrol

License

MIT © Eric Mika