@linkdesk/plugin-docs 0.1.0 → 0.1.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -228,6 +228,8 @@ Multi-theme package:
228
228
  | `distribution` | `string` | ⚠️ **Legacy field** (since the single-root flattening on 2026-09-05 it no longer maps to any directory; the install side always normalizes it to `user`; already marked deprecated in the schema). **Third parties must not fill this in** |
229
229
  | `factoryRole` | `string` | System slot role: `"settings"` \| `"marketplace"`. **Filling it in = form 2 (replace / switch into the slot); omitting it = form 1 (coexist as an ordinary view plugin)** — see "The `factoryRole` field in depth" below |
230
230
  | `iconSource` | `string` | `"codicon"` (default) / `"svg"` / `"url"` |
231
+ | `marketIcon` | `string` | The **coloured identity image** for marketplace display (list row + detail header). Unlike `icon`: plugins on the icon bar use it to supply a colour image. Missing → falls back to `icon` → then to the unified default block. See "The marketplace image `marketIcon`" below |
232
+ | `marketIconSource` | `string` | Same enum as `iconSource`. When the value is `resources/…` you can **just omit it** (inferred from the value) |
231
233
  | `description` | `string` | One-line description shown on the plugin detail page. Multi-line is supported |
232
234
  | `author` | `string` | Author name |
233
235
  | `sidebar` | `string` | Sidebar component path; only effective for the `view` type |
@@ -377,6 +379,42 @@ The icon appears in the icon bar, the tab bar, the welcome page and the [+] menu
377
379
 
378
380
  > **SVG + `fill="currentColor"` is recommended:** one file fits every size (24px in the icon bar, 14px in the tab bar, 24px/16px on the welcome page) and recolors automatically for light/dark themes. PNG gets blurry when scaled up and is not recommended.
379
381
 
382
+ ### The marketplace image `marketIcon` — what your plugin looks like in the market
383
+
384
+ `icon` is the **small in-app icon** (icon bar / tab bar / [+] menu); `marketIcon` is the **coloured identity image shown in
385
+ the marketplace list row and at the top of the detail page**. They can differ: a plugin that sits in the **icon bar** must
386
+ draw `icon` as a single-colour line glyph (the icon bar force-tints it, so a coloured image turns into a blob), while the
387
+ marketplace slot wants a branded colour image — that is when you add `marketIcon`. Plugins outside the icon bar normally
388
+ do not need it (`icon` *is* the identity image).
389
+
390
+ **Three tiers — pick what you need, all three are publishable:**
391
+
392
+ | Tier | What you declare | What the marketplace shows |
393
+ |:--|:--|:--|
394
+ | **No image** | Declare neither | The unified default coloured block (good enough to publish) |
395
+ | **One image** | `icon` only (coloured SVG) | The market row, the detail header and your own tab icon all show it |
396
+ | **Two images** | `icon` (line glyph) + `marketIcon` (coloured identity image) | Line glyph in the UI, colour image in the marketplace |
397
+
398
+ ```json
399
+ { "icon": "resources/icon-bar.svg", "marketIcon": "resources/icon.svg" }
400
+ ```
401
+
402
+ **The two data paths (not your concern, but they decide who sees which image):**
403
+
404
+ | Who is looking | Read from | Value form |
405
+ |:--|:--|:--|
406
+ | **An installed user** | the `plugin.json` inside your package | A package-relative path (`resources/icon.svg`) — works offline |
407
+ | **A not-yet-installed user** (browsing the market) | the catalog entry `marketplace.json` | An **absolute URL** — `publish` converts your relative path into a raw link automatically; **you never write the URL** |
408
+
409
+ 🔴 **Two rules:**
410
+
411
+ 1. Always write `icon` / `marketIcon` as a **package-relative path** (`resources/…`). `publish` turns it into
412
+ `https://raw.githubusercontent.com/<you>/<repo>/v<version>/resources/…` at release time — **writing a URL by hand is
413
+ redundant** and tends to go stale when the version changes. (An external CDN is still allowed: a full http(s) URL plus
414
+ `iconSource: "url"` is passed through untouched, but keeping it alive is on you.)
415
+ 2. **Changing the image = change the file + bump the version + `publish` again.** Installed users read the image from the
416
+ package, so they only get a new one with a new version; without a bump, whoever installed the old version never sees it.
417
+
380
418
  ### When an icon appears in the icon bar (appearsIn.iconBar)
381
419
 
382
420
  > **opt-IN — without declaring `appearsIn.iconBar` there is no icon of yours in the icon bar.** The old `iconLocation` default of `"top"` (opt-OUT — the editor got squeezed into the icon bar even without declaring anything) has been deprecated; it is now controlled declaratively by `appearsIn.iconBar` (`"top"` = the upper icon group, `"bottom"` = the fixed bottom group).
@@ -228,6 +228,8 @@ my-plugin/
228
228
  | `distribution` | `string` | ⚠️ **遗留字段**(2026-09-05 塌平单根后不再对应任何目录,安装侧恒归一化为 `user`;schema 已标废弃)。**第三方请勿填写** |
