Title Sync Plugin for Obsidian

Sync the first H1 header of a markdown file with its filename using a manual command.

Note: This plugin is currently under review for inclusion in the Obsidian Community Plugins directory. In the meantime, you can install it manually.

Features

• Single command: "Title Sync: Sync title to filename"
• Extracts the first H1 header after frontmatter (skips code blocks)
• Transforms the title to a valid filename:
  • Strips markdown formatting (bold, italic, links)
  • Replaces illegal filename characters with dashes
  • Truncates to 200 characters for cross-platform compatibility
• Shows notification on success/failure

Installation

From Obsidian Community Plugins

Coming soon — the plugin is under review. Once approved:

1. Open Obsidian Settings
2. Go to Community Plugins and disable Safe Mode
3. Click Browse and search for "Title Sync"
4. Install and enable the plugin

Manual Installation (recommended for now)

1. Download main.js and manifest.json from the latest release
2. Create a folder title-sync in your vault's .obsidian/plugins/ directory
3. Copy main.js and manifest.json into the folder
4. Reload Obsidian
5. Enable the plugin in Settings > Community Plugins

Usage

1. Open a markdown file with an H1 header (e.g., # My Title)
2. Open the command palette (Cmd/Ctrl + P)
3. Search for "Title Sync: Sync title to filename"
4. Run the command

The file will be renamed to match the H1 header.

Setting Up a Keyboard Shortcut

1. Open Obsidian Settings
2. Go to Hotkeys
3. Search for "Title Sync: Sync title to filename"
4. Click the plus icon and set your preferred shortcut
   • Suggested: Cmd+Option+T (Mac) or Ctrl+Alt+T (Windows/Linux)

Recommended setting: disable "Show inline title"

This plugin works best with Settings → Appearance → Show inline title turned off.

When enabled, Obsidian displays the filename as an editable title at the top of each note. If your notes also have an H1 header (which this plugin syncs to the filename), you'll see the title twice — once as the inline title and once as your H1 header. Disabling the inline title avoids this redundancy and keeps your H1 as the single source of truth for the note's title.

Examples

H1 Header	Resulting Filename
# My Title	My Title.md
# My **Bold** Title	My Bold Title.md
# Title: Subtitle	Title- Subtitle.md
# Is This Valid?	Is This Valid.md
# Link to [[Page]]	Link to Page.md

Comparison with obsidian-filename-heading-sync

This plugin is inspired by obsidian-filename-heading-sync but takes a different approach:

Feature	Title Sync	filename-heading-sync
Sync trigger	Manual command only	Automatic (file open/save hooks)
Direction	H1 → filename	Bidirectional
Auto-insert heading	No	Yes
Configuration	None needed	Multiple options
Philosophy	Simple, opinionated	Feature-rich

When to choose Title Sync:

• You want full control over when syncing happens
• You prefer explicit actions over automatic behavior
• You don't need bidirectional sync or auto-insertion of headings

When to choose filename-heading-sync:

• You want automatic syncing without manual intervention
• You need bidirectional sync (filename changes update heading)
• You want the plugin to auto-insert H1 headers in new files

Development

# Install dependencies
npm install

# Build for production
npm run build

# Run tests
npm test

# Run linting
npm run lint

# Run all checks
npm run check

# Development mode (watch)
npm run dev

License

MIT