Note UID Generator

UID Generator Plugin for Obsidian

Overview

The UID Generator plugin for Obsidian provides tools to create and manage unique identifiers (UIDs) for your notes directly within their frontmatter metadata. It supports multiple generator algorithms — UUID (v4), NanoID (customizable length, alphabet, and separators), ULID (lexicographically sortable), and Snowflake (64-bit time-sortable distributed ID) — along with manual and automatic UID generation, customization of the metadata key and copy formats, and bulk operations within folders. This helps in creating stable, unique references for your notes, useful for linking, scripting, or external systems.

Features

• Multiple Generator Algorithms:
  • UUID (v4) — Standard 36-character universally unique identifier.
  • NanoID — Customizable length, alphabet, and optional separator characters injected at specific positions.
  • ULID — 26-character, lexicographically sortable identifier that encodes creation time (useful for chronological ordering).
  • Snowflake — 64-bit time-sortable numeric ID (41-bit Unix timestamp + 10-bit node ID + 12-bit per-ms sequence). Node ID is auto-derived from the machine's MAC address on desktop and falls back to a random persistent value on mobile; both can be overridden manually.
• Collision Avoidance: An in-memory index of every UID in the vault ensures newly generated IDs are unique, with automatic retry on collision.
• Duplicate Detection: Catches UIDs that were never generated here — a note copied, synced in, or made from a template arrives carrying somebody else's UID, which collision avoidance cannot see.
  • On new notes: When a note is created carrying a UID another note already has, the plugin can show a notice or generate a fresh UID for the newcomer (never for the note it came from). Configurable, including off.
  • Vault-wide scan: Lists every UID more than one note carries — from the ribbon, the command palette, or a settings button. For each note you can either keep its UID (the rest of the group gets fresh ones) or give just that one a fresh UID.
  • Type-agnostic: The scan groups notes by the raw value under your configured UID key, so UUIDs, NanoIDs, ULIDs and Snowflakes are all compared together — switching generator algorithms never hides a duplicate.
• Generate/Update UID: Manually generate a new UID for the current note, optionally overwriting any existing UID under the configured key.
• Create UID If Missing: Manually generate a UID for the current note only if one doesn't already exist.
• Remove UID: Manually remove the UID from the current note's frontmatter.
• Copy UID: Copy the UID of the current note to the clipboard.
• Copy title + UID: Copy the title and UID of the current note (or multiple selected notes) to the clipboard, using a customizable format.
• Automatic UID Generation: Automatically add a UID to notes upon creation or opening if they lack one.
  • Configurable scope (entire vault or one or more specific folders).
  • Ability to exclude specific folders.
  • Never overwrites existing UIDs during automatic generation.
• Clear UIDs in Folder: Remove all UIDs (using the configured key) from notes within a specified folder and its subfolders, with confirmation.
• Customizable UID Key: Choose the frontmatter key name for your UIDs (e.g., uid, id, noteId).
• Customizable Copy Format: Define templates for how title/UID information is copied.
• Ribbon Icon: Quick access to "Create UID if missing" for the current note.
• Context Menu Actions:
  • Right-click a folder: Copy titles+UIDs for all notes inside.
  • Right-click a single note: Copy Title+UID.
  • Right-click multiple selected notes: Copy titles+UIDs for the selection (uses undocumented files-menu event).
• Folder Path Suggestions: Autocomplete suggestions for folder paths in settings.

Installation

1. Download the plugin files (main.js, manifest.json, styles.css) from the latest release on the GitHub repository (or build them yourself).
2. Create a new folder named obsidian-note-uid-generator inside your Obsidian vault's plugins folder (YourVault/.obsidian/plugins/).
3. Copy the downloaded main.js, manifest.json, and styles.css files into the obsidian-note-uid-generator folder.
4. Restart Obsidian or reload plugins.
5. Go to Obsidian Settings -> Community plugins.
6. Find "UID Generator" in the list of installed plugins and enable it.

Usage

Commands

The plugin provides the following commands accessible from the command palette (Ctrl+P or Cmd+P):

