mirror of
https://github.com/lutinglt/gitea-github-theme.git
synced 2026-10-28 09:44:55 +00:00
186 lines
6.1 KiB
Markdown
186 lines
6.1 KiB
Markdown
# 贡献指南
|
||
|
||
## 目录结构
|
||
|
||
| 目录 | 说明 |
|
||
| ----------------- | ----------------------------------------- |
|
||
| src | 主题生成框架与辅助工具的包 |
|
||
| src/core | 主题生成框架（CSS 变量、语法高亮样式） |
|
||
| src/functions | 主题辅助工具（颜色计算等） |
|
||
| src/palette | 主题调色板（GitHub / Gitea / Catppuccin） |
|
||
| src/types | 主题颜色变量类型定义 |
|
||
| src/vite-plugin | 主题的 Vite 构建插件 |
|
||
| styles | 主题样式覆盖 |
|
||
| styles/common | 可复用的 CSS 样式片段 |
|
||
| styles/public | 基础元素或跨页面元素的样式 |
|
||
| styles/components | 具体页面的样式 |
|
||
| styles/templates | 模板专属样式 |
|
||
| themes | 颜色主题定义 |
|
||
| primer | 自动生成的 Primer 设计令牌 |
|
||
| scripts | 构建和工具脚本 |
|
||
| templates | Gitea 模板覆盖（可选） |
|
||
| gitea | 上游 Gitea 参考文件 |
|
||
| screenshots | 主题截图 |
|
||
|
||
## 贡献说明
|
||
|
||
不推荐主题样式贡献, 因为 Gitea 主题最终是由单个 CSS 文件提供, 所以会有先后顺序覆盖, 样式影响广泛等问题.
|
||
|
||
开发者每个人的思路不一样, 审核很难看出这些问题, 会极大增加维护难度.
|
||
|
||
如果确定理解了 Gitea 的样式布局和我的思路, 请先提交 Issue 确认工作量和预期效果, 然后再开发提交 PR.
|
||
|
||
如果认为有更好的思路, 欢迎提交 Issue.
|
||
|
||
> [!IMPORTANT]
|
||
>
|
||
> 提交 PR 时, 请执行 `bun commit`
|
||
|
||
## 开发环境
|
||
|
||
主题依赖于 Bun 环境, 请确保你的环境中已经安装了 Bun, 推荐使用 Bun 1.3.14 或以上版本.
|
||
|
||
请使用 VSCode 开发, 并安装仓库中推荐的插件.
|
||
|
||
如果不喜欢多余的插件, 请务必安装 `vscode-styled-components` 插件, 此插件用于渲染和检查 TypeScript 中的 CSS 模板字符串.
|
||
|
||
推荐使用 VSCode 1.102.0 版本以上开发, 此版本以上提供 TypeScript 代码中 16 进制颜色的支持.
|
||
|
||
## 开发流程
|
||
|
||
### 安装依赖
|
||
|
||
```bash
|
||
bun install
|
||
```
|
||
|
||
### 设置环境变量
|
||
|
||
在项目根目录下创建 `.env` 文件, 变量参考 `.env.example` 文件.
|
||
|
||
环境变量用于发送编译后的主题到服务器上, 快速预览主题.
|
||
|
||
### 编译主题
|
||
|
||
编译并同步到远程服务器预览
|
||
|
||
```bash
|
||
bun bundle:dev
|
||
```
|
||
|
||
编译所有主题
|
||
|
||
```bash
|
||
bun bundle
|
||
```
|
||
|
||
格式化项目中的代码
|
||
|
||
```bash
|
||
bun fmt
|
||
```
|
||
|
||
用于 PR, 检查并编译项目中的所有代码并进行格式化
|
||
|
||
```bash
|
||
bun commit
|
||
```
|
||
|
||
## 开发规范
|
||
|
||
`src`, `styles`, `themes` 为项目的主目录.
|
||
|
||
跨模块引用时使用 package exports 路径, 例如 `import { defineTheme } from "@lutinglt/gitea-github-theme/core"`
|
||
|
||
同模块内文件互相引用时使用相对路径, 例如 `import { defineTheme } from "./theme"`
|
||
|
||
## 颜色主题贡献
|
||
|
||
主题文件命名格式: `主题名称.ts`，配合 `theme.config.ts` 注册使用。
|
||
|
||
如果主题同时有深色和亮色变体, 框架会自动生成 auto 自动颜色主题.
|
||
|
||
项目接受自定义主题并会附加到发布的版本中, 但项目所有者不参与维护和审核.
|
||
|
||
请在颜色主题文件头部附加自己的作者信息, 方便 Issue 提问者找到你 `@`.
|
||
|
||
推荐使用 `defineTheme` 配合 `ThemeColor` 类型来定义主题颜色, 框架会自动计算生成所有 Gitea CSS 变量.
|
||
|
||
颜色计算函数可从 `@lutinglt/gitea-github-theme/core` 导入 `scaleColorLight` 和 `rgba`, 或使用 `color2k`
|
||
库进行额外颜色操作.
|
||
|
||
例: `themes/主题名称.ts`
|
||
|
||
```ts
|
||
/**
|
||
* @author 你的名字
|
||
* @description 主题描述
|
||
*/
|
||
import { defineTheme, scaleColorLight } from "@lutinglt/gitea-github-theme/core";
|
||
import type { ThemeColor, Syntax } from "@lutinglt/gitea-github-theme/core";
|
||
|
||
const themeColor: ThemeColor = {
|
||
isDarkTheme: true,
|
||
primary: "#0969da",
|
||
primaryContrast: "#f0f6fc",
|
||
secondary: "#30363d",
|
||
base: { red: "#f85149", orange: "#d29922" /* ... */ },
|
||
console: {
|
||
/* ... */
|
||
},
|
||
diff: {
|
||
/* ... */
|
||
},
|
||
other: {
|
||
/* ... */
|
||
},
|
||
github: {
|
||
/* ... */
|
||
},
|
||
};
|
||
|
||
const syntaxColor: Syntax = {
|
||
/* 自定义代码高亮色, 或导入使用其他主题的代码高亮色 */
|
||
};
|
||
|
||
export default defineTheme({ colorType: "theme", themeColor, syntaxColor });
|
||
```
|
||
|
||
如需使用 Gitea 原生颜色格式, 使用 `colorType: "gitea"` 配合 `GiteaColor` 类型:
|
||
|
||
```ts
|
||
import type { GiteaColor, Syntax } from "@lutinglt/gitea-github-theme/core";
|
||
import { defineTheme } from "@lutinglt/gitea-github-theme/core";
|
||
|
||
const giteaColor: GiteaColor = {
|
||
/* ... */
|
||
};
|
||
const syntaxColor: Syntax = {
|
||
/* ... */
|
||
};
|
||
export default defineTheme({ colorType: "gitea", themeColor: giteaColor, syntaxColor });
|
||
```
|
||
|
||
完成主题颜色开发后, 在 `theme.config.ts` 中注册主题系列, 编译后在 Gitea 实例中截图放入 `screenshots`
|
||
目录, 截图名与主题名相同. (推荐克隆本仓库, 避免泄露个人隐私)
|
||
|
||
然后将截图信息添加到 `README.md` 文件中.
|
||
|
||
颜色复用案例可参考 `themes/github.ts` 的色盲主题实现.
|
||
|
||
## 主题样式贡献
|
||
|
||
主题样式使用 `css()`
|
||
模板字符串开发，字符串经过 LightningCSS 处理, 支持 CSS 嵌套语法。请勿使用 SCSS 函数，如需复杂处理请使用 TypeScript 相关库，比如项目自带的
|
||
`color2k` 库。
|
||
|
||
推荐需要复杂处理时，提取逻辑到 `src/functions` 目录下的函数中。
|
||
|
||
主题样式中使用到的所有颜色必须使用颜色变量，导入 `import { themeVars } from "@lutinglt/gitea-github-theme/core"`
|
||
|
||
涉及到主题自己的颜色变量 `${themeVars.github.xxx}`，在使用时请将使用的文件和变量添加到对应变量的注释中
|
||
`src/types/color/github`
|
||
|
||
小型圆角 (6px) 请使用全局圆角变量，导入
|
||
`import { otherThemeVars } from "@lutinglt/gitea-github-theme/core"`，`${otherThemeVars.border.radius}`
|