@linkdesk/plugin-docs 0.1.0
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 +58 -0
- package/docs/00-readme.md +189 -0
- package/docs/01-plugin-api-contract.md +171 -0
- package/docs/02-plugin-lifecycle.md +348 -0
- package/docs/03-contributes-spec.md +800 -0
- package/docs/04-distribution-format.md +172 -0
- package/docs/05-ui-conventions.md +549 -0
- package/docs/06-plugin-json-spec.md +640 -0
- package/docs/07-plugin-to-plugin-communication.md +299 -0
- package/docs/08-view-container-api.md +405 -0
- package/docs/09-plugin-directory-layout.md +301 -0
- package/docs/10-building-a-settings-plugin.md +164 -0
- package/docs/11-authoring-themes.md +173 -0
- package/docs/12-readme-media-contract.md +74 -0
- package/docs/13-development-guide.md +259 -0
- package/docs/14-data-pipeline-command-conventions.md +173 -0
- package/docs/15-multi-repo-and-local-workspace.md +86 -0
- package/docs/16-naming-conventions.md +77 -0
- package/docs/17-region-map.md +225 -0
- package/docs/18-cross-region-wiring.md +192 -0
- package/docs/19-component-cheatsheet.md +108 -0
- package/docs/20-adding-a-setting.md +159 -0
- package/docs/themes/01-build-a-theme-plugin.md +150 -0
- package/docs/themes/02-theme-field-index.md +145 -0
- package/docs/zh/00-README.md +189 -0
- package/docs/zh/01-/346/217/222/344/273/266API/345/245/221/347/272/246.md +171 -0
- package/docs/zh/02-/346/217/222/344/273/266/347/224/237/345/221/275/345/221/250/346/234/237.md +348 -0
- package/docs/zh/03-/346/217/222/344/273/266contributes/350/247/204/350/214/203.md +800 -0
- package/docs/zh/04-/346/217/222/344/273/266/345/210/206/345/217/221/346/240/274/345/274/217.md +172 -0
- package/docs/zh/05-/346/217/222/344/273/266UI/345/206/231/346/263/225/350/247/204/347/272/246.md +549 -0
- package/docs/zh/06-plugin.json/350/247/204/350/214/203.md +640 -0
- package/docs/zh/07-/346/217/222/344/273/266/351/227/264/351/200/232/344/277/241.md +299 -0
- package/docs/zh/08-ViewContainer-/350/247/206/345/233/276/345/256/271/345/231/250API.md +403 -0
- package/docs/zh/09-/346/217/222/344/273/266/347/233/256/345/275/225/350/247/204/350/214/203.md +301 -0
- package/docs/zh/10-/345/246/202/344/275/225/351/200/240/344/270/200/344/270/252/350/256/276/347/275/256/346/217/222/344/273/266.md +164 -0
- package/docs/zh/11-/344/270/273/351/242/230/345/210/266/344/275/234.md +172 -0
- package/docs/zh/12-README/350/257/264/346/230/216/345/214/272/345/252/222/344/275/223/345/245/221/347/272/246.md +74 -0
- package/docs/zh/13-/346/217/222/344/273/266/345/274/200/345/217/221/346/214/207/345/215/227.md +259 -0
- package/docs/zh/14-/346/225/260/346/215/256/347/256/241/351/201/223/345/221/275/344/273/244/347/272/246/345/256/232.md +173 -0
- package/docs/zh/15-/345/244/232/344/273/223/345/274/200/345/217/221/344/270/216/346/234/254/345/234/260/345/267/245/344/275/234/345/214/272.md +86 -0
- package/docs/zh/16-/345/221/275/345/220/215/350/247/204/350/214/203.md +77 -0
- package/docs/zh/17-/345/214/272/345/237/237/345/234/260/345/233/276.md +225 -0
- package/docs/zh/18-/345/214/272/345/237/237/351/227/264/344/272/222/345/212/250.md +192 -0
- package/docs/zh/19-/347/273/204/344/273/266/351/200/237/346/237/245.md +108 -0
- package/docs/zh/20-/346/210/221/347/232/204/346/217/222/344/273/266/345/212/240/344/270/200/346/235/241/351/205/215/347/275/256/351/241/271.md +159 -0
- package/docs/zh/plugin.schema.json +687 -0
- 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 +150 -0
- package/docs/zh//344/270/273/351/242/230/02-/344/270/273/351/242/230/345/255/227/346/256/265/351/200/237/346/237/245.md +145 -0
- package/package.json +20 -0
|
@@ -0,0 +1,173 @@
|
|
|
1
|
+
# 11-Authoring Themes (third-party theme plugin author guide)
|
|
2
|
+
|
|
3
|
+
> **Status:** final (2026-08-23) — the schema is frozen ([05](https://github.com/Encaron/linkdesk/blob/electron/docs/02-Electron架构/E5.8_归一化基建/外观主题化/05-主题数据模型.md) decisions A-F).
|
|
4
|
+
> **In one line:** a theme = a kind of plugin — one recipe json (style domain + colorway variants) + optional assets; a "domain contributor" inherits the default for any domain it leaves out, so the less you write the more stable it is.
|
|
5
|
+
> **AI-friendliness:** the readers of this doc = **humans + AI** — an AI reading it can produce valid theme files, and an AI reading an example theme (such as the migrated mint-soda) can imitate equivalents. Every schema concept has exactly one way to be written (decision F: always `colorways[]`).
|
|
6
|
+
> **2026-09-06 reconciliation with the implementation** (audit): flattened single root (no plugins/{builtin,user}) · shared controls via @linkdesk/ui · distribution = .linkdesk-plugin zip. References to the corresponding mechanisms have been removed from this page.
|
|
7
|
+
|
|
8
|
+
## 1. What a theme plugin is
|
|
9
|
+
|
|
10
|
+
- A theme is a **plugin** (hard constraint 10: the shell hard-codes no plugin id; themes also go through a plugin.json declaration).
|
|
11
|
+
- One theme plugin = 1 recipe json (`appearance` style domain + `colorways[]` colorway variants). It may also contain multiple recipe json files.
|
|
12
|
+
- **Domain contributor**: write only the domains you own; the rest inherit the shell defaults ([03 Domain Contributors](https://github.com/Encaron/linkdesk/blob/electron/docs/02-Electron架构/E5.8_归一化基建/外观主题化/03-域贡献者与混搭.md)) — a pure-color theme = colors only; a glass theme = glass + colors.
|
|
13
|
+
- **Style vs. colorway separation**: if you want "1 style base + N colorways" → put `colorways[]` in one recipe ([05 §2](https://github.com/Encaron/linkdesk/blob/electron/docs/02-Electron架构/E5.8_归一化基建/外观主题化/05-主题数据模型.md) for the complete schema).
|
|
14
|
+
|
|
15
|
+
## 2. Writing a theme (create the directories first → three steps)
|
|
16
|
+
|
|
17
|
+
### ⓪ Directory structure (must-read — flattening into the root is forbidden)
|
|
18
|
+
|
|
19
|
+
A theme plugin's directories = three slots, each holding its own kind (aligned with the general convention in [09-plugin-directory-layout](09-plugin-directory-layout.md)):
|
|
20
|
+
|
|
21
|
+
```
|
|
22
|
+
theme-myglass/
|
|
23
|
+
├── plugin.json # declaration (contributes.themes)
|
|
24
|
+
├── themes/ # the only home for recipe json — flattening into the plugin root is forbidden
|
|
25
|
+
│ └── myglass.json
|
|
26
|
+
├── assets/ # assets: fonts (woff2/ttf) + background images (png/jpeg/webp)
|
|
27
|
+
│ ├── MyFont.woff2
|
|
28
|
+
│ └── bg.png
|
|
29
|
+
└── resources/ # plugin icon and other metadata assets (09 §general convention)
|
|
30
|
+
```
|
|
31
|
+
|
|
32
|
+
| Directory | What goes in it | Rule |
|
|
33
|
+
|:--|:--|:--|
|
|
34
|
+
| `themes/` | recipe json (`appearance` + `colorways[]`) | **recipe json always goes here; flattening into the plugin root is forbidden**; one plugin may contain multiple recipe json files (each `contributes.themes` entry's `path` points at one) |
|
|
35
|
+
| `assets/` | fonts (woff2/ttf) + background images (png/jpeg/webp) | write relative paths `assets/...` in the json → resolved uniformly by the shell's `getPluginAssetPath(pluginId, path)` (hard constraint 12); **absolute paths `/assets/...` are forbidden** |
|
|
36
|
+
| `resources/` | plugin icon and other metadata assets | consistent with the general convention in [09-plugin-directory-layout](09-plugin-directory-layout.md) |
|
|
37
|
+
|
|
38
|
+
> **Why flattening is forbidden:** themes only get deeper — per-surface fine-tuning json, i18n, README, src (if scripts/UI are needed) all land in the plugin directory over time. A flat root = every future file needs a last-minute decision about where it goes; with the `themes/`+`assets/`+`resources/` three slots set up first, **each kind of customization has its own home and extensions need zero moving** (2026-08-23 user decision: "there are definitely going to be more things to customize in themes down the road, so it has to be easy to get into theme authoring").
|
|
39
|
+
>
|
|
40
|
+
> **A minimal theme = just the one directory, `themes/`** (a pure-color theme pulls in no assets and can skip even `assets/`); only fonts/background images need `assets/`.
|
|
41
|
+
|
|
42
|
+
### ① plugin.json declaration
|
|
43
|
+
|
|
44
|
+
```jsonc
|
|
45
|
+
// plugin.json — theme declaration goes through contributes.themes (modeled on VS Code; authoritative schema in plugin.schema.json)
|
|
46
|
+
{
|
|
47
|
+
"id": "theme-myglass",
|
|
48
|
+
"name": "My Glass Theme",
|
|
49
|
+
"version": "0.1.0",
|
|
50
|
+
"contributes": {
|
|
51
|
+
"themes": [
|
|
52
|
+
{ "id": "myglass", "label": "My Glass", "uiTheme": "dark", "path": "themes/myglass.json" }
|
|
53
|
+
]
|
|
54
|
+
}
|
|
55
|
+
}
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
### ② Recipe json (referencing the schema)
|
|
59
|
+
|
|
60
|
+
```jsonc
|
|
61
|
+
// themes/myglass.json — contract = theme.schema.json (the contract ships with @linkdesk/plugin-sdk = the author's npm channel)
|
|
62
|
+
// Recommended: inject $schema on the first line for editor IntelliSense (modeled on plugin.schema.json):
|
|
63
|
+
// "$schema": "./node_modules/@linkdesk/plugin-sdk/schemas/theme.schema.json"
|
|
64
|
+
// ↑ this is the only form (relative to **the plugin's own project root**). Official theme plugins also
|
|
65
|
+
// live in their own repos with the same project shape as third parties; the in-repo
|
|
66
|
+
// "../../../public/schemas/…" relative form **became void when the source moved out**.
|
|
67
|
+
// Malformed-input interception: editor IntelliSense + the SDK's validateThemeJson (the same channel for npm projects and the official plugin repo)
|
|
68
|
+
// Full schema in [05 §2](../02-Electron架构/E5.8_归一化基建/外观主题化/05-主题数据模型.md); the runtime parseThemeRecipe toast is the second line of defense
|
|
69
|
+
{
|
|
70
|
+
"id": "myglass", "name": "My Glass", "type": "dark",
|
|
71
|
+
"appearance": {
|
|
72
|
+
"radius": { "md": 10, "lg": 16 },
|
|
73
|
+
"glass": { "blur": 16, "saturate": 1.3, "tint": "rgba(255,255,255,0.06)", "opacity": 0.9 },
|
|
74
|
+
"font": { "ui": "assets/MyFont.woff2", "mono": "JetBrains Mono" },
|
|
75
|
+
"background": { "image": "assets/bg.png", "opacity": 0.85, "mask": 0.3 } // mask = 0-1 brightness coefficient (number); the base color goes through maskColor separately
|
|
76
|
+
},
|
|
77
|
+
"colorways": [
|
|
78
|
+
{ "id": "violet", "name": "Violet", "colors": { "bg-window": "#0E0B16", "accent": "#8B5CF6" } },
|
|
79
|
+
{ "id": "emerald", "name": "Emerald", "colors": { "bg-window": "#0A1410", "accent": "#34D399" } }
|
|
80
|
+
]
|
|
81
|
+
}
|
|
82
|
+
```
|
|
83
|
+
|
|
84
|
+
> **A single-colorway theme** = a `colorways` array with exactly 1 item (e.g. the official dark theme after migration = `colorways: [{ id:"dark", name:"Dark", colors:{…} }]`) — **there is no second way to write it** (decision F).
|
|
85
|
+
|
|
86
|
+
### ③ Assets (optional)
|
|
87
|
+
|
|
88
|
+
- Fonts/background images live in the plugin directory and are referenced by **relative paths** in the json (`assets/...`) — at render time the shell resolves them uniformly with `getPluginAssetPath(pluginId, path)` (hard constraint 12). **Writing absolute paths like `/assets/...` is forbidden.**
|
|
89
|
+
- Fonts come in two forms: ① an asset path (distributed with the plugin) ② a system font-family name string (already present on the user's machine).
|
|
90
|
+
|
|
91
|
+
### ④ Fully-loaded example (all six domains written + assets + 3-4 colorways — the "almost everything is themeable" template)
|
|
92
|
+
|
|
93
|
+
> Authors who want to write every themeable domain in one go can copy this. **Style (the six appearance domains) and colorways are separated** — switching a colorway only touches array items; all assets are relative paths. The template comes from the shell's built-in liquid glass recipe.
|
|
94
|
+
|
|
95
|
+
```
|
|
96
|
+
theme-liquid-glass/
|
|
97
|
+
├── plugin.json # contributes.themes declaration
|
|
98
|
+
├── themes/
|
|
99
|
+
│ └── liquid-glass.json # fully-loaded recipe (all six domains written + 3 colorways)
|
|
100
|
+
├── assets/ # assets: fonts + background images
|
|
101
|
+
│ ├── SpaceGrotesk.woff2 # font.ui asset font
|
|
102
|
+
│ ├── JetBrainsMono.ttf # font.mono asset font
|
|
103
|
+
│ └── aurora.jpg # background.image asset
|
|
104
|
+
└── resources/
|
|
105
|
+
└── icon.svg # plugin icon
|
|
106
|
+
```
|
|
107
|
+
|
|
108
|
+
```jsonc
|
|
109
|
+
// themes/liquid-glass.json
|
|
110
|
+
{
|
|
111
|
+
"id": "liquid-glass",
|
|
112
|
+
"name": "Liquid Glass",
|
|
113
|
+
"type": "dark",
|
|
114
|
+
"appearance": {
|
|
115
|
+
"radius": { "xs": 2, "sm": 4, "md": 8, "lg": 14, "xl": 20, "2xl": 24 },
|
|
116
|
+
"glass": { "blur": 20, "saturate": 1.8, "tint": "rgba(14,16,24,0.38)", "opacity": 0.9, "specular": 0.6, "morph": 400, "radius": 14, "shadow": true },
|
|
117
|
+
"font": { "ui": "assets/SpaceGrotesk.woff2", "mono": "JetBrains Mono" },
|
|
118
|
+
"background": { "image": "assets/aurora.jpg", "opacity": 1, "mask": "rgba(0,0,0,0.88)" }
|
|
119
|
+
},
|
|
120
|
+
"colorways": [
|
|
121
|
+
{ "id": "aurora", "name": "Aurora Violet", "colors": { "bg-window": "#0E0B16", "accent": "#8B5CF6" } },
|
|
122
|
+
{ "id": "emerald", "name": "Emerald", "colors": { "bg-window": "#0A1410", "accent": "#34D399" } },
|
|
123
|
+
{ "id": "ocean", "name": "Deep Ocean", "colors": { "bg-window": "#0B121E", "accent": "#38BDF8" } }
|
|
124
|
+
]
|
|
125
|
+
}
|
|
126
|
+
```
|
|
127
|
+
|
|
128
|
+
| Domain | How to write it | Notes |
|
|
129
|
+
|:--|:--|:--|
|
|
130
|
+
| radius | six size steps | `--radius-pill`/`--radius-full` form values are not written here (excluded from the scale, [08 §3](https://github.com/Encaron/linkdesk/blob/electron/docs/02-Electron架构/E5.8_归一化基建/外观主题化/08-持久化与配置.md)) |
|
|
131
|
+
| glass | material keys + floating form | specular/morph = liquid glass's "specular highlight / response" ([02 §2.3](https://github.com/Encaron/linkdesk/blob/electron/docs/02-Electron架构/E5.8_归一化基建/外观主题化/02-变量契约.md) material positioning); radius/shadow = floating corner radius / drop shadow (merged into glass after the surface domain was removed; inset is host-derived and border is not a field) |
|
|
132
|
+
| font | ui asset path + mono system family name | asset fonts take two steps: first register the family name with @font-face → then write `--font-ui` |
|
|
133
|
+
| background | image asset + opacity + mask | relative path → getPluginAssetPath (hard constraint 12) |
|
|
134
|
+
| colorways | style base + N colorways | 3-4 is recommended; a single colorway is still an array with 1 item (decision F) |
|
|
135
|
+
|
|
136
|
+
> **Sparse and omittable:** the fully-loaded example only means "every domain is written" — missing domains inherit the shell defaults and missing keys within a domain inherit too (§3 sparse override); the less you write, the more stable it is. A pure-color theme = only `colorways` (and can skip even `assets/`).
|
|
137
|
+
|
|
138
|
+
## 3. Pitfalls
|
|
139
|
+
|
|
140
|
+
| Pitfall | Explanation |
|
|
141
|
+
|:--|:--|
|
|
142
|
+
| Recipe json flattened into the plugin root | **Forbidden (§2 ⓪ directory spec)** — always put it in `themes/`; future i18n/README each get their own home |
|
|
143
|
+
| Writing a top-level `colors` (no `colorways`) | **The old format is deprecated** (decision F) — the engine reads only `colorways[]`; even a single colorway goes in an array with 1 item |
|
|
144
|
+
| Writing absolute paths | Everything blows up under packaged `file://` — always relative paths + getPluginAssetPath |
|
|
145
|
+
| Repeating every color | Sparse override = write only the differing keys; unwritten ones inherit `:root`, which is more stable |
|
|
146
|
+
| Wanting to break free of the accent color | Use **your own token** (e.g. `--toggle-on-bg`) instead of reading `--accent` ([04 §6](https://github.com/Encaron/linkdesk/blob/electron/docs/02-Electron架构/E5.8_归一化基建/外观主题化/04-两层调节与设置页.md)) |
|
|
147
|
+
| Large blur values | `--glass-blur` has a performance ceiling (large-area backdrop-filter is a GPU burden) — the contract will spell out the number ([02 §2.3](https://github.com/Encaron/linkdesk/blob/electron/docs/02-Electron架构/E5.8_归一化基建/外观主题化/02-变量契约.md) pending decision) |
|
|
148
|
+
|
|
149
|
+
## 4. What theme authors get
|
|
150
|
+
|
|
151
|
+
- Data: `window.linkdesk.theme.listRecipes()` (including colorways/preview colors) — third-party UIs can consume it too ([06 §6](https://github.com/Encaron/linkdesk/blob/electron/docs/02-Electron架构/E5.8_归一化基建/外观主题化/06-主题API契约.md) pending decision 3: prefer reusing the general API).
|
|
152
|
+
- Applying: `setRecipe`/`setColorway`, or writing the `app.theme` configuration directly.
|
|
153
|
+
- Events: `theme:changed` (the payload carries tokens) for live reactions.
|
|
154
|
+
- Mix-and-match: your theme automatically shows up among the mix-and-match sources in the settings page according to the domains it contributes (`RecipeMeta.domains`), with **zero extra work for the author** ([10 §2](https://github.com/Encaron/linkdesk/blob/electron/docs/02-Electron架构/E5.8_归一化基建/外观主题化/10-混搭设计.md)).
|
|
155
|
+
|
|
156
|
+
## 5. Migration (existing theme plugins — decision F: zero backward compatibility)
|
|
157
|
+
|
|
158
|
+
The engine **reads only the new format** (`colorways[]`); the old flat format is no longer read ([05 §5](https://github.com/Encaron/linkdesk/blob/electron/docs/02-Electron架构/E5.8_归一化基建/外观主题化/05-主题数据模型.md)). Converting existing theme plugins:
|
|
159
|
+
|
|
160
|
+
| Plugin | Current state | After migration |
|
|
161
|
+
|:--|:--|:--|
|
|
162
|
+
| `theme-defaults` | dark.json + light.json (flat colors) | a single recipe json: `colorways: [{id:"dark",…},{id:"light",…}]` |
|
|
163
|
+
| `theme-mint-soda` | 4 json (mint-soda/mint-dew/sea-salt-mint/lime-mint) | 1 recipe json = 4 colorways (the theme list shows 1 card; recommended) |
|
|
164
|
+
| `theme-twilight-forest` | 4 json (green/purple/sunset/teal) | same as above → 1 recipe, 4 colorways |
|
|
165
|
+
|
|
166
|
+
Conversion = **pure data editing** (wrapping `colors` in a `colorways[]` array), with no engine changes. After merging, the theme picker list is cleaner (1 card with multiple colorways vs. N cards). **While migrating, also put things in place per the §2 ⓪ directory spec** (json into `themes/`, assets into `assets/`, the old flat structure zeroed out).
|
|
167
|
+
|
|
168
|
+
## 6. Related
|
|
169
|
+
|
|
170
|
+
- Authoritative schema: [05-Theme Data Model](https://github.com/Encaron/linkdesk/blob/electron/docs/02-Electron架构/E5.8_归一化基建/外观主题化/05-主题数据模型.md)
|
|
171
|
+
- Authoritative API: [06-Theme API Contract](https://github.com/Encaron/linkdesk/blob/electron/docs/02-Electron架构/E5.8_归一化基建/外观主题化/06-主题API契约.md)
|
|
172
|
+
- Theme appearance doc set: [Appearance Theming README](https://github.com/Encaron/linkdesk/blob/electron/docs/02-Electron架构/E5.8_归一化基建/外观主题化/README.md)
|
|
173
|
+
- General plugin specs: [06-plugin-json-spec](06-plugin-json-spec.md) / [03-contributes-spec](03-contributes-spec.md)
|
|
@@ -0,0 +1,74 @@
|
|
|
1
|
+
# README Description-Area Media Contract
|
|
2
|
+
|
|
3
|
+
> 2026-09-09 · Documented (the author contract was added after all four 70a–d forms shipped). **Written for third-party plugin authors.**
|
|
4
|
+
> This document answers one question: **your README gets displayed by the plugin details page inside the LinkDesk app — if you want images / animated images / demo videos in it, how should you write them, and what are the rules?** Benchmarked against the open display canvas of VS Code's update page / extension READMEs.
|
|
5
|
+
> Nature = **interface contract** — it only defines "how an author writes it correctly + how it will be displayed"; it contains no implementation code (the implementation surface = the shell's shared MarkdownView + the marketplace DetailView). Authors don't need to know how the app renders — just get the points below right.
|
|
6
|
+
|
|
7
|
+
---
|
|
8
|
+
|
|
9
|
+
## 1. Where your README is displayed, and the two sources with two sets of rules
|
|
10
|
+
|
|
11
|
+
The `README.md` in the plugin root directory is displayed in the **"Details" tab of the plugin details page** (that tab = the screenshot gallery + this README area; the README area is what the project commonly calls the "description area"). The details page has three horizontal tabs — **Details / Features / Changelog** — and the README belongs in the "Details" cell. **But there are two routes to reading that same README, and their media display capabilities differ — this is the single easiest thing to get wrong:**
|
|
12
|
+
|
|
13
|
+
| State | Where the README comes from | Relative-path media (assets shipped in the package) | https absolute-URL media |
|
|
14
|
+
|:--|:--|:--:|:--:|
|
|
15
|
+
| **Installed state** (the user downloaded and installed it, or it shipped with the shell, and then views the details) | Reads **the copy you packaged into the zip** | ✅ Shown | ✅ Shown |
|
|
16
|
+
| **Marketplace preview state** (not installed; the list/details read the remote README of the catalog entry) | Reads the **remote readmeUrl** | ❌ Not shown (honestly hidden — at that moment there is no in-package copy of yours to resolve) | ✅ Shown |
|
|
17
|
+
|
|
18
|
+
> **What this means:** if you want the image/video to be guaranteed visible after the user has **installed** the plugin → use a **relative path pointing inside the package** (§3 below); if you want the image/video to be visible even to **visitors who haven't installed it yet** → use an **https absolute URL**. Shipping only relative-path media = visible only once installed.
|
|
19
|
+
|
|
20
|
+
---
|
|
21
|
+
|
|
22
|
+
## 2. Supported media forms (four of them — copy them as-is and they work)
|
|
23
|
+
|
|
24
|
+
| Form | How the author writes it (README markdown / inline HTML both work) | Description-area behavior |
|
|
25
|
+
|:--|:--|:--|
|
|
26
|
+
| **Static image** | `` or `<img src="resources/cover.svg" alt="Serial cover">` | Shown. png / svg / webp / jpg / gif all work. **Writing alt is recommended** (screen-reader friendly; use an empty string for a purely decorative image) |
|
|
27
|
+
| **Animated image** | Same one-line form, with a genuinely animated gif | Shown and **it really animates** (same pipeline as static images) |
|
|
28
|
+
| **Cover link-out video** (GitLens style) | `<a href="https://youtube.com/…"><img src="resources/cover.svg" alt="Click the cover to see the demo"></a>` | The description area shows a **clickable cover**; clicking opens the external page in the **system default browser** (the app never loads external pages in-app) |
|
|
29
|
+
| **In-page video** (VS Code update-page style) | `<video src="resources/demo.mp4" controls poster="resources/cover.svg"></video>`<br>or `<video controls><source src="resources/demo.mp4" type="video/mp4"></video>` | The description area **plays it in place**: native control bar, draggable progress bar, click to go fullscreen (one click fills the screen, one exit restores it). mp4 / webm / m4v |
|
|
30
|
+
|
|
31
|
+
> Any **https external text link** (`[See the demo](https://…)`) behaves the same way: clicking it goes to the system default browser. mailto: goes to the mail client. **The app never pops up an external web page.**
|
|
32
|
+
|
|
33
|
+
---
|
|
34
|
+
|
|
35
|
+
## 3. Where image / video files go and how to write src (source rules)
|
|
36
|
+
|
|
37
|
+
1. **Write "relative path + shipped in the package"**: put media files in the plugin root's **`resources/`** and write the relative path `resources/cover.svg` in the README. **The SDK build automatically packs these README-referenced assets into the zip** (zero declarations; see [04-distribution-format.md](04-distribution-format.md)) → guaranteed to show in the installed state.
|
|
38
|
+
🔴 **Media always lives in `resources/`** — the same goes for icons (`plugin.json`'s `icon` / `marketIcon` also point at `resources/…`). **No loose images in the plugin root.**
|
|
39
|
+
2. **Remote URLs**: an absolute `https://…` address works directly (good when you also want it visible in marketplace preview).
|
|
40
|
+
3. **Things to avoid**: image sources using `http:` / `data:` / `javascript:` / `file:` **are never displayed** (the security allowlist rejects them); protocol-relative URLs starting with `//` are not displayed either; **don't reference anything outside the package** (`../` parent directories, absolute disk paths) — it neither ships with the package nor displays.
|
|
41
|
+
|
|
42
|
+
> ℹ️ **Technically, putting them in the plugin root also works** (the SDK only looks at what path the README writes, not at the directory). **Narrowing everything into `resources/` is a tidiness requirement, not a correctness requirement** — new plugins just need to match the official exemplars' `resources/` style.
|
|
43
|
+
|
|
44
|
+
---
|
|
45
|
+
|
|
46
|
+
## 4. Rendering contract — what can't be done, so don't count on it (hard security guarantees)
|
|
47
|
+
|
|
48
|
+
- **No scripts run.** The README is a pure display canvas: `<script>`, event attributes (`onclick`, etc.) and the `javascript:` protocol are **removed whole, branch and all**, by the sanitizing layer — it's not that you wrote it wrong, it simply can't get in by design. Don't think in terms of "stuff JS into the README so the details page executes it".
|
|
49
|
+
- **Video never autoplays.** Writing `autoplay` has no effect (opening the description area must never suddenly make sound). Load strategy = `preload: metadata` (no full pre-download; saves bandwidth).
|
|
50
|
+
- **Controls are forced on.** An in-page `<video>` gets `controls` added even if you didn't write it (otherwise the reader has no way to start playback).
|
|
51
|
+
- Links with a dangerous / unknown protocol are removed whole and never reach the DOM.
|
|
52
|
+
|
|
53
|
+
---
|
|
54
|
+
|
|
55
|
+
## 5. Packaging and release discipline (change the content and you must re-release, or users won't see it)
|
|
56
|
+
|
|
57
|
+
1. **Any content change must bump `plugin.json.version`** ([§4 of 04](04-distribution-format.md), a core discipline): an installed user's copy is **frozen per version** — the app only fills in what's missing and never refreshes what's installed. You added an image / swapped a video in the README but didn't bump → installed users see the old content forever. README touched = content change = must bump + rebuild the zip.
|
|
58
|
+
2. **The zip is a one-off build artifact; it does not regenerate itself.** The SDK build (or `pack` for theme-type plugins) automatically collects the README-referenced assets into the package — but after you **change the README / the media / or touch the SDK packaging config** (the externalization list, etc.), the old zip on disk won't turn itself into a new one; **you must rebuild + re-release**. Rule of thumb: you installed a new package and it's still wrong → most likely the zip itself is stale → rebuild.
|
|
59
|
+
3. **Bundled zips shipped with the shell are the same**: re-zipping always requires a bump; `npm run check`'s packaging gate will red-flag a "same-version content diff" — don't work around it.
|
|
60
|
+
|
|
61
|
+
---
|
|
62
|
+
|
|
63
|
+
## 6. Live exemplars (copy them and you can't go wrong)
|
|
64
|
+
|
|
65
|
+
- The READMEs of the 8 official plugins that already embed scene covers are ready-made models: `editor` / `file-tree` / `serial-monitor` / `settings` / `python` / `theme-terminal` / `theme-aurora-glass` / `lang-defaults` (plus the first real third-party plugin, `hello-linkdesk`). The `` at the top of their READMEs is the standard way to write a cover.
|
|
66
|
+
- In-page `<video>` / cover link-out examples: the serial-monitor README's git history commits `2f9a52c6b` (real in-page playback) and `8c9d71551` (fullscreen fix) each carry a complete `<video>` / `<a><img></a>` example from the manual testing of that moment, reverted once verified — look at those two commits if you want to copy a complete example.
|
|
67
|
+
|
|
68
|
+
---
|
|
69
|
+
|
|
70
|
+
## Related
|
|
71
|
+
|
|
72
|
+
- [04-distribution-format.md](04-distribution-format.md) — zip packaging, content-change bumps, the `linkdesk://` resource protocol
|
|
73
|
+
- [09-plugin-directory-layout.md](09-plugin-directory-layout.md) — where files go
|
|
74
|
+
- The paired marketplace icon fields `marketIcon` / cover → [06-plugin-json-spec](06-plugin-json-spec.md)
|
|
@@ -0,0 +1,259 @@
|
|
|
1
|
+
# Plugin Development Guide — From Zero to Shipped
|
|
2
|
+
|
|
3
|
+
> 2026-09-12. **This is a walkthrough, not a reference manual.** Every step covers only three things: **what to do** / **how to know you did it right** / **which doc has the details**.
|
|
4
|
+
> Field meanings, method signatures, and normative clauses are **never repeated here** — each has its own single source of truth, so follow the links. Repeating them = creating a second source of truth = it will clash with the real one sooner or later.
|
|
5
|
+
|
|
6
|
+
| | |
|
|
7
|
+
|---|---|
|
|
8
|
+
| Readers | Someone writing a LinkDesk plugin for the first time |
|
|
9
|
+
| Shape | A tutorial walkthrough (just execute it in order from the top) |
|
|
10
|
+
| Not | An API reference (→ [01-plugin-api-contract](01-plugin-api-contract.md) + [the plugin-sdk README cheatsheet](https://github.com/Encaron/linkdesk/blob/electron/packages/plugin-sdk/README.md#api-速查表)) · a field dictionary (→ [06-plugin-json-spec](06-plugin-json-spec.md)) · normative clauses (→ the [00-readme](00-readme.md) index) |
|
|
11
|
+
| Estimate | Steps 1-3: see your own plugin running in 10 minutes |
|
|
12
|
+
|
|
13
|
+
---
|
|
14
|
+
|
|
15
|
+
## Before You Start — Three Iron Rules
|
|
16
|
+
|
|
17
|
+
Break any of these and your plugin **installs but then breaks** (it can even take the shell down with it). Memorize them now; that's much cheaper than fixing things afterwards:
|
|
18
|
+
|
|
19
|
+
1. **Use only `window.linkdesk.*`** — importing shell internals (`@src/core/...`) is forbidden. ESLint `noCoreImportInPlugin` is at `error` level, so the moment you write it, it's red.
|
|
20
|
+
2. **Colors go through CSS variables `var(--xxx)`** — hardcoded hex is forbidden, otherwise your plugin won't follow theme switches.
|
|
21
|
+
3. **Copy goes through `t()`** — the key is the source text (Chinese plugins use Chinese keys, with Chinese as the built-in fallback; English translations go in `i18n/en.json`).
|
|
22
|
+
|
|
23
|
+
> All eight rules + their scope → [00-readme §Hard Constraints](00-readme.md#hard-constraints--before-you-write-any-plugin-code).
|
|
24
|
+
|
|
25
|
+
---
|
|
26
|
+
|
|
27
|
+
## Step 1: Generate the Project Skeleton
|
|
28
|
+
|
|
29
|
+
**What to do**
|
|
30
|
+
|
|
31
|
+
```bash
|
|
32
|
+
npm create linkdesk-plugin my-cool-plugin # the name must be kebab-case (lowercase letters/digits/hyphens)
|
|
33
|
+
cd my-cool-plugin
|
|
34
|
+
npm install
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
Running `npm create linkdesk-plugin` with no arguments asks for the plugin name interactively.
|
|
38
|
+
|
|
39
|
+
**How to know you did it right**
|
|
40
|
+
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
|
+
|
|
42
|
+
**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.
|
|
44
|
+
|
|
45
|
+
> ✅ **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
|
+
> - 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);
|
|
47
|
+
> - the project directory **is already inside some git repo** ⇒ **don't create one** (prevents nested repos — for example when you generate the plugin in a subdirectory of an existing repo);
|
|
48
|
+
> - **`--no-git`** ⇒ never create one (the escape hatch, matching `cargo new --vcs none`).
|
|
49
|
+
>
|
|
50
|
+
> 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).
|
|
52
|
+
> 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
|
+
|
|
54
|
+
---
|
|
55
|
+
|
|
56
|
+
## Step 2: Run It and See It
|
|
57
|
+
|
|
58
|
+
**What to do**
|
|
59
|
+
|
|
60
|
+
```bash
|
|
61
|
+
npm run dev # = linkdesk-plugin-sdk dev
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
**How to know you did it right**
|
|
65
|
+
A browser opens the dev host page automatically, showing the template's built-in **"Plugin is running ✨"**. Now edit the text in `src/index.tsx` and save — **the page updates instantly** (HMR, no restart).
|
|
66
|
+
|
|
67
|
+
**Which doc has the details**
|
|
68
|
+
[02-local-preview-environment.md](https://github.com/Encaron/linkdesk/blob/electron/docs/02-Electron架构/E6_插件生态与发布/02-插件开发工具链/02-本地预览环境.md) — what the dev host is, why the author side needs zero configuration, and HMR's boundaries. This step **does not start the LinkDesk app**; it only runs the plugin's own preview host.
|
|
69
|
+
|
|
70
|
+
---
|
|
71
|
+
|
|
72
|
+
## Step 3: Write Your First Piece of UI
|
|
73
|
+
|
|
74
|
+
**What to do**
|
|
75
|
+
Edit the React component that is the `default export` in `src/index.tsx`. This is how the shell renders it:
|
|
76
|
+
|
|
77
|
+
```tsx
|
|
78
|
+
export default function HelloPlugin({ isActive }: { isActive: boolean }) { … }
|
|
79
|
+
```
|
|
80
|
+
|
|
81
|
+
- `isActive` = whether this tab currently has focus. **Under the keep-alive architecture all tabs stay mounted** — don't use `isActive` to blank out the whole content; it's only good for gating "effects that should run only while focused" (such as autosave or polling).
|
|
82
|
+
- `tabId` / `sourceId` = this tab's id / contextual data (editor-type plugins use `sourceId` to know which file the user opened).
|
|
83
|
+
|
|
84
|
+
**How to know you did it right**
|
|
85
|
+
The UI updates in the preview host as you edit. **And**: the UI has no bare hex colors and no hardcoded Chinese (use `t()`) — both are visible to the naked eye, and both are what `npm run lint` will catch later.
|
|
86
|
+
|
|
87
|
+
**Which docs have the details**
|
|
88
|
+
- View contract details → [05-ui-conventions](05-ui-conventions.md) (context menus/overlays/persistence/two keybinding tracks)
|
|
89
|
+
- Want it in the sidebar or the Bottom Panel → [08-view-container-api](08-view-container-api.md)
|
|
90
|
+
|
|
91
|
+
---
|
|
92
|
+
|
|
93
|
+
## Step 4: Call an API
|
|
94
|
+
|
|
95
|
+
**What to do**
|
|
96
|
+
To see what can follow `window.linkdesk.`, check the **cheatsheet** (45 namespaces / 242 methods, auto-generated from the contract):
|
|
97
|
+
|
|
98
|
+
- 👉 [plugin-sdk README §API cheatsheet](https://github.com/Encaron/linkdesk/blob/electron/packages/plugin-sdk/README.md#api-速查表)
|
|
99
|
+
- Full signatures and per-method notes → `node_modules/@linkdesk/contracts/linkdesk.d.ts` (your IDE can jump straight to it)
|
|
100
|
+
|
|
101
|
+
Example: read one setting and subscribe to a change.
|
|
102
|
+
|
|
103
|
+
```ts
|
|
104
|
+
const theme = await window.linkdesk.theme.getCurrent();
|
|
105
|
+
const dispose = window.linkdesk.configuration.onChange("my-plugin.greeting", (v) => { … });
|
|
106
|
+
```
|
|
107
|
+
|
|
108
|
+
**How to know you did it right**
|
|
109
|
+
If TypeScript compiles, it's right — the types for `window.linkdesk.*` come with the SDK (already wired up in `tsconfig.json`'s `types`), so **a misspelled method name or a wrong parameter type turns `tsc` red on the spot**. That's the free line of defense the contract gives authors.
|
|
110
|
+
|
|
111
|
+
**Which docs have the details**
|
|
112
|
+
- Which surfaces are available on which side (pool/shell), and what the `?` marking means → [01-plugin-api-contract §3 the single source of truth](01-plugin-api-contract.md)
|
|
113
|
+
- ⚠️ **Methods marked `°` in the cheatsheet** (contract `?`) are injected into only one preload, **and most are shell-side only** — your plugin runs in the pool, so check existence before calling them.
|
|
114
|
+
- How plugins pass data to each other → [07-plugin-to-plugin-communication](07-plugin-to-plugin-communication.md) (event broadcast / command invocation / data pipeline)
|
|
115
|
+
|
|
116
|
+
---
|
|
117
|
+
|
|
118
|
+
## Step 5: Declare Contribution Points (commands / menus / keybindings / settings / tabs / i18n)
|
|
119
|
+
|
|
120
|
+
**What to do**
|
|
121
|
+
Declare them in `contributes` in `plugin.json`. Commands, menu items, keybindings, settings, views, themes, i18n and title bar buttons **are all registered here**.
|
|
122
|
+
|
|
123
|
+
**How to know you did it right**
|
|
124
|
+
|
|
125
|
+
```bash
|
|
126
|
+
npm run validate # validates plugin.json: $schema / field legality / i18n files exist
|
|
127
|
+
```
|
|
128
|
+
|
|
129
|
+
No errors in the output means it passes. Declared a command → press `Ctrl+Shift+P` and you can find it in the command palette; declared a setting → the item appears on the settings page.
|
|
130
|
+
|
|
131
|
+
**Which docs have the details**
|
|
132
|
+
- Full syntax and examples for every contribution point → [03-contributes-spec](03-contributes-spec.md) (**the thickest doc; look up the point you need**)
|
|
133
|
+
- The meaning/type/default of every field → [06-plugin-json-spec](06-plugin-json-spec.md)
|
|
134
|
+
- The lifecycle (register→activate→run→uninstall) → [02-plugin-lifecycle](02-plugin-lifecycle.md)
|
|
135
|
+
|
|
136
|
+
---
|
|
137
|
+
|
|
138
|
+
## Step 6: Use Shared Components (don't build your own context menu)
|
|
139
|
+
|
|
140
|
+
**What to do**
|
|
141
|
+
|
|
142
|
+
```bash
|
|
143
|
+
npm i @linkdesk/ui
|
|
144
|
+
```
|
|
145
|
+
|
|
146
|
+
Controls like context menus, selects, and toggles come from the shared package — **glass/theme follow automatically**, no styling of your own.
|
|
147
|
+
|
|
148
|
+
**How to know you did it right**
|
|
149
|
+
Switch themes and your context menu's appearance follows (hand-made implementations usually don't). Repo hard constraint 3 is explicit: a hand-written context menu is a violation.
|
|
150
|
+
|
|
151
|
+
**Which doc has the details**
|
|
152
|
+
[05-ui-conventions](05-ui-conventions.md) + [19-component-cheatsheet](19-component-cheatsheet.md)
|
|
153
|
+
|
|
154
|
+
---
|
|
155
|
+
|
|
156
|
+
## Step 7: Install It into a Real LinkDesk to Verify
|
|
157
|
+
|
|
158
|
+
**What to do**
|
|
159
|
+
The preview host isn't the real shell after all. To confirm real-machine behavior (real serial port, real files, real windows):
|
|
160
|
+
|
|
161
|
+
```bash
|
|
162
|
+
npm run dev:real # = linkdesk-plugin-sdk dev --real
|
|
163
|
+
```
|
|
164
|
+
|
|
165
|
+
**How to know you did it right**
|
|
166
|
+
You can see your plugin in the LinkDesk app, behaving the same as in the preview. **One boundary to note**: an installed plugin runs the **prebuilt bundle**, so any source change requires a rebuild to take effect — that's not a bug, it's distribution discipline.
|
|
167
|
+
|
|
168
|
+
**Which doc has the details**
|
|
169
|
+
[04-author-real-machine-debug-loop.md](https://github.com/Encaron/linkdesk/blob/electron/docs/02-Electron架构/E6_插件生态与发布/02-插件开发工具链/04-作者真机调试环.md) — how the real-machine loop automates "rebuild + write directly", and why changing the bundle of an installed plugin doesn't count as a hot update.
|
|
170
|
+
|
|
171
|
+
---
|
|
172
|
+
|
|
173
|
+
## Step 8: Package It and Hand It to Others
|
|
174
|
+
|
|
175
|
+
**What to do**
|
|
176
|
+
|
|
177
|
+
```bash
|
|
178
|
+
npm run build
|
|
179
|
+
```
|
|
180
|
+
|
|
181
|
+
**How to know you did it right**
|
|
182
|
+
**One** `<pluginId>.linkdesk-plugin` single file (a zip) appears at the project root, plus an unpacked `dist/<pluginId>.linkdesk-plugin/` directory. Give that single file to someone else and they can install it.
|
|
183
|
+
|
|
184
|
+
⚠️ **Don't treat the source directory as the distribution vehicle** — the era of "copy the whole directory to install" is over. And once `plugin.json`'s `version` goes +1, you **must add a `## v<new version>(YYYY-MM-DD)` section to `CHANGELOG.md` in the same commit**, otherwise the plugin details page will show "No changelog provided for this version".
|
|
185
|
+
|
|
186
|
+
**Which docs have the details**
|
|
187
|
+
- Distribution format and install flow → [04-distribution-format](04-distribution-format.md)
|
|
188
|
+
- The byte-level format spec inside the zip → [01-plugin-standalone-build/02-linkdesk-plugin-format-spec.md](https://github.com/Encaron/linkdesk/blob/electron/docs/02-Electron架构/E6_插件生态与发布/01-插件独立构建/02-linkdesk-plugin格式规范.md)
|
|
189
|
+
- Rules for images/GIFs/videos in a README → [12-readme-media-contract](12-readme-media-contract.md)
|
|
190
|
+
|
|
191
|
+
---
|
|
192
|
+
|
|
193
|
+
## Step 9: List on the Marketplace
|
|
194
|
+
|
|
195
|
+
> 🔴 **First, clear up the most common misunderstanding: listing is "two steps", and `npm run publish` is only half of the first one.**
|
|
196
|
+
>
|
|
197
|
+
> | Step | What you do | Who can see it afterwards |
|
|
198
|
+
> |:--:|------|------|
|
|
199
|
+
> | **①** | `npm run publish` — publish to **your own** GitHub repo (Release asset + `marketplace.json` at the repo root) | **Only people who manually add your repo address as a "marketplace source".** Default users **can't see it** |
|
|
200
|
+
> | **②** | **Get your plugin into the official catalog** `Encaron/linkdesk-marketplace` (open a PR adding one entry to the catalog's `marketplace.json`) | **All users with default configuration** — this step is what "listing" really means |
|
|
201
|
+
>
|
|
202
|
+
> "I ran publish, so why can't I find it in the marketplace" = you're stuck on step two. Full story (including how to submit to the official catalog) → [04-distribution-format](04-distribution-format.md).
|
|
203
|
+
|
|
204
|
+
**What to do**
|
|
205
|
+
|
|
206
|
+
```bash
|
|
207
|
+
npm run publish # = linkdesk-plugin-sdk publish — step ①
|
|
208
|
+
```
|
|
209
|
+
|
|
210
|
+
**Prerequisite — the project must already be a git repo pushed to GitHub**
|
|
211
|
+
|
|
212
|
+
publish's target repo = your project's git remote `origin` (publishing to **your own** GitHub repo: Release asset + `marketplace.json` at the repo root; the multi-marketplace-source model). Before running it, use `git remote -v` to confirm origin points at your GitHub repo.
|
|
213
|
+
|
|
214
|
+
> ✅ **Current state (shipped 2026-09-14)**: the scaffold **already creates the git repo** (`main` branch + one initial commit, see step 1) ⇒ pushing to GitHub is **down to two commands**; the `git init` one from the three people usually mention is no longer needed:
|
|
215
|
+
>
|
|
216
|
+
> ```bash
|
|
217
|
+
> git remote add origin git@github.com:<you>/<repo>.git
|
|
218
|
+
> git push -u origin main
|
|
219
|
+
> ```
|
|
220
|
+
>
|
|
221
|
+
> When you still need to run `git init` yourself: you generated with `--no-git`, or the project was generated **inside another git repo** (in which case the scaffold deliberately skips creating a nested repo, following `cargo new` semantics).
|
|
222
|
+
|
|
223
|
+
**How to know you did it right**
|
|
224
|
+
Step one: your `.linkdesk-plugin` asset shows up on the GitHub Release. Step two: once your entry is in the official catalog, **on a clean machine (default configuration, no marketplace sources added)** it can be found in the marketplace, installed, and updated — that's the criterion for "listing complete".
|
|
225
|
+
|
|
226
|
+
**Which docs have the details**
|
|
227
|
+
- The full chain (local → GitHub → the user's machine) → [03-plugin-release-pipeline.md](https://github.com/Encaron/linkdesk/blob/electron/docs/02-Electron架构/E6_插件生态与发布/02-插件开发工具链/03-插件发布流水线.md)
|
|
228
|
+
- The end-to-end journey from an author's perspective → [05-docs-and-release/00-third-party-author-journey.md](https://github.com/Encaron/linkdesk/blob/electron/docs/02-Electron架构/E6_插件生态与发布/05-文档与发布/00-第三方作者旅程.md)
|
|
229
|
+
|
|
230
|
+
---
|
|
231
|
+
|
|
232
|
+
## Pitfalls Beginners Hit Most
|
|
233
|
+
|
|
234
|
+
| Symptom | Root cause | Where to look |
|
|
235
|
+
|---|---|---|
|
|
236
|
+
| When the theme switches, my UI colors don't follow | Hardcoded hex | Iron rule 2 · [00-readme](00-readme.md#hard-constraints--before-you-write-any-plugin-code) |
|
|
237
|
+
| Switch away from a tab and back: state is lost / content is empty | You conditionally rendered on `isActive` — under keep-alive it shouldn't unmount | [05-ui-conventions](05-ui-conventions.md) |
|
|
238
|
+
| After `npm run build` the installed plugin still behaves the old way | Installed plugins run the prebuilt bundle; source changes need a rebuild | Step 7 · [04-author-real-machine-debug-loop.md](https://github.com/Encaron/linkdesk/blob/electron/docs/02-Electron架构/E6_插件生态与发布/02-插件开发工具链/04-作者真机调试环.md) |
|
|
239
|
+
| The details page says "No changelog provided for this version" | The version went +1 but `CHANGELOG.md` didn't get a new section | Step 8 |
|
|
240
|
+
| The plugin details page description area is empty | The description comes from the `README.md` file, and **`plugin.json` has no `readme` field** | [09-plugin-directory-layout](09-plugin-directory-layout.md) · [06-plugin-json-spec](06-plugin-json-spec.md) |
|
|
241
|
+
| My context menu's styling doesn't match the shell | You hand-wrote the context menu | Step 6 · [05-ui-conventions](05-ui-conventions.md) |
|
|
242
|
+
| `import @src/core/xxx` errors out | That's shell-internal implementation; plugins must not import it | Iron rule 1 |
|
|
243
|
+
|
|
244
|
+
---
|
|
245
|
+
|
|
246
|
+
## Documentation Map (find it by what you're doing)
|
|
247
|
+
|
|
248
|
+
| What you want to do | Read this |
|
|
249
|
+
|---|---|
|
|
250
|
+
| **Know what APIs you can call** | [01-plugin-api-contract](01-plugin-api-contract.md) + [SDK README cheatsheet](https://github.com/Encaron/linkdesk/blob/electron/packages/plugin-sdk/README.md#api-速查表) |
|
|
251
|
+
| Look up **what a field means** | [06-plugin-json-spec](06-plugin-json-spec.md) + `plugin.schema.json` |
|
|
252
|
+
| Register **commands/menus/keybindings/settings/views/themes/i18n** | [03-contributes-spec](03-contributes-spec.md) |
|
|
253
|
+
| Understand **when a plugin is activated/uninstalled** | [02-plugin-lifecycle](02-plugin-lifecycle.md) |
|
|
254
|
+
| Pass data **between plugins** | [07-plugin-to-plugin-communication](07-plugin-to-plugin-communication.md) |
|
|
255
|
+
| **Sidebar/panel views**, adding things into someone else's container | [08-view-container-api](08-view-container-api.md) |
|
|
256
|
+
| A whole **replacement settings UI** | [10-building-a-settings-plugin](10-building-a-settings-plugin.md) |
|
|
257
|
+
| Build **themes/icons** | [11-authoring-themes](11-authoring-themes.md) |
|
|
258
|
+
| **Where files should go**; authoritative README/CHANGELOG criteria | [09-plugin-directory-layout](09-plugin-directory-layout.md) |
|
|
259
|
+
| The full documentation index | [00-readme §Documentation Index](00-readme.md#documentation-index) |
|