|
| 1 | + |
| 2 | +# SiYuan plugin sample with vite |
| 3 | + |
| 4 | +[中文版](./README_zh_CN.md) |
| 5 | + |
| 6 | +> Consistent with [siyuan/plugin-sample](https://github.com/siyuan-note/plugin-sample) [v0.2.8](https://github.com/siyuan-note/plugin-sample/tree/v0.2.8) |
| 7 | +
|
| 8 | + |
| 9 | + |
| 10 | +1. Using vite for packaging |
| 11 | +2. Use symbolic linking instead of putting the project into the plugins directory program development |
| 12 | +3. Provides a github action template to automatically generate package.zip and upload to new release |
| 13 | + |
| 14 | + |
| 15 | +## Get started |
| 16 | + |
| 17 | +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` |
| 18 | + |
| 19 | +2. Clone your repo to a local development folder at any place |
| 20 | + - Notice: we **don't recommand** you to place the folder under your `{workspace}/data/plugins/` folder. |
| 21 | + |
| 22 | +3. Install NodeJS and pnpm, then run pnpm i in the command line under your repo folder |
| 23 | +4. **Auto create development symbolic links** |
| 24 | + - Make sure that SiYuan is running |
| 25 | + - Run `pnpm run make-link`, the script will detect all the siyuan workspace, please select the targe workspace and the script will automatically create the symbolic link under the `{workspace}/data/plugins/` folder |
| 26 | + ```bash |
| 27 | + >>> pnpm run make-link |
| 28 | + > [email protected] make-link H: \SrcCode \开源项目 \plugin-sample-vite |
| 29 | + > node --no-warnings ./scripts/make_dev_link.js |
| 30 | + |
| 31 | + "targetDir" is empty, try to get SiYuan directory automatically.... |
| 32 | + Got 2 SiYuan workspaces |
| 33 | + [0] H:\Media\SiYuan |
| 34 | + [1] H:\临时文件夹\SiYuanDevSpace |
| 35 | + Please select a workspace[0-1]: 0 |
| 36 | + Got target directory: H:\Media\SiYuan/data/plugins |
| 37 | + Done! Created symlink H:\Media\SiYuan/data/plugins/plugin-sample-vite-svelte |
| 38 | + ``` |
| 39 | +4. **Manually create development symbolic links** |
| 40 | + - Open `./scripts/make_dev_link.js` file, set `targetDir` to your SiYuan plugin directory `<siyuan workspace>/data/plugins` |
| 41 | + - Run `pnpm run make-link`, succeed if following message is shown: |
| 42 | + ```bash |
| 43 | + >>> pnpm run make-link |
| 44 | + > [email protected] make-link H:\SrcCode\plugin-sample-vite-svelte |
| 45 | + > node ./scripts/make_dev_link.js |
| 46 | +
|
| 47 | + Done! Created symlink H:/SiYuanDevSpace/data/plugins/plugin-sample-vite-svelte |
| 48 | + ``` |
| 49 | +5. **Create development symbolic links by using environment variable** |
| 50 | + - You can set environment variable `SIYUAN_PLUGIN_DIR` as `/data/plugins` |
| 51 | +6. Execute pnpm run dev for real-time compilation |
| 52 | +7. Open SiYuan marketplace and enable plugin in downloaded tab |
| 53 | +
|
| 54 | +> Notice: as the `make-link` script rely on the `fetch` function, please **ensure that at least version v18 of nodejs is installed** if you want to use make-link script. |
| 55 | +
|
| 56 | +## I18n |
| 57 | +
|
| 58 | +In terms of internationalization, our main consideration is to support multiple languages. Specifically, we need to |
| 59 | +complete the following tasks: |
| 60 | +
|
| 61 | +* Meta information about the plugin itself, such as plugin description and readme |
| 62 | + * `description` and `readme` fields in plugin.json, and the corresponding README*.md file |
| 63 | +* Text used in the plugin, such as button text and tooltips |
| 64 | + * src/i18n/*.json language configuration files |
| 65 | + * Use `this.i18.key` to get the text in the code |
| 66 | +
|
| 67 | +It is recommended that the plugin supports at least English and Simplified Chinese, so that more people can use it more |
| 68 | +conveniently. |
| 69 | +
|
| 70 | +## plugin.json |
| 71 | +
|
| 72 | +```json |
| 73 | +{ |
| 74 | + "name": "plugin-sample-vite-svelte", |
| 75 | + "author": "frostime", |
| 76 | + "url": "https://github.com/siyuan-note/plugin-sample-vite-svelte", |
| 77 | + "version": "0.1.3", |
| 78 | + "minAppVersion": "2.8.8", |
| 79 | + "backends": ["windows", "linux", "darwin"], |
| 80 | + "frontends": ["desktop"], |
| 81 | + "displayName": { |
| 82 | + "en_US": "Plugin sample with vite and svelte", |
| 83 | + "zh_CN": "插件样例 vite + svelte 版" |
| 84 | + }, |
| 85 | + "description": { |
| 86 | + "en_US": "SiYuan plugin sample with vite and svelte", |
| 87 | + "zh_CN": "使用 vite 和 svelte 开发的思源插件样例" |
| 88 | + }, |
| 89 | + "readme": { |
| 90 | + "en_US": "README_en_US.md", |
| 91 | + "zh_CN": "README.md" |
| 92 | + }, |
| 93 | + "funding": { |
| 94 | + "openCollective": "", |
| 95 | + "patreon": "", |
| 96 | + "github": "", |
| 97 | + "custom": [ |
| 98 | + "https://ld246.com/sponsor" |
| 99 | + ] |
| 100 | + }, |
| 101 | + "keywords": [ |
| 102 | + "sample", "示例" |
| 103 | + ] |
| 104 | +} |
| 105 | +``` |
| 106 | +
|
| 107 | +* `name`: Plugin name, must be the same as the repo name, and must be unique globally (no duplicate plugin names in the |
| 108 | + marketplace) |
| 109 | +* `author`: Plugin author name |
| 110 | +* `url`: Plugin repo URL |
| 111 | +* `version`: Plugin version number, it is recommended to follow the [semver](https://semver.org/) specification |
| 112 | +* `minAppVersion`: Minimum version number of SiYuan required to use this plugin |
| 113 | +* `backends`: Backend environment required by the plugin, optional values are `windows`, `linux`, `darwin`, `docker`, `android`, `ios` and `all` |
| 114 | + * `windows`: Windows desktop |
| 115 | + * `linux`: Linux desktop |
| 116 | + * `darwin`: macOS desktop |
| 117 | + * `docker`: Docker |
| 118 | + * `android`: Android APP |
| 119 | + * `ios`: iOS APP |
| 120 | + * `all`: All environments |
| 121 | +* `frontends`: Frontend environment required by the plugin, optional values are `desktop`, `desktop-window`, `mobile`, `browser-desktop`, `browser-mobile` and `all` |
| 122 | + * `desktop`: Desktop |
| 123 | + * `desktop-window`: Desktop window converted from tab |
| 124 | + * `mobile`: Mobile APP |
| 125 | + * `browser-desktop`: Desktop browser |
| 126 | + * `browser-mobile`: Mobile browser |
| 127 | + * `all`: All environments |
| 128 | +* `displayName`: Template display name, mainly used for display in the marketplace list, supports multiple languages |
| 129 | + * `default`: Default language, must exist |
| 130 | + * `zh_CN`, `en_US` and other languages: optional, it is recommended to provide at least Chinese and English |
| 131 | +* `description`: Plugin description, mainly used for display in the marketplace list, supports multiple languages |
| 132 | + * `default`: Default language, must exist |
| 133 | + * `zh_CN`, `en_US` and other languages: optional, it is recommended to provide at least Chinese and English |
| 134 | +* `readme`: readme file name, mainly used to display in the marketplace details page, supports multiple languages |
| 135 | + * `default`: Default language, must exist |
| 136 | + * `zh_CN`, `en_US` and other languages: optional, it is recommended to provide at least Chinese and English |
| 137 | +* `funding`: Plugin sponsorship information |
| 138 | + * `openCollective`: Open Collective name |
| 139 | + * `patreon`: Patreon name |
| 140 | + * `github`: GitHub login name |
| 141 | + * `custom`: Custom sponsorship link list |
| 142 | +* `keywords`: Search keyword list, used for marketplace search function |
| 143 | +
|
| 144 | +## Package |
| 145 | +
|
| 146 | +No matter which method is used to compile and package, we finally need to generate a package.zip, which contains at |
| 147 | +least the following files: |
| 148 | +
|
| 149 | +* i18n/* |
| 150 | +* icon.png (160*160) |
| 151 | +* index.css |
| 152 | +* index.js |
| 153 | +* plugin.json |
| 154 | +* preview.png (1024*768) |
| 155 | +* README*.md |
| 156 | +
|
| 157 | +## List on the marketplace |
| 158 | +
|
| 159 | +* `pnpm run build` to generate package.zip |
| 160 | +* Create a new GitHub release using your new version number as the "Tag version". See here for an |
| 161 | + example: https://github.com/siyuan-note/plugin-sample/releases |
| 162 | +* Upload the file package.zip as binary attachments |
| 163 | +* Publish the release |
| 164 | +
|
| 165 | +If it is the first release, please create a pull request to |
| 166 | +the [Community Bazaar](https://github.com/siyuan-note/bazaar) repository and modify the plugins.json file in it. This |
| 167 | +file is the index of all community plugin repositories, the format is: |
| 168 | +
|
| 169 | +```json |
| 170 | +{ |
| 171 | + "repos": [ |
| 172 | + "username/reponame" |
| 173 | + ] |
| 174 | +} |
| 175 | +``` |
| 176 | +
|
| 177 | +After the PR is merged, the bazaar will automatically update the index and deploy through GitHub Actions. When releasing |
| 178 | +a new version of the plugin in the future, you only need to follow the above steps to create a new release, and you |
| 179 | +don't need to PR the community bazaar repo. |
| 180 | +
|
| 181 | +Under normal circumstances, the community bazaar repo will automatically update the index and deploy every hour, |
| 182 | +and you can check the deployment status at https://github.com/siyuan-note/bazaar/actions. |
| 183 | +
|
| 184 | +## Use Github Action |
| 185 | +
|
| 186 | +The github action is included in this sample, you can use it to publish your new realse to marketplace automatically: |
| 187 | +
|
| 188 | +1. In your repo setting page `https://github.com/OWNER/REPO/settings/actions`, down to **Workflow Permissions** and open the configuration like this: |
| 189 | +
|
| 190 | +  |
| 191 | +
|
| 192 | +2. Push a tag in the format `v*` and github will automatically create a new release with new bulit package.zip |
| 193 | +
|
| 194 | +3. By default, it will only publish a pre-release, if you don't think this is necessary, change the settings in release.yml |
| 195 | +
|
| 196 | + ```yaml |
| 197 | + - name: Release |
| 198 | + uses: ncipollo/release-action@v1 |
| 199 | + with. |
| 200 | + allowUpdates: true |
| 201 | + artifactErrorsFailBuild: true |
| 202 | + artifacts: 'package.zip' |
| 203 | + token: ${{ secrets.GITHUB_TOKEN }} |
| 204 | + prerelease: true # change this to false |
| 205 | + ``` |
| 206 | +
|
| 207 | +
|
| 208 | +## How to remove svelte dependencies |
| 209 | +
|
| 210 | +> Pure vite without svelte: https://github.com/frostime/plugin-sample-vite |
| 211 | +
|
| 212 | +This plugin is packaged in vite and provides a dependency on the svelte framework. However, in practice some developers may not want to use svelte and only want to use the vite package. |
| 213 | +
|
| 214 | +In fact you can use this template without using svelte without any modifications at all. The compilation-related parts of the svelte compilation are loaded into the vite workflow as plugins, so even if you don't have svelte in your project, it won't matter much. |
| 215 | +
|
| 216 | +If you insist on removing all svelte dependencies so that they do not pollute your workspace, you can perform the following steps. 1. |
| 217 | +
|
| 218 | +1. delete the |
| 219 | + ```json |
| 220 | + { |
| 221 | + "@sveltejs/vite-plugin-svelte": "^2.0.3", |
| 222 | + "@tsconfig/svelte": "^4.0.1", |
| 223 | + "svelte": "^3.57.0" |
| 224 | + } |
| 225 | + ``` |
| 226 | +2. delete the `svelte.config.js` file |
| 227 | +3. delete the following line from the `vite.config.js` file |
| 228 | + - Line 6: `import { svelte } from "@sveltejs/vite-plugin-svelte"` |
| 229 | + - Line 20: `svelte(),` |
| 230 | +4. delete line 37 of `tsconfig.json` from `"svelte"` 5. |
| 231 | +5. re-run `pnpm i` |
0 commit comments