插件

清单文件

Example

{
    "$schema": "https://docs.siyuan-note.club/schemas/manifest/plugin.schema.json",
    "name": "plugin-sample",
    "author": "Vanessa",
    "url": "https://github.com/siyuan-note/plugin-sample",
    "version": "0.2.7",
    "minAppVersion": "2.10.13",
    "keywords": [
        "sample",
        "示例"
    ],
    "backends": [
        "windows",
        "linux",
        "darwin"
    ],
    "frontends": [
        "desktop",
        "desktop-window"
    ],
    "displayName": {
        "default": "Plugin Sample",
        "zh_CN": "插件示例"
    },
    "description": {
        "default": "This is a plugin sample",
        "zh_CN": "这是一个插件示例"
    },
    "readme": {
        "default": "README.md",
        "zh_CN": "README_zh_CN.md"
    },
    "funding": {
        "openCollective": "",
        "patreon": "",
        "github": "",
        "custom": [
            "https://ld246.com/sponsor"
        ]
    }
}

Types

/**
 * Plugin resource manifest file definition
 */
export interface IPlugin {
    /**
     * The back-end environment list that the plugin is compatible with
     */
    readonly backends?: TBackEnd[];
    /**
     * The front-end environment list that the plugin is compatible with
     */
    readonly frontends?: TFrontEnd[];
    /**
     * The name of the author
     */
    readonly author: string;
    /**
     * The description of the resource
     */
    readonly description?: ILocalizedText;
    /**
     * The display name of the resource
     */
    readonly displayName?: ILocalizedText;
    /**
     * The funding of the resource
     */
    readonly funding?: IFunding;
    /**
     * The keywords of the resource used for search
     */
    readonly keywords?: string[];
    /**
     * The minimum version of SiYuan that the resource is compatible with
     */
    readonly minAppVersion?: string;
    /**
     * The name of the resource
     */
    readonly name: string;
    /**
     * The readme file name of the resource
     */
    readonly readme?: ILocalizedText;
    /**
     * The GitHub repository URL of the resource
     */
    readonly url: string;
    /**
     * The version of the resource
     */
    readonly version: string;
    [property: string]: any;
}

/**
 * The back-end environment that the plugin is compatible with
 */
export type TBackEnd = "all" | "android" | "darwin" | "docker" | "ios" | "linux" | "windows";

/**
 * The description of the resource
 *
 * Localize text fields
 *
 * The display name of the resource
 *
 * The readme file name of the resource
 */
export interface ILocalizedText {
    /**
     * The default text
     */
    readonly default: string;
    /**
     * The English text
     */
    readonly en_US?: string;
    /**
     * The Traditional Chinese text
     */
    readonly zh_CHT?: string;
    /**
     * The Simplified Chinese text
     */
    readonly zh_CN?: string;
    [property: string]: any;
}

/**
 * The front-end environment that the plugin is compatible with
 */
export type TFrontEnd = "all" | "browser-desktop" | "browser-mobile" | "desktop-window" | "desktop" | "mobile";

/**
 * The funding of the resource
 */
export interface IFunding {
    /**
     * The custom funding URLs
     */
    readonly custom?: string[];
    /**
     * The GitHub sponsors username, such as https://github.com/sponsors/<username>
     */
    readonly github?: string;
    /**
     * The Open Collective username, such as https://opencollective.com/<username>
     */
    readonly openCollective?: string;
    /**
     * The Patreon username, such as https://www.patreon.com/<username>
     */
    readonly patreon?: string;
}

JSON Schema (json5)

