Home

Awesome

SiYuan plugin sample with vite

中文版

Consistent with siyuan/plugin-sample v0.3.5

  1. Using vite for packaging
  2. Use symbolic linking instead of putting the project into the plugins directory program development
  3. Provides a github action template to automatically generate package.zip and upload to new release

[!TIP] You can also use our maintained siyuan-plugin-cli command-line tool to directly build plugins in your local terminal.

Additionally, for the make-link related commands mentioned in this plugin, all future updates will be made in siyuan-plugin-cli.

The built-in make-link scripts may also be removed in a future version, in favor of using the siyuan-plugin-cli tool, aiming to simplify the workload of maintaining multiple plugin templates.

Get started

  1. Use the <kbd>Use this template</kbd> button to make a copy of this repo as a template. Note that the repository name should match the plugin name, and the default branch must be main.
  2. Clone your repository to the local development folder.
    • Note: Unlike plugin-sample, this example does not recommend directly downloading the code to {workspace}/data/plugins/.
  3. Install NodeJS and pnpm, then run pnpm i in the development folder to install the required dependencies.
  4. Run the pnpm run make-link command to create a symbolic link (Windows developers, please refer to the "make-link on Windows" section below).
  5. Execute pnpm run dev for real-time compilation.
  6. Open the marketplace in SiYuan and enable the plugin in the download tab.

Setting the Target Directory for the make-link Command

The make-link command creates a symbolic link that binds your dev directory to the SiYuan plugin directory. You can configure the target SiYuan workspace and create the symbolic link in three ways:

  1. Select Workspace

    • Open SiYuan, ensure the SiYuan kernel is running.
    • Run pnpm run make-link, the script will automatically detect all SiYuan workspaces, please manually enter the number to select the workspace. 
      >>> pnpm run make-link
> plugin-sample-vite@0.0.3 make-link H:\SrcCode\开源项目\plugin-sample-vite
> node  --no-warnings ./scripts/make_dev_link.js

"targetDir" is empty, try to get SiYuan directory automatically....
Got 2 SiYuan workspaces
[0] H:\Media\SiYuan
[1] H:\临时文件夹\SiYuanDevSpace
Please select a workspace[0-1]: 0
Got target directory: H:\Media\SiYuan/data/plugins
Done! Created symlink H:\Media\SiYuan/data/plugins/plugin-sample-vite-svelte

  2. Manually Configure Target Directory

    • Open the ./scripts/make_dev_link.js file, change targetDir to the SiYuan plugin directory <siyuan workspace>/data/plugins.
    • Run the pnpm run make-link command. If you see a message similar to the one below, it indicates successful creation:

  3. Set Environment Variable to Create Symbolic Link

    • Set the system environment variable SIYUAN_PLUGIN_DIR to the path workspace/data/plugins.

make-link on Windows

Due to SiYuan upgrading to Go 1.23, the old version of junction links cannot be recognized normally on Windows, so it has been changed to create dir symbolic links.

https://github.com/siyuan-note/siyuan/issues/12399

However, creating directory symbolic links on Windows using NodeJs may require administrator privileges. You have the following options:

  1. Run pnpm run make-link in a command line with administrator privileges.
  2. Configure Windows settings, enable developer mode in [System Settings - Update & Security - Developer Mode] then run pnpm run make-link.
  3. Run pnpm run make-link-win, this command will use a PowerShell script to request administrator privileges, requiring the system to enable PowerShell script execution permissions.

I18n

In terms of internationalization, our main consideration is to support multiple languages. Specifically, we need to complete the following tasks:

It is recommended that the plugin supports at least English and Simplified Chinese, so that more people can use it more conveniently.

plugin.json

{
  "name": "plugin-sample-vite-svelte",
  "author": "frostime",
  "url": "https://github.com/siyuan-note/plugin-sample-vite-svelte",
  "version": "0.1.3",
  "minAppVersion": "2.8.8",
  "backends": ["windows", "linux", "darwin"],
  "frontends": ["desktop"],
  "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"
  },
  "funding": {
    "openCollective": "",
    "patreon": "",
    "github": "",
    "custom": [
      "https://ld246.com/sponsor"
    ]
  },
  "keywords": [
    "sample", "示例"
  ]
}

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:

List on the marketplace

If it is the first release, please create a pull request to the Community Bazaar repository and modify the plugins.json file in it. This file is the index of all community plugin repositories, the format is:

{
  "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:

  2. Push a tag in the format v* and github will automatically create a new release with new bulit package.zip

  3. By default, it will only publish a pre-release, if you don't think this is necessary, change the settings in release.yml

    - name: Release
    uses: ncipollo/release-action@v1
    with.
        allowUpdates: true
        artifactErrorsFailBuild: true
        artifacts: 'package.zip'
        token: ${{ secrets.GITHUB_TOKEN }}
        prerelease: true # change this to false

Developer's Guide

Developers of SiYuan need to pay attention to the following specifications.

1. File Reading and Writing Specifications

If plugins or external extensions require direct reading or writing of files under the data directory, please use the kernel API to achieve this. Do not call fs or other electron or nodejs APIs directly, as it may result in data loss during synchronization and cause damage to cloud data.

Related APIs can be found at: /api/file/* (e.g., /api/file/getFile).

2. Daily Note Attribute Specifications

When creating a daily note in SiYuan, a custom-dailynote-yyyymmdd attribute will be automatically added to the document to distinguish it from regular documents.

For more details, please refer to Github Issue #9807.

Developers should pay attention to the following when developing the functionality to manually create Daily Notes: