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

package/CHANGELOG.md

@@ -1,5 +1,63 @@
 # Changelog
 
+## 2.0.0-rc.2
+
+> 发布日期：2026-09-07
+
+本节记录从公开候选 `2.0.0-rc.1` 到 `2.0.0-rc.2` 最终文件树的净变化。
+
+### 新功能
+
+- Notebook 列表、设置页与错误页的专属配置统一收敛到 `profiles`；404 页新增默认关闭的评论区，可独立覆盖标题、线程、Provider 与参数。
+- 可信页面注入补全 `head_begin/head_end/body_begin/body_end` 四个位置，站点主题配置与页面 Front Matter 使用同一合并顺序和原样输出语义。
+
+### 修复与工程变化
+
+- 将 `hexo-front-matter` 声明为主题直接依赖，避免源码配置与 `stellar new note` 依赖 Hexo 宿主的传递依赖。
+- 重构中英文 README，明确 npm、源码与 Blueprint 三种安装入口，并补充随 npm 包分发的 Stellar 图标、项目描述、关键词和作者元数据。
+
+### 升级注意（配置变更与破坏性改动）
+
+- 从 RC1 升级时，将顶层 `notebook` 移到 `profiles.notebook`，将 `settings.about` 移到 `profiles.settings.about`，将 `error_page.image` 移到 `profiles.error.image`。
+- `profiles.notebook_index` 更名为 `profiles.notebooks`，`profiles.note_index` 更名为 `profiles.notebook`；Note 内容页继续使用 `profiles.note`。
+- `inject` 内容会作为可信 HTML 原样输出；只应配置维护者完全信任的内容，站点级内容在前、页面 Front Matter 在后。
+
+Full Changelog: [2.0.0-rc.1...2.0.0-rc.2](https://github.com/xaoxuu/hexo-theme-stellar/compare/2.0.0-rc.1...2.0.0-rc.2)
+
+## 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 +162,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 +348,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 +394,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

@@ -1,113 +1,106 @@
-# Stellar - 每个人的独立博客
+<div align="center">
+  <img src="assets/icon-v2-x512.webp" width="160" alt="Stellar">
+  <h1>Stellar</h1>
+  <p>每个人的独立博客</p>
+  <p>基于 Hexo 的全能个人知识库，开箱即用，内置海量标签和动态数据组件。可用于个人博客、项目文档、知识库、专栏、笔记等。</p>
+  <p><a href="README.md">简体中文</a> · <a href="README_EN.md">English</a></p>
+  <p>
+    <a href="https://github.com/xaoxuu/hexo-theme-stellar/releases"><img src="https://img.shields.io/github/v/release/xaoxuu/hexo-theme-stellar" alt="release"></a>
+    <a href="https://www.npmjs.com/package/hexo-theme-stellar"><img src="https://img.shields.io/npm/v/hexo-theme-stellar" alt="npm"></a>
+    <a href="https://www.npmjs.com/package/hexo-theme-stellar"><img src="https://img.shields.io/npm/dm/hexo-theme-stellar" alt="npm downloads"></a>
+    <a href="https://github.com/xaoxuu/hexo-theme-stellar"><img src="https://img.shields.io/github/stars/xaoxuu/hexo-theme-stellar" alt="stars"></a>
+    <a href="LICENSE"><img src="https://img.shields.io/github/license/xaoxuu/hexo-theme-stellar" alt="license"></a>
+  </p>
+  <p>
+    <a href="https://xaoxuu.com/wiki/stellar/start/install/">创建第一个博客</a> ·
+    <a href="https://xaoxuu.com/wiki/stellar/support/examples/">站点示例</a> ·
+    <a href="https://xaoxuu.com/wiki/stellar/">完整文档</a>
+  </p>
+</div>
 
-[简体中文](README.md) · [English](README_EN.md)
+## 在纷繁中建立秩序
 
-[![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 知识库、专栏、笔记与动态数据组件都按需启用，随着你的内容需求自然生长。
+从普通文章开始。项目需要稳定的文档目录时，用 Wiki；文章逐渐形成系列时，收进专栏；零散知识需要长期积累时，放进笔记本。它们共享同一套导航、搜索、侧栏与阅读体验，没有启用的内容系统不会增加额外负担。
 
-## 为什么选择 Stellar
+### 灵活的排版与表达方式
 
-### 四大内容系统，一体化整合
+从外观预设、配色和字体，到分栏、选项卡、折叠块与图库，站点的样子和内容的表达方式都可以按需组合。本地搜索可以直接定位到相关章节，响应式布局会在窄屏上把主要空间留给正文。
 
-- **博客系统**：支持技术 / 生活两种文章布局，分类、标签、分页与相关文章一应俱全；只想写博客时，它就是一个开箱即用的轻博客。
-- **Wiki 文档系统**：既可以展示多个项目文档，也可以作为个人知识库，项目树、小节与层级导航开箱即用。
-- **专栏系统**：系列文章集中管理，提供沉浸式的连续阅读体验。
-- **笔记本系统**：三层架构与标签树导航，方便地梳理、归档和检索笔记。
+### 静态页面，也能常看常新
 
-四套系统与动态数据组件一体化整合，无需拼装多个插件。
+手写内容沉淀观点，外部数据保持新鲜。远程内容、社区数据和外部服务可以按需加载，与静态正文保持解耦；经常变化的数据不必每次都随整站重新生成。
 
-### 富表达标签组件
+## 站点示例
 
-内置大量灵活而强大的标签组件——提示框、折叠、标签页、时间线、图库、图标、表情、高亮、OKR、聊天、表格等，互相之间可以自由混搭嵌套，让内容表达不再受 Markdown 语法限制。详见[标签组件文档](https://xaoxuu.com/wiki/stellar/tag-plugins/)。
+[Stellar Examples](https://github.com/xaoxuu/hexo-theme-stellar-examples/) 提供可以直接运行的示例站，适合先体验接近自己目标的站点，再逐步替换内容与配置。更多真实站点见[站点示例](https://xaoxuu.com/wiki/stellar/support/examples/)。
 
-### 动态数据组件
+## 开始使用
 
-静态博客也能拥有动态能力，内容更新无需重新部署：
-
-- **动态时间线**：像发朋友圈一样发布短文，也可以订阅他人的时间线。
-- **自动化友链**：自动检测友链状态、打标签、订阅友链文章。
-- **远程 Markdown 渲染**：例如直接渲染项目仓库的 README，避免重复维护。
-- **GitHub 仓库 / 贡献者卡片、评分、投票、最新评论**等数据组件，按需加载，不拖慢首屏。
-- **社区文化**：可以订阅「探索号」时间线数据源，获取社区用户的宝贵经验分享。
+### 环境要求
 
-### 体验与性能
+- Node.js 22 或更高版本
+- Hexo 8 或更高版本
 
-- **模块化设计**：内置多种高复用性小组件，左右侧边栏自由搭配，布局随心。
-- **设计令牌驱动的样式系统**：统一的设计语言、深色模式与移动端响应式适配。
-- **图片懒加载**按原图比例预留占位，不会出现高度跳变，体验更佳。
-- 可选插件按需启用：代码高亮与复制、KaTeX / MathJax 数学渲染、Mermaid 图表、Fancybox 灯箱、Swiper 轮播等。
-- **本地搜索**：内置索引生成器，结果按章节展示，点击直达锚点并高亮关键词。
-- **SEO 完备**：JSON-LD 结构化数据、Open Graph、canonical 与克隆站检测，保护原创内容。
-- **一站多作者**：可以为不同文章指定不同作者，每位作者都有专属主页。
+### 从蓝图创建
 
-以上功能都可以在[文档](https://xaoxuu.com/wiki/stellar/)中找到详细的使用方法。
+准备好 Git 和 npm 后，一条命令即可启动交互式蓝图安装器：
 
-## 示例与展示
+```bash
+sh -c "$(curl -fsSL https://github.com/xaoxuu/hexo-theme-stellar-examples/raw/main/install.sh)"
+```
 
-- 示例源码：[hexo-theme-stellar-examples](https://github.com/xaoxuu/hexo-theme-stellar-examples/)（`blog` 博客场景、`docs` 文档场景），可直接 fork 起步
-- 展示墙：[使用 Stellar 主题的博客](https://xaoxuu.com/wiki/stellar/examples/)
+安装器会读取示例仓库的 [`blueprints.json`](https://github.com/xaoxuu/hexo-theme-stellar-examples/blob/main/blueprints.json)，展示当前可用的蓝图，并依次确认蓝图、项目目录、依赖安装和创建计划。
 
-[![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)
+### 从 npm 安装
 
-## 快速开始
+在博客根目录安装 npm 当前提供的默认版本，并确认实际安装结果：
 
-### 环境要求
-
-```yaml
-Hexo: 6.3.0 ~ latest（已验证至 8.1.2）
-hexo-cli: 4.3.0 ~ latest
-node: >= 22 # 建议选择 LTS 版本
-npm: >= 10
+```bash
+npm install hexo-theme-stellar
+npm ls hexo-theme-stellar
 ```
 
-### 安装
+### 跟随最新源码
 
-在博客根目录执行：
+将官方仓库的 `main` 分支添加为子模块，并安装主题自身的依赖：
 
 ```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
 ```
 
-### 从轻博客开始
-
-配置完成后即可发布文章。Wiki、专栏、笔记本与动态数据组件按需启用，文档中均有详细说明；也可以直接参考示例仓库的 `blog` 场景快速搭建。
-
-## 使用文档
-
-完整文档请见：https://xaoxuu.com/wiki/stellar/
+然后运行 Doctor 并生成站点：
 
-> AI 文档：https://deepwiki.com/xaoxuu/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)
-
-### 常用文档
+```bash
+npx hexo stellar doctor
+npx hexo generate
+```
 
-- [标签组件](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/install/)和[创建第一个站点](https://xaoxuu.com/wiki/stellar/start/first-site/)。
 
-## 反馈
+## 文档与社区
 
-- 提交 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/)
+- [配置自己的站点](https://xaoxuu.com/wiki/stellar/start/configuration/)
+- [使用内容组件](https://xaoxuu.com/wiki/stellar/reference/tags/)
+- [管理 Wiki、专栏与笔记本](https://xaoxuu.com/wiki/stellar/reference/collection/)
+- [主题配置参考](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/)：反馈可以复现的问题
+- [Discussions](https://github.com/xaoxuu/hexo-theme-stellar/discussions/)：交流使用经验和想法
+- [贡献指南](CONTRIBUTING.md)：参与主题开发与文档维护
 
 ## 开源许可
 
-本项目采用 [MIT License](LICENSE)，Copyright (c) 2021 xaoxuu，永久开源、完全免费。
+Stellar 使用 [MIT License](LICENSE)，Copyright (c) 2021 xaoxuu，永久开源、完全免费。第三方组件及其许可证见[第三方授权声明](legal/THIRD-PARTY-NOTICES.md)。