hexo-theme-stellar 1.44.0 → 2.0.0-rc.1

package/CHANGELOG.md

@@ -1,5 +1,39 @@
 # Changelog
 
+## 2.0.0-rc.1
+
+> 发布日期：2026-09-07
+
+本节记录从最近公开版本 `1.44.0` 到当前候选文件树的净变化；开发期间已经被替换的中间方案不属于迁移契约。
+
+### 新功能
+
+- 配置、Collection YAML 与页面 Front Matter 采用声明式严格 Schema；默认配置、校验、JavaScript 投影和 Reference 由同一字段事实生成，Doctor 在构建前给出带来源和字段路径的诊断。
+- 新增 Post、Topic、Wiki、Notebook、Note 与索引页共享的 Collection/PageViewModel 管线，并以 `listed/searchable` 分离聚合展示和搜索收录。
+- 页面外壳统一为 Topbar、Leftbar、Rightbar Region，Brand、Menu、Widget、Footer 和 13 个 Profile 使用结构化配置与明确的覆盖语义。
+- 新增 `card/glass/minimal/flat` 外观预设、明暗模式切换、颜色／渐变／排版／形状／背景设置，以及独立设置页。
+- 浏览器功能改为原生 ESM Runtime Manifest 和按 DOM 命中加载的 Extension；搜索、评论、Feature、数据服务及请求缓存拥有明确生命周期。
+- Wiki Hero 支持 `ferrofluid`、`galaxy`、`light-rays` 三种可选背景效果，效果与静态图片可叠加；标签目录新增 `gist`。
+- 新增 `hexo stellar doctor` 与 `hexo stellar new note`；目录驱动的完整 Blueprint 改由 Stellar Examples 仓库维护。
+
+### 行为、样式与工程变化
+
+- Article 与 Notebook 的列表、横幅、许可、分享、标签和排序默认值收敛到内容模型；Collection 内容默认关闭分享，Notebook 与其它 Collection 使用一致的覆盖规则。
+- 侧栏集合、Navbar、Dropdown、Grid、文章卡片、下载按钮和 Topbar 对齐使用统一的 UI capability、形状与状态反馈。
+- 运行环境升级为 Node.js 22+、Hexo 8+；构建、包集成、性能、知识库、贡献注册表和复用规则各自拥有独立门禁。
+- 发布流程原子同步 `package.json`、`package-lock.json` 与安装知识库的版本，并把未跟踪文件纳入工作区门禁，避免候选包、锁文件或临时产物漂移；稳定版写入 npm `latest`，RC 写入 `rc` dist-tag。
+- 主题仓库只保留长期指南、当前知识库和阶段审计；单次方案、迁移中间态及已被最终实现取代的测试／兼容残留不进入发布文件树。
+
+### 升级注意（配置变更与破坏性改动）
+
+- v1 的 `logo/menubar/site_tree/style/tag_plugins/plugins/data_services` 等结构不会被兼容读取；请按[公开迁移说明](https://xaoxuu.com/wiki/stellar/migration/v1-to-v2/)逐项迁移到 `topbar/leftbar/rightbar/footer/profiles/appearance/tags/features/services`。
+- Collection 与 Front Matter 需要迁移为 `collection/route/navigation/listing/visibility/banner/article/comments/render/seo` 等分组字段；未知字段、错误类型与非法枚举会在构建早期失败。
+- `about`、`users` 标签以及对应的 `chat_users.yml`、`fcircle` 适配器已移除；`tip` 改为单标签 `{% tip 词句 pop:注解 %}`，`quot` 支持直接图标键与 `color`。
+- 浏览器后处理必须原样保留 `public/js/runtime/**/*.js` 的 ESM 语义、相对 import 与 JavaScript MIME 类型。
+- v2 当前源码从仓库 `main` 安装并需要执行 `npm install --prefix themes/stellar`；npm 包是否为 v2 以实际公开版本为准。
+
+Full Changelog: [1.44.0...main](https://github.com/xaoxuu/hexo-theme-stellar/compare/1.44.0...main)
+
 ## 1.44.0
 
 > 发布日期：2026-08-21
@@ -104,18 +138,18 @@ Full Changelog: [1.42.0...1.42.1](https://github.com/xaoxuu/hexo-theme-stellar/c
 ### 重构
 - 移除已失效的 auto_banner（Unsplash 自动横幅）与 `poster` 配置
 - 页面横幅上块重构为显式两行结构（面包屑 + 阅读时长/AI 标签 + 日期行）
-- 评论数图标统一使用 `default:tocomment`，移除 `weibo:comment`
+- 评论数图标统一使用 `default:to-comment`，移除 `weibo:comment`
 
 ### 其他
 - 移除知识库合并版 `知识库全量.md`，知识库以领域页面为唯一事实源
-- 新增 AI 规范引用一致性检查（check-spec-refs）与发版前提交登记完整性检查（随 `npm run check` 执行）
+- 新增 AI 规范引用一致性检查与发版前提交登记完整性检查（随 `npm run check` 执行）
 
 ### 升级注意（配置变更与破坏性改动）
 - 移除 `article.auto_banner`（Unsplash 自动横幅已失效）与文章 front-matter `poster`（`headline` / `topic` / `caption`）；`poster.color` / `banner_info.color` 显式文字颜色不再生效，由自适应文字颜色接管
 - 新增 `article.card_style`（`hero` 默认 / `classic`）：未显式设置的站点保持 hero 卡片样式
 - 新增 `plugins.adaptive_text`（默认 `enable: true`）：页面存在 `[data-text-adaptive]` 元素时才按需加载，文字颜色默认随背景自适应
 - 删除间距令牌 `--gap-margin` / `--gap-padding` / `--gap-max`，替换为 `--gap-base`（组件内部间距）与 `--gap-page`（页面级留白）；引用旧令牌的自定义 CSS 需迁移
-- `weibo:comment` 图标已移除，评论数图标统一使用 `default:tocomment`；自定义中引用了 `weibo:comment` 的站点请改用 `default:tocomment`
+- `weibo:comment` 图标已移除，评论数图标统一使用 `default:to-comment`；自定义中引用了 `weibo:comment` 的站点请改用 `default:to-comment`
 - 知识库合并版 `知识库全量.md` 移除（RAG 可直接索引领域页面）
 
 Full Changelog: [1.41.0...main](https://github.com/xaoxuu/hexo-theme-stellar/compare/1.41.0...main)
@@ -290,7 +324,7 @@ Full Changelog: [1.37.0...1.38.0](https://github.com/xaoxuu/hexo-theme-stellar/c
 
 ### 其他
 - CHANGELOG.md 历史数据一次性从 GitHub Releases API 同步入库（76 个版本，统一格式）
-- 新增发版流程文档（docs/guides/release-process.md）与设计记录（docs/designs/2026-08-09-release-automation.md）
+- 新增发版流程文档（docs/guides/release-process.md）并完善发布自动化记录
 
 Full Changelog: [1.36.0...1.37.0](https://github.com/xaoxuu/hexo-theme-stellar/compare/1.36.0...1.37.0)
 
@@ -336,7 +370,7 @@ Full Changelog: [1.35.0...1.36.0](https://github.com/xaoxuu/hexo-theme-stellar/c
 - 统一 URL 路径规范化逻辑，修复 canonical 标签路径不一致的问题
 - 修复 wiki 文档树中索引页（index）的路径匹配错误
 - 发版脚本迁移为 Node CLI（release.js），支持版本校验、dry-run 预览与二次确认
-- 完善仓库 AI 协作规范（AGENTS.md、issue 处理规则），重组 docs 目录（designs/、guides/、audits/）
+- 完善仓库 AI 协作规范（AGENTS.md、issue 处理规则），重组 docs 中的长期指南与审计记录
 - 优化 npm 发布忽略规则（.npmignore）
 
 Full Changelog: [1.34.0...1.35.0](https://github.com/xaoxuu/hexo-theme-stellar/compare/1.34.0...1.35.0)

package/CONTRIBUTING.md

@@ -1,155 +1,64 @@
 # 贡献指南
 
-感谢你考虑为 [Stellar](https://github.com/xaoxuu/hexo-theme-stellar) 贡献代码或文档！Stellar 是一个功能强大的综合型 Hexo 主题，内置博客、知识库、专栏、笔记四大系统，并提供丰富的标签组件与动态数据组件。
+感谢你考虑为 [Stellar](https://github.com/xaoxuu/hexo-theme-stellar) 贡献代码或文档。本指南只保留贡献者需要的入口；工程规则以 [AGENTS.md](AGENTS.md) 为准，主题使用方法见 [Wiki 文档](https://xaoxuu.com/wiki/stellar/)。
 
-本指南面向开发者，描述从环境准备、开发、验证到提交 PR 的完整流程；主题仓库的 AI 协作规范（唯一权威）见 [AGENTS.md](AGENTS.md)。使用上的问题请先查阅 [Wiki 文档](https://xaoxuu.com/wiki/stellar/)。
-
-## 仓库与职责边界
+## 仓库边界
 
 | 仓库 | 职责 |
-|------|------|
-| [hexo-theme-stellar](https://github.com/xaoxuu/hexo-theme-stellar) | 主题代码（`layout/`、`scripts/`、`source/`）、国际化（`languages/`）、主题文档（`docs/`）、版本发布 |
-| [xaoxuu.com 主工程](https://github.com/xaoxuu/xaoxuu.com) | 博客站点，以 git submodule 方式引用本主题；只更新子模块指针，不包含主题源码 |
-| [hexo-theme-stellar-docs](https://github.com/xaoxuu/hexo-theme-stellar-docs) | Wiki 文档内容（对应 xaoxuu.com/wiki/stellar/） |
-| [hexo-theme-stellar-examples](https://github.com/xaoxuu/hexo-theme-stellar-examples) | 官方示例工程（`blog` 博客场景、`docs` 文档场景），用于集成开发与验证 |
-
-主题无法单独运行，开发调试需要在主工程或官方 demo 工程中集成。
+| --- | --- |
+| [hexo-theme-stellar](https://github.com/xaoxuu/hexo-theme-stellar) | 主题代码、默认配置、国际化、主题工程文档与版本发布 |
+| [hexo-theme-stellar-examples](https://github.com/xaoxuu/hexo-theme-stellar-examples) | 官方博客与文档场景，用于需要宿主环境的集成验证 |
 
-## 环境准备
+主题仓库不维护具体站点的内容、配置、版本引用或部署规则。只有任务需要宿主页面且仓库内证据不足时，才使用示例工程或任务指定的消费站点。
 
-```yaml
-Hexo: 6.3.0 ~ latest（已验证至 8.1.2）
-hexo-cli: 4.3.0 ~ latest
-node: >= 22 # 建议选择 LTS 版本
-npm: >= 10
-```
+## 准备环境
 
-推荐使用官方 demo 工程集成开发：
+公开兼容范围以 [README.md](README.md) 为准，当前开发命令以 [package.json](package.json) 为准，CI 使用的 Node.js 版本以 [.github/workflows/ci.yml](.github/workflows/ci.yml) 为准，避免在多处复制版本矩阵。
 
-1. Fork 本仓库并克隆到本地。
-2. 克隆 [hexo-theme-stellar-examples](https://github.com/xaoxuu/hexo-theme-stellar-examples)，将你的主题副本放到 `blog/themes/stellar`（或 `docs/themes/stellar`）。
-3. 在 demo 工程中执行 `npm install`，然后按需 `npx hexo generate` / `npx gulp minify` 构建验证。
-
-也可以使用 git submodule 将主题挂载到自己的博客或主工程：
+需要宿主环境时，推荐克隆官方示例工程，将主题副本放入 `blog/themes/stellar` 或 `docs/themes/stellar`，在对应示例目录安装依赖并构建。也可以把主题作为 submodule 挂载到自己的 Hexo 站点：
 
 ```bash
 git submodule add https://github.com/<your-name>/hexo-theme-stellar.git themes/stellar
 ```
 
-## 开发流程
-
-每个功能或修复请按以下顺序推进，产物保留在仓库中。
-
-### 1. 方案
-
-在 `docs/designs/{YYYY-MM-DD}-{功能简称}/` 下创建方案文档（模板见 `docs/designs/_template/`），包含 `spec.md` / `plan.md` / `checklist.md`，写明：
-
-- 要解决的问题或新增的能力
-- 技术方案和实现思路
-- 影响范围（涉及哪些文件 / 模块）
-- 需要同步的知识库页面与文档
-
-### 2. 实施
+## 开发与验证
 
-新增功能覆盖全部相关维度：
+开始前阅读 [AGENTS.md](AGENTS.md)，确认任务边界和最低充分验证级别。常用专项指南：
 
-| 维度 | 目录 | 说明 |
-|------|------|------|
-| 模板 | `layout/` | EJS 模板与可复用 partial |
-| 服务端脚本 | `scripts/` | Hexo 标签 / 辅助函数 / 过滤器 |
-| 样式 | `source/css/` | Stylus 样式 |
-| 浏览器脚本 | `source/js/` | ES2015+ 源码（Gulp Babel 转译输出） |
-| 国际化 | `languages/` | 新增文案时同步 |
-| 文档 | `docs/` | 方案 + 执行计划 + 测试记录 + 知识库同步 |
+- 新增或重构标签插件：[标签插件开发规范](docs/guides/tag-plugins-style-guide.md)
+- 修改配置、内容 profile、组件、Extension 或语言文案：[贡献架构指南](docs/guides/contribution-architecture.md)
 
-### 3. 文档与知识库同步
+公开 v2 文档按[入门](https://xaoxuu.com/wiki/stellar/start/install/)、[配置参考](https://xaoxuu.com/wiki/stellar/reference/theme/)和[行为参考](https://xaoxuu.com/wiki/stellar/reference/behavior/)组织。维护使用方迁移说明时核对 [AI 迁移契约](https://xaoxuu.com/wiki/stellar/migration/ai/)；旧公开入口由文档仓库的映射表和消费站点跳转实现承接。
 
-涉及主题代码、配置或行为变化时，必须同步更新 `docs/knowledge/` 并在 `docs/knowledge/VERIFICATION.md` 登记；涉及逻辑变更（API、配置项、行为变化）同时更新仓库 Wiki。
+先运行最接近改动的检查；需要全仓证据时运行 `npm run check`。所有可用脚本及其当前组合以 `package.json` 为准。宿主构建、视觉检查和分发验收只在任务影响这些契约时补充。
 
-## 编码规范摘要
+机器契约与直接测试随实现更新；知识库、CHANGELOG 和版本级 `VERIFICATION.md` 在发版准备时按最终净变化集中同步。
 
-完整规范见 `AGENTS.md` §4，核心要求：
-
-- **EJS 模板**：`<%- %>` 输出非转义 HTML；变量声明用 `var`（IE8 兼容）；2 空格缩进；HTML 属性双引号；复杂逻辑提取到 `helpers/`
-- **Node 脚本**：CommonJS（`require()` / `module.exports`）；文件头 `/* global hexo */` + `'use strict';`；2 空格缩进、双引号、分号结尾
-- **Stylus 样式**：类名和文件名 `kebab-case`；变量在 `_defines/`，通用样式在 `_common/`，组件在 `_components/`；2 空格缩进
-- **浏览器 JS**：ES2015+ 语法；避免直接操作 DOM，使用主题工具函数
-- **不引入新构建系统**，保持 Hexo 原生 + Gulp 后处理；CSS 兼容 IE8，JS 兼容 ES2015+
-- 新增或重构标签插件时，先阅读 `docs/guides/tag-plugins-style-guide.md`
-
-## 测试与验证
-
-在主题仓库根目录执行：
-
-```bash
-npm run lint       # ESLint
-npm test           # node:test 单测
-python3 docs/knowledge/tools/verify.py   # 知识库硬事实核查
-npm run check      # 一键执行 lint + 单测 + 知识库核查
-```
-
-修改 `scripts/` 后**必须**在主工程（xaoxuu.com）执行全量验证：
-
-```bash
-npm run g          # hexo clean && hexo generate && npx gulp minify
-```
-
-> `npm run s`（本地按需渲染）不能替代全量验证。UI 方面（样式、模板、前端交互）改动量不大时无需执行自检流程，除非用户明确要求。
-
-新增 / 修改纯函数时请补充单元测试。
-
-## 提交规范
-
-使用 Conventional Commits，一次提交对应一个需求点（逻辑相似的需求可以合并）：
-
-```
-<type>(<scope>): <description>
-```
-
-`type` 白名单（完整规则以 `ci/check-commit-msg.js` 为准）：`feat` / `fix` / `refactor` / `perf` / `style` / `docs` / `chore` / `content` / `release`。
-
-- 任务完成后**不自动提交**：改动保留在工作区供审查
-- 只有明确要求时才 push
-- 发版流程除外（见下文）
+跨域架构、迁移、兼容、发布计划或其它需要持久化的设计方案统一使用 GitHub issue，正文应包含问题、决策、影响范围和验收标准；具体约定见 [Issue tracker](docs/agents/issue-tracker.md)。仓库不接收单次设计方案或其本地归档。
 
 ## 提交 Pull Request
 
-按 [PULL_REQUEST_TEMPLATE.md](.github/PULL_REQUEST_TEMPLATE.md) 填写 PR：
-
-- **变更说明**：描述解决的问题或新增能力，附相关 issue 编号（如有）
-- **改动范围**：勾选涉及维度（`layout/`、`scripts/`、`source/css/`、`source/js/`、`languages/`、`docs/`）
-- **验证清单**：确认 lint / 单测 / 全量构建 / 知识库同步等已通过
+按 [PULL_REQUEST_TEMPLATE.md](.github/PULL_REQUEST_TEMPLATE.md) 描述：
 
-CI 会在 PR 上强制执行以下检查，全部通过后才可合并：
+- 解决的问题、行为变化和相关 issue；
+- 受影响的公开契约或内部模块；
+- 实际执行的验证及结果；
+- 尚需人工确认的页面、兼容性或发布事项。
 
-| 检查 | 内容 |
-|------|------|
-| Lint | ESLint |
-| Unit tests | node:test 单测 |
-| Conventional Commits | 提交信息符合规范 |
-| Skill mirror sync | `.agents/` 与 `.claude/` 技能镜像一致 |
-| Spec refs | AGENTS.md 章节引用与关键措辞一致性 |
-| Integration build | 官方 demo 全量构建（hexo generate）+ Gulp minify |
-| Knowledge base verify | `docs/knowledge/tools/verify.py` 硬事实核查 |
+提交信息使用 Conventional Commits，具体允许格式以 `ci/check-commit-msg.js` 为准。CI 的当前作业与触发条件以 [.github/workflows/ci.yml](.github/workflows/ci.yml) 为准。
 
 ## 发版
 
-发版由维护者（或明确授权的贡献者）执行，一键全自动：
-
-```bash
-npm run release -- <version> --yes
-```
-
-发版前需在 `CHANGELOG.md` 准备好对应版本的非空章节（H2 版本号 + H3 分类），脚本校验通过后自动更新版本号、推送并触发 CI 完成 npm 发布、tag 与 GitHub Release。完整流程见 [docs/guides/release-process.md](docs/guides/release-process.md)。
+发版由维护者或明确授权的贡献者执行。准备 CHANGELOG、确认版本并运行脚本的完整流程见 [发版流程](docs/guides/release-process.md)；普通贡献不要提前维护发布快照。
 
 ## 社区与支持
 
-- [Issues](https://github.com/xaoxuu/hexo-theme-stellar/issues)：技术问题答疑、BUG 反馈
-- [Discussions](https://github.com/xaoxuu/hexo-theme-stellar/discussions)：论坛、相关话题讨论
-- [探索号](https://xaoxuu.com/wiki/stellar/articles/)：文章收录
-- [社区支持页面](https://xaoxuu.com/wiki/stellar/contributors/)：开发者列表、社区渠道与提问建议
+- [Issues](https://github.com/xaoxuu/hexo-theme-stellar/issues)：BUG 反馈与技术问题
+- [Discussions](https://github.com/xaoxuu/hexo-theme-stellar/discussions)：社区讨论
+- [探索号](https://xaoxuu.com/wiki/stellar/support/articles/)：文章收录
+- [社区支持页面](https://xaoxuu.com/wiki/stellar/support/contributors/)：贡献者与交流渠道
 
-无论在什么渠道提问，建议先学习[「提问的智慧」](https://github.com/ryanhanwu/How-To-Ask-Questions-The-Smart-Way/blob/main/README-zh_CN.md)，描述清楚问题现象、尝试过程与报错信息，能帮助大家更高效地解决你的问题。
+提问时请说明现象、复现步骤、尝试过程与报错信息。
 
 ## 许可
 

package/README.md

@@ -2,112 +2,113 @@
 
 [简体中文](README.md) · [English](README_EN.md)
 
+一个博客，也是一套可以长期生长的内容系统。
+
+从一篇文章开始。以后想加项目文档、专栏或笔记，仍然在同一个站点里写。
+
+[创建第一个博客](https://xaoxuu.com/wiki/stellar/start/install/) · [蓝图与展示墙](https://xaoxuu.com/wiki/stellar/support/examples/) · [完整文档](https://xaoxuu.com/wiki/stellar/)
+
+> Stellar v2 当前版本为 `2.0.0-rc.1`；是否已经公开发布，以 npm 页面和 GitHub Releases 为准。
+
 [![npm](https://img.shields.io/npm/v/hexo-theme-stellar)](https://www.npmjs.com/package/hexo-theme-stellar)
 [![license](https://img.shields.io/github/license/xaoxuu/hexo-theme-stellar)](https://github.com/xaoxuu/hexo-theme-stellar/blob/main/LICENSE)
 [![stars](https://img.shields.io/github/stars/xaoxuu/hexo-theme-stellar)](https://github.com/xaoxuu/hexo-theme-stellar)
 [![npm downloads](https://img.shields.io/npm/dm/hexo-theme-stellar)](https://www.npmjs.com/package/hexo-theme-stellar)
 [![release](https://img.shields.io/github/v/release/xaoxuu/hexo-theme-stellar)](https://github.com/xaoxuu/hexo-theme-stellar/releases)
 
-Stellar 是一个「博客 + 知识库一体」的 Hexo 主题：简约商务美学之下，内置博客、Wiki、专栏、笔记四大内容系统与丰富的标签、动态数据组件，开箱即用。
-
-可以只把它当作一个轻博客主题使用——安装启用即可写文章；Wiki 知识库、专栏、笔记与动态数据组件都按需启用，随着你的内容需求自然生长。
-
-## 为什么选择 Stellar
-
-### 四大内容系统，一体化整合
+## 内容多起来，也不用推倒重来
 
-- **博客系统**：支持技术 / 生活两种文章布局，分类、标签、分页与相关文章一应俱全；只想写博客时，它就是一个开箱即用的轻博客。
-- **Wiki 文档系统**：既可以展示多个项目文档，也可以作为个人知识库，项目树、小节与层级导航开箱即用。
-- **专栏系统**：系列文章集中管理，提供沉浸式的连续阅读体验。
-- **笔记本系统**：三层架构与标签树导航，方便地梳理、归档和检索笔记。
+普通文章照常发布。项目需要一套稳定目录时，用 Wiki；几篇文章写成了系列，收进专栏；零散知识想长期补充，放进笔记本。
 
-四套系统与动态数据组件一体化整合，无需拼装多个插件。
+博客、Wiki、专栏和笔记本共享同一套导航、搜索、侧栏与阅读体验。只写博客时，其它系统不会跑出来打扰你。
 
-### 富表达标签组件
+## 静态博客，也能放一些活的内容
 
-内置大量灵活而强大的标签组件——提示框、折叠、标签页、时间线、图库、图标、表情、高亮、OKR、聊天、表格等，互相之间可以自由混搭嵌套，让内容表达不再受 Markdown 语法限制。详见[标签组件文档](https://xaoxuu.com/wiki/stellar/tag-plugins/)。
+动态时间线、自动友链、远程 README、GitHub 仓库与贡献者、评分和投票都可以按需接入。博客仍然是静态文件，但经常变化的内容不必每次都跟着整站重新部署。
 
-### 动态数据组件
+远程服务不会挡住正文先显示。接口暂时不可用时，文章仍然可以读。
 
-静态博客也能拥有动态能力，内容更新无需重新部署：
+## 写作、检索和阅读是一件事
 
-- **动态时间线**：像发朋友圈一样发布短文，也可以订阅他人的时间线。
-- **自动化友链**：自动检测友链状态、打标签、订阅友链文章。
-- **远程 Markdown 渲染**：例如直接渲染项目仓库的 README，避免重复维护。
-- **GitHub 仓库 / 贡献者卡片、评分、投票、最新评论**等数据组件，按需加载，不拖慢首屏。
-- **社区文化**：可以订阅「探索号」时间线数据源，获取社区用户的宝贵经验分享。
+提示框、折叠、标签页、图库、时间线、聊天和表格等内容组件可以互相组合。Markdown 表达不够时，不需要临时拼一套风格各异的插件。
 
-### 体验与性能
+本地搜索由主题生成索引，结果可以直接落到文章章节；桌面端目录和信息栏到了手机上会变成抽屉，把位置让给正文。
 
-- **模块化设计**：内置多种高复用性小组件，左右侧边栏自由搭配，布局随心。
-- **设计令牌驱动的样式系统**：统一的设计语言、深色模式与移动端响应式适配。
-- **图片懒加载**按原图比例预留占位，不会出现高度跳变，体验更佳。
-- 可选插件按需启用：代码高亮与复制、KaTeX / MathJax 数学渲染、Mermaid 图表、Fancybox 灯箱、Swiper 轮播等。
-- **本地搜索**：内置索引生成器，结果按章节展示，点击直达锚点并高亮关键词。
-- **SEO 完备**：JSON-LD 结构化数据、Open Graph、canonical 与克隆站检测，保护原创内容。
-- **一站多作者**：可以为不同文章指定不同作者，每位作者都有专属主页。
+[内容组件](https://xaoxuu.com/wiki/stellar/reference/tags/) · [站内搜索](https://xaoxuu.com/wiki/stellar/guides/search/) · [外观与排版](https://xaoxuu.com/wiki/stellar/guides/appearance/)
 
-以上功能都可以在[文档](https://xaoxuu.com/wiki/stellar/)中找到详细的使用方法。
+> 如果你只想写博客，它不会逼你理解这些系统；内容真的多起来时，它们已经在那里了。
 
-## 示例与展示
+## 选择一个起点
 
-- 示例源码：[hexo-theme-stellar-examples](https://github.com/xaoxuu/hexo-theme-stellar-examples/)（`blog` 博客场景、`docs` 文档场景），可直接 fork 起步
-- 展示墙：[使用 Stellar 主题的博客](https://xaoxuu.com/wiki/stellar/examples/)
+| 示例 | 适合什么样的站点 |
+| --- | --- |
+| 留白 · Light Blog | 安静写长文、随笔和生活记录 |
+| 星迹 · Blog | 使用经典侧栏整理文章、分类与专栏 |
+| 个人知识库 · Knowledge | 把博客、项目资料和长期主题放在一起 |
+| 项目文档 · Docs | 给一个项目维护清晰的文档目录 |
 
-[![Star History Chart](https://star-history.dera.page/svg?repos=xaoxuu/hexo-theme-stellar&type=date&legend=top-left)](https://star-history.dera.page/#xaoxuu/hexo-theme-stellar&type=date&legend=top-left)
+示例源码在 [hexo-theme-stellar-examples](https://github.com/xaoxuu/hexo-theme-stellar-examples/)。
 
 ## 快速开始
 
 ### 环境要求
 
 ```yaml
-Hexo: 6.3.0 ~ latest（已验证至 8.1.2）
+Hexo: '>= 8'
 hexo-cli: 4.3.0 ~ latest
-node: >= 22 # 建议选择 LTS 版本
-npm: >= 10
+node: '>= 22'
+npm: '>= 10'
 ```
 
-### 安装
+### 使用最新源码
 
-在博客根目录执行：
+在博客根目录添加主题源码并安装依赖：
 
 ```bash
-npm install hexo-theme-stellar
+git submodule add -b main https://github.com/xaoxuu/hexo-theme-stellar.git themes/stellar
+npm install --prefix themes/stellar
 ```
 
-### 配置
-
-编辑 `_config.yml`，启用主题：
+然后在博客 `_config.yml` 中启用主题：
 
 ```yaml
 theme: stellar
 ```
 
-### 从轻博客开始
+运行 Doctor 和生成：
 
-配置完成后即可发布文章。Wiki、专栏、笔记本与动态数据组件按需启用，文档中均有详细说明；也可以直接参考示例仓库的 `blog` 场景快速搭建。
+```bash
+npx hexo stellar doctor
+npx hexo generate
+```
 
-## 使用文档
+完整步骤见[环境与安装](https://xaoxuu.com/wiki/stellar/start/install/)和[创建第一个站点](https://xaoxuu.com/wiki/stellar/start/first-site/)。
 
-完整文档请见：https://xaoxuu.com/wiki/stellar/
+### 使用 npm 公开稳定版
 
-> AI 文档：https://deepwiki.com/xaoxuu/hexo-theme-stellar/
+```bash
+npm install hexo-theme-stellar
+```
 
-- 更新日志：[CHANGELOG.md](https://github.com/xaoxuu/hexo-theme-stellar/blob/main/CHANGELOG.md) · [Releases](https://github.com/xaoxuu/hexo-theme-stellar/releases)
+这条命令不保证安装到 v2。复制 v2 配置前，请先运行 `npm ls hexo-theme-stellar` 核对实际版本。
 
-### 常用文档
+## 文档
 
-- [标签组件](https://xaoxuu.com/wiki/stellar/tag-plugins/)
-- [主题配置](https://xaoxuu.com/wiki/stellar/theme-settings/)
-- [Wiki 系统](https://xaoxuu.com/wiki/stellar/wiki-settings/)
-- [专栏与笔记](https://xaoxuu.com/wiki/stellar/topic/)
+- [从第一篇文章开始](https://xaoxuu.com/wiki/stellar/start/first-site/)
+- [把博客变成自己的样子](https://xaoxuu.com/wiki/stellar/start/configuration/)
+- [用 Wiki 写项目文档](https://xaoxuu.com/wiki/stellar/guides/wiki/)
+- [把文章整理成专栏](https://xaoxuu.com/wiki/stellar/guides/topic/)
+- [建立自己的笔记本](https://xaoxuu.com/wiki/stellar/guides/notebook/)
+- [主题配置参考](https://xaoxuu.com/wiki/stellar/reference/theme/)
+- [从 v1 迁移到 v2](https://xaoxuu.com/wiki/stellar/migration/v1-to-v2/)
 
-## 反馈
+## 社区
 
-- 提交 Issues：https://github.com/xaoxuu/hexo-theme-stellar/issues/
-- 参与讨论：https://github.com/xaoxuu/hexo-theme-stellar/discussions/
-- 贡献指南：[CONTRIBUTING.md](CONTRIBUTING.md) · [Wiki 贡献页](https://xaoxuu.com/wiki/stellar/contributors/)
+- [Issues](https://github.com/xaoxuu/hexo-theme-stellar/issues/)：反馈可以复现的问题
+- [Discussions](https://github.com/xaoxuu/hexo-theme-stellar/discussions/)：交流使用经验和想法
+- [蓝图与展示墙](https://xaoxuu.com/wiki/stellar/support/examples/)：看看不同的人怎样使用 Stellar
+- [贡献指南](CONTRIBUTING.md)：参与主题开发与文档维护
 
 ## 开源许可
 
-本项目采用 [MIT License](LICENSE)，Copyright (c) 2021 xaoxuu，永久开源、完全免费。
+Stellar 使用 [MIT License](LICENSE)，Copyright (c) 2021 xaoxuu，永久开源、完全免费。第三方组件及其许可证见[第三方授权声明](legal/THIRD-PARTY-NOTICES.md)。

package/README_EN.md

@@ -1,113 +1,83 @@
-# Stellar - Your Own Independent Blog
+# Stellar — a blog that can grow with your work
 
 [English](README_EN.md) · [简体中文](README.md)
 
+Stellar can begin as a quiet personal blog and grow into a home for your articles, project documentation, series, and notes.
+
+[See the examples](https://xaoxuu.com/wiki/stellar/support/examples/) · [Getting started](https://xaoxuu.com/wiki/stellar/start/install/) · [Chinese documentation](https://xaoxuu.com/wiki/stellar/)
+
+> The current Stellar v2 version is `2.0.0-rc.1`. Check npm and GitHub Releases for its public availability.
+
 [![npm](https://img.shields.io/npm/v/hexo-theme-stellar)](https://www.npmjs.com/package/hexo-theme-stellar)
 [![license](https://img.shields.io/github/license/xaoxuu/hexo-theme-stellar)](https://github.com/xaoxuu/hexo-theme-stellar/blob/main/LICENSE)
 [![stars](https://img.shields.io/github/stars/xaoxuu/hexo-theme-stellar)](https://github.com/xaoxuu/hexo-theme-stellar)
 [![npm downloads](https://img.shields.io/npm/dm/hexo-theme-stellar)](https://www.npmjs.com/package/hexo-theme-stellar)
-[![release](https://img.shields.io/github/v/release/xaoxuu/hexo-theme-stellar)](https://github.com/xaoxuu/hexo-theme-stellar/releases)
-
-Stellar is a Hexo theme that unifies blogging and knowledge base in one place. Beneath its clean, business-style aesthetics lie four built-in content systems — Blog, Wiki, Topic, and Notebook — plus a rich collection of tag plugins and dynamic data widgets, ready to use out of the box for every kind of expression.
-
-You can also use it as a lightweight blog theme from day one: install, enable, and start writing. Wiki, Topic, Notebook, and dynamic data widgets are all enabled on demand, growing naturally with your content needs.
-
-## Why Stellar
 
-### Four Content Systems, Integrated in One
+## Four kinds of content, one site
 
-- **Blog**: Two article layouts (tech / story) offer different reading experiences, with categories, tags, pagination, and related posts — use it as a lightweight blog right away if that's all you need.
-- **Wiki**: Showcase multiple project documentations or use it as your personal knowledge base, with project trees, sections, and hierarchical navigation.
-- **Topic**: Manage series of articles with an immersive, continuous reading experience.
-- **Notebook**: A three-layer architecture with a tag tree to organize, archive, and retrieve notes with ease.
+Publish regular blog posts as usual. Give a project its own Wiki when it needs stable navigation. Keep a series of posts together as a Topic, or collect smaller pieces of knowledge in a Notebook.
 
-All four systems and dynamic widgets are integrated out of the box — no need to assemble multiple plugins.
+They share the same navigation, search, sidebars, and reading experience. If all you need is a blog, the other systems stay out of the way.
 
-### Expressive Tag Plugins
+## A static site with room for live data
 
-A large set of flexible and powerful tag plugins — notes, folding, tabs, timelines, galleries, icons, emoji, highlights, OKR, chat, tables, and more — that can be freely mixed and nested, freeing your content from the limits of plain Markdown. See the [tag plugins documentation](https://xaoxuu.com/wiki/stellar/tag-plugins/).
+Timelines, link status, remote README files, GitHub repositories and contributors, ratings, and polls can load when they are needed. Your site remains static, while frequently changing data does not require a full rebuild.
 
-### Dynamic Data Widgets
+The article remains readable when a remote service is unavailable.
 
-Static blogs with dynamic capabilities — update content without redeploying:
+## Writing, finding, and reading belong together
 
-- **Dynamic timeline**: Post short updates like a social feed, or subscribe to others' timelines.
-- **Automated friend links**: Automatically detect link status, tag links, and subscribe to friends' posts.
-- **Remote Markdown rendering**: Render a project repository's README directly, avoiding duplicate maintenance.
-- **GitHub repository / contributor cards, ratings, votes, latest comments**, and other data widgets — loaded on demand without slowing down the first screen.
-- **Community culture**: Subscribe to the "Explorer" timeline data source to learn from the community.
+Stellar includes content components for notes, folding sections, tabs, galleries, timelines, chat, tables, and more. Built-in local search can take a reader straight to a matching section. On smaller screens, navigation moves into drawers and leaves the page to the article.
 
-### Experience & Performance
+## Choose a starting point
 
-- **Modular design**: Highly reusable widgets with freely configurable left/right sidebars.
-- **Design-token-driven styling**: A unified design language, dark mode, and responsive mobile adaptation.
-- **Lazy-loaded images** reserve space by original aspect ratio, preventing layout jumps.
-- Optional plugins enabled on demand: code highlighting & copy, KaTeX / MathJax, Mermaid diagrams, Fancybox lightbox, Swiper carousel, and more.
-- **Local search**: A built-in index generator, with results grouped by section, jumping to anchors and highlighting keywords.
-- **Complete SEO**: JSON-LD structured data, Open Graph, canonical URLs, and clone-site detection to protect original content.
-- **Multi-author support**: Assign different authors to different posts, each with their own dedicated homepage.
+| Example | A good fit for |
+| --- | --- |
+| Light Blog | Essays, personal notes, and distraction-free reading |
+| Blog | A classic sidebar blog with categories and series |
+| Knowledge | A personal site combining articles and long-lived knowledge |
+| Docs | Documentation for a single project |
 
-Detailed usage for all of the above can be found in the [documentation](https://xaoxuu.com/wiki/stellar/).
+The source for these sites lives in the catalog-driven [hexo-theme-stellar-examples](https://github.com/xaoxuu/hexo-theme-stellar-examples/) repository.
 
-## Examples & Showcase
+## Use the latest source
 
-- Example source: [hexo-theme-stellar-examples](https://github.com/xaoxuu/hexo-theme-stellar-examples/) (`blog` blog scenario, `docs` documentation scenario) — ready to fork and start
-- Showcase: [Blogs using Stellar](https://xaoxuu.com/wiki/stellar/examples/)
-
-[![Star History Chart](https://star-history.dera.page/svg?repos=xaoxuu/hexo-theme-stellar&type=date&legend=top-left)](https://star-history.dera.page/#xaoxuu/hexo-theme-stellar&type=date&legend=top-left)
-
-## Quick Start
-
-### Requirements
-
-```yaml
-Hexo: 6.3.0 ~ latest (verified up to 8.1.2)
-hexo-cli: 4.3.0 ~ latest
-node: >= 22 # LTS recommended
-npm: >= 10
-```
-
-### Install
-
-In the root directory of your blog:
+You need Node.js 22 or newer and Hexo 8 or newer. In the root of an existing Hexo site:
 
 ```bash
-npm install hexo-theme-stellar
+git submodule add -b main https://github.com/xaoxuu/hexo-theme-stellar.git themes/stellar
+npm install --prefix themes/stellar
 ```
 
-### Configure
-
-Edit `_config.yml` and enable the theme:
+Enable the theme in `_config.yml`:
 
 ```yaml
 theme: stellar
 ```
 
-### Start Light
-
-Once configured, you can publish posts immediately. Wiki, Topic, Notebook, and dynamic widgets can be enabled on demand and are documented in detail; alternatively, start from the `blog` scenario in the example repository for a quick setup.
-
-## Documentation
+Then check and build the site:
 
-Full documentation: https://xaoxuu.com/wiki/stellar/ (currently available in Chinese)
+```bash
+npx hexo stellar doctor
+npx hexo generate
+```
 
-> AI documentation: https://deepwiki.com/xaoxuu/hexo-theme-stellar/
+The full v2 documentation is currently maintained in Chinese. The example repository provides an English quick start and complete runnable sites that can be explored without reading the whole reference.
 
-- Changelog: [CHANGELOG.md](https://github.com/xaoxuu/hexo-theme-stellar/blob/main/CHANGELOG.md) · [Releases](https://github.com/xaoxuu/hexo-theme-stellar/releases)
+## Stable npm release
 
-### Common Topics
+```bash
+npm install hexo-theme-stellar
+```
 
-- [Tag Plugins](https://xaoxuu.com/wiki/stellar/tag-plugins/)
-- [Theme Settings](https://xaoxuu.com/wiki/stellar/theme-settings/)
-- [Wiki System](https://xaoxuu.com/wiki/stellar/wiki-settings/)
-- [Topic & Notebook](https://xaoxuu.com/wiki/stellar/topic/)
+This command may still install v1. Run `npm ls hexo-theme-stellar` before using any v2 configuration.
 
-## Feedback
+## Community
 
-- Issues: https://github.com/xaoxuu/hexo-theme-stellar/issues/
-- Discussions: https://github.com/xaoxuu/hexo-theme-stellar/discussions/
-- Contributing: [CONTRIBUTING.md](CONTRIBUTING.md) · [Wiki contributors page](https://xaoxuu.com/wiki/stellar/contributors/)
+- [Issues](https://github.com/xaoxuu/hexo-theme-stellar/issues/) for reproducible problems
+- [Discussions](https://github.com/xaoxuu/hexo-theme-stellar/discussions/) for ideas and usage questions
+- [Contributing](CONTRIBUTING.md) for code and documentation work
 
 ## License
 
-This project is licensed under the [MIT License](LICENSE), Copyright (c) 2021 xaoxuu. Permanently open source and completely free.
+Stellar is free and open source under the [MIT License](LICENSE). Third-party licenses are listed in [THIRD-PARTY-NOTICES.md](legal/THIRD-PARTY-NOTICES.md).