massivebox/siyuan-jsdraw-plugin
massivebox/siyuan-jsdraw-plugin
2
1
Fork 0
forked from mirrors/plugin-sample-vite-svelte
Code Issues 4 Pull requests Projects 3 Releases 7 Packages Wiki Activity Actions

README

Browse source
This commit is contained in:
frostime 2023-05-19 20:18:04 +08:00
parent b4780ef47e
commit 86fc5b3595
4 changed files with 142 additions and 45 deletions
Download patch file Download diff file Expand all files Collapse all files

161
README.md
View file

@ -1,61 +1,158 @@
# plugin-sample-vite-svelte
SiYuan plugin sample with vite and svelte.
# SiYuan plugin sample with vite and svelte
## Introduction
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:
1. based on vite package project, support for hot-loading, in dev mode whether the code or i18n changes can be automatically tracked
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
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
4. provides a github action template to automatically generate package.zip and upload to new release
5. pre-packaged siyuan.d.ts module, no need to manually replace the siyuan module under the node_module
6. Provide with api.ts and sy-dtype.d.ts
1. Using vite for packaging
2. Use soft linking instead of putting the project into the plugins directory program development
3. Built-in support for the svelte framework
4. Provides a github action template to automatically generate package.zip and upload to new release
## Template usage
## Get started
1. Use Template
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
2. Clone to local
2. Clone your repo to a local development folder at any place
- Notice: we **don't recommand** you to place the folder under your {workspace}/data/plugins/ folder.
3. Create development soft links
- Create the dev directory
- Run the ``scripts/make_dev_link.py`` script, passing in the absolute path to the plugins directory, e.g.
- It is recommended to create a symbolic link between your development directory and the plugins directory.
- 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.
```powershell
>> sudo python . \scripts\make_dev_link.py H:\temporary folder\SiYuanDevSpace\data\plugins
Folder already exists, exit
>>> sudo python . \scripts\make_dev_link.py "H:\SiYuanDevSpace\data\plugins"
Symlink created: H:\SiYuanDevSpace\data\plugins\plugin-sample
```
- 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.
- 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.
- 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)
- Notice: make sure that the name of soft link is same as the name in your plugin.json
- 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)
- 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)
4. development
4. Develope
- 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
- The new version of SiYuan already allows soft links, so there is no need to put the project under plugin.
- Install NodeJS and pnpm, then run pnpm i in the command line under your repo folder
- Execute pnpm run dev for real-time compilation
- Open SiYuan marketplace and enable plugin in downloaded tab
5. manual release (You can use github action instead)
## I18n
- pnpm build, automatically generates package.zip
In terms of internationalization, our main consideration is to support multiple languages. Specifically, we need to
complete the following tasks:
* Meta information about the plugin itself, such as plugin description and readme
* `description` and `readme` fields in plugin.json, and the corresponding README*.md file
* Text used in the plugin, such as button text and tooltips
* src/i18n/*.json language configuration files
* Use `this.i18.key` to get the text in the code
* Finally, declare the language supported by the plugin in the `i18n` field in plugin.json
## Github action
It is recommended that the plugin supports at least English and Simplified Chinese, so that more people can use it more
conveniently.
The github action is included and can be automatically packaged and published:
## plugin.json
1. set the project `https://github.com/OWNER/REPO/settings/actions` page down to **Workflow Permissions** and open the configuration
```json
{
"name": "plugin-sample-vite-svelte",
"author": "frostime",
"url": "https://github.com/siyuan-note/plugin-sample-vite-svelte",
"version": "1.0.0",
"displayName": {
"en_US": "Plugin sample with vite and svelte",
"zh_CN": "插件样例 vite + svelte 版"
},
"description": {
"en_US": "SiYuan plugin sample with vite and svelte",
"zh_CN": "使用 vite 和 svelte 开发的思源插件样例"
},
"readme": {
"en_US": "README_en_US.md",
"zh_CN": "README.md"
},
"i18n": [
"en_US",
"zh_CN"
],
"funding": {
"custom": [
"https://afdian.net/a/frostime"
]
}
}
```
* `name`: Plugin name, must be the same as the repo name, and must be unique globally (no duplicate plugin names in the
marketplace)
* `author`: Plugin author name
* `url`: Plugin repo URL
* `version`: Plugin version number, it is recommended to follow the [semver](https://semver.org/) specification
* `displayName`: Template display name, mainly used for display in the marketplace list, supports multiple languages
* `default`: Default language, must exist
* `zh_CN`, `en_US` and other languages: optional, it is recommended to provide at least Chinese and English
* `description`: Plugin description, mainly used for display in the marketplace list, supports multiple languages
* `default`: Default language, must exist
* `zh_CN`, `en_US` and other languages: optional, it is recommended to provide at least Chinese and English
* `readme`: readme file name, mainly used to display in the marketplace details page, supports multiple languages
* `default`: Default language, must exist
* `zh_CN`, `en_US` and other languages: optional, it is recommended to provide at least Chinese and English
* `i18n`: Plugin supported language list
* `funding`: Plugin sponsorship information
* `openCollective`: Open Collective name
* `patreon`: Patreon name
* `github`: GitHub login name
* `custom`: Custom sponsorship link list
## Package
No matter which method is used to compile and package, we finally need to generate a package.zip, which contains at
least the following files:
* icon.png
* index.js
* plugin.json
* preview.png
* README*.md
* index.css (optional)
* i18n/* (optional)
## List on the marketplace
* `pnpm run build` to generate package.zip
* Create a new GitHub release using your new version number as the "Tag version". See here for an
example: https://github.com/siyuan-note/plugin-sample/releases
* Upload the file package.zip as binary attachments
* Publish the release
If it is the first release, please create a pull request to
the [Community Bazaar](https://github.com/siyuan-note/bazaar) repository and modify the plugins.json file in it. This
file is the index of all community plugin repositories, the format is:
```json
{
"repos": [
"username/reponame"
]
}
```
After the PR is merged, the bazaar will automatically update the index and deploy through GitHub Actions. When releasing
a new version of the plugin in the future, you only need to follow the above steps to create a new release, and you
don't need to PR the community bazaar repo.
Under normal circumstances, the community bazaar repo will automatically update the index and deploy every hour,
and you can check the deployment status at https://github.com/siyuan-note/bazaar/actions.
## Use Github Action
The github action is included in this sample, you can use it to publish your new realse to marketplace automatically:
1. In your repo setting page `https://github.com/OWNER/REPO/settings/actions`, down to **Workflow Permissions** and open the configuration like this:
![](asset/action.png)
2. when you need to release a version, push a tag in the format `v*` and github will automatically release (including package.zip)
2. Push a tag in the format `v*` and github will automatically create a new release with new bulit package.zip
3. use conservative pre-release by default, if you don't think this is necessary, change the settings in release.yml to
3. By default, it will only publish a pre-release, if you don't think this is necessary, change the settings in release.yml
```yaml
- name: Release