SiYuan community bazaar

English | 简体中文

Bazaar package development samples

• SiYuan plugin sample, maintained by the SiYuan team; please refer to the README in the repository for plugin-related specifications.
• SiYuan plugin sample (Vite & Svelte), maintained by the community
• SiYuan plugin sample (Vite & Vue3), maintained by the community
• SiYuan theme sample
• SiYuan icon sample
• SiYuan template sample
• SiYuan widget sample

Submitting a bazaar package

If you have developed a plugin, theme, icon, template or widget and want to list it in the SiYuan community bazaar, follow these steps:

1. Fork this repository

1. Edit the bazaar package list TXT file

- One owner/repo per line, with no extra commas or empty lines. - Example: siyuan-note/plugin-sample. - Each PR may only be one of: add exactly 1 new package; change maintainer (add 1 new owner/repo and delete the old owner/repo with the same type and same GitHub repository name); or delist one or more packages only. Do not mix adding/changing with unrelated delistings in the same PR.

1. Open a PR

1. Wait for review and merge

If the PR Check workflow fails, update your changes using the check output. Do not open a new pull request. After you fix the package repo (e.g. update the Latest Release / package.zip), a scheduled job runs about every 20 minutes and re-checks open PRs that are not yet ci-passed by activity (Release changes are prioritized; idle PRs are checked less often) and updates the check comment. Maintainers can also add the Check label or run the workflow manually for an immediate re-check.

1. Successfully listed

Updating a bazaar package

No need to open another PR. Release a new version in your package repository. The bazaar index will pull updates automatically.

Under normal circumstances, the community bazaar repo updates the index and deploys every one to three hours. You can check the deployment status on the Stage workflow page.

If it has not been updated for a long time, there may be an issue with the update (for example, the metadata version was not bumped). First check whether your repository has an open Stage check failure issue (label stage-fail); you can also inspect the latest Stage workflow logs.

Deprecating a bazaar package

Deprecation is a recommendation state for a package that remains available but is no longer a good default choice, for example because it is no longer maintained or has a maintained successor. It is different from delisting or a security block: a deprecated package stays in its type TXT list and continues to be indexed, released, installed, updated and enabled.

The bazaar maintainers own the central deprecated.json registry and make the final decision on every deprecation. Package authors and community members may propose a change through a dedicated PR, but a package must not declare its own deprecation metadata in plugin.json, theme.json or another package manifest.

A deprecation PR must modify only deprecated.json. The root object contains plugins, themes, icons, templates and widgets; each object is keyed by the exact listed owner/repo. The presence of a key marks that package as deprecated. An empty object uses the generic client message; an optional localized reason must include default; optional alternatives are ordered owner/repo values that must each belong to exactly one type list. Alternatives may cross package types, for example a widget pointing at a plugin.

{
  "plugins": {
    "owner/old-plugin": {
      "reason": {
        "default": "This package is no longer maintained",
        "zh-CN": "该包已停止维护"
      },
      "alternatives": ["owner/new-plugin"]
    }
  },
  "themes": {},
  "icons": {},
  "templates": {},
  "widgets": {}
}

Both the deprecated source and every alternative must remain listed in the corresponding type TXT file, and each alternative must be listed in exactly one type. Alternatives may themselves be deprecated, although maintainers should verify that the recommendation is still useful. Stage then writes two generated fields: alternatives, which keeps only same-type targets as package names for clients that open an alternative using the source package type, and choices, which carries every target as {"packageType", "name"} and is what clients need to jump across package types. To restore a package to the normal state, remove its key from deprecated.json; the next Stage run clears the generated deprecation fields. Do not edit stage/*.json manually.

Changing maintainers

If the original author can no longer maintain a listed bazaar package, a new maintainer may take it over. Changing maintainers requires a dedicated PR (one package per PR) and will only be merged after the original maintainer confirms.

Submission process

1. Prepare the new repository

1. Edit the bazaar package list TXT file

- Example: change alice/foo-plugin to bob/foo-plugin. - The name in the package metadata should stay the same as the previously listed package so users still recognize it as the same bazaar package; the url must be updated to the new repository address. - A maintainer change counts as a package update: the manifest version must be higher than the previously listed version, and you must publish a Latest Release with a new package.zip.

1. Open a PR and ask the original maintainer to confirm

If the original maintainer does not agree, the PR will not be merged.

1. Wait for review and merge

About download counts and other statistics

Bazaar package statistics are currently keyed by owner/repo. After a maintainer change, statistics from the old repository (such as download counts) are not inherited by default.

To migrate statistics, all of the following are required:

1. The new maintainer requests the migration in the PR, or by opening a new issue in this repository;
2. The original author replies and agrees;
3. After confirmation, a SiYuan maintainer migrates the data manually on the server side.

Why is the repo named bazaar?

The name is inspired by the book _The Cathedral and the Bazaar_. The goal is not to be unconventional, but to continue the tradition of open source software.

Other questions

Please open an issue.