hexo-theme-stellar 1.34.0 → 1.35.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (22) hide show
  1. package/_config.yml +1 -10
  2. package/layout/_partial/head.ejs +0 -3
  3. package/layout/_partial/scripts/utils.ejs +1 -44
  4. package/layout/layout.ejs +0 -1
  5. package/package.json +4 -2
  6. package/scripts/events/index.js +2 -1
  7. package/scripts/events/lib/doc_tree.js +7 -4
  8. package/scripts/events/lib/merge_posts.js +3 -1
  9. package/scripts/events/lib/notebooks.js +5 -3
  10. package/scripts/events/lib/path_normalize.js +22 -0
  11. package/scripts/generators/search.js +3 -1
  12. package/scripts/helpers/json_ld.js +3 -2
  13. package/scripts/helpers/pretty_url.js +9 -10
  14. package/scripts/lib/path_utils.js +24 -0
  15. package/source/css/_plugins/index.styl +0 -3
  16. package/source/js/main.js +0 -4
  17. package/CLAUDE.md +0 -217
  18. package/docs/audits/2026-08-08-stellar-analysis.md +0 -267
  19. package/docs/release-process.md +0 -59
  20. package/layout/_plugins/pjax.ejs +0 -8
  21. package/source/css/_plugins/pjax.styl +0 -61
  22. package/source/js/plugins/pjax.js +0 -646