/**
 * 插件资源属性
 */
{
    $schema: 'https://json-schema.org/draft/2020-12/schema',
    $id: 'https://github.com/siyuan-community/siyuan-sdk/raw/main/schemas/manifest/plugin.schema.json5',
    $comment: 'v1.0.1',
    $ref: '#/$defs/root',
    $defs: {
        root: {
            // 插件资源清单文件定义
            title: 'IPlugin',
            description: 'Plugin resource manifest file definition',
            $ref: '#/$defs/base',

            properties: {
                backends: {
                    // 插件支持的后端环境列表
                    type: 'array',
                    description: 'The back-end environment list that the plugin is compatible with',
                    items: {
                        type: 'string',
                        title: 'TBackEnd',
                        description: 'The back-end environment that the plugin is compatible with',
                        enum: [
                            'all',
                            'windows',
                            'linux',
                            'darwin',
                            'docker',
                            'android',
                            'ios',
                        ],
                    },
                },
                frontends: {
                    // 插件支持的前端环境列表
                    type: 'array',
                    description: 'The front-end environment list that the plugin is compatible with',
                    items: {
                        type: 'string',
                        title: 'TFrontEnd',
                        description: 'The front-end environment that the plugin is compatible with',
                        enum: [
                            'all',
                            'desktop',
                            'desktop-window',
                            'mobile',
                            'browser-desktop',
                            'browser-mobile',
                        ],
                    },
                },
            },
        },
        base: {
            type: 'object',
            additionalProperties: true,
            required: [
                'author',
                'name',
                'url',
                'version',
            ],
            properties: {
                author: {
                    // 作者名
                    type: 'string',
                    description: 'The name of the author',
                },
                description: {
                    // 资源描述
                    description: 'The description of the resource',
                    $ref: '#/$defs/_localized_text_',
                },
                displayName: {
                    // 显示名称
                    description: 'The display name of the resource',
                    $ref: '#/$defs/_localized_text_',
                },
                funding: {
                    // 资助途径
                    type: 'object',
                    title: 'IFunding',
                    description: 'The funding of the resource',

                    additionalProperties: false,
                    required: [],
                    properties: {
                        custom: {
                            // 自定义捐助途径 URL
                            type: 'array',
                            description: 'The custom funding URLs',
                            items: {
                                type: 'string',
                                description: 'The custom funding URL',
                                format: 'uri',
                                examples: [
                                    'https://afdian.net/a/<username>', // 爱发电
                                    'https://ko-fi.com/<username>', // Ko-fi
                                    'https://tidelift.com/subscription/<platform-name>/<package-name>', // Tidelift
                                    'https://funding.communitybridge.org/projects/<project-name>', // Community Bridge
                                    'https://liberapay.com/<username>', // Liberapay
                                    'https://issuehunt.io/r/<username>', // IssueHunt
                                    'https://crowdfunding.lfx.linuxfoundation.org/projects/<project-name>', // LFX Crowdfunding
                                ],
                            },
                        },
                        github: {
                            // GitHub sponsors 用户名
                            type: 'string',
                            description: 'The GitHub sponsors username, such as https://github.com/sponsors/<username>',
                            examples: [
                                '88250',
                            ],
                        },
                        openCollective: {
                            // Open Collective 用户名
                            type: 'string',
                            description: 'The Open Collective username, such as https://opencollective.com/<username>',
                            examples: [
                                'siyuan',
                            ],
                        },
                        patreon: {
                            // Patreon 用户名
                            type: 'string',
                            description: 'The Patreon username, such as https://www.patreon.com/<username>',
                        },
                    },
                },
                keywords: {
                    // 用于搜索的关键词
                    type: 'array',
                    description: 'The keywords of the resource used for search',
                    items: {
                        type: 'string',
                        description: 'The keyword used for search',
                    },
                },
                minAppVersion: {
                    // 兼容的最低思源版本
                    type: 'string',
                    description: 'The minimum version of SiYuan that the resource is compatible with',
                    pattern: '^(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\\.(0|[1-9]\\d*)$',
                },
                name: {
                    // 资源名称
                    type: 'string',
                    description: 'The name of the resource',
                    pattern: '^[^\\\\/:*?"<>|. ][^\\\\/:*?"<>|]*[^\\\\/:*?"<>|. ]$',
                },
                readme: {
                    // 资源说明文档名称
                    description: 'The readme file name of the resource',
                    $ref: '#/$defs/_localized_text_',
                },
                url: {
                    // 资源仓库地址
                    type: 'string',
                    description: 'The GitHub repository URL of the resource',
                    format: 'uri',
                    examples: [
                        'https://github.com/siyuan-note/plugin-sample',
                    ],
                },
                version: {
                    // 资源版本号
                    type: 'string',
                    description: 'The version of the resource',
                    // REF: https://semver.org/#is-there-a-suggested-regular-expression-regex-to-check-a-semver-string
                    pattern: '^(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\\.(0|[1-9]\\d*)(?:-((?:0|[1-9]\\d*|\\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\\.(?:0|[1-9]\\d*|\\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\\+([0-9a-zA-Z-]+(?:\\.[0-9a-zA-Z-]+)*))?$',
                },
            },
        },
        _localized_text_: {
            // 本地化文本
            type: 'object',
            title: 'ILocalizedText',
            description: 'Localize text fields',

            additionalProperties: true,
            required: [
                'default',
            ],
            properties: {
                default: {
                    // 默认文本
                    type: 'string',
                    description: 'The default text',
                },
                en_US: {
                    // 英文文本
                    type: 'string',
                    description: 'The English text',
                },
                zh_CHT: {
                    // 繁体中文文本
                    type: 'string',
                    description: 'The Traditional Chinese text',
                },
                zh_CN: {
                    // 简体中文文本
                    type: 'string',
                    description: 'The Simplified Chinese text',
                },
            },
        },
    },
}

