Simple Mentions

Obsidian Simple Mentions

Reference people anywhere in your notes with @mentions, backed by a single, plain-Markdown contact database.

Installation

• Community Plugins (recommended): Obsidian Settings → Community plugins → Browse → search for "Simple Mentions" → Install → Enable.
• Manual (for testing): copy main.js, manifest.json, and styles.css from a GitHub Release into .obsidian/plugins/simple-mentions/, then enable in Settings → Community plugins.

Getting started

Enable the plugin and it creates a Contacts.md file in your vault root, pre-filled with one example contact. Open it and edit to fit your team — the plugin picks changes up automatically, no rebuild needed.

If a file already exists at the configured path but isn't a valid contact table, the plugin never overwrites it — it creates a fresh database under a new name (e.g. Contacts-1.md) and saves that path to Settings.

The contact database

Contacts live in one plain Markdown table file (default Contacts.md), one row per contact:

| Mention   | Name              | Profession            | Organization    | Email               | Phone        |
| --------- | ----------------- | --------------------- | --------------- | ------------------- | ------------ |
| misirAli  | Misir Ali (dummy)| Professor (Psychology)| Dhaka University| [email protected]   | +88017123456 |
| mou        | Mou Rahman        | Software Engineer     | Acme Inc        | [email protected]     |              |

Rules:

• The table header IS the schema. Add, remove, or rename a column and the plugin follows. Mention is the one required column — it can be anywhere, not just first.
• Every row needs a Mention value — this becomes the @mention key in your notes. Rows without one are skipped.
• Mention keys may contain only letters, digits, and underscores — e.g. misirAli, rupa_n, TEST_NAME. No spaces, hyphens, or punctuation. A row with an invalid key is skipped (it can never be mentioned or rendered) and reported by the Validate database command. Matching is case-insensitive by default.
• The file is 100% portable Markdown — readable on GitHub, VS Code, and mobile without the plugin.

Using mentions

Type @ anywhere in a note to trigger autocomplete:

Talked with @misirAli about the project.

Selecting a suggestion writes the mention key (e.g. @misirAli) — stable even if the person's name or details change. The note displays the contact's name instead of the raw key:

• Reading View and Live Preview: the mention renders as the contact's name — linked and color-highlighted, with a hover card showing their details.
• Live Preview: place the cursor on a name and it reveals the raw @misirAli for editing; move away and it collapses back to the name.
• Cmd/Ctrl-click a mention to open the contact database.

Commands

Renaming a mention

Rename a Mention key directly in the contact database (e.g. change rupa_n to ruponti in the table). The plugin picks the change up automatically and rewrites every matching @rupa_n across your vault to @ruponti, then shows how many files were updated.

• The When a mention key changes setting controls this: Always update vault rewrites immediately, Always ask confirms first, Never update vault leaves your notes alone.
• If the plugin can't tell which new key replaced an old one (you also edited other fields, or deleted the row), it leaves notes as-is and tells you.

Settings

• Database location — vault path to the contact file
• Trigger character — defaults to @
• Case-sensitive mention keys — off by default
• Name mode — single field or first/last, with a First Last / Last, First order choice
• Search fields — which fields the fuzzy matcher scans
• Popup columns — which columns appear in the suggestion popup
• Hover card fields — fields shown on hover
• Rename policy — always ask, always update, or never update vault notes

License

MIT