@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 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)
@@ -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)
@@ -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.1",
3
+ "version": "0.1.2",
4
4
  "description": "LinkDesk 插件作者文档(离线包)——`docs/03-插件制造` 的发布产物:从零学会做一个插件(导览 / 三档动线 / 区域地图 / 组件速查 / 主题 / API 入口)。",
5
5
  "type": "module",
6
6
  "files": [