How to Publish an Obsidian Community Plugin in 2026

Publishing an Obsidian plugin is no longer just a matter of opening a pull request and waiting for someone to merge a registry entry. The current Community directory has a clearer ownership model, automated review, release scanning, and a web interface for managing an entry. That makes the process more approachable, but it also means a plugin can work perfectly on your machine and still fail publication because its manifest, release assets, source tree, or build output does not satisfy the directory contract.

This guide focuses on that contract. It is for developers who already have a plugin that runs locally and want a repeatable path from repository to installable Community plugin. The goal is not merely to get version 1.0.0 accepted. A good release setup should also make version 1.0.1 boring.

Understand the publication model before packaging

There are three separate things involved: your source repository, a GitHub Release, and the Obsidian Community directory entry. Treating them as one object causes many avoidable mistakes.

The repository is where Obsidian reviews the plugin source and reads the manifest at the head of the default branch. The GitHub Release is the downloadable package users ultimately receive. The Community directory is the discovery, ownership, review, and listing layer that connects those pieces.

For an initial submission, Obsidian requires a GitHub account and an Obsidian account. You connect GitHub to the Community directory so it can verify repository ownership. After the plugin is published, you do not submit the whole entry again for every update. New versions are distributed from GitHub releases.

This separation is useful operationally. You can keep source readable and reviewable while shipping only the compiled files needed by the application. It also means a successful local build is only one gate in a longer release pipeline. If you already use automated release pipelines elsewhere, the same principle applies: make every boundary explicit rather than assuming that a green build implies a publishable artifact. See schema-first gates for AI publishing pipelines for the broader validation pattern.

Prepare the repository as a product, not a demo

Before thinking about the directory form, clean the repository. Obsidian’s submission guide expects a README, a license, and a valid manifest.json in the repository root. These are not decoration. They answer three different questions: what does the plugin do, under what terms can people use it, and what does Obsidian need to know to load it?

Remove sample-plugin code that no longer belongs to your product. The official requirements explicitly call this out. A reviewer should not have to distinguish your implementation from leftover tutorial commands, ribbon actions, settings, or placeholder text.

The README should explain the plugin’s purpose, installation or usage flow, important limitations, and any external service it depends on. Keep screenshots and relative links working from the repository because the directory can use repository content in its public presentation.

Choose a real license and commit it. The automated scanner asks GitHub about the repository license, so an unusual or incorrectly formatted license can generate a warning even when a file named LICENSE exists. This is one of those details that feels administrative until it becomes the only warning left in an otherwise clean release.

Finally, make the production build reproducible. The directory scanner can evaluate the build and compare what is produced with what you publish. If a release depends on an uncommitted local file, a globally installed package, or a manual edit to main.js, you have created a release process that cannot be reliably reviewed.

Make manifest.json boring and exact

The manifest is small enough to invite casual editing, but it is one of the most consequential files in the submission.

Your plugin ID must be unique and follow Obsidian’s identifier rules. Current documentation says it should use lowercase letters and hyphens, cannot contain obsidian, and cannot end with plugin. For local development, keeping the plugin folder name aligned with the ID also avoids surprising behavior in APIs that depend on the identifier.

Use a short, descriptive display name. The directory has naming restrictions, and plugin names should not include the word “Plugin” or variations of “Obsidian.” Avoid punctuation-heavy branding that makes the listing harder to scan.

The description deserves more attention than most manifests receive. Obsidian’s current submission requirements cap it at 250 characters, expect a period at the end, discourage emoji and special characters, and recommend an action-oriented description. Write what the plugin enables rather than “This is a plugin that…”.

Set minAppVersion to the minimum version you actually support. If you cannot establish an older compatible version confidently, the official guidance recommends using the latest stable build number rather than inventing compatibility.

Be precise with isDesktopOnly. A plugin that imports Node.js or Electron APIs cannot pretend to support mobile. If your feature can use browser APIs instead, that may allow a wider compatibility target, but do not make the switch merely to earn a broader badge. Compatibility claims are part of the product contract.

Build the exact release users will install

A Community plugin release needs a GitHub Release whose tag matches the version in manifest.json. If the manifest says 1.0.0, the release tag must be 1.0.0. That simple equality is worth enforcing in CI because humans are remarkably good at publishing v1.0.0 in one place and 1.0.0 in another.

Attach main.js and manifest.json to the GitHub Release. Include styles.css when the plugin uses it. These are binary release attachments, not merely files visible somewhere in the repository.

Build from the commit you intend to release. A reliable sequence is: clean checkout, install locked dependencies, run the production build, validate the manifest, create the release tag, and upload the generated assets. Do not patch the compiled JavaScript after the build. If a production fix is needed, change source, rebuild, and produce a new version.

This is also a good place to test installation from the packaged files rather than from your development tree. A development folder often contains source files and dependencies that hide packaging omissions. Copy only the release artifacts into a fresh test vault’s plugin directory, restart or reload Obsidian, and verify the core workflow.

If you automate this, borrow the discipline from reliable batch publishing workflows: generate immutable artifacts first, validate them, and only then mutate the public release state.

Connect ownership in the Community directory

Go to the Community directory website and sign in with your Obsidian account. In your profile, connect your GitHub account. The connection gives the directory read-only access to your public profile so it can verify ownership of repositories you submit.

This ownership step replaces an older mental model in which a registry contribution was the primary submission mechanism. The directory now has first-class management for personal and organization-owned entries.

If a plugin already exists under a repository you own, the interface may offer it as an entry you can claim. New plugins are added from the Plugins area with New plugin. You provide the GitHub repository URL and choose the owner. The owner can be you or an organization you belong to; it does not have to mirror the GitHub repository owner exactly.

