@linkdesk/plugin-docs 0.1.1 → 0.1.3
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 +11 -1
- package/docs/00-readme.md +2 -2
- package/docs/05-ui-conventions.md +34 -0
- package/docs/13-development-guide.md +6 -4
- package/docs/themes/01-build-a-theme-plugin.md +1 -1
- package/docs/zh/00-README.md +2 -2
- package/docs/zh/05-/346/217/222/344/273/266UI/345/206/231/346/263/225/350/247/204/347/272/246.md +30 -0
- package/docs/zh/13-/346/217/222/344/273/266/345/274/200/345/217/221/346/214/207/345/215/227.md +6 -4
- package/docs/zh//344/270/273/351/242/230/01-/345/201/232/344/270/200/344/270/252/344/270/273/351/242/230/346/217/222/344/273/266.md +1 -1
- package/package.json +1 -1
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
|
-
|
|
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)
|
|
@@ -526,6 +526,39 @@ When authors build their own settings UI or manage their own saves (without goin
|
|
|
526
526
|
|
|
527
527
|
---
|
|
528
528
|
|
|
529
|
+
## 12. CSS Class Names—Prefix Your Own Elements; Don't "Borrow" Reserved Names
|
|
530
|
+
|
|
531
|
+
**One thing to remember first: the plugin view's stylesheet is not yours alone.** The same window loads the
|
|
532
|
+
host's styles, the shared components' (`@linkdesk/ui`) styles, and **every loaded plugin's** styles at once —
|
|
533
|
+
**class names are global identifiers**. Writing a class name claims that name; if someone else uses it too,
|
|
534
|
+
both stylesheets land on the same element.
|
|
535
|
+
|
|
536
|
+
**Two rules:**
|
|
537
|
+
|
|
538
|
+
1. **Give your own elements prefixed class names**—that's what the official plugins do (`settings-*`, `ms-*`,
|
|
539
|
+
`mpd-*`). Use your plugin name or an abbreviation as the prefix, not something obviously generic like
|
|
540
|
+
`.active-panel`.
|
|
541
|
+
2. **These names are reserved by the host—don't use them for your own elements** (if you do, the host's
|
|
542
|
+
styles will hit you):
|
|
543
|
+
|
|
544
|
+
| Source | Reserved names | Notes |
|
|
545
|
+
|---|---|---|
|
|
546
|
+
| Host global utility classes | `.input` | Input-box utility—**just use it** (it exists for your inputs) |
|
|
547
|
+
| Host global utility classes | `.titlebar`, `.divider`, `.about`, `.rn`, `.vta` | The host UI's own container names; don't reuse them |
|
|
548
|
+
| Shared component public classes | `.badge`, `.button`, `.combobox`, `.mdv`, `.selectbox`, `.sle`, `.slider`, `.toggle` | Class names of the badge / button / combobox / Markdown container / select / string-list editor / slider / toggle components in `@linkdesk/ui` |
|
|
549
|
+
|
|
550
|
+
**Want their look? Use their component**—`import { Button } from "@linkdesk/ui"`, don't hand-write its class
|
|
551
|
+
name (hand-writing bypasses the component, and you fall behind the moment it changes).
|
|
552
|
+
|
|
553
|
+
**Always use state classes in compound form**: `.your-class.active`, `.your-class.on` (never bare
|
|
554
|
+
`.active {}` or `.on {}`—that would also restyle same-named state elements in the host and in other plugins).
|
|
555
|
+
|
|
556
|
+
**A real example from this project**: using a host-reserved name as a "handy style name" on your own element
|
|
557
|
+
painted the background and the text the same color, so the text was swallowed by its own background — the UI
|
|
558
|
+
just looked like "a solid block". **No error**, just wrong, and hard to trace.
|
|
559
|
+
|
|
560
|
+
---
|
|
561
|
+
|
|
529
562
|
## Quick Reference
|
|
530
563
|
|
|
531
564
|
| What you want to do | Core facility | How to bring it in |
|
|
@@ -544,6 +577,7 @@ When authors build their own settings UI or manage their own saves (without goin
|
|
|
544
577
|
| Six-domain token overview | see the §11.1 matrix | color/surface/radius/glass/font size/font family—`var(--*)` follows theme+glass+scaling automatically; full list in `src/index.css` |
|
|
545
578
|
| UI discipline gate | `linkdesk-plugin-sdk lint` | all 15 items are WARNs that never fail; a knowing bypass = a standard eslint-disable declaration (see §11.2) |
|
|
546
579
|
| Text | `t()` | `useTranslation()` from `react-i18next` |
|
|
580
|
+
| CSS class names / state classes | own prefix + host reserved-name list | see §12 (class names are global—all plugins share the document with the host) |
|
|
547
581
|
| Sidebar list selection | `onMouseDown` (not `onClick`) | aligned with VS Code Explorer—prevents lost events when a fast click crosses elements |
|
|
548
582
|
|
|
549
583
|
**Use these facilities when writing plugins; don't hand-roll. Even if you write one, it'll have to be torn out later—better to normalize from day one.**
|
|
@@ -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
|
|
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
|
|
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
|
---
|
package/docs/zh/00-README.md
CHANGED
|
@@ -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)
|
package/docs/zh/05-/346/217/222/344/273/266UI/345/206/231/346/263/225/350/247/204/347/272/246.md
CHANGED
|
@@ -526,6 +526,35 @@ monaco 当前背景不透明、只二态跟随(亮/暗)是**过渡态绕开
|
|
|
526
526
|
|
|
527
527
|
---
|
|
528
528
|
|
|
529
|
+
## 12. CSS 类名——自己的元素用自有前缀,宿主保留名不要「借用」
|
|
530
|
+
|
|
531
|
+
**先记住一件事:插件视图的样式表不是你自己独占的。** 同一个窗口里同时加载着宿主的样式、共享组件
|
|
532
|
+
(`@linkdesk/ui`)的样式、以及**所有已加载插件**的样式——**类名是全局标识符**。你写下一个类名,
|
|
533
|
+
就等于占用了这个名字;别人也用这个名字,两边的样式就会落到同一个元素上。
|
|
534
|
+
|
|
535
|
+
**两条纪律:**
|
|
536
|
+
|
|
537
|
+
1. **给自己的元素起带前缀的类名**——官方插件就是这么做的(`settings-*`、`ms-*`、`mpd-*`)。
|
|
538
|
+
前缀用你自己的插件名或简写,别用 `.active-panel` 这种一看就通用的名字。
|
|
539
|
+
2. **下面这些名字属于宿主保留名,不要拿来给自己的元素命名**(用了就会被宿主的样式命中):
|
|
540
|
+
|
|
541
|
+
| 来源 | 保留名 | 说明 |
|
|
542
|
+
|---|---|---|
|
|
543
|
+
| 宿主全局工具类 | `.input` | 输入框工具类——**直接用即可**(它本来就是给你的输入框用的) |
|
|
544
|
+
| 宿主全局工具类 | `.titlebar`、`.divider`、`.about`、`.rn`、`.vta` | 宿主界面自己的容器名,不要复用 |
|
|
545
|
+
| 共享组件公共类名 | `.badge`、`.button`、`.combobox`、`.mdv`、`.selectbox`、`.sle`、`.slider`、`.toggle` | 分别是 `@linkdesk/ui` 里徽标 / 按钮 / 组合输入 / Markdown 容器 / 下拉 / 数组编辑器 / 滑杆 / 开关的类名 |
|
|
546
|
+
|
|
547
|
+
**要它们的样子,就用它们的组件**——`import { Button } from "@linkdesk/ui"`,不要手写它的类名
|
|
548
|
+
(手写等于绕过组件,组件升级你就掉队)。
|
|
549
|
+
|
|
550
|
+
**状态类一律复合使用**:`.你的类.active`、`.你的类.on`(不要裸写 `.active {}`、`.on {}`——那会把
|
|
551
|
+
宿主和其他插件里带同名状态类的元素一起改掉)。
|
|
552
|
+
|
|
553
|
+
**反例(真实踩过)**:把宿主保留名当成「随手可用的样式名」套到自己的元素上,结果底色和文字被涂成
|
|
554
|
+
同一个颜色、文字被背景吞掉,界面上看着就是「一块纯色」——**不报错**,只是长得不对,很难查。
|
|
555
|
+
|
|
556
|
+
---
|
|
557
|
+
|
|
529
558
|
## 速查
|
|
530
559
|
|
|
531
560
|
| 你要做的 | 核心设施 | 引入方式 |
|
|
@@ -544,6 +573,7 @@ monaco 当前背景不透明、只二态跟随(亮/暗)是**过渡态绕开
|
|
|
544
573
|
| 六域 token 总览 | 见 §11.1 矩阵 | 颜色/表面/圆角/玻璃/字号/字体族——`var(--*)` 自动跟随主题+玻璃+缩放;完整清单 `src/index.css` |
|
|
545
574
|
| UI 纪律门禁 | `linkdesk-plugin-sdk lint` | 15 项全 WARN 永不 fail;知情绕行 = 标准 eslint-disable 声明(见 §11.2) |
|
|
546
575
|
| 文字 | `t()` | `useTranslation()` from `react-i18next` |
|
|
576
|
+
| CSS 类名 / 状态类 | 自有前缀 + 宿主保留名清单 | 见 §12(类名是全局的——所有插件与宿主同表) |
|
|
547
577
|
| 侧栏列表选中 | `onMouseDown`(非 `onClick`) | 对标 VS Code Explorer——防止快速点击跨元素丢事件 |
|
|
548
578
|
|
|
549
579
|
**写插件时用这些设施,别手写。写了以后也得拆——不如从第一天就归一。**
|
package/docs/zh/13-/346/217/222/344/273/266/345/274/200/345/217/221/346/214/207/345/215/227.md
CHANGED
|
@@ -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)——生成产物的**逐文件契约**(每个文件为什么存在、占位符规则、
|
|
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
|
|
53
|
+
> 既不会建仓、生成的工程也没有 CI。CLI 没有 `--version` 旗标,它自己说不出拿到的是哪一版;这正是第 1 步那条命令必须带 `@latest` 的原因。
|
|
52
54
|
> 工程该放哪、仓该叫什么 → [15-多仓开发与本地工作区](15-多仓开发与本地工作区.md)。
|
|
53
55
|
|
|
54
56
|
---
|