Zettel Links

Complete Zettelkasten workflow for Obsidian: create timestamp-based links and resolve them to matching notes. Works seamlessly with other Zettelkasten tools like The Archive.

Features

Link Creation

• Ribbon Icon: Click the link icon in the left sidebar (works on desktop and mobile!)
• Mobile Toolbar: Appears in the mobile toolbar when editing
• Keyboard Shortcut: Press Cmd+Shift+L (Mac) or Ctrl+Shift+L (Windows/Linux)
• Command Palette: Search for "Insert Zettel Link"
• Smart Link Formatting:
  • Files starting with timestamps (default: 12-digit YYYYMMDDHHMM) become [[timestamp]] Title
  • Regular files become standard [[filename]] links

Link Resolution

• Timestamp Resolution: Links like [[202512270824]] automatically resolve to files starting with that timestamp (e.g., 202512270824 Christmas Traditions.md)
• Partial Matching: Optional partial filename matching for greater interoperability
• Multiple Match Handling: If multiple files match, choose from a convenient picker modal
• Interoperability: Works with other Zettelkasten tools like The Archive

Usage

Creating Links

1. Position cursor where you want to insert a link
2. Trigger the modal using one of these methods:
   • Desktop: Click the link icon in ribbon (left sidebar)
   • Mobile: Tap the command in the mobile toolbar, or use the ribbon icon
   • Keyboard: Press Cmd+Shift+L / Ctrl+Shift+L
   • Command Palette: Search "Insert Zettel Link"
3. Search for the file you want to link to
4. Select the file (tap or press Enter)
5. Link is inserted at cursor position

Mobile Usage

The plugin works seamlessly on mobile:

• Mobile Toolbar: When you add the "Insert Zettel Link" command to your mobile toolbar (via Settings → Mobile), you'll see it with a link icon
• Ribbon Icon: Also available in the left sidebar ribbon
• Simply tap either one while editing to open the file picker

Examples

Zettelkasten timestamp file:

File: "202512270824 Christmas Traditions.md"
Output: [[202512270824]] Christmas Traditions

Regular note:

File: "Project Ideas.md"
Output: [[Project Ideas]]

Resolving Links

When you click on a link in your notes:

Direct match (standard Obsidian behavior):

[[Project Ideas]] → Project Ideas.md

Timestamp resolution:

[[202512270824]] → 202512270824 Christmas Traditions.md

Partial match:

[[partial-match]] → partial-matching might be unexpected.md

Multiple matches:

• A modal appears showing all matching files
• Choose the correct file from the list
• Or cancel to create a new note

No match:

[[202503102352]] unmatched link → Creates new note: 202503102352.md

How It Works

Link Creation

The plugin detects files following the Zettelkasten timestamp naming convention (configurable timestamp length, default 12-digit YYYYMMDDHHMM prefix) and automatically:

• Extracts the timestamp as the link target
• Appends the rest of the filename as readable text outside the link
• This allows concise links while maintaining readability

For files without timestamp prefixes, it creates standard Obsidian wiki-style links.

Link Resolution

The plugin overrides Obsidian's link resolution to:

1. First try standard Obsidian link matching (exact filename)
2. If no match, search for files whose names contain the link text
3. If one match found, open that file
4. If multiple matches found, show chooser modal
5. If no match, fall back to Obsidian's default (create new note)

This enables:

• Timestamp-based linking (Zettelkasten style)
• Interoperability with other Zettelkasten tools
• Partial filename matching (optional)

Settings

Access settings via Settings → Zettel Links in Obsidian.

Link Creation Settings

• Extract timestamps (default: enabled)

  • Toggle timestamp extraction on/off
  • When disabled, all links use standard [[filename]] format

• Timestamp length (default: 12)

  • Number of digits in your timestamp format
  • 12 = YYYYMMDDHHMM (e.g., 202512270824)
  • 8 = YYYYMMDD (e.g., 20251227)

