帮助文档授权协议插件开发规范主题开发规范数据导入 / 导出导航与友情链接文末版权 Vuecho 文档主题

RyeBlog 主题开发规范

本文档面向第三方开发者，介绍如何为 RyeBlog 开发自定义主题。

主题机制

RyeBlog 主题通过 CSS 变量覆盖实现换肤。系统内置三套主题（fresh / forest / mint），开发者可在 usr/theme/ 下创建自定义主题来覆盖 CSS 变量。

主题加载顺序

1. assets/css/themes.css   ← 内置主题变量定义（fresh/forest/mint）
2. assets/css/style.css    ← 核心布局样式
3. usr/theme/{主题名}/theme.css  ← 自定义主题覆盖（如果存在）

自定义主题的 theme.css 会作为最后一个 CSS 文件加载，优先级最高，可覆盖所有变量和样式。

目录结构

usr/theme/
└── your-theme/
    ├── theme.css          ← 主题样式文件（必需）
    ├── functions.php      ← 主题函数（可选，暂未启用）
    └── screenshot.png     ← 主题预览图（可选，用于后台展示）

theme.css 规范

元数据注释

文件头部使用 CSS 注释声明主题信息，后台通过正则解析：

/* ===========================================================
   RyeBlog 自定义主题 —— 主题名称
   @Title 主题名称
   @Desc  主题描述
   =========================================================== */

可覆盖的 CSS 变量

以下变量定义在 themes.css 中，可在自定义主题中覆盖：

| 变量 | 用途 | 示例值 | |------|------|--------| | --g-900 | 最深色（标题、强调） | #1b5e20 | | --g-700 | 深色（标题、链接） | #2e6b35 | | --g-600 | 中深色 | #357a3e | | --g-500 | 主色（按钮、高亮） | #43a047 | | --g-400 | 中色 | #66bb6a | | --g-300 | 中浅色 | #a5d6a7 | | --g-200 | 浅色（边框、背景） | #c8e6c9 | | --g-100 | 更浅色 | #e8f5e9 | | --g-050 | 最浅背景 | #f0f7f1 | | --g-025 | 极浅背景 | #f8fcf9 | | --ink | 正文文字色 | #2d3436 | | --muted | 次要文字色 | #636e72 | | --line | 分割线色 | #e0e0e0 | | --white | 白色背景 | #ffffff | | --shadow | 卡片阴影 | 0 2px 12px rgba(0,0,0,.06) | | --radius | 圆角 | 12px |

主题示例

/* ===========================================================
   RyeBlog 自定义主题 —— 暖橙风格
   @Title 暖橙主题
   @Desc  温暖的橙色调主题
   =========================================================== */

/* 覆盖绿色变量为暖橙色 */
.theme-fresh {
    --g-900: #bf360c;
    --g-700: #d84315;
    --g-600: #e64a19;
    --g-500: #ff6e40;
    --g-400: #ff8a65;
    --g-300: #ffab91;
    --g-200: #ffccbc;
    --g-100: #ffe0d0;
    --g-050: #fff3ee;
    --g-025: #fff8f5;
}

/* 自定义文章标题样式 */
.article h1 {
    border-bottom: 3px solid var(--g-500);
    padding-bottom: 12px;
}

/* 自定义链接颜色 */
a {
    color: var(--g-700);
}
a:hover {
    color: var(--g-900);
}

注意：自定义主题通过 .theme-{主题名} 类选择器覆盖变量。<body> 标签的 class 为 theme-{currentTheme()}，所以主题 CSS 需要用对应的类选择器。

主题命名规则

主题目录名仅使用字母、数字、下划线和连字符。
内置主题名 fresh / forest / mint 已被占用，自定义主题不可重名。
自定义主题如覆盖内置主题名（如 fresh），会通过 CSS 加载顺序覆盖内置变量。

ZIP 打包规范

将主题目录打包为 ZIP，ZIP 内应有一个顶层目录（即主题名）。
顶层目录内必须包含 theme.css。
示例结构：

`` my-theme.zip └── my-theme/ ├── theme.css └── screenshot.png ``

用户在后台「主题管理 → 上传安装」选择 ZIP 文件即可安装。

内置主题说明

| 主题名 | 说明 | |--------|------| | fresh | 清新绿（默认），柔和的青绿色调 | | forest | 深林绿，浓郁深绿色调 | | mint | 薄荷绿，清浅薄荷青绿 |

内置主题定义在 assets/css/themes.css 中，不可删除。

主题与 CSS 变量的关系

RyeBlog 的核心设计理念是"CSS 变量驱动换肤"：

themes.css 定义了三套内置主题的 CSS 变量。
style.css 中所有样式（颜色、边框、背景等）都引用这些变量。
切换主题时，<body> 的 class 变化，对应的 CSS 变量值变化，整站颜色即时切换。
自定义主题只需覆盖 CSS 变量值，无需重写全部样式。

这意味着自定义主题可以非常轻量 —— 只需定义 CSS 变量即可实现完全的视觉换肤。

主题开发建议

从覆盖变量开始：不要重写布局样式，先只覆盖颜色变量，效果最显著。
保持响应式：如需自定义布局，确保移动端适配。
使用 SVG 图标：RyeBlog 的元数据图标使用 CSS mask，会自动跟随 currentColor 着色。
测试所有页面：首页、文章页、分类页、标签页、搜索页、归档页、用户中心。
性能考虑：CSS 文件不宜过大，避免引入外部字体。