How obsidianmd/obsidian-releases works
Purpose and Consumers
This is Obsidian’s public distribution metadata repository, not the Obsidian application source. The Obsidian desktop client consumes curated JSON registries here to discover community plugins, themes, snippets, and public desktop releases. GitHub Actions maintain selected registry-derived artifacts.
Primary Entry Points
The client-facing registries are repository-root JSON files:
• community-plugins.json
• community-css-themes.json
• community-snippets.json
• desktop-releases.json
README.md defines the plugin installation contract: the client reads the plugin registry, then retrieves plugin metadata and release artifacts from each plugin’s GitHub repository.
Community Plugin Directory
community-plugins.json is the canonical plugin catalog. It supplies plugin identity and searchable metadata, including name, author, and description. A plugin entry directs Obsidian to an external GitHub repository; detailed metadata and installable artifacts do not live in this repository.
Lifecycle and policy overlays are represented separately:
• community-plugins-removed.json
• community-plugin-deprecation.json
• community-plugin-stats.json
These files allow the catalog to distinguish active plugins from removed/deprecated entries and publish aggregate or per-plugin statistics without changing the core discovery format.
Plugin Installation Boundary
Plugin installation crosses from this static registry into GitHub-hosted plugin repositories:
1. Obsidian selects an entry from community-plugins.json.
2. For plugin detail and version resolution, it fetches that repository’s manifest.json and README.md.
3. It compares the manifest’s Obsidian compatibility requirement; when needed, it consults the plugin repository’s versions.json.
4. It downloads release assets tagged with the manifest version: manifest.json, main.js, and optional styles.css.
Thus this repository owns discovery/curation, while plugin authors’ GitHub repositories and GitHub Releases own executable plugin delivery.
Theme and Snippet Directories
Theme discovery is represented by community-css-themes.json, with removals separated into community-css-themes-removed.json. Community snippets are indexed by community-snippets.json. Like plugins, these are public directory data rather than bundled application assets.
Desktop Release Publication
desktop-releases.json is the public release metadata surface for Obsidian desktop releases. It is distinct from community extensibility registries and enables clients or release consumers to resolve official application versions independently of plugin/theme catalogs.
Automation and Runtime
The repository is static-data-first, with Node/npm metadata in package.json and package-lock.json. GitHub Actions provide operational automation:
• .github/workflows/mirror-community-json.yml mirrors community JSON data.
• .github/workflows/plugin-stat.yml generates or updates plugin statistics.
GitHub is the material infrastructure boundary: it hosts this registry, runs the workflows, and serves external plugin repositories and release assets referenced by the catalog.
Main entry points: community-plugins.json Plugin catalog · mirror-community-json.yml Community JSON mirror · community-plugin-stats.json Plugin statistics · plugin-stat.yml Plugin statistics job
Components 17
Public registries
Client-consumed distribution metadata.
- Plugin catalog · Canonical curated community plugin directory.
community-plugins.json - Removed plugins · Separates removed entries from the active catalog.
community-plugins-removed.json - Plugin deprecations · Records plugin lifecycle deprecations.
community-plugin-deprecation.json - Plugin statistics · Publishes aggregate or per-plugin statistics.
community-plugin-stats.json - Theme catalog · Community CSS theme discovery directory.
community-css-themes.json - Removed themes · Separates removed themes from the active directory.
community-css-themes-removed.json - Snippet catalog · Community snippet discovery directory.
community-snippets.json - Desktop releases · Public metadata for official desktop versions.
desktop-releases.json
Repository automation
GitHub Actions maintain derived registry data.
- Community JSON mirror · Mirrors community JSON data.
.github/workflows/mirror-community-json.yml - Plugin statistics job · Generates or updates plugin statistics.
.github/workflows/plugin-stat.yml
GitHub delivery boundary
Plugin authors and releases own installable artifacts.
- Plugin GitHub repository · Author-owned source of detail, compatibility, and releases.
- Plugin metadata · manifest.json, README.md, and optional versions.json.
- Plugin release assets · Versioned manifest.json, main.js, and optional styles.css.
- GitHub platform · Hosts registries, workflows, repositories, and releases.
Other components
- Obsidian desktop client · Discovers extensions and resolves desktop releases.
- Installation contract · Defines registry-to-plugin installation resolution.
README.md - Node/npm metadata · Supports static-data repository tooling.
package.json
Connections 21
- Obsidian desktop client → Plugin catalog: discovers plugins
- Obsidian desktop client → Theme catalog: discovers themes
- Obsidian desktop client → Snippet catalog: discovers snippets
- Obsidian desktop client → Desktop releases: resolves desktop versions
- Installation contract → Plugin catalog: defines lookup
- Plugin catalog → Plugin GitHub repository: links author repository
- Plugin GitHub repository → Plugin metadata: serves detail and compatibility
- Plugin metadata → Plugin release assets: selects manifest version
- Obsidian desktop client → Plugin metadata: fetches metadata
- Obsidian desktop client → Plugin release assets: downloads installable assets
- Removed plugins → Plugin catalog: lifecycle overlay
- Plugin deprecations → Plugin catalog: lifecycle overlay
- Plugin statistics → Plugin catalog: statistics overlay
- Removed themes → Theme catalog: lifecycle overlay
- Community JSON mirror → Plugin catalog: mirrors data
- Plugin statistics job → Plugin statistics: updates statistics
- Node/npm metadata → Community JSON mirror: tooling runtime
- GitHub platform → Community JSON mirror: runs
- GitHub platform → Plugin statistics job: runs
- GitHub platform → Plugin GitHub repository: hosts
- GitHub platform → Plugin release assets: serves