Shared Blocks

Shared Blocks

Write a block of text once, in one note, and reuse it anywhere in your vault. When you edit the original, every place that references it re-renders while you look at it.

Everything happens locally. The plugin reads and renders notes from your vault and nothing else: no account, no server, no telemetry, no network access of any kind.

Left: the note that defines the block. Right: a note that uses it twice, in Reading view. Editing the definition updates both copies as you type.

Interface languages: English, 简体中文, 日本語, 한국어, Español, Deutsch, Français, Português (Brasil) and Русский, following Obsidian's language setting. A translation that reads wrong? Open an issue with the text and what it should say.

How it works

Define a block in any note, between two markers on lines of their own:

==share:contact==
**Support:** [email protected]
Office hours: 9:00 – 17:00 CET
==/share==

The name accepts letters (accented and non-Latin included), digits, _ and -. A block with an empty body is ignored, so a half-written block reports itself as missing instead of quietly rendering nothing.

Reference it from any other note:

==ref:Company handbook^contact==

Company handbook is the note holding the definition — the same link text you would put in [[ ]], so a bare name, a subfolder path, or anything Obsidian can resolve from the note you are writing in. contact is the block name.

The reference renders the block's markdown in place, styled as a quoted block, in Reading view and in Live Preview alike. In Live Preview a reference on a line of its own shows as the rendered block, the way an embed does, and turns back into its ==ref:…== text when you click it or move the cursor onto its line. Edit the definition and every reference on screen updates, without reopening the note.

You rarely need to type a reference in full. After ==ref: the editor suggests the notes that define blocks; pick one and it suggests that note's blocks, then closes the reference for you.

References can be nested: a shared block may itself contain a reference to another one. A cycle is detected and reported in place rather than hanging.

Blocks with fill-in values

A block can be a small template. Write {{name}} where a value goes, or {{name|default text}} to give it a default:

==share:greeting==
Hello {{name}}, welcome to the {{team|support}} team.
==/share==

A reference passes the values after the block name, as key=value pairs. Put a value in double quotes when it has spaces, and write \" for a quote inside it:

==ref:Company handbook^greeting name=Ana team="customer success"==

This renders "Hello Ana, welcome to the customer success team." Leave team out and it reads "support". A placeholder with no value and no default stays in the text as {{name}}, highlighted, with the tooltip "No value for name". Keys the block does not use are ignored, and if a key is repeated the last one wins. Placeholders inside code spans and code blocks are left alone, so a block can show {{name}} as an example.

References without values, and blocks without placeholders, render exactly as before. When you pick a block from the autocomplete or the insert command, the reference starts with an empty name="" for each placeholder, ready to fill in; an empty value counts as not given, so the default applies. Renaming or moving the note keeps the values in every reference.

Commands

You should not normally need the refresh command; it is there for when a block goes stale after an edit made outside Obsidian.

Performance

Opening a vault costs nothing: there is no scan at startup. A block is read the first time a reference asks for one, and edits are coalesced rather than handled per keystroke. The manual refresh scans in chunks, yielding between them, so a large vault does not freeze the window.

Limitations

• In Live Preview only a reference on a line of its own is rendered. One in the middle of a sentence renders in Reading view and stays as highlighted text while you edit.
• The markers use Obsidian's highlight syntax, so a block definition shows as a highlighted line in its source note.
• Blocks are matched by note path and block name. Renaming or moving a note rewrites every ==ref:…== that pointed at it, the way Obsidian updates ordinary links; renaming a block means updating the references yourself.

Installing

In Obsidian, open Settings -> Community plugins -> Browse, search for Shared Blocks, then install and enable it.

To install it by hand instead, copy main.js, manifest.json and styles.css into <vault>/.obsidian/plugins/shared-blocks/ and enable the plugin in Settings → Community plugins.

Development

npm install
npm run dev     # esbuild in watch mode
npm run build   # type-check, then a production bundle
npm test        # unit tests for the parsing and cache logic

Tests run on plain Node with no extra dependency — Node strips the types itself from 22.18 onward, which is what engines asks for. They cover src/blocks.ts, the pure half of the plugin: block parsing, reference parsing, cache keys, and which blocks changed between two reads of a note. main.ts is the only file that touches the vault, the metadata cache or the DOM.

More plugins by Siulved54

All of them are in the community directory: Settings -> Community plugins -> Browse, then search for the name.

License

MIT. See LICENSE.