JSON Schema (json)

{
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "$id": "https://github.com/siyuan-community/siyuan-sdk/raw/main/schemas/manifest/plugin.schema.json",
    "$comment": "v1.0.1",
    "$ref": "#/$defs/root",
    "$defs": {
        "root": {
            "title": "IPlugin",
            "description": "Plugin resource manifest file definition",
            "$ref": "#/$defs/base",
            "properties": {
                "backends": {
                    "type": "array",
                    "description": "The back-end environment list that the plugin is compatible with",
                    "items": {
                        "type": "string",
                        "title": "TBackEnd",
                        "description": "The back-end environment that the plugin is compatible with",
                        "enum": [
                            "all",
                            "windows",
                            "linux",
                            "darwin",
                            "docker",
                            "android",
                            "ios"
                        ]
                    }
                },
                "frontends": {
                    "type": "array",
                    "description": "The front-end environment list that the plugin is compatible with",
                    "items": {
                        "type": "string",
                        "title": "TFrontEnd",
                        "description": "The front-end environment that the plugin is compatible with",
                        "enum": [
                            "all",
                            "desktop",
                            "desktop-window",
                            "mobile",
                            "browser-desktop",
                            "browser-mobile"
                        ]
                    }
                }
            }
        },
        "base": {
            "type": "object",
            "additionalProperties": true,
            "required": [
                "author",
                "name",
                "url",
                "version"
            ],
            "properties": {
                "author": {
                    "type": "string",
                    "description": "The name of the author"
                },
                "description": {
                    "description": "The description of the resource",
                    "$ref": "#/$defs/_localized_text_"
                },
                "displayName": {
                    "description": "The display name of the resource",
                    "$ref": "#/$defs/_localized_text_"
                },
                "funding": {
                    "type": "object",
                    "title": "IFunding",
                    "description": "The funding of the resource",
                    "additionalProperties": false,
                    "required": [],
                    "properties": {
                        "custom": {
                            "type": "array",
                            "description": "The custom funding URLs",
                            "items": {
                                "type": "string",
                                "description": "The custom funding URL",
                                "format": "uri",
                                "examples": [
                                    "https://afdian.net/a/<username>",
                                    "https://ko-fi.com/<username>",
                                    "https://tidelift.com/subscription/<platform-name>/<package-name>",
                                    "https://funding.communitybridge.org/projects/<project-name>",
                                    "https://liberapay.com/<username>",
                                    "https://issuehunt.io/r/<username>",
                                    "https://crowdfunding.lfx.linuxfoundation.org/projects/<project-name>"
                                ]
                            }
                        },
                        "github": {
                            "type": "string",
                            "description": "The GitHub sponsors username, such as https://github.com/sponsors/<username>",
                            "examples": [
                                "88250"
                            ]
                        },
                        "openCollective": {
                            "type": "string",
                            "description": "The Open Collective username, such as https://opencollective.com/<username>",
                            "examples": [
                                "siyuan"
                            ]
                        },
                        "patreon": {
                            "type": "string",
                            "description": "The Patreon username, such as https://www.patreon.com/<username>"
                        }
                    }
                },
                "keywords": {
                    "type": "array",
                    "description": "The keywords of the resource used for search",
                    "items": {
                        "type": "string",
                        "description": "The keyword used for search"
                    }
                },
                "minAppVersion": {
                    "type": "string",
                    "description": "The minimum version of SiYuan that the resource is compatible with",
                    "pattern": "^(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\\.(0|[1-9]\\d*)$"
                },
                "name": {
                    "type": "string",
                    "description": "The name of the resource",
                    "pattern": "^[^\\\\/:*?\"<>|. ][^\\\\/:*?\"<>|]*[^\\\\/:*?\"<>|. ]$"
                },
                "readme": {
                    "description": "The readme file name of the resource",
                    "$ref": "#/$defs/_localized_text_"
                },
                "url": {
                    "type": "string",
                    "description": "The GitHub repository URL of the resource",
                    "format": "uri",
                    "examples": [
                        "https://github.com/siyuan-note/plugin-sample"
                    ]
                },
                "version": {
                    "type": "string",
                    "description": "The version of the resource",
                    "pattern": "^(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\\.(0|[1-9]\\d*)(?:-((?:0|[1-9]\\d*|\\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\\.(?:0|[1-9]\\d*|\\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\\+([0-9a-zA-Z-]+(?:\\.[0-9a-zA-Z-]+)*))?$"
                }
            }
        },
        "_localized_text_": {
            "type": "object",
            "title": "ILocalizedText",
            "description": "Localize text fields",
            "additionalProperties": true,
            "required": [
                "default"
            ],
            "properties": {
                "default": {
                    "type": "string",
                    "description": "The default text"
                },
                "en_US": {
                    "type": "string",
                    "description": "The English text"
                },
                "zh_CHT": {
                    "type": "string",
                    "description": "The Traditional Chinese text"
                },
                "zh_CN": {
                    "type": "string",
                    "description": "The Simplified Chinese text"
                }
            }
        }
    }
}

