@linkdesk/plugin-docs 0.1.0 → 0.1.2

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.
package/README.md CHANGED
@@ -48,11 +48,21 @@ rule byte-for-byte comparison against the source (except the link rewrites b
48
48
 
49
49
  This package is the **fifth author axis** (the others: `@linkdesk/contracts` / `@linkdesk/plugin-sdk` / `create-linkdesk-plugin` / `@linkdesk/ui`) — **any content change means a PATCH**, and it is independent of the application version.
50
50
 
51
+ Its surface is the **generated** `docs/**`, so the order matters: edit the source trees under the repository's `docs/`, regenerate, then publish.
52
+
51
53
  ```bash
54
+ # 1. edit the source docs (docs/03-plugin-authoring/** English / docs/03-插件制造/** Chinese)
55
+ # 2. regenerate + verify byte-for-byte (in the LinkDesk repo root)
56
+ npm run docs:build && npm run docs:check
57
+ # 3. bump packages/plugin-docs/package.json version, then publish
52
58
  npm publish --registry=https://registry.npmjs.org # pass the registry explicitly (inside a workspace this package's .npmrc is ignored)
53
- npm run release:mark # record the baseline (verified against the shelf)
59
+ # 4. record the baseline (verified against the shelf)
60
+ npm run release:mark
54
61
  ```
55
62
 
63
+ > 🔴 The shelf read lags by **~3 minutes** for this package — don't re-publish on a 404.
64
+ > Full procedure + the three measured pitfalls → **`docs/06-发布管理/作者轴npm发版.md`** in the LinkDesk repository.
65
+
56
66
  ## License
57
67
 
58
68
  MIT
package/docs/00-readme.md CHANGED
@@ -105,7 +105,7 @@ System-level capabilities (serial ports, filesystem, configuration, dialogs) are
105
105
  **The commands authors actually type:**
106
106
 
107
107
  ```bash
108
- npm create linkdesk-plugin my-plugin # ① Create the project (once per plugin; auto git init + initial commit)
108
+ npm create linkdesk-plugin@latest my-plugin # ① Create the project (once per plugin; auto git init + initial commit)
109
109
  cd my-plugin && npm install # ② Install the SDK (types flow into the TS program automatically)
110
110
  npm run dev # Preview: browser dev host → HMR on save
111
111
  npm run dev:real # Real-machine loop: sub-second debugging inside an installed LinkDesk (for real-IPC plugins)
@@ -119,7 +119,7 @@ npm run publish # Publish to your own GitHub repo (step o
119
119
  ## 5. Zero to Shipped — The Shortest Path
120
120
 
121
121
  ```
122
- 1. npm create linkdesk-plugin my-plugin → generate the project (pluginId / name / author already filled in, git repo created)
122
+ 1. npm create linkdesk-plugin@latest my-plugin → generate the project (pluginId / name / author already filled in, git repo created)
123
123
  2. Write plugin.json + src/index.tsx → declare your plugin, write the first piece of UI
124
124
  3. npm run dev → see it in the browser preview host
125
125
  4. npm run build → produces my-plugin.linkdesk-plugin (a single-file zip)
@@ -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).
@@ -29,18 +29,20 @@ Break any of these and your plugin **installs but then breaks** (it can even tak
29
29
  **What to do**
30
30
 
31
31
  ```bash
32
- npm create linkdesk-plugin my-cool-plugin # the name must be kebab-case (lowercase letters/digits/hyphens)
32
+ npm create linkdesk-plugin@latest my-cool-plugin # the name must be kebab-case (lowercase letters/digits/hyphens)
33
33
  cd my-cool-plugin
34
34
  npm install
35
35
  ```
36
36
 
37
- Running `npm create linkdesk-plugin` with no arguments asks for the plugin name interactively.
37
+ Running `npm create linkdesk-plugin@latest` with no arguments asks for the plugin name interactively.
38
+
39
+ > 🔴 **Keep the `@latest`.** Without a version anchor npm's npx cache can silently hand you a months-old copy of the scaffold, and the CLI never prints its own version — the only symptom is a project **missing files** (no git repo, no `AGENTS.md`, no CI, 7 files instead of 16). If that already happened to you: `npm cache clean --force`, then re-run.
38
40
 
39
41
  **How to know you did it right**
40
42
  A new directory shows `plugin.json` + `src/index.tsx`, and placeholders like `{{pluginName}}` in `plugin.json` have **been replaced with your real plugin name** (`pluginId` / `name` / `description` / `author` are filled in too, with `author` defaulting to `git config user.name`). The CLI prints a line telling you **whether a git repo was created**: if it was, `git log` has one "initial skeleton" commit and the branch is called `main`.
41
43
 
42
44
  **Which doc has the details**
43
- [02-plugin-dev-toolchain/01-create-linkdesk-plugin-scaffold.md](https://github.com/Encaron/linkdesk/blob/electron/docs/02-Electron架构/E6_插件生态与发布/02-插件开发工具链/01-create-linkdesk-plugin脚手架.md) — the **file-by-file contract** for the generated output (why each file exists, the placeholder rules, the roles of the 15 template files). **Don't look for the project structure here**; that doc is the single source of truth.
45
+ [02-plugin-dev-toolchain/01-create-linkdesk-plugin-scaffold.md](https://github.com/Encaron/linkdesk/blob/electron/docs/02-Electron架构/E6_插件生态与发布/02-插件开发工具链/01-create-linkdesk-plugin脚手架.md) — the **file-by-file contract** for the generated output (why each file exists, the placeholder rules, the roles of the 16 template files). **Don't look for the project structure here**; that doc is the single source of truth.
44
46
 
45
47
  > ✅ **Repo creation (shipped 2026-09-14)**: the scaffold **creates the git repo for you** — following the three `cargo new` semantics, **not "always `git init`"**:
46
48
  > - the project directory is **not inside any git repo** ⇒ `git init -b main` automatically + **one initial commit** (the template ships a `.gitignore`, so your first step isn't a screenful of untracked files);
@@ -48,7 +50,7 @@ A new directory shows `plugin.json` + `src/index.tsx`, and placeholders like `{{
48
50
  > - **`--no-git`** ⇒ never create one (the escape hatch, matching `cargo new --vcs none`).
49
51
  >
50
52
  > The CLI **prints explicitly** whether it created a repo and why, so don't guess. 🔴 **This requires scaffold version ≥ 0.1.3** — older versions
51
- > neither create a repo nor generate CI in the project (`npm create linkdesk-plugin` pulls the latest by default).
53
+ > neither create a repo nor generate CI in the project. The CLI has no `--version` flag, so it can't tell you which copy you got; that is exactly why Step 1's command carries `@latest`.
52
54
  > Where the project should live and what the repo should be called → [15-multi-repo-and-local-workspace](15-multi-repo-and-local-workspace.md).
53
55
 
54
56
  ---
@@ -29,7 +29,7 @@
29
29
  ### Step 1: Scaffold the Project
30
30
 
31
31
  ```bash
32
- npm create linkdesk-plugin theme-myglass # kebab-case name
32
+ npm create linkdesk-plugin@latest theme-myglass # kebab-case name
33
33
  cd theme-myglass
34
34
  npm install
35
35
  ```
@@ -105,7 +105,7 @@
105
105
  **作者真正敲的命令**:
106
106
 
107
107
  ```bash
108
- npm create linkdesk-plugin my-plugin # ① 建工程(每建一个用一次;自动 git init + 初始提交)
108
+ npm create linkdesk-plugin@latest my-plugin # ① 建工程(每建一个用一次;自动 git init + 初始提交)
109
109
  cd my-plugin && npm install # ② 装 SDK(类型自动进 TS program)
110
110
  npm run dev # 预览:浏览器 dev 宿主 → 改码 HMR
111
111
  npm run dev:real # 真机环:在已装 LinkDesk 里秒级真机调试(真 IPC 插件用)
@@ -119,7 +119,7 @@ npm run publish # 发布到你自己的 GitHub 仓(上
119
119
  ## 五、从零到上线——最短路径
120
120
 
121
121
  ```
122
- 1. npm create linkdesk-plugin my-plugin → 生成工程(pluginId / name / author 已填好,git 仓已建)
122
+ 1. npm create linkdesk-plugin@latest my-plugin → 生成工程(pluginId / name / author 已填好,git 仓已建)
123
123
  2. 写 plugin.json + src/index.tsx → 声明你的插件、写第一段 UI
124
124
  3. npm run dev → 浏览器预览宿主里看见它
125
125
  4. npm run build → 产出 my-plugin.linkdesk-plugin(单文件 zip)
@@ -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"` = 底部固定组)。
@@ -29,18 +29,20 @@
29
29
  **做什么**
30
30
 
31
31
  ```bash
32
- npm create linkdesk-plugin my-cool-plugin # 名字必须 kebab-case(小写字母/数字/连字符)
32
+ npm create linkdesk-plugin@latest my-cool-plugin # 名字必须 kebab-case(小写字母/数字/连字符)
33
33
  cd my-cool-plugin
34
34
  npm install
35
35
  ```
36
36
 
37
- 不带参数运行 `npm create linkdesk-plugin` 会交互式问插件名。
37
+ 不带参数运行 `npm create linkdesk-plugin@latest` 会交互式问插件名。
38
+
39
+ > 🔴 **`@latest` 别省。** 不带版本锚时,npm 的 npx 缓存可能**一声不响**给你一份几个月前的脚手架拷贝,而 CLI 从不打印自己的版本号——唯一的症状是生成出来的工程**少了文件**(没有 git 仓、没有 `AGENTS.md`、没有 CI,只有 7 个文件而不是 16 个)。已经中招的人:`npm cache clean --force`,再重跑。
38
40
 
39
41
  **怎么知道做对了**
40
42
  新目录里出现 `plugin.json` + `src/index.tsx`,且 `plugin.json` 里的 `{{pluginName}}` 之类占位符**已替换成你的真实插件名**(还有 `pluginId` / `name` / `description` / `author` 已填好,`author` 默认取 `git config user.name`)。CLI 会打印一行告诉你**建没建 git 仓**:建了的话 `git log` 里有一笔「初始骨架」提交、分支叫 `main`。
41
43
 
42
44
  **细节点哪一篇**
43
- [02-插件开发工具链/01-create-linkdesk-plugin脚手架.md](https://github.com/Encaron/linkdesk/blob/electron/docs/02-Electron架构/E6_插件生态与发布/02-插件开发工具链/01-create-linkdesk-plugin脚手架.md)——生成产物的**逐文件契约**(每个文件为什么存在、占位符规则、15 个模板文件的角色)。**项目结构不要在这里找**,那篇是唯一真相源。
45
+ [02-插件开发工具链/01-create-linkdesk-plugin脚手架.md](https://github.com/Encaron/linkdesk/blob/electron/docs/02-Electron架构/E6_插件生态与发布/02-插件开发工具链/01-create-linkdesk-plugin脚手架.md)——生成产物的**逐文件契约**(每个文件为什么存在、占位符规则、16 个模板文件的角色)。**项目结构不要在这里找**,那篇是唯一真相源。
44
46
 
45
47
  > ✅ **建仓(2026-09-14 已落地)**:脚手架**代建 git 仓**——照 `cargo new` 的三条语义,**不是「一律 `git init`」**:
46
48
  > - 工程目录**不在任何 git 仓里** ⇒ 自动 `git init -b main` + **一次初始提交**(模板自带 `.gitignore`,所以你第一步看到的不是满屏 untracked);
@@ -48,7 +50,7 @@ npm install
48
50
  > - **`--no-git`** ⇒ 一律不建(逃生口,对标 `cargo new --vcs none`)。
49
51
  >
50
52
  > CLI 会**明确打印**它到底建没建、为什么,别自己猜。🔴 **前提是脚手架的版本 ≥ 0.1.3**——旧版
51
- > 既不会建仓、生成的工程也没有 CI(`npm create linkdesk-plugin` 默认取最新版)。
53
+ > 既不会建仓、生成的工程也没有 CI。CLI 没有 `--version` 旗标,它自己说不出拿到的是哪一版;这正是第 1 步那条命令必须带 `@latest` 的原因。
52
54
  > 工程该放哪、仓该叫什么 → [15-多仓开发与本地工作区](15-多仓开发与本地工作区.md)。
53
55
 
54
56
  ---
@@ -29,7 +29,7 @@
29
29
  ### 第 1 步:生成工程骨架
30
30
 
31
31
  ```bash
32
- npm create linkdesk-plugin theme-myglass # 名字 kebab-case
32
+ npm create linkdesk-plugin@latest theme-myglass # 名字 kebab-case
33
33
  cd theme-myglass
34
34
  npm install
35
35
  ```
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.2",
4
4
  "description": "LinkDesk 插件作者文档(离线包)——`docs/03-插件制造` 的发布产物:从零学会做一个插件(导览 / 三档动线 / 区域地图 / 组件速查 / 主题 / API 入口)。",
5
5
  "type": "module",
6
6
  "files": [