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

package/package.json

@@ -1,12 +1,20 @@
 {
   "name": "hexo-theme-stellar",
-  "version": "1.44.0",
-  "description": "Elegant and powerful theme for Hexo.",
+  "version": "2.0.0-rc.2",
+  "description": "An all-in-one Hexo theme for blogs, project documentation, knowledge bases, series, and notebooks.",
   "main": "package.json",
   "scripts": {
     "lint": "eslint .",
-    "test": "node ci/check-require-decls.js && node --test && node ci/check-spec-refs.js",
-    "check": "npm run lint && npm test && python3 docs/knowledge/tools/verify.py && node ci/check-release-docs.js",
+    "test:unit": "node ci/check-require-decls.js && npm run reuse:check && node --test && node ci/check-agent-docs.js",
+    "test": "npm run test:unit && npm run contributions:check",
+    "reuse:check": "node ci/check-reuse-contracts.js",
+    "contributions:check": "node ci/check-contributions.js",
+    "knowledge:check": "node ci/check-knowledge.js",
+    "integration:check": "node ci/check-package-integration.js",
+    "acceptance:prepare": "node ci/check-package-integration.js --prepare",
+    "performance:check": "node ci/check-performance.js",
+    "check": "npm run lint && npm test",
+    "release:check": "npm run check && npm run integration:check && npm run performance:check && npm run knowledge:check",
     "release": "node release.js",
     "release:dry": "node release.js --dry-run"
   },
@@ -16,20 +24,34 @@
   },
   "keywords": [
     "hexo",
+    "hexo-theme",
     "theme",
-    "stellar"
+    "stellar",
+    "blog",
+    "wiki",
+    "documentation",
+    "knowledge-base",
+    "notebook"
   ],
-  "author": "[@xaoxuu](https://github.com/xaoxuu/)",
+  "author": {
+    "name": "xaoxuu",
+    "url": "https://github.com/xaoxuu/"
+  },
   "license": "MIT",
+  "engines": {
+    "node": ">=22"
+  },
   "bugs": {
     "url": "https://github.com/xaoxuu/hexo-theme-stellar/issues/"
   },
   "dependencies": {
     "cheerio": "^1.1.0",
     "glob": "^10.4.0",
+    "hexo-front-matter": "^4.2.1",
     "hexo-renderer-ejs": "^2.0.0",
     "hexo-renderer-stylus": "^3.0.1",
     "hexo-pagination": "^3.0.0",
+    "js-yaml": "^4.1.0",
     "probe-image-size": "^7.2.3"
   },
   "homepage": "https://xaoxuu.com/wiki/stellar/",

package/scripts/commands/stellar.js

@@ -0,0 +1,55 @@
+/* global hexo */
+"use strict";
+
+const { formatDoctorJson, formatDoctorText, runDoctor } = require("../lib/doctor");
+const { buildNewNotePlan, formatNewNotePlan, writeNewNotePlan } = require("../lib/new-note");
+
+function hexoVersion(ctx) {
+  try {
+    const file = require.resolve("hexo/package.json", { paths: [ctx.base_dir] });
+    return require(file).version;
+  } catch (error) {
+    return String(ctx.version || "");
+  }
+}
+
+hexo.extend.console.register("stellar", "Diagnose and author a Stellar v2 site.", {
+  usage: "<doctor|new note> [options]",
+  commands: [
+    { name: "doctor", desc: "Validate the environment and v2 configuration." },
+    { name: "new note", desc: "Create a Note in a known Notebook." }
+  ],
+  options: [
+    { name: "--dry-run", desc: "Print the new note plan without writing files." },
+    { name: "--format <text|json>", desc: "Doctor output format; use Hexo global --silent with JSON." },
+    { name: "--notebook <id>", desc: "Notebook id for stellar new note." },
+    { name: "--title <title>", desc: "Note title and filename for stellar new note." },
+    { name: "--tags <tags>", desc: "Comma-separated Note tags." }
+  ]
+}, async function (args) {
+  const subcommand = args._[0];
+  if (subcommand === "doctor") {
+    const format = args.format || "text";
+    if (!["text", "json"].includes(format)) throw new Error("--format 必须是 text 或 json");
+    const result = runDoctor({ baseDir: this.base_dir, hexoVersion: hexoVersion(this) });
+    console.log(format === "json" ? formatDoctorJson(result) : formatDoctorText(result));
+    if (!result.ok) process.exitCode = 1;
+    return result;
+  }
+  if (subcommand === "new" && args._[1] === "note") {
+    const plan = buildNewNotePlan({
+      baseDir: this.base_dir,
+      sourceDir: this.source_dir,
+      notebook: args.notebook,
+      title: args.title,
+      tags: args.tags
+    });
+    console.log(formatNewNotePlan(plan, { dryRun: args.dryRun }));
+    if (!args.dryRun) {
+      writeNewNotePlan(plan);
+      console.log(`Created ${plan.outputPath}`);
+    }
+    return plan;
+  }
+  throw new Error("Usage: hexo stellar <doctor|new note>");
+});

