Publish Obsidian plugins to the community plugin directory.
Use when releasing your first plugin, updating existing plugins,
or managing the community plugin submission process.
Trigger with phrases like "publish obsidian plugin", "obsidian community plugins",
"submit obsidian plugin", "obsidian plugin directory".
Release and distribute Obsidian plugins through multiple channels: the official community plugin directory, GitHub releases, BRAT beta testing, and manual installation. Covers the full lifecycle from building release assets to submitting your PR to the obsidian-releases repo.
Prerequisites
Obsidian plugin with main.ts, manifest.json, and styles.css (if applicable)
GitHub repository for your plugin (public)
gh CLI authenticated (gh auth status)
Plugin passes obsidian-prod-checklist validation
Instructions
Step 1: Build Release Assets
set -euo pipefail
# Clean build for production
rm -f main.js
npm ci
npm run build
# Verify the three release files exist
for f in main.js manifest.json; do
test -f "$f" || { echo "MISSING: $f"; exit 1; }
done
test -f styles.css && echo "styles.css included" || echo "No styles.css (OK if no custom styles)"
echo "Release assets ready"
Step 2: Version Bump with version-bump.mjs
// version-bump.mjs
import { readFileSync, writeFileSync } from 'fs';
const targetVersion = process.env.npm_package_version;
// Sync manifest.json
const manifest = JSON.parse(readFileSync('manifest.json', 'utf8'));
const { minAppVersion } = manifest;
manifest.version = targetVersion;
writeFileSync('manifest.json', JSON.stringify(manifest, null, '\t'));
// Sync versions.json — maps each plugin version to its minimum Obsidian version
const versions = JSON.parse(readFileSync('versions.json', 'utf8'));
versions[targetVersion] = minAppVersion;
writeFileSync('versions.json', JSON.stringify(versions, null, '\t'));
console.log(`Bumped to ${targetVersion} (requires Obsidian >= ${minAppVersion})`);
Wire it into package.json so npm version triggers it automatically:
set -euo pipefail
# Bump version, commit, and tag
npm version patch # or minor / major
git push origin main --tags
# Create release with assets (or let the release workflow from obsidian-ci-integration handle it)
gh release create "$(node -p 'require("./manifest.json").version')" \
main.js manifest.json styles.css \
--title "v$(node -p 'require("./manifest.json").version')" \
--generate-notes
The release must include these files at the root level (not nested in folders):
main.js — compiled plugin code
manifest.json — plugin metadata
styles.css — only if your plugin has custom styles
Use npm version which triggers the script automatically
BRAT can't find releases
No GitHub release created
BRAT needs actual GitHub releases, not just tags
gh release create fails
Not authenticated
Run gh auth login first
Manual install doesn't load
Missing manifest.json
All three files must be in the plugin directory
Examples
Update an Existing Community Plugin
Already listed? Just create a new release — Obsidian auto-detects new versions:
set -euo pipefail
npm version patch
git push origin main --tags
# Release workflow creates the GitHub release automatically
Users see the update in Settings > Community Plugins > Check for updates.
Check Your Submission Status
set -euo pipefail
# See if your plugin is already in the directory
gh pr list --repo obsidianmd/obsidian-releases --search "your-plugin-id" --state all
