@linkdesk/plugin-docs 0.1.1 → 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 +11 -1
- package/docs/00-readme.md +2 -2
- 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/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)
|
|
@@ -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/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
|
---
|