|
| 1 | +[English](./README.md) |
| 2 | + |
| 3 | +# 使用 vite + svelte 的思源笔记插件示例 |
| 4 | + |
| 5 | +1. 使用 vite 打包 |
| 6 | +2. 使用软链接、而不是把项目放到插件目录下的模式进行开发 |
| 7 | +3. 内置对 svelte 框架的支持 |
| 8 | +4. 提供一个github action 模板，能自动生成package.zip并上传到新版本中 |
| 9 | + |
| 10 | +## 开始 |
| 11 | + |
| 12 | +1. 通过 <kbd>Use this template</kbd> 按钮将该库文件复制到你自己的库中，请注意库名必须和插件名称一致，默认分支必须为 `main` |
| 13 | +2. 将你的库克隆到本地开发文件夹中 |
| 14 | + * 注意: 同 `plugin-sample` 不同, 本样例并不推荐直接把代码下载到 `{workspace}/data/plugins/` |
| 15 | +3. 创建开发需要的软链接 |
| 16 | + - 推荐使用软链接来链接你的工作目录和插件目录 |
| 17 | + - 如果你的设备安装了 python 环境，运行 `python scripts/make_dev_link.py <plugin_dir>` 命令，`<plugin_dir>`是插件目录的绝对路径，示例: |
| 18 | + ```powershell |
| 19 | + >>> sudo python . \scripts\make_dev_link.py "H:\SiYuanDevSpace\data\plugins" |
| 20 | + Symlink created: H:\SiYuanDevSpace\data\plugins\plugin-sample |
| 21 | + ``` |
| 22 | + - 可能需要使用管理员身份来运行这个命令。对 windows 用户来讲可以首先使用管理员身份打开控制台，然后再运行脚本。如果你的 windows 设备上安装了 scoop 等软件，可以安装 `scoop install sudo` 然后使用 sudo 命令来运行上面的程序 |
| 23 | + - 如果您的开发环境下没有安装 python，也可以自己手动创建软链接 |
| 24 | + - 首先手动在工作目录下创建 dev 目录 |
| 25 | + - windows 用户请使用 [mklink](https://learn.microsoft.com/windows-server/administration/windows-commands/mklink) 命令; unix 用户使用 ln 命令 |
| 26 | + - 注意：要确保软链接的名称和 plugin.json 中的 name 字段保持一致 |
| 27 | + 由于生成的软链接和 plugin name 相同，所以不要把工程目录放在 plugins 下（这一点和 plugin-sample 模板相反） |
| 28 | +
|
| 29 | +4. 安装 [NodeJS](https://nodejs.org/en/download) 和 [pnpm](https://pnpm.io/installation)，然后在开发文件夹下执行 `pnpm i` |
| 30 | +5. 执行 `pnpm run dev` 进行实时编译 |
| 31 | +6. 在思源中打开集市并在下载选项卡中启用插件 |
| 32 | +
|
| 33 | +
|
| 34 | +## 国际化 |
| 35 | +
|
| 36 | +国际化方面我们主要考虑的是支持多语言，具体需要完成以下工作： |
| 37 | +
|
| 38 | +* 插件自身的元信息，比如插件描述和自述文件 |
| 39 | + * plugin.json 中的 `description` 和 `readme` 字段，以及对应的 README*.md 文件 |
| 40 | +* 插件中使用的文本，比如按钮文字和提示信息 |
| 41 | + * src/i18n/*.json 语言配置文件 |
| 42 | + * 代码中使用 `this.i18.key` 获取文本 |
| 43 | +* 最后在 plugin.json 中的 `i18n` 字段中声明该插件支持的语言 |
| 44 | +
|
| 45 | +建议插件至少支持英文和简体中文，这样可以方便更多人使用。 |
| 46 | +
|
| 47 | +## plugin.json |
| 48 | +
|
| 49 | +```json |
| 50 | +{ |
| 51 | + "name": "plugin-sample-vite-svelte", |
| 52 | + "author": "frostime", |
| 53 | + "url": "https://github.com/siyuan-note/plugin-sample-vite-svelte", |
| 54 | + "version": "1.0.0", |
| 55 | + "displayName": { |
| 56 | + "en_US": "Plugin sample with vite and svelte", |
| 57 | + "zh_CN": "插件样例 vite + svelte 版" |
| 58 | + }, |
| 59 | + "description": { |
| 60 | + "en_US": "SiYuan plugin sample with vite and svelte", |
| 61 | + "zh_CN": "使用 vite 和 svelte 开发的思源插件样例" |
| 62 | + }, |
| 63 | + "readme": { |
| 64 | + "en_US": "README_en_US.md", |
| 65 | + "zh_CN": "README.md" |
| 66 | + }, |
| 67 | + "i18n": [ |
| 68 | + "en_US", |
| 69 | + "zh_CN" |
| 70 | + ], |
| 71 | + "funding": { |
| 72 | + "custom": [ |
| 73 | + "https://afdian.net/a/frostime" |
| 74 | + ] |
| 75 | + } |
| 76 | +} |
| 77 | +``` |
| 78 | + |
| 79 | +* `name`：插件名称，必须和库名一致，且全局唯一（集市中不能有重名插件） |
| 80 | +* `author`：插件作者名 |
| 81 | +* `url`：插件仓库地址 |
| 82 | +* `version`：插件版本号，建议遵循 [semver](https://semver.org/lang/zh-CN/) 规范 |
| 83 | +* `displayName`：模板显示名称，主要用于模板集市列表中显示，支持多语言 |
| 84 | + * `default`：默认语言，必须存在 |
| 85 | + * `zh_CN`、`en_US` 等其他语言：可选，建议至少提供中文和英文 |
| 86 | +* `description`：插件描述，主要用于插件集市列表中显示，支持多语言 |
| 87 | + * `default`：默认语言，必须存在 |
| 88 | + * `zh_CN`、`en_US` 等其他语言：可选，建议至少提供中文和英文 |
| 89 | +* `readme`：自述文件名，主要用于插件集市详情页中显示，支持多语言 |
| 90 | + * `default`：默认语言，必须存在 |
| 91 | + * `zh_CN`、`en_US` 等其他语言：可选，建议至少提供中文和英文 |
| 92 | +* `i18n`：插件支持的语言列表 |
| 93 | +* `funding`：插件赞助信息 |
| 94 | + * `openCollective`：Open Collective 名称 |
| 95 | + * `patreon`：Patreon 名称 |
| 96 | + * `github`：GitHub 登录名 |
| 97 | + * `custom`：自定义赞助链接列表 |
| 98 | + |
| 99 | +## 打包 |
| 100 | + |
| 101 | +无论使用何种方式编译打包，我们最终需要生成一个 package.zip，它至少包含如下文件： |
| 102 | + |
| 103 | +* icon.png |
| 104 | +* index.js |
| 105 | +* plugin.json |
| 106 | +* preview.png |
| 107 | +* README*.md |
| 108 | +* index.css (optional) |
| 109 | +* i18n/* (optional) |
| 110 | + |
| 111 | +## 上架集市 |
| 112 | + |
| 113 | +* 执行 `pnpm run build` 生成 package.zip |
| 114 | +* 在 GitHub 上创建一个新的发布，使用插件版本号作为 “Tag |
| 115 | + version”，示例 https://github.com/siyuan-note/plugin-sample/releases |
| 116 | +* 上传 package.zip 作为二进制附件 |
| 117 | +* 提交发布 |
| 118 | + |
| 119 | +如果是第一次发布版本，还需要创建一个 PR 到 [Community Bazaar](https://github.com/siyuan-note/bazaar) 社区集市仓库，修改该库的 |
| 120 | +plugins.json。该文件是所有社区插件库的索引，格式为： |
| 121 | + |
| 122 | +```json |
| 123 | +{ |
| 124 | + "repos": [ |
| 125 | + "username/reponame" |
| 126 | + ] |
| 127 | +} |
| 128 | +``` |
| 129 | + |
| 130 | +PR 被合并以后集市会通过 GitHub Actions 自动更新索引并部署。后续发布新版本插件时只需要按照上述步骤创建新的发布即可，不需要再 |
| 131 | +PR 社区集市仓库。 |
| 132 | + |
| 133 | +正常情况下，社区集市仓库每隔 1 小时会自动更新索引并部署，可在 https://github.com/siyuan-note/bazaar/actions 查看部署状态。 |
| 134 | + |
| 135 | +## 使用 Github action 自动发布 |
| 136 | + |
| 137 | +样例中自带了 github action，可以自动打包发布，请遵循以下操作： |
| 138 | + |
| 139 | +1. 设置项目 `https://github.com/OWNER/REPO/settings/actions` 页面向下划到 **Workflow Permissions**，打开配置 |
| 140 | + |
| 141 | +  |
| 142 | + |
| 143 | +2. 需要发布版本的时候，push 一个格式为 `v*` 的 tag，github 就会自动打包发布 release（包括 package.zip） |
| 144 | + |
| 145 | +3. 默认使用保守策略进行 pre-release 发布，如果觉得没有必要，可以更改 release.yml 中的设置： |
| 146 | + |
| 147 | + ```yaml |
| 148 | + - name: Release |
| 149 | + uses: ncipollo/release-action@v1 |
| 150 | + with: |
| 151 | + allowUpdates: true |
| 152 | + artifactErrorsFailBuild: true |
| 153 | + artifacts: 'package.zip' |
| 154 | + token: ${{ secrets.GITHUB_TOKEN }} |
| 155 | + prerelease: true # 把这个改为 false |
| 156 | + ``` |
| 157 | +
|
| 158 | +
|
0 commit comments