package/docs/audits/2026-08-08-stellar-analysis.md DELETED
@@ -1,267 +0,0 @@
1
- # Stellar 主题及 xaoxuu.com 项目全面分析报告
2
-
3
- > 审计日期：2026-08-08 | 版本：hexo-theme-stellar v1.33.1 | Hexo 7.0.0
4
-
5
- ## 一、项目概览
6
-
7
- | 维度 | 详情 |
8
- |------|------|
9
- | **站点** | `xaoxuu.com` 个人博客，Hexo 7.0.0 |
10
- | **主题** | `hexo-theme-stellar` v1.33.1（Git 子模块） |
11
- | **部署** | GitHub Actions → gh-pages + Vercel 边缘 |
12
- | **模板引擎** | EJS + Stylus |
13
- | **内容规模** | ~100 篇文章（2013-2026），wiki 文档、笔记系统 |
14
- | **语言** | zh-CN / en / zh-TW 多语言 |
15
-
16
- ---
17
-
18
- ## 二、高优先级问题清单（按紧急程度排序）
19
-
20
- ### P0 - 阻塞性/安全性问题
21
-
22
- #### 问题 1：缺少安全响应头（CSP / X-Frame-Options / X-Content-Type-Options）
23
-
24
- **场景**：当前 HTML 响应头中未设置任何安全策略头，站点对所有浏览器默认攻击面完全暴露。
25
-
26
- **影响范围**：全局，所有页面。
27
-
28
- **根因**：`layout/_partial/head.ejs` 模板中没有添加安全头部，`vercel.json` 也仅配置了缓存策略。
29
-
30
- **修复方向**：
31
- 1. 在 `layout/_partial/head.ejs` 中添加 `<meta http-equiv>` 级别的基础安全策略（作为最低保障）
32
- 2. 在 `vercel.json` 中添加 `Content-Security-Policy`、`X-Frame-Options: DENY`、`X-Content-Type-Options: nosniff` 响应头
33
-
34
- **复杂度**：低 | **建议时间**：1 周内
35
-
36
- ---
37
-
38
- #### 问题 2：Tag 插件存在 XSS 注入风险
39
-
40
- **场景**：多个 tag 插件在渲染用户可控内容（`alt`、`title`、`url` 参数）时直接拼接到 HTML 属性中，未做转义处理。
41
-
42
- **影响范围**：所有使用 tag 插件的页面。若结合友链等用户贡献内容存在被注入风险。
43
-
44
- **具体位置**：
45
-
46
- | 文件 | 行号 | 风险参数 |
47
- |------|------|----------|
48
- | `scripts/tags/lib/image.js` | L45 | `alt` 直接拼接 |
49
- | `scripts/tags/lib/frame.js` | L61 | `alt` 直接拼接 |
50
- | `scripts/tags/lib/folding.js` | L23 | `title` 通过 markdown 渲染但未过滤 HTML 标签 |
51
- | `scripts/tags/lib/link.js` | L52 | `title` 直接拼接 |
52
-
53
- **修复方向**：对所有用户可控的输出进行 `escape_html` 或等效转义处理后再嵌入 HTML。
54
-
55
- **复杂度**：中 | **建议时间**：2 周内
56
-
57
- ---
58
-
59
- #### 问题 3：`glob` 依赖未声明导致构建可能失败
60
-
61
- **场景**：`scripts/events/lib/get_image_ratios.js` L3 中 `require('glob')` 引入了 `glob` 包，但该包未在主题 `package.json` 或站点 `package.json` 中声明为依赖。当前能运行是因为 `gulp` 的传递依赖中存在 glob，但这是一个脆弱的巧合。
62
-
63
- **影响范围**：启用 `lazyload.fix_ratio` 功能的 `hexo server` 模式。在全新 `npm install --production` 环境下必然失败。
64
-
65
- **修复方向**：在 `themes/stellar/package.json` 的 `dependencies` 中添加 `"glob": "^10.x"`。
66
-
67
- **复杂度**：低 | **建议时间**：1 周内
68
-
69
- ---
70
-
71
- ### P1 - 严重影响可用性
72
-
73
- #### 问题 4：GitHub Actions 使用已弃用的 Node 16 actions
74
-
75
- **场景**：`.github/workflows/auto-deploy.yml` 中 `actions/checkout@v3` (L15) 和 `peaceiris/actions-gh-pages@v3` (L29) 均依赖 Node.js 16，GitHub 已宣布逐步弃用。
76
-
77
- **影响范围**：CI 自动部署流程将中断。
78
-
79
- **修复方向**：升级 `actions/checkout@v4` 和 `peaceiris/actions-gh-pages@v4`。
80
-
81
- **复杂度**：低 | **建议时间**：1 周内
82
-
83
- ---
84
-
85
- #### 问题 5：`document.execCommand("Copy")` 已弃用
86
-
87
- **场景**：`source/js/main.js` L40 中使用 `document.execCommand("Copy")` 实现复制功能，该 API 已被 W3C 标记为废弃，主流浏览器未来版本将移除。
88
-
89
- **影响范围**：所有页面的「复制代码」功能。
90
-
91
- **修复方向**：迁移到 `navigator.clipboard.writeText()` API。
92
-
93
- **复杂度**：低 | **建议时间**：2 周内
94
-
95
- ---
96
-
97
- #### 问题 6：构建后缺少 JS/CSS 压缩步骤
98
-
99
- **场景**：CI 流水线（`.github/workflows/auto-deploy.yml`）仅执行 `hexo generate`，未运行 gulpfile 中的 JS/CSS/HTML 压缩任务。而 `gulpfile.js` 配置了完整的压缩流程（babel + terser + cleanCSS + htmlmin）。
100
-
101
- **影响范围**：生产环境部署的静态资源未经压缩，JS 文件体积较大，直接影响首屏加载速度。
102
-
103
- **修复方向**：在 CI 的 "Generate Public Files" 步骤后、部署前添加 `npx gulp minify`。
104
-
105
- **复杂度**：低 | **建议时间**：1 周内
106
-
107
- ---
108
-
109
- #### 问题 7：首屏加载阻塞 — jQuery 和 Marked 同步加载
110
-
111
- **场景**：CSS 采用同步 `<link>` 加载（`layout/_partial/head.ejs` L190），jQuery（3.7）和 Marked（13.0）虽然以 `defer` 方式加载（`layout/_partial/scripts.ejs` L25），但 CSS 阻塞渲染的问题仍然存在，且大量 CDN 依赖增加了网络往返次数。
112
-
113
- **影响范围**：首屏加载时间可能超过 3 秒（尤其在 CDN 网络抖动时）。
114
-
115
- **修复方向**：
116
- 1. 将非首屏必需的 CSS 延迟加载
117
- 2. 考虑将核心 CSS 内联到 `<head>` 中
118
- 3. 为 CDN 资源添加 `dns-prefetch`（已部分实现 preconnect）
119
-
120
- **复杂度**：中 | **建议时间**：1 个月内
121
-
122
- ---
123
-
124
- ### P2 - 阻碍主题迭代
125
-
126
- #### 问题 8：无测试覆盖
127
-
128
- **场景**：主题 `package.json` 中 `"test": "echo test"`，零测试覆盖。tag 插件多达 40+ 个，任何修改都可能引入回归。
129
-
130
- **影响范围**：主题维护效率低，发布后经常出现回归问题。
131
-
132
- **修复方向**：至少为核心 tag 插件、配置合并逻辑、URL 生成逻辑添加单元测试。推荐使用 mocha + chai。
133
-
134
- **复杂度**：高 | **建议时间**：3 个月内逐步覆盖
135
-
136
- ---
137
-
138
- #### 问题 9：大型内联 SVG 造成代码膨胀
139
-
140
- **场景**：`scripts/tags/lib/chat.js` 文件 ~517 行中包含大量内联 SVG 数据（浏览器图标 ~10 个、文件类型图标 ~15 个），使得 tag 插件脚本体积显著增大。
141
-
142
- **影响范围**：每次 hexo generate 时都会加载这些数据到内存，构建性能受影响。
143
-
144
- **修复方向**：将 SVG 数据外置到独立 JSON/YAML 文件，通过 `require` 引用。
145
-
146
- **复杂度**：低 | **建议时间**：1 个月内
147
-
148
- ---
149
-
150
- #### 问题 10：主题内 `hexo-fs` 依赖未声明且未使用
151
-
152
- **场景**：`scripts/filters/lib/img_onerror.js` L8 中 `const fs = require('hexo-fs')` 声明了变量但未实际使用（该函数只用到 `this.theme.config.default.image`）。
153
-
154
- **影响范围**：轻微性能影响，且若 `hexo-fs` 在未来版本中行为变化可能引入问题。
155
-
156
- **修复方向**：移除未使用的 `require('hexo-fs')`。
157
-
158
- **复杂度**：低 | **建议时间**：1 周内
159
-
160
- ---
161
-
162
- ### P3 - 生产环境潜在风险
163
-
164
- #### 问题 11：无站点监控/告警机制
165
-
166
- **场景**：当前仅靠 GitHub Actions 构建成功后 curl 触发服务器更新。无任何可用性监控、无错误追踪、无流量异常告警。
167
-
168
- **影响范围**：站点故障时依赖用户反馈，恢复时间不可控。
169
-
170
- **修复方向**：接入 UptimeRobot 或类似免费监控服务，配置宕机告警。
171
-
172
- **复杂度**：低 | **建议时间**：2 周内
173
-
174
- ---
175
-
176
- #### 问题 12：`hexo-all-minifier` 安装但未启用
177
-
178
- **场景**：站点 `package.json` 中安装了 `hexo-all-minifier`，但 `_config.yml` 中 `all_minifier: false`。如果意外启用，可能和 gulp 压缩产生冲突。
179
-
180
- **修复方向**：若已使用 gulp 替代，应移除该依赖。
181
-
182
- **复杂度**：低 | **建议时间**：按需
183
-
184
- ---
185
-
186
- ## 三、快速修复建议（按工作量排序）
187
-
188
- | # | 问题 | 工作量 |
189
- |---|------|--------|
190
- | 1 | 移除 `img_onerror.js` 中未使用的 `hexo-fs` require | 5 min ~~已修复~~ |
191
- | 2 | 添加 `glob` 到 theme package.json dependencies | 5 min ~~已修复~~ |
192
- | 3 | 添加安全响应头 (vercel.json) | 15 min ~~已修复~~ |
193
- | 4 | 升级 GitHub Actions (`checkout@v4`, `gh-pages@v4`) | 5 min ~~已修复~~ |
194
- | 5 | 替换 `execCommand` 为 `navigator.clipboard` | 30 min ~~已修复~~ |
195
- | 6 | CI 中加入 `npx gulp minify` 步骤 | 10 min ~~已修复~~ |
196
- | 7 | Tag 插件 HTML 转义修复 | 2-4 h ~~已修复~~ |
197
-
198
- ---
199
-
200
- ## 四、主题 Stellar 后续核心优化方向
201
-
202
- | 方向 | 说明 | 优先级 |
203
- |------|------|--------|
204
- | **安全加固** | 添加 CSP 头、全量审查 tag 插件 HTML 输出转义 | 高 |
205
- | **性能优化** | CDN 依赖瘦身、CSS/JS 代码分割、字体子集化 | 高 |
206
- | **测试覆盖** | 建立 CI 测试流水线、核心功能回归测试 | 高 |
207
- | **Hexo 7+ 适配** | 验证所有 API 在 Hexo 7.x 下的兼容性 | 中 |
208
- | **PJAX 稳定化** | 完成 pjax 模式的兼容性修复并正式发布 | 中 |
209
- | **TypeScript 迁移** | 将 scripts/ 下 JS 逐步迁移到 TS，提升可维护性 | 低 |
210
- | **无障碍 (a11y)** | 检查 ARIA 标签、键盘导航支持 | 低 |
211
-
212
- ---
213
-
214
- ## 五、技术栈与依赖清单
215
-
216
- ### 站点 package.json
217
-
218
- | 依赖 | 版本 | 用途 |
219
- |------|------|------|
220
- | hexo | ^7.0.0 | 静态站点生成器 |
221
- | hexo-all-minifier | ^0.5.7 | 资源压缩（未启用） |
222
- | hexo-autonofollow | ^1.0.1 | 外链 nofollow |
223
- | hexo-deployer-git | ^4.0.0 | Git 部署 |
224
- | hexo-generator-feed | ^3.0.0 | RSS/Atom Feed |
225
- | hexo-generator-seo-friendly-sitemap | ^0.2.1 | SEO 站点地图 |
226
- | hexo-renderer-ejs | ^2.0.0 | EJS 渲染器 |
227
- | hexo-renderer-marked | ^6.2.0 | Markdown 渲染器 |
228
- | hexo-renderer-stylus | ^3.0.1 | Stylus CSS 预处理器 |
229
-
230
- ### 主题 package.json
231
-
232
- | 依赖 | 版本 | 用途 |
233
- |------|------|------|
234
- | cheerio | ^1.1.0 | HTML 解析 |
235
- | hexo-renderer-ejs | ^2.0.0 | EJS 渲染 |
236
- | hexo-renderer-stylus | ^3.0.1 | Stylus 渲染 |
237
- | probe-image-size | ^7.2.3 | 图片尺寸探测 |
238
- | glob（缺失） | - | 文件匹配（get_image_ratios.js） |
239
-
240
- ### 部署架构
241
-
242
- ```
243
- GitHub Push → GitHub Actions (auto-deploy.yml)
244
- ├─ checkout + submodules
245
- ├─ npm i + hexo generate
246
- ├─ deploy to gh-pages (peaceiris/actions-gh-pages)
247
- └─ curl hook → 服务器 pull 更新
248
- ```
249
-
250
- ### CDN 资源依赖
251
-
252
- | 资源 | CDN |
253
- |------|-----|
254
- | jQuery 3.7 | gcore.jsdelivr.net |
255
- | Marked 13.0 | gcore.jsdelivr.net |
256
- | Vanilla Lazyload 19.1 | gcore.jsdelivr.net |
257
- | Fancybox UI 5.0 | gcore.jsdelivr.net |
258
- | Swiper 10.3 | unpkg.com |
259
- | KaTeX 0.16.23 | cdn.jsdelivr.net |
260
- | MathJax 2.7.6 | cdnjs.cloudflare.com |
261
- | Mermaid v9 | gcore.jsdelivr.net |
262
- | Flying Pages 2 | gcore.jsdelivr.net |
263
- | Highlight.js 11.9 | gcore.jsdelivr.net |
264
-
265
- ---
266
-
267
- *报告生成时间：2026-08-08 | 分析工具：人工代码审查 + npm audit*
package/docs/release-process.md DELETED
@@ -1,59 +0,0 @@
1
- # 发版流程
2
-
3
- > 创建日期: 2026-08-08
4
-
5
- ## 概述
6
-
7
- Stellar 发版分两步：脚本完成版本号更新和推送 → CI 自动化完成 npm 发布和 tag 创建。
8
-
9
- ```
10
- npm-publish.sh → push main + npm → CI (.github/workflows/npm-publish.yml) → npm publish + git tag
11
- ```
12
-
13
- ## 前置条件
14
-
15
- - 当前在 `main` 分支，且已同步最新代码
16
- - 工作区无无关改动（仅允许 `_config.yml` 和 `package.json` 有未提交变更）
17
-
18
- ## 脚本功能
19
-
20
- `npm-publish.sh` 负责：
21
-
22
- 1. 更新 `_config.yml` → `stellar.version`
23
- 2. 更新 `package.json` → `version`
24
- 3. 更新 `_config.yml` 中 CDN URL 的版本号（jsdelivr）
25
- 4. `git add _config.yml package.json` + commit（`release: {version}`）
26
- 5. push main 分支 → rebase npm 分支 → push npm 分支
27
-
28
- ## CI 自动化
29
-
30
- push npm 分支后，[npm-publish.yml](../.github/workflows/npm-publish.yml) 自动触发：
31
-
32
- - 检测 commit message 匹配 `^release:\ (.*)`，提取版本号
33
- - 发布到 [npm](https://www.npmjs.com/package/hexo-theme-stellar)
34
- - 创建 Git tag（如 `1.33.2`）
35
-
36
- ## 使用方式
37
-
38
- ```bash
39
- # 正常发版（CI 自动处理 npm publish 和 tag）
40
- bash npm-publish.sh 1.33.2
41
-
42
- # 预览（仅显示变更，不提交/推送，执行后自动回滚）
43
- bash npm-publish.sh 1.33.2 --dry-run
44
- ```
45
-
46
- ## 发版 Checklist
47
-
48
- - [ ] 所有功能变更已合并到 main，且通过 `gulp minify` 验证
49
- - [ ] 通过 `bash npm-publish.sh <version> --dry-run` 检查版本号变更
50
- - [ ] 执行 `bash npm-publish.sh <version>` 推送
51
- - [ ] 等待 CI 完成（GitHub Actions → npm-publish workflow）
52
- - [ ] 验证 [GitHub Releases](https://github.com/xaoxuu/hexo-theme-stellar/releases) 有对应 tag
53
- - [ ] 验证 [npm 页面](https://www.npmjs.com/package/hexo-theme-stellar) 版本已更新
54
-
55
- ## 版本号规范
56
-
57
- - 格式: `x.y.z` 或 `x.y.z-rc.n`
58
- - Tag 格式: 不带 `v` 前缀（如 `1.33.2`，非 `v1.33.2`）
59
- - 仅 rc 测试版本和正式版本发布到 npm（CI 自动处理）
package/layout/_plugins/pjax.ejs DELETED
@@ -1,8 +0,0 @@
1
- <script>
2
- window.StellarPjaxConfig = {
3
- selectors: <%- JSON.stringify((conf.selectors || ['title', '#l_cover', '.l_body']).includes('#l_cover') ? (conf.selectors || ['title', '#l_cover', '.l_body']) : (conf.selectors || ['title', '#l_cover', '.l_body']).concat('#l_cover')) %>,
4
- timeout: <%= conf.timeout || 10000 %>,
5
- cacheBust: <%= conf.cacheBust || false %>
6
- };
7
- </script>
8
- <script src="<%- url_for('/js/plugins/pjax.js') %>" defer></script>
package/source/css/_plugins/pjax.styl DELETED
@@ -1,61 +0,0 @@
1
- // PJAX - Seamless page transitions
2
-
3
- // Custom easing for smooth, natural animations
4
- $pjax-easing = cubic-bezier(0.4, 0, 0.2, 1)
5
- $pjax-easing-out = cubic-bezier(0.16, 1, 0.3, 1) // Expo out - more elegant deceleration
6
- $pjax-duration = 0.4s
7
- $pjax-translate-distance = convert(hexo-config('plugins.pjax.translate-distance'))
8
-
9
- .page-loading-bar
10
- position: fixed
11
- top: 0
12
- left: calc(50% - 16px)
13
- width: 32px
14
- height: 32px
15
- display: none
16
- flex-direction: column
17
- align-items: center
18
- img
19
- height: 100%
20
- body.pjax-loading
21
- .page-loading-bar
22
- display: flex
23
-
24
- // Main content transition base
25
- .l_body .l_main, #l_cover
26
- transition: opacity $pjax-duration $pjax-easing, transform $pjax-duration $pjax-easing
27
-
28
- // Fade-in animation keyframes
29
- @keyframes pjax-fade-in
30
- 0%
31
- opacity: 0
32
- transform: translateY($pjax-translate-distance)
33
- 100%
34
- opacity: 1
35
- transform: translateY(0)
36
-
37
- // Loading state - content fades out and moves down slightly
38
- body.pjax-loading
39
- .l_body .l_main, #l_cover
40
- opacity: 0.4
41
- transform: translateY($pjax-translate-distance)
42
- pointer-events: none
43
-
44
- // Loaded state - content fades in with upward motion
45
- body.pjax-loaded
46
- .l_body .l_main, #l_cover
47
- animation: pjax-fade-in $pjax-duration $pjax-easing-out forwards
48
-
49
- // Respect reduced motion preferences
50
- @media (prefers-reduced-motion: reduce)
51
- .l_body .l_main, #l_cover
52
- transition: opacity $pjax-duration ease
53
- body.pjax-loading .l_body .l_main, body.pjax-loading #l_cover
54
- transform: none
55
- body.pjax-loaded .l_body .l_main, body.pjax-loaded #l_cover
56
- animation: pjax-fade-simple $pjax-duration ease forwards
57
- @keyframes pjax-fade-simple
58
- 0%
59
- opacity: 0
60
- 100%
61
- opacity: 1