Obsidian Stats logoObsidian Stats

Expander

by Sébastien Dubois
5
4
3
2
1
Score: 37/100
Install Code

Description

Replace variables across your vault using HTML comment markers. Supports static values and dynamic functions

Reviews

No reviews yet.

Stats

4
stars
963
downloads
1
forks
129
days
6
days
23
days
6
total PRs
6
open PRs
0
closed PRs
0
merged PRs
4
total issues
0
open issues
4
closed issues
67
commits

Latest Version

1.0.0
23 days ago

Changelog

1.0.0 (2026-08-28)

⚠ BREAKING CHANGES

  • plugin: minAppVersion is now 1.13.0 (was 1.8.7). The settings pane uses the declarative settings API introduced in Obsidian 1.13.
  • getSettingDefinitions() replaces display(): 2 toggles as declared controls, the 2 folder lists as native type 'list' groups (framework delete resolving entries BY VALUE from the live array; the add control keeps its inline FolderSuggest search box), the vault-wide replace action and the support block as render: rows, everything indexed by the settings search.
  • The replacements editor deliberately keeps its draft-plus-Save semantics inside a render: row: replacement keys are live the moment they are stored, so persisting every keystroke would let a half-typed key match and expand text in notes. The Save button now reports success only after the write lands, and a failed persist keeps the draft dirty so Save can retry.
  • updateSettings becomes the serialized persist-then-commit write path from the template: memory is swapped only after saveData() succeeds, and queued writes each derive from the previously committed state so overlapping edits cannot drop each other. saveSettings is documented as load-time-only.
  • Support block and replacements editor rows get block layout via an unlayered .setting-item.exp-settings-embed rule (Obsidian's own flex-row rule is unlayered, and unlayered CSS beats layered CSS regardless of specificity).
  • Tests: settings-guard.spec.ts (source-level guard for the two known-fatal render patterns) and settings-write.spec.ts (13 behavioral tests: queue, rollback, validation, folder-list races; mutation-checked against an optimistic commit and an unserialized chain — 3 tests fail under each).
  • Docs: README and docs/configuration.md state the 1.13 requirement; AGENTS.md gains the declarative-settings section including the draft-plus-Save exception.

Features

  • plugin: declare the settings tab (Obsidian 1.13 declarative settings) (adaeb41)
  • plugin: show what's new in a tab instead of a modal dialog (e0c5a18)
  • plugin: surface support CTAs everywhere users can see them (2ee15ac)

Bug Fixes

  • build: align with the catalog reviewer's archive, ruleset and audit (f7fef46)
  • plugin: harden the settings write paths after adversarial review (1578ef8)

Enjoying this plugin?

See all version on GitHub

README file from

Github

Obsidian Expander

Replace variables across your Obsidian vault using HTML comment markers. Configure key-value pairs in settings, and Expander will automatically substitute them throughout your notes, and keep those updated too.

Features

  • Variable Replacement: Define key-value pairs that get expanded throughout your vault
  • Dynamic Values: Use function expressions like now().format("YYYY-MM-DD") for dynamic content
  • Update Modes: Control when expansions update
    • Auto: Updates automatically on file changes
    • Manual: Updates only via command or button
    • Once: Updates once, then never again
    • Once-and-Eject: Updates once, removes markers
  • Folder Filtering: Choose which folders to scan or ignore
  • Visual Feedback: Mode badges and refresh buttons in the editor
  • Commands: Replace values in current note or entire vault, add new expansion, ...
  • What's new after updates. After a plugin update, a one-time dialog shows the release notes you just received (including skipped versions) with ways to support development. Never shown on fresh installs or regular restarts.

Installation

Requires Obsidian 1.13.0 or later. The settings pane uses the declarative settings API introduced in 1.13. On an older version the plugin will not load, and the community catalog will not offer it to you — but a manual or BRAT install can still put an incompatible build in your vault, so check Settings → About first.

Community plugins (recommended)

  1. In Obsidian, go to Settings → Community plugins.
  2. Disable Restricted mode if it's enabled.
  3. Select Browse, search for Expander, install it, then enable it.

You can also browse the catalog on the Obsidian Community website.

Manual installation

If the plugin isn't listed in the community catalog yet (or you want a specific version):

  1. Download main.js, manifest.json, and styles.css from the latest release.
  2. Copy them into <Vault>/.obsidian/plugins/expander/.
  3. Reload Obsidian and enable Expander in Settings → Community plugins.

BRAT (bleeding edge)

BRAT (Beta Reviewers Auto-update Tool) installs plugins straight from a GitHub repo and keeps them updated automatically. Use this if you want the latest commits — things might break.

  1. Install Obsidian42 - BRAT from Settings → Community plugins → Browse and enable it.
  2. Run BRAT: Add a beta plugin for testing from the command palette.
  3. Paste https://github.com/dsebastien/obsidian-expander.
  4. Select the latest version and confirm.
  5. Enable Expander in Settings → Community plugins.

Quick Start

  1. Install the plugin (see Installation above).
  2. Open Settings → Expander
  3. Add a replacement (e.g., key: today, value: now().format("YYYY-MM-DD"))
  4. In your note, add: 
    <!-- expand: today -->
  5. The value and closing tag will be automatically inserted

Syntax

Just add an opening tag - the closing tag is added automatically:

<!-- expand: key -->

After expansion:

<!-- expand: key -->value<!---->

Update mode variants:

  • <!-- expand: key --> - Auto mode (updates on file change)
  • <!-- expand-manual: key --> - Manual mode (update via command only)
  • <!-- expand-once: key --> - Once mode (fills once, never updates)
  • <!-- expand-once-and-eject: key --> - Once-and-eject mode (fills once, removes markers)

Functions

Dynamic values using function expressions:

Function Description Example
now() Current date/time now().format("YYYY-MM-DD")
today() Today at midnight today().format("MM/DD/YYYY")
format(pattern) Format date now().format("HH:mm")
lower() Lowercase now().format("MMMM").lower()
upper() Uppercase now().format("MMMM").upper()
trim() Trim whitespace
replace(old, new) Replace text replace("-", "/")

Documentation

Full documentation available at docs/.

Development

See DEVELOPMENT.md for build instructions, testing setup, and contribution guidelines.

License

MIT License - see LICENSE for details.

Author

Created by Sébastien Dubois (@dSebastien)

My other Obsidian plugins

Plugin What it does
Agentic Resource Discovery Server Local-first Agentic Resource Discovery publisher and registry that serves your AI skills and tools to agents over a local HTTP and MCP server
Book Exporter Export books (one manifest note + linked chapter notes) to EPUB and PDF via Pandoc
Bookshelf Base Display your notes as a visual bookshelf via a custom Bases view
Dataview Serializer Serialize Dataview queries to Markdown, and keep the Markdown representation up to date
Ghost Publish Publish your vault notes to a Ghost blog with configurable presets for tags, newsletters, and frontmatter conventions
Graph Explorer Base View A custom Bases view that renders notes as an interactive force-directed graph with explored/unexplored tracking
Hidden Folders Access Index hidden root-level folders (e.g. .claude) so they appear in the file tree, metadata cache, and Bases
Journal Bases Custom Base views for journaling and periodic reviews
Kanban Action Planner Render your notes as configurable Kanban boards and calendars inside Bases, with statuses, ordering, relationships, and scheduling
Life Tracker Capture and visualize the data that matters in your life
Note Village A 2D pixel art village where your notes become villagers you can explore and chat with using AI
Obsidian Starter Kit Adds strong typing support and powerful automation support for notes
Remarkable Synchronizer Connect to the reMarkable cloud, list, download, and sync notebook pages as images
Replicate Use AI models with ease via the Replicate.com integration
REST and MCP server Exposes CLI commands as RESTful API endpoints and an MCP server for AI tool integration
Time Machine Browse, compare, and restore previous versions of your notes using built-in file-recovery snapshots
Transcriber Transcribe images to markdown using Ollama vision models
Typefully Publish social media posts with ease using the Typefully integration
Update Time Automatically update front matter to include creation and last update times

Everything I build is documented in my newsletter and on my YouTube channel.

News & support

To stay up to date about this plugin, Obsidian in general, Personal Knowledge Management and note-taking:

If this plugin is useful to you, here are the best ways to support my work ❤️:

Found a bug or have an idea? Open an issue.

Sponsors