update contributing.md

2025-10-25 20:30:30 +00:00 · 2025-08-10 21:46:30 +08:00
parent 3b5a596b2f
commit dc4eff2bd7
8 changed files with 223 additions and 150 deletions
--- a/.env.example
+++ b/.env.example
@@ -1,4 +1,8 @@
+# 开发模式下编译的主题 (开发模式仅编译单个主题)
 DEV_THEME=dark
+# 把编译后的主题上传到服务器的服务器名称, 通过 SCP 上传
 SSH_SERVER=localhost
+# 上传到服务器的用户名称, 不支持密码, 请确保有 SSH 免密登录权限
 SSH_USER=root
+# 上传到服务器的主题路径, 请使用绝对路径
 GITEA_THEME_PATH=/data/gitea/public/assets/css/
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -1,7 +1,150 @@
+# 贡献指南
+
+## 目录结构
+
 | 目录              | 说明                         |
 | ----------------- | ---------------------------- |
-| styles            | 元素 GitHub 风格             |
-| styles/components | 具体页面的元素单独风格       |
-| styles/public     | 适用大部分页面的元素默认风格 |
+| src               | 主题生成框架与辅助工具的包   |
+| src/core          | 主题生成框架                 |
+| src/functions     | 主题辅助工具                 |
+| src/types         | 主题的颜色变量定义           |
+| styles            | 主题样式                     |
+| styles/components | 具体页面的元素的样式         |
+| styles/public     | 基础元素或跨页面的元素的样式 |
 | themes            | 颜色主题                     |