• UID Generator: Generate/Update [YourKeyName] (Overwrites): Creates a new UID for the current note. If a UID already exists under the configured key name ([YourKeyName]), it will be replaced.
• UID Generator: Create [YourKeyName] if missing: Creates a new UID for the current note only if one doesn't already exist under the configured key name.
• UID Generator: Remove [YourKeyName] from current note: Deletes the UID key and value from the current note's frontmatter.
• UID Generator: Copy [YourKeyName] of current note: Copies the UID value to the clipboard. (Only available if the current note has a UID).
• UID Generator: Copy title + [YourKeyName]: Copies the current note's title and UID using the configured format. (Always available if a note is open).
• UID Generator: Copy titles+[YourKeyName]s for selected files: Copies the titles and UIDs for all Markdown files currently selected in the file explorer, using the configured format. (Only available when the file explorer is active and has Markdown files selected).
• UID Generator: Scan for duplicate [YourKeyName]s: Reads every note in the vault and opens a report of the UIDs more than one note carries. Reports a notice instead when there are none.

Ribbon Icons

Two ribbon icons are added to the left sidebar:

• Fingerprint: performs the Create [YourKeyName] if missing action on the currently active note.
• Magnifier: runs Scan for duplicate [YourKeyName]s over the whole vault.

Context Menus

• Right-clicking a Folder in the file explorer: Provides an option Copy titles+[YourKeyName]s from "[FolderName]". This copies the titles and UIDs of all Markdown notes within that folder (and subfolders) according to your format settings.
• Right-clicking a Single Markdown File: Provides an option Copy Title+[YourKeyName]. This copies the title and UID for that specific file.
• Right-clicking multiple selected files: Provides an option Copy titles+[YourKeyName]s for X selected. This copies the titles and UIDs for all selected Markdown files.
  • Note: This specific multi-file context menu relies on an undocumented Obsidian event (files-menu). While functional, it could potentially break in future Obsidian updates. The Command Palette option provides a more stable alternative for multi-file selection.

Settings

Access the plugin settings from Obsidian Settings -> Community Plugins -> UID Generator:

• General:
  • UID Metadata Key: Set the frontmatter key name used for storing UIDs (default: uid). Avoid spaces.
• UID Generator Type:
  • Generator Algorithm: Choose between UUID, NanoID, ULID, or Snowflake.
  • NanoID Length: (NanoID only) Length of the generated ID, excluding separators. Min 4, max 128. (Default: 21)
  • NanoID Alphabet: (NanoID only) Characters used for ID generation. Must have at least 2 unique characters. (Default: 0-9A-Za-z)
  • NanoID Separator Groups: (NanoID only) Inject characters at specific positions in the generated ID. Positions can be negative (count from end). Multiple groups supported.
  • Machine Node ID: (Snowflake only) Read-only display of the 10-bit node ID derived from this machine — MAC-hashed on desktop, random persistent on mobile. Used for generated IDs unless a Custom Node ID is set below.
  • Custom Node ID: (Snowflake only) Optional override (0–1023). When set, takes precedence over the Machine Node ID. Leave empty to use the machine value.
• Automatic UID Generation:
  • Enable Automatic UID Generation: Toggle the automatic creation of UIDs on/off.
  • Generation Scope: Choose Entire Vault or Specific Folder(s).
  • Target Folders for Auto-Generation: (Visible if Scope is 'Specific Folder(s)') Click "Manage folders" to open a modal where you can search, add, or remove folders that should be in scope for auto-generation. Notes in any of the listed folders (including subfolders) are eligible. Settings created with previous versions of the plugin are migrated automatically.
  • Excluded Folders: Click "Manage Exclusions" to open a modal where you can search, add, or remove folders that should be ignored by automatic generation. The current list is displayed below the button.
• Duplicate UIDs:
  • On a new note arriving with a duplicate UID: Do nothing, Show a notice (default), or Generate a fresh UID. Only ever applies to notes as they are created — an existing note you merely edit is never rewritten, so the note a copy was taken from keeps its UID.
  • Scan the vault for duplicate UIDs: Reads every note and opens a report of the UIDs more than one note carries. Also available from the ribbon and the command palette. Each group lists its notes oldest first, and each note offers two ways out:
    • Keep this one — this note keeps the UID; every other note in the group gets a fresh one. Best when you know which note is the original.
    • New UID for this one — only this note gets a fresh UID; the rest of the group is left alone. Best when you know which note is the copy, or when resolving a large group one note at a time.
    • Keep the oldest in each resolves every group at once, keeping the oldest note in each.
