Skip to content

Commit 86fc5b3

Browse files
frostimefrostime
committedMay 19, 2023
README
·
v1.0.0v0.0.1
1 parent b4780ef commit 86fc5b3

File tree

4 files changed

+150
-53
lines changed

4 files changed

+150
-53
lines changed
 

‎README.md

+137-40
Original file line numberDiff line numberDiff line change
@@ -1,61 +1,158 @@
1-
# plugin-sample-vite-svelte
21

3-
SiYuan plugin sample with vite and svelte.
2+
# SiYuan plugin sample with vite and svelte
43

5-
## Introduction
4+
1. Using vite for packaging
5+
2. Use soft linking instead of putting the project into the plugins directory program development
6+
3. Built-in support for the svelte framework
7+
4. Provides a github action template to automatically generate package.zip and upload to new release
68

7-
This plugin is a community third-party plug-in development template, in addition to the official development template provides a basic level of functionality, has the following features:
89

9-
1. based on vite package project, support for hot-loading, in dev mode whether the code or i18n changes can be automatically tracked
10-
2. soft linking instead of putting the project into the plugins directory program development, you can feel free to develop multiple projects in the same workspace at the same time, and do not worry about accidentally deleting the project code in the source
11-
3. built-in support for the svelte framework, compared to react, vue and other virtual DOM-based solutions, svelte such compiled framework is more suitable for plug-in development of such lightweight scenarios
12-
4. provides a github action template to automatically generate package.zip and upload to new release
13-
5. pre-packaged siyuan.d.ts module, no need to manually replace the siyuan module under the node_module
14-
6. Provide with api.ts and sy-dtype.d.ts
10+
## Get started
1511

12+
1. Make a copy of this repo as a template with the Use this template button, please note that the repo name must be the same as the plugin name, the default branch must be main
1613

17-
## Template usage
18-
19-
1. Use Template
20-
21-
2. Clone to local
14+
2. Clone your repo to a local development folder at any place
15+
- Notice: we **don't recommand** you to place the folder under your {workspace}/data/plugins/ folder.
2216

2317
3. Create development soft links
2418

25-
- Create the dev directory
26-
- Run the ``scripts/make_dev_link.py`` script, passing in the absolute path to the plugins directory, e.g.
19+
- It is recommended to create a symbolic link between your development directory and the plugins directory.
20+
- If you have python environment in you device, run the command `python scripts/make_dev_link.py <plugin_dir>` script, `<plugin_dir>` is the absolute path to the plugins directory, e.g.
2721