-| themes/\<theme>   | 具体颜色主题自己的颜色或风格 |
+
+## 贡献说明
+
+本主题不推荐样式贡献, 因为 Gitea 主题最终是由单个 CSS 文件提供, 所以会有先后顺序覆盖, 样式影响广泛等问题.
+
+开发者每个人的思路不一样, 审核很难看出这些问题, 会极大增加维护难度.
+
+如果确定理解了 Gitea 的样式布局和我的思路, 请先提交 Issue 确认工作量和预期效果, 然后再开发提交 PR.
+
+如果认为有更好的思路, 欢迎提交 PR.
+
+> [!IMPORTANT]
+>
+> 提交 PR 时, 请执行 `npm run commit`
+
+## 开发环境
+
+本主题仅依赖于 Node.js 环境, 请确保你的环境中已经安装了 Node.js, 推荐使用 Node.js 20 或以上版本.
+
+请使用 VSCode 开发, 并安装仓库中推荐的插件.
+
+如果不喜欢多余的插件, 请务必安装 `vscode-styled-components`
+插件, 此插件用于渲染和检查 TypeScript 中的 CSS 中的模板字符串.
+
+推荐使用 VSCode 1.102.0 版本以上开发, 此版本以上提供 TypeScript 代码中 16 进制颜色的支持.
+
+## 开发流程
+
+### 安装依赖
+
+```bash
+npm install
+```
+
+### 设置环境变量
+
+在项目根目录下创建 `.env` 文件, 变量参考 `.env.example` 文件.
+
+环境变量用于发送编译后的主题到服务器上, 快速预览主题.
+
+### 编译主题
+
+编译开发中的主题
+
+```bash
+npm run dev
+```
+
+编译所有主题
+
+```bash
+npm run build
+```
+
+格式化项目中的代码
+
+```bash
+npm run format
+```
+
+用于 PR, 检查并编译项目中的所有代码并进行格式化
+
+```bash
+npm run commit
+```
+
+## 开发规范
+
+`src`, `styles`, `themes` 为项目的主目录, 主目录下的第一个目录为模块.
+
+主目录或主目录模块互相引用时, 请使用绝对路径, 例如 `import { defineTheme } from "src"`
+
+模块下的文件互相引用时, 请使用相对路径, 例如 `import { defineTheme } from "./theme"`
+
+## 颜色主题贡献
+
+颜色主题名称格式 `主题名称-dark.css.ts` 或 `主题名称-light.css.ts`, 分别表示深色和亮色主题.
+
+如果主题有深色和亮色模式, 会自动生成自动颜色主题, 不需要手动添加.
+
+项目接受自定义主题并会附加到发布的版本中, 但项目所有者不参与维护和审核.
+
+请在颜色主题文件头部附加自己的作者信息, 方便 Issue 提问者找到你 `@`.
+
+推荐使用 `import { defineTheme } from "src"` 导入主题生成框架, 然后使用 `defineTheme` 函数生成主题,
+defineTheme 中设置了一些经过计算得到的 Gitea 变量可以减少工作量, 具体请查看函数说明.
+
+例: `themes/主题名称-dark.css.ts`
+
+```ts
+/**
+ * @author 你的名字
+ * @description 主题描述
+ */
+import { defineTheme } from "src";
+export default defineTheme({
+  ...
+});
+// 使用其他主题颜色作为基础
+import dark from "themes/dark";
+export default defineTheme({
+  ...dark,
+  ...
+});
+```
+
+如果不需要自定义代码高亮色, 则不传递 chroma 参数, 框架会自动根据主题的暗色或亮色生成代码高亮色.
+
+如果需要完全自定义每个 Gitea 变量, 请导入 `import { Theme } from "src/theme"`
+
+例: `themes/主题名称-dark.css.ts`
+
+```ts
+/**
+ * @author 你的名字
+ * @description 主题描述
+ */
+import { Theme } from "src";
+export default theme: Theme = {
+ ...
+};
+```
+
+## 主题样式贡献
+
+主题样式使用 TypeScript 的 css 模板字符串开发, 该模板字符串会经过过 sass 预处理器处理, 支持 SCSS 语法并且本主题只接受 SCSS 嵌套语法, 请不要使用 CSS 语法, 如果一定要用请说明原因.
+
+请尽量不要使用 SCSS 的函数, `vscode-styled-components` 插件会报错, 请使用 TypeScript 相关库处理, 比如本主题自带的
+`polished` 库.
+
+推荐需要使用复杂处理时, 提取逻辑到 `src/functions` 目录下的函数中, 然后在 `src/styles` 目录下的样式文件中使用.
+
+主题样式中使用到的所有颜色请使用颜色变量, 颜色变量导入 `import { themeVars } from "src/types"`
+
+小型圆角(6px)请使用全局圆角变量, 圆角变量导入 `import { otherThemeVars } from "src/types/vars"`
+`${otherThemeVars.border.radius}`
--- a/src/core/chroma.ts
+++ b/src/core/chroma.ts
@@ -0,0 +1,61 @@
+import { prettylights2Chroma } from "./prettylights";
+
+export const defaultDarkChroma = prettylights2Chroma({
+  syntax: {
+    brackethighlighter: { angle: "#9198a1", unmatched: "#f85149" },
+    carriage: { return: { bg: "#b62324", text: "#f0f6fc" } },
+    comment: "#9198a1",
+    constant: "#79c0ff",
+    constantOtherReferenceLink: "#a5d6ff",
+    entity: "#d2a8ff",
+    entityTag: "#7ee787",
+    invalid: { illegal: { bg: "#8e1519", text: "#f0f6fc" } },
+    keyword: "#ff7b72",
+    markup: {
+      bold: "#f0f6fc",
+      changed: { bg: "#5a1e02", text: "#ffdfb6" },
+      deleted: { bg: "#67060c", text: "#ffdcd7" },
+      heading: "#1f6feb",
+      ignored: { bg: "#1158c7", text: "#f0f6fc" },
+      inserted: { bg: "#033a16", text: "#aff5b4" },
+      italic: "#f0f6fc",
+      list: "#f2cc60",
+    },
+    metaDiffRange: "#d2a8ff",
+    storageModifierImport: "#f0f6fc",
+    string: "#a5d6ff",
+    stringRegexp: "#7ee787",
+    sublimelinterGutterMark: "#3d444d",
+    variable: "#ffa657",
+  },
+});
+
+export const defaultLightChroma = prettylights2Chroma({
+  syntax: {
+    brackethighlighter: { angle: "#59636e", unmatched: "#82071e" },
+    carriage: { return: { bg: "#cf222e", text: "#f6f8fa" } },
+    comment: "#59636e",
+    constant: "#0550ae",
+    constantOtherReferenceLink: "#0a3069",
+    entity: "#6639ba",
+    entityTag: "#0550ae",
+    invalid: { illegal: { bg: "#82071e", text: "#f6f8fa" } },
+    keyword: "#cf222e",
+    markup: {
+      bold: "#1f2328",
+      changed: { bg: "#ffd8b5", text: "#953800" },
+      deleted: { bg: "#ffebe9", text: "#82071e" },
+      heading: "#0550ae",
+      ignored: { bg: "#0550ae", text: "#d1d9e0" },
+      inserted: { bg: "#dafbe1", text: "#116329" },
+      italic: "#1f2328",
+      list: "#3b2300",
+    },
+    metaDiffRange: "#8250df",
+    storageModifierImport: "#1f2328",
+    string: "#0a3069",
+    stringRegexp: "#116329",
+    sublimelinterGutterMark: "#818b98",
+    variable: "#953800",
+  },
+});
--- a/src/core/color.ts
+++ b/src/core/color.ts
@@ -2,7 +2,7 @@ import { rgba, saturate } from "polished";
 import { scaleColorLight } from "src/functions";
 import type { Ansi, Chroma, Console, Diff, Github, Message, Named, Other, Primary, Secondary } from "src/types";
 import { themeVars } from "src/types/vars";
