主题

清单文件

Example

{
    "$schema": "https://docs.siyuan-note.club/schemas/manifest/theme.schema.json",
    "name": "theme-sample",
    "author": "Vanessa",
    "url": "https://github.com/siyuan-note/theme-sample",
    "version": "0.0.3",
    "minAppVersion": "2.8.8",
    "displayName": {
        "default": "Theme Sample",
        "zh_CN": "主题示例"
    },
    "description": {
        "default": "This is a theme sample",
        "zh_CN": "这是一个主题示例"
    },
    "readme": {
        "default": "README.md",
        "zh_CN": "README_zh_CN.md"
    },
    "funding": {
        "openCollective": "",
        "patreon": "",
        "github": "",
        "custom": [
            "https://ld246.com/sponsor"
        ]
    },
    "modes": [
        "light"
    ]
}

Types

/**
 * Theme resource manifest file definition
 */
export interface ITheme {
    /**
     * The modes supported by the theme
     */
    readonly modes?: TMode[];
    /**
     * 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 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 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;
}

/**
 * The mode supported by the theme
 */
export type TMode = "dark" | "light";

JSON Schema (json5)

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

            properties: {
                modes: {
                    // 主题支持的模式
                    type: 'array',
                    description: 'The modes supported by the theme',
                    items: {
                        type: 'string',
                        title: 'TMode',
                        description: 'The mode supported by the theme',
                        enum: [
                            'light',
                            'dark',
                        ],
                    },
                },
            },
        },
        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/theme-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/theme.schema.json",
    "$comment": "v1.0.1",
    "$ref": "#/$defs/root",
    "$defs": {
        "root": {
            "title": "ITheme",
            "description": "Theme resource manifest file definition",
            "$ref": "#/$defs/base",
            "properties": {
                "modes": {
                    "type": "array",
                    "description": "The modes supported by the theme",
                    "items": {
                        "type": "string",
                        "title": "TMode",
                        "description": "The mode supported by the theme",
                        "enum": [
                            "light",
                            "dark"
                        ]
                    }
                }
            }
        },
        "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/theme-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：自定义赞助链接列表
• 附加字段
  • modes：主题支持的模式列表，可选值为 light 和 dark
    • light: 明亮模式
    • dark: 暗黑模式