That distinction matters for projects that grow from a personal experiment into a maintained team product. Decide who should own the directory entry before launch rather than treating ownership as an afterthought.

Before pressing Submit, make sure the manifest committed at the head of the default branch is the one you mean to publish. The directory processes that manifest during submission. A perfect release attached to GitHub does not compensate for stale metadata on the default branch.

Treat automated review as part of development

Submission is not the finish line. The directory automatically reviews the plugin and groups results into Manifest, Releases, Source code, and Build verification. Results can be errors, warnings, recommendations, or passes.

This is a healthier model than a mysterious yes-or-no queue because it gives you concrete failure domains. A manifest error should be repaired in metadata. A release error points toward packaging. A source-code finding belongs in implementation. A build-verification problem asks whether the published output can be reproduced from the committed source.

Errors must be resolved before the plugin becomes installable. Warnings do not necessarily block publication, but treating them as free documentation about future support cost is wise. A warning you ignore today may become the issue users report tomorrow.

The directory can also preview a scan against a branch, tag, or commit SHA. Use that capability before cutting another release when you are fixing review feedback. It shortens the loop and avoids producing a trail of releases that differ only because you were guessing what the scanner wanted.

The FAQ also documents how the scanner selects a build script: it looks for build, then build:plugin, then compile. Make sure the first applicable command is truly your production build. A script named build that only prepares development fixtures can make verification fail even though your real production command works.

Respect privacy and platform policies before submission

A plugin can be technically impressive and still be inappropriate for the Community directory. Read the developer policies as product requirements.

The current policies prohibit obfuscated code intended to hide behavior, dynamic internet-loaded ads, client-side telemetry, and self-installing or self-updating dependencies. These rules align with Obsidian’s emphasis on private and offline usage.

If your plugin talks to a remote service, explain why. Request only the network access necessary for the feature. If you accept financial support, use the manifest’s fundingUrl mechanism rather than inventing promotional UI that conflicts with directory rules.

Desktop-only APIs deserve another check here. Node.js and Electron APIs are available on desktop but not mobile, so using them requires isDesktopOnly: true. Sometimes a Web API can replace a Node dependency and preserve mobile compatibility. Make that architectural decision deliberately and test both environments when you claim both.

Security review is not just for malicious behavior. Look for accidentally bundled tokens, debug endpoints, verbose logs containing note content, and dependencies that make unnecessary network requests. The cleanest submission is one whose behavior is unsurprising when another developer reads the source.

Fix review feedback with versioned releases

When automated review identifies a problem, fix the source or metadata in the repository and publish a new GitHub Release with an incremented version. Do not silently replace the meaning of an existing release tag.

Versioning review fixes may feel wasteful before public launch, but immutable versions make the review trail understandable. They also force the manifest and release tag to stay synchronized.

After publishing a corrected release, the directory checks for new releases periodically. If you need an immediate refresh, the management interface provides actions to check or request review rather than requiring a brand-new plugin submission.

Keep a small release checklist in the repository. It can be as simple as: version updated, changelog written, clean production build passed, packaged install tested, release assets present, tag equals manifest version, and directory review checked. A checklist turns institutional memory into a repeatable system.

This is especially valuable for solo maintainers. Months can pass between releases, and the exact sequence you remembered during launch will not be as obvious later.

Design the update path before version 1.0.0

Once the initial plugin is published, users receive later versions from GitHub releases. You do not need to resubmit the plugin entry for every update.

That convenience makes release discipline more important, not less. Every new version should repeat the same deterministic packaging process. Keep source and built assets traceable to the same commit. Tag intentionally. Attach the required files. Test migration paths when settings or stored data change.

Do not assume that a plugin loading successfully means an update is safe. Test an existing installation with real settings, upgrade it, and verify that data survives. Then test a fresh installation. Those two paths catch different classes of bugs.

If you support both desktop and mobile, test both whenever shared code changes around storage, filesystem access, networking, or platform APIs. A feature that works on desktop because Node is present can fail immediately on mobile.

The same principle appears in designing offline-first mobile systems: state transitions and recovery paths deserve explicit testing, not just the happy-path initialization.

A release checklist you can actually reuse

Before submission, verify the repository contains a useful README, recognized license, production source, and valid manifest. Confirm the ID, name, description, minimum app version, version, and desktop-only flag are truthful.

Run the production build from a clean checkout. Install only the packaged main.js, manifest.json, and optional styles.css into a clean test vault. Exercise the plugin’s primary workflow and settings. If the plugin stores data, test an upgrade from the previous version as soon as a previous version exists.

Create a GitHub Release whose tag exactly matches the manifest version. Upload the required release assets. Then connect GitHub in the Community directory, select the correct owner, submit the repository, and work through automated review findings by category.

Before calling the launch complete, open the public listing as a user would. Read the description without your developer context. Install the plugin from the Community interface. Confirm that the release users receive is the release you tested.

This final outside-in check catches a surprisingly common class of publishing mistakes: everything in the repository is correct, but the public path points at a stale version or unclear listing.

What changed for plugin authors

The most important change is conceptual. Publishing an Obsidian plugin is now closer to operating a small software supply chain than submitting a single registry record.

That sounds heavier, but the responsibilities are clearer. GitHub proves source and release provenance. The Community directory establishes ownership and listing metadata. Automated review checks the manifest, releases, source, and build. Your job is to make those layers agree.

The payoff is maintainability. When the release process is deterministic, version two is not another publishing project. It is the same pipeline with a new version number and a new set of changes.

For a solo developer, that is the standard worth optimizing for: not “Can I get this accepted once?” but “Can I explain and repeat every step six months from now?” A plugin that is easy to release is easier to maintain, easier to review, and ultimately safer for the people who install it.