2822
```powershell
29-
>> sudo python . \scripts\make_dev_link.py H:\temporary folder\SiYuanDevSpace\data\plugins
30-
Folder already exists, exit
23+
>>> sudo python . \scripts\make_dev_link.py "H:\SiYuanDevSpace\data\plugins"
24+
Symlink created: H:\SiYuanDevSpace\data\plugins\plugin-sample
3125
```
32-
33-
- You may need sudo to run it, I installed sudo myself on windows via scoop and can run it directly that way, normal windows users can first open the command line as administrator and then run it.
26+
- You may need to run it as administration, normal windows users can first open the command line as administrator and then run it. Or if you have scoop installed in you windows system, you install `scoop install sudo` and run with sudo.
3427
- If you haven't installed python in your environment, you can also manually make a soft link, reference to [mklink](https://learn.microsoft.com/windows-server/administration/windows-commands/mklink)
3528
- Notice: make sure that the name of soft link is same as the name in your plugin.json
36-
- As the generated softlink is the same as the plugin name, do not put the project directory under plugins (this is contrary to the official template)
37-
38-
4. development
39-
40-
- When pnpm dev mode is enabled, the code and i18n README plugin.json are automatically tracked and the compiled results are placed in the dev directory
41-
- The new version of SiYuan already allows soft links, so there is no need to put the project under plugin.
42-
43-
5. manual release (You can use github action instead)
44-
45-
- pnpm build, automatically generates package.zip
46-
47-
48-
## Github action
49-
50-
The github action is included and can be automatically packaged and published:
51-
52-
1. set the project `https://github.com/OWNER/REPO/settings/actions` page down to **Workflow Permissions** and open the configuration
29+
- As the generated softlink is the same as the plugin name, **do not put the project directory under plugins** (this is contrary to the webpack version)
30+
31+
4. Develope
32+
33+
- Install NodeJS and pnpm, then run pnpm i in the command line under your repo folder
34+
- Execute pnpm run dev for real-time compilation
35+
- Open SiYuan marketplace and enable plugin in downloaded tab
36+
37+
## I18n
38+
39+
In terms of internationalization, our main consideration is to support multiple languages. Specifically, we need to
40+
complete the following tasks:
41+
42+
* Meta information about the plugin itself, such as plugin description and readme
43+
* `description` and `readme` fields in plugin.json, and the corresponding README*.md file
44+
* Text used in the plugin, such as button text and tooltips
45+
* src/i18n/*.json language configuration files
46+
* Use `this.i18.key` to get the text in the code
47+
* Finally, declare the language supported by the plugin in the `i18n` field in plugin.json
48+
49+
It is recommended that the plugin supports at least English and Simplified Chinese, so that more people can use it more
50+
conveniently.
51+
52+
## plugin.json
53+
54+
```json
55+
{
56+
"name": "plugin-sample-vite-svelte",
57+
"author": "frostime",
58+
"url": "https://github.com/siyuan-note/plugin-sample-vite-svelte",
59+
"version": "1.0.0",
60+
"displayName": {
61+
"en_US": "Plugin sample with vite and svelte",
62+
"zh_CN": "插件样例 vite + svelte 版"
63+
},
64+
"description": {
65+
"en_US": "SiYuan plugin sample with vite and svelte",
66+
"zh_CN": "使用 vite 和 svelte 开发的思源插件样例"
67+
},
68+
"readme": {
69+
"en_US": "README_en_US.md",
70+
"zh_CN": "README.md"
71+
},
72+
"i18n": [
73+
"en_US",
74+
"zh_CN"
75+
],
76+
"funding": {
77+
"custom": [
78+
"https://afdian.net/a/frostime"
79+
]
80+
}
81+
}
82+
```
83+
84+
* `name`: Plugin name, must be the same as the repo name, and must be unique globally (no duplicate plugin names in the
85+
marketplace)
86+
* `author`: Plugin author name
87+
* `url`: Plugin repo URL
88+
* `version`: Plugin version number, it is recommended to follow the [semver](https://semver.org/) specification
89+
* `displayName`: Template display name, mainly used for display in the marketplace list, supports multiple languages
90+
* `default`: Default language, must exist
91+
* `zh_CN`, `en_US` and other languages: optional, it is recommended to provide at least Chinese and English
92+
* `description`: Plugin description, mainly used for display in the marketplace list, supports multiple languages
93+
* `default`: Default language, must exist
94+
* `zh_CN`, `en_US` and other languages: optional, it is recommended to provide at least Chinese and English
95+
* `readme`: readme file name, mainly used to display in the marketplace details page, supports multiple languages
96+
* `default`: Default language, must exist
97+
* `zh_CN`, `en_US` and other languages: optional, it is recommended to provide at least Chinese and English
98+
* `i18n`: Plugin supported language list
99+
* `funding`: Plugin sponsorship information
100+
* `openCollective`: Open Collective name
101+
* `patreon`: Patreon name
102+
* `github`: GitHub login name
103+
* `custom`: Custom sponsorship link list
104+
105+
## Package
106+
107+
No matter which method is used to compile and package, we finally need to generate a package.zip, which contains at
108+
least the following files:
109+
110+
* icon.png
111+
* index.js
112+
* plugin.json
113+
* preview.png
114+
* README*.md
115+
* index.css (optional)
116+
* i18n/* (optional)
117+
118+
## List on the marketplace
119+
120+
* `pnpm run build` to generate package.zip
121+
* Create a new GitHub release using your new version number as the "Tag version". See here for an
122+
example: https://github.com/siyuan-note/plugin-sample/releases
123+
* Upload the file package.zip as binary attachments
124+
* Publish the release
125+
126+
If it is the first release, please create a pull request to
127+
the [Community Bazaar](https://github.com/siyuan-note/bazaar) repository and modify the plugins.json file in it. This
128+
file is the index of all community plugin repositories, the format is:
129+
130+
```json
131+
{
132+
"repos": [
133+
"username/reponame"
134+
]
135+
}
136+
```
137+
138+
After the PR is merged, the bazaar will automatically update the index and deploy through GitHub Actions. When releasing
139+
a new version of the plugin in the future, you only need to follow the above steps to create a new release, and you
140+
don't need to PR the community bazaar repo.
141+
142+
Under normal circumstances, the community bazaar repo will automatically update the index and deploy every hour,
143+
and you can check the deployment status at https://github.com/siyuan-note/bazaar/actions.
144+
145+
## Use Github Action
146+
147+
The github action is included in this sample, you can use it to publish your new realse to marketplace automatically:
148+
149+
1. In your repo setting page `https://github.com/OWNER/REPO/settings/actions`, down to **Workflow Permissions** and open the configuration like this:
53150

54151
![](asset/action.png)
55152

56-
2. when you need to release a version, push a tag in the format `v*` and github will automatically release (including package.zip)
153+
2. Push a tag in the format `v*` and github will automatically create a new release with new bulit package.zip
57154

58-
3. use conservative pre-release by default, if you don't think this is necessary, change the settings in release.yml to
155+
3. By default, it will only publish a pre-release, if you don't think this is necessary, change the settings in release.yml
59156

60157
```yaml
61158
- name: Release

‎asset/action.png

41.3 KB
Loading

‎plugin.json

+6-6
Original file line numberDiff line numberDiff line change
@@ -1,15 +1,15 @@
11
{
2-
"name": "sy-plugin-template-vite",
2+
"name": "plugin-sample-vite-svelte",
33
"author": "frostime",
4-
"url": "https://github.com/frostime/sy-plugin-template-vite",
4+
"url": "https://github.com/siyuan-note/plugin-sample-vite-svelte",
55
"version": "1.0.0",
66
"displayName": {
7-
"en_US": "Plugin Template Vite Ver",
8-
"zh_CN": "插件开发模板-Vite版"
7+
"en_US": "Plugin sample with vite and svelte",
8+
"zh_CN": "插件样例 vite + svelte 版"
99
},
1010
"description": {
11-
"en_US": "This is a plugin development template based on vite, provided by community",
12-
"zh_CN": "这是一个基于 Vite 的插件开发模板, 由社区热心用户提供"
11+
"en_US": "SiYuan plugin sample with vite and svelte",
12+
"zh_CN": "使用 vite 和 svelte 开发的思源插件样例"
1313
},
1414
"readme": {
1515
"en_US": "README_en_US.md",

‎scripts/make_dev_link.py

+7-7
Original file line numberDiff line numberDiff line change
@@ -2,18 +2,18 @@
22
import json
33
from argparse import ArgumentParser
44

5-
# 1. 读取一个参数 plugin_dir
5+
# 1. Read plugin_dir
66
parser = ArgumentParser()
77
parser.add_argument('plugin_dir')
88
args = parser.parse_args()
99
plugin_dir = args.plugin_dir
1010

11-
# 2. 读取当前根目录下 plugin.json 的 name 字段
11+
# 2. Read name in plugin.json
1212
with open('plugin.json', 'r', encoding='utf-8') as f:
1313
content = json.load(f)
1414
name = content.get('name')
1515

16-
# ...如果 name 字段为空，报错并退出
16+
# ...error if name not found
1717
if not name or name == '':
1818
print('"name" in plugin.json not found, exit')
1919
exit()
@@ -22,11 +22,11 @@
2222
if not os.path.exists(dev_dir):
2323
os.mkdir(dev_dir)
2424

25-
# 3. 读取 plugin_dir 下的是否有和 name 字段相同的文件夹
26-
# ...如果没有，创建一个软链接到当前根目录下的 dev 文件夹
27-
# ...如果有，报错并退出
25+
# 3. Create symlink
2826
if not os.path.exists(os.path.join(plugin_dir, name)):
29-
os.symlink(dev_dir, os.path.join(plugin_dir, name))
27+
link = os.path.join(plugin_dir, name)
28+
os.symlink(dev_dir, link)
29+
print('Symlink created:', link)
3030
else:
3131
print('Folder already exists, exit')
3232
exit()

0 commit comments

Comments
 (0)
Please sign in to comment.