package/scripts/events/index.js

@@ -2,38 +2,44 @@
 
 'use strict';
 
+require('./lib/config-hot-reload').registerConfigHotReload(hexo);
+
 hexo.on('generateBefore', () => {
   // 页面路径归一化：xxx.html → xxx/，必须先于所有读取 page.path 的逻辑
   require('./lib/path_normalize')(hexo);
+  // v2 声明式配置必须先于所有主题配置消费方完成解析。
+  require('./lib/config-schema')(hexo);
   // Merge config.
   require('./lib/config')(hexo);
   require('./lib/links')(hexo);
   require('./lib/authors')(hexo);
-  require('./lib/doc_tree')(hexo);
-  require('./lib/topic_tree')(hexo);
   require('./lib/utils')(hexo);
-  require('./lib/notebooks')(hexo);
 });
 
-hexo.on('generateAfter', () => {
-  require('./lib/merge_posts')(hexo);
-});
+hexo.extend.filter.register("before_generate", () => {
+  // locals 已失效并从完整 source 库重建；单一 Pipeline 依次完成配置解析、
+  // 内容发现、归属、Collection 状态、两阶段 ViewModel、聚合与路由投影。
+  require("../lib/collection-pipeline").runCollectionPipeline(hexo);
+}, 1);
 
 hexo.on('ready', () => {
   if (process.env.HEXO_READY === '1') return;
   process.env.HEXO_READY = '1';
+  // `hexo stellar doctor --format json --silent` 必须保持 stdout 为单一 JSON 文档；
+  // init/doctor 不需要常规浏览/构建命令的欢迎信息和版本联网检查。
+  if (hexo.env?.cmd === 'stellar') return;
   const isClean = ['cl', 'clean'].some(arg => process.argv.includes(arg));
   if (isClean) {
     return;
   }
-  const { version, homepage, repository } = require('../../package.json');
+  const { version, homepage, repository } = require("../lib/theme-metadata");
   console.log(``);
 
   const line = '------------------------------------------------';
   hexo.log.info(line);
   hexo.log.info(`Welcome to \x1b[33mStellar ${version}\x1b[0m
 \x1b[32mDOCS\x1b[0m  ${homepage}
-\x1b[32mREPO\x1b[0m  ${repository.url}`);
+\x1b[32mREPO\x1b[0m  ${repository}`);
   hexo.log.info(line);
   console.log(``);
   // version check
@@ -54,7 +60,7 @@ hexo.extend.filter.register('before_generate', async () => {
   hasRun = true;
   
   // 读取主题配置开关
-  const enabled = hexo.theme.config.dependencies.lazyload?.fix_ratio === true;
+  const enabled = hexo.stellar.config.features.lazyLoading.autoAspectRatio === true;
 
   const generateImageRatios = require('./lib/get_image_ratios');
   const fixMarkdownImages = require('./lib/fix_image_tags');

package/scripts/events/lib/authors.js

@@ -2,11 +2,14 @@
  * authors.js v2 | https://github.com/xaoxuu/hexo-theme-stellar/
  */
 
-'use strict';
+"use strict";
+
+const { profilePath, requireLayoutProfiles } = require("../../lib/layout-config");
+const { ensureRuntimeData } = require("../../lib/runtime-data");
 
 module.exports = ctx => {
   var authors = ctx.locals.get('data').authors || {}
-  let basePath = ctx.theme.config.site_tree.author.base_dir
+  let basePath = profilePath(requireLayoutProfiles(ctx.stellar?.config).author.path);
   // url
   for (let key of Object.keys(authors)) {
     let author = authors[key]
@@ -14,8 +17,7 @@ module.exports = ctx => {
   }
   // default author
   const keys = Object.keys(authors)
-  if (keys.length > 0) {
-    ctx.theme.config.default_author = authors[keys[0]]
-  }
-  ctx.theme.config.authors = authors
-}
+  const runtimeData = ensureRuntimeData(ctx);
+  runtimeData.defaultAuthor = keys.length > 0 ? authors[keys[0]] : null;
+  runtimeData.authors = authors;
+}

package/scripts/events/lib/config-hot-reload.js

@@ -0,0 +1,65 @@
+/* global hexo */
+"use strict";
+
+const fs = require("node:fs");
+const path = require("node:path");
+
+const { parseStellarConfig } = require("../../lib/config-schema");
+
+const CONFIG_FILENAME = "_config.stellar.yml";
+
+function registerConfigHotReload(ctx, options = {}) {
+  const watchFile = options.watchFile || fs.watchFile;
+  const unwatchFile = options.unwatchFile || fs.unwatchFile;
+  const existsSync = options.existsSync || fs.existsSync;
+  const runtime = options.runtime || process;
+  const debounceMs = Number.isInteger(options.debounceMs) ? options.debounceMs : 100;
+  const interval = Number.isInteger(options.interval) ? options.interval : 250;
+  const configPath = path.join(ctx.base_dir, CONFIG_FILENAME);
+  let watching = false;
+  let timer;
+  let revision = 0;
+
+  async function reload(expectedRevision) {
+    try {
+      const themeConfig = existsSync(configPath)
+        ? await ctx.render.render({ path: configPath }) || {}
+        : {};
+      parseStellarConfig({ source: CONFIG_FILENAME, themeConfig, mode: "recover" });
+      if (expectedRevision !== revision) return;
+      ctx.config.theme_config = themeConfig;
+      if (typeof ctx._watchBox !== "function") {
+        throw new TypeError("Hexo watcher 尚未初始化");
+      }
+      ctx.log.info(`Stellar: ${CONFIG_FILENAME} 已重载，正在重新生成。`);
+      ctx._watchBox();
+    } catch (error) {
+      if (expectedRevision !== revision) return;
+      ctx.log.warn(`Stellar: ${CONFIG_FILENAME} 重载失败，继续使用上一次有效配置。\n${error.message}`);
+    }
+  }
+
+  function schedule() {
+    revision += 1;
+    const expectedRevision = revision;
+    clearTimeout(timer);
+    timer = setTimeout(() => reload(expectedRevision), debounceMs);
+  }
+
+  ctx.on("server", () => {
+    if (watching) return;
+    watching = true;
+    watchFile(configPath, { interval, persistent: false }, schedule);
+  });
+
+  runtime.once("exit", () => {
+    clearTimeout(timer);
+    if (watching) unwatchFile(configPath, schedule);
+    watching = false;
+  });
+}
+
+module.exports = {
+  CONFIG_FILENAME,
+  registerConfigHotReload
+};

package/scripts/events/lib/config-schema.js

@@ -0,0 +1,20 @@
+/* global hexo */
+"use strict";
+
+const { formatConfigWarnings, parseStellarConfig } = require("../../lib/config-schema");
+
+module.exports = ctx => {
+  const hasSiteThemeConfig = ctx.config.theme_config !== undefined;
+  const source = hasSiteThemeConfig ? "_config.stellar.yml" : "themes/stellar/_config.yml";
+  const themeConfig = hasSiteThemeConfig ? ctx.config.theme_config : {};
+  ctx.stellar = ctx.stellar || {};
+  const issues = [];
+  ctx.stellar.config = parseStellarConfig({
+    source,
+    themeConfig,
+    mode: "recover",
+    onIssues: current => issues.push(...current)
+  });
+  const warning = formatConfigWarnings(issues);
+  if (warning) ctx.log.warn(warning);
+};

package/scripts/events/lib/config.js

@@ -1,76 +1,35 @@
-/**
- * 部分代码借鉴自 NexT:
- * https://github.com/next-theme/hexo-theme-next/blob/master/scripts/events/lib/config.js
- * Volantis:
- * https://github.com/volantis-x/hexo-theme-volantis/blob/master/scripts/events/lib/cdn.js
- */
+/* global hexo */
+"use strict";
 
-'use strict';
-
-const path = require('path')
+const path = require("path");
+const { ensureRuntimeData } = require("../../lib/runtime-data");
 
 module.exports = ctx => {
+  // v2 内部 URL 策略：只支持无 index.html 与无 .html 尾缀的规范路径。
+  ctx.config.pretty_urls ||= {};
+  ctx.config.pretty_urls.trailing_index = false;
+  ctx.config.pretty_urls.trailing_html = false;
 
-  const { cache, language_switcher, system } = ctx.theme.config
-  const warning = function(...args) {
-    ctx.log.warn(`Since ${args[0]} is turned on, the ${args[1]} is disabled to avoid potential hazards.`)
-  }
-
-  if (system.override_pretty_urls !== false) {
-    // 强制修改 pretty_urls 配置项
-    ctx.config.pretty_urls.trailing_index = false
-    ctx.config.pretty_urls.trailing_html = false
-  }
+  const data = ctx.locals.get("data") || {};
+  const runtimeData = ensureRuntimeData(ctx);
 
-  if (cache && cache.enable && language_switcher) {
-    warning('language_switcher', 'caching')
-    cache.enable = false
-  }
-
-  if (cache && cache.enable && ctx.config.relative_link) {
-    warning('caching', '`relative_link` option in Hexo `_config.yml`')
-    ctx.config.relative_link = false
-  }
-  // ctx.config.meta_generator = false;
-
-  // merge data
-  const data = ctx.locals.get('data')
   // merge widgets: 可覆盖删除的合并
-  var widgets = ctx.render.renderSync({ path: path.join(ctx.theme_dir, '_data/widgets.yml'), engine: 'yaml' })
+  const widgets = ctx.render.renderSync({ path: path.join(ctx.theme_dir, "_data/widgets.yml"), engine: "yaml" });
   if (data.widgets) {
-    for (let i of Object.keys(data.widgets)) {
-      let widget = data.widgets[i]
-      if (widget == null || widget.length == 0) {
-        // delete
-        delete widgets[i]
+    for (const id of Object.keys(data.widgets)) {
+      const widget = data.widgets[id];
+      if (widget == null || widget.length === 0) {
+        delete widgets[id];
+      } else if (widgets[id] == null) {
+        widgets[id] = widget;
       } else {
-        // create
-        if (widgets[i] == null) {
-          widgets[i] = widget
-        } else {
-          // merge
-          for (let j of Object.keys(widget)) {
-            widgets[i][j] = widget[j]
-          }
-        }
+        Object.assign(widgets[id], widget);
       }
     }
   }
-  ctx.theme.config.widgets = widgets
+  runtimeData.widgets = widgets;
 
   // merge icons: 简单覆盖合并
-  var icons = ctx.render.renderSync({ path: path.join(ctx.theme_dir, '_data/icons.yml'), engine: 'yaml' })
-  if (data.icons) {
-    icons = Object.assign({}, icons, data.icons)
-  }
-  ctx.theme.config.icons = icons
-
-  // default menu
-  if (ctx.theme.config.menubar == undefined) {
-    ctx.theme.config.menubar = {}
-  }
-
-  // chat users
-  ctx.theme.config.chat_users = data.chat_users;
-
-}
+  const themeIcons = ctx.render.renderSync({ path: path.join(ctx.theme_dir, "_data/icons.yml"), engine: "yaml" });
+  runtimeData.icons = Object.assign({}, themeIcons, data.icons || {});
+};

package/scripts/events/lib/content-config.js

@@ -0,0 +1,5 @@
+'use strict';
+
+const { prepareCollectionPipeline } = require("../../lib/collection-pipeline");
+
+module.exports = prepareCollectionPipeline;

package/scripts/events/lib/doc_tree.js

@@ -2,19 +2,109 @@
  * doc_tree.js v2 | https://github.com/xaoxuu/hexo-theme-stellar/
  *
  * Wiki 文档树构建入口：委托 scripts/lib/doc_tree.js 的纯函数，
- * 保持 ctx.theme.config.wiki 输出结构与旧实现一致。
+ * 将 Wiki 运行时树写入 ctx.stellar.data.wiki。
  */
 
-'use strict';
+"use strict";
 
-const { buildWikiTree } = require('../../lib/doc_tree');
+const { getCollectionId } = require("../../lib/content-config");
+const { buildWikiTree } = require("../../lib/doc_tree");
+const { requireLayoutProfiles } = require("../../lib/layout-config");
+const {
+  buildWikiListingRender,
+  buildWikiPageViewModelBase,
+  buildWikiRelated,
+  completeWikiPageViewModel
+} = require("../../lib/models");
+const { ensureRuntimeData } = require("../../lib/runtime-data");
+const {
+  setProfileViewModelBase,
+  setProfileViewModelInput
+} = require("../../lib/page-view-model-registry");
+const { sourcePathForData } = require("../../lib/source-config");
+
+function cloneConfig(value) {
+  return value == null ? value : structuredClone(value);
+}
+
+module.exports = (ctx, pipeline) => {
+  if (!pipeline) throw new TypeError("Stellar v2: Wiki 构建必须由 Collection Pipeline 驱动");
+  const data = ctx.locals.get("data");
+  const records = pipeline.members("wiki");
+  const pages = records.map(record => record.page);
+  const parsedPages = new Map(records.map(record => [record.page, record.config]));
+  const collectionConfigs = new Map(pipeline.collections("wiki").map(([id, config]) => [id, cloneConfig(config)]));
+  const normalizedData = { ...data };
+  for (const [id, value] of collectionConfigs) {
+    normalizedData[`wiki/${id}`] = cloneConfig(value);
+  }
 
-module.exports = ctx => {
   const wiki = buildWikiTree({
-    data: ctx.locals.get('data'),
-    pages: ctx.locals.get('pages'),
-    shelf: ctx.locals.get('data').wiki || [],
-    siteTree: ctx.theme.config.site_tree
+    data: normalizedData,
+    pages,
+    pageConfigs: parsedPages,
+    shelf: data.wiki || [],
+    wikiIndexPath: requireLayoutProfiles(ctx.stellar?.config).wikiIndex.path
   });
-  ctx.theme.config.wiki = wiki;
+  const runtimeData = ensureRuntimeData(ctx);
+  runtimeData.wiki = wiki;
+
+  const entries = [];
+  const homepageEntries = new Map();
+  for (const record of records) {
+    const page = record.page;
+    const config = record.config;
+    if (config == null) continue;
+    const collectionId = getCollectionId(config, "wiki");
+    if (collectionId == null) continue;
+    const input = {
+      ...pipeline.modelInput(record),
+      collectionSource: sourcePathForData(`wiki/${collectionId}`),
+      collectionId,
+      collectionConfig: collectionConfigs.get(collectionId),
+      collectionState: wiki.tree[collectionId],
+      collectionListed: wiki.shelf.includes(collectionId),
+      isBackup: process.env.IS_BACKUP === "true"
+    };
+    const base = buildWikiPageViewModelBase(input);
+    const entry = { page, collectionId, input, base };
+    entries.push(entry);
+    if (!homepageEntries.has(collectionId) || base.item.route.path === base.collection.route.homepage) {
+      homepageEntries.set(collectionId, entry);
+    }
+  }
+
+  const listings = new Map();
+  for (const [collectionId, entry] of homepageEntries) {
+    listings.set(collectionId, buildWikiListingRender(entry.input, entry.base.collection));
+  }
+
+  for (const entry of entries) {
+    const relatedCollections = (wiki.tree[entry.collectionId]?.relatedItems || []).map(group => ({
+      name: group.name,
+      items: (group.items || [])
+        .map(id => homepageEntries.get(id)?.base.collection)
+        .filter(Boolean)
+    }));
+    const related = buildWikiRelated({ relatedCollections });
+    const completeInput = Object.freeze({
+      ...entry.input,
+      related,
+      listing: listings.get(entry.collectionId)
+    });
+    entry.page.viewModel = completeWikiPageViewModel(completeInput, entry.base);
+    setProfileViewModelInput("wiki", entry.page, completeInput);
+    setProfileViewModelBase("wiki", entry.page, entry.base);
+  }
+
+  wiki.index = {
+    items: wiki.shelf
+      .map(id => listings.get(id))
+      .filter(item => item?.listed === true),
+    tags: Object.values(wiki.all_tags || {}).map(tag => ({
+      name: String(tag.name || ""),
+      path: String(tag.path || ""),
+      itemIds: Array.isArray(tag.items) ? tag.items.slice() : []
+    }))
+  };
 };

package/scripts/events/lib/links.js

@@ -2,7 +2,10 @@
  * links.js v1 | https://github.com/xaoxuu/hexo-theme-stellar/
  */
 
-'use strict';
+/* global hexo */
+"use strict";
+
+const { ensureRuntimeData } = require("../../lib/runtime-data");
 
 module.exports = ctx => {
   var allLinks = {}
@@ -13,5 +16,5 @@ module.exports = ctx => {
       allLinks[newKey] = data[key]
     }
   }
-  ctx.theme.config.links = allLinks
-}
+  ensureRuntimeData(ctx).links = allLinks;
+};