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

package/scripts/generators/wiki.js

@@ -1,38 +1,66 @@
+/* global hexo */
 /**
  * wiki v1 | https://github.com/xaoxuu/hexo-theme-stellar/
  */
 
-hexo.extend.generator.register('wiki', function (locals) {
-  const { site_tree, wiki } = hexo.theme.config
-  const wikiIdList = Object.keys(wiki.tree)
+"use strict";
+
+const { generatorPath, requireLayoutProfiles, toRenderNavigation } = require("../lib/layout-config");
+const { selectListingItems } = require("../lib/collection-pipeline/shared");
+
+hexo.extend.generator.register("wiki", function () {
+  const { wiki } = hexo.stellar.data;
+  const profile = requireLayoutProfiles(hexo.stellar?.config).wikiIndex;
+  if (profile.path == null) return [];
+  const index = wiki.index;
+  if (!index || !Array.isArray(index.items) || !Array.isArray(index.tags)) {
+    throw new Error("Stellar v2: Wiki 索引缺少显式 render.listing 投影");
+  }
+  const wikiIdList = Object.keys(wiki.tree);
   if (wikiIdList.length == 0) {
-    return {}
+    return {};
   }
-  var ret = []
+  var ret = [];
   ret.push({
-    path: site_tree.index_wiki.base_dir + '/index.html',
-    layout: ['index_wiki'],
+    path: generatorPath(profile.path),
+    layout: ["index_wiki"],
     data: {
-      layout: 'index_wiki',
-      menu_id: site_tree.index_wiki.menu_id,
-      filter: false
+      layout: "index_wiki",
+      navigation: toRenderNavigation(profile),
+      wikiIndex: {
+        items: structuredClone(index.items),
+        allItems: structuredClone(index.items),
+        tags: structuredClone(index.tags),
+        filter: false,
+        tagName: "",
+        path: profile.path
+      }
     }
-  })
+  });
   if (wiki.all_tags) {
     for (let id of Object.keys(wiki.all_tags)) {
-      let tag = wiki.all_tags[id]
+      let tag = wiki.all_tags[id];
       ret.push({
         path: tag.path,
-        layout: ['index_wiki'],
+        layout: ["index_wiki"],
         data: {
-          layout: 'index_wiki',
-          menu_id: site_tree.index_wiki.menu_id,
-          filter: true,
-          tagName: tag.name,
-          title: tag.name
+          layout: "index_wiki",
+          navigation: toRenderNavigation(profile),
+          title: tag.name,
+          wikiIndex: {
+            items: selectListingItems(index.items, {
+              tagId: tag.name,
+              tags: index.tags
+            }).map(item => structuredClone(item)),
+            allItems: structuredClone(index.items),
+            tags: structuredClone(index.tags),
+            filter: true,
+            tagName: tag.name,
+            path: profile.path
+          }
         }
-      })
+      });
     }
   }
-  return ret
-})
+  return ret;
+});

package/scripts/helpers/ai_label.js

@@ -1,23 +1,17 @@
 /* global hexo */
 'use strict';
 
-const { buildAiLabel, resolveAiKey } = require('../lib/ai_label');
+const { AI_LABELS, buildAiLabel, resolveAiKey } = require('../lib/ai_label');
 
-// 文章 AI 成分标签：front-matter 用 ai_label: manual / reviewed / polished / generated 标记，
-// 未设置时取配置 article.ai_label.default（为空则不渲染）；
+// 文章 AI 成分标签：Collection / front matter 用 article.ai_label 标记，
 // 文案由多语言系统提供（languages/*.yml 的 meta.ai_label.*，缺失时不渲染），