• Copy Format:
  • Format (UID exists): Define the template for copied text when a UID is present. Use placeholders {title}, {uid}, {uidKey}. (Default: {title} - {uidKey}: {uid})
  • Format (UID missing): Define the template for copied text when a UID is missing. Use placeholders {title}, {uidKey}. (Default: {title} - No {uidKey})
• Manual UID Clearing:
  • Folder to clear UIDs from: Specify the vault path for the bulk removal action. Uses folder path suggestions.
  • Clear UIDs Now: Button to initiate the removal process for the specified folder.
    • Warning: This is irreversible.
    • A confirmation modal will appear.
    • If automatic UID generation is enabled, it will be temporarily disabled as a safety measure when you confirm the deletion. You will be notified and can re-enable it afterwards.

Example Usage

• Ensure a Note Has a Unique ID: Open the note, open the command palette, run UID Generator: Create uid if missing.
• Link Using UID: Open a note, run UID Generator: Copy uid, paste the UID into another note's link or alias.
• Auto-Assign IDs to New Notes in Inbox: Enable Automatic Generation, set Scope to 'Specific Folder(s)', click "Manage folders" and add Inbox (and any other target folders).
• Clean Up Old IDs: Set 'Folder to clear UIDs from' to Archives/Old Project, click 'Clear UIDs Now', confirm.
• Get List of Project Notes with IDs: Right-click the Projects/Current Project folder, select Copy titles+uids from "Current Project".
• Clean Up After Copying Notes: Click the magnifier in the ribbon (or run Scan for duplicate uids). For each group, either 'Keep this one' on the original or 'New uid for this one' on the copy — or 'Keep the oldest in each' to resolve every group at once.

Development

For developers interested in contributing:

Setup

1. Clone the GitHub repository to your local machine.
2. Navigate to the repository directory.
3. Install dependencies: npm install (or yarn install).

Build

• To compile the TypeScript code to JavaScript (main.js), run: npm run build (or yarn build).
• For development, you can often use a watch command like npm run dev (if configured in package.json) to automatically rebuild on changes.

Code Structure

The code splits in two: src/uid is the domain (what a uid is and what can be done to one), src/plugin is the Obsidian-facing surface (commands, settings, events). Each folder is entered through one file — its "door" — and the split is checked in CI by npm run arch.

• src/main.ts: The Obsidian entry point (UIDGenerator, onload), which does nothing but start the plugin.
• src/plugin/: register.ts wires every surface into Obsidian; state.ts adapts Obsidian's persistence to the domain's port.
• src/plugin/commands/: Command, ribbon and context-menu handlers, registered by commands/register.ts.
• src/plugin/settings/: SettingsTab.ts plus one folder per settings feature — generator/, autoGeneration/, clearing/ — each owning the widgets and vault pass it uses.
• src/plugin/duplicates/: The duplicate scan, its report modal and its settings section. It sits beside commands/ and settings/ because it is both, and plugin/register.ts wires it into each.
• src/settings.ts: The persisted settings shape, its defaults, and the migration of whatever an older version wrote.
• src/uid/: context.ts (what the domain needs from its host), noteUid.ts (read/ensure/renew/clear one note's uid), bulk.ts (vault-wide passes), duplicates.ts (notes sharing a uid), scope.ts, folderNotes.ts.
• src/uid/generators/: generate.ts (unique ids, retrying past collisions) over the UUID, NanoID, ULID and Snowflake modules.
• src/uid/storage/: Frontmatter read/write, the UidIndex of which notes carry which uid, and the vault sync that keeps it current.
• src/plugin/obsidian.d.ts: TypeScript declarations for undocumented Obsidian APIs used (like files-menu).

Contributing

Contributions, issues, and feature requests are welcome! Please feel free to check the issues page or submit a pull request on the GitHub repository.

License

This plugin is licensed under the OBSD License. See the LICENSE file for details.