• Show full path (default: enabled)

  • Show complete file paths in suggestion list
  • When disabled, shows only filenames

• Append filename after timestamp (default: enabled)

  • Include filename text after timestamp link
  • When enabled: [[202512270824]] Christmas Traditions
  • When disabled: [[202512270824]]

Link Resolution Settings

• Enable link resolution (default: enabled)

  • Resolve timestamp links to matching files
  • Enables interoperability with The Archive and other tools
  • When disabled, uses standard Obsidian link behavior only

• Enable partial matching (default: enabled)

  • Match partial filenames when resolving links
  • WARNING: This makes ALL links look for partial matches before creating new notes
  • Disable if you want standard Obsidian link behavior
  • Only active when link resolution is enabled

Development

First time developing plugins?

Quick starting guide for new plugin devs:

• Check if someone already developed a plugin for what you want! There might be an existing plugin similar enough that you can partner up with.
• Make a copy of this repo as a template with the "Use this template" button (login to GitHub if you don't see it).
• Clone your repo to a local development folder. For convenience, you can place this folder in your .obsidian/plugins/your-plugin-name folder.
• Install NodeJS, then run npm i in the command line under your repo folder.
• Run npm run dev to compile your plugin from main.ts to main.js.
• Make changes to main.ts (or create new .ts files). Those changes should be automatically compiled into main.js.
• Reload Obsidian to load the new version of your plugin.
• Enable plugin in settings window.
• For updates to the Obsidian API run npm update in the command line under your repo folder.

Releasing new releases

• Update your manifest.json with your new version number, such as 1.0.1, and the minimum Obsidian version required for your latest release.
• Update your versions.json file with "new-plugin-version": "minimum-obsidian-version" so older versions of Obsidian can download an older version of your plugin that's compatible.
• Create new GitHub release using your new version number as the "Tag version". Use the exact version number, don't include a prefix v. See here for an example: https://github.com/obsidianmd/obsidian-sample-plugin/releases
• Upload the files manifest.json, main.js, styles.css as binary attachments. Note: The manifest.json file must be in two places, first the root path of your repository and also in the release.
• Publish the release.

You can simplify the version bump process by running npm version patch, npm version minor or npm version major after updating minAppVersion manually in manifest.json. The command will bump version in manifest.json and package.json, and add the entry for the new version to versions.json

Adding your plugin to the community plugin list

• Check the plugin guidelines.
• Publish an initial version.
• Make sure you have a README.md file in the root of your repo.
• Make a pull request at https://github.com/obsidianmd/obsidian-releases to add your plugin.

How to use

• Clone this repo.
• Make sure your NodeJS is at least v16 (node --version).
• npm i or yarn to install dependencies.
• npm run dev to start compilation in watch mode.

Manually installing the plugin

• Copy over main.js, styles.css, manifest.json to your vault VaultFolder/.obsidian/plugins/your-plugin-id/.

Improve code quality with eslint (optional)

• ESLint is a tool that analyzes your code to quickly find problems. You can run ESLint against your plugin to find common bugs and ways to improve your code.
• To use eslint with this project, make sure to install eslint from terminal:
  • npm install -g eslint
• To use eslint to analyze this project use this command:
  • eslint main.ts
  • eslint will then create a report with suggestions for code improvement by file and line number.
• If your source code is in a folder, such as src, you can use eslint with this command to analyze all files in that folder:
  • eslint .\src\

Funding URL

You can include funding URLs where people who use your plugin can financially support it.

The simple way is to set the fundingUrl field to your link in your manifest.json file:

{
    "fundingUrl": "https://buymeacoffee.com"
}

If you have multiple URLs, you can also do:

{
    "fundingUrl": {
        "Buy Me a Coffee": "https://buymeacoffee.com",
        "GitHub Sponsor": "https://github.com/sponsors",
        "Patreon": "https://www.patreon.com/"
    }
}

API Documentation

See https://github.com/obsidianmd/obsidian-api