From dc4eff2bd7c8efff73ee877b03681aae6772e229 Mon Sep 17 00:00:00 2001 From: lutinglt Date: Sun, 10 Aug 2025 21:46:30 +0800 Subject: [PATCH] update contributing.md --- .env.example | 4 + CONTRIBUTING.md | 151 +++++++++++++++++++++++++++++++++++++- src/core/chroma.ts | 61 +++++++++++++++ src/core/color.ts | 4 +- src/core/prettylights.ts | 110 --------------------------- src/index.ts | 2 +- styles/components/diff.ts | 2 +- themes/soft-dark.css.ts | 39 ++-------- 8 files changed, 223 insertions(+), 150 deletions(-) create mode 100644 src/core/chroma.ts diff --git a/.env.example b/.env.example index be2e09e..77f64d6 100644 --- 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/ \ No newline at end of file diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index f6207fa..9aee2eb 100644 --- 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/\ | 具体颜色主题自己的颜色或风格 | + +## 贡献说明 + +本主题不推荐样式贡献, 因为 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}` diff --git a/src/core/chroma.ts b/src/core/chroma.ts new file mode 100644 index 0000000..0e9de9f --- /dev/null +++ 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", + }, +}); diff --git a/src/core/color.ts b/src/core/color.ts index 53f89df..e8febca 100644 --- 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, diff --git a/src/core/prettylights.ts b/src/core/prettylights.ts index fccffb7..43170fb 100644 --- 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", - } -}) \ No newline at end of file diff --git a/src/index.ts b/src/index.ts index e792b23..cc42935 100644 --- 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"; diff --git a/styles/components/diff.ts b/styles/components/diff.ts index 2db5f5f..74044c6 100644 --- 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}; } } /* 行号居中 */ diff --git a/themes/soft-dark.css.ts b/themes/soft-dark.css.ts index 33351fc..8a9b747 100644 --- 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", },