Files
witcher ca00daddf6 feat: release Terminal-Witcher 3.1.17 and project handoff
Ship responsive navigation, configurable profile and four-section homepage, article/life category separation, natural-ratio book covers, and independent border settings. Include release history and complete context handoff documentation.
2026-11-16 18:30:36 +08:00

288 lines
18 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Terminal-EZ
一款简洁, 复古的 Terminal 风格 Halo 主题
<a href="https://raw.githubusercontent.com/Erzbir/halo-theme-terminal/refs/heads/main/screenshot.png">预览图</a>
<a href="https://witchercheung.cn">预览网站</a>
## 使用说明
### 通用设置
- `时间格式` 提供常用格式, 也可以填写自定义 Java 时间格式
- `访客偏好有效期` 控制外观, 配色和像素风格的保存时间, 默认为 24 小时, 设为 `0` 时永久保存
- `PJAX` 默认关闭; 开启后支持局部刷新, 如果遇到插件兼容问题可以将其关闭
### 页头功能按钮
页头默认包含搜索, 配色切换, 外观切换和像素化按钮. 可以在 `页头 -> 功能按钮` 中添加, 删除或拖动按钮来控制显示顺序.
- 搜索按钮仅在搜索组件可用时显示
- 内置按钮可以分别设置普通图标和像素风格图标, 留空时使用主题内置图标
- 自定义功能按钮需要填写名称, `onclick` JavaScript 和图标; 只应填写可信任的 JavaScript
外观切换顺序为 `浅色 -> 深色 -> 跟随系统`. 切换外观时会清除访客单独选择的配色, 重新使用当前外观对应的主题方案.
### 配色
在 `配色` 中分别选择浅色和深色方案. 默认外观设为“跟随系统”时, 主题会根据访客的系统设置自动切换.
添加自定义配色:
1. 在 `配色 -> 自定义方案` 中添加一项并填写唯一 ID, 背景色, 主文本色和基础强调色.
2. 如需更精细的效果, 开启高级颜色设置后配置文字, 链接, 导航, 控件, 边框和代码颜色.
3. 在浅色方案或深色方案中选择 `custom`, 再填写自定义方案的 ID.
4. 如需允许访客自由选择配色, 在 `页头 -> 功能按钮` 中保留或添加配色切换按钮.
自定义方案的高级颜色设置支持分别配置 `导航栏背景色` 和 `导航文字颜色`,同时作用于顶部导航、下拉菜单和手机全屏菜单。背景色留空时跟随页面背景,滚动后基于导航栏背景色显示半透明毛玻璃效果。
### 字体与像素风格
主题内置 JetBrains Mono, Hack 和 Fira Code, 也可以选择访客的系统字体. 如需加载自己的字体, 开启 `字体与排版 -> 启用自定义字体`, 再按优先级添加字体文件.
每项自定义字体可以填写字体名称, PostScript Name, 字体文件和格式. 浏览器会优先匹配访客设备中的本地字体, 未找到时再加载字体文件. 高级设置可配置字重, 样式, Unicode 范围, 显示策略和可变字体轴等属性.
开启像素风格后, 主题会优先使用内置像素字体和像素图标.
### 布局与全局样式
- `全屏布局` 会让正文占满可用宽度, 并可单独限制正文图片, 视频和 `figure` 的最大宽度
- `正文区域最大宽度`, `正文区域内边距` 和 `表格宽度铺满父元素` 用于调整内容区域
- `基础字体大小`, `基础行高` 和 `文章段落间距` 用于调整阅读密度
- `无序列表标记`, 边线样式, 边线宽度和标题分隔线用于统一全站视觉风格;图片与卡片默认使用方角,主边框默认 2px。在 `全局样式 → 边线宽度(px)` 直接填写 1、1.5、2 等数字,0 隐藏主边框。留空时兼容原有的 `边线宽度(高级 CSS,可选)`,两项都留空时采用默认值
- `元信息分隔符` 用于分隔文章时间, 作者和标签等信息
### 页面设置
首页采用错开的两排布局:上排为 70% 文章和 30% 生活,下排为 30% 阅读和 70% 作品集;窄屏自动变为单列。欢迎区左侧为可配置的个人简介,右侧沿用公告标题、公告内容和终端光标,无外框;标题靠左,公告内容在欢迎区域内靠右。各区域右侧入口统一为“更多”。
在 `主题设置 → 首页` 中配置欢迎区与个人简介:
- `欢迎区样式`:默认细节版,用淡电路走线、轻底色简介和细分隔线组织欢迎区;社交图标与文章归档、作品集快捷入口收在右侧欢迎内容底部。支持切换简洁版。颜色跟随主题,装饰不拦截点击。
- `欢迎区左右比例`:默认左侧名片占 30%、右侧欢迎内容占 70%;也可切换为 50% / 50%。
- 填写 `简介姓名或昵称`、`身份或研究方向` 和 `个人简介`;简介为纯文本,保留换行,文字左对齐。
- `个人照片(可选)`:上传后显示在最右侧,简介位于照片左侧;不上传照片时只显示文字,不留照片占位。也支持仅放照片。
- `关于我或完整简历链接(可选)`:可指向站内页面、外部网址或简历 PDF,不填则不显示链接。
- 手机端先显示名片,再显示欢迎语,简介文字仍在照片左侧。所有简介字段均为空时隐藏简介;关闭 `欢迎区左侧展示个人简介` 可恢复全宽欢迎语。
在 `首页` 设置中维护四个区域:
- `首页文章来源`:默认展示生活分类以外的已发布文章,不会因为模块名为“文章”而自动筛选同名分类;旧版本保存的分类选择也不会自动开启筛选。生活分类(含子分类)优先归入首页生活区,即使文章同时属于技术分类,也不会在两个区域重复出现。排除生活文章后再按设置数量展示,“更多”进入完整归档 `/archives`。如需只展示某一分类,请选择“仅指定分类”,再设置 `首页文章分类`;此时同样排除生活文章,“更多”进入该分类。未找到生活分类时保留原有文章列表。
- 顶层导航中名为“文章”的入口指向 `/archives`,其下嵌入式、机器人、Web 等分类链接仍指向各自分类。导航菜单的缩进用于组织链接,与文章分类管理中的真实父子关系分别维护,不需要为首页展示逐篇移动文章或修改原有分类。
- `文章卡片列数`:自动模式按文章区实际宽度显示两列或三列,手机窄屏一列,也可手动选择两列或三列。`首页文章数量` 默认六篇,适合三列两行或两列三行;已有的自定义数量会保留,可在设置中调整。卡片上方为正方形封面,下方为标题、摘要和日期;无封面时使用终端字符占位。标题最多两行、摘要最多三行,标题提示和文章页保留完整内容。图片框使用方角和主题主边框,鼠标悬停或键盘聚焦提供反馈;减少动态效果模式关闭位移动画。
- `生活文章分类`:选择已有分类,自动读取其中的文章及子分类文章。留空时寻找名为 `生活` 或别名为 `life` 的分类;名称不同时在此明确选择即可,无需调整技术文章的分类。`首页生活文章数量` 控制条数。设置文章封面后,生活列表会显示左侧小封面、右侧标题/日期/摘要;没有封面则采用纯文字布局。
- `阅读书架`:添加书名、封面、一句话点评和可选的阅读笔记链接,每行两本。封面宽度铺满、高度按原图比例自然显示,不裁切、不添加固定比例框造成的上下留白;悬停时不放大裁切书封。通过 `首页书籍数量` 限制首页展示。“更多”默认指向 `/read`,创建别名为 `read` 的独立页面后即可访问;也可通过 `完整书架链接` 改为阅读分类或其它页面地址。
- `首页作品来源`:自动模式读取已启用的项目集插件 `portfolio`,以封面、名称、介绍和开源仓库入口展示作品。插件未启用时使用 `手动作品`;也可直接选择手动模式。GitHub 仓库会显示 GitHub 链接。“更多”默认指向 `/portfolio`,可通过 `完整作品集链接` 修改。
未配置书籍、尚无生活文章或作品时显示简短的空状态。首页沿用主题现有字体、配色、标题分隔线和图片边框;其它页面保持原有布局宽度。
| 页面 | 可配置内容 |
|-----|-----------------------------------|
| 首页 | 公告标题, 公告内容, 个人简介与照片, 社交资料, 置顶图标, 图标位置和文章标签 |
| 文章页 | 文章目录, 目录默认状态和文章标签 |
| 归档页 | 页面标题, 文章标签, 分页和年份展开模式 |
| 分类页 | 分类列表标题和分类详情标题 |
| 标签页 | 标签列表标题和标签详情标题 |
| 友链页 | 页面标题 |
文章目录会读取正文中的 `h1` 到 `h4`. “自动”模式在普通布局中默认展开, 在全屏布局中默认收起; 目录也会根据浏览器宽度和正文右侧空间调整位置.
在 `主题设置 → 文章页` 中,`目录边框粗细(px)` 单独控制目录外框,默认 1px,支持小数和 0(隐藏外框)。`目录边框颜色` 留空时,按当前配色自动生成浅色线条,随明暗模式切换;也可选择固定颜色。目录内的层级辅助线沿用这个浅色,整体轮廓更柔和。
### 插件与扩展页面
| 功能 | 使用条件 |
|-------|----------------------------------|
| 友链 | 安装并启用友链插件 |
| 友链申请 | 使用友链插件 `>=2.3.0`, 并在插件设置中开启友链申请 |
| 朋友圈 | 安装并启用朋友圈插件 |
| 瞬间 | 安装并启用瞬间插件 |
| 项目作品集 | 安装并启用作品集插件 |
| 搜索 | 安装并启用搜索组件, 并在页头功能按钮中添加搜索按钮 |
| 评论 | 安装并启用评论插件, 同时在 Halo 中开启对应内容的评论功能 |
安装插件后, 对应页面会自动使用主题提供的样式和页面模板.
### 社交资料与备案
在 `社交资料` 中可以添加任意社交资料, 每项资料可配置名称, 链接, 普通图标和像素风格图标; 链接支持 `http://`, `https://`, `mailto:` 和 `tel:`.
添加后还需要开启 `首页 -> 展示社交资料` 才会在首页显示. RSS 可单独开启.
页脚支持 ICP 备案号, ICP 跳转链接, 公安备案号和公安备案跳转链接.
### 内置配色
| 名称 | 背景色 | 主文本色 | 基础强调色 |
|-------------|-----------|-----------|-----------|
| `day` | `#f4f4f4` | `#3e3e3e` | `#003e8a` |
| `night` | `#101216` | `#8b949e` | `#6ca4f8` |
| `niello` | `#1a170f` | `#eceae5` | `#eec35e` |
| `matrix` | `#000000` | `#4eee85` | `#4eee85` |
| `ink` | `#121212` | `#c3c3c3` | `#ffffff` |
| `paper` | `#ffffff` | `#1b1b1b` | `#000000` |
| `hopbush` | `#fff6f6` | `#462d2d` | `#cc6099` |
| `pistachio` | `#1d2021` | `#ebdbb2` | `#8ec07c` |
| `blue` | `#153489` | `#eceae5` | `#5ea5ee` |
| `vanilla` | `#fff4f2` | `#424140` | `#8f6a5e` |
| `studio` | `#f7f4ff` | `#403352` | `#6f49ab` |
| `blood` | `#221f29` | `#ffffff` | `#ff6266` |
### 自定义 CSS
在主题设置的 `高级设置 -> 自定义 CSS` 中填写原始 CSS. 自定义内容在主题主样式之后加载, 可以覆盖内置规则.
直接使用内置配色名称即可覆盖对应变量:
```css
html[data-theme-color-scheme='matrix'] {
--color-theme-background: #07130b;
--color-theme-text: #7dff9b;
--color-theme-accent: #39ff68;
}
```
修改特定配色下的字体:
```css
html[data-theme-color-scheme='matrix'] {
--family-theme-font: system-ui;
}
```
### CSS 变量
#### 常用颜色变量
| 变量 | 用途 |
|---------------------------------|---------------------|
| `--color-theme-background` | 页面和基础背景 |
| `--color-theme-text` | 正文和主要文字 |
| `--color-theme-text-secondary` | 摘要, 插件等辅助文字 |
| `--color-theme-text-muted` | 时间, 作者, 占位符等弱化文字 |
| `--color-theme-text-inverse` | 强调色填充背景上的文字 |
| `--color-theme-accent` | 基础强调色, 用于填充和焦点等强调基础 |
| `--color-theme-text-accent` | 标题, 按钮文字等强调文字 |
| `--color-theme-text-label` | 标签和技术标记文字 |
| `--color-theme-text-link` | 普通链接文字 |
| `--color-theme-accent-muted` | 中等强度强调色 |
| `--color-theme-accent-subtle` | 低强度强调色 |
| `--color-theme-navigation` | 主导航文字 |
| `--color-theme-navigation-background` | 导航栏、下拉菜单及手机菜单背景 |
| `--color-theme-control` | 页头工具控件 |
| `--color-theme-surface` | 代码块和组件表面 |
| `--color-theme-surface-strong` | 对比度更高的代码和控件表面 |
| `--color-theme-border` | 默认边框 |
| `--color-theme-border-muted` | 低对比度边框 |
| `--color-theme-border-accent` | 交互元素和内容强调边框 |
| `--color-theme-border-emphasis` | 公告框, 作品卡片等强调边框 |
| `--color-theme-selection` | 选中文字的背景 |
| `--color-theme-overlay` | 模态遮罩层 |
| `--color-theme-scrollbar` | 滚动条 |
| `--color-theme-code-text` | 行内代码和代码块文字 |
| `--color-theme-code-background` | 行内代码背景 |
| `--color-theme-caret` | 打字效果动态光标 |
派生颜色使用 CSS `color-mix()`. 自定义配色通常只需要设置背景色, 主文本色和基础强调色;
相同语义在所有配色中保持一致, 只有确实需要不同视觉层级时才覆盖其他语义变量.
#### 常用布局变量
| 变量 | 默认值 |
|--------------------------------------------|-----------------------------------------|
| `--size-theme-font` | `1rem` |
| `--height-theme-line` | `calc(var(--size-theme-font) * 1.75)` |
| `--spacing-theme-post-paragraph` | `calc(var(--size-theme-font) * 1.25)` |
| `--content-theme-post-meta-divider` | `"::"` |
| `--family-theme-font` | `'JetBrains Mono'` |
| `--list-theme-style` | `disc` |
| `--width-theme-border` | `2px` |
| `--width-theme-table-border` | `calc(var(--size-theme-font) * 0.0625)` |
| `--width-theme-media-max` | `60%` |
| `--spacing-theme-container-padding` | `calc(var(--size-theme-font) * 2.5)` |
| `--spacing-theme-container-padding-mobile` | `calc(var(--size-theme-font) * 1.25)` |
| `--style-theme-border` | `solid` |
| `--style-theme-table-border` | `dashed` |
| `--style-theme-title-divider` | `dashed` |
| `--radius-theme-border` | `0` |
| `--text-decoration-theme-link` | `none` |
| `--text-decoration-theme-post-link` | `var(--text-decoration-theme-link)` |
| `--weight-theme-inline-code` | `inherit` |
| `--lig-theme-font` | `none` |
| `--width-theme-scrollbar` | `thin` |
### PJAX
PJAX 默认关闭, 开启后站内 `a[data-pjax]` 链接会更新以下区域:
- `<head>` 中的 `<title>`
- `.content`
- `.ex-pjax`
`a[data-pjax]` 用于触发 PJAX 导航. `.ex-pjax` 是额外的内容替换区域, 需要确保当前页面和目标页面都存在对应元素.
```html
<div class="ex-pjax">
Dynamic content
</div>
```
如果要注入 `<script>` 或 `<link rel="stylesheet">`, 根据插入的位置需要为标签添加一些属性才能保证行为正常
- `<head>`: 重新执行所有请求页面新插入的无 `data-no-pjax` 属性的 `<script>` 和 `<link rel="stylesheet">`
- `<footer>`: 重新执行有 `data-pjax` 属性的 `<script>` 和 `<link rel="stylesheet">`
- `.content`: 重新执行有 `data-pjax` 属性的 `<script>`
设置 `data-no-pjax` 属性, 可以防止被 PJAX 处理
## 开发和构建
### 环境
项目使用原生 ES 模块, 用 `esbuild` 来构建, 使用 `pnpm` 管理依赖
确保已安装 `nodejs`
### 使用 Make
```shell
make
```
其他目标:
```shell
make install
make build
make test
make clean
```
`make test` 会构建主题, 清理旧的测试目录并将压缩包解压到 `dist/theme-terminal-witcher`
### 使用 pnpm
```shell
corepack enable
pnpm install --frozen-lockfile
pnpm build
```
构建产物位于:
```text
dist/theme-terminal-witcher-<version>.zip
```
## 版本与源码交接
主题版本以 `theme.yaml` 中的 `spec.version` 为准,当前集中交付版本为 **3.1.17**。对应的 Git 标签为 `3.1.17`,安装包与校验文件见 [3.1.17 发布页](https://gitea.witchercheung.cn/witcher/halo_theme_terminal/releases/tag/3.1.17)。
当前 Git 远程为 [自建仓库](https://gitea.witchercheung.cn/witcher/halo_theme_terminal)。版本变化见 [CHANGELOG.md](CHANGELOG.md);新会话接手先读 [HANDOFF.md](HANDOFF.md) 与 [PROJECT_CONTEXT.md](PROJECT_CONTEXT.md)。
## 原主题
- [Terminal](https://github.com/wan92hen/theme-terminal)
- [Hugo Terminal](https://github.com/panr/hugo-theme-terminal)