Concepts

Concepts is an Obsidian plugin for building a wiki-like concept index from definitions, theorems, and other callout blocks. It is especially useful for mathematical notes.

Features

• Add any rendered callout to the concept database with the button in its top-right corner.
• Use the callout title as the canonical concept name and optionally record aliases.
• Give each registered callout a stable Obsidian block ID.
• Link a selected name or alias with the Concepts: Link concept at cursor or selection command (Ctrl/Cmd+Shift+K by default).
• Choose between concepts that share a term from a popup next to the line you are typing on.
• Insert any concept link on demand with Concepts: Choose concept to link from popup (Ctrl/Cmd+Shift+L by default). This opens a searchable list of concepts.
• Write aliases as regular expressions to cover plurals and phrasings.
• Use Link concept from the editor context menu.
• Automatically update the concept record when a callout and its block ID move to another note.
• Rewrite every [[…#^concept-…]] link across the vault so it follows the callout to its new note.
• Browse and edit concept records through an automatically created Obsidian Base.

For example, selecting Banach space and running the link command produces:

[[Banach Spaces#^concept-a1b2c3d4e5f6|Banach space]]

Usage

Write a callout with a useful title:

> [!definition] Banach Space
> A complete normed vector space.

In Live Preview or Reading view, hover over it and select the book-plus button. Confirm the name and add comma-separated aliases. Concepts adds a block ID after the callout:

> [!definition] Banach Space
> A complete normed vector space.

^concept-a1b2c3d4e5f6

It then creates:

• Concepts/Database/Banach Space.md, a concept record with the name, aliases, source path, block ID, callout type, target, and timestamps.
• Concepts/Concepts.base, a table view over all concept records.

The paths can be changed in Settings → Concepts. Change them before registering concepts; path changes take effect after reloading the plugin.

A callout stays recognized whether its ^concept-... ID sits on its own line beneath the callout, on a quoted line inside it, or at the end of its last quoted line. Clicking the button on a callout that is already registered opens Update concept prefilled with the stored name and aliases; submitting it records the callout's current note and rewrites every reference to it across the vault.

When moving a callout, include the blank line and ^concept-... line beneath it. The stable ID lets Concepts discover the new note, rewrite the database target, and update every link to that concept throughout the vault so none of them break. Concepts: Rebuild concept locations performs a full manual rescan if files were changed outside Obsidian.

Vault-wide link updates are controlled by Update links across the vault in Settings → Concepts (on by default). Each link's note path is rewritten to the callout's new location while the visible text is preserved, so [[Analysis#^concept-a1b2c3d4e5f6|Banach space]] becomes [[Functional Analysis#^concept-a1b2c3d4e5f6|Banach space]]. Embeds (![[…]]) are updated too. After the vault scan finishes, Concepts displays a notice with the number of links updated.

Choosing between concepts that share a term

Terms such as product belong to several concepts at once: the product of topological spaces, the Cartesian product of sets, and the product object in a category. When the link command finds more than one candidate, Concepts opens a popup beside the line you are typing on, listing each concept with its callout type and note so the right one is obvious. Picking an entry keeps the text you typed as the link's display name.

Concept popup position in Settings → Concepts chooses whether that popup opens below the line (the default) or above it. Either way it flips to the other side when there is not enough room on screen.

Concepts: Choose concept to link from popup opens a searchable list of concepts on demand, so it is available even when nothing is ambiguous. With the cursor on a known term, the list narrows to the concepts claiming it and the typed text is preserved. Otherwise every concept is listed and the chosen one is inserted under its own name. The default hotkey is Ctrl/Cmd+Shift+L and can be changed in Settings → Hotkeys.

Choose concept link interface in Settings → Concepts switches that command between Search all concepts (the default) and the small Popup menu beside the cursor. The popup that appears when a term belongs to several concepts still uses the small menu, and Concept popup position applies to that menu.

Regular expression aliases

An alias wrapped in slashes is treated as a regular expression, using the same JavaScript syntax as the JavaScript flavour on regex101. Anything else is matched literally.

Flags go after the closing slash, so /Product/i ignores case. When Case-sensitive linking is off, the ignore-case flag is added for you.

Literal aliases only match between word boundaries, so product never matches inside counterproductive. A regular expression is assumed to express its own boundaries, which lets a pattern match a fragment on purpose; add \b when you do not want that. An alias whose pattern cannot compile is ignored, so a typo in one alias never stops the rest from linking.

Install with BRAT

1. Install and enable BRAT.
2. Open Settings → BRAT → Add Beta plugin.
3. Paste this repository's public GitHub URL.
4. Enable Concepts under Community plugins.

BRAT requires manifest.json, main.js, and optionally styles.css in the repository or a release. This repository's build and release workflow provide those files.

Manual installation

Copy manifest.json, main.js, and styles.css into:

<vault>/.obsidian/plugins/concepts/

Then reload Obsidian and enable Concepts.

Development

npm install
npm test
npm run build

The production build writes main.js at the repository root. Tagged versions should match manifest.json, package.json, and versions.json.

Data model

Concept records are plain Markdown files, so the database remains usable without this plugin. The frontmatter fields are:

Start-up behaviour

Obsidian loads plugins while it is still indexing the vault, so Concepts registers its commands, settings, and callout buttons immediately and opens the concept database once the workspace is ready. Notes that were already rendered are refreshed at that point so their callout buttons show the correct state. If the database cannot be opened, the plugin stays loaded and reports the problem; Concepts: Rebuild concept locations retries.

Limitations

• The callout title should be plain text. Rich Markdown in a title is normalized when used as a concept name.
• Moving only the quoted lines and leaving the block ID behind breaks identity tracking. Move the ID with the callout.
• Concepts adds buttons through Obsidian's rendered Markdown API. Some heavily customized themes or callout plugins may alter the button position.

License

MIT