• 基础字段
  • name：插件名称，必须全局唯一（集市中不能有同名插件）
  • author：插件作者名
  • url：插件仓库地址
  • version：插件版本号，建议遵循 semver 规范
  • minAppVersion：插件支持的最低思源笔记版本号
  • keywords: 用于在集市中搜索的关键词列表
  • displayName：模板显示名称，主要用于模板集市列表中显示，支持多语言
    • default：默认语言，必须存在
    • zh_CN、en_US 等其他语言：可选，建议至少提供中文和英文
  • description：插件描述，主要用于插件集市列表中显示，支持多语言
    • default：默认语言，必须存在
    • zh_CN、en_US 等其他语言：可选，建议至少提供中文和英文
  • readme：自述文件名，主要用于插件集市详情页中显示，支持多语言
    • default：默认语言，必须存在
    • zh_CN、en_US 等其他语言：可选，建议至少提供中文和英文
  • funding：插件赞助信息
    • openCollective：Open Collective 名称
    • patreon：Patreon 名称
    • github：GitHub 用户名
    • custom：自定义赞助链接列表
• 附加字段
  • backends：插件兼容的后端环境列表，可选值为 windows, linux, darwin, docker, android, ios 与 all
    • windows：Windows 桌面端
    • linux：Linux 桌面端
    • darwin：macOS 桌面端
    • docker：Docker 端
    • android：Android 端
    • ios：iOS 端
    • all：所有环境
  • frontends：插件兼容的前端环境列表，可选值为 desktop, desktop-window, mobile, browser-desktop, browser-mobile 与 all
    • desktop：桌面端
    • desktop-window：桌面端页签转换的独立窗口
    • mobile：移动端
    • browser-desktop：桌面端浏览器
    • browser-mobile：移动端浏览器
    • all：所有环境