-// 颜色与可选图标由配置 article.ai_label 提供（默认在主题 _config.yml，站点可覆盖）。
+// 颜色与图标由主题内部固定。
 hexo.extend.helper.register('ai_label', function(value, extraClass, noColor) {
-  const article = hexo.theme.config.article;
-  const labelConfig = article && article.ai_label;
-  const key = resolveAiKey(value, labelConfig);
-  if (key && (!labelConfig || !labelConfig[key])) {
-    console.warn('[ai_label] 未知的 ai_label 值: ' + key);
-  }
+  const key = resolveAiKey(value);
   if (!key) {
     return '';
   }
-  const def = labelConfig && labelConfig[key];
+  const def = AI_LABELS[key];
   const iconHtml = (def && def.icon) ? hexo.utils.icon(def.icon) : '';
   const __ = (this && typeof this.__ === 'function') ? this.__ : hexo.theme.i18n.__(hexo.config.language);
   const i18nKey = 'meta.ai_label.' + key;
@@ -25,5 +19,5 @@ hexo.extend.helper.register('ai_label', function(value, extraClass, noColor) {
   if (!text || text === i18nKey) {
     return '';
   }
-  return buildAiLabel(key, labelConfig, text, extraClass, iconHtml, noColor);
+  return buildAiLabel(key, text, extraClass, iconHtml, noColor);
 });

package/scripts/helpers/brand.js

@@ -0,0 +1,17 @@
+/* global hexo */
+"use strict";
+
+const { replaceConfigTokens, shouldShowMobileBrand } = require("../lib/brand");
+
+hexo.extend.helper.register("brandGithubUsername", function() {
+  const username = hexo.stellar.data?.widgets?.ghuser?.username;
+  return typeof username === "string" ? username.trim() : "";
+});
+
+hexo.extend.helper.register("brandText", function(value) {
+  return replaceConfigTokens(value, hexo.config);
+});
+
+hexo.extend.helper.register("showMobileBrand", function(page, state) {
+  return shouldShowMobileBrand({ layout: page?.layout, ...(state || {}) });
+});

package/scripts/helpers/browser_runtime_manifest.js

@@ -0,0 +1,12 @@
+/* global hexo */
+
+"use strict";
+
+const {
+  buildBrowserRuntimeManifest,
+  serializeBrowserRuntimeManifest
+} = require("../lib/browser-runtime");
+
+hexo.extend.helper.register("browser_runtime_manifest", function(input) {
+  return serializeBrowserRuntimeManifest(buildBrowserRuntimeManifest(input));
+});

package/scripts/helpers/caption.js

@@ -0,0 +1,8 @@
+/* global hexo */
+'use strict';
+
+const { caption } = require('../lib/caption');
+
+hexo.extend.helper.register('caption', function(item) {
+  return caption(item);
+});

package/scripts/helpers/category_color.js

@@ -1,22 +1,22 @@
-'use strict';
+/* global hexo */
+"use strict";
 
-hexo.extend.helper.register('category_color', function(cat){
-  const { config } = hexo.theme
-  const color = config.article.category_color[cat]
+hexo.extend.helper.register("category_color", function(cat) {
+  const color = hexo.stellar.config.article.categoryColors[cat];
   if (color) {
-    var textColor = color
-    if (color.startsWith('#')) {
-      textColor = color
+    var textColor = color;
+    if (color.startsWith("#")) {
+      textColor = color;
     } else {
-      textColor = '#' + color
+      textColor = `#${color}`;
     }
-    var bgColor = textColor
+    var bgColor = textColor;
     if (textColor.length == (1+3)) { // #fff
-      bgColor += '2'
+      bgColor += "2";
     } else if (textColor.length == (1+6)) { // #ffffff
-      bgColor += '20'
+      bgColor += "20";
     }
     return ` style="--text-p2:${textColor};--theme-block:${bgColor}"`;
   }
-  return ''
-})
+  return "";
+});

package/scripts/helpers/collection.js

@@ -0,0 +1,18 @@
+/* global hexo */
+'use strict';
+
+const { getCollectionId } = require('../lib/content-config');
+const { getPageConfig } = require("../lib/page-view-model-registry");
+
+hexo.extend.helper.register("content_config", function(page) {
+  return getPageConfig(page) || {};
+});
+
+hexo.extend.helper.register('collection_id', function(page, type) {
+  const collectionId = getCollectionId(getPageConfig(page), type);
+  if (collectionId != null) return collectionId;
+  if (type === "notebook" && page?.notebookIndex?.mode === "notes") {
+    return page.notebookIndex.collection?.id || null;
+  }
+  return null;
+});

package/scripts/helpers/comments_model.js

@@ -0,0 +1,14 @@
+/* global hexo */
+"use strict";
+
+const { mergeComments, resolveCommentsModel } = require("../lib/comments");
+const { getPageConfig } = require("../lib/page-view-model-registry");
+
+hexo.extend.helper.register("comments_model", function(page, overrides) {
+  const pageComments = getPageConfig(page)?.comments || {};
+  return resolveCommentsModel(
+    hexo.stellar.config,
+    mergeComments(pageComments, overrides),
+    page?.title
+  );
+});

package/scripts/helpers/extension_assets.js

@@ -0,0 +1,8 @@
+/* global hexo */
+"use strict";
+
+const assets = require("../lib/internal-constants").assets;
+
+hexo.extend.helper.register("extension_assets", function() {
+  return assets;
+});

package/scripts/helpers/json_ld.js

@@ -7,11 +7,20 @@
 
 const util = require('hexo-util');
 const { postImages, postDescription } = require('../lib/seo');
+const { getCollectionId } = require('../lib/content-config');
+const { getPageConfig } = require("../lib/page-view-model-registry");
 
 hexo.extend.helper.register('json_ld', function(args) {
+  if (args?.render?.seo) {
+    if (!args.render?.seo?.jsonLd) {
+      throw new Error(`Stellar v2: ${args.collection?.profile || "页面"} ${args.item?.source?.file || "<unknown>"} 缺少 render.seo.jsonLd`);
+    }
+    return `<script type="application/ld+json">${JSON.stringify(args.render.seo.jsonLd)}</script>`;
+  }
   const page = this.page;
+  const pageConfig = getPageConfig(page) || {};
   const config = this.config;
-  const structured_data = this.theme.structured_data;
+  const structuredData = this.stellar_config("structuredData");
   const authorEmail = config.email;
   let authorImage = config.avatar || (authorEmail ? this.gravatar(authorEmail) : null);
   const isPage = page.layout == 'page';
@@ -22,7 +31,7 @@ hexo.extend.helper.register('json_ld', function(args) {
   const author = {
     '@type': 'Person',
     name: config.author,
-    sameAs: structured_data.links || []
+    sameAs: structuredData.sameAs
   };
   // Google does not accept `Person` as item type for the publisher property
   const publisher = Object.assign({}, author, {'@type': 'Organization'});
@@ -39,11 +48,11 @@ hexo.extend.helper.register('json_ld', function(args) {
 
   if (this.is_post()) {
     const images = postImages({
-      cover: page.cover,
-      banner: page.banner,
+      cardCover: pageConfig.cover,
+      bannerImage: pageConfig.banner?.image,
       photos: page.photos,
       content: page.content,
-      defaultCover: this.theme.default && this.theme.default.cover
+      defaultCover: this.stellar_config("fallbacks.cover")
     });
     schema = {
       '@context': 'https://schema.org',
@@ -95,8 +104,8 @@ hexo.extend.helper.register('json_ld', function(args) {
 
       if (page.excerpt || page.description) {
         schema.description = this.strip_html(page.description || page.excerpt);
-      } else if (page.wiki) {
-        const proj = this.theme.wiki.tree[page.wiki];
+      } else if (getCollectionId(pageConfig, "wiki")) {
+        const proj = this.stellar_data("wiki.tree")[getCollectionId(pageConfig, "wiki")];
         if (proj && proj.description) {
           schema.description = proj.description;
         }

package/scripts/helpers/mdrender.js

@@ -2,21 +2,15 @@
 'use strict';
 
 const { mdrenderHtml, PLACEHOLDER_CLASS } = require('../lib/mdrender_html');
-const { wikiReadmeHtml, isWikiReadmePage } = require('../lib/wiki_readme');
 
 // 远程 Markdown 渲染占位标记（底层组件服务端入口，供 EJS 模板复用）
 hexo.extend.helper.register('mdrender_html', function (src, options = {}) {
-  if (options.ghraw == null) {
-    options.ghraw = hexo.theme.config.api_host.ghraw;
+  if (options.rawUrl == null) {
+    options.rawUrl = hexo.stellar.config.services.github.rawUrl;
   }
   return mdrenderHtml(src, options);
 });
 
-// wiki 项目 README 主页占位（首页正文为空且配置 repo 时输出，否则空串）
-hexo.extend.helper.register('wiki_readme_html', function (proj, page) {
-  return wikiReadmeHtml(proj, page, { ghraw: hexo.theme.config.api_host.ghraw });
-});
-
 // 页面是否包含客户端渲染的远程 md（供 TOC 预留空容器）
 hexo.extend.helper.register('has_remote_md', function (page) {
   if (!page) {
@@ -25,5 +19,5 @@ hexo.extend.helper.register('has_remote_md', function (page) {
   if (page.content && page.content.indexOf(PLACEHOLDER_CLASS) >= 0) {
     return true;
   }
-  return isWikiReadmePage(hexo.theme.config.wiki.tree[page.wiki], page);
+  return false;
 });

package/scripts/helpers/menu.js

@@ -0,0 +1,9 @@
+/* global hexo */
+"use strict";
+
+const { resolveMenuActiveByPath } = require("../lib/menu");
+
+hexo.extend.helper.register("menu_active_by_path", function (pagePath, menuItems) {
+  const items = Array.isArray(menuItems) ? menuItems : [];
+  return resolveMenuActiveByPath(items, pagePath, value => this.url_for(value));
+});

package/scripts/helpers/post_view_model.js

@@ -0,0 +1,23 @@
+/* global hexo */
+"use strict";
+
+const { buildPostViewModelFromData, buildTopicViewModelFromData } = require("../filters/lib/page-view-model");
+const {
+  getPostViewModelInput,
+  getRelatedItems,
+  getTopicViewModelBase,
+  getTopicViewModelInput
+} = require("../lib/page-view-model-registry");
+
+hexo.extend.helper.register("post_view_model", function(post) {
+  const input = getPostViewModelInput(post);
+  if (input) return buildPostViewModelFromData(post, input, { relatedItems: getRelatedItems(post) });
+  const topicInput = getTopicViewModelInput(post);
+  if (topicInput) {
+    return buildTopicViewModelFromData(post, topicInput, {
+      base: getTopicViewModelBase(post),
+      relatedItems: getRelatedItems(post)
+    });
+  }
+  throw new Error(`Stellar v2: Post ${post?.source || post?.path || "<unknown>"} 缺少列表 ViewModel 输入`);
+});

package/scripts/helpers/regions.js

@@ -0,0 +1,37 @@
+/* global hexo */
+"use strict";
+
+const { resolveRegions } = require("../lib/regions");
+
+const reported = new Set();
+
+function report(warnings) {
+  for (const warning of warnings) {
+    const message = `Widget ${warning.widget}（layout=${warning.layout}）不支持 Region ${warning.region}；支持：${warning.supported.join(", ") || "none"}；已跳过`;
+    if (reported.has(message)) continue;
+    reported.add(message);
+    hexo.log.warn(`[Stellar Region] ${message}`);
+  }
+}
+
+hexo.extend.helper.register("region_layout", function(profile, collectionRegions, pageRegions) {
+  const config = hexo.stellar.config;
+  const profileConfig = config.profiles[profile] || {};
+  const result = resolveRegions({
+    profile,
+    defaultState: config.leftbar.defaultState,
+    catalog: hexo.stellar.data.widgets || {},
+    layers: [config, profileConfig, collectionRegions, pageRegions]
+  });
+  report(result.warnings);
+  return {
+    topbar: result.topbar,
+    leftbar: result.leftbar,
+    rightbar: result.rightbar
+  };
+});
+
+hexo.extend.helper.register("report_region_warnings", function(warnings) {
+  report(Array.isArray(warnings) ? warnings : []);
+  return "";
+});

package/scripts/helpers/scrollreveal.js

@@ -1,9 +1,9 @@
-'use strict';
+/* global hexo */
+"use strict";
 
-hexo.extend.helper.register('scrollreveal', function(args) {
-  if (hexo.theme.config.plugins.scrollreveal?.enable) {
-    return `${args ? args : ''}slide-up`
-  } else {
-    return ''
+hexo.extend.helper.register("scrollreveal", function(args) {
+  if (hexo.stellar.config.features.reveal.enabled) {
+    return `${args ? args : ""}slide-up`;
   }
-})
+  return "";
+});

package/scripts/helpers/search_domain.js

@@ -0,0 +1,34 @@
+/* global hexo */
+"use strict";
+
+const { resolveSearchScope } = require("../lib/search-domain");
+
+function isBlogAggregate(helper, page) {
+  if (helper.is_home?.() || helper.is_category?.() || helper.is_tag?.() || helper.is_archive?.()) return true;
+  return ["archives", "categories", "tags"].includes(page?.layout);
+}
+
+hexo.extend.helper.register("search_scope", function(page, viewModel) {
+  if (hexo.stellar?.config?.search?.provider !== "local") return null;
+  const notebookCollection = page?.notebookIndex?.mode === "notes"
+    ? page.notebookIndex.collection
+    : null;
+  const scope = resolveSearchScope({
+    blogAggregate: isBlogAggregate(this, page),
+    collection: notebookCollection ? {
+      id: notebookCollection.id,
+      profile: "notebook",
+      name: notebookCollection.name
+    } : null,
+    indexScope: hexo.stellar.config.search.local.scope,
+    viewModel
+  });
+  if (!scope) return null;
+  const blogLabel = this.__("search.scope_blog");
+  const currentLabel = scope.current === "blog" ? blogLabel : scope.label;
+  return {
+    current: scope.current,
+    currentLabel,
+    hasBlog: scope.options.includes("blog")
+  };
+});

package/scripts/helpers/service_provider.js

@@ -0,0 +1,9 @@
+/* global hexo */
+
+"use strict";
+
+const { resolveServiceProvider } = require("../lib/service-provider");
+
+hexo.extend.helper.register("service_provider", function(service) {
+  return resolveServiceProvider(service);
+});

package/scripts/helpers/settings.js

@@ -0,0 +1,16 @@
+/* global hexo */
+"use strict";
+
+const metadata = require("../lib/theme-metadata");
+const { replaceSettingsTokens } = require("../lib/settings");
+
+hexo.extend.helper.register("settings_value", function (value) {
+  return replaceSettingsTokens(value, {
+    "{hexo.name}": "Hexo",
+    "{hexo.version}": hexo.version || "",
+    "{hexo.homepage}": "https://hexo.io/",
+    "{theme.name}": metadata.name,
+    "{theme.version}": metadata.version,
+    "{theme.tree}": `${metadata.repository}/tree/${metadata.version}`
+  });
+});

package/scripts/helpers/share_action.js

@@ -0,0 +1,8 @@
+/* global hexo */
+"use strict";
+
+const { buildShareAction } = require("../lib/share-services");
+
+hexo.extend.helper.register("share_action", function(service, share) {
+  return buildShareAction(service, share);
+});

package/scripts/helpers/stellar_config.js

@@ -0,0 +1,12 @@
+/* global hexo */
+"use strict";
+
+hexo.extend.helper.register("stellar_config", function(path) {
+  const parts = typeof path === "string" && path.length > 0 ? path.split(".") : [];
+  let value = hexo.stellar?.config;
+  for (const part of parts) {
+    if (value == null || !Object.prototype.hasOwnProperty.call(value, part)) return undefined;
+    value = value[part];
+  }
+  return value;
+});

package/scripts/helpers/stellar_data.js

@@ -0,0 +1,8 @@
+/* global hexo */
+"use strict";
+
+const { runtimeDataAt } = require("../lib/runtime-data");
+
+hexo.extend.helper.register("stellar_data", function(path) {
+  return runtimeDataAt(hexo, path);
+});

package/scripts/helpers/stellar_info.js

@@ -1,21 +1,26 @@
-'use strict';
+/* global hexo */
+"use strict";
 
-hexo.extend.helper.register('stellar_info', function(args){
-  const repo = 'https://github.com/xaoxuu/hexo-theme-stellar';
-  const wiki = 'https://xaoxuu.com/wiki/stellar/';
-  const issues = repo + '/issues/';
-  const { version } = require('../../package.json');
-  const cfg = hexo.theme.config.stellar;
+const metadata = require("../lib/theme-metadata");
+
+hexo.extend.helper.register("stellar_info", function(args) {
+  const repo = metadata.repository;
   if (!args) {
     return repo;
-  } else if (args == 'name') {
-    return 'Stellar';
-  } else if (args == 'version') {
-    return version;
-  } else if (args == 'issues') {
-    return repo + '/issues/'
-  } else if (args == 'tree') {
-    return repo + '/tree/' + version;
+  } else if (args === "name") {
+    return metadata.name;
+  } else if (args === "version") {
+    return metadata.version;
+  } else if (args === "homepage") {
+    return metadata.homepage;
+  } else if (args === "issues") {
+    return `${repo}/issues/`;
+  } else if (args === "tree") {
+    return `${repo}/tree/${metadata.version}`;
+  } else if (args === "main_css") {
+    return metadata.assets.mainCss;
+  } else if (args === "main_js") {
+    return metadata.assets.mainJs;
   }
-  return '';
+  return "";
 });

package/scripts/helpers/stellar_inject.js

@@ -0,0 +1,9 @@
+/* global hexo */
+"use strict";
+
+const { mergeTrustedInject } = require("../lib/config-inject");
+
+hexo.extend.helper.register("stellar_inject", function(kind, pageValue) {
+  const siteText = this.stellar_config(`inject.${kind}`);
+  return mergeTrustedInject(siteText, pageValue);
+});

package/scripts/helpers/ui_classes.js

@@ -0,0 +1,12 @@
+/* global hexo */
+"use strict";
+
+const { UI_CAPABILITIES, composeUiClasses } = require("../lib/ui-capabilities");
+
+hexo.extend.helper.register("ui_classes", function(baseClass, capability, modifiers) {
+  return composeUiClasses(baseClass, capability, modifiers);
+});
+
+hexo.extend.helper.register("ui_capabilities", function() {
+  return UI_CAPABILITIES;
+});

package/scripts/lib/ai_label.js

@@ -2,7 +2,14 @@
 
 const { escapeHTML } = require('hexo-util');
 
-// 文章 AI 成分标签（ai_label）：颜色规范化 + 标签 HTML 生成。
+const AI_LABELS = Object.freeze({
+  manual: Object.freeze({ color: '#03a9f4', icon: 'default:shield-user' }),
+  reviewed: Object.freeze({ color: '#4caf50', icon: 'default:shield-check' }),
+  polished: Object.freeze({ color: '#4caf50', icon: 'default:shield-up' }),
+  generated: Object.freeze({ color: '#ff9800', icon: 'default:shield-warning' })
+});
+
+// 文章 AI 成分标签（ai_label）：展示样式由主题内部固定。
 // 文案由调用方传入（多语言系统提供），经 HTML 转义后输出；
 // 文字使用配置色（无背景），缺 # 自动补全；可选 iconHtml 渲染在文案前；
 // noColor 时输出不带内联样式（继承默认文字色，用于 banner 含图片场景）；
@@ -22,19 +29,15 @@ function normalizeColor(color) {
   return text;
 }
 
-// 解析实际生效的标签键：文章设置 ai_label 时优先使用，否则取配置 default（为空则不渲染）
-function resolveAiKey(value, labelConfig) {
-  if (value && typeof value === 'string') {
-    return value;
-  }
-  return (labelConfig && labelConfig.default) || '';
+function resolveAiKey(value) {
+  return typeof value === 'string' && Object.prototype.hasOwnProperty.call(AI_LABELS, value) ? value : '';
 }
 
-function buildAiLabel(value, labelConfig, text, extraClass, iconHtml, noColor) {
-  if (!value || typeof value !== 'string' || !labelConfig || typeof labelConfig !== 'object') {
+function buildAiLabel(value, text, extraClass, iconHtml, noColor) {
+  if (!value || typeof value !== 'string') {
     return '';
   }
-  const def = labelConfig[value];
+  const def = AI_LABELS[value];
   if (!def || typeof def !== 'object' || !text) {
     return '';
   }
@@ -52,4 +55,4 @@ function buildAiLabel(value, labelConfig, text, extraClass, iconHtml, noColor) {
   return `<span class="${className}">${icon}${safeText}</span>`;
 }
 
-module.exports = { buildAiLabel, normalizeColor, resolveAiKey };
+module.exports = { AI_LABELS, buildAiLabel, normalizeColor, resolveAiKey };