# Publishing to the DSH plugin community

The community place to be listed is the curated list
[`awesome-dsh-plugin/awesome-dsh-plugin`](https://github.com/awesome-dsh-plugin/awesome-dsh-plugin).
Both `dshmarket` (the in-app visual market) and the site
[awesome-dsh-plugin.com](https://awesome-dsh-plugin.com) read that list
(`plugins.json` / the format-1 index generated from it); a merged entry usually
shows up within a day. `dshmarket.com` shares the same discussion threads.

This package is prepared for that flow. The steps that need external accounts
(GitHub / npm) are listed here; the authoring environment cannot reach those
services with credentials, so the final push / publish / PR runs on your machine.

## 0. Prerequisites

- A public GitHub repository containing this package at its **root**
  (`package.json` with `dsh.bundle` + `cordis.patch.yml` + `lib/` + `vendor/` +
  `patches/`). Suggested name: `dsh-sidebar-sections`.
- The repository's GitHub **topic** must be `dsh-plugin`.
- The repository must be **at least 1 day old** before the list PR is accepted
  (CI checks the creation time; commit count does not matter).
- Optional: an npm account (the registry name
  `dsh-sidebar-sections` was free when this doc was written). A
  published package gives storefronts download counts and prebuilt installs; the
  listing works without it.

## 1. Create and push the repository

~~~powershell
# in this package directory (it already contains a local git repo)
git remote add origin https://github.com/Arfrsa/dsh-sidebar-sections.git
git push -u origin main
~~~

This repository is already pushed to
<https://github.com/Arfrsa/dsh-sidebar-sections>. The remaining one-time GitHub
setting is the **`dsh-plugin` topic**:
`https://github.com/Arfrsa/dsh-sidebar-sections/settings` -> Topics -> add
`dsh-plugin`.

The `repository` / `homepage` / `bugs` fields in `package.json` point at that
repository (the npm ↔ repo mapping reads `repository`).

## 2. (Optional, recommended) Publish to npm

~~~powershell
npm login
npm publish            # prepack rebuilds lib/client.js from vendor/ and runs node --check
~~~

- Unscoped name: `dsh-sidebar-sections` (public).
- `publishConfig.access` is already `public`; the `files` list ships
  `lib/client.js`, `vendor/`, `patches/`, `scripts/` and the docs, so the
  installed package needs no build step.
- After publishing, `dsh plugin --profile <profile> add dsh-sidebar-sections`
  is the preferred install command; storefronts also show download counts.
- The package's `repository` field must point at the listed GitHub repo.

## 3. Submit the list entry (after the repo is 1 day old)

One PR = one file. Fork `awesome-dsh-plugin/awesome-dsh-plugin`, then:

~~~text
data/plugins/<owner>__dsh-sidebar-sections.yml
~~~

Copy `docs/community/awesome-dsh-plugin-entry.yml` from this package, replace
`<owner>` (and the URL if you used another repo name), then commit and open a
PR titled `Add <owner>/dsh-sidebar-sections`.

Do **not** edit the generated `README.md` / `README.zh.md` in that repository:
the maintainers regenerate them from `data/plugins/*.yml` after merge.

### What the CI checks (and the maintainer review)

- at most 3 entries per PR (ours is 1);
- `dsh.bundle` is read from the submitted repository's `package.json` - a
  `dsh.client`-only package fails (ours declares both);
- repository age >= 1 day;
- `awesome-lint` / site build (YAML shape, bilingual text, separators, dates,
  screenshots);
- a maintainer reads the code and checks the description against it. Keep the
  description accurate - this package is Windows-oriented because the fixed
  middle workspace path is `D:\files\history-tasks`, and it replaces the shipped
  `ui-workspace` row while enabled (both are documented in the README).

## 4. After merge

- The list's README, `index.json` and the marketplace catalog are regenerated by
  CI; `dshmarket` picks the entry up on its next daily refresh.
- `screenshots.json` in this repository is read by storefronts (AppStore-style
  screenshots); relative paths only, 1-8 PNG/JPG/WebP images hosted in the repo.
- Keep the repository maintained: a periodic scan removes entries whose repo is
  gone, archived or long dormant.

## 5. Badge (optional)

The list offers a badge for listed plugins; copy its snippet from the list's
"Badge" section into this README once the entry is merged.