Base Settings

An Obsidian plugin for enforcing shared base settings across multi-user vaults.

Define partial JSON files that get deeply merged into .obsidian config files on startup and whenever settings change. Base template values always win on conflict, ensuring shared settings are enforced while still giving each user freedom to add their own customizations.

Use case

Teams or projects with multiple contributors can commit a folder of base template files to version control. When any user opens the vault, the plugin automatically merges those templates into their local .obsidian config — enforcing required plugins, shared hotkeys, or any other settings without overriding everything the user has configured.

How it works

1. Create a folder inside .obsidian/ to hold your base templates (e.g. .obsidian/base-settings/)
2. Add partial JSON files named to match the .obsidian config files you want to manage (e.g. app.json, community-plugins.json)
3. Set the folder path in plugin settings
4. The plugin deeply merges each template into the matching .obsidian file — template values take precedence over user values on any conflicting keys

If a target config file does not exist yet (e.g. a plugin hasn't been installed), the template is skipped and will be applied on the next sync after the file is created by Obsidian.

Merge strategies

By default the plugin deep-merges objects and replaces all other values (arrays, scalars) with the template value. For arrays you may want a different behaviour — for example, adding required plugins to the user's existing list rather than replacing it entirely.

A merge directive lets template authors declare the strategy for a specific key:

{
  "plugins": {
    "value": ["required-plugin-a", "required-plugin-b"],
    "__mergeDirective": {
      "strategy": "concat"
    }
  }
}

The directive object must have a __mergeDirective key. Any object without that key is treated as a normal value and deep-merged as usual.

Type enforcement: when source and target values both exist for a key, they must share the same type (e.g. both arrays, both strings). A mismatch throws an error. This applies to both plain merges and directive merges — a directive also requires the target key to already exist with a matching type.

Available strategies

Strategy	Behaviour	unique supported
replace	value replaces the target value entirely (explicit version of the default)	yes
concat	[...value, ...targetValue] — base items first, then user items	yes

unique flag

Add "unique": true to any directive to remove duplicate entries from the result. Deduplication uses value identity, so it works best with primitive arrays such as plugin ID lists.

{
  "plugins": {
    "value": ["dataview", "templater-obsidian"],
    "__mergeDirective": {
      "strategy": "concat",
      "unique": true
    }
  }
}

With unique: true, if the user already has "dataview" in their list, it will appear only once in the merged result. First-occurrence order is preserved, so value items always take precedence over target duplicates.

Example — enforcing required community plugins

base-settings/community-plugins.json:

{
  "value": ["dataview", "templater-obsidian"],
  "__mergeDirective": {
    "strategy": "concat"
  }
}

A user whose community-plugins.json already contains ["calendar"] will end up with ["dataview", "templater-obsidian", "calendar"] after sync.

Settings

Setting	Description	Default
Base templates path	Folder containing template JSON files, relative to .obsidian/	(empty)
Debounce interval	Milliseconds to wait after a file change before syncing	500

Sync triggers

A sync runs automatically on:

• Plugin startup — enforces settings when the vault opens
• Template file changes — re-syncs when any file in the templates folder is created, modified, or deleted
• .obsidian/ file changes — re-enforces settings if a user manually reverts a managed value, or when a new plugin config file appears
• Settings save — re-syncs when the base templates path is changed

A Sync base settings command is also available in the command palette to trigger a sync manually.

Installation

Community plugin manager

1. Open Obsidian Settings
2. Go to Community plugins and turn off Restricted mode if prompted
3. Click Browse and search for Base Settings
4. Click Install, then Enable

Manual installation

1. Download main.js, manifest.json, and styles.css from the latest release
2. Copy them into .obsidian/plugins/obsidian-base-settings/ in your vault
3. Open Obsidian Settings → Community plugins and enable Base Settings

Development

npm install
npm run dev   # watch mode
npm run build # production build
npm run lint  # lint