-import { prettylightsDark, prettylightsLight } from "./prettylights";
+import { defaultDarkChroma, defaultLightChroma } from "./chroma";
 import type { Theme } from "./theme";

 type ThemeColor = {
@@ -341,7 +341,7 @@ export function defineTheme(themeColor: ThemeColor, chroma: Chroma | null = null

  return {
    isDarkTheme: themeColor.isDarkTheme.toString(),
-    chroma: chroma || (themeColor.isDarkTheme ? prettylightsDark : prettylightsLight),
+    chroma: chroma || (themeColor.isDarkTheme ? defaultDarkChroma : defaultLightChroma),
    color: {
      primary,
      secondary,
--- a/src/core/prettylights.ts
+++ b/src/core/prettylights.ts
@@ -150,113 +150,3 @@ export function prettylights2Chroma(prettylights: prettylightsColor): Chroma {
    },
  };
 }
-
-export const prettylightsDark = prettylights2Chroma({
-  syntax: {
-    brackethighlighter: {
-      angle: "#9198a1",
-      unmatched: "#f85149",
-    },
-    carriage: {
-      return: {
-        bg: "#b62324",
-        text: "#f0f6fc",
-      },
-    },
-    comment: "#9198a1",
-    constant: "#79c0ff",
-    constantOtherReferenceLink: "#a5d6ff",
-    entity: "#d2a8ff",
-    entityTag: "#7ee787",
-    invalid: {
-      illegal: {
-        bg: "#8e1519",
-        text: "#f0f6fc",
-      },
-    },
-    keyword: "#ff7b72",
-    markup: {
-      bold: "#f0f6fc",
-      changed: {
-        bg: "#5a1e02",
-        text: "#ffdfb6",
-      },
-      deleted: {
-        bg: "#67060c",
-        text: "#ffdcd7",
-      },
-      heading: "#1f6feb",
-      ignored: {
-        bg: "#1158c7",
-        text: "#f0f6fc",
-      },
-      inserted: {
-        bg: "#033a16",
-        text: "#aff5b4",
-      },
-      italic: "#f0f6fc",
-      list: "#f2cc60",
-    },
-    metaDiffRange: "#d2a8ff",
-    storageModifierImport: "#f0f6fc",
-    string: "#a5d6ff",
-    stringRegexp: "#7ee787",
-    sublimelinterGutterMark: "#3d444d",
-    variable: "#ffa657",
-  }
-})
-
-export const prettylightsLight = prettylights2Chroma({
-  syntax: {
-    brackethighlighter: {
-      angle: "#59636e",
-      unmatched: "#82071e",
-    },
-    carriage: {
-      return: {
-        bg: "#cf222e",
-        text: "#f6f8fa",
-      },
-    },
-    comment: "#59636e",
-    constant: "#0550ae",
-    constantOtherReferenceLink: "#0a3069",
-    entity: "#6639ba",
-    entityTag: "#0550ae",
-    invalid: {
-      illegal: {
-        bg: "#82071e",
-        text: "#f6f8fa",
-      },
-    },
-    keyword: "#cf222e",
-    markup: {
-      bold: "#1f2328",
-      changed: {
-        bg: "#ffd8b5",
-        text: "#953800",
-      },
-      deleted: {
-        bg: "#ffebe9",
-        text: "#82071e",
-      },
-      heading: "#0550ae",
-      ignored: {
-        bg: "#0550ae",
-        text: "#d1d9e0",
-      },
-      inserted: {
-        bg: "#dafbe1",
-        text: "#116329",
-      },
-      italic: "#1f2328",
-      list: "#3b2300",
-    },
-    metaDiffRange: "#8250df",
-    storageModifierImport: "#1f2328",
-    string: "#0a3069",
-    stringRegexp: "#116329",
-    sublimelinterGutterMark: "#818b98",
-    variable: "#953800",
-  }
-})
--- a/src/index.ts
+++ b/src/index.ts
@@ -1,3 +1,3 @@
 export { defineTheme } from "./core/color";
-export type { Console, Diff, Other } from "./types";
+export type { Chroma, Console, Diff, Other } from "./types";
 export { themeVars } from "./types/vars";
--- a/styles/components/diff.ts
+++ b/styles/components/diff.ts
@@ -34,7 +34,7 @@ export const diff = css`

    &:hover {
      background: ${themeVars.github.bgColor.accent.emphasis};
-      color: ${themeVars.color.white}
+      color: ${themeVars.color.white};
    }
  }
  /* 行号居中 */
--- a/themes/soft-dark.css.ts
+++ b/themes/soft-dark.css.ts
@@ -74,47 +74,22 @@ export default defineGithubTheme(
  },
  prettylights2Chroma({
    syntax: {
-      brackethighlighter: {
-        angle: "#9198a1",
-        unmatched: "#e5534b",
-      },
-      carriage: {
-        return: {
-          bg: "#ad2e2c",
-          text: "#f0f6fc",
-        },
-      },
+      brackethighlighter: { angle: "#9198a1", unmatched: "#e5534b" },
+      carriage: { return: { bg: "#ad2e2c", text: "#f0f6fc" } },
      comment: "#9198a1",
      constant: "#6cb6ff",
      constantOtherReferenceLink: "#96d0ff",
      entity: "#dcbdfb",
      entityTag: "#8ddb8c",
-      invalid: {
-        illegal: {
-          bg: "#922323",
-          text: "#f0f6fc",
-        },
-      },
+      invalid: { illegal: { bg: "#922323", text: "#f0f6fc" } },
      keyword: "#f47067",
      markup: {
        bold: "#f0f6fc",
-        changed: {
-          bg: "#682d0f",
-          text: "#ffddb0",
-        },
-        deleted: {
-          bg: "#78191b",
-          text: "#ffd8d3",
-        },
+        changed: { bg: "#682d0f", text: "#ffddb0" },
+        deleted: { bg: "#78191b", text: "#ffd8d3" },
        heading: "#316dca",
-        ignored: {
-          bg: "#255ab2",
-          text: "#f0f6fc",
-        },
-        inserted: {
-          bg: "#1b4721",
-          text: "#b4f1b4",
-        },
+        ignored: { bg: "#255ab2", text: "#f0f6fc" },
+        inserted: { bg: "#1b4721", text: "#b4f1b4" },
        italic: "#f0f6fc",
        list: "#eac55f",
      },