贡献指南

目录结构

目录	说明
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 进制颜色的支持.

开发流程

安装依赖

bun install

设置环境变量

在项目根目录下创建 .env 文件, 变量参考 .env.example 文件.

环境变量用于发送编译后的主题到服务器上, 快速预览主题.

编译主题

编译并同步到远程服务器预览

bun bundle:dev

编译所有主题

bun bundle

格式化项目中的代码

bun fmt

用于 PR, 检查并编译项目中的所有代码并进行格式化

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

/**
 * @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 类型:

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}

FilesExpand file tree

CONTRIBUTING_CN.md

Latest commit

History