joplin-plugin-writer

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Joplin Plugin Writer

Joplin 插件编写指南

Overview

概述

Implement Joplin plugins with a reliable flow from idea to runnable build. Use official docs first, then produce code, manifest updates, and validation steps.

遵循从想法到可运行构建的可靠流程来开发Joplin插件。优先参考官方文档，然后生成代码、更新清单并执行验证步骤。

Workflow

工作流程

Clarify plugin type and target. Gather target platform (
```
desktop
```
or
```
desktop+mobile
```
), core user action, UI surface (command, panel, toolbar, editor content script), and expected trigger.
Bootstrap or inspect the project. For a new plugin, scaffold with:

bash

npm install -g yo generator-joplin
yo joplin

For an existing plugin, inspect

src/index.ts

src/manifest.json

plugin.config.json

, and

webpack.config.js

Implement with the official plugin lifecycle. Always register through
```
joplin.plugins.register({ onStart: async () => {} })
```
. Place command/view/content-script wiring in
```
onStart
```
. Treat handlers and API calls as async.
Choose the integration pattern. If the feature targets note/workspace behavior, use
```
joplin.workspace
```
,
```
joplin.commands
```
,
```
joplin.views
```
. If the feature targets editor behavior, use content scripts and choose CodeMirror strategy:

Prefer CodeMirror 6 plugin flow for modern Joplin.
Add dual CM5+CM6 scripts only when explicit backward compatibility is required.
Keep CM packages externalized to avoid duplicate-instance runtime issues.

Keep manifest and packaging correct. Update
```
src/manifest.json
```
with accurate
```
app_min_version
```
,
```
platforms
```
, metadata, and assets. Build with
```
npm run dist
```
so runtime artifacts are available under
```
dist/
```
and publish output under
```
publish/
```
.
Run and verify in Development Mode. Launch Joplin in Development Mode, point "Development plugins" to plugin root, restart fully, and validate:

Plugin loads without errors
Core command/view behavior works
Console/log output is clean

Debug with directed checks. For loading failures, check compiled entry and load paths (
```
dist/index.js
```
and plugin directory selection). For editor issues, verify CM6/CM5 compatibility branch and content script registration IDs. For mobile/web behavior, follow mobile debugging flow and ensure
```
platforms
```
contains
```
mobile
```
when needed.

明确插件类型与目标。收集目标平台（
```
desktop
```
或
```
desktop+mobile
```
）、核心用户操作、UI载体（命令、面板、工具栏、编辑器内容脚本）以及预期触发方式。
初始化或检查项目。如果是新插件，使用以下命令搭建脚手架：

bash

npm install -g yo generator-joplin
yo joplin

如果是现有插件，检查

src/index.ts

、

src/manifest.json

、

plugin.config.json

和

webpack.config.js

文件。

遵循官方插件生命周期实现功能。始终通过
```
joplin.plugins.register({ onStart: async () => {} })
```
进行注册。将命令/视图/内容脚本的关联逻辑放在
```
onStart
```
方法中。将处理器和API调用视为异步操作。
选择集成模式。如果功能针对笔记/工作区行为，使用
```
joplin.workspace
```
、
```
joplin.commands
```
、
```
joplin.views
```
。如果功能针对编辑器行为，使用内容脚本并选择CodeMirror策略：

对于现代Joplin，优先使用CodeMirror 6插件流程。
仅当明确需要向后兼容时，才添加CM5+CM6双版本脚本。
保持CM包外部化，以避免运行时出现重复实例问题。

确保清单与打包正确无误。更新
```
src/manifest.json
```
，填入准确的
```
app_min_version
```
、
```
platforms
```
、元数据和资源信息。使用
```
npm run dist
```
命令构建，使运行时产物存放在
```
dist/
```
目录下，发布输出存放在
```
publish/
```
目录下。
在开发模式下运行并验证。启动Joplin开发模式，将「开发插件」指向插件根目录，完全重启后验证：

插件加载无错误
核心命令/视图功能正常工作
控制台/日志输出无异常

针对性调试检查。对于加载失败问题，检查编译后的入口文件和加载路径（
```
dist/index.js
```
和插件目录选择）。对于编辑器问题，验证CM6/CM5兼容分支和内容脚本注册ID。对于移动端/网页端行为，遵循移动端调试流程，并确保在需要时
```
platforms
```
包含
```
mobile
```
。

Implementation Rules

实现规则

Read
```
references/official-docs-index.md
```
first and load only the minimum relevant section.
Keep generated code TypeScript-first unless the repository is clearly JavaScript-only.
Modify existing plugin structure instead of rewriting whole files when possible.
Preserve user/plugin IDs and public command names unless migration is explicitly requested.
Explain manifest-impacting changes (ID/version/platforms/min-version) before finalizing.
Prefer incremental commits: scaffold, core feature, polish/fix, docs update.

首先阅读
```
references/official-docs-index.md
```
，仅加载最相关的部分。
除非仓库明确为纯JavaScript项目，否则优先使用TypeScript生成代码。
尽可能修改现有插件结构，而非重写整个文件。
保留用户/插件ID和公共命令名称，除非明确要求迁移。
在最终确定前，说明影响清单的变更（ID/版本/平台/最低版本）。
优先采用增量提交：搭建脚手架、核心功能、优化/修复、文档更新。

Task Playbooks

任务手册

New Plugin From Requirement

从需求创建新插件

Convert requirement into one primary user interaction.
Scaffold with
```
yo joplin
```
.
Implement minimum viable command/panel/content script.
Update manifest metadata.
Build and run in Development Mode.
Return install/run steps and known limitations.

将需求转化为一个核心用户交互场景。
使用
```
yo joplin
```
搭建脚手架。
实现最小可行的命令/面板/内容脚本。
更新清单元数据。
在开发模式下构建并运行。
返回安装/运行步骤和已知限制。

Feature Upgrade In Existing Plugin

现有插件功能升级

Identify extension points in existing
```
onStart
```
registration.
Add feature with minimal API surface change.
Keep compatibility with existing settings and data where possible.
Validate build and runtime regressions.

在现有
```
onStart
```
注册中确定扩展点。
以最小化API变更的方式添加功能。
尽可能保持与现有设置和数据的兼容性。
验证构建和运行时是否存在回归问题。

Debugging and Fixes

调试与修复

Reproduce in Development Mode.
Triage by category: load-time, API/runtime, editor-content-script, packaging.
Apply smallest fix with clear reason.
Rebuild and re-test.

在开发模式下复现问题。
按类别分类：加载时错误、API/运行时错误、编辑器内容脚本错误、打包错误。
应用最小化修复并说明明确原因。
重新构建并测试。

References

参考资料

Use

references/official-docs-index.md

for direct links and focused loading guidance.

使用

references/official-docs-index.md

获取直接链接和聚焦加载指南。