Obsidian plugin distribution, publishing, and release management. TRIGGER when: preparing a plugin release, publishing to the Obsidian community plugin list, setting up GitHub Actions for automated releases, creating manifest.json or versions.json, submitting a plugin for review, managing BRAT beta releases, or when the user asks about plugin distribution, versioning, or the review process.
Every release needs exactly 3 files attached to a GitHub Release:
| File | Purpose |
|---|---|
main.js | Bundled plugin code (esbuild output) |
manifest.json | Plugin metadata (copied from repo root) |
styles.css | Plugin styles (optional — only if used) |
{
"id": "your-plugin-id",
"name": "Your Plugin Name",
"version": "1.0.0",
"minAppVersion": "1.0.0",
"description": "What your plugin does",
"author": "Your Name",
"authorUrl": "https://github.com/you",
"fundingUrl": "https://buymeacoffee.com/you",
"isDesktopOnly": false
}
Rules:
id must match the directory name in .obsidian/plugins/id must be lowercase, hyphens only, no spaces, cannot contain "obsidian"version must follow semver1.0.0, NOT v1.0.0)minAppVersion — set to oldest Obsidian version that supports all APIs you useisDesktopOnly — set true only if plugin uses Electron/Node APIsMaps each plugin version to the minimum Obsidian version it requires:
{
"1.0.0": "1.0.0",
"1.1.0": "1.2.0",
"2.0.0": "1.5.0"
}
Obsidian uses this to show the latest compatible version to users on older Obsidian.
See github-actions.md for the complete CI/CD setup including:
See community-submission.md for:
isDesktopOnly: true)manifest.json has all required fieldsversions.json exists and is correctmain.js + manifest.json attachedeval(), Function(), or dynamic code executionBRAT lets users install plugins directly from GitHub before community submission:
# User installs via BRAT:
1. Install BRAT from community plugins
2. BRAT → Add Beta Plugin → enter GitHub repo URL
3. BRAT pulls latest release artifacts automatically
For developers: just create a GitHub Release with the 3 required files. BRAT handles the rest. Use pre-release tags for unstable versions.
# 1. Update version in manifest.json
# 2. Update versions.json with new entry
# 3. Update package.json version
# 4. Commit: "Release 1.2.0"
# 5. Tag: git tag 1.2.0
# 6. Push: git push && git push --tags
# 7. GitHub Actions creates release automatically (if configured)
See github-actions.md for automating steps 1-6 with a single command.
manifest.json, package.json, versions.jsonnpm run build produces clean main.jsisDesktopOnly: true