229
229
  | `factoryRole` | `string` | 系统插槽角色:`"settings"` \| `"marketplace"`。**填 = 形态二(替换/进槽位切换);不填 = 形态一(普通视图插件并存)**——详见下方「`factoryRole` 字段详解」 |
230
230
  | `iconSource` | `string` | `"codicon"`(默认)/ `"svg"` / `"url"` |
231
+ | `marketIcon` | `string` | 市场展示位的**身份彩色图**(列表行 + 详情顶)。与 `icon` 不同:进图标栏的插件用它补一张彩色图。缺省 → 回退 `icon` → 再缺 → 统一默认彩色块。详见下方「市场展示图 `marketIcon`」 |
232
+ | `marketIconSource` | `string` | 与 `iconSource` 同枚举。写 `resources/…` 时**省略即可**(按值推断) |
231
233
  | `description` | `string` | 一句话描述,插件详情页展示。支持多行 |
232
234
  | `author` | `string` | 作者名 |
233
235
  | `sidebar` | `string` | 侧栏组件路径,仅 `view` 类型有效 |
@@ -377,6 +379,39 @@ my-plugin/
377
379
 
378
380
  > **推荐 SVG + `fill="currentColor"`:** 一个文件适配所有尺寸(图标栏 24px、标签栏 14px、欢迎页 24px/16px),亮/暗主题自动变色。PNG 放大会模糊,不推荐。
379
381
 
382
+ ### 市场展示图 `marketIcon`——你的插件在市场里「长什么样」
383
+
384
+ `icon` 是**界面小图标**(图标栏 / 标签栏 / [+] 菜单);`marketIcon` 是**插件在市场列表行与详情页顶部的身份彩色图**。
385
+ 两者可以不是同一张:**进了图标栏的插件**,`icon` 必须是单色线稿(图标栏会强制着色成一种颜色,彩色图会糊成一块),
386
+ 而市场位该显一张有品牌色的图——这时就用 `marketIcon` 补第二枚。没进图标栏的插件一般不需要它(`icon` 本身就是身份图)。
387
+
388
+ **三档契约——按需选,三档都能上架:**
389
+
390
+ | 档 | 怎么声明 | 市场里显示 |
391
+ |:--|:--|:--|
392
+ | **零图** | 都不写 | 统一默认彩色块(够用即可上架) |
393
+ | **一张图** | 只写 `icon`(彩色 SVG) | 市场行 + 详情顶 + 你的标签页图标都显它 |
394
+ | **两张图** | `icon`(界面线稿)+ `marketIcon`(彩色身份图) | 界面用线稿、市场用彩色图 |
395
+
396
+ ```json
397
+ { "icon": "resources/icon-bar.svg", "marketIcon": "resources/icon.svg" }
398
+ ```
399
+
400
+ **两条数据路(你不用管,但它决定「谁看得到哪张图」):**
401
+
402
+ | 谁在看 | 从哪读 | 值是什么形态 |
403
+ |:--|:--|:--|
404
+ | **已装用户** | 你包里的 `plugin.json` | 包内相对路径(`resources/icon.svg`)——断网也显 |
405
+ | **未装用户**(逛市场) | 目录条目 `marketplace.json` | **绝对 URL**——`publish` 自动把你的包内路径转成 raw 直链,**你不用写 URL** |
406
+
407
+ 🔴 **两条纪律:**
408
+
409
+ 1. `icon` / `marketIcon` 一律写**包内相对路径**(`resources/…`)。`publish` 会在发布时自动转成
410
+ `https://raw.githubusercontent.com/<你>/<仓库>/v<版本>/resources/…`——**写 URL 是多余的**,而且换版本后容易过期。
411
+ (真要用外部 CDN 也可以:写完整 http(s) URL + `iconSource: "url"`,原样保留;但长期有效性得你自己保证。)
412
+ 2. **换图 = 改文件 + bump 版本 + 重新 `publish`**。已装用户的图从包里读,只随版本更新获得;不 bump 版本,
413
+ 装了旧版的人永远看不到新图。
414
+
380
415
  ### 图标栏出现规则(appearsIn.iconBar)
381
416
 
382
417
  > **opt-IN——不声明 `appearsIn.iconBar` = 图标栏没有你的图标。** 曾经的 `iconLocation` 默认 `"top"`(opt-OUT——编辑器没声明也挤进图标栏)已被废弃,现在由 `appearsIn.iconBar` 声明式控制(`"top"` = 上部图标组,`"bottom"` = 底部固定组)。
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@linkdesk/plugin-docs",
3
- "version": "0.1.0",
3
+ "version": "0.1.1",
4
4
  "description": "LinkDesk 插件作者文档(离线包)——`docs/03-插件制造` 的发布产物:从零学会做一个插件(导览 / 三档动线 / 区域地图 / 组件速查 / 主题 / API 入口)。",
5
5
  "type": "module",
6
6
  "files": [